Skip to content

Commit 95e2e52

Browse files
committed
refactor(sdk)!: invert the paint query to isProvablyEmptyAt
paintsAt handed callers three falsy bottom values with opposite safe readings: false meant "no ink, pass the click through", null meant "not knowable, treat as painted", and undefined from an adapter without the method also meant painted. The idiomatic `if (!preview.paintsAt?.(x, y)) passThrough()` therefore did the dangerous thing for two of the three, and the convention needed defending in the interface docstring, the reference and the guide — plus a dedicated comment and a pinning test on the headless adapter to stop null regressing to false. Inverting the polarity collapses the tri-state to a plain boolean and makes the safe reading structural: true only when the composition was readable and nothing painted there, so ink, an unreadable or still-loading document, and a missing implementation all land on "keep the composition clickable". The prose stays as rationale, but nothing depends on a reader remembering it. PaintsAtOptions becomes PaintQueryOptions, since it now describes the walk that both the adapter method and the exported compositionPaintsAt share rather than one method's arguments. compositionPaintsAt keeps its ink-positive name: it answers the other question, and its docstring points callers who need the fail-safe contract at the adapter. Nothing is released yet, so no consumer is on the old name.
1 parent 2c65241 commit 95e2e52

8 files changed

Lines changed: 101 additions & 86 deletions

File tree

‎docs/sdk/guides/canvas-integration.mdx‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,14 @@ iframeDoc.addEventListener("click", (e) => {
103103

104104
A composition authored as an overlay — a small graphic on an otherwise-empty 1080×1920 frame, layered over a video or an avatar — is still a rectangular DOM box covering every pixel of the frame. Without help it swallows every click, and whatever sits beneath it becomes unreachable.
105105

106-
`preview.paintsAt(x, y)` is the question you need answered: does the composition put ink here, or is the pointer over an empty gap? Toggle `pointer-events` on your wrapper from the answer, and let the browser deliver the event to the right target:
106+
`preview.isProvablyEmptyAt(x, y)` is the question you need answered: is this point provably free of ink, so a click may safely reach what sits beneath? Toggle `pointer-events` on your wrapper from the answer, and let the browser deliver the event to the right target:
107107

108108
```typescript
109109
const wrapper = document.querySelector<HTMLElement>("#composition-wrapper")!;
110110

111111
/**
112112
* Host-page pointer coordinates → the iframe document's own client space, which is what
113-
* `paintsAt` samples against. The iframe renders at the composition's native size and is
113+
* the paint query samples against. The iframe renders at the composition's native size and is
114114
* CSS-scaled to fit, so the on-screen scale has to be divided out — skip this and you
115115
* sample the wrong pixel, and pass-through toggles over the wrong regions.
116116
*/
@@ -126,10 +126,10 @@ function toCompositionPoint(clientX: number, clientY: number) {
126126
function updatePassThrough(clientX: number, clientY: number, altKey: boolean) {
127127
const point = toCompositionPoint(clientX, clientY);
128128
// Alt is the escape hatch for grabbing the composition itself in an empty region.
129-
// `null` means the answer is not knowable yet — treat it as painted, so a
130-
// composition that is still loading stays clickable.
131-
const painted = point ? (preview.paintsAt?.(point.x, point.y) ?? null) : null;
132-
const passThrough = !!point && !altKey && painted === false;
129+
// Every uncertain case — no point, still loading, adapter without the method — is
130+
// falsy here, so the composition stays clickable rather than vanishing.
131+
const passThrough =
132+
!!point && !altKey && !!preview.isProvablyEmptyAt?.(point.x, point.y);
133133
wrapper.style.pointerEvents = passThrough ? "none" : "";
134134
}
135135
```
@@ -149,14 +149,14 @@ Three things are easy to get wrong here:
149149
<Step title="Re-evaluate on every frame, not only on movement">
150150
Animated artwork moves under a stationary cursor. Anything that can change the answer — pointer movement, the Alt key, and the playhead — has to re-run the query from the last known position. Coalesce those triggers into one `requestAnimationFrame` query rather than answering each separately, and short-circuit before the query when the pointer is outside the composition's box: it is a walk over the document, so it does not belong on an ungated per-event path.
151151
</Step>
152-
<Step title="Treat null as painted">
153-
`paintsAt` returns `null` when the document is not loaded or not readable. Erring toward "paints" costs a click that selects the composition; erring the other way makes the composition vanish from under the cursor.
152+
<Step title="Let the polarity do the work">
153+
`isProvablyEmptyAt` is true only when it has established there is no ink. A document that hasn't loaded, an adapter without the method, and a point you couldn't map all come back falsy — which keeps the composition clickable. Don't invert it into a "does it paint" variable; that reintroduces the bug the polarity removes.
154154
</Step>
155155
</Steps>
156156

157157
Pass `{ fullBleedFraction: 0.9 }` if your editor treats a layer covering nearly the whole frame as background rather than artwork — a common choice, since a full-bleed wrapper is usually scaffolding rather than something the user is pointing at.
158158

159-
Do not reimplement this with `elementsFromPoint`. That stack omits `pointer-events: none` nodes, and a decorative overlay carrying `pointer-events: none` still paints — a z-stack query would report no ink over visible artwork and pass the click through anyway. `paintsAt` walks element boxes geometrically for that reason.
159+
Do not reimplement this with `elementsFromPoint`. That stack omits `pointer-events: none` nodes, and a decorative overlay carrying `pointer-events: none` still paints — a z-stack query would report no ink over visible artwork and pass the click through anyway. The paint walk covers element boxes geometrically for that reason.
160160

161161
## Draft loop: 60fps drag without model mutations
162162

‎docs/sdk/reference/adapters.mdx‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ Injectable preview surface adapter. Decouples the SDK from the host's rendering
8787
```typescript
8888
interface PreviewAdapter {
8989
elementAtPoint(x: number, y: number, opts?: { atTime?: number }): ElementAtPointResult | null;
90-
paintsAt?(x: number, y: number, opts?: PaintsAtOptions): boolean | null;
90+
isProvablyEmptyAt?(x: number, y: number, opts?: PaintQueryOptions): boolean;
9191
applyDraft(id: string, props: DraftProps): void;
9292
commitPreview(): void;
9393
cancelPreview(): void;
@@ -101,10 +101,14 @@ interface PreviewAdapter {
101101
Synchronous hit-test at composition coordinates `(x, y)`. Returns the nearest `[data-hf-id]` element under the point, or `null` for a transparent hit (the composition root, an opacity-0 element, or nothing at all). Requires a same-origin iframe — cross-origin access throws a DOMException. The `atTime` option reflects GSAP state at the current playhead; seeking to a speculative time is not supported.
102102
</ParamField>
103103

104-
<ParamField path="paintsAt" type="(x, y, opts?) => boolean | null">
105-
Optional. Does the composition put ink at composition coordinates `(x, y)`? This is the question a host has to answer before a transparent composition layered over other content swallows a click: is the user pointing **at** artwork, or through an empty gap at whatever sits beneath? Geometry alone cannot tell — a composition is mostly full-bleed wrapper `<div>`s that cover every pixel of the frame without painting anything.
104+
<ParamField path="isProvablyEmptyAt" type="(x, y, opts?) => boolean">
105+
Optional. Is `(x, y)` provably free of ink — is it safe to let a click pass through to whatever sits beneath? This is the question a host has to answer before a transparent composition layered over other content swallows a click: is the user pointing **at** artwork, or through an empty gap? Geometry alone cannot tell — a composition is mostly full-bleed wrapper `<div>`s that cover every pixel of the frame without painting anything.
106106

107-
Returns `null` when the answer is not knowable (document not loaded, not readable, or the adapter has no surface). **Treat `null` as painted.** Erring toward "paints" costs a click that selects the composition; erring the other way makes the composition vanish from under the cursor.
107+
**True only when the composition was readable and nothing painted there.** Ink present, a document still loading or unreadable, and an adapter that doesn't implement the method (`preview.isProvablyEmptyAt?.(x, y)` → `undefined` → falsy) all come back falsy. That polarity is deliberate: it puts the burden of proof on passing the click through, so every way of failing keeps the composition clickable rather than making it vanish from under the cursor. The obvious call site is safe by construction:
108+
109+
```typescript
110+
if (preview.isProvablyEmptyAt?.(x, y)) passThrough();
111+
```
108112

109113
Ink is a computed-style test — background colour, background image, visible border, the element's own text, or intrinsic media — with one exception: `<img>` (and the `<img>` inside a `<picture>`) routes through per-pixel alpha, so a transparent PNG paints only where its pixels do. A pixel-verified hit is never discounted by `fullBleedFraction`: box area is not ink area, so a full-frame transparent overlay stays clickable where it is actually opaque.
110114

@@ -174,10 +178,10 @@ interface DraftProps {
174178

175179
`dx` and `dy` are the accumulated drag deltas in composition pixels. `width` and `height` are defined in the interface for forward compatibility but are not yet wired to any op.
176180

177-
### PaintsAtOptions
181+
### PaintQueryOptions
178182

179183
```typescript
180-
interface PaintsAtOptions {
184+
interface PaintQueryOptions {
181185
fullBleedFraction?: number;
182186
addressableOnly?: boolean;
183187
}
@@ -194,7 +198,7 @@ interface PaintsAtOptions {
194198
</ParamField>
195199

196200
<Note>
197-
`ElementAtPointResult` and `DraftProps` are the structural shapes a `PreviewAdapter` produces and consumes. They are **not** re-exported from the `@hyperframes/sdk` barrel — you implement against these shapes rather than importing them. `PaintsAtOptions` **is** re-exported, since callers pass it rather than implement it.
201+
`ElementAtPointResult` and `DraftProps` are the structural shapes a `PreviewAdapter` produces and consumes. They are **not** re-exported from the `@hyperframes/sdk` barrel — you implement against these shapes rather than importing them. `PaintQueryOptions` **is** re-exported, since callers pass it rather than implement it.
198202
</Note>
199203

200204
---
@@ -292,9 +296,9 @@ import { createHeadlessAdapter } from "@hyperframes/sdk";
292296
function createHeadlessAdapter(): PreviewAdapter;
293297
```
294298

295-
Returns a no-op `PreviewAdapter` for headless use: agents, CI pipelines, and server-side rendering. All methods are stubs — `elementAtPoint` and `paintsAt` always return `null`, `applyDraft` and `commitPreview` are no-ops, and the `"selection"` event never fires.
299+
Returns a no-op `PreviewAdapter` for headless use: agents, CI pipelines, and server-side rendering. All methods are stubs — `elementAtPoint` always returns `null` and `isProvablyEmptyAt` always returns `false`, `applyDraft` and `commitPreview` are no-ops, and the `"selection"` event never fires.
296300

297-
`paintsAt` returns `null` rather than `false` on purpose: an adapter with no surface cannot know whether the composition paints, and callers read `null` as painted. Answering `false` would tell a host that a composition it cannot see puts down no ink.
301+
`isProvablyEmptyAt` returns `false` on purpose: an adapter with no surface cannot establish that a point is free of ink, and answering `true` would tell a host it is safe to click through a composition nobody can see.
298302

299303
Pass this adapter when you open a composition for programmatic editing and do not need a live preview surface.
300304

@@ -333,7 +337,7 @@ Returns a `PreviewAdapter` that bridges the SDK to a same-origin `<iframe>` cont
333337

334338
**Image-alpha hit-testing:** For `<img>` elements, the adapter samples the alpha channel of the pixel under the pointer using an `OffscreenCanvas`. Transparent pixels fall through to the element behind. Cross-origin images that taint the canvas are treated as opaque (safe fallback, logged once per src).
335339

336-
**Paint queries:** `paintsAt` answers whether the composition puts ink at a point — see the [`PreviewAdapter` interface](#previewadapter) above and the [transparent-overlay recipe](/sdk/guides/canvas-integration#transparent-compositions-over-other-content). The pieces it is built from are importable directly for hosts whose hit-test policy differs:
340+
**Paint queries:** `isProvablyEmptyAt` answers whether a point is safe to click through — see the [`PreviewAdapter` interface](#previewadapter) above and the [transparent-overlay recipe](/sdk/guides/canvas-integration#transparent-compositions-over-other-content). The pieces it is built from are importable directly for hosts whose hit-test policy differs:
337341

338342
```typescript
339343
import {
@@ -377,7 +381,7 @@ if (hit) {
377381
| `createMemoryAdapter` | `@hyperframes/sdk` |
378382
| `createHeadlessAdapter` | `@hyperframes/sdk` |
379383
| `createIframePreviewAdapter`, `resolveNearestHfElement` | `@hyperframes/sdk` |
380-
| `PaintsAtOptions` | `@hyperframes/sdk` (type only) |
384+
| `PaintQueryOptions` | `@hyperframes/sdk` (type only) |
381385
| `elementPaintsInk`, `compositionPaintsAt`, `imageAlphaOpaqueAt`, `alphaIsOpaque`, `mapPointToImagePixel`, `INTRINSIC_PAINT_TAGS` | `@hyperframes/sdk/adapters/iframe` |
382386
| `createFsAdapter`, `FsAdapterOptions` | `@hyperframes/sdk/adapters/fs` |
383387

‎packages/sdk/src/adapters/headless.test.ts‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,10 @@ import { describe, it, expect } from "vitest";
33
import { createHeadlessAdapter } from "./headless.js";
44

55
describe("createHeadlessAdapter", () => {
6-
it("answers paintsAt with null, not false", () => {
7-
// The two queries read the same value differently: for elementAtPoint null means
8-
// "nothing there", for paintsAt it means "not knowable" and callers treat it as
9-
// painted. Returning false here would tell a host that a composition it cannot
10-
// see puts down no ink, which is the direction that makes content vanish.
11-
expect(createHeadlessAdapter().paintsAt?.(10, 10)).toBeNull();
6+
it("is never provably empty", () => {
7+
// An adapter with no surface cannot establish that a point is free of ink. Answering
8+
// true would tell a host it is safe to click through a composition nobody can see.
9+
expect(createHeadlessAdapter().isProvablyEmptyAt?.(10, 10)).toBe(false);
1210
expect(createHeadlessAdapter().elementAtPoint(10, 10)).toBeNull();
1311
});
1412
});

‎packages/sdk/src/adapters/headless.ts‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
import type { PreviewAdapter, ElementAtPointResult, DraftProps, PaintsAtOptions } from "./types.js";
1+
import type {
2+
PreviewAdapter,
3+
ElementAtPointResult,
4+
DraftProps,
5+
PaintQueryOptions,
6+
} from "./types.js";
27
import type { Composition } from "../types.js";
38

49
/** Null PreviewAdapter for headless use (agents, CI, server-side rendering). */
@@ -8,12 +13,12 @@ class HeadlessPreviewAdapter implements PreviewAdapter {
813
}
914

1015
/**
11-
* null, not false — the same value means different things on the two queries. For
12-
* elementAtPoint null is "nothing there"; for paintsAt it is "not knowable", which
13-
* is the honest answer from an adapter with no surface. Callers read it as painted.
16+
* Never provably empty: an adapter with no surface cannot establish that a point is
17+
* free of ink, and claiming otherwise would tell a host it is safe to click through a
18+
* composition nobody can see.
1419
*/
15-
paintsAt(_x: number, _y: number, _opts?: PaintsAtOptions): boolean | null {
16-
return null;
20+
isProvablyEmptyAt(_x: number, _y: number, _opts?: PaintQueryOptions): boolean {
21+
return false;
1722
}
1823

1924
applyDraft(_id: string, _props: DraftProps): void {}

‎packages/sdk/src/adapters/iframe.test.ts‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
* - canvas taint → opaque fallback
1717
* - non-image regression (WS-A1 opacity behavior unchanged)
1818
*
19-
* Paint-query tests (elementPaintsInk / compositionPaintsAt / paintsAt) live at the
19+
* Paint-query tests (elementPaintsInk / compositionPaintsAt / isProvablyEmptyAt) live at
2020
* bottom of this file and carry their own fake-DOM helpers: the walk is geometric, so
2121
* they need element boxes and computed style rather than a hit-test stack.
2222
*/
@@ -905,7 +905,7 @@ describe("WS-G: z-stack fallthrough via mock elementsFromPoint", () => {
905905
});
906906
});
907907

908-
// ─── Paint query: elementPaintsInk / compositionPaintsAt / paintsAt ──────────
908+
// ─── Paint query: elementPaintsInk / compositionPaintsAt / isProvablyEmptyAt ───
909909

910910
/**
911911
* The paint query decides whether a host layering a transparent composition over
@@ -1438,48 +1438,50 @@ describe("compositionPaintsAt", () => {
14381438
});
14391439
});
14401440

1441-
describe("IframePreviewAdapter.paintsAt", () => {
1441+
describe("IframePreviewAdapter.isProvablyEmptyAt", () => {
14421442
beforeEach(() => {
14431443
_imgCanvasCache.clear();
14441444
});
14451445

14461446
const iframeWith = (doc: unknown, win: unknown) =>
14471447
({ contentDocument: doc, contentWindow: win }) as unknown as HTMLIFrameElement;
14481448

1449-
it("returns null when the document is not reachable", () => {
1450-
// Not knowable, not "no ink" — callers treat null as painted so a composition that
1451-
// has not loaded stays clickable.
1452-
expect(createIframePreviewAdapter(iframeWith(null, paintWin())).paintsAt(1, 1)).toBeNull();
1453-
expect(createIframePreviewAdapter(iframeWith(paintDoc([]), null)).paintsAt(1, 1)).toBeNull();
1449+
it("is never provably empty when the document is not reachable", () => {
1450+
// Unknowable is not empty: the composition stays clickable rather than vanishing.
1451+
expect(createIframePreviewAdapter(iframeWith(null, paintWin())).isProvablyEmptyAt(1, 1)).toBe(
1452+
false,
1453+
);
1454+
expect(createIframePreviewAdapter(iframeWith(paintDoc([]), null)).isProvablyEmptyAt(1, 1)).toBe(
1455+
false,
1456+
);
14541457
});
14551458

1456-
it("returns null when contentDocument access throws (cross-origin)", () => {
1459+
it("is never provably empty when contentDocument access throws (cross-origin)", () => {
14571460
const hostile = {} as HTMLIFrameElement;
14581461
Object.defineProperty(hostile, "contentDocument", {
14591462
get() {
14601463
throw new DOMException("Blocked a frame", "SecurityError");
14611464
},
14621465
});
1463-
expect(createIframePreviewAdapter(hostile).paintsAt(1, 1)).toBeNull();
1466+
expect(createIframePreviewAdapter(hostile).isProvablyEmptyAt(1, 1)).toBe(false);
14641467
});
14651468

1466-
it("answers null while the document is still loading", () => {
1469+
it("is never provably empty while the document is still loading", () => {
14671470
// A same-origin iframe mid-navigation is READABLE and empty, so the !doc guard never
14681471
// fires — walking it would answer a confident "no ink" under an arriving composition.
14691472
const stamped = [pnode({ attrs: { "data-hf-id": "hf-a" } })];
14701473
expect(
1471-
createIframePreviewAdapter(iframeWith(paintDoc(stamped, "loading"), paintWin())).paintsAt(
1472-
1,
1473-
1,
1474-
),
1475-
).toBeNull();
1474+
createIframePreviewAdapter(
1475+
iframeWith(paintDoc(stamped, "loading"), paintWin()),
1476+
).isProvablyEmptyAt(1, 1),
1477+
).toBe(false);
14761478
// Loaded but carrying nothing of the composition — equally unknowable.
14771479
expect(
1478-
createIframePreviewAdapter(iframeWith(paintDoc([]), paintWin())).paintsAt(1, 1),
1479-
).toBeNull();
1480+
createIframePreviewAdapter(iframeWith(paintDoc([]), paintWin())).isProvablyEmptyAt(1, 1),
1481+
).toBe(false);
14801482
});
14811483

1482-
it("delegates to the walk", () => {
1484+
it("inverts the walk: empty where nothing paints, not empty over ink", () => {
14831485
const nodes = [
14841486
pnode({
14851487
attrs: { "data-composition-id": "main" },
@@ -1491,7 +1493,7 @@ describe("IframePreviewAdapter.paintsAt", () => {
14911493
}),
14921494
];
14931495
const adapter = createIframePreviewAdapter(iframeWith(paintDoc(nodes), paintWin()));
1494-
expect(adapter.paintsAt(50, 50)).toBe(true);
1495-
expect(adapter.paintsAt(400, 400)).toBe(false);
1496+
expect(adapter.isProvablyEmptyAt(50, 50)).toBe(false); // over the painted box
1497+
expect(adapter.isProvablyEmptyAt(400, 400)).toBe(true); // empty region
14961498
});
14971499
});

0 commit comments

Comments
 (0)