@onmark/cli 0.1.3 → 0.1.4

package/README.md

@@ -1,177 +1,141 @@
-# Onmark
+<h1 align="center">Onmark</h1>
 
-Onmark is a screenplay-first video compiler and rendering engine for people and
-agents.
+<p align="center"><strong>Write the film. Own every frame.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@onmark/cli"><img src="https://img.shields.io/npm/v/%40onmark%2Fcli?color=111214" alt="npm version"></a>
+  <a href="https://github.com/varo-yang/onmark/actions/workflows/ci.yml"><img src="https://github.com/varo-yang/onmark/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f04d32" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://onmark-cdn-1313593665.cos.ap-guangzhou.myqcloud.com/onmark-hero-compiled-draft-v2.mp4">
+    <img src="docs/onmark-hero.gif" alt="Onmark screenplay compiling into a rendered composition" width="720">
+  </a>
+</p>
+
+Onmark is a screenplay-first video compiler for people and agents. Write one
+HTML document with semantic film elements, ordinary CSS, and optional seekable
+motion. Onmark compiles the authored intent into an exact timeline, renders it
+through Chromium, mixes media with FFmpeg, and writes an MP4.
 
 ```text
-screenplay → deterministic Timeline IR → browser frames + audio plan → MP4
+screenplay → Timeline IR → Render Units → browser frames + audio → MP4
 ```
 
-Delivery gates one through seven and distributed incremental reuse are
-complete. No later delivery gate is currently active. Gate one renders and
-independently verifies one real screenplay through the compiler, browser
-protocol, Chromium, and FFmpeg. Gate two partitions one media-bearing two-shot
-film into two local Render Units and
-proves that their assembled decoded video and audio match the whole-film
-baseline. Gate three sends those
-same portable units to two concurrent arm64 Lambda workers, verifies their
-immutable S3 frame artifacts against a remote whole-film capture by canonical
-raw-RGBA pixels, and assembles the partitions through the shared H.264/AAC
-path. Gate four carries authored music, shot-local effects, voice-over, and
-imported SRT/WebVTT/ASS captions through the same local whole-film and
-partitioned paths, with both canonical raw-RGBA frames and decoded audio
-checked for equivalence.
-
-Gate five admits exact-frame effects and a closed presentation temporal
-capability after bounded WAAPI, GSAP, and Three.js experiments. Its exit
-conformance proves that the effect-bearing presentation produces identical
-canonical pixels as one whole-film unit or two independent units. Unknown
-presentation code remains sequential. Deployment work remains frozen.
-
-Gate six carries content-addressed local image, SVG, and font resources through
-bounded browser readiness that names the resource still pending. It also gives
-film, scene, shot, and content facts Rust-owned node identity and ownership.
-Authored IDs retain semantic identity across unit projections. Its Linux exit
-conformance proves equal pixels across cold browsers and whole-film versus
-partitioned execution without adding a general props channel, new screenplay
-spelling, or a second timing system.
-
-Gate seven admits transparent browser presentation over persistent native media
-decode and composition for an explicitly separable visual capability. Its
-locked experiment passes at 4.18× the Chromium-media baseline speed and 79.73%
-of its peak RSS. The production executor preserves a bounded stream, exact
-whole-film/partition equivalence, declared color conformance, and the existing
-Chromium-media path for presentations without the capability. The real-process
-exit fixture passes; this is neither new screenplay syntax nor a hidden
-fallback.
-
-The executor now also carries an independent, proved browser-frame behavior.
-For placement-bounded foregrounds it captures only the first frame and solved
-placement changes, then shares the immutable PNG between intervening output
-frames. The real-process layered control reduces browser evaluation from 75
-authored frames to one while retaining exact canonical raw-RGBA output;
-browser-owned video and unknown authored effects remain per-frame.
-
-The completed foundation includes the pure compiler and versioned wire types in
-`onmark-core`; bounded ffprobe and strict SubRip/WebVTT/ASS normalization in
-`onmark-media`; deterministic video and overlay presentation in
-`@onmark/runtime`; authored-HTML bindings in `@onmark/authoring`; immutable
-presentation artifacts in `@onmark/bundler`; the typed Chromium-to-FFmpeg
-executor in `onmark-render`; and the `onmark-cli` composition root. A production
-deployment workflow and infrastructure definition remain deliberately absent;
-there is still no queue, lease system, scheduler, or coordinator.
-
-## Render
-
-The native command needs one authored HTML document and writes a no-clobber
-`renders/<name>.mp4` by default. Onmark custom elements carry screenplay intent;
-ordinary HTML and inline CSS carry presentation. An optional inline
-`type="module" data-om-motion` script exports vendor-neutral motion
-assembled from adapters such as `onmark/motion/gsap`:
+## One timeline. Three visual languages.
+
+Each film is one authored HTML document rendered by the same deterministic CLI.
+
+<table>
+  <tr>
+    <td width="33%" align="center">
+      <a href="https://onmark-cdn-1313593665.cos.ap-guangzhou.myqcloud.com/onmark-luminous-story.mp4">
+        <img src="docs/showcase-luminous.gif" alt="Luminous Story: chromatic light and kinetic typography">
+      </a>
+    </td>
+    <td width="33%" align="center">
+      <a href="https://onmark-cdn-1313593665.cos.ap-guangzhou.myqcloud.com/onmark-exact-system.mp4">
+        <img src="docs/showcase-system.gif" alt="Exact System: black-and-lime deterministic interface">
+      </a>
+    </td>
+    <td width="33%" align="center">
+      <a href="https://onmark-cdn-1313593665.cos.ap-guangzhou.myqcloud.com/onmark-printed-motion.mp4">
+        <img src="docs/showcase-printed.gif" alt="Printed Motion: monochrome editorial choreography">
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td align="center"><strong>Luminous Story</strong><br><sub>Chromatic atmosphere</sub></td>
+    <td align="center"><strong>Exact System</strong><br><sub>Deterministic interface</sub></td>
+    <td align="center"><strong>Printed Motion</strong><br><sub>Editorial choreography</sub></td>
+  </tr>
+</table>
+
+## Quick start
+
+Install the desktop CLI on macOS arm64, Linux x64, or Windows x64:
 
 ```bash
 npm install --global @onmark/cli
+```
+
+Create `film.html`:
+
+```html
+<om-film>
+  <om-scene>
+    <om-shot duration="3s">
+      <om-title>Hello, motion.</om-title>
+    </om-shot>
+  </om-scene>
+</om-film>
+```
+
+Render it:
+
+```bash
 onmark render film.html
-onmark render film.html --output review.mp4
-onmark render film.html --fps 30000/1001 --width 1920 --height 1080
-onmark render film.html --subtitle captions.vtt
 ```
 
-`--subtitle` imports strict UTF-8 `.srt`, `.vtt`, or `.ass` files without adding
-external-format syntax to the screenplay. Invalid files produce diagnostics
-against their own path and byte spans before browser or media processes start.
-
-Presentation capabilities are not inferred from source text or observed pixel
-equality. The production authored-HTML adapter is admitted as random-access,
-browser-composited, and per-frame; unknown future components remain sequential
-until their own conformance proves otherwise. Immutable bundle metadata carries
-the admitted facts into Render Graph planning.
-
-The desktop command projects each shot into an isolated browser region and
-reuses verified contract-addressed frame artifacts across processes. Editing one
-shot leaves unrelated region artifacts intact; final encoding and audio mixing
-still use the same assembler as a cold render. Every completed command reports
-the exact reused region and frame counts plus pipeline phase timings, so
-incremental work is visible without inspecting the cache.
-
-The Lambda adapter applies the same artifact identity before materializing
-inputs or preparing Chromium. A verified S3 hit skips capture; a corrupt object
-is conditionally repaired through the ordinary worker path. This closes
-distributed incremental reuse without adding a coordinator or durable progress
-service.
-
-## Showcases
-
-[`showcases/`](showcases/) contains twenty self-contained films rendered through
-the public CLI. They cover native media, imported captions, audio, GSAP, Canvas
-2D, raw WebGL, Three.js, spatial CSS, editorial typography, and continuous
-brand motion without relying on a shared visual template or remote assets.
-Rendered outputs remain untracked; each checked-in source and exact render
-command stays reproducible.
-
-The desktop artifact is admitted on macOS arm64, Linux x64, and Windows x64. It
-exposes one `@onmark/cli` package and `onmark` command, carries the native CLI,
-`ffmpeg`, and `ffprobe` in a platform sidecar, and installs the pinned browser
-into a verified private cache. Linux uses Chrome for Testing's
-`chrome-headless-shell` with CDP BeginFrameControl; macOS and Windows use
-ordinary Chrome's portable screenshot backend. macOS selects Metal and verifies
-the active renderer through CDP; Linux and Windows retain `SwiftShader`. Every
-target renders the same admitted screenplay twice in an empty consumer before
-release artifacts are retained. After the initial package bootstrap, merging a
-`release/vX.Y.Z` pull request admits and publishes the same archives through npm
-Trusted Publishing, then creates the matching GitHub Release. Execution
-overrides remain explicit:
-`--graphics software` selects the canonical software control, and
-`--video-encoder-threads` can replace the stable four-thread local default with
-a bounded value from 1 through 64.
-Deterministic comparisons apply within the same locked browser environment,
-capture mode, and graphics backend.
-
-## Worker capture
-
-Gate three introduced a narrow local worker entry point for already-composed
-visual work:
+The command writes `renders/film.mp4` without overwriting an existing file.
+Resolution, exact rational frame rates, and imported subtitles stay explicit:
 
 ```bash
-onmark worker capture --input worker-input --output opening.onmark-frames \
-  --browser /path/to/chrome-headless-shell --ffmpeg /path/to/ffmpeg
+onmark render film.html \
+  --output launch.mp4 \
+  --width 1920 \
+  --height 1080 \
+  --fps 30000/1001 \
+  --subtitle captions.vtt
 ```
 
-`worker-input` contains a versioned `request.json`, including the locked
-capture-environment identity, the `bundle/` payload files named by that
-request's manifest, and any frozen `assets/sha256/` bytes. The worker accepts no
-screenplay and does not compile source. It publishes one checksum-verified,
-no-clobber frame artifact; retry reuse requires both the planned unit and the
-declared capture environment to match. This is the same portable interchange
-used by the Lambda adapter; it is not a cloud coordinator or a replacement for
-`onmark render`.
-
-## Lambda capture adapter
-
-`deploy/aws-lambda` wraps that same worker contract with a bounded S3 download
-and conditional artifact publication. Its V1 invocation and result schemas are
-checked in under `schemas/`; its required environment, IAM scope, limits, and
-intentional non-goals are documented in
-[its deployment README](deploy/aws-lambda/README.md). The real arm64 Lambda ZIP
-experiment and deterministic package command are recorded there. Infrastructure
-provisioning remains outside this gate; desktop npm publication is a separate
-release boundary.
-
-## Repository map
-
-- `crates/` contains Rust product code.
-- `packages/` contains browser and Node product packages.
-- `conformance/` groups compiler, media, browser, CLI, wire, and admission evidence.
-- `evals/` contains frozen language-admission experiments and raw model output.
-- `schemas/` contains the five generated, versioned wire contracts.
-- `scripts/` contains the `xtask` entry point plus evaluation, schema,
-  TypeScript-quality, and release tooling; release npm and media toolchains have
-  separate process-owned subdirectories.
+## Why screenplay-first
+
+- **Intent before coordinates.** Source describes scenes, shots, content, cues,
+  and relationships. Rust owns absolute frame placement and timing provenance.
+- **The browser remains the canvas.** Use HTML, CSS, Canvas, WebGL, Three.js,
+  GSAP, media, fonts, and SVG without introducing a second layout engine.
+- **One execution model.** Whole-film, partitioned, local, Lambda, and
+  incremental renders consume the same verified Render Units and assembler.
+- **Failures stay explainable.** Authored mistakes are diagnostics with source
+  spans; browser, media, and infrastructure faults remain typed errors.
+
+## Authoring
+
+An Onmark film is one self-contained HTML document. Custom elements carry
+screenplay meaning; ordinary HTML and inline CSS carry presentation. Optional
+`data-om-motion` code exports seekable animation through adapters such as
+`onmark/motion/gsap`.
+
+The compiler supports authored video, audio, voice-over, music, sound effects,
+titles, calls to action, cues, and imported SRT, WebVTT, or ASS captions.
+Unknown browser components remain sequential until conformance proves that they
+are safe to seek or partition.
+
+Browse [`showcases/`](showcases/) for complete films using native media, CSS 3D,
+GSAP, Canvas 2D, raw WebGL, Three.js, captions, and audio.
+
+## Architecture
+
+Rust owns compilation, planning, media normalization, browser control, encoding,
+and artifact verification. TypeScript owns authoring bindings and browser
+presentation. The compiler core has no filesystem, network, clock, Chromium,
+FFmpeg, or cloud dependency.
+
+The repository contains four Rust crates:
+
+- `onmark-core` — model, parser, diagnostics, compiler, IR, and wire contracts;
+- `onmark-media` — bounded media and subtitle normalization;
+- `onmark-render` — Chromium, FFmpeg, Render Units, and verified artifacts;
+- `onmark-cli` — the desktop command and composition root.
+
+Browser packages live under [`packages/`](packages/). Rust wire types generate
+the checked-in schemas and TypeScript codecs; CI rejects generated drift.
 
 ## Development
 
-Rust 1.97.0, Node.js 26.4.0, and pnpm 11.9.0 are pinned for reproducible
-development.
+Rust 1.97.0, Node.js 26.4.0, and pnpm 11.9.0 are pinned.
 
 ```bash
 cargo test --workspace
@@ -183,20 +147,14 @@ pnpm lint
 pnpm typecheck
 pnpm test
 cargo xtask schema --check
-cargo xtask eval audio
-cargo xtask eval html
 ```
 
-## Design documents
+Design contracts:
 
 - [Architecture](docs/en/architecture.md)
 - [Language specification](docs/en/language-specification.md)
 - [Presentation contract](docs/en/presentation-contract.md)
 - [Competitive pipeline review](docs/en/competitive-pipeline-review.md)
-- [Rust style guide](docs/en/rust-style-guide.md)
-- [TypeScript style guide](docs/en/typescript-style-guide.md)
 - [中文文档](docs/zh-CN/)
 
-The design documents remain the project contract. Code and documentation
-disagreements must be resolved explicitly rather than silently choosing one
-side.
+Onmark is available under the [MIT License](LICENSE).

package/onmark-release.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "packageName": "@onmark/cli",
-  "version": "0.1.3",
-  "sourceRevision": "25000b2f44d6b2463083ed977ead461b198b9f8b",
+  "version": "0.1.4",
+  "sourceRevision": "faaf3134890c979f082912e6882d99750452031d",
   "files": [
     {
       "path": "LICENSE",
@@ -11,23 +11,43 @@
     },
     {
       "path": "README.md",
-      "bytes": 9972,
-      "sha256": "60000f53e551fea49368f36a68d71933423f314e6dd5bbf1cec495cad84f6c60"
+      "bytes": 5791,
+      "sha256": "d2da7345c7e5a623ca47e26296994f1c4a0febf26415b698397dca44e01e0c8a"
     },
     {
       "path": "package.json",
       "bytes": 1406,
-      "sha256": "93a60078967eb56474b3bcca33115c037432399df91908a161983a3e699d203d"
+      "sha256": "9527406d0676f0d8ff7bd545075a4f66f55072ac71082349400c3ce74ae65321"
+    },
+    {
+      "path": "packages/authoring/dist/src/frame-motion.d.ts",
+      "bytes": 1006,
+      "sha256": "119a4a0327ec0cb6baecf313ed90041b302f6207b2d963ca268a8ba348850e40"
+    },
+    {
+      "path": "packages/authoring/dist/src/frame-motion.js",
+      "bytes": 2685,
+      "sha256": "ca5775d727f39b1d6310d775d090d3db074a55e3e3d2e9a2ad62a9f355c1e578"
     },
     {
       "path": "packages/authoring/dist/src/index.d.ts",
-      "bytes": 444,
-      "sha256": "04a987076863ba1a11fabea37a8c15878abbffa12b4942c28d9b26da1e98f8f3"
+      "bytes": 775,
+      "sha256": "bdf86f3a16736963d83abf2ac8412b26b623bad45140f450666d9060688a5aae"
     },
     {
       "path": "packages/authoring/dist/src/index.js",
-      "bytes": 266,
-      "sha256": "bdff297aee92136a3304af030c07f1b03ee386feee9435deb22b0993ceaf19bb"
+      "bytes": 413,
+      "sha256": "2b9da5ff9f6a3cea24eaf7a835353676aee14d471ece6a45ebe2a0438a4c0d62"
+    },
+    {
+      "path": "packages/authoring/dist/src/interpolation.d.ts",
+      "bytes": 901,
+      "sha256": "0155b6fa4873204b20043c83ad23e6f4442eda727c68bee54fa7042a411c2770"
+    },
+    {
+      "path": "packages/authoring/dist/src/interpolation.js",
+      "bytes": 4007,
+      "sha256": "8cf8289e743b6885514602e336d64db2da7e3d1b2392f1c1ce8efebc32bc25d6"
     },
     {
       "path": "packages/authoring/dist/src/motion.d.ts",
@@ -59,6 +79,16 @@
       "bytes": 2544,
       "sha256": "6f1d471c95678c4b0b4493c704771a59098e5d1d0c7ef81145901f7d86ad31b1"
     },
+    {
+      "path": "packages/authoring/dist/src/spring.d.ts",
+      "bytes": 865,
+      "sha256": "97349b3da4eaaa2ebf4622d543264d47d5a7836061cc3b61b9cf4b93df7d7db3"
+    },
+    {
+      "path": "packages/authoring/dist/src/spring.js",
+      "bytes": 4259,
+      "sha256": "3b11f90933144ec36ab434b91e534dc74ac4503cc1633e85addd456229030274"
+    },
     {
       "path": "packages/authoring/dist/src/types.d.ts",
       "bytes": 133,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onmark/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Screenplay-first deterministic browser video compiler",
   "license": "MIT",
   "repository": {
@@ -45,8 +45,8 @@
     "yauzl": "3.4.0"
   },
   "optionalDependencies": {
-    "@onmark/cli-darwin-arm64": "0.1.3",
-    "@onmark/cli-linux-x64": "0.1.3",
-    "@onmark/cli-win32-x64": "0.1.3"
+    "@onmark/cli-darwin-arm64": "0.1.4",
+    "@onmark/cli-linux-x64": "0.1.4",
+    "@onmark/cli-win32-x64": "0.1.4"
   }
 }

package/packages/authoring/dist/src/frame-motion.d.ts

@@ -0,0 +1,17 @@
+import type { PresentationExtension, PresentationExtensionContext, PresentationTargetKind } from "./motion.js";
+/** One immutable sample inside a semantic element's solved interval. */
+export interface FrameMotionContext {
+    readonly durationFrames: number;
+    readonly element: HTMLElement;
+    readonly frameRate: PresentationExtensionContext["frameRate"];
+    readonly localFrame: number;
+    readonly progress: number;
+}
+/** Applies browser-owned visual state for one exact local frame. */
+export type FrameMotionHandler = (context: FrameMotionContext) => void;
+/** Semantic handlers and optional selector handlers for exact-frame motion. */
+export type FrameMotionDefinition = Readonly<Partial<Record<PresentationTargetKind, FrameMotionHandler>> & {
+    readonly selectors?: Readonly<Record<string, FrameMotionHandler>>;
+}>;
+/** Creates local browser effects driven directly by exact runtime frames. */
+export declare function frameMotion(definition: FrameMotionDefinition): PresentationExtension;

package/packages/authoring/dist/src/frame-motion.js

@@ -0,0 +1,80 @@
+// Vendor-neutral exact-frame motion over compiler-owned semantic intervals.
+// Each sample is local to one target, so presentation code cannot reschedule it.
+/** Creates local browser effects driven directly by exact runtime frames. */
+export function frameMotion(definition) {
+    const rules = ownRules(definition);
+    return Object.freeze({
+        bind(context) {
+            return {
+                effects: bindEffects(rules, context),
+                resources: [],
+            };
+        },
+    });
+}
+function bindEffects(rules, context) {
+    const effects = [];
+    for (const target of context.targets) {
+        const handlers = matchingHandlers(rules, target);
+        if (handlers.length > 0) {
+            effects.push(bindEffect(target, handlers, context.frameRate));
+        }
+    }
+    return Object.freeze(effects);
+}
+function bindEffect(target, handlers, frameRate) {
+    const durationFrames = target.interval.end - target.interval.start;
+    return Object.freeze({
+        apply(frame) {
+            const localFrame = frame.index - target.interval.start;
+            if (localFrame < 0 || localFrame >= durationFrames) {
+                return;
+            }
+            const sample = Object.freeze({
+                durationFrames,
+                element: target.element,
+                frameRate,
+                localFrame,
+                progress: localFrame / durationFrames,
+            });
+            for (const handler of handlers) {
+                handler(sample);
+            }
+        },
+        dispose() {
+            // Direct frame motion retains no vendor playhead or browser resource.
+        },
+    });
+}
+function ownRules(definition) {
+    const kinds = Object.freeze({
+        film: definition.film,
+        scene: definition.scene,
+        shot: definition.shot,
+        video: definition.video,
+        title: definition.title,
+        callToAction: definition.callToAction,
+        caption: definition.caption,
+    });
+    const selectors = Object.freeze(Object.entries(definition.selectors ?? {}).map(ownSelector));
+    return Object.freeze({ kinds, selectors });
+}
+function ownSelector([selector, apply]) {
+    if (selector.trim().length === 0) {
+        throw new RangeError("exact-frame motion selector cannot be blank");
+    }
+    return Object.freeze({ apply, selector });
+}
+function matchingHandlers(rules, target) {
+    const handlers = [];
+    const kind = rules.kinds[target.kind];
+    if (kind !== undefined) {
+        handlers.push(kind);
+    }
+    for (const rule of rules.selectors) {
+        if (target.element.matches(rule.selector)) {
+            handlers.push(rule.apply);
+        }
+    }
+    return handlers;
+}

package/packages/authoring/dist/src/index.d.ts

@@ -1,3 +1,6 @@
+export { frameMotion, type FrameMotionContext, type FrameMotionDefinition, type FrameMotionHandler, } from "./frame-motion.js";
+export { easing, interpolate, type EasingFunction, type Extrapolation, type InterpolationOptions, } from "./interpolation.js";
+export { spring, type SpringFrame, type SpringOptions } from "./spring.js";
 export { combineMotion, type PresentationExtension, type PresentationExtensionContext, type PresentationTarget, type PresentationTargetKind, } from "./motion.js";
 export { createDomPresentationBindings, type DomPresentationOptions, type VideoSource, } from "./presentation.js";
 export { createFontResource, createImageResource, type FontResource, type FontResourceOptions, type ImageResource, type ImageResourceOptions, } from "./resource.js";

package/packages/authoring/dist/src/index.js

@@ -1,4 +1,7 @@
 // Public facade for semantic browser authoring and optional motion adapters.
+export { frameMotion, } from "./frame-motion.js";
+export { easing, interpolate, } from "./interpolation.js";
+export { spring } from "./spring.js";
 export { combineMotion, } from "./motion.js";
 export { createDomPresentationBindings, } from "./presentation.js";
 export { createFontResource, createImageResource, } from "./resource.js";

package/packages/authoring/dist/src/interpolation.d.ts

@@ -0,0 +1,19 @@
+export type EasingFunction = (progress: number) => number;
+export type Extrapolation = "clamp" | "extend";
+export interface InterpolationOptions {
+    /** Maps normalized segment progress before output interpolation. */
+    readonly easing?: EasingFunction;
+    /** Defaults to clamp. */
+    readonly extrapolateLeft?: Extrapolation;
+    /** Defaults to clamp. */
+    readonly extrapolateRight?: Extrapolation;
+}
+/** Stateless easing functions for native exact-frame motion. */
+export declare const easing: Readonly<{
+    inCubic(progress: number): number;
+    inOutCubic(progress: number): number;
+    linear(progress: number): number;
+    outCubic(progress: number): number;
+}>;
+/** Maps a scalar through one piecewise-linear visual domain. */
+export declare function interpolate(input: number, inputRange: readonly number[], outputRange: readonly number[], options?: InterpolationOptions): number;

package/packages/authoring/dist/src/interpolation.js

@@ -0,0 +1,100 @@
+// Piecewise visual-value interpolation for native exact-frame motion.
+// The closed edge policy prevents implicit extrapolation beyond authored ranges.
+/** Stateless easing functions for native exact-frame motion. */
+export const easing = Object.freeze({
+    inCubic(progress) {
+        return progress ** 3;
+    },
+    inOutCubic(progress) {
+        if (progress < 0.5) {
+            return 4 * progress ** 3;
+        }
+        return 1 - (-2 * progress + 2) ** 3 / 2;
+    },
+    linear(progress) {
+        return progress;
+    },
+    outCubic(progress) {
+        return 1 - (1 - progress) ** 3;
+    },
+});
+/** Maps a scalar through one piecewise-linear visual domain. */
+export function interpolate(input, inputRange, outputRange, options = {}) {
+    validateInterpolation(input, inputRange, outputRange);
+    validateOptions(options);
+    const value = applyExtrapolation(input, inputRange, options);
+    const segment = segmentFor(value, inputRange);
+    const inputStart = rangeValue(inputRange, segment);
+    const inputEnd = rangeValue(inputRange, segment + 1);
+    const outputStart = rangeValue(outputRange, segment);
+    const outputEnd = rangeValue(outputRange, segment + 1);
+    const progress = (value - inputStart) / (inputEnd - inputStart);
+    const eased = (options.easing ?? easing.linear)(progress);
+    requireFinite(eased, "interpolation easing must return finite progress");
+    const output = outputStart + (outputEnd - outputStart) * eased;
+    requireFinite(output, "interpolation output must be finite");
+    return output;
+}
+function validateOptions(options) {
+    if (options.easing !== undefined && typeof options.easing !== "function") {
+        throw new RangeError("interpolation easing must be a function");
+    }
+    validateExtrapolation(options.extrapolateLeft, "left");
+    validateExtrapolation(options.extrapolateRight, "right");
+}
+function validateExtrapolation(extrapolation, edge) {
+    if (extrapolation !== undefined &&
+        extrapolation !== "clamp" &&
+        extrapolation !== "extend") {
+        throw new RangeError(`interpolation ${edge} extrapolation must be clamp or extend`);
+    }
+}
+function validateInterpolation(input, inputRange, outputRange) {
+    requireFinite(input, "interpolation input must be finite");
+    if (inputRange.length < 2) {
+        throw new RangeError("interpolation ranges need at least two values");
+    }
+    if (inputRange.length !== outputRange.length) {
+        throw new RangeError("interpolation ranges must have the same length");
+    }
+    for (let index = 0; index < inputRange.length; index += 1) {
+        const inputValue = rangeValue(inputRange, index);
+        const outputValue = rangeValue(outputRange, index);
+        requireFinite(inputValue, "interpolation input range must be finite");
+        requireFinite(outputValue, "interpolation output range must be finite");
+        if (index > 0 && inputValue <= rangeValue(inputRange, index - 1)) {
+            throw new RangeError("interpolation input range must be strictly increasing");
+        }
+    }
+}
+function applyExtrapolation(input, inputRange, options) {
+    const first = rangeValue(inputRange, 0);
+    const last = rangeValue(inputRange, inputRange.length - 1);
+    if (input < first && (options.extrapolateLeft ?? "clamp") === "clamp") {
+        return first;
+    }
+    if (input > last && (options.extrapolateRight ?? "clamp") === "clamp") {
+        return last;
+    }
+    return input;
+}
+function segmentFor(input, inputRange) {
+    for (let index = 1; index < inputRange.length; index += 1) {
+        if (input <= rangeValue(inputRange, index)) {
+            return index - 1;
+        }
+    }
+    return inputRange.length - 2;
+}
+function requireFinite(value, message) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(message);
+    }
+}
+function rangeValue(range, index) {
+    const value = range[index];
+    if (value === undefined) {
+        throw new RangeError("interpolation range is incomplete");
+    }
+    return value;
+}

package/packages/authoring/dist/src/spring.d.ts

@@ -0,0 +1,19 @@
+import type { PresentationExtensionContext } from "./motion.js";
+export interface SpringFrame {
+    readonly frameRate: PresentationExtensionContext["frameRate"];
+    readonly localFrame: number;
+}
+export interface SpringOptions {
+    /** Damping coefficient. Defaults to 10. */
+    readonly damping?: number;
+    /** Initial progress velocity per second toward the target. Defaults to zero. */
+    readonly initialVelocity?: number;
+    /** Moving mass. Defaults to one. */
+    readonly mass?: number;
+    /** Whether progress may cross the zero-to-one visual range. */
+    readonly overshoot?: "allow" | "clamp";
+    /** Restoring-force stiffness. Defaults to 100. */
+    readonly stiffness?: number;
+}
+/** Samples a damped physical spring directly at one exact local frame. */
+export declare function spring(frame: SpringFrame, options?: SpringOptions): number;

package/packages/authoring/dist/src/spring.js

@@ -0,0 +1,95 @@
+// Closed-form spring sampling over exact local frame facts.
+// Direct evaluation stays independent of DOM state and prior seek order.
+const DEFAULT_SPRING = Object.freeze({
+    damping: 10,
+    initialVelocity: 0,
+    mass: 1,
+    overshoot: "allow",
+    stiffness: 100,
+});
+/** Samples a damped physical spring directly at one exact local frame. */
+export function spring(frame, options = {}) {
+    validateFrame(frame);
+    const parameters = springParameters(options);
+    const seconds = (frame.localFrame / frame.frameRate.numerator) *
+        frame.frameRate.denominator;
+    const displacement = springDisplacement(seconds, parameters);
+    const progress = 1 - displacement;
+    requireFinite(progress, "spring progress must be finite");
+    if (parameters.overshoot === "allow") {
+        return progress;
+    }
+    return Math.max(0, Math.min(progress, 1));
+}
+function springDisplacement(seconds, parameters) {
+    const frequency = Math.sqrt(parameters.stiffness / parameters.mass);
+    const decay = parameters.damping / (2 * parameters.mass);
+    const criticalTolerance = frequency * 1e-7;
+    if (decay < frequency - criticalTolerance) {
+        return underDampedDisplacement(seconds, frequency, decay, parameters);
+    }
+    if (decay > frequency + criticalTolerance) {
+        return overDampedDisplacement(seconds, frequency, decay, parameters);
+    }
+    // The general solutions divide by the vanishing distance between roots.
+    // Their critical limit is both equivalent and numerically stable here.
+    return criticallyDampedDisplacement(seconds, frequency, parameters);
+}
+function underDampedDisplacement(seconds, frequency, decay, parameters) {
+    const dampedFrequency = Math.sqrt(frequency ** 2 - decay ** 2);
+    const velocityTerm = (decay - parameters.initialVelocity) / dampedFrequency;
+    return (Math.exp(-decay * seconds) *
+        (Math.cos(dampedFrequency * seconds) +
+            velocityTerm * Math.sin(dampedFrequency * seconds)));
+}
+function criticallyDampedDisplacement(seconds, decay, parameters) {
+    const velocityTerm = decay - parameters.initialVelocity;
+    return Math.exp(-decay * seconds) * (1 + velocityTerm * seconds);
+}
+function overDampedDisplacement(seconds, frequency, decay, parameters) {
+    const root = Math.sqrt(decay ** 2 - frequency ** 2);
+    const slowRoot = -decay + root;
+    const fastRoot = -decay - root;
+    const slowWeight = (-parameters.initialVelocity - fastRoot) / (slowRoot - fastRoot);
+    const fastWeight = 1 - slowWeight;
+    return (slowWeight * Math.exp(slowRoot * seconds) +
+        fastWeight * Math.exp(fastRoot * seconds));
+}
+function springParameters(options) {
+    const parameters = {
+        damping: options.damping ?? DEFAULT_SPRING.damping,
+        initialVelocity: options.initialVelocity ?? DEFAULT_SPRING.initialVelocity,
+        mass: options.mass ?? DEFAULT_SPRING.mass,
+        overshoot: options.overshoot ?? DEFAULT_SPRING.overshoot,
+        stiffness: options.stiffness ?? DEFAULT_SPRING.stiffness,
+    };
+    requirePositive(parameters.damping, "spring damping");
+    requireFinite(parameters.initialVelocity, "spring initial velocity must be finite");
+    requirePositive(parameters.mass, "spring mass");
+    requirePositive(parameters.stiffness, "spring stiffness");
+    if (parameters.overshoot !== "allow" && parameters.overshoot !== "clamp") {
+        throw new RangeError("spring overshoot must be allow or clamp");
+    }
+    return parameters;
+}
+function validateFrame(frame) {
+    if (!Number.isSafeInteger(frame.localFrame) || frame.localFrame < 0) {
+        throw new RangeError("spring local frame must be a non-negative safe integer");
+    }
+    if (!Number.isSafeInteger(frame.frameRate.numerator) ||
+        !Number.isSafeInteger(frame.frameRate.denominator) ||
+        frame.frameRate.numerator <= 0 ||
+        frame.frameRate.denominator <= 0) {
+        throw new RangeError("spring frame rate must contain positive safe integers");
+    }
+}
+function requirePositive(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`${label} must be positive and finite`);
+    }
+}
+function requireFinite(value, message) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(message);
+    }
+}