From 7a91b93dd6222cd5c4ae0017aceb688c394e2488 Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Mon, 3 Aug 2026 21:23:50 -0700 Subject: [PATCH] docs: correct four developer-reference claims the source contradicts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/packages/cli.mdx | 2 +- docs/sdk/guides/canvas-integration.mdx | 7 ++++-- docs/sdk/reference/adapters.mdx | 7 ++++-- docs/sdk/reference/composition.mdx | 2 ++ docs/sdk/reference/open-composition.mdx | 4 +++- docs/sdk/reference/types.mdx | 29 ++++++++++++++++++++++++- 6 files changed, 44 insertions(+), 7 deletions(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 6f4941974..387f34cd2 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -934,7 +934,7 @@ npx hyperframes render --gpu --output gpu.mp4 | `--batch` | path | — | Render one output per variables row from a JSON array or `{ "rows": [...] }` object | | `--batch-concurrency` | positive integer | 1 | Maximum number of batch rows rendered at once | | `--batch-fail-fast` | — | off | Stop launching new batch rows after the first failure | -| `--json` | — | off | Emit JSON progress events for a batch render | +| `--json` | — | off | Print one final JSON result for the batch instead of human-readable progress | | `--page-side-compositing` / `--no-page-side-compositing` | — | on | Use the faster page-side WebGL path for compatible SDR shader transitions, or force layered compositing | | `--browser-timeout` | seconds (0.001–86400) | 60 | Puppeteer page-navigation timeout for the entry HTML. Increase when heavy compositions (many videos, fonts, or asset requests) cannot reach `domcontentloaded` within the default 60 s. The flag takes **seconds**; the env fallback `PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS` takes **milliseconds**. This controls `page.goto` only — very heavy compositions may also need `PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS` and/or `PRODUCER_PLAYER_READY_TIMEOUT_MS` bumped (post-navigation `window.__hf` readiness has its own 45 s budget). | | `--protocol-timeout` | milliseconds (≥ 1000) | 300000 (5 min) | Puppeteer CDP protocol timeout — the per-call budget for `Runtime.callFunctionOn` seek/paint, `Page.captureScreenshot`, and other CDP round-trips. Raise on RAM-pressured hosts (≤ 8 GB), heavy-asset compositions (many videos + images), or when the render fails with `Runtime.callFunctionOn timed out` / `Target closed`. The default is auto-scaled per composition by output pixel area (a 4K comp bumps the ceiling proportionally, capped at 30 min); an explicit override sets the floor and disables scaling below it. Env fallback `PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS` (also **milliseconds**). | diff --git a/docs/sdk/guides/canvas-integration.mdx b/docs/sdk/guides/canvas-integration.mdx index be878c0da..80b17a983 100644 --- a/docs/sdk/guides/canvas-integration.mdx +++ b/docs/sdk/guides/canvas-integration.mdx @@ -123,8 +123,11 @@ iframe.addEventListener("load", () => { targetId = hit.id; startX = event.clientX; startY = event.clientY; - if (event.target instanceof Element && "setPointerCapture" in event.target) { - event.target.setPointerCapture(event.pointerId); + // The target comes from the iframe's realm, so `instanceof Element` against + // this window's constructor is always false and capture would be skipped — + // then a pointer leaving the frame loses `pointerup` and drag state sticks. + if (event.target && "setPointerCapture" in event.target) { + (event.target as Element).setPointerCapture(event.pointerId); } }); diff --git a/docs/sdk/reference/adapters.mdx b/docs/sdk/reference/adapters.mdx index f02e3ec21..a8b6a6760 100644 --- a/docs/sdk/reference/adapters.mdx +++ b/docs/sdk/reference/adapters.mdx @@ -301,8 +301,11 @@ Returns a `PreviewAdapter` that bridges the SDK to a same-origin `