@cueframe/kernel 0.0.1

package/dist/_members/composition/validators/render.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+import { Composition } from "./composition";
+import { BrandKit } from "./brandKit";
+export const RenderPriority = z.enum(["interactive", "standard", "background"]);
+export const RenderIntent = z.enum(["preview", "final"]);
+export const RenderMode = z.enum(["offline", "live"]);
+// Cancel reasons — union of doc spec and operational realities.
+// `user`, `agent`, `cost_limit` are the doc-required triad; the rest are
+// operational reasons the worker pool needs to surface (idempotently retryable).
+export const RenderCancelReason = z.enum([
+    "user",
+    "agent",
+    "cost_limit",
+    "superseded",
+    "source_removed",
+    "timeout",
+    "error",
+]);
+// Lifecycle per data-model.md § Render (RenderJob).
+// pending → rendering → complete | error | cancelled.
+export const RenderStatus = z.enum([
+    "pending",
+    "rendering",
+    "complete",
+    "error",
+    "cancelled",
+]);
+export const RenderProgressPhase = z.object({
+    phase: z.string().min(1),
+    percent: z.number().min(0).max(100),
+    scenesTotal: z.number().int().positive().optional(),
+});
+export const RegistryPin = z.object({
+    package: z.string().min(1),
+    name: z.string().min(1),
+    version: z.string().min(1),
+});
+export const MediaSourceSnapshot = z.object({
+    mediaId: zid("mediaItems"),
+    presignedUrl: z.string().url(),
+    expiresAt: z.number().optional(),
+});
+export const RenderSnapshot = z.object({
+    composition: Composition,
+    brandKit: BrandKit.optional(),
+    mediaSources: z.array(MediaSourceSnapshot),
+    registryPins: z.array(RegistryPin),
+    capturedAt: z.number(),
+});
+// Destinations — delivery intents post-encode. R2 is always the canonical origin;
+// additional destinations are delivered in parallel after the R2 write succeeds.
+// Credentials are referenced by `credentialId` and never inlined on the request.
+export const R2Destination = z.object({
+    kind: z.literal("r2"),
+    path: z.string().optional(),
+});
+export const S3Destination = z.object({
+    kind: z.literal("s3"),
+    credentialId: z.string().min(1),
+    bucket: z.string().min(1),
+    key: z.string().min(1),
+    region: z.string().optional(),
+    acl: z.string().optional(),
+});
+export const YoutubeDestination = z.object({
+    kind: z.literal("youtube"),
+    credentialId: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().optional(),
+    privacy: z.enum(["public", "unlisted", "private"]),
+    tags: z.array(z.string()).optional(),
+});
+export const MuxDestination = z.object({
+    kind: z.literal("mux"),
+    credentialId: z.string().min(1),
+    passthrough: z.string().optional(),
+});
+export const WebhookDestination = z.object({
+    kind: z.literal("webhook"),
+    url: z.string().url(),
+    signingKeyId: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+});
+export const Destination = z.discriminatedUnion("kind", [
+    R2Destination,
+    S3Destination,
+    YoutubeDestination,
+    MuxDestination,
+    WebhookDestination,
+]);
+export const DestinationDeliveryStatus = z.enum([
+    "pending",
+    "uploading",
+    "delivered",
+    "failed",
+]);
+export const DestinationResult = z.object({
+    destinationIndex: z.number().int().nonnegative(),
+    status: DestinationDeliveryStatus,
+    url: z.string().url().optional(),
+    deliveredAt: z.number().optional(),
+    error: z.string().optional(),
+});
+export const RenderJob = z.object({
+    id: zid("renderJobs"),
+    projectId: zid("projects").optional(),
+    compositionId: zid("compositions"),
+    compositionVersionId: z.string().min(1),
+    status: RenderStatus,
+    progress: RenderProgressPhase.optional(),
+    mode: RenderMode.optional(),
+    priority: RenderPriority, // required per data-model.md § Render priority
+    intent: RenderIntent.optional(),
+    snapshot: RenderSnapshot.optional(),
+    snapshotRef: z.string().optional(),
+    outputUrl: z.string().url().optional(),
+    outputExpiresAt: z.number().optional(), // epoch ms
+    destinations: z.array(Destination).optional(),
+    destinationResults: z.array(DestinationResult).optional(),
+    cancelReason: RenderCancelReason.optional(),
+    // `error` is structured (richer than the doc's plain-string spec) so the worker
+    // can surface a stable code, a human message, and operator-visible details.
+    // See CONVEX_ADAPTATIONS.md for the rationale on richer-than-doc shapes.
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        details: z.record(z.string(), z.unknown()).optional(),
+    }).optional(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+});
+export const RenderProgress = z.object({
+    jobId: zid("renderJobs"),
+    status: RenderStatus,
+    percent: z.number().min(0).max(100).optional(),
+    framesRendered: z.number().int().nonnegative().optional(),
+    framesTotal: z.number().int().positive().optional(),
+});

package/dist/_members/composition/validators/session.d.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+export declare const SessionMediaRole: z.ZodEnum<["main", "wide", "facecam", "screen", "audio"]>;
+export type SessionMediaRole = z.infer<typeof SessionMediaRole>;
+export declare const SessionMember: z.ZodObject<{
+    mediaId: import("convex-helpers/server/zod3").Zid<"mediaItems">;
+    role: z.ZodEnum<["main", "wide", "facecam", "screen", "audio"]>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    mediaId: string & {
+        __tableName: "mediaItems";
+    };
+    role: "wide" | "audio" | "main" | "facecam" | "screen";
+    label?: string | undefined;
+}, {
+    mediaId: string & {
+        __tableName: "mediaItems";
+    };
+    role: "wide" | "audio" | "main" | "facecam" | "screen";
+    label?: string | undefined;
+}>;
+export type SessionMember = z.infer<typeof SessionMember>;
+export declare const SessionMux: z.ZodObject<{
+    videoRole: z.ZodEnum<["main", "wide", "facecam", "screen"]>;
+    audioRole: z.ZodLiteral<"audio">;
+}, "strip", z.ZodTypeAny, {
+    audioRole: "audio";
+    videoRole: "wide" | "main" | "facecam" | "screen";
+}, {
+    audioRole: "audio";
+    videoRole: "wide" | "main" | "facecam" | "screen";
+}>;
+export type SessionMux = z.infer<typeof SessionMux>;
+export declare const Session: z.ZodObject<{
+    id: import("convex-helpers/server/zod3").Zid<"sessions">;
+    name: z.ZodString;
+    members: z.ZodArray<z.ZodObject<{
+        mediaId: import("convex-helpers/server/zod3").Zid<"mediaItems">;
+        role: z.ZodEnum<["main", "wide", "facecam", "screen", "audio"]>;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mediaId: string & {
+            __tableName: "mediaItems";
+        };
+        role: "wide" | "audio" | "main" | "facecam" | "screen";
+        label?: string | undefined;
+    }, {
+        mediaId: string & {
+            __tableName: "mediaItems";
+        };
+        role: "wide" | "audio" | "main" | "facecam" | "screen";
+        label?: string | undefined;
+    }>, "atleastone">;
+    mux: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        videoRole: z.ZodEnum<["main", "wide", "facecam", "screen"]>;
+        audioRole: z.ZodLiteral<"audio">;
+    }, "strip", z.ZodTypeAny, {
+        audioRole: "audio";
+        videoRole: "wide" | "main" | "facecam" | "screen";
+    }, {
+        audioRole: "audio";
+        videoRole: "wide" | "main" | "facecam" | "screen";
+    }>, "many">>;
+    ownerOrgId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    id: string & {
+        __tableName: "sessions";
+    };
+    members: [{
+        mediaId: string & {
+            __tableName: "mediaItems";
+        };
+        role: "wide" | "audio" | "main" | "facecam" | "screen";
+        label?: string | undefined;
+    }, ...{
+        mediaId: string & {
+            __tableName: "mediaItems";
+        };
+        role: "wide" | "audio" | "main" | "facecam" | "screen";
+        label?: string | undefined;
+    }[]];
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    ownerOrgId?: string | undefined;
+    mux?: {
+        audioRole: "audio";
+        videoRole: "wide" | "main" | "facecam" | "screen";
+    }[] | undefined;
+}, {
+    id: string & {
+        __tableName: "sessions";
+    };
+    members: [{
+        mediaId: string & {
+            __tableName: "mediaItems";
+        };
+        role: "wide" | "audio" | "main" | "facecam" | "screen";
+        label?: string | undefined;
+    }, ...{
+        mediaId: string & {
+            __tableName: "mediaItems";
+        };
+        role: "wide" | "audio" | "main" | "facecam" | "screen";
+        label?: string | undefined;
+    }[]];
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    ownerOrgId?: string | undefined;
+    mux?: {
+        audioRole: "audio";
+        videoRole: "wide" | "main" | "facecam" | "screen";
+    }[] | undefined;
+}>;
+export type Session = z.infer<typeof Session>;

package/dist/_members/composition/validators/session.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+// Session per data-model.md § Session — a group of MediaItem items captured
+// together (multi-cam podcast, screen + facecam recording, two-person
+// interview on separate cameras). Each MediaItem in the session has a typed
+// `role`. Sessions can be muxed (audio role merged onto a video role).
+//
+// In a Composition, a scene references a session and specifies which angle
+// is active by role; the session resolves to a concrete `mediaId` at write
+// time and the TimelineClip stores the resolved id, not the session reference.
+export const SessionMediaRole = z.enum([
+    "main",
+    "wide",
+    "facecam",
+    "screen",
+    "audio",
+]);
+export const SessionMember = z.object({
+    mediaId: zid("mediaItems"),
+    role: SessionMediaRole,
+    label: z.string().optional(), // human-readable annotation, e.g., "host's camera"
+});
+// Mux pairing — audio role merged onto a video role at session-resolution time.
+// The renderer treats the muxed pair as a single source for sync and trim.
+export const SessionMux = z.object({
+    videoRole: z.enum(["main", "wide", "facecam", "screen"]),
+    audioRole: z.literal("audio"),
+});
+export const Session = z.object({
+    id: zid("sessions"),
+    name: z.string().min(1),
+    members: z.array(SessionMember).nonempty(),
+    mux: z.array(SessionMux).optional(),
+    ownerOrgId: z.string().optional(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+});

package/dist/_members/composition/validators/webhook.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+export declare const SubstrateWebhookEvent: z.ZodEnum<["render.completed", "media.transcribed", "media.completed", "composition.updated"]>;
+export type SubstrateWebhookEvent = z.infer<typeof SubstrateWebhookEvent>;
+export declare const WebhookDeliveryStatus: z.ZodEnum<["pending", "delivering", "delivered", "failed", "exhausted"]>;
+export type WebhookDeliveryStatus = z.infer<typeof WebhookDeliveryStatus>;
+export declare const Webhook: z.ZodObject<{
+    id: import("convex-helpers/server/zod3").Zid<"webhooks">;
+    url: z.ZodString;
+    events: z.ZodArray<z.ZodString, "atleastone">;
+    signingKeyId: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    ownerOrgId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    id: string & {
+        __tableName: "webhooks";
+    };
+    url: string;
+    createdAt: number;
+    updatedAt: number;
+    events: [string, ...string[]];
+    enabled?: boolean | undefined;
+    ownerOrgId?: string | undefined;
+    signingKeyId?: string | undefined;
+    headers?: Record<string, string> | undefined;
+}, {
+    id: string & {
+        __tableName: "webhooks";
+    };
+    url: string;
+    createdAt: number;
+    updatedAt: number;
+    events: [string, ...string[]];
+    enabled?: boolean | undefined;
+    ownerOrgId?: string | undefined;
+    signingKeyId?: string | undefined;
+    headers?: Record<string, string> | undefined;
+}>;
+export type Webhook = z.infer<typeof Webhook>;
+export declare const WebhookDelivery: z.ZodObject<{
+    id: z.ZodString;
+    webhookId: import("convex-helpers/server/zod3").Zid<"webhooks">;
+    event: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    status: z.ZodEnum<["pending", "delivering", "delivered", "failed", "exhausted"]>;
+    attemptCount: z.ZodNumber;
+    responseStatus: z.ZodOptional<z.ZodNumber>;
+    responseBody: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    deliveredAt: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    status: "pending" | "failed" | "delivered" | "delivering" | "exhausted";
+    createdAt: number;
+    webhookId: string & {
+        __tableName: "webhooks";
+    };
+    event: string;
+    payload: Record<string, unknown>;
+    attemptCount: number;
+    error?: string | undefined;
+    deliveredAt?: number | undefined;
+    responseStatus?: number | undefined;
+    responseBody?: string | undefined;
+}, {
+    id: string;
+    status: "pending" | "failed" | "delivered" | "delivering" | "exhausted";
+    createdAt: number;
+    webhookId: string & {
+        __tableName: "webhooks";
+    };
+    event: string;
+    payload: Record<string, unknown>;
+    attemptCount: number;
+    error?: string | undefined;
+    deliveredAt?: number | undefined;
+    responseStatus?: number | undefined;
+    responseBody?: string | undefined;
+}>;
+export type WebhookDelivery = z.infer<typeof WebhookDelivery>;

package/dist/_members/composition/validators/webhook.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+// Webhook per data-model.md — subscriber URLs that receive events for
+// substrate state transitions (renders, media, font, composition).
+// Delivery is at-least-once, with Standard Webhooks signing.
+//
+// Domain-extensible event names: `Webhook.events` is `string[]` so domain
+// packages (e.g. @cueframe/clip-model) can contribute their own event
+// vocabulary without forcing substrate to know about them. Each domain exports
+// its own typed enum (e.g. ClipsWebhookEvent) that consumers compose into the
+// `events` array; the substrate's SubstrateWebhookEvent enum below is the
+// canonical list of substrate-emitted events. The webhook delivery
+// infrastructure routes any event name.
+//
+// EMITTED-ONLY SSOT (#16 webhook-vocab honesty). This enum lists ONLY the
+// render/media/composition lifecycle events the substrate ACTUALLY fires (an
+// `event:` literal routed to webhooksFire.fireEvent). The previously-advertised
+// `render.queued/started/delivered/delivery_failed`, `media.uploaded`,
+// `media.spatial_ready`, `media.transcript_ready`, and the `font.*` family were
+// REMOVED: nothing emits them. Honesty over aspiration — advertising a webhook
+// the agent can never receive silently breaks its progress tracking. The convex
+// parity gate (api.webhookVocabParity.test.ts) asserts every value here has a
+// real emit site.
+export const SubstrateWebhookEvent = z.enum([
+    // Render lifecycle — A3 terminal family (plan 2026-07-10-flow-checkpoint):
+    // ONE terminal event per kind, `status` INSIDE the payload.
+    "render.completed",
+    // MediaItem lifecycle
+    "media.transcribed",
+    "media.completed",
+    // Composition lifecycle
+    "composition.updated",
+]);
+export const WebhookDeliveryStatus = z.enum([
+    "pending",
+    "delivering",
+    "delivered",
+    "failed",
+    "exhausted", // retry budget burned through
+]);
+export const Webhook = z.object({
+    id: zid("webhooks"),
+    url: z.string().url(),
+    // Open string array — substrate event names live in SubstrateWebhookEvent;
+    // domain packages export their own event enums and consumers compose them.
+    events: z.array(z.string().min(1)).nonempty(),
+    // Standard Webhooks signing key reference; the signing secret itself is
+    // stored server-side and never round-tripped through the API surface.
+    signingKeyId: z.string().optional(),
+    // Optional headers the subscriber wants on every delivery.
+    headers: z.record(z.string(), z.string()).optional(),
+    enabled: z.boolean().optional(),
+    ownerOrgId: z.string().optional(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+});
+// Per-attempt delivery record. Useful for the operator dashboard and for
+// the subscriber's "what did you receive" replay surface.
+export const WebhookDelivery = z.object({
+    id: z.string().min(1),
+    webhookId: zid("webhooks"),
+    // Open string — could be any substrate or domain event name.
+    event: z.string().min(1),
+    payload: z.record(z.string(), z.unknown()),
+    status: WebhookDeliveryStatus,
+    attemptCount: z.number().int().nonnegative(),
+    responseStatus: z.number().int().optional(),
+    responseBody: z.string().optional(),
+    error: z.string().optional(),
+    createdAt: z.number(),
+    deliveredAt: z.number().optional(),
+});

package/dist/_members/composition-ops/alphaLayers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Alpha-layer clip walk — the SINGLE shared, V8-safe home for finding a wire
+ * composition's alpha-layer clips (overlay-track clips whose
+ * `source.kind === 'alpha-layer'`).
+ *
+ * This is PURE and crypto-free on purpose: both the director (Node worker, which
+ * bakes the alpha) and Convex (V8 isolate, which materializes the authored
+ * tsxSource into the stage body) walk the SAME composition for the SAME clips —
+ * so the walk is the SSOT and lives here, importable from both. The director's
+ * content-hash (`alphaLayerHash`, uses `node:crypto`) stays director-side; it is
+ * NOT shareable with the V8 isolate and is orthogonal to the walk.
+ */
+export interface AlphaLayerClipRef {
+    clipId: string;
+    componentId: string;
+    props: Record<string, unknown>;
+    /** timeline seconds (used to derive the bake's durationInFrames) */
+    startTime: number;
+    duration: number;
+}
+/**
+ * Walk a wire composition for alpha-layer clips (overlay-track clips whose
+ * `source.kind === 'alpha-layer'`). Pure + tolerant of unknown shape (skips
+ * malformed entries rather than throwing — the validator already gated saves).
+ */
+export declare function collectAlphaLayerClips(composition: unknown): AlphaLayerClipRef[];
+/**
+ * Walk a wire composition for RAW `component` clip sources — sources that have
+ * NOT been desugared and therefore cannot be projected by the renderer.
+ *
+ * `component` is a first-class `ClipSource` in the validator, but it is an
+ * AUTHORING shape, never a render one: the cloud's save/writer chokepoint
+ * (`the server's composition projection`) lowers every one of them to an
+ * `alpha-layer` or a `custom` overlay before it is persisted, reading the
+ * component's `executionMode` from the `installedComponents` table. Anything
+ * that reaches `projectOverlayTrack` still wearing `kind:'component'` throws
+ * `kind=component is invalid on an overlay track`.
+ *
+ * That throw is why this exists. On the desktop lane there is no such
+ * chokepoint (and no registry to lower against), so an agent-authored component
+ * clip committed straight to the store, the preview projected it during render,
+ * and the throw escaped a `useMemo` into the app-root ErrorBoundary — the entire
+ * editor replaced by "Something went wrong", with the broken composition saved,
+ * so every subsequent open died the same way. Observed 2026-08-18.
+ *
+ * Two callers, which is the point of putting it here rather than in either of
+ * them: the desktop plane REFUSES an apply that would create one, and the
+ * preview GATE holds the player with a readable reason if a project already
+ * contains one. The first stops the state being reachable; the second is how
+ * anyone who already reached it gets their project open again.
+ *
+ * Pure + tolerant of unknown shape, like its siblings above.
+ */
+export declare function collectRawComponentClips(composition: unknown): string[];
+export interface LiveComponentClipRef {
+    clipId: string;
+    componentId: string;
+}
+/**
+ * Walk a wire composition for LIVE component-backed `custom` overlays — the
+ * bakeless-lane peer of `collectAlphaLayerClips`. A live component desugars (at
+ * the save writer) to `{ kind:'overlay', primitiveId:'custom', params:{
+ * componentId, ...props } }` — a componentId REFERENCE with no frozen source.
+ * The renderJob-create path (renders.ts) walks these to materialize each
+ * component's FRESH transpiled jsSource per render (keyed by clipId). Pure +
+ * tolerant of unknown shape. Desktop-INLINE customs (which carry their own
+ * `params.sourceCode` and no `componentId`) are NOT returned — they need no
+ * materialization.
+ */
+export declare function collectLiveComponentClips(composition: unknown): LiveComponentClipRef[];

package/dist/_members/composition-ops/alphaLayers.js

@@ -0,0 +1,141 @@
+/**
+ * Alpha-layer clip walk — the SINGLE shared, V8-safe home for finding a wire
+ * composition's alpha-layer clips (overlay-track clips whose
+ * `source.kind === 'alpha-layer'`).
+ *
+ * This is PURE and crypto-free on purpose: both the director (Node worker, which
+ * bakes the alpha) and Convex (V8 isolate, which materializes the authored
+ * tsxSource into the stage body) walk the SAME composition for the SAME clips —
+ * so the walk is the SSOT and lives here, importable from both. The director's
+ * content-hash (`alphaLayerHash`, uses `node:crypto`) stays director-side; it is
+ * NOT shareable with the V8 isolate and is orthogonal to the walk.
+ */
+/**
+ * Walk a wire composition for alpha-layer clips (overlay-track clips whose
+ * `source.kind === 'alpha-layer'`). Pure + tolerant of unknown shape (skips
+ * malformed entries rather than throwing — the validator already gated saves).
+ */
+export function collectAlphaLayerClips(composition) {
+    const tracks = composition?.tracks;
+    if (!Array.isArray(tracks))
+        return [];
+    const out = [];
+    for (const track of tracks) {
+        const contents = track?.contents;
+        if (!Array.isArray(contents))
+            continue;
+        for (const c of contents) {
+            const src = c?.source;
+            if (!src || typeof src !== "object")
+                continue;
+            if (src.kind !== "alpha-layer")
+                continue;
+            const componentId = src.componentId;
+            const clipId = c.id;
+            const startTime = c.startTime;
+            const duration = c.duration;
+            if (typeof componentId !== "string" || componentId.length === 0)
+                continue;
+            if (typeof clipId !== "string" || clipId.length === 0)
+                continue;
+            if (typeof startTime !== "number" || typeof duration !== "number" || duration <= 0)
+                continue;
+            const rawProps = src.props;
+            const props = rawProps && typeof rawProps === "object" && !Array.isArray(rawProps)
+                ? rawProps
+                : {};
+            out.push({ clipId, componentId, props, startTime, duration });
+        }
+    }
+    return out;
+}
+/**
+ * Walk a wire composition for RAW `component` clip sources — sources that have
+ * NOT been desugared and therefore cannot be projected by the renderer.
+ *
+ * `component` is a first-class `ClipSource` in the validator, but it is an
+ * AUTHORING shape, never a render one: the cloud's save/writer chokepoint
+ * (`services/convex/composition/projection.ts`) lowers every one of them to an
+ * `alpha-layer` or a `custom` overlay before it is persisted, reading the
+ * component's `executionMode` from the `installedComponents` table. Anything
+ * that reaches `projectOverlayTrack` still wearing `kind:'component'` throws
+ * `kind=component is invalid on an overlay track`.
+ *
+ * That throw is why this exists. On the desktop lane there is no such
+ * chokepoint (and no registry to lower against), so an agent-authored component
+ * clip committed straight to the store, the preview projected it during render,
+ * and the throw escaped a `useMemo` into the app-root ErrorBoundary — the entire
+ * editor replaced by "Something went wrong", with the broken composition saved,
+ * so every subsequent open died the same way. Observed 2026-08-18.
+ *
+ * Two callers, which is the point of putting it here rather than in either of
+ * them: the desktop plane REFUSES an apply that would create one, and the
+ * preview GATE holds the player with a readable reason if a project already
+ * contains one. The first stops the state being reachable; the second is how
+ * anyone who already reached it gets their project open again.
+ *
+ * Pure + tolerant of unknown shape, like its siblings above.
+ */
+export function collectRawComponentClips(composition) {
+    const tracks = composition?.tracks;
+    if (!Array.isArray(tracks))
+        return [];
+    const out = [];
+    for (const track of tracks) {
+        const contents = track?.contents;
+        if (!Array.isArray(contents))
+            continue;
+        for (const c of contents) {
+            const src = c?.source;
+            if (!src || typeof src !== "object")
+                continue;
+            if (src.kind !== "component")
+                continue;
+            const id = c.id;
+            out.push(typeof id === "string" && id.length > 0 ? id : "(unnamed clip)");
+        }
+    }
+    return out;
+}
+/**
+ * Walk a wire composition for LIVE component-backed `custom` overlays — the
+ * bakeless-lane peer of `collectAlphaLayerClips`. A live component desugars (at
+ * the save writer) to `{ kind:'overlay', primitiveId:'custom', params:{
+ * componentId, ...props } }` — a componentId REFERENCE with no frozen source.
+ * The renderJob-create path (renders.ts) walks these to materialize each
+ * component's FRESH transpiled jsSource per render (keyed by clipId). Pure +
+ * tolerant of unknown shape. Desktop-INLINE customs (which carry their own
+ * `params.sourceCode` and no `componentId`) are NOT returned — they need no
+ * materialization.
+ */
+export function collectLiveComponentClips(composition) {
+    const tracks = composition?.tracks;
+    if (!Array.isArray(tracks))
+        return [];
+    const out = [];
+    for (const track of tracks) {
+        const contents = track?.contents;
+        if (!Array.isArray(contents))
+            continue;
+        for (const c of contents) {
+            const src = c?.source;
+            if (!src || typeof src !== "object")
+                continue;
+            if (src.kind !== "overlay")
+                continue;
+            if (src.primitiveId !== "custom")
+                continue;
+            const params = src.params;
+            const componentId = params && typeof params === "object"
+                ? params.componentId
+                : undefined;
+            const clipId = c.id;
+            if (typeof componentId !== "string" || componentId.length === 0)
+                continue;
+            if (typeof clipId !== "string" || clipId.length === 0)
+                continue;
+            out.push({ clipId, componentId });
+        }
+    }
+    return out;
+}