@onmark/cli 0.4.0 → 0.5.0

package/onmark-release.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "packageName": "@onmark/cli",
-  "version": "0.4.0",
-  "sourceRevision": "2e7e548ab5e309264477239e8c7ca1f4c15cc462",
+  "version": "0.5.0",
+  "sourceRevision": "770428f38a704d4f08eb117e64d52fc37a164931",
   "files": [
     {
       "path": "LICENSE",
@@ -17,7 +17,7 @@
     {
       "path": "package.json",
       "bytes": 1406,
-      "sha256": "0b8c9e832be7f92fdf4a635aba18306806fc63a723f0f8cc320a9d33ba2c7bc8"
+      "sha256": "91721649e92466ab8a096460c959146c113b6f3d18a9f8f2617b3b2af6af023d"
     },
     {
       "path": "packages/authoring/dist/src/frame-motion.d.ts",
@@ -66,8 +66,8 @@
     },
     {
       "path": "packages/authoring/dist/src/presentation.js",
-      "bytes": 10584,
-      "sha256": "4d4ec19ded892ea0372ad76c18cb6e2175b172300164d030f4c26fdc1bfde7bb"
+      "bytes": 14927,
+      "sha256": "0a47ca310dce4c37db3a241cb63301d504aa8d767063a395aa520d519e14a874"
     },
     {
       "path": "packages/authoring/dist/src/resource.d.ts",
@@ -101,13 +101,13 @@
     },
     {
       "path": "packages/bundler/dist/src/authored_html.d.ts",
-      "bytes": 2117,
-      "sha256": "02f8a7256bd35bbb8aaffe1d2a56fbe901aa32f1e3ae383e311696bc14b393bd"
+      "bytes": 2278,
+      "sha256": "7b40cb7d424b01b0543caf97ac9ed50ca68d94ddf969de7219b5c9c9a29f674c"
     },
     {
       "path": "packages/bundler/dist/src/authored_html.js",
-      "bytes": 15985,
-      "sha256": "485c622b295bc7b33dba2af2ca98800ed0e8a691baa7fef22cfd9ccb470be1ec"
+      "bytes": 17153,
+      "sha256": "841d2fc962b65d7f5cfafd4805eac28990d76f15cf298173ca1d7ac424a2480e"
     },
     {
       "path": "packages/bundler/dist/src/bundle_projection.d.ts",
@@ -126,18 +126,18 @@
     },
     {
       "path": "packages/bundler/dist/src/command.js",
-      "bytes": 5931,
-      "sha256": "03292a60d8989e5abbf17a34dc46736d1549689963a73e9f2cb26c531dedee1c"
+      "bytes": 6086,
+      "sha256": "39a4302c67457825502e2ad525309f3cf26ebb2bf2f957aa4b5d36bd391b53ab"
     },
     {
       "path": "packages/bundler/dist/src/generated/bundle-manifest.d.ts",
-      "bytes": 2515,
-      "sha256": "8aa6f33d79f9269da7d5d766d69f1d1037aee3141d76d380ea301b8b6c0d5002"
+      "bytes": 2500,
+      "sha256": "8599570ed61765e2f6e167c637f8ca7b2d83bf1c8fc44242c62aa0e2178ec290"
     },
     {
       "path": "packages/bundler/dist/src/generated/bundle-manifest.js",
-      "bytes": 621,
-      "sha256": "d3f7d430ebbc045db575d648e61f459848bac3c936acf9a6ec5f825260ef2458"
+      "bytes": 646,
+      "sha256": "49a7197dfca225e5ab1a296562b6dd9cbf50bd101eefd8650994085b367a50c0"
     },
     {
       "path": "packages/bundler/dist/src/generated/bundle-projection-validator.d.ts",
@@ -191,13 +191,13 @@
     },
     {
       "path": "packages/bundler/dist/src/presentation.d.ts",
-      "bytes": 2311,
-      "sha256": "50dea00d649ef252a7529e36f0e9f4d829022d38064ed64693dc621ff4c64fcd"
+      "bytes": 2312,
+      "sha256": "b15d3a4c69baccfd6ed56628348dfba180ea698f77993b20b4a249572d7e0cb8"
     },
     {
       "path": "packages/bundler/dist/src/presentation.js",
-      "bytes": 20046,
-      "sha256": "053c22902c3d758e9dbd27857be910c8f6b982001d7924833f077d237c83eb43"
+      "bytes": 20567,
+      "sha256": "62524b69029d27972163c19d3bb87832dbb7c1cb6e4b465715f4375e2ed84fca"
     },
     {
       "path": "packages/launcher/dist/desktop-release.json",
@@ -306,8 +306,8 @@
     },
     {
       "path": "packages/runtime/dist/src/generated/browser-request.d.ts",
-      "bytes": 4883,
-      "sha256": "15861c41b4713352e6b75bdf71c4ad165d8084d9f1031db58b563f984d618f0b"
+      "bytes": 5010,
+      "sha256": "9bd56a97a68aa2a48c4ef94c104a77e18d4b6b95e4444d76fb461468f54640ce"
     },
     {
       "path": "packages/runtime/dist/src/generated/browser-request.js",
@@ -316,8 +316,8 @@
     },
     {
       "path": "packages/runtime/dist/src/generated/browser-response.d.ts",
-      "bytes": 1368,
-      "sha256": "adfd72031e58b5774ebdd62578d2f3bd17009d16bf1881d48330bc42689f77fc"
+      "bytes": 2540,
+      "sha256": "f0345c35a41f7f09961fa7df181a30d991116769e9ecb28dd0627e76a0a20034"
     },
     {
       "path": "packages/runtime/dist/src/generated/browser-response.js",
@@ -326,13 +326,13 @@
     },
     {
       "path": "packages/runtime/dist/src/generated/bundle-layout.d.ts",
-      "bytes": 639,
-      "sha256": "1e5aee7947ce8d4c09de4e05a7e729b31d868c47640963cfe120b1ebb1af69ca"
+      "bytes": 660,
+      "sha256": "213d9166593e39cedf85489b1415834fe95b6d6b95ec00ef0a56c9f10a37c736"
     },
     {
       "path": "packages/runtime/dist/src/generated/bundle-layout.js",
-      "bytes": 455,
-      "sha256": "1807eab2041ee935b3bde12f12402b06d0dd3328e3fb6cb9fc0282699b311f9e"
+      "bytes": 480,
+      "sha256": "f22f9910f25b67d0953fca16488b97531dcefb273938c7ed0fcf9d04552be90e"
     },
     {
       "path": "packages/runtime/dist/src/generated/codec.d.ts",
@@ -346,13 +346,13 @@
     },
     {
       "path": "packages/runtime/dist/src/generated/runtime-contract.d.ts",
-      "bytes": 496,
-      "sha256": "4595ac4a096d79a3f153db88a4e19fd20be23db896b83e54527b26605e2f214c"
+      "bytes": 609,
+      "sha256": "ba1fac50be3c9494935fbc5d31c1e3037934e2d6dd1ca3adfe3d692575f68d27"
     },
     {
       "path": "packages/runtime/dist/src/generated/runtime-contract.js",
-      "bytes": 505,
-      "sha256": "48aff07bb36ec9f8edad25f597b985ff6a5dea9d44fbd2458e63cc4957026ece"
+      "bytes": 604,
+      "sha256": "3cc8116cc4d37c92643c672ef313bed7aa32ac466aeb8724e9563548a6d981ce"
     },
     {
       "path": "packages/runtime/dist/src/generated/validators.d.ts",
@@ -361,8 +361,8 @@
     },
     {
       "path": "packages/runtime/dist/src/generated/validators.js",
-      "bytes": 234626,
-      "sha256": "fdfb7d5ebac40c9845c8998dda53d4d231f8affbb1e3a2a94868415b0862351b"
+      "bytes": 274203,
+      "sha256": "8e1309412309eeda69cd27a8b3a88935cdb8a8b61d0e6776a0a4ac472039e930"
     },
     {
       "path": "packages/runtime/dist/src/host.d.ts",
@@ -376,13 +376,13 @@
     },
     {
       "path": "packages/runtime/dist/src/index.d.ts",
-      "bytes": 1770,
-      "sha256": "de8c076c1aea98cb88bd49f90acd38b882e0240334b88174be53e6085c2ae1e8"
+      "bytes": 1895,
+      "sha256": "5faebc8e4726ec5261e174a55811536991ae0cf42135e0f43e5fb67e9df77eba"
     },
     {
       "path": "packages/runtime/dist/src/index.js",
-      "bytes": 1094,
-      "sha256": "146654c7bdc89e1e1815545af22577744eeb00ec95106f81cb13a41a87690938"
+      "bytes": 1152,
+      "sha256": "10bb00b68b1aba0106334606c72a68227c2dbc9f997aaf99afd14c0502b18872"
     },
     {
       "path": "packages/runtime/dist/src/media.d.ts",
@@ -396,13 +396,13 @@
     },
     {
       "path": "packages/runtime/dist/src/presentation.d.ts",
-      "bytes": 3560,
-      "sha256": "8a27e87ae90d27f2fd7ab20b4048e88f344b59262ac47c5e7ba19bfda8d1dffc"
+      "bytes": 3943,
+      "sha256": "9f2abf95bc614f0a41a42c52f2563574afa24b126c1b266983cc72e1a0f83ee1"
     },
     {
       "path": "packages/runtime/dist/src/presentation.js",
-      "bytes": 14443,
-      "sha256": "4052fe152744acc35981ba60c68822750187a28728dd26312a9b789714e60251"
+      "bytes": 17755,
+      "sha256": "de785ba109f6cf446d211cb05387f5d42d406a61f9cb9c5e38925fbd9c4bccbe"
     },
     {
       "path": "packages/runtime/dist/src/resource.d.ts",
@@ -416,18 +416,18 @@
     },
     {
       "path": "packages/runtime/dist/src/session.d.ts",
-      "bytes": 2057,
-      "sha256": "628ebe74134f71f4d05642c8bf878ae89da57360e3eca34b0317e2f7d371a88c"
+      "bytes": 2298,
+      "sha256": "28b12b59ac2e042ae6e571f861b5b70dec0779a08b6ad1cf8897b262bdbc51db"
     },
     {
       "path": "packages/runtime/dist/src/session.js",
-      "bytes": 20157,
-      "sha256": "d2c7cc8cf073af64ff5dda45bdec3b3aca8bb8e693243ad037c84dce0165eaa6"
+      "bytes": 20533,
+      "sha256": "6383f8ff8fda51e0c51b5c20d736c45bf9d36cc76dfb41bb87588ff0b72654b6"
     },
     {
       "path": "packages/runtime/dist/src/types.d.ts",
-      "bytes": 636,
-      "sha256": "eb75c5eacb50cc83d5bf4b27a3ebc904c4af4a33113d0aa2772dfb54493757f8"
+      "bytes": 753,
+      "sha256": "20d1e1c41b5ed7ac43341b928a6ba331dd73fcf2fea2fe8534f0c523233358ff"
     },
     {
       "path": "packages/runtime/dist/src/types.js",

package/package.json

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

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

@@ -90,15 +90,10 @@ 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,
-            element,
-            source: this.#videoSource(placement),
-        };
+        return bindVideoElement(element, placement.node, this.#videoSource(placement));
     }
     bindTransition(placement) {
         const nodes = this.#nodeIndex();
@@ -238,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/bundler/dist/src/authored_html.d.ts

@@ -1,8 +1,10 @@
+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 shots: readonly AuthoredHtmlShot[];
     readonly regionStructure: AuthoredHtmlRegionStructure;

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
@@ -267,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) {

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

@@ -14,7 +14,7 @@ const USAGE = [
     "  --max-output-bytes <bytes>",
     "  --frame-behavior <perFrame|placementBounded>",
     "  --temporal-capability <sequential|randomAccess>",
-    "  --visual-capability <browserComposite|separableOverlay>",
+    "  [--visual-capability <browserComposite|separableBackdrop|separableOverlay>]",
     "",
 ].join("\n");
 // ── Execution ──
@@ -45,12 +45,12 @@ async 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,
-        visualCapability,
+        ...visualCapability,
     };
     const common = {
         ...controls,
@@ -107,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);

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

@@ -25,11 +25,10 @@ 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.
+ * Unknown presentation code requires `BrowserComposite`. A separable layer
+ * explicitly limits browser ownership to one side of native media.
  */
-export type PresentationVisualCapability = "browserComposite" | "separableOverlay";
+export type PresentationVisualCapability = "browserComposite" | "separableBackdrop" | "separableOverlay";
 /**
  * Stable description of one immutable presentation artifact.
  */
@@ -57,7 +56,7 @@ export interface BundleFile {
 }
 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_VISUAL_CAPABILITIES: readonly ["browserComposite", "separableBackdrop", "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";

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

@@ -6,6 +6,7 @@ export const BUNDLE_TEMPORAL_CAPABILITIES = Object.freeze([
 ]);
 export const BUNDLE_VISUAL_CAPABILITIES = Object.freeze([
     "browserComposite",
+    "separableBackdrop",
     "separableOverlay",
 ]);
 export const BUNDLE_FRAME_BEHAVIORS = Object.freeze([

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

@@ -15,7 +15,7 @@ interface BundleControls {
     readonly resolveDirectory?: string;
     readonly outputDirectory: string;
     readonly maxOutputBytes: number;
-    readonly visualCapability: PresentationVisualCapability;
+    readonly visualCapability?: PresentationVisualCapability;
     readonly frameBehavior: PresentationFrameBehavior;
 }
 /** Explicit inputs for one authored HTML document. */

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

@@ -64,6 +64,7 @@ export async function bundlePresentation(options) {
     return bundle(Object.freeze({
         ...controls,
         html: Object.freeze({ ...html }),
+        visualCapability: resolveVisualCapability(controls.visualCapability, html.visualCapability),
     }));
 }
 async function bundle(input) {
@@ -110,7 +111,9 @@ function snapshotControls(options) {
         throw new BundleError("configuration", "maximum output bytes must be a positive safe integer");
     }
     const temporalCapability = validateTemporalCapability(options.temporalCapability);
-    const visualCapability = validateVisualCapability(options.visualCapability);
+    const visualCapability = options.visualCapability === undefined
+        ? undefined
+        : validateVisualCapability(options.visualCapability);
     const frameBehavior = validateFrameBehavior(options.frameBehavior);
     if (frameBehavior === "placementBounded" &&
         temporalCapability !== "randomAccess") {
@@ -177,7 +180,15 @@ function validateVisualCapability(capability) {
     if (admitted !== undefined) {
         return admitted;
     }
-    throw new BundleError("configuration", "visual capability must be browserComposite or separableOverlay");
+    throw new BundleError("configuration", "visual capability must be browserComposite, separableBackdrop, or separableOverlay");
+}
+function resolveVisualCapability(configured, authored) {
+    if (configured !== undefined &&
+        authored !== undefined &&
+        configured !== authored) {
+        throw new BundleError("configuration", "configured and authored visual capabilities disagree");
+    }
+    return configured ?? authored ?? "browserComposite";
 }
 function validateFrameBehavior(behavior) {
     const admitted = BUNDLE_FRAME_BEHAVIORS.find((candidate) => candidate === behavior);

package/packages/runtime/dist/src/generated/browser-request.d.ts

@@ -2,6 +2,10 @@
  * Closed commands understood by the browser runtime.
  */
 export type BrowserCommand = {
+    /**
+     * Browser responsibility for primary-media elements.
+     */
+    mediaMode: "decoded" | "omitted" | "layoutOnly";
     plan: BrowserPlan;
     type: "load";
 } | {
@@ -66,7 +70,7 @@ export type RequestId = number;
 /**
  * Version of the native-to-browser message contract.
  */
-export type ProtocolVersion = 4;
+export type ProtocolVersion = 5;
 /**
  * One versioned command sent from the native executor to the browser.
  */

package/packages/runtime/dist/src/generated/browser-response.d.ts

@@ -8,6 +8,7 @@ export type BrowserEvent = {
      * Frame at which preparation completed.
      */
     evaluationStart: number;
+    mediaLayout: BrowserMediaLayout;
     type: "prepared";
 } | {
     /**
@@ -40,6 +41,25 @@ export type BrowserEvent = {
 } | {
     type: "disposed";
 };
+/**
+ * Browser identity for one Timeline element or imported caption.
+ *
+ * IDs form dense renderable-semantic preorder within one Browser Plan.
+ *
+ * Authored IDs, rather than this unit-local key, retain cross-projection
+ * semantic identity.
+ */
+export type BrowserNodeId = number;
+/**
+ * Closed CSS object-fit subset admitted by native media.
+ */
+export type BrowserObjectFit = "fill" | "contain" | "cover";
+/**
+ * Exact static media layout observed by the browser.
+ *
+ * @maxItems 16
+ */
+export type BrowserMediaLayout = BrowserMediaPlacement[];
 /**
  * Correlation identity shared by one request and its response events.
  */
@@ -47,7 +67,7 @@ export type RequestId = number;
 /**
  * Version of the native-to-browser message contract.
  */
-export type ProtocolVersion = 4;
+export type ProtocolVersion = 5;
 /**
  * One versioned event returned by the browser runtime.
  */
@@ -56,3 +76,28 @@ export interface BrowserResponse {
     requestId: RequestId;
     version: ProtocolVersion;
 }
+/**
+ * One video element's static, axis-aligned browser layout.
+ */
+export interface BrowserMediaPlacement {
+    nodeId: BrowserNodeId;
+    objectFit: BrowserObjectFit;
+    objectPosition: BrowserObjectPosition;
+    rectangle: BrowserPixelRectangle;
+}
+/**
+ * Fixed-point CSS object-position, where one million represents 100%.
+ */
+export interface BrowserObjectPosition {
+    x: number;
+    y: number;
+}
+/**
+ * Positive pixel rectangle relative to the output viewport.
+ */
+export interface BrowserPixelRectangle {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+}