@onmark/cli 0.3.0 → 0.5.0

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

@@ -1,13 +1,13 @@
 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";
 export { DecodedVideo, materializedVideoSource, type BrowserVideoElement, type DecodedVideoOptions, } from "./video.js";
-export { MAX_PRESENTATION_EFFECTS, PresentationRuntimeAdapter, type ContainerPresentation, type FrameEffect, type OverlayPresentation, type PresentationBindings, type PresentationExtensions, type RuntimeOverlay, type RuntimeNode, type RuntimeScene, type RuntimeShot, type VideoPresentation, } from "./presentation.js";
+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 { MAX_BROWSER_OVERLAYS, MAX_BROWSER_OVERLAY_TEXT_CHARACTERS, MAX_BROWSER_VIDEOS, 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 { MAX_BROWSER_OVERLAYS, MAX_BROWSER_OVERLAY_TEXT_CHARACTERS, MAX_BROWSER_VIDEOS, 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. */
@@ -11,6 +12,8 @@ export type RuntimeOverlay = RuntimePlan["overlays"][number];
 export type RuntimeScene = RuntimePlan["scenes"][number];
 /** Immutable shot container projected from Timeline IR. */
 export type RuntimeShot = RuntimePlan["shots"][number];
+/** Immutable transition relationship projected from Timeline IR. */
+export type RuntimeTransition = RuntimePlan["transitions"][number];
 /** Immutable film identity projected from Timeline IR. */
 export type RuntimeNode = RuntimePlan["film"];
 /** Presentation-owned effects for one semantic container. */
@@ -23,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;
 }
@@ -32,6 +39,13 @@ export interface OverlayPresentation {
     setVisible(visible: boolean): void;
     dispose(): void;
 }
+/** Presentation-owned binding between two adjacent shot elements. */
+export interface TransitionPresentation {
+    readonly element: HTMLElement;
+    readonly incomingElement: HTMLElement;
+    readonly outgoingElement: HTMLElement;
+    dispose(): void;
+}
 /** One paused browser effect driven exclusively by the authored frame. */
 export interface FrameEffect {
     /** Applies the exact frame before the runtime reports it as staged. */
@@ -50,6 +64,7 @@ export interface PresentationBindings {
     bindFilm(plan: RuntimePlan): ContainerPresentation;
     bindScene(scene: RuntimeScene): ContainerPresentation;
     bindShot(shot: RuntimeShot): ContainerPresentation;
+    bindTransition(transition: RuntimeTransition): TransitionPresentation;
     bindVideo(placement: RuntimeVideo): VideoPresentation;
     bindOverlay(placement: RuntimeOverlay): OverlayPresentation;
     bindExtensions(plan: RuntimePlan): Promise<PresentationExtensions>;
@@ -58,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,10 +34,13 @@ export class PresentationRuntimeAdapter {
         };
         let boundStructure;
         const videos = [];
+        const layoutVideos = [];
         const overlays = [];
+        const transitions = [];
         try {
             boundStructure = this.#bindStructure(plan, structure);
-            this.#bindVideos(plan, videos);
+            this.#bindTransitions(plan, transitions);
+            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
@@ -51,7 +54,7 @@ export class PresentationRuntimeAdapter {
             await loadVideos(videos);
         }
         catch (error) {
-            const cleanupFailure = await releasePresentation(effects, resources, structure, 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" };
@@ -63,7 +66,9 @@ export class PresentationRuntimeAdapter {
             frameRate: plan.frameRate,
             resources,
             structure: boundStructure,
+            transitions,
             videos,
+            layoutVideos,
             overlays,
         };
     }
@@ -71,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) {
@@ -122,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?.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");
         }
@@ -147,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,
@@ -160,6 +174,11 @@ export class PresentationRuntimeAdapter {
             presentation.setVisible(false);
         }
     }
+    #bindTransitions(plan, transitions) {
+        for (const placement of plan.transitions) {
+            transitions.push(this.#bindings.bindTransition(placement));
+        }
+    }
     #bindOverlays(plan, overlays) {
         for (const placement of plan.overlays) {
             const presentation = this.#bindings.bindOverlay(placement);
@@ -293,7 +312,7 @@ function presentationLoadFailure(error, cleanupFailure) {
     }
     return RuntimeAdapterError.fromUnknown(error, "presentation failed to load");
 }
-async function releasePresentation(effects, resources, structure, videos, overlays) {
+async function releasePresentation(effects, resources, structure, transitions, videos, layoutVideos, overlays) {
     let failure = await releaseFrameEffects(effects);
     const resourceFailure = await releasePresentationResources(resources);
     failure ??= resourceFailure;
@@ -301,14 +320,94 @@ async function releasePresentation(effects, resources, structure, videos, overla
         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;
     }
+    for (const transition of transitions.toReversed()) {
+        const releaseFailure = releaseTransition(transition);
+        failure ??= releaseFailure;
+    }
     const structureFailure = releaseStructure(structure);
     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()]);
+}
 function releaseStructure(structure) {
     if (structure === undefined) {
         return undefined;
@@ -359,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 { 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") {
@@ -157,7 +161,11 @@ export class RuntimeSession {
     }
 }
 function response(requestId, event) {
-    return decodeBrowserResponse({ version: 3, requestId, event });
+    return decodeBrowserResponse({
+        version: BROWSER_PROTOCOL_VERSION,
+        requestId,
+        event,
+    });
 }
 function invalidRequest(requestId, message) {
     return response(requestId, {
@@ -195,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";
     }
@@ -217,6 +229,7 @@ function planViolation(plan) {
     }
     if (!hasCanonicalNodeOrder(plan.scenes) ||
         !hasCanonicalNodeOrder(plan.shots) ||
+        !hasCanonicalNodeOrder(plan.transitions) ||
         !hasCanonicalNodeOrder(plan.videos) ||
         !hasCanonicalNodeOrder(plan.overlays)) {
         return "plan node collection is not in canonical order";
@@ -238,7 +251,7 @@ function planViolation(plan) {
         }
         sceneIntervals.set(scene.node.nodeId, scene.interval);
     }
-    const shotIntervals = new Map();
+    const shots = new Map();
     for (const shot of plan.shots) {
         const nodeViolation = claimNode(shot.node, nodeIds, authoredIds);
         if (nodeViolation !== undefined) {
@@ -254,21 +267,35 @@ function planViolation(plan) {
         if (!insideInterval(shot.interval, sceneInterval)) {
             return "plan shot interval falls outside its scene";
         }
-        shotIntervals.set(shot.node.nodeId, shot.interval);
+        shots.set(shot.node.nodeId, {
+            interval: shot.interval,
+            order: shots.size,
+            sceneId: shot.sceneId,
+        });
+    }
+    for (const transition of plan.transitions) {
+        const nodeViolation = claimNode(transition.node, nodeIds, authoredIds);
+        if (nodeViolation !== undefined) {
+            return nodeViolation;
+        }
+        const relationViolation = transitionRelationViolation(transition, shots, plan);
+        if (relationViolation !== undefined) {
+            return relationViolation;
+        }
     }
     for (const video of plan.videos) {
         const nodeViolation = claimNode(video.node, nodeIds, authoredIds);
         if (nodeViolation !== undefined) {
             return nodeViolation;
         }
-        const shotInterval = shotIntervals.get(video.shotId);
-        if (shotInterval === undefined) {
+        const shot = shots.get(video.shotId);
+        if (shot === undefined) {
             return "plan video names an unknown shot";
         }
         if (!insideEvaluation(video.interval, plan.evaluation)) {
             return "plan video interval falls outside evaluation";
         }
-        if (!insideInterval(video.interval, shotInterval)) {
+        if (!insideInterval(video.interval, shot.interval)) {
             return "plan video interval falls outside its shot";
         }
         if (!videoSourceMappingIsValid(video, plan.frameRate)) {
@@ -280,7 +307,7 @@ function planViolation(plan) {
         if (nodeViolation !== undefined) {
             return nodeViolation;
         }
-        const parentViolation = overlayParentViolation(overlay, shotIntervals);
+        const parentViolation = overlayParentViolation(overlay, shots);
         if (parentViolation !== undefined) {
             return parentViolation;
         }
@@ -293,6 +320,26 @@ function planViolation(plan) {
     }
     return undefined;
 }
+function transitionRelationViolation(transition, shots, plan) {
+    const outgoing = shots.get(transition.outgoingShotId);
+    const incoming = shots.get(transition.incomingShotId);
+    if (outgoing === undefined ||
+        incoming === undefined ||
+        incoming.order !== outgoing.order + 1 ||
+        outgoing.sceneId !== incoming.sceneId) {
+        return "plan transition does not connect adjacent projected shots";
+    }
+    if (!validPlacement(transition.interval, plan.timeline, plan.evaluation)) {
+        return "plan transition interval is invalid for this evaluation";
+    }
+    if (!insideInterval(transition.interval, outgoing.interval) ||
+        !insideInterval(transition.interval, incoming.interval) ||
+        transition.interval.start !== incoming.interval.start ||
+        transition.interval.end !== outgoing.interval.end) {
+        return "plan transition interval does not match its adjacent shot boundary";
+    }
+    return undefined;
+}
 function hasDenseNodeIdentity(identities) {
     for (let expected = 0; expected < identities.size; expected += 1) {
         if (!identities.has(expected)) {
@@ -311,7 +358,7 @@ function hasCanonicalNodeOrder(entries) {
     }
     return true;
 }
-function overlayParentViolation(overlay, shotIntervals) {
+function overlayParentViolation(overlay, shots) {
     if (overlay.kind === "caption") {
         return overlay.shotId === undefined || overlay.shotId === null
             ? undefined
@@ -320,11 +367,11 @@ function overlayParentViolation(overlay, shotIntervals) {
     if (overlay.shotId === undefined || overlay.shotId === null) {
         return "plan overlay names an unknown shot";
     }
-    const shotInterval = shotIntervals.get(overlay.shotId);
-    if (shotInterval === undefined) {
+    const shot = shots.get(overlay.shotId);
+    if (shot === undefined) {
         return "plan overlay names an unknown shot";
     }
-    if (!insideInterval(overlay.interval, shotInterval)) {
+    if (!insideInterval(overlay.interval, shot.interval)) {
         return "plan overlay interval falls outside its shot";
     }
     return undefined;
@@ -372,6 +419,7 @@ function snapshotPlan(plan) {
     const film = snapshotNode(plan.film);
     const scenes = Object.freeze(plan.scenes.map(snapshotScene));
     const shots = Object.freeze(plan.shots.map(snapshotShot));
+    const transitions = Object.freeze(plan.transitions.map(snapshotTransition));
     const videos = Object.freeze(plan.videos.map(snapshotVideo));
     const overlays = Object.freeze(plan.overlays.map(snapshotOverlay));
     return Object.freeze({
@@ -383,10 +431,19 @@ function snapshotPlan(plan) {
         film,
         scenes,
         shots,
+        transitions,
         videos,
         overlays,
     });
 }
+function snapshotTransition(transition) {
+    return Object.freeze({
+        incomingShotId: transition.incomingShotId,
+        interval: Object.freeze({ ...transition.interval }),
+        node: snapshotNode(transition.node),
+        outgoingShotId: transition.outgoingShotId,
+    });
+}
 function snapshotScene(scene) {
     return Object.freeze({
         node: snapshotNode(scene.node),

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 { ContainerPresentation, FrameEffect, OverlayPresentation, PresentationBindings, PresentationExtensions, RuntimeOverlay, RuntimeNode, RuntimeScene, RuntimeShot, VideoPresentation, } from "./presentation.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";