The VS Code of video editing, built for agents.
TypeScript
Enhance useTicker with hold functionality for async work
konstantin-paulus572425a511df
diff --git a/examples/06-three.tsx b/examples/06-three.tsxindex c5c43bc9..36c7bc01 100644--- a/examples/06-three.tsx+++ b/examples/06-three.tsx@@ -12,6 +12,10 @@* useTicker's composition time seeks the helmet's rotation inside a* createEffect, so scrubbing and exports stay frame-accurate, not wall-clock.*+ * An export mounts the module again in a world of its own, so the .glb is+ * fetched from scratch there and races the first frames — which is what+ * `hold` is for: the encoder waits for the model before it samples anything.+ ** The "Battle Damaged Sci-Fi Helmet" is the Khronos DamagedHelmet sample, a* single-file .glb GLTFLoader fetches directly over the network.* RoomEnvironment bakes an in-memory PBR reflection map, so the metal reads@@ -31,7 +35,7 @@ const MODEL_URL =const TURN_SECONDS = 6; // one full revolution per 6s of composition timeexport default function ThreeHelmet() {- const { time } = useTicker();+ const { time, hold } = useTicker();const [loaded, setLoaded] = createSignal(false);let surfaceRef: SceneNode | undefined;@@ -71,7 +75,9 @@ export default function ThreeHelmet() {scene.add(pivot);let disposed = false;- new GLTFLoader()+ // Held, so export and capture wait for the helmet rather than writing the+ // frames it hasn't arrived for; live playback collects nothing.+ const ready = new GLTFLoader().loadAsync(MODEL_URL).then((gltf) => {if (disposed) return;@@ -87,6 +93,8 @@ export default function ThreeHelmet() {}).catch((err) => console.error("Helmet model load failed:", err));+ hold(ready);+// The playhead is the only clock. Reading time() (and loaded()) subscribes// the effect, so it re-renders every tick and once the model streams in.createEffect(() => {diff --git a/examples/07-webgpu.tsx b/examples/07-webgpu.tsxindex d39efdb8..c2872b05 100644--- a/examples/07-webgpu.tsx+++ b/examples/07-webgpu.tsx@@ -8,10 +8,12 @@* detached canvas; onMount a WebGPU context takes it over, and the engine* samples the bitmap into the node's box every frame. Device setup is async,* so the draw effect is created synchronously in the component body and a- * signal wakes it once the pipeline exists. Composition time feeds a uniform- * and the fragment- * shader derives the colors from it (a phase-shifted cosine palette), so the- * playhead is the only clock: scrubbing and exports stay frame-accurate.+ * signal wakes it once the pipeline exists — and `hold` keeps an export from+ * writing the frames that setup hasn't finished for, since a capture or an+ * export mounts the module again and sets up a device of its own.+ * Composition time feeds a uniform and the fragment shader derives the colors+ * from it (a phase-shifted cosine palette), so the playhead is the only+ * clock: scrubbing and exports stay frame-accurate.* Fails with a console error where WebGPU is unavailable.*/@@ -54,12 +56,12 @@ type Gpu = {};export default function WebgpuTriangle() {- const { time } = useTicker();+ const { time, hold } = useTicker();const [gpu, setGpu] = createSignal<Gpu>();let surfaceRef: SceneNode | undefined;- onMount(async () => {+ const setup = async () => {const el = surfaceRef!.element;if (!el) return;@@ -89,7 +91,10 @@ export default function WebgpuTriangle() {});setGpu({ device, context, pipeline, uniforms, bindGroup });- });+ };++ // Held, so the frames wait for the pipeline instead of being sampled empty.+ onMount(() => hold(setup()));createEffect(() => {const g = gpu();diff --git a/packages/jsx/src/hooks.ts b/packages/jsx/src/hooks.tsindex cf3f6323..6933e8ba 100644--- a/packages/jsx/src/hooks.ts+++ b/packages/jsx/src/hooks.ts@@ -19,6 +19,7 @@ export type Ticker = {frame: Accessor<number>;delta: Accessor<number>;playing: Accessor<boolean>;+ hold: (work: Promise<unknown>) => void;};function hostOnly(name: string): never {@@ -34,6 +35,13 @@ function hostOnly(name: string): never {* nothing and `frame()` consumers update at most once per frame. Values move* while the reactive graph is alive: a mount stays live, and export, capture,* and reload each re-execute the module and drive the ticker themselves.+ *+ * `hold` is the other half of that: because a mount of its own is what an+ * export or a capture draws, a project's own async work (a mesh, a texture,+ * a fetch a layout is decided by) races the first frames, which are sampled+ * as soon as the module has rendered. Handing the promise to `hold` keeps+ * those frames waiting for it. Live playback collects nothing, so a held+ * promise costs the editor nothing.*/export function useTicker(): Ticker {return hostOnly("useTicker");diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex 5ff12ce2..0100b760 100644--- a/packages/reconciler/src/document.ts+++ b/packages/reconciler/src/document.ts@@ -3,7 +3,7 @@* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';import { LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';import { createSignal } from 'solid-js';import { SVGElements } from 'solid-js/web';@@ -18,6 +18,14 @@ import type { ProjectDocument, ProjectTick } from './host';/** Props that address or wire an element rather than describe it. */const UNAUTHORED_PROPS: ReadonlySet<string> = new Set([SOURCE_ATTR, LOOP_ATTR, 'children', 'ref']);+/**+ * How long a single `hold` may keep an offline frame waiting. A project's+ * async work is its own, so a promise that never settles is a real+ * possibility, and an export that never finishes is worse than one that+ * misses a picture.+ */+const HOLD_TIMEOUT_MS = 30_000;+/** What an element with no `SourceModifiers` trait is asking for: nothing. */const NO_MODIFIERS = { removeBackground: false, upscale: 1, addAudio: false };@@ -1596,6 +1604,40 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {return this.ticker[0]();}+ /**+ * The barrier behind `useTicker().hold`: a project's own async work, put+ * where the frames in flight wait for it — the same list the decoders push+ * their readiness onto, drained by `warmupAssets` before the first frame+ * and by the encoder before each one after it. Held during the mount, the+ * first frame waits for it; held during a tick, that frame does — hold on+ * every tick, as a decoder that is not ready does, for work that is not+ * done once.+ *+ * The list is null in realtime (nothing collects), so a live mount holds+ * nothing and pays nothing.+ *+ * Settled either way and bounded: the decoders' promises are the engine's+ * own, this one is a project's, and neither a rejection nor a promise that+ * never settles may take an export down with it.+ */+ public hold(work: Promise<unknown>): void {+ const promises = this.world.get(FramePromises)?.list;+ if (!promises) return;++ let timer: ReturnType<typeof setTimeout> | undefined;+ const expired = new Promise<void>((resolve) => {+ timer = setTimeout(() => {+ console.warn(`[hold] gave up after ${HOLD_TIMEOUT_MS}ms — rendering the frame without it`);+ resolve();+ }, HOLD_TIMEOUT_MS);+ });++ promises.push(+ Promise.race([Promise.resolve(work).catch((error) => console.error('[hold]', error)), expired])+ .finally(() => clearTimeout(timer)),+ );+ }+/*** Reads the playhead into the ticker signal. Called by the playback system* once per tick (through the world's `Tickers` set — see `mount`), sodiff --git a/packages/reconciler/src/host.ts b/packages/reconciler/src/host.tsindex f0244a81..87d210fd 100644--- a/packages/reconciler/src/host.ts+++ b/packages/reconciler/src/host.ts@@ -40,5 +40,6 @@ export interface ProjectDocument<N = unknown> {getFirstChild(node: N): N | undefined;getNextSibling(node: N): N | undefined;tick?(): ProjectTick;+ hold?(work: Promise<unknown>): void;applyRef?(node: N, ref: (target: unknown) => void): void;}diff --git a/packages/reconciler/src/renderer.ts b/packages/reconciler/src/renderer.tsindex a332e786..3e6ae620 100644--- a/packages/reconciler/src/renderer.ts+++ b/packages/reconciler/src/renderer.ts@@ -91,6 +91,10 @@ export function use(fn: (target: unknown, arg?: unknown) => void, node: unknown,* @diffusionstudio/jsx (see "./runtime"), so a mounted project's import* resolves to this one. Each accessor only propagates when its value changes,* so a paused scene re-runs nothing.+ *+ * `hold` is the host's frame barrier, or a no-op where the host has none:+ * a project holding work in a document that draws in realtime is not an+ * error, there is simply nothing there that waits.*/export function useTicker(): Ticker {const document = doc();@@ -99,11 +103,13 @@ export function useTicker(): Ticker {}const tick = document.tick.bind(document);+ const hold = document.hold?.bind(document) ?? (() => {});return {time: createMemo(() => tick().time),frame: createMemo(() => tick().frame),delta: createMemo(() => tick().delta),playing: createMemo(() => tick().playing),+ hold,};}diff --git a/reference/jsx/lifecycle.md b/reference/jsx/lifecycle.mdindex 9534299c..20ba91a0 100644--- a/reference/jsx/lifecycle.md+++ b/reference/jsx/lifecycle.md@@ -44,9 +44,33 @@ Call it in a component body. It returns accessors for the playhead of the scene| `frame()` | Playhead in frames (30 fps) || `delta()` | Seconds advanced since the previous engine tick: 0 while paused, negative on a backward scrub or loop || `playing()` | Whether the scene is playing |+| `hold(work)` | Holds the frames an export or a capture is sampling until `work` settles — see [below](#hold) |The values respect play, pause, scrubbing, looping, and playback speed, which wall-clock timers do not. Each accessor only propagates when its value changes, so a paused scene re-runs nothing and `frame()` consumers update at most once per frame. Ticker-driven drawing follows the playhead in the editor **and in exports and captures**; wall-clock timers (`setInterval`, `requestAnimationFrame`) render live but do not appear in the output.`useTicker` is host-bound: it only works inside a mounted project, and throws with a message saying so anywhere else.-> **Status:** the runtime document does not provide a timeline clock yet, so `useTicker()` currently throws inside a mounted project too (`useTicker: this host does not provide a timeline clock`) — and, being called in a component body, takes the whole mount with it. Until it is wired, drive motion with [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md), which run on the same playhead.+## `hold`++An export or a capture does not photograph the live mount — it **mounts the module again**, in a world of its own, and starts sampling as soon as that render returns. So a project's own async work races the first frames: a mesh fetched in `onMount`, a WebGPU device, a `fetch` whose answer decides a layout. The picture on the canvas has been there for minutes; the one in the encoder is a few milliseconds old.++`hold` is how a project says that a frame is not ready yet:++```tsx+const { hold } = useTicker();++onMount(() => {+ const ready = new GLTFLoader().loadAsync(MODEL_URL).then((gltf) => {+ scene.add(gltf.scene);+ setLoaded(true); // wake the draw effect+ });++ hold(ready); // the encoder waits for the model before sampling a frame+});+```++- **Held during the mount**, the promise is awaited before the first frame is written — the same barrier the engine's own decoders and sources wait behind. Nothing later needs to wait for it, since the frame it held did.+- **Held during a tick** (inside an effect, a draw callback), it is awaited before *that* frame is sampled. Work that is not done once — a texture that streams in, an `ImageBitmap` decode, a readback — is held on every tick it is still pending, the way a decoder that is not ready re-registers its own promise each frame.+- **Live playback holds nothing.** Nothing in the editor waits for a frame, so `hold` there is a no-op and costs a mounted project nothing.+- **Holding is not drawing.** The barrier makes the frame wait; something still has to redraw once the work lands — hence the `setLoaded(true)` above, read inside the draw effect. Without it the frame waits and is still sampled blank.+- A held promise is **settled either way and bounded**: a rejection is logged rather than failing the export, and a promise that never settles is given up on after 30 seconds so a render cannot hang on it.diff --git a/reference/jsx/surface-paint.md b/reference/jsx/surface-paint.mdindex 123e7039..936d736d 100644--- a/reference/jsx/surface-paint.md+++ b/reference/jsx/surface-paint.md@@ -97,6 +97,19 @@ Like all paints it stacks with siblings in document order and clips to the parenThe module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`dapi capture`](../capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).+**Async setup has to be held.** Because that re-execution is a fresh mount, a model, a texture, or a device your drawing waits for is fetched again there — and sampling begins as soon as the render returns, so the first frames are written from a canvas nothing has drawn into yet. Hand the promise to [`useTicker().hold`](./lifecycle.md#hold) and those frames wait for it:++```tsx+const { hold } = useTicker();++onMount(() => {+ const ready = loadModel().then((model) => { scene.add(model); setLoaded(true); });+ hold(ready);+});+```++The hold makes the frames wait; the signal it sets is what redraws the canvas once the work lands — both are needed.+## Requirements and limitations- Duplicating or copy-pasting a mounted surface yields a static copy (the drawing does not re-run for the copy); re-mount to get a fresh animated instance.