@xplainer/motion 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,110 @@
+Copyright (c) 2026 BrewMyTech.
+
+This repository is NOT under a single licence. Part of it is open source and
+part of it is proprietary, and the line between them is drawn per directory
+below. Read the whole of this file before copying anything out of here.
+
+
+PART ONE — OPEN SOURCE, APACHE LICENCE 2.0
+
+The eight packages published to npm — seven under the `@xplainer/` scope, plus
+the unscoped `xplainer`, which is an alias for `@xplainer/cli` — are licensed
+under the Apache Licence, Version 2.0:
+
+    apps/cli                 @xplainer/cli
+    packages/alias           xplainer
+    packages/mcp-server      @xplainer/mcp-server
+    packages/motion          @xplainer/motion
+    packages/protocol        @xplainer/protocol
+    packages/render-core     @xplainer/render-core
+    packages/skill           @xplainer/skill
+    packages/tts-client      @xplainer/tts-client
+
+Everything inside those eight directories is Apache-2.0, including the workspace
+template and the scaffold templates under `packages/render-core`.
+The full licence text is in LICENSE-APACHE-2.0 at the root of this repository,
+and a copy of it is committed as `LICENSE` inside each of the eight package
+directories so that it also travels inside every published tarball. The
+attribution notice Apache-2.0 section 4(d) propagates is the NOTICE file, at
+the root and inside each of the eight.
+
+Each of those eight manifests declares `"license": "Apache-2.0"`. That SPDX
+identifier is the authoritative statement for machine consumers.
+
+    Licensed under the Apache Licence, Version 2.0 (the "Licence"); you may
+    not use these files except in compliance with the Licence. You may obtain
+    a copy of the Licence at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the Licence is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    Licence for the specific language governing permissions and limitations
+    under the Licence.
+
+
+PART TWO — PROPRIETARY, ALL RIGHTS RESERVED
+
+Every file that neither Part One nor Part Three names is proprietary. No
+permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell any part of it. This covers, without being limited to:
+
+    apps/desktop             the desktop client                (tier: open-later)
+    packages/config          shared build presets and tooling  (tier: open-later)
+    services/tts-sidecar     the packaged TTS sidecar          (tier: open-later)
+
+    infra/ (but not infra/ffmpeg/, which is Part Three), scripts/, docs/,
+    .github/ (but not .github/workflows/ffmpeg-macos.yml, also Part Three),
+    and every other file at the root
+
+No `hosted` member remains in this repository. `apps/api`, `apps/web` and
+`services/media-service` were relocated to a private repository on 2026-09-06
+(ADR 0023) and this file stopped listing them when they went; that tier stays
+proprietary wherever it lives.
+
+The three `open-later` members listed above are on a path to being opened but
+have NOT been relicensed: opening the published packages did not open them,
+and each still declares `"license": "UNLICENSED"` in its own manifest. Nothing
+in Part One extends to them. Making this repository public did not change that
+either — it made them readable, not usable.
+
+The tier each package belongs to is declared in its own package.json as
+`"xplainer": { "tier": "hosted" | "open-later" }`, and the boundary between
+the tiers is machine-checked. The tier field describes intent; this file
+describes the grant. Where they appear to disagree, this file and the
+`license` field of the package's own manifest govern.
+
+
+PART THREE — THE macOS FFMPEG BUILD SCRIPTS, MIT LICENCE
+
+The scripts that build the macOS FFmpeg which `xplainer setup` downloads, and
+the workflow that runs them, are licensed under the MIT Licence:
+
+    infra/ffmpeg/                          except infra/ffmpeg/keys/
+    .github/workflows/ffmpeg-macos.yml
+
+They are published beside every build as part of its complete corresponding
+source ("the scripts used to control compilation and installation of the
+executable", GPLv2 section 3), so that whoever receives the binary can rebuild
+it. The full licence text is in infra/ffmpeg/LICENSE. Each of those files
+carries `SPDX-License-Identifier: MIT`.
+
+infra/ffmpeg/keys/ holds the OpenPGP public keys of FFmpeg's release signer and
+of zlib's maintainer, unmodified, so that the build can check their signatures.
+They are their owners'; nothing in this file licenses them.
+
+The FFmpeg binary those scripts produce is not covered by any part of this
+file. It is FFmpeg, x264 and zlib under the GNU General Public License version
+2 or later, and every download carries their licences in its LICENSE file.
+
+
+THIRD PARTY COMPONENTS
+
+This software depends on components that others own, and `xplainer setup`
+downloads more of them onto the machine it runs on, each under its own licence.
+The Apache-2.0 grant in Part One covers this software only and grants you
+nothing in respect of any of them. The NOTICE file names them and their terms.
+
+
+Questions: rishav@brewmytech.com

package/NOTICE

@@ -0,0 +1,68 @@
+xplainer.video
+Copyright 2026 BrewMyTech
+
+This product includes software developed by BrewMyTech (https://xplainer.video).
+
+The packages published to npm — those under the `@xplainer/` scope and the
+unscoped `xplainer`, which is an alias for `@xplainer/cli` — are licensed under
+the Apache Licence, Version 2.0. See the LICENSE file distributed with each
+package, or LICENSE-APACHE-2.0 in the source repository.
+
+--------------------------------------------------------------------------------
+
+THIRD PARTY COMPONENTS
+
+This software depends on components owned by others, each under its own
+licence. Those licences govern those components.
+
+`@xplainer/render-core` redistributes the CMU Pronouncing Dictionary
+(`cmudict.dict`), Copyright (C) 1993-2015 Carnegie Mellon University, under the
+2-clause BSD licence reproduced verbatim beside it at
+`packages/render-core/src/g2p/data/cmudict.LICENSE` and shipped in the package
+at `dist/g2p/data/cmudict.LICENSE`. That licence's clause 1 requires the notice
+and the disclaimer to travel with the source, which is why the file is copied
+into the tarball rather than referenced.
+
+`@xplainer/render-core` also redistributes the tokenizer of
+`onnx-community/Kokoro-82M-v1.0-ONNX-timestamped` (`kokoro-tokenizer.json`),
+Apache-2.0, as the authoritative list of the symbols the speech model accepts.
+The model weights themselves are neither bundled nor redistributed here; they
+are fetched from their upstream home, pinned by revision and digest.
+
+`@xplainer/cli` depends on xz-decompress
+(https://github.com/httptoolkit/xz-decompress), MIT, to unpack the `.tar.xz`
+FFmpeg builds `xplainer setup` downloads on Linux. It is installed from the npm
+registry as a declared dependency, not bundled. It contains, compiled to
+WebAssembly, xzwasm (Copyright (c) Steve Sanderson, MIT), XZ Embedded by Lasse
+Collin and Igor Pavlov (public domain) and walloc (Copyright (c) 2020 Igalia,
+S.L., MIT). Its package carries no licence file; those are the terms its
+`package.json` and the header of its own code state.
+
+`xplainer setup` fetches two more components onto the machine it runs on, and
+neither is bundled in or redistributed by any package here. The speech model
+weights and voice pack of `onnx-community/Kokoro-82M-v1.0-ONNX-timestamped` are
+Apache-2.0 and come from that repository, pinned by revision and digest. ONNX
+Runtime (`onnxruntime-node` and `onnxruntime-common`, Copyright (c) Microsoft
+Corporation) is MIT and comes from the npm registry, pinned by version and
+digest; only the host platform's build is kept. `setup` is the one command that
+downloads, it says what it is fetching and what each artefact must hash to, and
+nothing is installed behind your back.
+
+`xplainer setup` also acquires FFmpeg (https://ffmpeg.org), which xplainer
+runs as a separate program and does not link, modify or bundle. On macOS,
+`xplainer setup` downloads an FFmpeg program built by xplainer.video from
+unmodified FFmpeg 9.0.2, x264 b35605ace3ddf7c1a5d67a2eb553f034aef41d55 and zlib
+1.3.2, licensed under the GNU General Public License version 2 or later. Its
+complete corresponding source is listed at
+https://cdn.xplainer.video/toolchain/v1/ffmpeg/9.0.2/source/README.txt. On
+Linux and Windows it downloads the GPL build BtbN publishes as FFmpeg-Builds
+(https://github.com/FFmpeg-Builds/FFmpeg-Builds), licensed under the GNU
+General Public License version 3 or later, from that project's own release.
+The GPL texts travel with each download, not in these packages.
+docs/third-party-components.md in the source repository lists every
+component `setup` acquires. FFmpeg is a trademark of Fabrice Bellard,
+originator of the FFmpeg project.
+
+Apache-2.0 governs this software. It does not govern the components named above
+— the FFmpeg builds and everything else `xplainer setup` acquires among them —
+and nothing here grants you any right to them.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @xplainer/motion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The API explainer scenes are written against, and the page-side harness the xplainer renderer
+drives one frame at a time.** A scene is ordinary React: it reads the frame, computes its picture
+from it, and the renderer captures that picture once per frame.
+
+```bash
+npm i @xplainer/motion react react-dom
+```
+
+```tsx
+import { AbsoluteFill, Easing, interpolate, spring, useCurrentFrame, useVideoConfig } from "@xplainer/motion";
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const opacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });
+  const scale = spring({ frame, fps, config: { damping: 12 } });
+  const y = interpolate(frame, [0, 30], [40, 0], {
+    easing: Easing.out(Easing.cubic),
+    extrapolateRight: "clamp",
+  });
+  return (
+    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
+      <h1 style={{ opacity, transform: `translateY(${y}px) scale(${scale})` }}>{text}</h1>
+    </AbsoluteFill>
+  );
+};
+```
+
+## What is in it
+
+| Kind | Exports |
+|---|---|
+| Frame and video | `useCurrentFrame`, `useVideoConfig` |
+| Motion | `interpolate`, `Easing`, `spring`, `measureSpring`, `random` |
+| Timing and layout | `Sequence`, `Series`, `Loop`, `Freeze`, `AbsoluteFill` |
+| Media | `Img`, `Audio` (the narration marker), `staticFile` |
+| Render holds | `delayRender`, `continueRender`, `cancelRender` |
+| The video itself | `registerRoot`, `Composition`, `registerVideo`, `CalculateMetadataFunction` |
+| Captions | `paginateCaptions`, `Caption`, `TikTokPage` |
+
+Every motion function is a pure function of the frame, so a frame rendered out of order, or a
+single still, is the same picture the full render shows. `spring` is the closed-form solution of a
+damped harmonic oscillator; `Easing` holds the textbook closed forms; `random(seed)` is
+deterministic per seed.
+
+`<Video>` and `<OffthreadVideo>` throw `NOT_SUPPORTED_IN_V1` when rendered: video assets are not
+supported by this renderer yet, so use `<Img>` stills. A second `<Audio>` beside the narration fails
+the same way, because the narration is the only audio track the video gets. `staticFile()` takes a
+name inside the video's public directory and refuses one that starts with `/` or climbs out of it
+with `..`.
+
+## The harness
+
+`@xplainer/motion/harness` is a separate entry point with side effects, imported only by the
+renderer's generated bundle, before the scene code. It runs the page on film time — `Date`,
+`performance.now`, `setTimeout`, `setInterval` and `requestAnimationFrame` all advance only when the
+renderer asks for the next frame — and before each frame is captured it waits for render holds,
+images and fonts, and for the page to stop changing, so an image a scene's effects mount a few
+React updates after the frame is still in that frame; a frame that never stops changing is released
+with a warning in the job log. `Math.random` in the page is seeded, so it repeats from run to run.
+A scene never imports it.
+
+The exported surface of the main entry point is recorded in `api/motion.api.md` in the repository.
+
+## Docs
+
+- [Architecture][architecture] — the members and the dependency direction
+- [Decision records][adr]
+- [Roadmap][roadmap] — what is built and what is not
+
+## Licence
+
+Apache-2.0. See `LICENSE` and `NOTICE`, both shipped inside this package.
+
+[architecture]: https://github.com/BrewMyTech/xplainer.video/blob/main/docs/ARCHITECTURE.md
+[adr]: https://github.com/BrewMyTech/xplainer.video/blob/main/docs/adr/README.md
+[roadmap]: https://github.com/BrewMyTech/xplainer.video/blob/main/docs/ROADMAP.md

package/dist/animations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Web Animations on film time.
+ *
+ * CSS animations, CSS transitions and `element.animate()` all run on the document timeline, which
+ * is wall time and is not something the harness can replace. So instead of replacing the clock,
+ * the harness pauses every animation on the document timeline after each frame commits and sets
+ * its `currentTime` itself: film time now, minus the film time at which the harness first saw that
+ * animation. An animation that starts when its element mounts at frame 40 is therefore at 0 ms on
+ * frame 40 and at 1000 ms on frame 70 at 30 fps, however long the capture of the frames between
+ * took.
+ *
+ * **The start is when the harness first saw the animation, so the order of `setFrame` calls
+ * matters.** A video rendered front to back sees every animation start at the frame its element
+ * mounted. A page asked for frame 70 alone, of an element that mounts at frame 40, has no earlier
+ * frame to have seen it on, and shows it at 0 ms — which is why the renderer steps a still's page
+ * through every frame before the one it captures, at the cost of setting each of them. A scene
+ * whose animation is `interpolate()` on `useCurrentFrame()` is a pure function of the frame and
+ * needs none of this.
+ *
+ * Scroll- and view-driven animations (`animation-timeline: scroll()` / `view()`) are not on the
+ * document timeline and are not touched: their progress is the scroll position, not time.
+ */
+/** The part of `Animation` the seeker touches, so Node tests can hand it plain objects. */
+export type SeekableAnimation = {
+    pause(): void;
+    currentTime: CSSNumberish | null;
+    /** Compared by identity with the document's own timeline; nothing else is read from it. */
+    readonly timeline: unknown;
+};
+export declare class AnimationSeeker {
+    #private;
+    /**
+     * Pause and seek each animation on `timeline` — the document's — to film time; returns how many
+     * were seeked. Any other animation is left alone: one driven by a scroll or view timeline
+     * (`animation-timeline: scroll()`) measures its time in percentages of a scroll range, not in
+     * milliseconds, and setting a number of milliseconds on it throws. Its progress follows the
+     * scroll position, which a frame's own render already decides.
+     */
+    seek(animations: Iterable<SeekableAnimation>, filmMs: number, timeline: unknown): number;
+}

package/dist/animations.js

@@ -0,0 +1 @@
+export class AnimationSeeker{#firstSeen=new WeakMap;seek(animations,filmMs,timeline){let count=0;for(const animation of animations){if(animation.timeline!==timeline)continue;let start=this.#firstSeen.get(animation);start===void 0&&(start=filmMs,this.#firstSeen.set(animation,start)),animation.pause(),animation.currentTime=filmMs-start,count+=1}return count}}

package/dist/captions.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Caption paging: word-level `captions.json` into the pages the caption track shows one at a time.
+ *
+ * **The rule, which `packages/render-core` already writes `captions.json` against.** Its
+ * `buildCaptions()` gives every word but the first of the whole track a leading space and never
+ * gives one to folded punctuation (`packages/render-core/src/narrate/captions.ts`). The pager is
+ * the other half of that agreement:
+ *
+ * 1. Captions are taken in order. The first one opens the first page.
+ * 2. A caption **opens a new page only if its `text` begins with whitespace** and at least
+ *    `combineWithinMs` have elapsed from the current page's start to the caption's `startMs`. The
+ *    window is half-open: a caption exactly `combineWithinMs` after the page start opens the next
+ *    page. A caption with no leading space never opens a page however late it is — it is the tail
+ *    of the word before it, and splitting there would strand it.
+ * 3. The caption that opens a page has its leading whitespace trimmed, in the page `text` and in
+ *    its token, so no page begins with a space. Every other caption is appended verbatim: page
+ *    `text` is the plain concatenation of its tokens' `text`.
+ * 4. A page lasts until the next page starts; the last page lasts until the latest `endMs` among
+ *    its own tokens. So consecutive pages tile the time between them with no gap for the caption
+ *    band to flicker through, and the track ends when the speech does.
+ *
+ * Grouping is by elapsed time only; nothing here knows where a sentence or a narration segment
+ * ends. The scaffold's `Captions.tsx` gets sentence-aware pages by calling this once per sentence,
+ * which is why this function stays this small.
+ *
+ * Pure: no clock, no frame, no order dependence, so a frame rendered out of order or a still taken
+ * alone pages exactly as the full render does.
+ */
+/** One word of `captions.json`, in the shape `packages/protocol/schemas/captions.json` defines. */
+export type Caption = {
+    text: string;
+    startMs: number;
+    endMs: number;
+    timestampMs: number | null;
+    confidence: number | null;
+};
+/** One caption inside a page, with its own span so the spoken word can be highlighted. */
+export type TikTokToken = {
+    text: string;
+    fromMs: number;
+    toMs: number;
+};
+/** One page of caption text and the tokens it was built from. */
+export type TikTokPage = {
+    text: string;
+    startMs: number;
+    durationMs: number;
+    tokens: TikTokToken[];
+};
+/** The fields of a caption the pager reads. Every `Caption` is one. */
+export type PageableCaption = Pick<Caption, "text" | "startMs" | "endMs">;
+export type PaginateCaptionsOptions = {
+    /** A caption starting this long after its page's start (or later) may open the next page. */
+    combineWithinMs: number;
+};
+export declare function paginateCaptions(captions: readonly PageableCaption[], options: PaginateCaptionsOptions): TikTokPage[];
+export type CreateTikTokStyleCaptionsInput = {
+    captions: readonly PageableCaption[];
+    combineTokensWithinMilliseconds: number;
+};
+/**
+ * `paginateCaptions` under its older name and argument shape.
+ *
+ * It exists so scenes written before this package — which imported the pager from a
+ * captions-specific module under this name — keep compiling through the renderer's import alias
+ * for one release. New code should call `paginateCaptions`.
+ */
+export declare function createTikTokStyleCaptions(input: CreateTikTokStyleCaptionsInput): {
+    pages: TikTokPage[];
+};

package/dist/captions.js

@@ -0,0 +1 @@
+const LEADING_WHITESPACE=/^\s/u;export function paginateCaptions(captions,options){const{combineWithinMs}=options;if(!(Number.isFinite(combineWithinMs)&&combineWithinMs>=0))throw new RangeError(`paginateCaptions: combineWithinMs must be zero or a positive number, got ${String(combineWithinMs)}.`);const pages=[];let page;for(const caption of captions){if(page===void 0||LEADING_WHITESPACE.test(caption.text)&&caption.startMs-page.startMs>=combineWithinMs||page===void 0){const text=caption.text.trimStart();page={text,startMs:caption.startMs,durationMs:0,tokens:[{text,fromMs:caption.startMs,toMs:caption.endMs}]},pages.push(page);continue}page.text+=caption.text,page.tokens.push({text:caption.text,fromMs:caption.startMs,toMs:caption.endMs})}for(const[index,current]of pages.entries()){const next=pages[index+1],end=next===void 0?Math.max(...current.tokens.map(token=>token.toMs)):next.startMs;current.durationMs=Math.max(0,end-current.startMs)}return pages}export function createTikTokStyleCaptions(input){return{pages:paginateCaptions(input.captions,{combineWithinMs:input.combineTokensWithinMilliseconds})}}

package/dist/clock.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Film time: the clock a captured page runs on instead of the wall clock.
+ *
+ * A browser animates against wall time — `Date.now()`, `performance.now()`, `setTimeout`,
+ * `requestAnimationFrame` — and a capture that takes 40 ms per frame would otherwise see a scene
+ * whose timers ran 40 ms per frame instead of 33. The harness replaces all four with **film
+ * time**: `frame / fps · 1000` milliseconds, which only moves when the renderer asks for a frame.
+ * These are the pieces of that replacement that need no `window`, so they are tested in Node; the
+ * harness installs them.
+ *
+ * Three rules, each of which the spike found by being wrong first:
+ *
+ * - **Due timers fire in due order, ties in creation order** — the same order a browser would have
+ *   fired them in, given time.
+ * - **A timer created while the queue is draining waits for the next drain**, even with delay 0.
+ *   Otherwise `setTimeout(tick, 0)` inside `tick` is an infinite loop inside one frame.
+ * - **An interval fires as many times as fit**, so a 10 ms interval fires three times across one
+ *   33 ms frame rather than once.
+ */
+/** 2020-01-01T00:00:00Z: what `Date.now()` reads at frame 0, so dates are stable across renders. */
+export declare const FILM_EPOCH_MS: number;
+/** Film milliseconds at a frame. Multiplies first, so whole frames at integer fps stay exact. */
+export declare function frameToFilmMs(frame: number, fps: number): number;
+/**
+ * A `Date` that reads film time when asked for "now" and is the native `Date` otherwise.
+ *
+ * A `Proxy` rather than a subclass because `Date()` called without `new` must keep working (it
+ * returns a string), and `instanceof Date` must stay true for dates made either way; both fall out
+ * of forwarding everything but the three "now" paths to the native constructor.
+ */
+export declare function createFrozenDate(NativeDate: DateConstructor, filmMs: () => number): DateConstructor;
+/** `setTimeout` / `setInterval` against a clock somebody else advances. */
+export declare class TimerQueue {
+    #private;
+    /**
+     * Schedule `callback` `delayMs` after `nowMs`. The delay is whatever the page passed, converted
+     * with `Number()` as a browser converts it — `setTimeout(fn, "100")` waits 100 ms — and one that
+     * converts to a non-finite or negative number is 0.
+     */
+    add(callback: () => void, delayMs: unknown, repeat: boolean, nowMs: number): number;
+    /**
+     * Reschedule every pending timer with an id of at least `fromId` as if it had been added at
+     * `nowMs`, keeping what has happened to it since: a one-shot timer becomes due its own delay
+     * after `nowMs`, and an interval that has fired `n` times becomes due where the same interval
+     * added at `nowMs` would be after `n` firings — the same phase, on the new origin. The due time is
+     * recomputed rather than shifted, so it is the same number to the last bit whatever it was
+     * scheduled from; a shift could land a timer due exactly on a frame one ulp past it. Returns how
+     * many it moved.
+     *
+     * This is how the harness takes the wall clock back out of a render-hold wait: a timer the wait
+     * created was scheduled from film time plus however long the wait had run, and once the hold is
+     * released it is rebased onto the frame's film instant, so when it fires no longer depends on how
+     * long the page took to release the hold.
+     */
+    rebase(fromId: number, nowMs: number): number;
+    /** Cancel a timer or an interval. Anything that is not a live id is ignored, as in a browser. */
+    clear(id: unknown): void;
+    /**
+     * The id the next timer will get. Every timer created from now on has an id at least this
+     * large, which is how a caller marks "timers created after this point" for `runDue`.
+     */
+    get nextId(): number;
+    /**
+     * The earliest due time among timers with an id of at least `fromId` (all of them by default),
+     * or `undefined` when there is none.
+     */
+    nextDue(fromId?: number): number | undefined;
+    get size(): number;
+    /**
+     * Fire every timer due at or before `targetMs`, earliest first, ties in creation order. Timers
+     * created while this runs are left for the next call, and timers with an id below `fromId` are
+     * left alone entirely. Returns how many fired. `invoke` is how a callback is called, so the
+     * caller decides what a throwing one means.
+     */
+    runDue(targetMs: number, invoke: (callback: () => void) => void, fromId?: number): number;
+}
+/** `requestAnimationFrame` as a queue the harness drains once per captured frame. */
+export declare class FrameCallbackQueue {
+    #private;
+    request(callback: (timestamp: number) => void): number;
+    cancel(id: unknown): void;
+    get size(): number;
+    /** The id the next request will get; the same "requested after this point" mark as `TimerQueue`'s. */
+    get nextId(): number;
+    /** How many queued callbacks have an id of at least `fromId`. */
+    pending(fromId?: number): number;
+    /**
+     * Run every queued callback with an id of at least `fromId` (all of them by default) with
+     * `timestamp`, in request order, and leave the rest queued. A callback requested while this runs
+     * belongs to the next drain, and one cancelled by an earlier callback in the same drain does not
+     * run — both exactly as a browser runs a frame's callbacks.
+     */
+    drain(timestamp: number, invoke: (callback: () => void) => void, fromId?: number): number;
+}

package/dist/clock.js

@@ -0,0 +1 @@
+export const FILM_EPOCH_MS=Date.UTC(2020,0,1);export function frameToFilmMs(frame,fps){return frame*1e3/fps}export function createFrozenDate(NativeDate,filmMs){const now=()=>FILM_EPOCH_MS+Math.floor(filmMs());return new Proxy(NativeDate,{construct(target,args,newTarget){return Reflect.construct(target,args.length===0?[now()]:args,newTarget)},apply(){return new NativeDate(now()).toString()},get(target,property,receiver){return property==="now"?now:Reflect.get(target,property,receiver)}})}export class TimerQueue{#timers=new Map;#nextId=1;add(callback,delayMs,repeat,nowMs){const requested=Number(delayMs),delay=Number.isFinite(requested)&&requested>0?requested:0,id=this.#nextId;return this.#nextId+=1,this.#timers.set(id,{id,due:nowMs+delay,delay,ticks:0,callback,interval:repeat?Math.max(1,delay):null}),id}rebase(fromId,nowMs){let moved=0;for(const timer of this.#timers.values()){if(timer.id<fromId)continue;let due=nowMs+timer.delay;if(timer.interval!==null)for(let tick=0;tick<timer.ticks;tick+=1)due+=timer.interval;timer.due=due,moved+=1}return moved}clear(id){typeof id=="number"&&this.#timers.delete(id)}get nextId(){return this.#nextId}nextDue(fromId=1){let earliest;for(const timer of this.#timers.values())timer.id<fromId||(earliest===void 0||timer.due<earliest)&&(earliest=timer.due);return earliest}get size(){return this.#timers.size}runDue(targetMs,invoke,fromId=1){const watermark=this.#nextId;let fired=0;for(;;){let next;for(const timer of this.#timers.values())timer.id<fromId||timer.id>=watermark||timer.due>targetMs||(next===void 0||timer.due<next.due||timer.due===next.due&&timer.id<next.id)&&(next=timer);if(next===void 0)return fired;next.interval===null?this.#timers.delete(next.id):(next.due+=next.interval,next.ticks+=1),fired+=1,invoke(next.callback)}}}export class FrameCallbackQueue{#callbacks=new Map;#nextId=1;request(callback){const id=this.#nextId;return this.#nextId+=1,this.#callbacks.set(id,callback),id}cancel(id){typeof id=="number"&&this.#callbacks.delete(id)}get size(){return this.#callbacks.size}get nextId(){return this.#nextId}pending(fromId=1){let count=0;for(const id of this.#callbacks.keys())id>=fromId&&(count+=1);return count}drain(timestamp,invoke,fromId=1){const handles=[...this.#callbacks.keys()].filter(id=>id>=fromId);let ran=0;for(const id of handles){const callback=this.#callbacks.get(id);callback!==void 0&&(this.#callbacks.delete(id),ran+=1,invoke(()=>callback(timestamp)))}return ran}}

package/dist/components.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The layout and timing components a scene is built from.
+ *
+ * Timing is one rule applied at every level (see `context.ts`): a component reads the frame its
+ * parent sees, decides whether its children exist at that frame, and re-provides the frame
+ * relative to itself. Children outside their window are **not mounted**, rather than hidden, so a
+ * scene's effects and `delayRender` calls run only while it is on screen.
+ *
+ * Media is deliberately narrow in this version. `<Img>` is a plain `<img>` and the harness waits
+ * for every image in the document before a frame is captured. `<Audio>` is a marker: the renderer
+ * muxes the narration track itself, so the element only exists to keep the engine-owned
+ * `Video.tsx` declarative about it, and a second one mounted beside it throws
+ * `NOT_SUPPORTED_IN_V1`, because the narration is the only audio track the video gets. `<Video>`
+ * and `<OffthreadVideo>` throw `NOT_SUPPORTED_IN_V1` the moment they render, because a
+ * frame-accurate video decoder is not part of this renderer and a silently blank rectangle would be
+ * worse than a named refusal. A silently missing sound would be worse in the same way.
+ */
+import { type ComponentProps, type CSSProperties, type ReactElement, type ReactNode } from "react";
+export type AbsoluteFillProps = ComponentProps<"div">;
+/** A `<div>` covering its positioned parent, laid out as a flex column. `style` wins over the fill. */
+export declare function AbsoluteFill({ style, ...rest }: AbsoluteFillProps): ReactElement;
+/** `absolute-fill` wraps the children in an `AbsoluteFill`; `none` renders them as they are. */
+export type SequenceLayout = "absolute-fill" | "none";
+export type SequenceProps = {
+    /** The frame, in the parent's timeline, at which this sequence's frame 0 falls. Default 0. */
+    from?: number;
+    /** How many frames the children stay mounted. Default `Infinity`. */
+    durationInFrames?: number;
+    /** A label for people reading the tree. The renderer ignores it. */
+    name?: string;
+    layout?: SequenceLayout;
+    /** Applied to the `AbsoluteFill` wrapper; ignored with `layout="none"`. */
+    style?: CSSProperties;
+    /** Applied to the `AbsoluteFill` wrapper; ignored with `layout="none"`. */
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Mount the children for frames `from ≤ f < from + durationInFrames` of the parent's timeline,
+ * and show them their own frame, `f − from`.
+ *
+ * `useVideoConfig().durationInFrames` inside is how long the children can actually be on screen:
+ * this sequence's own duration, clipped to what is left of the parent's window from `from` on — so
+ * an open sequence at frame 100 of a 300-frame parent reports 200, and a 50-frame sequence placed
+ * 20 frames before its parent's end reports 20.
+ */
+export declare function Sequence({ from, durationInFrames, layout, style, className, children, }: SequenceProps): ReactElement | null;
+export type SeriesSequenceProps = Omit<SequenceProps, "from" | "durationInFrames"> & {
+    /** Required: the series places the next sequence where this one ends. */
+    durationInFrames: number;
+    /** Shift this sequence, and every one after it, by this many frames. Default 0. */
+    offset?: number;
+};
+export type SeriesProps = {
+    children?: ReactNode;
+};
+/**
+ * The sequences placed back to back. `Series.Sequence` is the only child it accepts, directly or
+ * inside Fragments (`<>…</>`, or an array from `.map`), which are opened in place.
+ */
+export declare const Series: ((props: SeriesProps) => ReactElement) & {
+    Sequence: (props: SeriesSequenceProps) => never;
+};
+export type LoopProps = {
+    /** The length of one iteration. */
+    durationInFrames: number;
+    /** How many iterations to play before unmounting. Default `Infinity`. */
+    times?: number;
+    name?: string;
+    layout?: SequenceLayout;
+    style?: CSSProperties;
+    className?: string;
+    children?: ReactNode;
+};
+/** Replay the children every `durationInFrames`; they see `frame mod durationInFrames`. */
+export declare function Loop({ durationInFrames, times, layout, style, className, children, }: LoopProps): ReactElement | null;
+export type FreezeProps = {
+    /** The frame the children see while frozen. */
+    frame: number;
+    /** Whether the freeze applies, or a test of the parent's frame. Default `true`. */
+    active?: boolean | ((frame: number) => boolean);
+    children?: ReactNode;
+};
+/** Show the children a fixed frame. Adds no wrapper element. */
+export declare function Freeze({ frame, active, children }: FreezeProps): ReactElement;
+export type ImgProps = ComponentProps<"img">;
+/** An `<img>`. The harness holds every frame until each image in the document has loaded. */
+export declare function Img(props: ImgProps): ReactElement;
+export type AudioProps = {
+    src: string;
+    volume?: number | ((frame: number) => number);
+    muted?: boolean;
+    loop?: boolean;
+    name?: string;
+};
+/**
+ * A marker for the narration track. Renders nothing; the renderer muxes the narration itself.
+ * A second concurrently mounted `<Audio>` throws `NOT_SUPPORTED_IN_V1` when it mounts, because the
+ * narration is the only audio track the video gets and the second would be silently missing.
+ */
+export declare function Audio(_props: AudioProps): null;
+export type VideoProps = {
+    src: string;
+    [prop: string]: unknown;
+};
+/** Refused in this version: throws `NOT_SUPPORTED_IN_V1` when rendered. */
+export declare function Video(_props: VideoProps): never;
+/** Refused in this version: throws `NOT_SUPPORTED_IN_V1` when rendered. */
+export declare function OffthreadVideo(_props: VideoProps): never;

package/dist/components.js

@@ -0,0 +1 @@
+import{Fragment as _Fragment,jsx as _jsx}from"react/jsx-runtime";import{Children,Fragment,isValidElement,useEffect}from"react";import{TimelineContext}from"./context.js";import{useTimeline}from"./hooks.js";import{mountAudio}from"./runtime.js";const FILL={position:"absolute",top:0,left:0,right:0,bottom:0,width:"100%",height:"100%",display:"flex",flexDirection:"column"};export function AbsoluteFill({style,...rest}){return _jsx("div",{...rest,style:{...FILL,...style}})}function assertFrom(from,caller){if(typeof from!="number"||!Number.isFinite(from))throw new TypeError(`${caller}: from must be a finite number, got ${String(from)}.`)}function assertDuration(duration,caller){if(typeof duration!="number"||Number.isNaN(duration)||duration<=0)throw new RangeError(`${caller}: durationInFrames must be a positive number or Infinity, got ${String(duration)}.`)}function Layout({layout,style,className,children}){return layout==="none"?_jsx(_Fragment,{children}):_jsx(AbsoluteFill,{style,className,children})}export function Sequence({from=0,durationInFrames=Number.POSITIVE_INFINITY,layout="absolute-fill",style,className,children}){const parent=useTimeline("<Sequence>");assertFrom(from,"<Sequence>"),assertDuration(durationInFrames,"<Sequence>");const frame=parent.frame-from;if(frame<0||frame>=durationInFrames)return null;const left=parent.durationInFrames-from,timeline={frame,durationInFrames:Math.min(durationInFrames,left>0?left:parent.durationInFrames)};return _jsx(TimelineContext.Provider,{value:timeline,children:_jsx(Layout,{layout,style,className,children})})}function SeriesSequence(_props){throw new Error("<Series.Sequence> was rendered on its own. It only has a meaning as a direct child of <Series>.")}function seriesChildren(children,prefix=""){return Children.toArray(children).flatMap(child=>{const key=`${prefix}${isValidElement(child)?String(child.key):""}`;return isValidElement(child)&&child.type===Fragment?seriesChildren(child.props.children,`${key}/`):[{child,key}]})}function SeriesRoot({children}){const items=seriesChildren(children);let cursor=0;const sequences=items.map(({child,key},index)=>{if(!isValidElement(child)||child.type!==SeriesSequence)throw new TypeError("<Series> accepts only <Series.Sequence> elements as its children.");const{durationInFrames,offset=0,...rest}=child.props;if(assertFrom(offset,"<Series.Sequence> offset"),assertDuration(durationInFrames,"<Series.Sequence>"),!Number.isFinite(durationInFrames)&&index!==items.length-1)throw new RangeError("<Series.Sequence>: only the last sequence of a <Series> may have an infinite durationInFrames.");const from=cursor+offset;return cursor=from+durationInFrames,_jsx(Sequence,{...rest,from,durationInFrames},key)});return _jsx(_Fragment,{children:sequences})}export const Series=Object.assign(SeriesRoot,{Sequence:SeriesSequence});export function Loop({durationInFrames,times=Number.POSITIVE_INFINITY,layout="absolute-fill",style,className,children}){const parent=useTimeline("<Loop>");if(!(Number.isFinite(durationInFrames)&&durationInFrames>0))throw new RangeError(`<Loop>: durationInFrames must be a positive finite number, got ${String(durationInFrames)}.`);if(typeof times!="number"||Number.isNaN(times)||times<0)throw new RangeError(`<Loop>: times must be zero or a positive number, got ${String(times)}.`);if(parent.frame<0)return null;const iteration=Math.floor(parent.frame/durationInFrames);if(iteration>=times)return null;const timeline={frame:parent.frame-iteration*durationInFrames,durationInFrames};return _jsx(TimelineContext.Provider,{value:timeline,children:_jsx(Layout,{layout,style,className,children})})}export function Freeze({frame,active=!0,children}){const parent=useTimeline("<Freeze>");if(typeof frame!="number"||Number.isNaN(frame))throw new TypeError(`<Freeze>: frame must be a number, got ${String(frame)}.`);if(!(typeof active=="function"?active(parent.frame):active))return _jsx(_Fragment,{children});const timeline={frame,durationInFrames:parent.durationInFrames};return _jsx(TimelineContext.Provider,{value:timeline,children})}export function Img(props){return _jsx("img",{alt:"",...props})}export function Audio(_props){return useEffect(()=>mountAudio(),[]),null}const VIDEO_NOT_SUPPORTED="NOT_SUPPORTED_IN_V1: video assets are not supported by the xplainer renderer; use <Img> stills instead";export function Video(_props){throw new Error(VIDEO_NOT_SUPPORTED)}export function OffthreadVideo(_props){throw new Error(VIDEO_NOT_SUPPORTED)}