mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-13 15:49:53 +00:00
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.
This commit is contained in:
ukimsanov
@@ -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**). |
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -301,8 +301,11 @@ Returns a `PreviewAdapter` that bridges the SDK to a same-origin `<iframe>` cont
|
||||
import { openComposition, createIframePreviewAdapter } from "@hyperframes/sdk";
|
||||
|
||||
const iframe = document.querySelector<HTMLIFrameElement>("#preview-frame")!;
|
||||
let comp: Awaited<ReturnType<typeof openComposition>>;
|
||||
const preview = createIframePreviewAdapter(iframe, (op) => comp.dispatch(op));
|
||||
// Optional, and dispatched with `?.` — the callback cannot fire before
|
||||
// openComposition() resolves, but strict TypeScript cannot prove that and
|
||||
// rejects a definite `let` captured before assignment (TS2454).
|
||||
let comp: Awaited<ReturnType<typeof openComposition>> | undefined;
|
||||
const preview = createIframePreviewAdapter(iframe, (op) => comp?.dispatch(op));
|
||||
comp = await openComposition(html, { preview });
|
||||
|
||||
// Hit-test at pointer position
|
||||
|
||||
@@ -628,6 +628,8 @@ comp.on("selectionchange", (ids) => {
|
||||
Fires after every committed change with a `PatchEvent` containing RFC 6902 forward and inverse patches, the `origin`, and semantic `opTypes`. Use this to mirror edits into a host history stack, collaboration layer, or audit log.
|
||||
|
||||
```typescript
|
||||
import { ORIGIN_APPLY_PATCHES } from "@hyperframes/sdk";
|
||||
|
||||
comp.on("patch", ({ patches, inversePatches, origin, opTypes }) => {
|
||||
if (origin !== ORIGIN_APPLY_PATCHES) {
|
||||
hostHistory.push({ patches, inversePatches });
|
||||
|
||||
@@ -6,7 +6,7 @@ description: "Open a composition HTML string for editing. Returns a Composition
|
||||
`openComposition` is the single entry point for every SDK session. It parses the composition HTML, stamps stable `hf-id` attributes on any elements that lack them, and returns a [`Composition`](/sdk/reference/composition) ready to receive edits.
|
||||
|
||||
```typescript
|
||||
import { openComposition, ORIGIN_APPLY_PATCHES } from "@hyperframes/sdk";
|
||||
import { openComposition } from "@hyperframes/sdk";
|
||||
|
||||
const comp = await openComposition(html, opts?);
|
||||
```
|
||||
@@ -118,6 +118,8 @@ comp.dispose();
|
||||
### Embedded mode with overrides
|
||||
|
||||
```typescript
|
||||
import { ORIGIN_APPLY_PATCHES } from "@hyperframes/sdk";
|
||||
|
||||
import { openComposition } from "@hyperframes/sdk";
|
||||
|
||||
// Stored override delta for one customer
|
||||
|
||||
@@ -3,7 +3,7 @@ title: "Types"
|
||||
description: "All exported types from @hyperframes/sdk."
|
||||
---
|
||||
|
||||
This page documents every type exported from `@hyperframes/sdk`. Types are verified against `packages/sdk/src/types.ts` and the export barrel at `packages/sdk/src/index.ts`.
|
||||
This page documents the core types exported from `@hyperframes/sdk`, verified against `packages/sdk/src/types.ts` and the export barrel at `packages/sdk/src/index.ts`. Adapter, history, and persistence types live with the APIs that take them — see [Adapters](/sdk/reference/adapters), [Utilities](/sdk/reference/utilities), [Composition](/sdk/reference/composition), and [openComposition](/sdk/reference/open-composition).
|
||||
|
||||
See also: [`Composition`](/sdk/reference/composition) for the main session interface, [`Edit Operations`](/sdk/reference/edit-operations) for the `EditOp` catalog.
|
||||
|
||||
@@ -677,6 +677,33 @@ title.setTiming({ start: 0.5, duration: 3 });
|
||||
|
||||
---
|
||||
|
||||
## CompositionVariableType
|
||||
|
||||
```typescript
|
||||
type CompositionVariableType =
|
||||
| "string" | "number" | "color" | "boolean" | "enum" | "font" | "image";
|
||||
```
|
||||
|
||||
The declared type of a composition variable. Re-exported from
|
||||
`@hyperframes/parsers`; `VARIABLE_TYPES` is the matching runtime list, useful
|
||||
for validators that need the set rather than the union.
|
||||
|
||||
## VariableUsageScan
|
||||
|
||||
```typescript
|
||||
interface VariableUsageScan {
|
||||
usedIds: string[];
|
||||
scanIncomplete: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
The result of statically scanning a composition's script for variable reads.
|
||||
`usedIds` is in first-seen order. `scanIncomplete` is `true` when the script
|
||||
reaches variables in a way the scan cannot resolve — computed keys, rest
|
||||
spreads, the values object escaping into a call — or when it fails to parse;
|
||||
`usedIds` is then a lower bound, not a complete list, so treat an unlisted id as
|
||||
unknown rather than unused.
|
||||
|
||||
## ORIGIN_APPLY_PATCHES / ORIGIN_LOCAL
|
||||
|
||||
```typescript
|
||||
|
||||
Reference in New Issue
Block a user