mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
sync/hyperframes-codegen-3ff80b22
8
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Hblee
|
9769ba2c7b |
feat(sdk): expose a paint query for transparent-composition hit-testing (#3070)
* feat(sdk): expose a paint query for transparent-composition hit-testing A host layering a transparent composition over other content has to know whether a point carries ink before it decides to swallow a click. The adapter only answered "what element is here", so AI Studio wrote its own answer and could not reach the per-pixel alpha the adapter already samples for <img>. Add PreviewAdapter.paintsAt, plus the pieces it is built from on a new ./adapters/iframe subpath so a host with different hit-test policy can compose its own walk. The walk is geometric rather than elementsFromPoint-based: that stack omits pointer-events:none nodes, and a decorative overlay carrying it still paints, so a z-stack query would report no ink over visible artwork — the direction that makes a composition vanish from under the cursor. fullBleedFraction is an option rather than a constant because "a layer covering the whole frame is background, not artwork" is host policy, not a fact about the composition. * fix(sdk): scope the full-bleed frame to the root under the point compositionFrameArea took the smallest [data-composition-id] in the whole document, so an unrelated sub-composition sized the reference frame for points nowhere near it: a 300x300 badge in a corner made every mid-size painter in a 1920x1080 outer frame read as full-bleed, and the composition went click-through under artwork the user can plainly see. That is the direction the fail-safe exists to avoid, and the docs already described the intended behaviour — the innermost root CONTAINING the point. Also read the alpha channel instead of matching known transparent spellings. Only the `transparent` keyword computes to rgba(0, 0, 0, 0); a faded-out white stays rgba(255, 255, 255, 0), which the set counted as painted. That erred toward absorbing clicks rather than losing them, so it was a false positive rather than a hazard, but it is wrong. Both are pinned by tests that fail when the fix is reverted. * fix(sdk): stop the paint query answering "no ink" over visible artwork Four cases where the walk landed on the wrong side of its own fail-safe. The full-bleed veto tested the winner's border-box area even when the alpha sampler had just read an opaque pixel there, so a full-frame transparent PNG or SVG overlay — the case this feature exists for — reported background over visibly opaque artwork, with no fullBleedFraction that worked. Ink now carries how it was established, and a measured pixel is never vetoed. An image whose pixels could NOT be read stays inferred, so a tainted CDN overlay still yields to the veto rather than absorbing every click. Composition roots were excluded from candidacy outright, so a root carrying a background answered false even at fraction 0, where the docs promise every painting box counts. Roots are candidates now; the veto discounts them without a special case, since a root's box is the frame. An <img> with a clear pixel early-returned past its own background, padding plate and border, which any other element would have counted. A same-origin iframe mid-navigation exposes a readable but empty document, so the !doc guard never fired and a loading composition answered a confident "no ink" — the exact failure the null convention exists to prevent. Also: the sort comparator's epsilon tie was intransitive, leaving the smallest-first guarantee (and the lazy single-sample property that rides on it) engine-dependent; the guide's pass-through recipe called a function that does not exist and hand-waved the coordinate mapping that makes it correct; and the reference now states the under-counts alongside the over-counts, the walk's blindness to runtime-mounted content, and compositionPaintsAt's preconditions. Each fix is pinned by a test that fails when the fix is reverted. * 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. |
||
|
ukimsanov
|
7a91b93dd6 |
docs: correct four developer-reference claims the source contradicts
Miguel's three P2s and Rames' one finding on #2974, all verified in source before changing anything. **`render --json` is not a progress stream.** It prints exactly one `batch-complete` document at the end (`batchRender.ts:408-418`), asserted as a single `console.log` in `batchRender.test.ts`. Described as a final result now. **The iframe drag example never captured the pointer.** `event.target` comes from `iframe.contentDocument`, so `instanceof Element` against this window's constructor is always false for a cross-realm node and `setPointerCapture()` never ran — a pointer leaving the frame then loses `pointerup` and drag state sticks. Structural feature detection instead, with the reason in a comment so it does not get "simplified" back. **The preview adapter example did not compile under strict TypeScript.** `comp` was captured by the callback before definite assignment (TS2454). Optional, with `comp?.dispatch(op)`. **`ORIGIN_APPLY_PATCHES` was imported in a fence that did not use it and used in fences that did not import it.** Imports do not cross fences, so both examples were wrong in opposite directions. Rames found the pair in `open-composition.mdx`; the same shape is in `composition.mdx:630`, which he did not name. All three fences are self-contained now. **And `types.mdx` claimed coverage it does not have.** It promised "every type exported from `@hyperframes/sdk`" while omitting 13 of 42. Eleven are documented on sibling pages, so the sentence now points at those instead of overclaiming. The two with no home anywhere — `CompositionVariableType` and `VariableUsageScan`, both re-exported from the barrel — have entries. The second is worth having written down: `scanIncomplete` means `usedIds` is a lower bound, so an id missing from it is unknown rather than unused. |
||
|
ukimsanov
|
bebaf679d9 | docs: rebuild developer and rendering reference | ||
|
Vance Ingalls
|
4682da14f1 | fix(sdk): attachSync re-syncs the override snapshot on iframe load | ||
|
Vance Ingalls
|
91cc67a007 |
docs(sdk): document attachSync, variable CRUD, and getRootElements/getAllAnimationIds
These SDK reference docs were behind the API surface: PR #2100's attachSync had zero documentation, and PR #2098/#2092's declareVariable, removeVariable, getVariableValue, listVariables, and getRootElements were all missing from composition.mdx despite being real public Composition methods. getAllAnimationIds was also undocumented (pre-existing gap, unrelated to this stack). - composition.mdx: adds getVariableValue, listVariables, declareVariable, removeVariable (Typed edit methods), getRootElements, getAllAnimationIds (Query section) - adapters.mdx: adds attachSync to the PreviewAdapter interface + a ParamField documenting its contract (immediate sync, ongoing patch mirroring, script-patch exclusion, detach semantics) - edit-operations.mdx: adds declareVariable/removeVariable rows + examples to the Variables op table |
||
|
Vance IngallsandClaude Fable 5
|
74faa4b2a4 |
fix(sdk): moveElement survives GSAP animation per-axis via runtime delta translate (#1875)
* fix(sdk): moveElement survives GSAP animation per-axis via runtime delta translate A committed moveElement wrote data-x/data-y but nothing rendered them: hosts shimmed CSS translate, which GSAP folds into the cached transform at first parse and then discards on the animated axis at every seek — dragging an animated element kept only the un-animated axis. Spike-proven on GSAP 3.15: a translate set AFTER GSAP's first parse is never read, folded, or cleared across seeks and composes natively with the animated transform. So: - moveElement captures the pre-edit baseline once (data-hf-edit-base-x/y) - the runtime (new core runtime/positionEdits.ts, applied at timeline bind — after GSAP parse) renders translate = (data-x − base), a pure delta that composes with GSAP tweens, tl.set positions, and CSS alike - applyDraft now drives the drag preview through the same translate channel (the --hf-studio-dx/dy vars had no consumer outside authored Studio bridges), and commitPreview mirrors the committed move onto the live element so it holds without an srcdoc reload Acceptance: packages/engine/scripts/test-runtime-position-edits-browser.ts (real Chrome + GSAP + runtime IIFE, no Studio shell) — X-animated, Y-animated, and static elements hold both edited axes across the full seek range. New subpath export @hyperframes/core/runtime/position-edits. Known limitation (documented): a tween created lazily at runtime that first-parses a marked element after apply folds the edit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(sdk): harden position-edit rendering and the drag draft channel Fixes six issues from adversarial review of the moveElement stack: - Runtime: apply position edits at init as well as at timeline bind, so committed moves render in compositions with no usable GSAP timeline (CSS/WAAPI-animated or fully static) — previously the apply was unreachable outside the boundDuration > 0 bind branch and the edit silently vanished from reloads and renders. - Runtime: guard bind-path re-apply against post-fold double-apply — if the previously written translate was consumed externally (a lazily created tween folding it into GSAP's cached transform), skip instead of re-setting it on top ({force} escape hatch for editor commits). - Adapter: stop writing the --hf-studio-dx/dy custom properties during drags — compositions with the documented var-consuming drag-bridge CSS moved by twice the pointer delta (var transform + new inline translate). The inline translate is now the only draft channel; deltas accumulate in adapter fields. Docs updated to match. - Adapter: switching applyDraft to a new id reverts the abandoned element's draft translate instead of leaving it displaced with no op. - Adapter: cancelPreview restores the raw inline translate (removing it when there was none), so a stylesheet-authored translate is never promoted to a permanent inline style. - Adapter: commitPreview reverts the draft and clears state when dispatch throws, instead of leaving the element shifted by an uncommitted draft. Cleanups: reuse readCurrentTranslate from the core module (was a verbatim copy), drop the dead __hfApplyPositionEdits window hook. Browser acceptance test now also covers the GSAP-free composition path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(core): prime GSAP transform cache before position-edit apply; add fold-loss telemetry Addresses PR #1875 review feedback (Rames, Miga): - Prime the element's GSAP transform parse (gsap.getProperty) before the first translate apply — positioned tl.set()s and tweens that first RENDER after the apply now reuse the cache instead of folding the edit. This closes the lazy-first-parse fold-loss for any page where GSAP is loaded at apply time; the residual limitation is GSAP itself loading after the apply. Proven by the extended browser acceptance test. - Emit position_edit_fold_skipped analytics at the fold-guard skip site so the residual degradation is observable instead of silent. - Browser acceptance test: add a both-axis-animated element (the shape that originated the per-axis loss) and a positioned tl.set() element, asserted across the full seek range. - Simplify the num() null guard (review nit). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
Vance Ingalls
|
bd27ea31ad |
docs(sdk): republish SDK tab pages (Mintlify incremental deploy skipped the new files)
The #1817 deploy added 15 pages but Mintlify only published changed files
incrementally; the 14 unmodified pages 404'd on production while
editing-affordances (touched in
|
||
|
Vance IngallsandClaude Opus 4.8
|
26e9283f6b |
docs(sdk): comprehensive SDK reference + guides (#1817)
* docs(sdk): comprehensive SDK reference + guides Adds a dedicated SDK tab to the Mintlify docs documenting the entire @hyperframes/sdk surface, verified against source: Reference (6 pages): - openComposition + OpenCompositionOptions - Composition (every typed method, query, selection, dispatch/batch/can, events, serialize, override mode, lifecycle) - Edit Operations (all 33 EditOp variants for dispatch/can/batch) - Types (every exported type + constants) - Adapters (PersistAdapter/PreviewAdapter + memory/fs/headless/iframe factories) - Utilities & Constants (history, persist-queue, document utils, origins, errors) Guides (7) + Overview + Quickstart: - querying-and-editing, timing-and-animation, undo-redo-and-patches, persistence, embedded-override-mode, canvas-integration, editing-affordances The existing packages/sdk.mdx stays as the package card and now links the new SDK tab. editing-affordances documents the @hyperframes/sdk/editing subpath shipping in #1814 (flagged with a version Note). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(sdk): address PR review feedback Correctness fixes from PR #1817 review (Miga + Rames): - types.mdx: FindQuery.text is a substring match (String.includes), not exact - persistence.mdx: import PersistAdapter/PersistVersionEntry/PersistErrorEvent from @hyperframes/sdk (no @hyperframes/sdk/adapters/types export exists) - open-composition.mdx: createHeadlessAdapter is a PreviewAdapter, not a persist adapter; PersistAdapter is exported from @hyperframes/sdk (no /adapters subpath) - types.mdx / adapters.mdx: note KeyframeSpec, ElementAtPointResult, DraftProps are structural shapes, not barrel exports (no import to copy) - overview.mdx: drop leaked authoring meta-comment - timing-and-animation.mdx: getElementTimings is keyed by scopedId - embedded-override-mode.mdx: history is already off by default in embedded mode - editing-affordances.mdx: /editing subpath is merged; soften the version note - querying-and-editing.mdx: bare id only resolves top-level; use find() for sub-composition leaves - canvas-integration.mdx + persistence.mdx: explain the comp closure forward-ref and the fs-adapter subpath (tree-shaking) asymmetry Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |