@onmark/cli 0.4.0 → 0.5.0

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

@@ -1,6 +1,6 @@
 export { ProtocolDecodeError, decodeBrowserRequest, decodeBrowserResponse, } from "./generated/codec.js";
 export type { BrowserRequest } from "./generated/browser-request.js";
-export type { BrowserResponse } from "./generated/browser-response.js";
+export type { BrowserMediaLayout, BrowserMediaPlacement, BrowserResponse, } from "./generated/browser-response.js";
 export type { BrowserPlan, BrowserVideo } from "./generated/browser-request.js";
 export { runtimeFrameAt, type RuntimeFrame } from "./clock.js";
 export { videoFrameSelection, type RuntimeVideo, type VideoFrameSelection, } from "./media.js";
@@ -8,6 +8,6 @@ export { DecodedVideo, materializedVideoSource, type BrowserVideoElement, type D
 export { MAX_PRESENTATION_EFFECTS, PresentationRuntimeAdapter, type ContainerPresentation, type FrameEffect, type OverlayPresentation, type PresentationBindings, type PresentationExtensions, type RuntimeOverlay, type RuntimeNode, type RuntimeScene, type RuntimeShot, type RuntimeTransition, type TransitionPresentation, type VideoPresentation, } from "./presentation.js";
 export { MAX_PRESENTATION_RESOURCES, PRESENTATION_RESOURCE_KINDS, type PresentationResource, type PresentationResourceKind, } from "./resource.js";
 export { BUNDLE_ASSET_DIRECTORY, PRESENTATION_TEMPORAL_CAPABILITIES, type PresentationTemporalCapability, } from "./generated/bundle-layout.js";
-export { BROWSER_PROTOCOL_VERSION, MAX_BROWSER_OVERLAYS, MAX_BROWSER_OVERLAY_TEXT_CHARACTERS, MAX_BROWSER_VIDEOS, MAX_BROWSER_TRANSITIONS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
+export { BROWSER_PROTOCOL_VERSION, BROWSER_OBJECT_POSITION_SCALE, MAX_BROWSER_MEDIA_LAYOUTS, MAX_BROWSER_OVERLAYS, MAX_BROWSER_OVERLAY_TEXT_CHARACTERS, MAX_BROWSER_VIDEOS, MAX_BROWSER_TRANSITIONS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
 export { RUNTIME_HOST_NAME, installRuntimeHost, type RuntimeHost, } from "./host.js";
-export { RuntimeAdapterError, RuntimeSession, type RuntimeAdapter, type RuntimeAdapterFailureKind, type RuntimePlan, } from "./session.js";
+export { RuntimeAdapterError, RuntimeSession, type RuntimeAdapter, type RuntimeAdapterFailureKind, type RuntimeMediaMode, type RuntimePlan, } from "./session.js";

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

@@ -7,6 +7,6 @@ export { DecodedVideo, materializedVideoSource, } from "./video.js";
 export { MAX_PRESENTATION_EFFECTS, PresentationRuntimeAdapter, } from "./presentation.js";
 export { MAX_PRESENTATION_RESOURCES, PRESENTATION_RESOURCE_KINDS, } from "./resource.js";
 export { BUNDLE_ASSET_DIRECTORY, PRESENTATION_TEMPORAL_CAPABILITIES, } from "./generated/bundle-layout.js";
-export { BROWSER_PROTOCOL_VERSION, MAX_BROWSER_OVERLAYS, MAX_BROWSER_OVERLAY_TEXT_CHARACTERS, MAX_BROWSER_VIDEOS, MAX_BROWSER_TRANSITIONS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
+export { BROWSER_PROTOCOL_VERSION, BROWSER_OBJECT_POSITION_SCALE, MAX_BROWSER_MEDIA_LAYOUTS, MAX_BROWSER_OVERLAYS, MAX_BROWSER_OVERLAY_TEXT_CHARACTERS, MAX_BROWSER_VIDEOS, MAX_BROWSER_TRANSITIONS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
 export { RUNTIME_HOST_NAME, installRuntimeHost, } from "./host.js";
 export { RuntimeAdapterError, RuntimeSession, } from "./session.js";

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

@@ -1,6 +1,7 @@
 import type { RuntimeFrame } from "./clock.js";
+import type { BrowserMediaLayout, BrowserMediaPlacement } from "./generated/browser-response.js";
 import { type RuntimeVideo } from "./media.js";
-import { type RuntimeAdapter, type RuntimePlan } from "./session.js";
+import { type RuntimeAdapter, type RuntimeMediaMode, type RuntimePlan } from "./session.js";
 import { type BrowserVideoElement } from "./video.js";
 import { type PresentationResource } from "./resource.js";
 /** Maximum exact-frame effects retained by one presentation adapter. */
@@ -25,6 +26,10 @@ export interface ContainerPresentation {
 export interface VideoPresentation {
     readonly element: BrowserVideoElement;
     readonly source: string;
+    /** Includes the media box in layout without exposing its pixels. */
+    setLayoutVisible(visible: boolean): void;
+    /** Measures one visible layout-only media box. */
+    measureLayout(): BrowserMediaPlacement;
     setVisible(visible: boolean): void;
     dispose(): void;
 }
@@ -68,8 +73,8 @@ export interface PresentationBindings {
 export declare class PresentationRuntimeAdapter implements RuntimeAdapter {
     #private;
     constructor(bindings: PresentationBindings, readinessTimeoutMilliseconds: number);
-    load(plan: RuntimePlan): Promise<void>;
-    prepare(_frame: RuntimeFrame): Promise<void>;
+    load(plan: RuntimePlan, mediaMode?: RuntimeMediaMode): Promise<void>;
+    prepare(_frame: RuntimeFrame): Promise<BrowserMediaLayout>;
     seek(frame: RuntimeFrame): Promise<void>;
     confirm(frame: RuntimeFrame): Promise<void>;
     dispose(): Promise<void>;

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

@@ -21,7 +21,7 @@ export class PresentationRuntimeAdapter {
         this.#bindings = bindings;
         this.#readinessTimeoutMilliseconds = readinessTimeoutMilliseconds;
     }
-    async load(plan) {
+    async load(plan, mediaMode = "decoded") {
         if (this.#state.kind !== "empty") {
             throw new RuntimeAdapterError("operation", "presentation load requires the empty state");
         }
@@ -34,12 +34,13 @@ export class PresentationRuntimeAdapter {
         };
         let boundStructure;
         const videos = [];
+        const layoutVideos = [];
         const overlays = [];
         const transitions = [];
         try {
             boundStructure = this.#bindStructure(plan, structure);
             this.#bindTransitions(plan, transitions);
-            this.#bindVideos(plan, videos);
+            this.#bindVideos(plan, mediaMode, videos, layoutVideos);
             this.#bindOverlays(plan, overlays);
             const extensions = await this.#bindings.bindExtensions(plan);
             // Take both returned collections before either ownership projection or
@@ -53,7 +54,7 @@ export class PresentationRuntimeAdapter {
             await loadVideos(videos);
         }
         catch (error) {
-            const cleanupFailure = await releasePresentation(effects, resources, structure, transitions, videos, overlays);
+            const cleanupFailure = await releasePresentation(effects, resources, structure, transitions, videos, layoutVideos, overlays);
             // A binding attempt may mutate author-owned state that generic cleanup
             // cannot prove reusable. A fresh page owns the only valid retry.
             this.#state = { kind: "disposed" };
@@ -67,6 +68,7 @@ export class PresentationRuntimeAdapter {
             structure: boundStructure,
             transitions,
             videos,
+            layoutVideos,
             overlays,
         };
     }
@@ -74,10 +76,11 @@ export class PresentationRuntimeAdapter {
         const state = this.#loadedState("prepare");
         try {
             await preparePresentationResources(state.resources, this.#readinessTimeoutMilliseconds);
+            return measureMediaLayout(state.layoutVideos, state.structure);
         }
         catch (error) {
             this.#state = { ...state, kind: "failed" };
-            throw error;
+            throw RuntimeAdapterError.fromUnknown(error, "presentation preparation failed");
         }
     }
     async seek(frame) {
@@ -125,7 +128,7 @@ export class PresentationRuntimeAdapter {
             : undefined;
         this.#state = { kind: "disposed" };
         this.#staged = undefined;
-        const failure = await releasePresentation(loaded?.effects ?? [], loaded?.resources ?? [], loaded?.structure, loaded?.transitions ?? [], loaded?.videos ?? [], loaded?.overlays ?? []);
+        const failure = await releasePresentation(loaded?.effects ?? [], loaded?.resources ?? [], loaded?.structure, loaded?.transitions ?? [], loaded?.videos ?? [], loaded?.layoutVideos ?? [], loaded?.overlays ?? []);
         if (failure !== undefined) {
             throw RuntimeAdapterError.fromUnknown(failure, "presentation cleanup failed");
         }
@@ -150,9 +153,17 @@ export class PresentationRuntimeAdapter {
             shots: structure.shots,
         };
     }
-    #bindVideos(plan, videos) {
+    #bindVideos(plan, mediaMode, videos, layoutVideos) {
+        if (mediaMode === "omitted") {
+            return;
+        }
         for (const placement of plan.videos) {
             const presentation = this.#bindings.bindVideo(placement);
+            if (mediaMode === "layoutOnly") {
+                layoutVideos.push({ placement, presentation });
+                presentation.setVisible(false);
+                continue;
+            }
             const resource = new DecodedVideo({
                 element: presentation.element,
                 nodeId: placement.node.nodeId,
@@ -301,7 +312,7 @@ function presentationLoadFailure(error, cleanupFailure) {
     }
     return RuntimeAdapterError.fromUnknown(error, "presentation failed to load");
 }
-async function releasePresentation(effects, resources, structure, transitions, videos, overlays) {
+async function releasePresentation(effects, resources, structure, transitions, videos, layoutVideos, overlays) {
     let failure = await releaseFrameEffects(effects);
     const resourceFailure = await releasePresentationResources(resources);
     failure ??= resourceFailure;
@@ -309,6 +320,10 @@ async function releasePresentation(effects, resources, structure, transitions, v
         const releaseFailure = releaseVideo(video);
         failure ??= releaseFailure;
     }
+    for (const video of layoutVideos) {
+        const releaseFailure = releaseLayoutVideo(video);
+        failure ??= releaseFailure;
+    }
     for (const overlay of overlays) {
         const releaseFailure = releaseOverlay(overlay);
         failure ??= releaseFailure;
@@ -321,6 +336,75 @@ async function releasePresentation(effects, resources, structure, transitions, v
     failure ??= structureFailure;
     return failure;
 }
+function measureMediaLayout(videos, structure) {
+    try {
+        return collectMediaLayout(videos, structure);
+    }
+    catch (error) {
+        throw mediaLayoutFailure(error);
+    }
+}
+function collectMediaLayout(videos, structure) {
+    const byShot = groupLayoutVideos(videos);
+    const scenes = new Map(structure.scenes.map((scene) => [scene.placement.node.nodeId, scene]));
+    const placements = [];
+    for (const shot of structure.shots) {
+        const group = byShot.get(shot.placement.node.nodeId);
+        if (group === undefined) {
+            continue;
+        }
+        const scene = scenes.get(shot.placement.sceneId);
+        if (scene === undefined) {
+            throw new RuntimeAdapterError("operation", "layout-only video names an unbound scene");
+        }
+        scene.presentation.setVisible(true);
+        shot.presentation.setVisible(true);
+        for (const video of group) {
+            video.presentation.setLayoutVisible(true);
+        }
+        try {
+            for (const video of group) {
+                const placement = video.presentation.measureLayout();
+                if (placement.nodeId !== video.placement.node.nodeId) {
+                    throw new RuntimeAdapterError("operation", "measured video layout names the wrong browser node");
+                }
+                placements.push(placement);
+            }
+        }
+        finally {
+            for (const video of group) {
+                video.presentation.setLayoutVisible(false);
+            }
+            shot.presentation.setVisible(false);
+            scene.presentation.setVisible(false);
+        }
+    }
+    // Freeze the owned array in place; generated JSON types remain mutable-shaped.
+    Object.freeze(placements);
+    return placements;
+}
+function mediaLayoutFailure(error) {
+    if (error instanceof RuntimeAdapterError) {
+        return error;
+    }
+    const message = error instanceof Error
+        ? error.message
+        : "browser media layout measurement failed";
+    return new RuntimeAdapterError("operation", message);
+}
+function groupLayoutVideos(videos) {
+    const groups = new Map();
+    for (const video of videos) {
+        const group = groups.get(video.placement.shotId);
+        if (group === undefined) {
+            groups.set(video.placement.shotId, [video]);
+        }
+        else {
+            group.push(video);
+        }
+    }
+    return groups;
+}
 function releaseTransition(transition) {
     return releaseAll([() => transition.dispose()]);
 }
@@ -374,6 +458,12 @@ function releaseVideo(video) {
         () => video.presentation.dispose(),
     ]);
 }
+function releaseLayoutVideo(video) {
+    return releaseAll([
+        () => video.presentation.setLayoutVisible(false),
+        () => video.presentation.dispose(),
+    ]);
+}
 function releaseOverlay(overlay) {
     return releaseAll([
         () => overlay.presentation.setVisible(false),

package/packages/runtime/dist/src/session.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserPlan, BrowserRequest } from "./generated/browser-request.js";
-import type { BrowserResponse } from "./generated/browser-response.js";
+import type { BrowserMediaLayout, BrowserResponse } from "./generated/browser-response.js";
 import { type RuntimeFrame } from "./clock.js";
 type Immutable<T> = T extends object ? {
     readonly [Key in keyof T]: Immutable<T[Key]>;
@@ -14,9 +14,9 @@ export type RuntimePlan = Immutable<BrowserPlan>;
  */
 export interface RuntimeAdapter {
     /** Installs one owned snapshot of the immutable browser plan. */
-    load(plan: RuntimePlan): Promise<void>;
+    load(plan: RuntimePlan, mediaMode: RuntimeMediaMode): Promise<void>;
     /** Resolves only after resources at the evaluation start are stable. */
-    prepare(frame: RuntimeFrame): Promise<void>;
+    prepare(frame: RuntimeFrame): Promise<BrowserMediaLayout>;
     /** Stages one exact frame and registers media presentation observers. */
     seek(frame: RuntimeFrame): Promise<void>;
     /** Verifies media presentation after native compositor capture. */
@@ -24,6 +24,10 @@ export interface RuntimeAdapter {
     /** Releases all resources owned by this adapter. */
     dispose(): Promise<void>;
 }
+/** Browser responsibility selected before presentation loading begins. */
+export type RuntimeMediaMode = Extract<BrowserRequest["command"], {
+    type: "load";
+}>["mediaMode"];
 export type RuntimeAdapterFailureKind = "operation" | "readinessTimeout";
 /** Expected failure reported by a browser adapter. */
 export declare class RuntimeAdapterError extends Error {

package/packages/runtime/dist/src/session.js

@@ -2,7 +2,7 @@
 // Owns command ordering and state while a narrow adapter owns browser effects;
 // this split keeps protocol behavior deterministic and directly testable.
 import { decodeBrowserResponse } from "./generated/codec.js";
-import { BROWSER_PROTOCOL_VERSION, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
+import { BROWSER_PROTOCOL_VERSION, MAX_BROWSER_MEDIA_LAYOUTS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
 import { runtimeFrameAt } from "./clock.js";
 import { exactRatioIsCanonical, videoSourceMappingIsValid } from "./media.js";
 /** Expected failure reported by a browser adapter. */
@@ -48,7 +48,7 @@ export class RuntimeSession {
     #execute(request) {
         switch (request.command.type) {
             case "load":
-                return this.#load(request.requestId, request.command.plan);
+                return this.#load(request.requestId, request.command.plan, request.command.mediaMode);
             case "prepare":
                 return this.#prepare(request.requestId, request.command.evaluationStart);
             case "seek":
@@ -59,18 +59,18 @@ export class RuntimeSession {
                 return this.#dispose(request.requestId);
         }
     }
-    async #load(requestId, plan) {
+    async #load(requestId, plan, mediaMode) {
         if (this.#state.kind !== "empty") {
             return invalidRequest(requestId, "load requires an empty browser session");
         }
-        const violation = planViolation(plan);
+        const violation = planViolation(plan, mediaMode);
         if (violation !== undefined) {
             return invalidRequest(requestId, violation);
         }
         const ownedPlan = snapshotPlan(plan);
         const nextState = loadedState(ownedPlan);
         try {
-            await this.#adapter.load(ownedPlan);
+            await this.#adapter.load(ownedPlan, mediaMode);
         }
         catch (error) {
             // Loading may have entered author code and partially mutated its owned
@@ -89,7 +89,13 @@ export class RuntimeSession {
             return invalidRequest(requestId, "prepare must use the plan evaluation start");
         }
         try {
-            await this.#adapter.prepare(runtimeFrameAt(evaluationStart, this.#state.frameRate));
+            const mediaLayout = await this.#adapter.prepare(runtimeFrameAt(evaluationStart, this.#state.frameRate));
+            this.#state = { ...this.#state, kind: "ready" };
+            return response(requestId, {
+                type: "prepared",
+                evaluationStart,
+                mediaLayout,
+            });
         }
         catch (error) {
             // Preparation may have started author-owned asynchronous work that the
@@ -98,8 +104,6 @@ export class RuntimeSession {
             this.#state = { kind: "failed" };
             return readinessFailure(requestId, "prepareFailed", error);
         }
-        this.#state = { ...this.#state, kind: "ready" };
-        return response(requestId, { type: "prepared", evaluationStart });
     }
     async #seek(requestId, frame) {
         if (this.#state.kind !== "ready") {
@@ -199,7 +203,11 @@ function readinessFailure(requestId, operationCode, error) {
     }
     return operationFailure(requestId, operationCode, error);
 }
-function planViolation(plan) {
+function planViolation(plan, mediaMode) {
+    if (mediaMode === "layoutOnly" &&
+        plan.videos.length > MAX_BROWSER_MEDIA_LAYOUTS) {
+        return "layout-only plan exceeds the browser media-layout limit";
+    }
     if (!exactRatioIsCanonical(plan.frameRate)) {
         return "plan frame rate is not canonical";
     }

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

@@ -1,6 +1,7 @@
 export type { RuntimeFrame } from "./clock.js";
+export type { BrowserMediaLayout, BrowserMediaPlacement, } from "./generated/browser-response.js";
 export type { RuntimeVideo } from "./media.js";
 export type { PresentationFrameBehavior, PresentationTemporalCapability, PresentationVisualCapability, } from "./generated/bundle-layout.js";
-export type { RuntimePlan } from "./session.js";
+export type { RuntimeMediaMode, RuntimePlan } from "./session.js";
 export type { ContainerPresentation, FrameEffect, OverlayPresentation, PresentationBindings, PresentationExtensions, RuntimeOverlay, RuntimeNode, RuntimeScene, RuntimeShot, RuntimeTransition, TransitionPresentation, VideoPresentation, } from "./presentation.js";
 export type { PresentationResource, PresentationResourceKind, } from "./resource.js";