Skip to content

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.tsx
index 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 time
export 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.tsx
index 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.ts
index 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.ts
index 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`), so
diff --git a/packages/reconciler/src/host.ts b/packages/reconciler/src/host.ts
index 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.ts
index 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.md
index 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.md
index 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 paren
The 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.