@onmark/cli 0.3.0 → 0.5.0

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

@@ -9,6 +9,7 @@ const ELEMENTS = Object.freeze({
     scene: "om-scene",
     shot: "om-shot",
     title: "om-title",
+    transition: "om-transition",
     video: "video",
 });
 // Whole-film artifacts may contain semantic nodes absent from a projected
@@ -17,6 +18,7 @@ const VISIBILITY_RULE = [
     "[data-om-node][hidden],",
     "om-film > om-scene:not([data-om-node]),",
     "om-scene > om-shot:not([data-om-node]),",
+    "om-scene > om-transition,",
     "om-shot > :is(video, om-title, om-cta):not([data-om-node]) {",
     "  display: none !important;",
     "}",
@@ -32,6 +34,7 @@ export function createDomPresentationBindings(options) {
         bindFilm: document.bindFilm.bind(document),
         bindScene: document.bindScene.bind(document),
         bindShot: document.bindShot.bind(document),
+        bindTransition: document.bindTransition.bind(document),
         bindVideo: document.bindVideo.bind(document),
         bindOverlay: document.bindOverlay.bind(document),
         async bindExtensions(plan) {
@@ -87,15 +90,31 @@ class AuthoredDocument {
     }
     bindVideo(placement) {
         const element = requiredNode(this.#nodeIndex(), placement.node, "video", ELEMENTS.video);
-        const bound = bindElement(element, placement.node);
         element.muted = true;
         element.playsInline = true;
         this.#record("video", element, placement.node, placement.interval);
-        return {
-            ...bound,
+        return bindVideoElement(element, placement.node, this.#videoSource(placement));
+    }
+    bindTransition(placement) {
+        const nodes = this.#nodeIndex();
+        const element = requiredNode(nodes, placement.node, "transition", ELEMENTS.transition);
+        const outgoingElement = requiredNodeId(nodes, placement.outgoingShotId, "outgoing shot", ELEMENTS.shot);
+        const incomingElement = requiredNodeId(nodes, placement.incomingShotId, "incoming shot", ELEMENTS.shot);
+        const bound = bindElement(element, placement.node);
+        this.#targets.push(Object.freeze({
+            element,
+            incomingElement,
+            interval: placement.interval,
+            kind: "transition",
+            node: placement.node,
+            outgoingElement,
+        }));
+        return Object.freeze({
+            dispose: bound.dispose,
             element,
-            source: this.#videoSource(placement),
-        };
+            incomingElement,
+            outgoingElement,
+        });
     }
     bindOverlay(placement) {
         if (placement.kind === "caption") {
@@ -157,7 +176,13 @@ function collectAuthoredNodes(document, plan) {
     const browserVideoShots = new Set(plan.videos.map(({ shotId }) => shotId));
     for (const scene of semanticChildren(film, ELEMENTS.scene)) {
         indexed.push(scene);
-        for (const shot of semanticChildren(scene, ELEMENTS.shot)) {
+        const structure = semanticChildren(scene, `${ELEMENTS.shot}, ${ELEMENTS.transition}`);
+        for (const element of structure) {
+            if (element.matches(ELEMENTS.transition)) {
+                indexed.push(element);
+                continue;
+            }
+            const shot = element;
             indexed.push(shot);
             // Browser Plans assign dense semantic preorder IDs. The shot just
             // admitted is therefore the parent ID carried by projected videos.
@@ -170,6 +195,9 @@ function collectAuthoredNodes(document, plan) {
     }
     return Object.freeze({ film, elements: Object.freeze(indexed) });
 }
+function requiredNodeId(nodes, nodeId, role, selector) {
+    return requiredNode(nodes, { nodeId }, role, selector);
+}
 function requiredNode(nodes, node, role, selector) {
     const element = nodes.elements[node.nodeId];
     if (element === undefined) {
@@ -205,6 +233,132 @@ function bindElement(element, node, release) {
         },
     };
 }
+function bindVideoElement(element, node, source) {
+    const bound = bindElement(element, node);
+    const authoredVisibility = element.style.visibility;
+    let layoutVisible = false;
+    return {
+        element,
+        source,
+        setVisible: bound.setVisible,
+        setLayoutVisible(visible) {
+            if (visible) {
+                element.style.visibility = "hidden";
+                bound.setVisible(true);
+            }
+            else {
+                bound.setVisible(false);
+                element.style.visibility = authoredVisibility;
+            }
+            layoutVisible = visible;
+        },
+        measureLayout() {
+            if (!layoutVisible) {
+                throw new Error("video layout requires a visible layout-only element");
+            }
+            return measureVideoLayout(element, node.nodeId);
+        },
+        dispose() {
+            bound.setVisible(false);
+            element.style.visibility = authoredVisibility;
+            bound.dispose();
+        },
+    };
+}
+function measureVideoLayout(element, nodeId) {
+    requireStaticVideoStyle(element);
+    const rectangle = pixelRectangle(element.getBoundingClientRect());
+    const style = getComputedStyle(element);
+    return Object.freeze({
+        nodeId,
+        objectFit: objectFit(style.objectFit),
+        objectPosition: objectPosition(style.objectPosition),
+        rectangle,
+    });
+}
+function requireStaticVideoStyle(element) {
+    const style = getComputedStyle(element);
+    const unsupported = [
+        ["border-radius", style.borderRadius, "0px"],
+        ["filter", style.filter, "none"],
+        ["mix-blend-mode", style.mixBlendMode, "normal"],
+        ["opacity", style.opacity, "1"],
+        ["transform", style.transform, "none"],
+    ];
+    for (const [name, actual, expected] of unsupported) {
+        if (actual !== expected) {
+            throw new Error(`layout-only video requires ${name}: ${expected}, found ${actual}`);
+        }
+    }
+    for (const name of [
+        "borderBottomWidth",
+        "borderLeftWidth",
+        "borderRightWidth",
+        "borderTopWidth",
+        "paddingBottom",
+        "paddingLeft",
+        "paddingRight",
+        "paddingTop",
+    ]) {
+        if (style[name] !== "0px") {
+            throw new Error(`layout-only video requires ${cssName(name)}: 0`);
+        }
+    }
+    if (style.clipPath !== "none") {
+        throw new Error("layout-only video requires clip-path: none");
+    }
+}
+function pixelRectangle(rectangle) {
+    const values = [rectangle.x, rectangle.y, rectangle.width, rectangle.height];
+    if (devicePixelRatio !== 1 ||
+        !values.every(Number.isSafeInteger) ||
+        rectangle.x < 0 ||
+        rectangle.y < 0 ||
+        rectangle.width <= 0 ||
+        rectangle.height <= 0 ||
+        rectangle.right > document.documentElement.clientWidth ||
+        rectangle.bottom > document.documentElement.clientHeight) {
+        throw new Error("layout-only video requires a positive, pixel-aligned viewport rectangle");
+    }
+    return Object.freeze({
+        height: rectangle.height,
+        width: rectangle.width,
+        x: rectangle.x,
+        y: rectangle.y,
+    });
+}
+function objectFit(value) {
+    if (value === "fill" || value === "contain" || value === "cover") {
+        return value;
+    }
+    throw new Error(`layout-only video does not support object-fit: ${value}`);
+}
+function objectPosition(value) {
+    const [x, y, ...rest] = value.trim().split(/\s+/u);
+    if (x === undefined || y === undefined || rest.length > 0) {
+        throw new Error("layout-only video requires two percentage positions");
+    }
+    return Object.freeze({
+        x: percentageMillionths(x),
+        y: percentageMillionths(y),
+    });
+}
+function percentageMillionths(value) {
+    const match = /^(?<whole>[0-9]{1,3})(?:\.(?<fraction>[0-9]{1,4}))?%$/u.exec(value);
+    if (match?.groups === undefined) {
+        throw new Error("layout-only video object-position must use exact percentages");
+    }
+    const whole = Number(match.groups["whole"]);
+    const fraction = Number((match.groups["fraction"] ?? "").padEnd(4, "0"));
+    const millionths = whole * 10_000 + fraction;
+    if (millionths > 1_000_000) {
+        throw new Error("layout-only video object-position must lie between 0% and 100%");
+    }
+    return millionths;
+}
+function cssName(value) {
+    return value.replace(/[A-Z]/gu, (character) => `-${character.toLowerCase()}`);
+}
 function requireAuthoredId(element, node) {
     const expected = node.authoredId ?? "";
     if (element.id !== expected) {

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

@@ -1 +1 @@
-export type { PresentationExtension, PresentationExtensionContext, PresentationTarget, PresentationTargetKind, } from "./motion.js";
+export type { PresentationExtension, PresentationExtensionContext, PresentationElementTarget, PresentationElementTargetKind, PresentationTarget, PresentationTargetKind, PresentationTransitionTarget, } from "./motion.js";

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

@@ -1,16 +1,18 @@
+import type { PresentationVisualCapability } from "../../../runtime/dist/src/index.js";
 import { type HtmlImageResource } from "./html_image.js";
 /** Authored document bytes and optional inline module prepared for esbuild. */
 export interface AuthoredHtml {
     readonly document: string;
     readonly motion: string | undefined;
+    readonly visualCapability: PresentationVisualCapability | undefined;
     readonly resources: readonly HtmlImageResource[];
-    readonly regions: readonly AuthoredHtmlRegion[];
+    readonly shots: readonly AuthoredHtmlShot[];
     readonly regionStructure: AuthoredHtmlRegionStructure;
     readonly resolveDirectory: string;
     readonly runtimeOffset: number;
 }
-/** One shot selection within the shared authored-document structure. */
-export interface AuthoredHtmlRegion {
+/** One dense screenplay-order shot within the authored document. */
+export interface AuthoredHtmlShot {
     readonly scene: number;
     readonly shot: number;
 }
@@ -20,9 +22,19 @@ export interface AuthoredHtmlRegionStructure {
 }
 export interface AuthoredHtmlScene {
     readonly range: SourceRange;
-    readonly shots: readonly SourceRange[];
+    readonly shots: readonly AuthoredHtmlShotRange[];
+    readonly transitions: readonly AuthoredHtmlTransitionRange[];
 }
-/** One materialized shot-scoped browser document. */
+export interface AuthoredHtmlShotRange {
+    readonly index: number;
+    readonly range: SourceRange;
+}
+export interface AuthoredHtmlTransitionRange {
+    readonly incomingShot: number;
+    readonly outgoingShot: number;
+    readonly range: SourceRange;
+}
+/** One materialized render-region browser document. */
 export interface AuthoredHtmlRegionDocument {
     readonly document: string;
     readonly runtimeOffset: number;
@@ -33,8 +45,8 @@ export declare class AuthoredHtmlError extends Error {
 }
 /** Reads one bounded UTF-8 document and isolates its motion module. */
 export declare function readAuthoredHtml(path: string, maxOutputBytes: number, resolveDirectory?: string): Promise<AuthoredHtml>;
-/** Materializes one shot projection without retaining every projected document. */
-export declare function projectShotDocument(html: AuthoredHtml, region: AuthoredHtmlRegion): AuthoredHtmlRegionDocument;
+/** Materializes one Rust-planned region without retaining every projection. */
+export declare function projectRegionDocument(html: AuthoredHtml, shotIndices: readonly number[]): AuthoredHtmlRegionDocument;
 export interface SourceRange {
     readonly end: number;
     readonly start: number;

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

@@ -6,6 +6,7 @@ import { parse } from "parse5";
 import { freezeHtmlImages } from "./html_image.js";
 const MAX_HTML_BYTES = 8 * 1024 * 1024;
 const MOTION_ATTRIBUTE = "data-om-motion";
+const VISUAL_CAPABILITY_META = "onmark:visual-capability";
 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 {
@@ -18,6 +19,7 @@ export class AuthoredHtmlError extends Error {
 export async function readAuthoredHtml(path, maxOutputBytes, resolveDirectory) {
     const absolute = resolve(path);
     const source = await readBoundedSource(absolute);
+    const visualCapability = declaredVisualCapability(parseDocument(source));
     const directory = resolveDirectory === undefined
         ? dirname(absolute)
         : resolve(resolveDirectory);
@@ -28,6 +30,7 @@ export async function readAuthoredHtml(path, maxOutputBytes, resolveDirectory) {
         ...extracted,
         resources: frozen.resources,
         resolveDirectory: directory,
+        visualCapability,
     });
 }
 // ── Bounded input
@@ -119,39 +122,81 @@ function projectShotStructure(source) {
     const film = findElement(document, "om-film");
     if (film === undefined) {
         return {
-            regions: Object.freeze([]),
+            shots: 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 })));
+    const shots = [];
+    const scenes = childElements(film, "om-scene").map((scene, sceneIndex) => projectSceneStructure(source, scene, sceneIndex, shots));
     return {
-        regions: Object.freeze(regions),
+        shots: Object.freeze(shots),
         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");
+function projectSceneStructure(source, scene, sceneIndex, documentShots) {
+    const shots = [];
+    const transitions = [];
+    let outgoingShot;
+    let pendingTransition;
+    for (const element of directElements(scene)) {
+        if (element.tagName === "om-transition") {
+            if (outgoingShot === undefined || pendingTransition !== undefined) {
+                throw transitionProjectionError();
+            }
+            pendingTransition = removableElementRange(source, element);
+            continue;
+        }
+        if (element.tagName !== "om-shot") {
+            continue;
+        }
+        const index = documentShots.length;
+        const shot = Object.freeze({ scene: sceneIndex, shot: shots.length });
+        documentShots.push(shot);
+        shots.push(Object.freeze({
+            index,
+            range: removableElementRange(source, element),
+        }));
+        if (pendingTransition !== undefined && outgoingShot !== undefined) {
+            transitions.push(Object.freeze({
+                incomingShot: index,
+                outgoingShot,
+                range: pendingTransition,
+            }));
+            pendingTransition = undefined;
+        }
+        outgoingShot = index;
+    }
+    if (pendingTransition !== undefined) {
+        throw transitionProjectionError();
     }
+    return Object.freeze({
+        range: removableElementRange(source, scene),
+        shots: Object.freeze(shots),
+        transitions: Object.freeze(transitions),
+    });
+}
+function transitionProjectionError() {
+    return new AuthoredHtmlError("compiled transition boundaries cannot be projected into browser regions");
+}
+/** Materializes one Rust-planned region without retaining every projection. */
+export function projectRegionDocument(html, shotIndices) {
+    const selectedShots = selectedShotSet(html, shotIndices);
     const ranges = [];
-    for (const [sceneIndex, scene] of html.regionStructure.scenes.entries()) {
-        if (sceneIndex !== region.scene) {
+    for (const scene of html.regionStructure.scenes) {
+        if (!scene.shots.some((shot) => selectedShots.has(shot.index))) {
             ranges.push(scene.range);
             continue;
         }
-        for (const [shotIndex, shot] of scene.shots.entries()) {
-            if (shotIndex !== region.shot) {
-                ranges.push(shot);
+        for (const shot of scene.shots) {
+            if (!selectedShots.has(shot.index)) {
+                ranges.push(shot.range);
+            }
+        }
+        for (const transition of scene.transitions) {
+            const retained = selectedShots.has(transition.outgoingShot) &&
+                selectedShots.has(transition.incomingShot);
+            if (!retained) {
+                ranges.push(transition.range);
             }
         }
     }
@@ -160,6 +205,16 @@ export function projectShotDocument(html, region) {
         runtimeOffset: projectOffset(html.runtimeOffset, ranges),
     });
 }
+function selectedShotSet(html, shotIndices) {
+    const selected = new Set();
+    for (const index of shotIndices) {
+        if (html.shots[index] === undefined) {
+            throw new AuthoredHtmlError(`browser projection selects unknown shot ${index}`);
+        }
+        selected.add(index);
+    }
+    return selected;
+}
 function parseDocument(source) {
     const errors = [];
     const document = parse(source, {
@@ -215,6 +270,33 @@ function collectScripts(node) {
     });
     return scripts;
 }
+function declaredVisualCapability(document) {
+    const declarations = [];
+    visit(document, (element) => {
+        if (element.tagName !== "meta") {
+            return;
+        }
+        const attributes = new Map(element.attrs.map(({ name, value }) => [name, value]));
+        if (attributes.get("name") === VISUAL_CAPABILITY_META) {
+            declarations.push(attributes.get("content") ?? "");
+        }
+    });
+    if (declarations.length > 1) {
+        throw new AuthoredHtmlError(`authored HTML may contain at most one ${VISUAL_CAPABILITY_META} declaration`);
+    }
+    const [declaration] = declarations;
+    if (declaration === undefined) {
+        return undefined;
+    }
+    switch (declaration) {
+        case "browserComposite":
+        case "separableBackdrop":
+        case "separableOverlay":
+            return declaration;
+        default:
+            throw new AuthoredHtmlError(`${VISUAL_CAPABILITY_META} must be browserComposite, separableBackdrop, or separableOverlay`);
+    }
+}
 function findElement(node, name) {
     const pending = [node];
     while (pending.length > 0) {
@@ -234,6 +316,9 @@ function findElement(node, name) {
 function childElements(parent, name) {
     return parent.childNodes.filter((child) => "tagName" in child && child.tagName === name);
 }
+function directElements(parent) {
+    return parent.childNodes.filter((child) => "tagName" in child);
+}
 function visit(node, visitor) {
     const pending = [node];
     while (pending.length > 0) {
@@ -328,9 +413,12 @@ function isCompilerOnlyAttribute(tagName, attributeName) {
         case "om-title":
             return attributeName === "cue" || attributeName === "delay";
         case "om-shot":
+        case "om-transition":
             return attributeName === "duration";
         case "video":
             return (attributeName === "delay" ||
+                attributeName === "hold-last" ||
+                attributeName === "plays" ||
                 attributeName === "speed" ||
                 attributeName === "src" ||
                 attributeName === "trim");

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

@@ -0,0 +1,9 @@
+import type { BundleProjection } from "./generated/bundle-projection.js";
+/** Invalid or unreadable projection data at the bundler process boundary. */
+export declare class BundleProjectionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Reads and validates one bounded Rust-owned projection snapshot. */
+export declare function readBundleProjection(path: string): Promise<BundleProjection>;
+/** Decodes one checked projection at an in-process or file boundary. */
+export declare function decodeBundleProjection(value: unknown): BundleProjection;

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

@@ -0,0 +1,66 @@
+// Bounded reader for the Rust-owned render-region projection contract.
+// It validates process input before authored HTML is projected or published.
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+import { validateBundleProjection } from "./generated/bundle-projection-validator.js";
+const MAX_PROJECTION_BYTES = 1024 * 1024;
+/** Invalid or unreadable projection data at the bundler process boundary. */
+export class BundleProjectionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "BundleProjectionError";
+    }
+}
+/** Reads and validates one bounded Rust-owned projection snapshot. */
+export async function readBundleProjection(path) {
+    const absolute = resolve(path);
+    let file;
+    try {
+        file = await open(absolute, "r");
+    }
+    catch (error) {
+        throw new BundleProjectionError(`cannot open bundle projection ${absolute}`, { cause: error });
+    }
+    try {
+        const bytes = await readBoundedProjection(file);
+        const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        return decodeBundleProjection(value);
+    }
+    catch (error) {
+        if (error instanceof BundleProjectionError) {
+            throw error;
+        }
+        throw new BundleProjectionError(`cannot read bundle projection ${absolute}`, { cause: error });
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Decodes one checked projection at an in-process or file boundary. */
+export function decodeBundleProjection(value) {
+    if (!validateBundleProjection(value)) {
+        throw invalidProjection();
+    }
+    return value;
+}
+async function readBoundedProjection(file) {
+    const bytes = Buffer.allocUnsafe(MAX_PROJECTION_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_PROJECTION_BYTES) {
+        throw new BundleProjectionError(`bundle projection exceeds the ${MAX_PROJECTION_BYTES}-byte limit`);
+    }
+    return bytes.subarray(0, length);
+}
+function invalidProjection() {
+    const error = validateBundleProjection.errors?.[0];
+    const path = error?.instancePath ?? "";
+    const detail = error?.message ?? "does not match its schema";
+    return new BundleProjectionError(`bundle projection${path} ${detail}`.trim());
+}

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

@@ -3,21 +3,23 @@
 import process from "node:process";
 import { parseArgs } from "node:util";
 import { BundleError, bundlePresentation, } from "./presentation.js";
+import { BundleProjectionError, readBundleProjection, } from "./bundle_projection.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>]",
+    "  [--projection <path>  # required for randomAccess]",
     "  --output <directory>",
     "  --max-output-bytes <bytes>",
     "  --frame-behavior <perFrame|placementBounded>",
     "  --temporal-capability <sequential|randomAccess>",
-    "  --visual-capability <browserComposite|separableOverlay>",
+    "  [--visual-capability <browserComposite|separableBackdrop|separableOverlay>]",
     "",
 ].join("\n");
 // ── Execution ──
 try {
-    const command = parseArguments(process.argv.slice(2));
+    const command = await parseArguments(process.argv.slice(2));
     if (command.kind === "help") {
         process.stdout.write(USAGE);
     }
@@ -31,7 +33,7 @@ catch (error) {
     process.exitCode = failure.kind === "configuration" ? 2 : 1;
 }
 // ── Arguments ──
-function parseArguments(arguments_) {
+async function parseArguments(arguments_) {
     const values = commandValues(arguments_);
     if (values.help !== undefined) {
         if (arguments_.length !== 1) {
@@ -43,21 +45,30 @@ function parseArguments(arguments_) {
     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 visualCapability = optionalVisualCapability(values["visual-capability"]);
     const controls = {
         frameBehavior,
         maxOutputBytes,
         outputDirectory,
-        temporalCapability,
-        visualCapability,
+        ...visualCapability,
     };
+    const common = {
+        ...controls,
+        document: oneValue(values.html, "--html"),
+        ...optionalResolveDirectory(values["resolve-directory"]),
+    };
+    if (temporalCapability === "sequential") {
+        rejectValue(values.projection, "--projection requires randomAccess");
+        return {
+            kind: "bundle",
+            options: { ...common, temporalCapability },
+        };
+    }
+    const projectionPath = oneValue(values.projection, "--projection");
+    const projection = await readBundleProjection(projectionPath);
     return {
         kind: "bundle",
-        options: {
-            ...controls,
-            document: oneValue(values.html, "--html"),
-            ...optionalResolveDirectory(values["resolve-directory"]),
-        },
+        options: { ...common, projection, temporalCapability },
     };
 }
 function commandValues(arguments_) {
@@ -71,6 +82,7 @@ function commandValues(arguments_) {
                 html: { type: "string", multiple: true },
                 "max-output-bytes": { type: "string", multiple: true },
                 output: { type: "string", multiple: true },
+                projection: { type: "string", multiple: true },
                 "resolve-directory": { type: "string", multiple: true },
                 "temporal-capability": { type: "string", multiple: true },
                 "visual-capability": { type: "string", multiple: true },
@@ -95,12 +107,16 @@ function parseTemporalCapability(value) {
     }
     throw configuration("--temporal-capability must be sequential or randomAccess");
 }
-function parseVisualCapability(value) {
+function optionalVisualCapability(values) {
+    if (values === undefined) {
+        return {};
+    }
+    const value = oneValue(values, "--visual-capability");
     const capability = BUNDLE_VISUAL_CAPABILITIES.find((candidate) => candidate === value);
     if (capability !== undefined) {
-        return capability;
+        return { visualCapability: capability };
     }
-    throw configuration("--visual-capability must be browserComposite or separableOverlay");
+    throw configuration("--visual-capability must be browserComposite, separableBackdrop, or separableOverlay");
 }
 function parseFrameBehavior(value) {
     const behavior = BUNDLE_FRAME_BEHAVIORS.find((candidate) => candidate === value);
@@ -119,6 +135,11 @@ function oneValue(values, name) {
     }
     return value;
 }
+function rejectValue(values, message) {
+    if (values !== undefined) {
+        throw configuration(message);
+    }
+}
 function parseByteLimit(value) {
     const bytes = Number(value);
     if (!Number.isSafeInteger(bytes) || bytes <= 0) {
@@ -134,5 +155,8 @@ function commandFailure(error) {
     if (error instanceof BundleError) {
         return error;
     }
+    if (error instanceof BundleProjectionError) {
+        return configuration(error.message, error);
+    }
     return new BundleError("output", "unexpected bundler failure", error);
 }