@onmark/cli 0.1.3

package/packages/bundler/dist/src/authored_html.js

@@ -0,0 +1,387 @@
+// Bounded HTML ingestion and exact motion-module extraction.
+// Parsing identifies source ranges; publication preserves all other bytes.
+import { open } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { parse } from "parse5";
+import { freezeHtmlImages } from "./html_image.js";
+const MAX_HTML_BYTES = 8 * 1024 * 1024;
+const MOTION_ATTRIBUTE = "data-om-motion";
+const RUNTIME_SCRIPT = '<script type="module" src="./presentation.js"></script>';
+/** Invalid or unreadable authored HTML at the Node bundling boundary. */
+export class AuthoredHtmlError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AuthoredHtmlError";
+    }
+}
+/** Reads one bounded UTF-8 document and isolates its motion module. */
+export async function readAuthoredHtml(path, maxOutputBytes, resolveDirectory) {
+    const absolute = resolve(path);
+    const source = await readBoundedSource(absolute);
+    const directory = resolveDirectory === undefined
+        ? dirname(absolute)
+        : resolve(resolveDirectory);
+    const browserSource = projectBrowserDocument(source);
+    const frozen = await freezeHtmlImages(browserSource, directory, maxOutputBytes);
+    const extracted = extractMotion(frozen.document);
+    return Object.freeze({
+        ...extracted,
+        resources: frozen.resources,
+        resolveDirectory: directory,
+    });
+}
+// ── Bounded input
+async function readBoundedSource(path) {
+    let file;
+    try {
+        file = await open(path, "r");
+    }
+    catch (error) {
+        throw new AuthoredHtmlError(`cannot open authored HTML ${path}`, {
+            cause: error,
+        });
+    }
+    try {
+        const bytes = Buffer.allocUnsafe(MAX_HTML_BYTES + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const { bytesRead } = await file.read(bytes, length, bytes.length - length, length);
+            if (bytesRead === 0) {
+                break;
+            }
+            length += bytesRead;
+        }
+        if (length > MAX_HTML_BYTES) {
+            throw new AuthoredHtmlError(`authored HTML exceeds the ${MAX_HTML_BYTES}-byte limit`);
+        }
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+    }
+    catch (error) {
+        if (error instanceof AuthoredHtmlError) {
+            throw error;
+        }
+        throw new AuthoredHtmlError(`cannot read authored HTML ${path}`, {
+            cause: error,
+        });
+    }
+    finally {
+        await file.close();
+    }
+}
+function extractMotion(source) {
+    // Reparse after each source edit because parse5 offsets are not transferable.
+    // The final tree owns runtime insertion and projected shot ranges.
+    const installed = installRuntime(source);
+    const projection = projectShotStructure(installed.document);
+    return {
+        ...installed,
+        ...projection,
+    };
+}
+function projectBrowserDocument(source) {
+    const document = parseDocument(source);
+    const edits = [];
+    collectCompilerFacts(document, source, edits);
+    return removeRanges(source, edits);
+}
+function installRuntime(source) {
+    const document = parseDocument(source);
+    const scripts = collectScripts(document);
+    const motion = scripts.filter(isMotionScript);
+    const unsupported = scripts.filter((script) => !isMotionScript(script));
+    if (unsupported.length > 0) {
+        throw new AuthoredHtmlError('authored HTML scripts must use type="module" and data-om-motion');
+    }
+    if (motion.length > 1) {
+        throw new AuthoredHtmlError("authored HTML may contain at most one motion module");
+    }
+    const script = motion[0];
+    if (script === undefined) {
+        return insertRuntimeScript(source, document);
+    }
+    const location = script.sourceCodeLocation;
+    const startTag = location?.startTag;
+    const endTag = location?.endTag;
+    if (location == null || startTag === undefined || endTag === undefined) {
+        throw new AuthoredHtmlError("the motion module must have explicit opening and closing tags");
+    }
+    const motionSource = source.slice(startTag.endOffset, endTag.startOffset);
+    const browserSource = removeRanges(source, [
+        { end: location.endOffset, start: location.startOffset },
+    ]);
+    return {
+        ...insertRuntimeScript(browserSource, parseDocument(browserSource)),
+        motion: motionSource,
+    };
+}
+function projectShotStructure(source) {
+    const document = parseDocument(source);
+    const film = findElement(document, "om-film");
+    if (film === undefined) {
+        return {
+            regions: Object.freeze([]),
+            regionStructure: Object.freeze({ scenes: Object.freeze([]) }),
+        };
+    }
+    const scenes = childElements(film, "om-scene").map((scene) => {
+        const shots = childElements(scene, "om-shot").map((shot) => removableElementRange(source, shot));
+        return Object.freeze({
+            range: removableElementRange(source, scene),
+            shots: Object.freeze(shots),
+        });
+    });
+    const regions = scenes.flatMap((scene, sceneIndex) => scene.shots.map((_, shotIndex) => Object.freeze({ scene: sceneIndex, shot: shotIndex })));
+    return {
+        regions: Object.freeze(regions),
+        regionStructure: Object.freeze({ scenes: Object.freeze(scenes) }),
+    };
+}
+/** Materializes one shot projection without retaining every projected document. */
+export function projectShotDocument(html, region) {
+    const selectedScene = html.regionStructure.scenes[region.scene];
+    const selectedShot = selectedScene?.shots[region.shot];
+    if (selectedScene === undefined || selectedShot === undefined) {
+        throw new AuthoredHtmlError("browser projection selects an unknown shot");
+    }
+    const ranges = [];
+    for (const [sceneIndex, scene] of html.regionStructure.scenes.entries()) {
+        if (sceneIndex !== region.scene) {
+            ranges.push(scene.range);
+            continue;
+        }
+        for (const [shotIndex, shot] of scene.shots.entries()) {
+            if (shotIndex !== region.shot) {
+                ranges.push(shot);
+            }
+        }
+    }
+    return Object.freeze({
+        document: removeRanges(html.document, ranges),
+        runtimeOffset: projectOffset(html.runtimeOffset, ranges),
+    });
+}
+function parseDocument(source) {
+    const errors = [];
+    const document = parse(source, {
+        onParseError(error) {
+            if (error.code !== "missing-doctype") {
+                errors.push(error);
+            }
+        },
+        sourceCodeLocationInfo: true,
+    });
+    if (errors.length > 0) {
+        throw new AuthoredHtmlError(`authored HTML cannot be bundled after parse error ${errors[0].code}`);
+    }
+    return document;
+}
+function insertRuntimeScript(source, document) {
+    const body = findElement(document, "body");
+    const endTag = body?.sourceCodeLocation?.endTag;
+    if (endTag === undefined) {
+        return {
+            document: `${source}\n${RUNTIME_SCRIPT}`,
+            motion: undefined,
+            runtimeOffset: source.length + 1,
+        };
+    }
+    const lineStart = source.lastIndexOf("\n", endTag.startOffset - 1) + 1;
+    const indentation = source.slice(lineStart, endTag.startOffset);
+    if (indentation.trim().length === 0) {
+        const before = source.slice(0, lineStart);
+        const after = source.slice(lineStart);
+        const prefix = `${before}${indentation}  `;
+        return {
+            document: `${prefix}${RUNTIME_SCRIPT}\n${after}`,
+            motion: undefined,
+            runtimeOffset: prefix.length,
+        };
+    }
+    const before = source.slice(0, endTag.startOffset);
+    const after = source.slice(endTag.startOffset);
+    return {
+        document: `${before}\n${RUNTIME_SCRIPT}\n${after}`,
+        motion: undefined,
+        runtimeOffset: before.length + 1,
+    };
+}
+// ── Parsed-tree queries
+function collectScripts(node) {
+    const scripts = [];
+    visit(node, (element) => {
+        if (element.tagName === "script") {
+            scripts.push(element);
+        }
+    });
+    return scripts;
+}
+function findElement(node, name) {
+    const pending = [node];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined) {
+            break;
+        }
+        if ("tagName" in current && current.tagName === name) {
+            return current;
+        }
+        if ("childNodes" in current) {
+            pushChildren(pending, current.childNodes);
+        }
+    }
+    return undefined;
+}
+function childElements(parent, name) {
+    return parent.childNodes.filter((child) => "tagName" in child && child.tagName === name);
+}
+function visit(node, visitor) {
+    const pending = [node];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined) {
+            break;
+        }
+        if ("tagName" in current) {
+            visitor(current);
+        }
+        if ("childNodes" in current) {
+            pushChildren(pending, current.childNodes);
+        }
+    }
+}
+function pushChildren(pending, children) {
+    for (let index = children.length - 1; index >= 0; index -= 1) {
+        const child = children[index];
+        if (child !== undefined) {
+            pending.push(child);
+        }
+    }
+}
+function isMotionScript(element) {
+    const attributes = new Map(element.attrs.map(({ name, value }) => [name, value]));
+    return (attributes.get("type") === "module" &&
+        attributes.has(MOTION_ATTRIBUTE) &&
+        !attributes.has("src"));
+}
+function projectOffset(offset, ranges) {
+    let projected = offset;
+    for (const range of ranges) {
+        if (range.start < offset && offset < range.end) {
+            throw new AuthoredHtmlError("browser projection cannot remove its runtime entry");
+        }
+        if (range.end <= offset) {
+            projected -= range.end - range.start;
+        }
+    }
+    return projected;
+}
+function collectCompilerFacts(node, source, ranges) {
+    const pending = [node];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined) {
+            break;
+        }
+        if ("tagName" in current) {
+            if (isCompilerOnlyElement(current.tagName)) {
+                ranges.push(removableElementRange(source, current));
+                continue;
+            }
+            collectCompilerAttributes(current, source, ranges);
+        }
+        if ("childNodes" in current) {
+            pushChildren(pending, current.childNodes);
+        }
+    }
+}
+function collectCompilerAttributes(element, source, ranges) {
+    for (const attribute of element.attrs) {
+        if (!isCompilerOnlyAttribute(element.tagName, attribute.name)) {
+            continue;
+        }
+        const location = element.sourceCodeLocation?.attrs?.[attribute.name];
+        if (location === undefined) {
+            throw new AuthoredHtmlError(`browser projection cannot locate ${attribute.name} on <${element.tagName}>`);
+        }
+        ranges.push(attributeRange(source, location));
+    }
+}
+function attributeRange(source, location) {
+    let start = location.startOffset;
+    while (start > 0 && isHtmlSpace(source[start - 1])) {
+        start -= 1;
+    }
+    return { end: location.endOffset, start };
+}
+function isCompilerOnlyElement(tagName) {
+    // This closed list mirrors the language boundary, not HTML vocabulary.
+    // New spellings require the Rust compiler, specification, and identity
+    // conformance to change together before they may disappear from the browser.
+    return (tagName === "om-cues" ||
+        tagName === "om-music" ||
+        tagName === "om-sfx" ||
+        tagName === "om-vo");
+}
+function isCompilerOnlyAttribute(tagName, attributeName) {
+    switch (tagName) {
+        case "om-cta":
+        case "om-title":
+            return attributeName === "cue" || attributeName === "delay";
+        case "om-shot":
+            return attributeName === "duration";
+        case "video":
+            return attributeName === "delay" || attributeName === "src";
+        default:
+            return false;
+    }
+}
+function isHtmlSpace(character) {
+    return (character === "\t" ||
+        character === "\n" ||
+        character === "\f" ||
+        character === "\r" ||
+        character === " ");
+}
+function elementRange(element) {
+    const location = element.sourceCodeLocation;
+    if (location == null) {
+        throw new AuthoredHtmlError(`browser projection cannot locate <${element.tagName}>`);
+    }
+    return { end: location.endOffset, start: location.startOffset };
+}
+function removableElementRange(source, element) {
+    const range = elementRange(element);
+    // Indentation on an otherwise empty line belongs to the removed element.
+    // Retaining it creates a browser text node and invalid source artifacts.
+    const lineStart = source.lastIndexOf("\n", range.start - 1) + 1;
+    const newline = source.indexOf("\n", range.end);
+    const lineEnd = newline === -1 ? source.length : newline + 1;
+    const leading = source.slice(lineStart, range.start);
+    const trailing = source.slice(range.end, lineEnd);
+    if (isHtmlWhitespace(leading) && isHtmlWhitespace(trailing)) {
+        return { end: lineEnd, start: lineStart };
+    }
+    return range;
+}
+function isHtmlWhitespace(value) {
+    for (const character of value) {
+        if (!isHtmlSpace(character)) {
+            return false;
+        }
+    }
+    return true;
+}
+function removeRanges(source, ranges) {
+    const ordered = ranges.toSorted((left, right) => left.start - right.start);
+    const parts = [];
+    let cursor = 0;
+    for (const range of ordered) {
+        if (range.start < cursor || range.end < range.start) {
+            throw new AuthoredHtmlError("browser projection ranges overlap");
+        }
+        parts.push(source.slice(cursor, range.start));
+        cursor = range.end;
+    }
+    parts.push(source.slice(cursor));
+    return parts.join("");
+}

package/packages/bundler/dist/src/command.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/packages/bundler/dist/src/command.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// Executable boundary for one bounded presentation build.
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { BundleError, bundlePresentation, } from "./presentation.js";
+import { BUNDLE_FRAME_BEHAVIORS, BUNDLE_TEMPORAL_CAPABILITIES, BUNDLE_VISUAL_CAPABILITIES, } from "./generated/bundle-manifest.js";
+const USAGE = [
+    "Usage: onmark-bundle",
+    "  --html <path>",
+    "  [--resolve-directory <directory>]",
+    "  --output <directory>",
+    "  --max-output-bytes <bytes>",
+    "  --frame-behavior <perFrame|placementBounded>",
+    "  --temporal-capability <sequential|randomAccess>",
+    "  --visual-capability <browserComposite|separableOverlay>",
+    "",
+].join("\n");
+// ── Execution ──
+try {
+    const command = parseArguments(process.argv.slice(2));
+    if (command.kind === "help") {
+        process.stdout.write(USAGE);
+    }
+    else {
+        await bundlePresentation(command.options);
+    }
+}
+catch (error) {
+    const failure = commandFailure(error);
+    process.stderr.write(`${failure.kind}: ${failure.message}\n`);
+    process.exitCode = failure.kind === "configuration" ? 2 : 1;
+}
+// ── Arguments ──
+function parseArguments(arguments_) {
+    const values = commandValues(arguments_);
+    if (values.help !== undefined) {
+        if (arguments_.length !== 1) {
+            throw configuration("--help cannot be combined with bundle options");
+        }
+        return { kind: "help" };
+    }
+    const outputDirectory = oneValue(values.output, "--output");
+    const maxOutputBytes = parseByteLimit(oneValue(values["max-output-bytes"], "--max-output-bytes"));
+    const frameBehavior = parseFrameBehavior(oneValue(values["frame-behavior"], "--frame-behavior"));
+    const temporalCapability = parseTemporalCapability(oneValue(values["temporal-capability"], "--temporal-capability"));
+    const visualCapability = parseVisualCapability(oneValue(values["visual-capability"], "--visual-capability"));
+    const controls = {
+        frameBehavior,
+        maxOutputBytes,
+        outputDirectory,
+        temporalCapability,
+        visualCapability,
+    };
+    return {
+        kind: "bundle",
+        options: {
+            ...controls,
+            document: oneValue(values.html, "--html"),
+            ...optionalResolveDirectory(values["resolve-directory"]),
+        },
+    };
+}
+function commandValues(arguments_) {
+    try {
+        return parseArgs({
+            args: arguments_,
+            allowPositionals: false,
+            options: {
+                "frame-behavior": { type: "string", multiple: true },
+                help: { type: "boolean" },
+                html: { type: "string", multiple: true },
+                "max-output-bytes": { type: "string", multiple: true },
+                output: { type: "string", multiple: true },
+                "resolve-directory": { type: "string", multiple: true },
+                "temporal-capability": { type: "string", multiple: true },
+                "visual-capability": { type: "string", multiple: true },
+            },
+            strict: true,
+        }).values;
+    }
+    catch (error) {
+        throw configuration("arguments are invalid", error);
+    }
+}
+function optionalResolveDirectory(values) {
+    if (values === undefined) {
+        return {};
+    }
+    return { resolveDirectory: oneValue(values, "--resolve-directory") };
+}
+function parseTemporalCapability(value) {
+    const capability = BUNDLE_TEMPORAL_CAPABILITIES.find((candidate) => candidate === value);
+    if (capability !== undefined) {
+        return capability;
+    }
+    throw configuration("--temporal-capability must be sequential or randomAccess");
+}
+function parseVisualCapability(value) {
+    const capability = BUNDLE_VISUAL_CAPABILITIES.find((candidate) => candidate === value);
+    if (capability !== undefined) {
+        return capability;
+    }
+    throw configuration("--visual-capability must be browserComposite or separableOverlay");
+}
+function parseFrameBehavior(value) {
+    const behavior = BUNDLE_FRAME_BEHAVIORS.find((candidate) => candidate === value);
+    if (behavior !== undefined) {
+        return behavior;
+    }
+    throw configuration("--frame-behavior must be perFrame or placementBounded");
+}
+function oneValue(values, name) {
+    const value = values?.[0];
+    if (value === undefined) {
+        throw configuration(`${name} is required`);
+    }
+    if (values !== undefined && values.length > 1) {
+        throw configuration(`${name} cannot be repeated`);
+    }
+    return value;
+}
+function parseByteLimit(value) {
+    const bytes = Number(value);
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+        throw configuration("--max-output-bytes must be a positive safe integer");
+    }
+    return bytes;
+}
+// ── Failures ──
+function configuration(message, cause) {
+    return new BundleError("configuration", message, cause);
+}
+function commandFailure(error) {
+    if (error instanceof BundleError) {
+        return error;
+    }
+    return new BundleError("output", "unexpected bundler failure", error);
+}

package/packages/bundler/dist/src/generated/bundle-manifest.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Semantic DOM extent present in one immutable browser artifact.
+ */
+export type PresentationDocumentScope = "wholeFilm" | "renderRegion";
+/**
+ * Proven cadence at which browser-owned pixels may change.
+ *
+ * Unknown presentation code requires `PerFrame`. Placement-bounded pixels may
+ * change only when the browser plan changes its active structural placements,
+ * so execution may reuse one exact capture between those boundaries.
+ */
+export type PresentationFrameBehavior = "perFrame" | "placementBounded";
+/**
+ * Proven relationship between a presentation's output and requested frames.
+ *
+ * Unknown presentation code requires `Sequential`. Random access is an
+ * explicit claim that each requested frame depends only on immutable inputs
+ * and that exact frame.
+ */
+export type PresentationTemporalCapability = "sequential" | "randomAccess";
+/**
+ * Version of the immutable presentation-bundle contract.
+ */
+export type BundleVersion = 1;
+/**
+ * Proven relationship between browser presentation pixels and primary media.
+ *
+ * Unknown presentation code requires `BrowserComposite`. A separable overlay
+ * is an explicit claim that the browser output is a transparent foreground
+ * independent of the primary video beneath it.
+ */
+export type PresentationVisualCapability = "browserComposite" | "separableOverlay";
+/**
+ * Stable description of one immutable presentation artifact.
+ */
+export interface BundleManifest {
+    bundleId: string;
+    documentScope: PresentationDocumentScope;
+    entryPoint: "index.html";
+    /**
+     * @minItems 1
+     * @maxItems 99999
+     */
+    files: [BundleFile, ...BundleFile[]];
+    frameBehavior: PresentationFrameBehavior;
+    temporalCapability: PresentationTemporalCapability;
+    version: BundleVersion;
+    visualCapability: PresentationVisualCapability;
+}
+/**
+ * One content-addressed presentation payload file.
+ */
+export interface BundleFile {
+    bytes: number;
+    path: string;
+    sha256: string;
+}
+export declare const BUNDLE_VERSION: 1;
+export declare const BUNDLE_TEMPORAL_CAPABILITIES: readonly ["sequential", "randomAccess"];
+export declare const BUNDLE_VISUAL_CAPABILITIES: readonly ["browserComposite", "separableOverlay"];
+export declare const BUNDLE_FRAME_BEHAVIORS: readonly ["perFrame", "placementBounded"];
+export declare const BUNDLE_ENTRY_POINT: "index.html";
+export declare const BUNDLE_MANIFEST_FILE: "manifest.json";
+export declare const BUNDLE_ASSET_DIRECTORY: "assets/sha256";
+export declare const BUNDLE_REGION_DIRECTORY: "regions";

package/packages/bundler/dist/src/generated/bundle-manifest.js

@@ -0,0 +1,18 @@
+// Generated by `cargo xtask schema`; edit Rust protocol types instead.
+export const BUNDLE_VERSION = 1;
+export const BUNDLE_TEMPORAL_CAPABILITIES = Object.freeze([
+    "sequential",
+    "randomAccess",
+]);
+export const BUNDLE_VISUAL_CAPABILITIES = Object.freeze([
+    "browserComposite",
+    "separableOverlay",
+]);
+export const BUNDLE_FRAME_BEHAVIORS = Object.freeze([
+    "perFrame",
+    "placementBounded",
+]);
+export const BUNDLE_ENTRY_POINT = "index.html";
+export const BUNDLE_MANIFEST_FILE = "manifest.json";
+export const BUNDLE_ASSET_DIRECTORY = "assets/sha256";
+export const BUNDLE_REGION_DIRECTORY = "regions";

package/packages/bundler/dist/src/html_image.d.ts

@@ -0,0 +1,20 @@
+/** One local image frozen into the presentation artifact. */
+export interface HtmlImageResource {
+    readonly contents: Uint8Array;
+    readonly path: string;
+}
+/** Invalid or unreadable native image input. */
+export declare class HtmlImageError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Native image bytes exceed the bounded presentation artifact. */
+export declare class HtmlImageLimitError extends HtmlImageError {
+    constructor();
+}
+/** Freezes local `img[src]` bytes and rewrites their authored references. */
+export declare function freezeHtmlImages(source: string, directory: string, maxOutputBytes: number): Promise<{
+    readonly document: string;
+    readonly resources: readonly HtmlImageResource[];
+}>;
+/** Selects only frozen images referenced by one projected document. */
+export declare function projectedImageResources(document: string, resources: readonly HtmlImageResource[]): readonly HtmlImageResource[];