@cueframe/kernel 0.1.0 → 0.1.1

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

@@ -1,94 +0,0 @@
-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.js

@@ -1,4 +0,0 @@
-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.js

@@ -1,118 +0,0 @@
-/**
- * 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.js

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

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

@@ -1,77 +0,0 @@
-/**
- * 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.js

@@ -1,16 +0,0 @@
-/**
- * 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 {};

package/dist/_members/composition/primitive-catalog/catalogQuery.js

@@ -1,150 +0,0 @@
-import { SFX_PACK_ENTRIES } from '../audio/pack.generated';
-export const CATALOG_CATEGORY_VALUES = new Set([
-    'text', 'effects', 'transitions', 'layouts', 'backgrounds', 'ui-blocks', 'scenes',
-]);
-export const CATALOG_KIND_VALUES = new Set(['component', 'transition', 'scene']);
-export const CATALOG_TIER_VALUES = new Set(['recommended', 'standard', 'niche']);
-export const CATALOG_USE_CASE_VALUES = new Set([
-    'intro', 'outro', 'full-scene', 'title-over-footage', 'transition',
-    'background', 'grade', 'emphasis', 'explainer', 'social-cut',
-]);
-const TIER_RANK = { recommended: 0, standard: 1, niche: 2 };
-/** A bad filter enum value — both lanes map this to their 400 invalid_query. */
-export class CatalogFilterError extends Error {
-    field;
-    value;
-    allowed;
-    constructor(field, value, allowed) {
-        super(`Unknown ${field} '${value}'. Allowed: ${allowed.join(', ')}.`);
-        this.field = field;
-        this.value = value;
-        this.allowed = allowed;
-        this.name = 'CatalogFilterError';
-    }
-}
-/** A cursor that decodes to no catalog entry — both lanes map to invalid_cursor. */
-export class CatalogCursorError extends Error {
-    constructor(message = 'The supplied cursor is invalid or expired.') {
-        super(message);
-        this.name = 'CatalogCursorError';
-    }
-}
-/**
- * Validate raw query values into CatalogFilters. `q` and `intent` are aliases
- * (free-text vs recommend-by-intent framing); both fold into the same match.
- */
-export function validateCatalogFilters(raw) {
-    const norm = (v) => (v === undefined || v === '' ? undefined : v);
-    const f = {
-        category: norm(raw.category),
-        kind: norm(raw.kind),
-        tier: norm(raw.tier),
-        useCase: norm(raw.useCase),
-        mood: norm(raw.mood),
-        q: norm(raw.q) ?? norm(raw.intent),
-    };
-    if (f.category && !CATALOG_CATEGORY_VALUES.has(f.category))
-        throw new CatalogFilterError('category', f.category, [...CATALOG_CATEGORY_VALUES]);
-    if (f.kind && !CATALOG_KIND_VALUES.has(f.kind))
-        throw new CatalogFilterError('kind', f.kind, [...CATALOG_KIND_VALUES]);
-    if (f.tier && !CATALOG_TIER_VALUES.has(f.tier))
-        throw new CatalogFilterError('tier', f.tier, [...CATALOG_TIER_VALUES]);
-    if (f.useCase && !CATALOG_USE_CASE_VALUES.has(f.useCase))
-        throw new CatalogFilterError('useCase', f.useCase, [...CATALOG_USE_CASE_VALUES]);
-    return f;
-}
-/** True if ANY facet/free-text filter is set (drives recommend-first ordering). */
-export function hasAnyCatalogFilter(f) {
-    return Boolean(f.category || f.kind || f.tier || f.useCase || f.mood || f.q);
-}
-/** Apply facet + free-text filters to a catalog. */
-export function filterCatalog(catalog, f) {
-    const q = f.q?.toLowerCase();
-    return catalog.filter((e) => {
-        if (f.category && e.category !== f.category)
-            return false;
-        if (f.kind && e.kind !== f.kind)
-            return false;
-        if (f.tier && e.tier !== f.tier)
-            return false;
-        if (f.useCase && !(e.useCase ?? []).includes(f.useCase))
-            return false;
-        if (f.mood && !(e.mood ?? []).includes(f.mood))
-            return false;
-        if (q) {
-            const hay = [
-                e.id, e.name, e.description, e.intent ?? '', e.useWhen ?? '',
-                ...(e.tags ?? []), ...(e.mood ?? []),
-            ].join(' ').toLowerCase();
-            if (!hay.includes(q))
-                return false;
-        }
-        return true;
-    });
-}
-const nodeBuffer = globalThis.Buffer;
-function b64urlEncode(raw) {
-    const b64 = typeof btoa === 'function' ? btoa(raw) : nodeBuffer.from(raw, 'utf-8').toString('base64');
-    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-function b64urlDecode(opaque) {
-    const b64 = opaque.replace(/-/g, '+').replace(/_/g, '/');
-    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
-    return typeof atob === 'function'
-        ? atob(padded)
-        : nodeBuffer.from(padded, 'base64').toString('utf-8');
-}
-export const encodeCatalogCursor = b64urlEncode;
-export function decodeCatalogCursor(opaque) {
-    try {
-        return b64urlDecode(opaque);
-    }
-    catch {
-        throw new CatalogCursorError();
-    }
-}
-/**
- * The whole read: filter → recommend-order (only when filtered) → page.
- * `limit` undefined returns the WHOLE filtered catalog in one page (an agent
- * must never silently see a partial slice); `after` is the OPAQUE cursor from
- * a previous page. Throws CatalogCursorError on an unknown/undecodable cursor.
- */
-export function queryCatalog(catalog, filters, opts = {}) {
-    let sorted = filterCatalog(catalog, filters);
-    if (hasAnyCatalogFilter(filters)) {
-        sorted = [...sorted].sort((a, b) => (TIER_RANK[a.tier ?? 'standard'] ?? 1) - (TIER_RANK[b.tier ?? 'standard'] ?? 1));
-    }
-    const limit = opts.limit ?? Number.POSITIVE_INFINITY;
-    let start = 0;
-    if (opts.after !== undefined) {
-        const afterId = decodeCatalogCursor(opts.after);
-        const idx = sorted.findIndex((e) => e.id === afterId);
-        if (idx < 0)
-            throw new CatalogCursorError('Cursor not found.');
-        start = idx + 1;
-    }
-    const page = sorted.slice(start, start + limit);
-    const hasMore = start + limit < sorted.length;
-    return {
-        data: page,
-        pagination: {
-            hasMore,
-            nextCursor: hasMore && page.length > 0 ? encodeCatalogCursor(page[page.length - 1].id) : null,
-            prevCursor: null,
-        },
-    };
-}
-/** The curated CC0 SFX pack projected to the agent-legible browse shape
- *  (drops content-audit internals — sha256, structured source). First-page
- *  attachment on both lanes. */
-export function serializeSfxCatalog() {
-    return SFX_PACK_ENTRIES.map((e) => ({
-        soundId: e.soundId,
-        family: e.family,
-        envelopeClass: e.envelopeClass,
-        intensity: e.intensity,
-        durationSec: e.durationSec,
-        description: e.description,
-        attribution: e.attribution,
-    }));
-}

package/dist/_members/composition/primitive-catalog/disabled.js

@@ -1,32 +0,0 @@
-// @cueframe/primitive-registry — the disabled-primitive denylist.
-//
-// The ONE switch that takes a built-in primitive out of circulation without
-// deleting its config or regenerating the catalog. Dependency-free + V8-safe
-// (imported by both this package's projections AND the Convex write boundary).
-//
-// WHY A DENYLIST, not a per-primitive `disabled` flag: a primitive is baked into
-// SEVERAL generated artifacts — the catalog meta (generated/meta.ts),
-// version-map.json (the membership SSOT), params-required.json, the component
-// source (primitiveSource.generated.ts) — and, for name-coupled primitives like
-// heroText, hard-referenced by id in the graphics-plan compiler and the agent
-// prompts. A flag would have to be threaded through every one of those and
-// regenerated. One denylist, checked at the few points a primitive is OFFERED
-// (discovery projections), ADMITTED (the membership guard at save), or
-// AUTO-EMITTED (the compiler), is the clean lever: add an id here and it
-// vanishes from discovery and is rejected on save, everywhere, reversibly — no
-// regen, no config surgery.
-//
-// The RENDERER is intentionally UNTOUCHED: an already-saved composition that
-// references a now-disabled primitive still renders (the execution catalog keeps
-// the component). This blocks NEW authoring; it does not retro-break saved work.
-export const DISABLED_PRIMITIVE_IDS = new Set([
-// (empty) — heroText was denylisted 2026-07-08 because behind-subject
-// matte compositing desynced lip movement. Root cause was the matte bake
-// re-timing the co-view at average fps (VFR sources drifted seconds);
-// fixed by the CFR timing invariant at ingest (plan: brain
-// 2026-07-28-cfr-timing-invariant) — re-enabled 2026-07-28.
-]);
-/** True when a primitive id is on the disabled denylist (not offered / not admitted). */
-export function isPrimitiveDisabled(id) {
-    return DISABLED_PRIMITIVE_IDS.has(id);
-}