@cueframe/kernel 0.0.1

package/dist/_members/composition/ops/headlessStore.d.ts

@@ -0,0 +1,40 @@
+import { Composition } from '../validators/index.js';
+import { type CompositionOps } from './compositionOps.js';
+import type { CompositionOpsState } from './types.js';
+export interface HeadlessStore extends CompositionOps {
+    getState: () => CompositionOpsState;
+    /** Transaction grouping — a headless store has no history, so this is
+     *  just `fn()`; it exists so HeadlessStore stays structurally a
+     *  CompositionStore (the apply lane's contract). */
+    batch: (fn: () => void) => void;
+}
+export declare function emptyComposition(): Composition;
+/**
+ * Initial composition seeded with the source A-roll clip on a video track.
+ *
+ * Compose-from-suggestion hydrates a *fresh* project → an empty composition (no
+ * clips). But the agent's `set_crop_intents` / `enable_captions_behind_speaker`
+ * operate on the store's video clip — with no clip they're rejected ("No video
+ * track") and the crop/captions-behind silently never land. The source clip is
+ * a GIVEN (the suggestion window), so it belongs in the initial state, not as an
+ * agent edit. Seed it here (matches the canonical serializer's `clip-0`:
+ * id `clip-0`, startTime 0, duration = window length, `media` source + trim).
+ *
+ * Built loosely then `safeParse`d (the serializer's pattern) so the raw id
+ * string brands to the wire-shape Convex Id through the schema — no hand-written
+ * type cast — and the seed is runtime-validated as a bonus.
+ */
+export declare function compositionWithSourceClip(spec: {
+    mediaId: string;
+    /** Source-relative seconds — the clip's `trim` window. */
+    startTime: number;
+    endTime: number;
+    format: Composition['format'];
+}): Composition;
+export declare function emptyCompositionState(): CompositionOpsState;
+/**
+ * Headless wrapper used server-side (Director worker, tests). Accepts either
+ * a full `CompositionOpsState` or a bare `Composition` (which is then wrapped
+ * with default selection state).
+ */
+export declare function createHeadlessStore(initial?: Composition | CompositionOpsState): HeadlessStore;

package/dist/_members/composition/ops/headlessStore.js

@@ -0,0 +1,94 @@
+import { produce } from 'immer';
+import { Composition } from '../validators';
+import { createCompositionOps } from './compositionOps';
+export function emptyComposition() {
+    return { v: 1, format: { aspectRatio: '16:9' }, tracks: [] };
+}
+/**
+ * Initial composition seeded with the source A-roll clip on a video track.
+ *
+ * Compose-from-suggestion hydrates a *fresh* project → an empty composition (no
+ * clips). But the agent's `set_crop_intents` / `enable_captions_behind_speaker`
+ * operate on the store's video clip — with no clip they're rejected ("No video
+ * track") and the crop/captions-behind silently never land. The source clip is
+ * a GIVEN (the suggestion window), so it belongs in the initial state, not as an
+ * agent edit. Seed it here (matches the canonical serializer's `clip-0`:
+ * id `clip-0`, startTime 0, duration = window length, `media` source + trim).
+ *
+ * Built loosely then `safeParse`d (the serializer's pattern) so the raw id
+ * string brands to the wire-shape Convex Id through the schema — no hand-written
+ * type cast — and the seed is runtime-validated as a bonus.
+ */
+export function compositionWithSourceClip(spec) {
+    const parsed = Composition.safeParse({
+        v: 1,
+        format: spec.format,
+        tracks: [
+            {
+                id: 'track-video',
+                kind: 'video',
+                name: 'Main video',
+                contents: [
+                    {
+                        id: 'clip-0',
+                        startTime: 0,
+                        duration: Math.max(0, spec.endTime - spec.startTime),
+                        source: {
+                            kind: 'media',
+                            mediaId: spec.mediaId,
+                            trim: { start: spec.startTime, end: spec.endTime },
+                        },
+                    },
+                ],
+            },
+        ],
+    });
+    if (!parsed.success) {
+        throw new Error(`compositionWithSourceClip: produced an invalid composition — ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+export function emptyCompositionState() {
+    return {
+        composition: emptyComposition(),
+        selection: [],
+        selectedClipId: null,
+        selectedOverlayId: null,
+    };
+}
+/**
+ * Headless wrapper used server-side (Director worker, tests). Accepts either
+ * a full `CompositionOpsState` or a bare `Composition` (which is then wrapped
+ * with default selection state).
+ */
+export function createHeadlessStore(initial) {
+    let state;
+    if (!initial) {
+        state = emptyCompositionState();
+    }
+    else if ('composition' in initial) {
+        state = initial;
+    }
+    else {
+        state = {
+            composition: initial,
+            selection: [],
+            selectedClipId: null,
+            selectedOverlayId: null,
+        };
+    }
+    const get = () => state;
+    const set = (fnOrPartial) => {
+        if (typeof fnOrPartial === 'function') {
+            state = produce(state, fnOrPartial);
+        }
+        else {
+            state = { ...state, ...fnOrPartial };
+        }
+    };
+    return {
+        ...createCompositionOps(get, set),
+        getState: get,
+        batch: (fn) => fn(),
+    };
+}

package/dist/_members/composition/ops/index.d.ts

@@ -0,0 +1,6 @@
+export { createCompositionOps, type CompositionOps, findOrCreateTrackByKind, findClipById, findTrackContainingClipId, findMarkerById, type TrackKind, } from './compositionOps.js';
+export { createHeadlessStore, emptyComposition, compositionWithSourceClip, emptyCompositionState, type HeadlessStore, } from './headlessStore.js';
+export { selectAllTracks, selectTracksByKind, selectAllClips, selectMediaClipAt, selectAllOverlays, selectAllAudioClips, selectClipById, selectMarkers, selectSceneMarkers, describeFrameAt, type FrameLayers, } from './selectors.js';
+export { mergeTimelineTranscripts, formatWordTimings, type Transcript, type TranscriptSegment, } from './transcript.js';
+export type { CompositionOpsState, CompositionData, ClipPropertyUpdates, OpsSet, OpsGet, DeletedRange, SceneLabel, ContentSource, EffectConfig, TextEffectConfig, TextConfig, TransitionConfig, LayoutConfig, GlobalEffects, Scene, EffectTarget, EffectInstance, } from './types.js';
+export type { TimelineWord, TimedWordAttrs } from './timeline-word.js';

package/dist/_members/composition/ops/index.js

@@ -0,0 +1,4 @@
+export { createCompositionOps, findOrCreateTrackByKind, findClipById, findTrackContainingClipId, findMarkerById, } from './compositionOps';
+export { createHeadlessStore, emptyComposition, compositionWithSourceClip, emptyCompositionState, } from './headlessStore';
+export { selectAllTracks, selectTracksByKind, selectAllClips, selectMediaClipAt, selectAllOverlays, selectAllAudioClips, selectClipById, selectMarkers, selectSceneMarkers, describeFrameAt, } from './selectors';
+export { mergeTimelineTranscripts, formatWordTimings, } from './transcript';

package/dist/_members/composition/ops/selectors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Selectors for the v2 wire-shape Composition. Mirrors the desktop store's
+ * selectors so headless callers (agent, Director worker, tests) get the same
+ * flattened views without re-implementing track-walking everywhere.
+ */
+import type { Composition, Track, TimelineClip, Marker } from '../validators/index.js';
+/** All tracks in declared order. The Timeline UI projects these 1:1 to `TimelineRow`s. */
+export declare function selectAllTracks(composition: Composition): Track[];
+/** Tracks of a given kind, declared order preserved. */
+export declare function selectTracksByKind(composition: Composition, kind: Track['kind']): Track[];
+/** Flatten all video-track clips into a single array, in track + content order. */
+export declare function selectAllClips(composition: Composition): TimelineClip[];
+/**
+ * THE MEDIA CLIP ON SCREEN AT `seconds` — the clip whose bytes a still drawn at
+ * that instant comes from, or `null` when nothing media-backed covers it (a
+ * gap, a card-only stretch, past the end).
+ *
+ * ONE RULE, TWO READERS, and that is why it lives in the kernel rather than in
+ * either of them. The desktop's frame capture resolves the video file to
+ * extract from this clip; the verb plane routes that capture by the SAME clip's
+ * media residency BEFORE calling it, so that a still is never asked for from
+ * bytes the machine cannot open. Two spellings of "which clip is on screen"
+ * would let the router clear a frame the renderer then draws from something
+ * else.
+ *
+ * VIDEO TRACKS, in track + content order, and a non-media clip is SKIPPED
+ * rather than ending the search: a card sitting over a video does not replace
+ * the pixels underneath it.
+ *
+ * Half-open `[startTime, startTime + duration)` — a clip's last instant belongs
+ * to whatever follows it, which is the boundary the renderer draws.
+ */
+export declare function selectMediaClipAt(composition: Composition, seconds: number): TimelineClip | null;
+/** Flatten all overlay-track clips. */
+export declare function selectAllOverlays(composition: Composition): TimelineClip[];
+/** What a frame drawn at one instant is actually made of. */
+export interface FrameLayers {
+    /**
+     * `mediaId` of the media clip covering this instant, or `null` when nothing
+     * media-backed does — a gap, a card-only stretch, or a timeline with no
+     * footage in it at all.
+     */
+    video: string | null;
+    /** How many overlay-track clips are active at this instant. */
+    overlays: number;
+}
+/**
+ * THE LAYER CENSUS AT `seconds` — what a still drawn here contains, stated in
+ * words rather than left for the reader to infer from pixels.
+ *
+ * WHY THIS EXISTS. A preview is an agent's only evidence about a composition,
+ * and pixels alone cannot distinguish "my edit did not land" from "there is no
+ * footage under this timestamp". On 2026-08-14 a desktop run applied ops and
+ * previewed ten times against an EMPTY library: every capture succeeded, every
+ * still came back 200 OK, and the only record that the frames had no video in
+ * them was a `console.warn` in the app's own log — invisible to the agent that
+ * needed it. It kept editing something that was never going to be a video, then
+ * gave up. The frames were not broken; the instrument simply never said what it
+ * had drawn.
+ *
+ * This is the same correction `geometry` made for SIZE (2026-08-13, after an
+ * agent measured text in a quarter-scale still and rewrote a video to avoid
+ * cards): when a preview omits a fact about itself, an agent will infer a wrong
+ * one. State it.
+ *
+ * IN THE KERNEL, because both preview lanes must answer this identically. The
+ * desktop plane draws its own stills and the cloud route renders them through
+ * Modal, but an agent moving between the two reads ONE shape — the property the
+ * plane exists to hold. A second spelling of "what is on screen" is exactly the
+ * drift that makes local and cloud disagree.
+ *
+ * `overlays` is a COUNT, not a judgement: a frame with no video and one overlay
+ * is a legitimate card — not an error, and deliberately not refused. The agent
+ * is told what is there and decides for itself.
+ */
+export declare function describeFrameAt(composition: Composition, seconds: number): FrameLayers;
+/** Flatten all audio-track clips. */
+export declare function selectAllAudioClips(composition: Composition): TimelineClip[];
+export declare function selectClipById(composition: Composition, id: string): TimelineClip | undefined;
+export declare function selectMarkers(composition: Composition): Marker[];
+export declare function selectSceneMarkers(composition: Composition): Marker[];

package/dist/_members/composition/ops/selectors.js

@@ -0,0 +1,118 @@
+/**
+ * Selectors for the v2 wire-shape Composition. Mirrors the desktop store's
+ * selectors so headless callers (agent, Director worker, tests) get the same
+ * flattened views without re-implementing track-walking everywhere.
+ */
+/** All tracks in declared order. The Timeline UI projects these 1:1 to `TimelineRow`s. */
+export function selectAllTracks(composition) {
+    return composition.tracks;
+}
+/** Tracks of a given kind, declared order preserved. */
+export function selectTracksByKind(composition, kind) {
+    return composition.tracks.filter((t) => t.kind === kind);
+}
+/** Flatten all video-track clips into a single array, in track + content order. */
+export function selectAllClips(composition) {
+    return composition.tracks
+        .filter((t) => t.kind === 'video')
+        .flatMap((t) => t.contents.filter((c) => 'source' in c));
+}
+/**
+ * THE MEDIA CLIP ON SCREEN AT `seconds` — the clip whose bytes a still drawn at
+ * that instant comes from, or `null` when nothing media-backed covers it (a
+ * gap, a card-only stretch, past the end).
+ *
+ * ONE RULE, TWO READERS, and that is why it lives in the kernel rather than in
+ * either of them. The desktop's frame capture resolves the video file to
+ * extract from this clip; the verb plane routes that capture by the SAME clip's
+ * media residency BEFORE calling it, so that a still is never asked for from
+ * bytes the machine cannot open. Two spellings of "which clip is on screen"
+ * would let the router clear a frame the renderer then draws from something
+ * else.
+ *
+ * VIDEO TRACKS, in track + content order, and a non-media clip is SKIPPED
+ * rather than ending the search: a card sitting over a video does not replace
+ * the pixels underneath it.
+ *
+ * Half-open `[startTime, startTime + duration)` — a clip's last instant belongs
+ * to whatever follows it, which is the boundary the renderer draws.
+ */
+export function selectMediaClipAt(composition, seconds) {
+    for (const clip of selectAllClips(composition)) {
+        if (seconds < clip.startTime)
+            continue;
+        if (seconds >= clip.startTime + clip.duration)
+            continue;
+        if (clip.source.kind !== 'media')
+            continue;
+        return clip;
+    }
+    return null;
+}
+/** Flatten all overlay-track clips. */
+export function selectAllOverlays(composition) {
+    return composition.tracks
+        .filter((t) => t.kind === 'overlay')
+        .flatMap((t) => t.contents.filter((c) => 'source' in c));
+}
+/**
+ * THE LAYER CENSUS AT `seconds` — what a still drawn here contains, stated in
+ * words rather than left for the reader to infer from pixels.
+ *
+ * WHY THIS EXISTS. A preview is an agent's only evidence about a composition,
+ * and pixels alone cannot distinguish "my edit did not land" from "there is no
+ * footage under this timestamp". On 2026-08-14 a desktop run applied ops and
+ * previewed ten times against an EMPTY library: every capture succeeded, every
+ * still came back 200 OK, and the only record that the frames had no video in
+ * them was a `console.warn` in the app's own log — invisible to the agent that
+ * needed it. It kept editing something that was never going to be a video, then
+ * gave up. The frames were not broken; the instrument simply never said what it
+ * had drawn.
+ *
+ * This is the same correction `geometry` made for SIZE (2026-08-13, after an
+ * agent measured text in a quarter-scale still and rewrote a video to avoid
+ * cards): when a preview omits a fact about itself, an agent will infer a wrong
+ * one. State it.
+ *
+ * IN THE KERNEL, because both preview lanes must answer this identically. The
+ * desktop plane draws its own stills and the cloud route renders them through
+ * Modal, but an agent moving between the two reads ONE shape — the property the
+ * plane exists to hold. A second spelling of "what is on screen" is exactly the
+ * drift that makes local and cloud disagree.
+ *
+ * `overlays` is a COUNT, not a judgement: a frame with no video and one overlay
+ * is a legitimate card — not an error, and deliberately not refused. The agent
+ * is told what is there and decides for itself.
+ */
+export function describeFrameAt(composition, seconds) {
+    const clip = selectMediaClipAt(composition, seconds);
+    // Half-open `[startTime, startTime + duration)`, the same boundary
+    // `selectMediaClipAt` uses — so the two halves of one census cannot disagree
+    // about which side of a cut an instant falls on.
+    const overlays = selectAllOverlays(composition).filter((c) => seconds >= c.startTime && seconds < c.startTime + c.duration).length;
+    return {
+        video: clip !== null && clip.source.kind === 'media' ? clip.source.mediaId : null,
+        overlays,
+    };
+}
+/** Flatten all audio-track clips. */
+export function selectAllAudioClips(composition) {
+    return composition.tracks
+        .filter((t) => t.kind === 'audio')
+        .flatMap((t) => t.contents.filter((c) => 'source' in c));
+}
+export function selectClipById(composition, id) {
+    for (const t of composition.tracks) {
+        for (const c of t.contents) {
+            if ('source' in c && c.id === id)
+                return c;
+        }
+    }
+    return undefined;
+}
+export function selectMarkers(composition) {
+    return composition.markers ?? [];
+}
+export function selectSceneMarkers(composition) {
+    return (composition.markers ?? []).filter((m) => m.kind === 'scene');
+}

package/dist/_members/composition/ops/timeline-word.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Timeline word + timed-word attrs — relocated from @cueframe/core (2026-06-10).
+ * Computed (transcript projected onto the timeline), read by authoring/the editor.
+ * Composition is the SSOT, so these live here, not in the renderer (core/execution).
+ */
+export interface TimelineWord {
+    text: string;
+    timelineStart: number;
+    timelineEnd: number;
+    clipId: string;
+    poolItemId: string;
+    sourceStart: number;
+    sourceEnd: number;
+    speakerId: string | null;
+}
+export interface TimedWordAttrs {
+    start: number;
+    end: number;
+    sourceStart: number;
+    sourceEnd: number;
+    clipId: string;
+    poolItemId: string;
+    speakerId: string | null;
+}

package/dist/_members/composition/ops/timeline-word.js

@@ -0,0 +1 @@
+export {};

package/dist/_members/composition/ops/transcript.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure functions for merging per-clip transcripts into timeline-ordered words.
+ * Lives in @cueframe/core because it operates on composition data (clips +
+ * transcripts) with no dependency on stores, DOM, or runtime environment.
+ *
+ * v2 wire-shape: walks `TimelineClip`s straight off composition tracks. Each
+ * clip references its source via `source: { kind: 'media', mediaId, trim?,
+ * playbackRate?, muted? }`; cuts are baked into clip startTime/duration so
+ * there is no deletion-range filtering step.
+ *
+ * Output is the v1-shape `TimelineWord` from `@cueframe/core/types` so the
+ * agent context layer (which still reads `word.poolItemId`) keeps working.
+ * The "poolItemId" field carries the wire-shape `mediaId` value — same
+ * semantic, retained name for back-compat.
+ */
+import type { TimelineClip } from '../validators/index.js';
+import type { TimelineWord } from './timeline-word.js';
+export interface TranscriptSegment {
+    text: string;
+    startTime: number;
+    endTime: number;
+    speakerId: string | null;
+}
+export interface Transcript {
+    segments: TranscriptSegment[];
+}
+/**
+ * Merges transcripts from multiple clips into a single timeline-ordered word list.
+ * Each clip's transcript segments are filtered to its source range and re-mapped
+ * to timeline positions.
+ *
+ * Deduplication: segments with the same (mediaId, sourceStartTime) pair are emitted
+ * only once, preventing duplicates when clips have overlapping source ranges.
+ */
+export declare function mergeTimelineTranscripts(clips: TimelineClip[], transcripts: Record<string, Transcript>): TimelineWord[];
+/**
+ * Format word timings for a given time range into a human-readable string.
+ * Used by the Director's TranscriptProvider.getWordTimings() capability.
+ */
+export declare function formatWordTimings(words: Array<{
+    text: string;
+    timelineStart: number;
+    timelineEnd: number;
+}>, startTime: number, endTime: number): string;

package/dist/_members/composition/ops/transcript.js

@@ -0,0 +1,77 @@
+/**
+ * Pure functions for merging per-clip transcripts into timeline-ordered words.
+ * Lives in @cueframe/core because it operates on composition data (clips +
+ * transcripts) with no dependency on stores, DOM, or runtime environment.
+ *
+ * v2 wire-shape: walks `TimelineClip`s straight off composition tracks. Each
+ * clip references its source via `source: { kind: 'media', mediaId, trim?,
+ * playbackRate?, muted? }`; cuts are baked into clip startTime/duration so
+ * there is no deletion-range filtering step.
+ *
+ * Output is the v1-shape `TimelineWord` from `@cueframe/core/types` so the
+ * agent context layer (which still reads `word.poolItemId`) keeps working.
+ * The "poolItemId" field carries the wire-shape `mediaId` value — same
+ * semantic, retained name for back-compat.
+ */
+/**
+ * Merges transcripts from multiple clips into a single timeline-ordered word list.
+ * Each clip's transcript segments are filtered to its source range and re-mapped
+ * to timeline positions.
+ *
+ * Deduplication: segments with the same (mediaId, sourceStartTime) pair are emitted
+ * only once, preventing duplicates when clips have overlapping source ranges.
+ */
+export function mergeTimelineTranscripts(clips, transcripts) {
+    const words = [];
+    const seen = new Set();
+    for (const clip of clips) {
+        if (clip.source.kind !== 'media')
+            continue;
+        if (clip.source.muted)
+            continue;
+        const mediaId = clip.source.mediaId;
+        const transcript = transcripts[mediaId];
+        if (!transcript?.segments)
+            continue;
+        const trimStart = clip.source.trim?.start ?? 0;
+        const trimEnd = clip.source.trim?.end ?? clip.duration;
+        const rate = clip.source.playbackRate ?? 1;
+        // Filter segments that START within clip's source range.
+        // Inclusive start (>=) is intentional: Whisper words often have zero-gap
+        // boundaries so a micro-fade shift to trim.start would exclude the neighbor word.
+        const clippedSegments = transcript.segments.filter((seg) => seg.startTime >= trimStart && seg.startTime < trimEnd);
+        for (const segment of clippedSegments) {
+            const key = `${mediaId}:${segment.startTime}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const clampedEnd = Math.min(segment.endTime, trimEnd);
+            words.push({
+                text: segment.text,
+                timelineStart: clip.startTime + (segment.startTime - trimStart) / rate,
+                timelineEnd: clip.startTime + (clampedEnd - trimStart) / rate,
+                clipId: clip.id,
+                // The v1 TimelineWord field is named `poolItemId`; v2 calls it
+                // `mediaId`. Same semantic — retain v1 name on the wire so the
+                // agent context (which reads `word.poolItemId`) keeps working.
+                poolItemId: mediaId,
+                sourceStart: segment.startTime,
+                sourceEnd: clampedEnd,
+                speakerId: segment.speakerId,
+            });
+        }
+    }
+    return words.sort((a, b) => a.timelineStart - b.timelineStart);
+}
+/**
+ * Format word timings for a given time range into a human-readable string.
+ * Used by the Director's TranscriptProvider.getWordTimings() capability.
+ */
+export function formatWordTimings(words, startTime, endTime) {
+    const rangeWords = words.filter((w) => w.timelineEnd > startTime && w.timelineStart < endTime);
+    if (rangeWords.length === 0) {
+        return `No words found in range ${startTime.toFixed(1)}s–${endTime.toFixed(1)}s`;
+    }
+    const lines = rangeWords.map((w) => `${w.text}=${w.timelineStart.toFixed(2)}-${w.timelineEnd.toFixed(2)}`);
+    return `Word timings (${startTime.toFixed(1)}s–${endTime.toFixed(1)}s, ${rangeWords.length} words):\n${lines.join(' | ')}`;
+}

package/dist/_members/composition/ops/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Composition types — v2 wire-shape.
+ *
+ * The OSS shared composition module mirrors the desktop store's v2
+ * shape (cueframe/src/store/compositionStore/types.ts) minus desktop-only
+ * envelope concerns (corrections, transcriptDoc, isLoaded).
+ *
+ * Used by:
+ * - @cueframe/authoring — handlers + capability shape
+ * - Director worker (the Director worker) — server-side composition
+ *
+ * Canonical state lives on `composition: Composition` (from
+ * `../validators`). All ops walk `composition.tracks`
+ * and `composition.markers`.
+ */
+import type { Composition, Region, ClipFit } from '../validators/index.js';
+/**
+ * Per-clip property updates the editor/agent can apply via `setClipProperties`.
+ * `playbackRate` triggers ripple recompute; the rest are pure visual props
+ * patched in place — `opacity`/`scale`/`rotation` (the animation channel) and
+ * `region`/`fit` (the output-space placement primitive: PiP / inset / banner /
+ * split-screen pane).
+ */
+export interface ClipPropertyUpdates {
+    playbackRate?: number;
+    opacity?: number;
+    scale?: number;
+    rotation?: number;
+    /** Output-space placement rect (fractions of the frame). Omit = full frame. */
+    region?: Region;
+    /** How the source fills `region` (default 'cover'). */
+    fit?: ClipFit;
+}
+/** Setter for compositionOps — accepts an immer draft mutator or a partial. */
+export type OpsSet = (fn: ((draft: CompositionOpsState) => void) | Partial<CompositionOpsState>) => void;
+/** Getter for compositionOps — returns the current state (read-only). */
+export type OpsGet = () => CompositionOpsState;
+import type { TimelineEntity } from "../timeline/plan.js";
+/** The undo-tracked data slice. */
+export interface CompositionData {
+    composition: Composition;
+}
+/**
+ * State shape for compositionOps — composition + selection.
+ * Used by both the desktop zustand wrapper and the headless Temporal-side
+ * wrapper. Selection lives here because both wrappers care about
+ * "selected clip / overlay" UX and want it captured in the same patch
+ * stream as content edits.
+ */
+export interface CompositionOpsState extends CompositionData {
+    /**
+     * SELECTION, as a set. Any number of entities, and not only clips —
+     * keyframes and transitions are addressable the same way, which is what lets
+     * ONE selection model serve all of them instead of a field per kind.
+     *
+     * It rides the patch stream with the content edits (see the note above), so
+     * undo restores what was selected as well as what changed.
+     */
+    selection: TimelineEntity[];
+    /**
+     * DERIVED MIRRORS of `selection`, maintained by `setSelection` and nothing
+     * else. They exist because ~90 call sites across 13 files read them, and a
+     * flag day across all of those is how a selection bug gets shipped. New code
+     * reads `selection`; these go away when the last reader does.
+     *
+     * `selectedClipId` is the first non-overlay clip in the selection;
+     * `selectedOverlayId` the first overlay clip.
+     */
+    selectedClipId: string | null;
+    selectedOverlayId: string | null;
+}
+export interface DeletedRange {
+    start: number;
+    end: number;
+}
+export interface SceneLabel {
+    clipId: string;
+    name: string;
+    layout?: 'speaker' | 'broll' | 'split' | 'fullscreen';
+}
+export type ContentSource = {
+    type: 'image';
+    src: string;
+} | {
+    type: 'video';
+    src: string;
+    startFrom?: number;
+} | {
+    type: 'color';
+    value: string;
+};
+export interface EffectConfig {
+    type: 'parallax' | 'particles' | 'grain' | 'vignette' | 'color-grade' | 'blur';
+    [key: string]: unknown;
+}
+export interface TextEffectConfig {
+    type: 'gradient' | 'neon' | 'glow' | 'wave' | 'outline' | 'shadow';
+    [key: string]: unknown;
+}
+export interface TextConfig {
+    type: 'cinematic-title' | 'typewriter' | 'split-reveal' | 'kinetic-type' | 'karaoke' | 'lower-third';
+    content: string;
+    effect?: TextEffectConfig;
+    position?: 'center' | 'bottom' | 'top' | 'left' | 'right';
+    enterAt?: number;
+    exitAt?: number;
+}
+export interface TransitionConfig {
+    type: 'light-leak' | 'ink-wipe' | 'luma-matte' | 'glitch-cut' | 'zoom-through' | 'morph';
+    duration?: number;
+    [key: string]: unknown;
+}
+export interface LayoutConfig {
+    type: 'letterbox' | 'split-screen' | 'picture-in-picture' | 'photo-grid';
+    [key: string]: unknown;
+}
+export interface GlobalEffects {
+    grain?: number;
+    vignette?: number;
+    colorGrade?: string;
+    letterbox?: number;
+}
+export interface Scene {
+    id: string;
+    content: ContentSource;
+    duration: number;
+    effects?: EffectConfig[];
+    text?: TextConfig[];
+    layout?: LayoutConfig;
+    transition?: TransitionConfig;
+}
+export type EffectTarget = {
+    kind: 'clip';
+    clipId: string;
+} | {
+    kind: 'global';
+};
+export interface EffectInstance {
+    id: string;
+    primitiveId: string;
+    params: Record<string, unknown>;
+    target: EffectTarget;
+    startTime?: number;
+    duration?: number;
+}

package/dist/_members/composition/ops/types.js

@@ -0,0 +1,16 @@
+/**
+ * Composition types — v2 wire-shape.
+ *
+ * The OSS shared composition module mirrors the desktop store's v2
+ * shape (cueframe/src/store/compositionStore/types.ts) minus desktop-only
+ * envelope concerns (corrections, transcriptDoc, isLoaded).
+ *
+ * Used by:
+ * - @cueframe/authoring — handlers + capability shape
+ * - Director worker (services/temporal/director) — server-side composition
+ *
+ * Canonical state lives on `composition: Composition` (from
+ * `../validators`). All ops walk `composition.tracks`
+ * and `composition.markers`.
+ */
+export {};