@onmark/cli 0.5.1 → 0.6.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 { BrowserMediaLayout, BrowserMediaPlacement, BrowserResponse, } from "./generated/browser-response.js";
+export type { BrowserMediaLayout, BrowserMediaPlacement, BrowserResponse, BrowserVisualFinding, BrowserVisualFindings, BrowserVisualIssue, } 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, 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 { BROWSER_PROTOCOL_VERSION, BROWSER_OBJECT_POSITION_SCALE, MAX_BROWSER_MEDIA_LAYOUTS, MAX_BROWSER_OVERLAYS, MAX_BROWSER_VISUAL_FINDINGS, 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 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, 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 { BROWSER_PROTOCOL_VERSION, BROWSER_OBJECT_POSITION_SCALE, MAX_BROWSER_MEDIA_LAYOUTS, MAX_BROWSER_OVERLAYS, MAX_BROWSER_VISUAL_FINDINGS, 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,5 +1,5 @@
 import type { RuntimeFrame } from "./clock.js";
-import type { BrowserMediaLayout, BrowserMediaPlacement } from "./generated/browser-response.js";
+import type { BrowserMediaLayout, BrowserMediaPlacement, BrowserVisualFindings } from "./generated/browser-response.js";
 import { type RuntimeVideo } from "./media.js";
 import { type RuntimeAdapter, type RuntimeMediaMode, type RuntimePlan } from "./session.js";
 import { type BrowserVideoElement } from "./video.js";
@@ -76,6 +76,6 @@ export declare class PresentationRuntimeAdapter implements RuntimeAdapter {
     load(plan: RuntimePlan, mediaMode?: RuntimeMediaMode): Promise<void>;
     prepare(_frame: RuntimeFrame): Promise<BrowserMediaLayout>;
     seek(frame: RuntimeFrame): Promise<void>;
-    confirm(frame: RuntimeFrame): Promise<void>;
+    confirm(frame: RuntimeFrame): Promise<BrowserVisualFindings>;
     dispose(): Promise<void>;
 }

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

@@ -2,6 +2,7 @@
 // Rust owns every interval; presentation callbacks own DOM and layout effects.
 import { videoFrameSelection, } from "./media.js";
 import { RuntimeAdapterError, } from "./session.js";
+import { MAX_BROWSER_VISUAL_FINDINGS } from "./generated/runtime-contract.js";
 import { DecodedVideo } from "./video.js";
 import { ownPresentationResources, preparePresentationResources, releasePresentationResources, requireReadinessTimeout, validatePresentationResources, } from "./resource.js";
 // ── Presentation boundary ──
@@ -33,6 +34,7 @@ export class PresentationRuntimeAdapter {
             shots: [],
         };
         let boundStructure;
+        let visualSubjects;
         const videos = [];
         const layoutVideos = [];
         const overlays = [];
@@ -42,6 +44,7 @@ export class PresentationRuntimeAdapter {
             this.#bindTransitions(plan, transitions);
             this.#bindVideos(plan, mediaMode, videos, layoutVideos);
             this.#bindOverlays(plan, overlays);
+            visualSubjects = bindVisualSubjects(boundStructure.shots, overlays);
             const extensions = await this.#bindings.bindExtensions(plan);
             // Take both returned collections before either ownership projection or
             // validation can fail; cleanup must retain every transferred resource.
@@ -70,6 +73,7 @@ export class PresentationRuntimeAdapter {
             videos,
             layoutVideos,
             overlays,
+            visualSubjects,
         };
     }
     async prepare(_frame) {
@@ -104,14 +108,16 @@ export class PresentationRuntimeAdapter {
         }
     }
     async confirm(frame) {
-        this.#loadedState("confirm");
+        const state = this.#loadedState("confirm");
         const staged = this.#staged;
         if (staged === undefined || staged.frame.index !== frame.index) {
             throw new RuntimeAdapterError("operation", "presentation confirmation requires the staged frame");
         }
         try {
             await confirmVideos(staged.videos);
+            const findings = inspectPresentation(frame, state.visualSubjects);
             this.#staged = undefined;
+            return findings;
         }
         catch (error) {
             this.#staged = undefined;
@@ -193,6 +199,78 @@ export class PresentationRuntimeAdapter {
         return this.#state;
     }
 }
+function inspectPresentation(frame, subjects) {
+    const findings = [];
+    for (const subject of subjects) {
+        const { interval } = subject;
+        if (frame.index < interval.start || frame.index >= interval.end) {
+            continue;
+        }
+        const issues = inspectVisualSubject(subject);
+        for (const issue of issues) {
+            findings.push({
+                nodeId: subject.nodeId,
+                issue,
+            });
+            if (findings.length === MAX_BROWSER_VISUAL_FINDINGS) {
+                return findings;
+            }
+        }
+    }
+    return findings;
+}
+function bindVisualSubjects(shots, overlays) {
+    const subjects = [];
+    for (const shot of shots) {
+        subjects.push({
+            element: shot.presentation.element,
+            interval: shot.placement.interval,
+            kind: "shot",
+            nodeId: shot.placement.node.nodeId,
+        });
+    }
+    for (const overlay of overlays) {
+        subjects.push({
+            element: overlay.presentation.element,
+            interval: overlay.placement.interval,
+            kind: "overlay",
+            nodeId: overlay.placement.node.nodeId,
+        });
+    }
+    subjects.sort((left, right) => left.nodeId - right.nodeId);
+    return subjects;
+}
+function inspectVisualSubject(subject) {
+    if (hasEmptyBox(subject.element)) {
+        return ["emptyBox"];
+    }
+    return subject.kind === "overlay" ? inspectOverlay(subject.element) : [];
+}
+function inspectOverlay(element) {
+    if (hasEmptyBox(element)) {
+        return ["emptyBox"];
+    }
+    const view = element.ownerDocument.defaultView;
+    if (view === null) {
+        throw new RuntimeAdapterError("operation", "overlay layout requires an active browser document");
+    }
+    const style = view.getComputedStyle(element);
+    const issues = [];
+    if (clips(style.overflowX) && element.scrollWidth > element.clientWidth) {
+        issues.push("clippedHorizontally");
+    }
+    if (clips(style.overflowY) && element.scrollHeight > element.clientHeight) {
+        issues.push("clippedVertically");
+    }
+    return issues;
+}
+function hasEmptyBox(element) {
+    const rectangle = element.getBoundingClientRect();
+    return rectangle.width <= 0 || rectangle.height <= 0;
+}
+function clips(overflow) {
+    return overflow === "hidden" || overflow === "clip";
+}
 // ── Frame application ──
 function ownFrameEffects(effects) {
     return Object.freeze(effects.map(ownFrameEffect));

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

@@ -1,5 +1,5 @@
 import type { BrowserPlan, BrowserRequest } from "./generated/browser-request.js";
-import type { BrowserMediaLayout, BrowserResponse } from "./generated/browser-response.js";
+import type { BrowserMediaLayout, BrowserResponse, BrowserVisualFindings } 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]>;
@@ -19,8 +19,8 @@ export interface RuntimeAdapter {
     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. */
-    confirm(frame: RuntimeFrame): Promise<void>;
+    /** Verifies captured media and returns bounded facts about the staged layout. */
+    confirm(frame: RuntimeFrame): Promise<BrowserVisualFindings>;
     /** Releases all resources owned by this adapter. */
     dispose(): Promise<void>;
 }

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

@@ -2,9 +2,10 @@
 // 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_BROWSER_MEDIA_LAYOUTS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, } from "./generated/runtime-contract.js";
+import { BROWSER_PROTOCOL_VERSION, MAX_BROWSER_TEXT_BYTES, MAX_BROWSER_MEDIA_LAYOUTS, MAX_BROWSER_VISUAL_FINDINGS, MAX_FAILURE_MESSAGE_CHARACTERS, MAX_PENDING_RESOURCE_CHARACTERS, MAX_PENDING_RESOURCES, MAX_VARIANT_TEXT_BYTES, } from "./generated/runtime-contract.js";
 import { runtimeFrameAt } from "./clock.js";
 import { exactRatioIsCanonical, videoSourceMappingIsValid } from "./media.js";
+const UTF8 = new TextEncoder();
 /** Expected failure reported by a browser adapter. */
 export class RuntimeAdapterError extends Error {
     kind;
@@ -133,7 +134,14 @@ export class RuntimeSession {
             return invalidRequest(requestId, "confirm must use the staged frame");
         }
         try {
-            await this.#adapter.confirm(runtimeFrameAt(frame, this.#state.frameRate));
+            const findings = await this.#adapter.confirm(runtimeFrameAt(frame, this.#state.frameRate));
+            const visualFindings = snapshotVisualFindings(findings);
+            this.#state = { ...this.#state, kind: "ready" };
+            return response(requestId, {
+                type: "frameReady",
+                frame,
+                visualFindings,
+            });
         }
         catch (error) {
             // Confirmation consumes staged media observers and may succeed for only
@@ -141,8 +149,6 @@ export class RuntimeSession {
             this.#state = { kind: "failed" };
             return readinessFailure(requestId, "confirmFailed", error);
         }
-        this.#state = { ...this.#state, kind: "ready" };
-        return response(requestId, { type: "frameReady", frame });
     }
     async #dispose(requestId) {
         if (this.#state.kind === "disposed") {
@@ -167,6 +173,47 @@ function response(requestId, event) {
         event,
     });
 }
+function snapshotVisualFindings(findings) {
+    if (findings.length > MAX_BROWSER_VISUAL_FINDINGS) {
+        throw new RuntimeAdapterError("operation", "browser visual findings exceed the per-frame limit");
+    }
+    const owned = findings.map((finding) => {
+        if (!Number.isSafeInteger(finding.nodeId) ||
+            finding.nodeId < 0 ||
+            finding.nodeId > 2 ** 32 - 1) {
+            throw new RuntimeAdapterError("operation", "browser visual finding has an invalid node identity");
+        }
+        visualFindingOrder(finding.issue);
+        return { nodeId: finding.nodeId, issue: finding.issue };
+    });
+    owned.sort(compareVisualFindings);
+    let previous;
+    for (const finding of owned) {
+        if (previous?.nodeId === finding.nodeId &&
+            previous.issue === finding.issue) {
+            throw new RuntimeAdapterError("operation", "browser visual findings contain a duplicate");
+        }
+        previous = finding;
+        Object.freeze(finding);
+    }
+    return Object.freeze(owned);
+}
+function compareVisualFindings(left, right) {
+    return (left.nodeId - right.nodeId ||
+        visualFindingOrder(left.issue) - visualFindingOrder(right.issue));
+}
+function visualFindingOrder(issue) {
+    switch (issue) {
+        case "emptyBox":
+            return 0;
+        case "clippedHorizontally":
+            return 1;
+        case "clippedVertically":
+            return 2;
+        default:
+            throw new RuntimeAdapterError("operation", "browser visual finding has an invalid issue");
+    }
+}
 function invalidRequest(requestId, message) {
     return response(requestId, {
         type: "failed",
@@ -234,6 +281,13 @@ function planViolation(plan, mediaMode) {
         !hasCanonicalNodeOrder(plan.overlays)) {
         return "plan node collection is not in canonical order";
     }
+    const variantTextBytes = canonicalVariantFieldsTextBytes(plan.variantFields);
+    if (variantTextBytes === undefined) {
+        return "plan variant fields are not canonical";
+    }
+    if (!browserTextFitsBudget(plan.overlays, variantTextBytes)) {
+        return "plan text exceeds the browser request budget";
+    }
     const nodeIds = new Set();
     const authoredIds = new Set();
     const filmViolation = claimNode(plan.film, nodeIds, authoredIds);
@@ -358,11 +412,71 @@ function hasCanonicalNodeOrder(entries) {
     }
     return true;
 }
+function canonicalVariantFieldsTextBytes(fields) {
+    let previous;
+    let textBytes = 0;
+    for (const field of fields) {
+        const valueBytes = canonicalVariantTextBytes(field.value);
+        if (!/^[a-z][A-Za-z0-9]{0,63}$/u.test(field.name) ||
+            (previous !== undefined && field.name <= previous) ||
+            valueBytes === undefined) {
+            return undefined;
+        }
+        textBytes += valueBytes;
+        previous = field.name;
+    }
+    return textBytes;
+}
+function canonicalVariantTextBytes(value) {
+    switch (value.kind) {
+        case "text": {
+            const bytes = UTF8.encode(value.value).byteLength;
+            return bytes <= MAX_VARIANT_TEXT_BYTES ? bytes : undefined;
+        }
+        case "integer":
+            return Number.isSafeInteger(value.value) ? 0 : undefined;
+        case "boolean":
+            return 0;
+        case "color":
+            return /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/u.test(value.value)
+                ? 0
+                : undefined;
+    }
+}
+function browserTextFitsBudget(overlays, variantTextBytes) {
+    let textBytes = variantTextBytes;
+    for (const overlay of overlays) {
+        textBytes += UTF8.encode(overlay.text).byteLength;
+        const track = overlay.captionTrack;
+        if (track !== undefined && track !== null) {
+            textBytes += UTF8.encode(track.id).byteLength;
+            textBytes += UTF8.encode(track.language).byteLength;
+        }
+        if (textBytes > MAX_BROWSER_TEXT_BYTES) {
+            return false;
+        }
+    }
+    return true;
+}
 function overlayParentViolation(overlay, shots) {
     if (overlay.kind === "caption") {
-        return overlay.shotId === undefined || overlay.shotId === null
-            ? undefined
-            : "plan caption names a structural parent";
+        if (overlay.shotId !== undefined && overlay.shotId !== null) {
+            return "plan caption names a structural parent";
+        }
+        const track = overlay.captionTrack;
+        if (track === undefined || track === null) {
+            return "plan caption omits track metadata";
+        }
+        if (track.id.length === 0 || /[\t\n\f\r ]/u.test(track.id)) {
+            return "plan caption track identity is invalid";
+        }
+        if (!/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/u.test(track.language)) {
+            return "plan caption language is invalid";
+        }
+        return undefined;
+    }
+    if (overlay.captionTrack !== undefined && overlay.captionTrack !== null) {
+        return "plan authored overlay names caption track metadata";
     }
     if (overlay.shotId === undefined || overlay.shotId === null) {
         return "plan overlay names an unknown shot";
@@ -420,6 +534,7 @@ function snapshotPlan(plan) {
     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 variantFields = Object.freeze(plan.variantFields.map(snapshotVariantField));
     const videos = Object.freeze(plan.videos.map(snapshotVideo));
     const overlays = Object.freeze(plan.overlays.map(snapshotOverlay));
     return Object.freeze({
@@ -432,10 +547,17 @@ function snapshotPlan(plan) {
         scenes,
         shots,
         transitions,
+        variantFields,
         videos,
         overlays,
     });
 }
+function snapshotVariantField(field) {
+    return Object.freeze({
+        name: field.name,
+        value: Object.freeze({ ...field.value }),
+    });
+}
 function snapshotTransition(transition) {
     return Object.freeze({
         incomingShotId: transition.incomingShotId,
@@ -489,12 +611,20 @@ function snapshotFrameBoundaries([first, second, third, ...rest]) {
     return Object.freeze([first, second, third, ...rest]);
 }
 function snapshotOverlay(overlay) {
-    return Object.freeze({
+    const snapshot = {
         node: snapshotNode(overlay.node),
         shotId: overlay.shotId ?? null,
         kind: overlay.kind,
         text: overlay.text,
         interval: Object.freeze({ ...overlay.interval }),
+    };
+    const track = overlay.captionTrack;
+    if (track === undefined || track === null) {
+        return Object.freeze(snapshot);
+    }
+    return Object.freeze({
+        ...snapshot,
+        captionTrack: Object.freeze({ ...track }),
     });
 }
 function snapshotNode(node) {

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

@@ -1,5 +1,5 @@
 export type { RuntimeFrame } from "./clock.js";
-export type { BrowserMediaLayout, BrowserMediaPlacement, } from "./generated/browser-response.js";
+export type { BrowserMediaLayout, BrowserMediaPlacement, BrowserVisualFinding, BrowserVisualFindings, BrowserVisualIssue, } from "./generated/browser-response.js";
 export type { RuntimeVideo } from "./media.js";
 export type { PresentationFrameBehavior, PresentationTemporalCapability, PresentationVisualCapability, } from "./generated/bundle-layout.js";
 export type { RuntimeMediaMode, RuntimePlan } from "./session.js";