@anvpx/motion-scenes 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvpx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @anvpx/motion-scenes
 
-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.
+Scene plugins (`ScenePlugin` from `@anvpx/motion-schema`) and the shared browser runtime. Base scenes: `title`, `bullets`, `stat`, `flow`, `outro`. Overlay scenes: `lower-third`, `bug`, `progress`, `countdown`, `chapter`.
+
+- `sceneRegistry` / `getScene(type)` / `sceneTypes`: build consumes only this barrel.
+- `runtimeFiles()`: shared modules (`runtime/easing.js`, `timeline.js`, `mount.js`), emitted once by build.
+- `emit(entry, ctx)` returns, per scene id: `scenes/<id>/fragment.html`, `style.css`, `scene.js`.
+
+Fragment root is `<section id="scene-<id>">` without a `clip` class; build wraps timing.
+
+## Add a scene
+
+1. New folder `src/scenes/<type>/` with `index.ts`, `style.css`, `scene.js`, `index.test.ts`.
+2. Build the plugin with `defineScene` (`type`, `configSchema`, `meta`, `style`, `script`, `render`); run `describeSceneContract` in its test.
+3. Add one import and one entry to the `plugins` list in `src/registry.ts`.
+4. Run `mk catalog --write` to refresh the root `CATALOG.md` (a test fails on drift).
+
+## Overlay scenes
+
+An overlay is a transparent layer above the base timeline (`layer: "overlay"` on the storyboard entry; the plugin declares `layer: "overlay"` in `defineScene`). The root has no background, ignores pointer events and keeps the 5 % safe margin as padding, so content stays inside 90 % of the frame.
+
+## Catalog metadata
+
+Each scene passes `meta: { purpose, example }` to `defineScene`: a one-line purpose and the smallest props object that passes the schema. `sceneDocs()` derives everything else (layer, fields, required/optional, types, enums, defaults) from `configSchema` via `z.toJSONSchema`, so the schema stays the single source of truth. `mk catalog` and the generated `CATALOG.md` at the repo root consume it. Cross-field rules (for example `bug`: exactly one of `text` or `image`) are not derivable; state them in `purpose`.
+
+## Flow layout
+
+`flow` sizes its cards from the label text with a deterministic width estimate (`scenes/flow/measure.ts`, no font loading): labels wrap only at spaces, into at most two lines, and a word is never broken; a card widens for a long word and the text steps down `lg` -> `md` -> `sm` (theme steps, so always >= 28 px) before it is declared crowded. Edge labels sit on or beside their own edge and slide along it (then to either side) until they clear every card, earlier label and other edge; the room between layers is 2.2x the longest label. `planFlow` is the single layout; the scene renders it and `inspectFlow` (exported) feeds the lint rules below.
+
+## Runtime contract
+
+`createScene(root, config, ctx)` returns `{ seek(t), dispose(), ready }`. `seek(t)` is a pure function of `t`. Config falls back to `data-*` attributes on the root (ease, move, focus, fps, duration). Browser code is plain ES modules (`// @ts-check` plus JSDoc), shipped as text. No `requestAnimationFrame`, `Date.now` or unseeded random.
+
+## Theme and text rules
+
+CSS uses only `--mk-*` custom properties from `@anvpx/motion-themes`; text is at least 28 px and uses one theme font family; at most 40 on-screen words per scene (`limitWords`). Props are strict (unknown keys rejected).
+
+## Shared helpers
+
+`src/shared/` holds the helpers every scene reuses (one implementation, no per-scene copies): `staggerStart`/`staggerDuration` (offset always < item duration), `countUp` (ease-out, exact end), `progress`/`scale`/`lerp`/`clamp`, `wipe`, `drawOn`, `revealTimings`/`revealProgress` (word by word), `fmt` (locale-free tabular numbers: unit, decimals, sign, compact), `fitText` (deterministic width estimate, balanced wrap, never breaks a word, last line >= 35 % of the widest), `sceneIcon` (config error with the prop pointer and 3 suggestions), and `esc`/`accentHtml` (`[x]` accent markup; every character escaped, only `<span class="accent">` is emitted). `motion.js` and `format.js` are plain browser ES modules (they import `runtime/easing.js`); emitting them next to `runtime/` is wired by the first scene that needs them. `@anvpx/motion-assets` (a leaf) is imported only by `shared/icon.ts`.

package/dist/catalog.d.ts

@@ -0,0 +1,17 @@
+export interface FieldDoc {
+    readonly name: string;
+    /** Compact type: `text`, `number`, `int 0..99`, `a|b` (enum), `text[1..6]`, `{id,label}[2..8]`. */
+    readonly type: string;
+    readonly required: boolean;
+    readonly default?: unknown;
+}
+export interface SceneDoc {
+    readonly type: string;
+    readonly layer: "base" | "overlay";
+    readonly purpose: string;
+    readonly fields: readonly FieldDoc[];
+    /** Minimal props that pass the scene's schema. */
+    readonly example: Readonly<Record<string, unknown>>;
+}
+/** Catalog data for every registered scene, derived from each plugin's configSchema and meta. */
+export declare const sceneDocs: () => SceneDoc[];

package/dist/catalog.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { sceneRegistry } from "./registry.js";
+const range = (min, max) => min === undefined && max === undefined ? "" : `${min ?? ""}..${max ?? ""}`;
+const textType = (node) => node.maxLength === undefined ? "text" : `text<=${node.maxLength}`;
+const numberType = (node) => {
+    const base = node.type === "integer" ? "int" : "number";
+    const bounds = range(node.minimum, node.maximum);
+    return bounds === "" ? base : `${base} ${bounds}`;
+};
+const arrayType = (node) => {
+    const bounds = range(node.minItems, node.maxItems);
+    return `${typeOf(node.items ?? {})}${bounds === "" ? "[]" : `[${bounds}]`}`;
+};
+const scalarType = (node) => {
+    if (node.type === "string")
+        return textType(node);
+    if (node.type === "number" || node.type === "integer")
+        return numberType(node);
+    return node.type === "boolean" ? "boolean" : "any";
+};
+/** Compact, single-line type of a JSON Schema node. */
+function typeOf(node) {
+    if (node.enum)
+        return node.enum.map(String).join("|");
+    if (node.anyOf)
+        return node.anyOf.map(typeOf).join("|");
+    if (node.type === "array")
+        return arrayType(node);
+    if (node.type === "object")
+        return `{${Object.keys(node.properties ?? {}).join(",")}}`;
+    return scalarType(node);
+}
+const fieldsOf = (plugin) => {
+    const schema = z.toJSONSchema(plugin.configSchema, { io: "input" });
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties ?? {}).map(([name, node]) => ({
+        name,
+        type: typeOf(node),
+        required: required.has(name),
+        ...("default" in node ? { default: node.default } : {}),
+    }));
+};
+const docOf = (plugin) => ({
+    type: plugin.type,
+    layer: plugin.layer ?? "base",
+    purpose: plugin.meta?.purpose ?? "",
+    fields: fieldsOf(plugin),
+    example: plugin.meta?.example ?? {},
+});
+/** Catalog data for every registered scene, derived from each plugin's configSchema and meta. */
+export const sceneDocs = () => [...sceneRegistry.values()].map(docOf);

package/dist/custom.d.ts

@@ -0,0 +1,86 @@
+import { type EmitContext, type SceneEntry, type VendorLib } from "@anvpx/motion-schema";
+/** The storyboard `type` that means "the author wrote this scene". */
+export declare const CUSTOM_SCENE_TYPE = "custom";
+/** One extra file an authored scene imports by relative path (path is scene-relative, forward slash). */
+export interface CustomSceneFile {
+    readonly path: string;
+    readonly text: string;
+}
+/** An authored scene's three files, already read from disk by the caller. */
+export interface CustomSceneSource {
+    readonly html: string;
+    readonly css?: string;
+    readonly js: string;
+    /** Browser libraries `js` imports by bare specifier; the build vendors each (ADR-0006). */
+    readonly vendor?: readonly VendorLib[];
+    /**
+     * Relative-import closure of `js` (its own helpers, and theirs). Emitted beside
+     * `scene.js`, so `import { x } from "./helper.js"` resolves in the built project.
+     */
+    readonly files?: readonly CustomSceneFile[];
+}
+export interface VendorScan {
+    /** Vendored libraries the script imports, sorted and deduplicated. */
+    readonly libs: readonly VendorLib[];
+    /** Bare specifiers that nothing vendors, so the page would 404 on them. */
+    readonly unknown: readonly string[];
+}
+/**
+ * What a scene script imports. Relative paths are the emitted project's own files; a bare
+ * specifier only works if the build wrote an import map entry for it.
+ */
+export declare const scanVendorImports: (js: string) => VendorScan;
+export type SceneDirResult = {
+    readonly ok: true;
+    readonly dir: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Relative module specifiers a scene script imports, split from those that would escape. */
+export interface RelativeImportScan {
+    /** Specifiers as written (`./lib/x.js`), deduplicated and sorted. */
+    readonly paths: readonly string[];
+    /** Absolute or drive-qualified specifiers: never a scene-local helper. */
+    readonly escaping: readonly string[];
+}
+/**
+ * The `./x` specifiers one script imports. Bare specifiers are the vendored ones
+ * (`scanVendorImports`); an absolute or drive path is reported as escaping because
+ * packaging can only copy files inside the scene directory.
+ */
+export declare const scanRelativeImports: (js: string) => RelativeImportScan;
+/** Packaging limits: a scene is a few files, not a bundled application. */
+export declare const HELPER_LIMITS: {
+    readonly files: 32;
+    readonly chars: 262144;
+};
+export interface RelativeClosure {
+    /** Helpers found, sorted by scene-relative path. */
+    readonly files: readonly CustomSceneFile[];
+    /** Specifiers that point outside the scene directory. */
+    readonly escaping: readonly string[];
+    /** Helper paths that do not exist beside the scene. */
+    readonly missing: readonly string[];
+    /** True when the file/byte limit stopped the walk. */
+    readonly overflow: boolean;
+}
+/**
+ * Walks the relative-import closure of an authored scene's script, reading each
+ * helper through the injected `read` (so this stays free of filesystem access).
+ * Nested helpers resolve against their own directory; the walk is breadth-first,
+ * deduplicated and bounded by {@link HELPER_LIMITS}.
+ */
+export declare const readRelativeClosure: (entryJs: string, read: (path: string) => Promise<string | undefined>) => Promise<RelativeClosure>;
+/**
+ * Resolves `props.dir` against the storyboard's directory and refuses anything that
+ * escapes it. A storyboard is data until it points at code, so the containment check
+ * is the boundary between "a document" and "arbitrary code execution".
+ */
+export declare const resolveSceneDir: (baseDir: string, requested: string) => SceneDirResult;
+/**
+ * Emits an authored scene as the same three files a catalog scene produces, so the
+ * rest of the pipeline (fragment guard, boot, manifest, cache) cannot tell them apart.
+ * `#scene-root` in the author's CSS is rewritten to this scene's selector.
+ */
+export declare const emitCustomScene: (entry: SceneEntry, ctx: EmitContext, source: CustomSceneSource) => Map<string, string>;

package/dist/custom.js

@@ -0,0 +1,176 @@
+import { isAbsolute, posix, relative, resolve } from "node:path";
+import { SceneEntryBaseSchema, } from "@anvpx/motion-schema";
+import { rootElement, safePadding } from "./define-scene.js";
+import { isSharedModulePath } from "./runtime-files.js";
+/** The storyboard `type` that means "the author wrote this scene". */
+export const CUSTOM_SCENE_TYPE = "custom";
+/** The bare specifiers a scene script may import; everything else must be a relative path. */
+const VENDORED = new Set(["three", "postprocessing"]);
+const SPECIFIER = /(?:from\s*|import\s*\(\s*|import\s+)["']([^"']+)["']/g;
+/**
+ * What a scene script imports. Relative paths are the emitted project's own files; a bare
+ * specifier only works if the build wrote an import map entry for it.
+ */
+export const scanVendorImports = (js) => {
+    const libs = new Set();
+    const unknown = new Set();
+    for (const match of js.matchAll(SPECIFIER)) {
+        const specifier = match[1] ?? "";
+        if (specifier === "" || specifier.startsWith(".") || specifier.startsWith("/"))
+            continue;
+        if (VENDORED.has(specifier))
+            libs.add(specifier);
+        else
+            unknown.add(specifier);
+    }
+    return { libs: [...libs].sort(), unknown: [...unknown].sort() };
+};
+/**
+ * The `./x` specifiers one script imports. Bare specifiers are the vendored ones
+ * (`scanVendorImports`); an absolute or drive path is reported as escaping because
+ * packaging can only copy files inside the scene directory.
+ */
+export const scanRelativeImports = (js) => {
+    const paths = new Set();
+    const escaping = new Set();
+    for (const match of js.matchAll(SPECIFIER)) {
+        const specifier = match[1] ?? "";
+        if (specifier === "")
+            continue;
+        if (specifier.startsWith("/") || specifier.startsWith("\\") || /^[a-zA-Z]:/.test(specifier)) {
+            escaping.add(specifier);
+            continue;
+        }
+        if (!specifier.startsWith("."))
+            continue;
+        paths.add(specifier);
+    }
+    return { paths: [...paths].sort(), escaping: [...escaping].sort() };
+};
+/** Resolves a relative specifier against the importing file's scene-relative directory. */
+const resolveRelative = (base, specifier) => {
+    const joined = posix.normalize(posix.join(base === "" ? "." : base, specifier));
+    if (joined === "." || joined === "" || joined.startsWith("../") || posix.isAbsolute(joined)) {
+        return undefined;
+    }
+    return joined;
+};
+/** Packaging limits: a scene is a few files, not a bundled application. */
+export const HELPER_LIMITS = { files: 32, chars: 262_144 };
+/**
+ * Walks the relative-import closure of an authored scene's script, reading each
+ * helper through the injected `read` (so this stays free of filesystem access).
+ * Nested helpers resolve against their own directory; the walk is breadth-first,
+ * deduplicated and bounded by {@link HELPER_LIMITS}.
+ */
+export const readRelativeClosure = async (entryJs, read) => {
+    const found = new Map();
+    const missing = new Set();
+    const escaping = new Set();
+    let chars = 0;
+    let overflow = false;
+    const queue = [{ text: entryJs, base: "" }];
+    while (queue.length > 0 && !overflow) {
+        const item = queue.shift();
+        if (item === undefined)
+            break;
+        const scan = scanRelativeImports(item.text);
+        for (const specifier of scan.escaping)
+            escaping.add(specifier);
+        for (const specifier of scan.paths) {
+            // Shared modules are virtual build outputs, never reads from the source
+            // filesystem. Resolve from the same scenes/<id>/ location used by emit.
+            const emitted = posix.normalize(posix.join("scenes/custom", item.base, specifier));
+            if (isSharedModulePath(emitted))
+                continue;
+            const path = resolveRelative(item.base, specifier);
+            if (path === undefined) {
+                escaping.add(specifier);
+                continue;
+            }
+            if (found.has(path))
+                continue;
+            if (found.size >= HELPER_LIMITS.files) {
+                overflow = true;
+                break;
+            }
+            const text = await read(path);
+            if (text === undefined) {
+                missing.add(path);
+                continue;
+            }
+            if (chars + text.length > HELPER_LIMITS.chars) {
+                overflow = true;
+                break;
+            }
+            chars += text.length;
+            found.set(path, text);
+            queue.push({ text, base: posix.dirname(path) });
+        }
+    }
+    return {
+        files: [...found.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([path, text]) => ({ path, text })),
+        escaping: [...escaping].sort(),
+        missing: [...missing].sort(),
+        overflow,
+    };
+};
+const ESCAPE = "props.dir must stay inside the storyboard directory";
+const ABSOLUTE = "props.dir must be relative to the storyboard";
+/**
+ * Resolves `props.dir` against the storyboard's directory and refuses anything that
+ * escapes it. A storyboard is data until it points at code, so the containment check
+ * is the boundary between "a document" and "arbitrary code execution".
+ */
+export const resolveSceneDir = (baseDir, requested) => {
+    const trimmed = requested.trim();
+    if (trimmed === "")
+        return { ok: false, message: "props.dir is empty" };
+    if (isAbsolute(trimmed) || /^[a-zA-Z]:/.test(trimmed) || trimmed.startsWith("\\\\")) {
+        return { ok: false, message: ABSOLUTE };
+    }
+    const base = resolve(baseDir);
+    const target = resolve(base, trimmed);
+    const rel = relative(base, target);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        return { ok: false, message: ESCAPE };
+    }
+    return { ok: true, dir: target };
+};
+/** Root styles for an authored scene: fills the frame and inherits the theme, nothing else. */
+const baseCss = (root, ctx) => `${root} {
+  position: absolute;
+  inset: 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  overflow: hidden;
+  padding: ${safePadding(ctx)};
+  color: var(--mk-color-fg);
+  font-family: var(--mk-font-sans);
+  line-height: 1.2;
+}
+${root} * { margin: 0; box-sizing: border-box; }
+`;
+/**
+ * Emits an authored scene as the same three files a catalog scene produces, so the
+ * rest of the pipeline (fragment guard, boot, manifest, cache) cannot tell them apart.
+ * `#scene-root` in the author's CSS is rewritten to this scene's selector.
+ */
+export const emitCustomScene = (entry, ctx, source) => {
+    const id = SceneEntryBaseSchema.shape.id.parse(entry.id);
+    const root = `#scene-${id}`;
+    const dir = `scenes/${id}`;
+    const css = (source.css ?? "").replaceAll("#scene-root", root);
+    const files = new Map([
+        [`${dir}/fragment.html`, rootElement(entry, ctx, { type: CUSTOM_SCENE_TYPE }, source.html)],
+        [`${dir}/style.css`, baseCss(root, ctx) + css],
+        [`${dir}/scene.js`, source.js],
+    ]);
+    for (const helper of source.files ?? [])
+        files.set(`${dir}/${helper.path}`, helper.text);
+    return files;
+};

package/dist/define-scene.d.ts

@@ -0,0 +1,31 @@
+import { type EmitContext, type SceneEntry, type SceneMeta, type ScenePlugin, type VendorLib } from "@anvpx/motion-schema";
+import type { z } from "zod";
+export interface Rendered {
+    /** Children of the scene root element. */
+    readonly body: string;
+    /** Extra CSS (already scoped to the root selector). */
+    readonly css?: string;
+}
+export interface SceneSpec<S extends z.ZodType> {
+    readonly type: string;
+    /** "overlay": transparent layer above the base timeline (no background, no camera art). */
+    readonly layer?: "overlay";
+    readonly configSchema: S;
+    /** Catalog documentation: purpose line and minimal example props. */
+    readonly meta: SceneMeta;
+    /** Static CSS; `#scene-root` is replaced by the scene's root selector. */
+    readonly style: string;
+    /** Static ES module text: `export function createScene(root, config, ctx)`. */
+    readonly script: string;
+    /** Browser libraries the script imports by bare specifier; the build vendors them (ADR-0006). */
+    readonly vendor?: readonly VendorLib[];
+    render(props: z.output<S>, ctx: EmitContext, root: string): Rendered;
+}
+/** Safe-margin padding of the 5 % rule, in px. */
+export declare const safePadding: (ctx: EmitContext) => string;
+export declare const rootElement: (entry: SceneEntry, ctx: EmitContext, spec: {
+    type: string;
+    layer?: "overlay";
+}, body: string) => string;
+/** Builds a ScenePlugin: validates props, renders the fragment, assembles the three files. */
+export declare const defineScene: <S extends z.ZodType>(spec: SceneSpec<S>) => ScenePlugin;

package/dist/define-scene.js

@@ -0,0 +1,128 @@
+import { SceneEntryBaseSchema, } from "@anvpx/motion-schema";
+import { esc } from "./html.js";
+const SAFE_MARGIN = 0.05;
+const DEFAULT_EASE = "out";
+const DEFAULT_MOVE = "static";
+/** Safe-margin padding of the 5 % rule, in px. */
+export const safePadding = (ctx) => {
+    const { insets } = ctx;
+    const side = (frac, size) => Math.round(size * Math.max(SAFE_MARGIN, frac ?? 0));
+    if (insets === undefined)
+        return `${side(0, ctx.height)}px ${side(0, ctx.width)}px`;
+    const { top, right, bottom, left } = insets;
+    return [
+        side(top, ctx.height),
+        side(right, ctx.width),
+        side(bottom, ctx.height),
+        side(left, ctx.width),
+    ]
+        .map((px) => `${px}px`)
+        .join(" ");
+};
+const baseCss = (root, ctx) => `${root} {
+  position: absolute;
+  inset: 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: ${safePadding(ctx)};
+  overflow: hidden;
+  isolation: isolate;
+  background: var(--mk-grain-image, none), linear-gradient(160deg, var(--mk-color-bg) 0%, var(--mk-color-bgEnd) 100%);
+  color: var(--mk-color-fg);
+  font-family: var(--mk-font-sans);
+  line-height: 1.2;
+}
+${root}::before {
+  content: "";
+  position: absolute;
+  inset: -12%;
+  z-index: -1;
+  pointer-events: none;
+  background:
+    radial-gradient(48% 56% at calc(80% + var(--drift, 0) * 3%) calc(28% - var(--drift, 0) * 4%), var(--mk-color-glow) 0%, transparent 100%),
+    radial-gradient(40% 50% at calc(8% - var(--drift, 0) * 3%) calc(104% + var(--drift, 0) * 3%), var(--mk-color-glow2) 0%, transparent 100%);
+}
+${root}::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  background-image: radial-gradient(color-mix(in srgb, var(--mk-color-fg) 12%, transparent) 2px, transparent 2.5px);
+  background-size: 64px 64px;
+  background-position: calc(var(--drift, 0) * 8px) 0;
+  mask-image: radial-gradient(75% 75% at 50% 50%, transparent 30%, black 100%);
+}
+${root} * { margin: 0; box-sizing: border-box; }
+${root} [data-anim] { opacity: 0; }
+${root} [data-anim="draw"] { stroke-dasharray: 1; stroke-dashoffset: 1; }
+${root} [data-anim="grow"] { transform: scaleX(0); }
+${root} .mk-rule {
+  display: block;
+  flex: none;
+  width: 160px;
+  height: 8px;
+  border-radius: var(--mk-radius-full);
+  background: linear-gradient(90deg, var(--mk-color-accent), var(--mk-color-accent2));
+  transform-origin: left center;
+}
+`;
+/** Transparent, click-through layer; content stays inside the safe margin. */
+const overlayCss = (root, ctx) => `${root} {
+  position: absolute;
+  inset: 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  padding: ${safePadding(ctx)};
+  overflow: hidden;
+  pointer-events: none;
+  color: var(--mk-color-fg);
+  font-family: var(--mk-font-sans);
+  font-size: var(--mk-font-size-sm);
+  line-height: 1.2;
+}
+${root} * { margin: 0; box-sizing: border-box; }
+${root} [data-anim] { opacity: 0; }
+${root} [data-anim="grow"] { transform: scaleX(0); }
+`;
+export const rootElement = (entry, ctx, spec, body) => {
+    const { type, layer } = spec;
+    const attrs = [
+        `id="scene-${entry.id}"`,
+        `class="${layer === "overlay" ? "mk-scene mk-overlay" : "mk-scene"} mk-${type}"`,
+        `data-ease="${esc(entry.ease ?? DEFAULT_EASE)}"`,
+        `data-move="${esc(entry.move ?? DEFAULT_MOVE)}"`,
+        `data-focus="${esc(entry.focus ?? "")}"`,
+        `data-fps="${ctx.fps}"`,
+        `data-duration="${ctx.duration}"`,
+    ];
+    return `<section ${attrs.join(" ")}>\n${body}\n</section>\n`;
+};
+/** Builds a ScenePlugin: validates props, renders the fragment, assembles the three files. */
+export const defineScene = (spec) => ({
+    type: spec.type,
+    ...(spec.layer === undefined ? {} : { layer: spec.layer }),
+    configSchema: spec.configSchema,
+    meta: spec.meta,
+    ...(spec.vendor === undefined ? {} : { vendor: spec.vendor }),
+    emit(entry, ctx) {
+        const id = SceneEntryBaseSchema.shape.id.parse(entry.id);
+        const props = spec.configSchema.parse(entry.props);
+        const root = `#scene-${id}`;
+        const { body, css = "" } = spec.render(props, ctx, root);
+        const dir = `scenes/${id}`;
+        return new Map([
+            [`${dir}/fragment.html`, rootElement(entry, ctx, spec, body)],
+            [
+                `${dir}/style.css`,
+                (spec.layer === "overlay" ? overlayCss(root, ctx) : baseCss(root, ctx)) +
+                    spec.style.replaceAll("#scene-root", root) +
+                    css,
+            ],
+            [`${dir}/scene.js`, spec.script],
+        ]);
+    },
+});

package/dist/html.d.ts

@@ -0,0 +1,5 @@
+/** Escapes text for element content and double- or single-quoted attributes. */
+export declare const esc: (text: string) => string;
+export type AnimKind = "rise" | "fade" | "draw" | "grow";
+/** Attributes the runtime reads: entrance kind, stagger step and focus keys. */
+export declare const animAttrs: (kind: AnimKind, step: number, focusKeys?: string) => string;

package/dist/html.js

@@ -0,0 +1,14 @@
+const ESCAPES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/** Escapes text for element content and double- or single-quoted attributes. */
+export const esc = (text) => text.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+/** Attributes the runtime reads: entrance kind, stagger step and focus keys. */
+export const animAttrs = (kind, step, focusKeys = "") => {
+    const keys = focusKeys ? ` data-focus-key="${esc(focusKeys)}"` : "";
+    return `data-anim="${kind}" data-step="${step}"${keys}`;
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { type FieldDoc, type SceneDoc, sceneDocs } from "./catalog.ts";
+export { CUSTOM_SCENE_TYPE, type CustomSceneFile, type CustomSceneSource, emitCustomScene, HELPER_LIMITS, type RelativeClosure, type RelativeImportScan, readRelativeClosure, resolveSceneDir, type SceneDirResult, scanRelativeImports, scanVendorImports, type VendorScan, } from "./custom.ts";
+export { esc } from "./html.ts";
+export { getScene, sceneRegistry, sceneTypes } from "./registry.ts";
+export { runtimeFiles } from "./runtime-files.ts";
+export { type FlowReport, inspectFlow } from "./scenes/flow/inspect.ts";
+export { collectIcons, iconLedgerRows, LUCIDE_LICENCE_TEXT } from "./shared/icon.ts";
+export { iconGroups, listIcons, searchIconNames } from "./shared/icon-search.ts";
+export { textWidth } from "./shared/measure.ts";
+export { sceneSourceHash } from "./source-hash.ts";
+export { sceneWords } from "./words.ts";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { sceneDocs } from "./catalog.js";
+export { CUSTOM_SCENE_TYPE, emitCustomScene, HELPER_LIMITS, readRelativeClosure, resolveSceneDir, scanRelativeImports, scanVendorImports, } from "./custom.js";
+export { esc } from "./html.js";
+export { getScene, sceneRegistry, sceneTypes } from "./registry.js";
+export { runtimeFiles } from "./runtime-files.js";
+export { inspectFlow } from "./scenes/flow/inspect.js";
+export { collectIcons, iconLedgerRows, LUCIDE_LICENCE_TEXT } from "./shared/icon.js";
+export { iconGroups, listIcons, searchIconNames } from "./shared/icon-search.js";
+export { textWidth } from "./shared/measure.js";
+export { sceneSourceHash } from "./source-hash.js";
+export { sceneWords } from "./words.js";

package/dist/position.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const CORNERS: readonly ["top-left", "top-right", "bottom-left", "bottom-right"];
+export declare const POSITIONS: readonly ["top-left", "top-right", "bottom-left", "bottom-right", "center"];
+export declare const cornerSchema: z.ZodEnum<{
+    "bottom-left": "bottom-left";
+    "bottom-right": "bottom-right";
+    "top-left": "top-left";
+    "top-right": "top-right";
+}>;
+export declare const positionSchema: z.ZodEnum<{
+    "bottom-left": "bottom-left";
+    "bottom-right": "bottom-right";
+    center: "center";
+    "top-left": "top-left";
+    "top-right": "top-right";
+}>;
+export type Position = (typeof POSITIONS)[number];
+/** Class that places a child of an overlay root (a flex column inside the safe margin). */
+export declare const positionClass: (position: Position) => string;
+/** Placement rules for the `mk-pos-*` classes, scoped to the scene root. */
+export declare const positionCss: (root: string) => string;

package/dist/position.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export const CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"];
+export const POSITIONS = [...CORNERS, "center"];
+export const cornerSchema = z.enum(CORNERS);
+export const positionSchema = z.enum(POSITIONS);
+/** Class that places a child of an overlay root (a flex column inside the safe margin). */
+export const positionClass = (position) => `mk-pos-${position}`;
+/** Placement rules for the `mk-pos-*` classes, scoped to the scene root. */
+export const positionCss = (root) => [
+    `${root} .mk-pos-top-left { align-self: flex-start; margin-bottom: auto; }`,
+    `${root} .mk-pos-top-right { align-self: flex-end; margin-bottom: auto; }`,
+    `${root} .mk-pos-bottom-left { align-self: flex-start; margin-top: auto; }`,
+    `${root} .mk-pos-bottom-right { align-self: flex-end; margin-top: auto; }`,
+    `${root} .mk-pos-center { align-self: center; margin-block: auto; }`,
+    "",
+].join("\n");

package/dist/registry.d.ts

@@ -0,0 +1,4 @@
+import type { ScenePlugin } from "@anvpx/motion-schema";
+export declare const sceneRegistry: ReadonlyMap<string, ScenePlugin>;
+export declare const sceneTypes: readonly string[];
+export declare const getScene: (type: string) => ScenePlugin;