@cueframe/kernel 0.1.0 → 0.1.1

package/dist/_members/composition/graphics-plan/solve.js

@@ -1,145 +0,0 @@
-/**
- * Layout stage (P1): ContentBeat → LayoutPlan. Deterministic placement that is
- * content-aware BY CONSTRUCTION — every front element is solved clear of the
- * composition-floor face keep-outs (reusing `placeInLegalArea`), so text can
- * never land on the speaker. This is the "solver snaps to legal" half of the
- * hybrid layout stage; P4 lets an agent PROPOSE boxes that this validates/snaps.
- *
- * A per-role TEMPLATE decomposes each graphic into ordered element slots; the
- * solver finds one legal vertical band for the whole stack and lays the slots
- * out within it. styleRole (→ brand token) and typeScaleStep (→ type scale) are
- * assigned per slot, so nothing off-brand or raw-px is emitted.
- */
-import { placeInLegalArea } from "../projection/composition-floor.js";
-import { GRAPHICS_PLAN_VERSION, } from "./schemas.js";
-/** Per-graphic-role templates: the ordered element slots + the band anchor
- *  preference. Widths/heights are conservative fractions the compiler can
- *  refine once real text metrics exist (P2).
- *
- *  PARTIAL on purpose. The ARGUMENT roles (enumeration / sequence / comparison) have no template
- *  and must not have one: a `sequence` might be a reasoning-trace, a tool-call-stack or a bespoke
- *  component, and choosing between those is a DESIGN decision made with eyes on the frame — not a
- *  slot table. This deterministic solver only lays out the text-shaped roles; the designer owns
- *  the rest. `solveLayout` fails loud below rather than inventing a headline for a chain of steps.
- */
-const TEMPLATES = {
-    "title-card": {
-        anchor: "free",
-        slots: [
-            { role: "headline", styleRole: "heading", copyKey: "headline", h: 0.1, w: 0.82, typeScaleStep: 6 },
-            { role: "sublabel", styleRole: "body", copyKey: "sub", h: 0.05, w: 0.7, typeScaleStep: 3 },
-        ],
-    },
-    stat: {
-        anchor: "free",
-        slots: [
-            { role: "value", styleRole: "accent", copyKey: "value", h: 0.13, w: 0.6, typeScaleStep: 7 },
-            { role: "label", styleRole: "body", copyKey: "label", h: 0.05, w: 0.72, typeScaleStep: 3 },
-        ],
-    },
-    "lower-third": {
-        anchor: "lower-third",
-        slots: [
-            { role: "headline", styleRole: "heading", copyKey: "headline", h: 0.07, w: 0.7, typeScaleStep: 5 },
-            { role: "sublabel", styleRole: "body", copyKey: "sub", h: 0.045, w: 0.62, typeScaleStep: 2 },
-        ],
-    },
-    "pull-quote": {
-        anchor: "free",
-        slots: [{ role: "headline", styleRole: "heading", copyKey: "headline", h: 0.14, w: 0.82, typeScaleStep: 5 }],
-    },
-    hero: {
-        anchor: "free",
-        slots: [{ role: "headline", styleRole: "heading", copyKey: "headline", h: 0.18, w: 0.9, typeScaleStep: 8, z: "behind-subject" }],
-    },
-    "logo-tag": {
-        anchor: "bottom",
-        slots: [{ role: "logo", styleRole: "accent", copyKey: null, h: 0.06, w: 0.22 }],
-    },
-};
-const GAP = 0.02;
-const clamp01 = (n) => Math.min(1, Math.max(0, n));
-function clampRect(r) {
-    const x = clamp01(r.x);
-    const y = clamp01(r.y);
-    return { x, y, w: Math.min(r.w, 1 - x), h: Math.min(r.h, 1 - y) };
-}
-/** Top + bottom strips outside the title-safe area, as band blockers. */
-function safeBands(safe) {
-    const m = clamp01((1 - safe.titleSafe) / 2);
-    if (m <= 0)
-        return [];
-    return [
-        { x: 0, y: 0, w: 1, h: m },
-        { x: 0, y: 1 - m, w: 1, h: m },
-    ];
-}
-/** Center a block of `totalH` vertically, clamped inside the safe margins. */
-function centeredBand(totalH, safe) {
-    const m = clamp01((1 - safe.titleSafe) / 2);
-    const y = Math.min(1 - m - totalH, Math.max(m, 0.5 - totalH / 2));
-    return { x: 0, y: Math.max(0, y), w: 1, h: totalH };
-}
-/**
- * Solve one beat's layout. Front stacks land in a legal band clear of the face;
- * behind-subject heroes intentionally ignore the keep-out (the subject occludes
- * them). An opener with no detected face centers vertically.
- */
-export function solveLayout(beat, ctx) {
-    const tpl = TEMPLATES[beat.role];
-    if (!tpl) {
-        throw new Error(`graphics-plan/solve: role "${beat.role}" (beat "${beat.id}") is a DESIGNER-AUTHORED argument ` +
-            `role — the deterministic layout solver has no template for it, and must not invent one. ` +
-            `The designer picks the component and its layout with the frame in front of it.`);
-    }
-    const isBehind = tpl.slots.every((s) => s.z === "behind-subject");
-    const active = tpl.slots.filter((s) => s.copyKey === null || beat.copy[s.copyKey] != null);
-    if (active.length === 0) {
-        return { version: GRAPHICS_PLAN_VERSION, beatId: beat.id, frame: ctx.frame, keepOut: ctx.keepOut, safe: ctx.safe, elements: [] };
-    }
-    const totalH = active.reduce((s, x) => s + x.h, 0) + GAP * (active.length - 1);
-    const maxW = Math.max(...active.map((s) => s.w));
-    const hasFace = ctx.keepOut.length > 0;
-    // Band selection preserves the invariant: a front stack NEVER lands on the
-    // face. behind-subject heroes center by design; a face-free opener centers;
-    // otherwise the legal-area solver places clear of the face — and if NO legal
-    // band fits (face fills the frame), we DROP the graphic (empty elements)
-    // rather than fall back onto the speaker. Dropping is the safe failure: a
-    // graphic you can't place legally is worse than no graphic.
-    const band = isBehind
-        ? centeredBand(totalH, ctx.safe)
-        : hasFace
-            ? placeInLegalArea({ id: beat.id, anchor: tpl.anchor, minH: totalH, minW: maxW }, { faceKeepOut: ctx.keepOut, safeZones: safeBands(ctx.safe) })
-            : centeredBand(totalH, ctx.safe);
-    if (band === null) {
-        // Dropped, not occluding the face — and OBSERVABLE (distinct from no-copy).
-        return { version: GRAPHICS_PLAN_VERSION, beatId: beat.id, frame: ctx.frame, keepOut: ctx.keepOut, safe: ctx.safe, elements: [], dropped: { reason: "no legal band clear of the face keep-out" } };
-    }
-    const elements = [];
-    let cursor = band.y;
-    for (const s of active) {
-        // Place WITHIN the band's horizontal corridor (band.x..band.x+band.w) — NOT
-        // re-centered on 0.5. For an off-center (side-framed) face, placeInLegalArea
-        // shifts the corridor into the clear side; centering on 0.5 would put text
-        // back onto the speaker. Element width is capped to the corridor.
-        const w = Math.min(s.w, band.w, 0.92);
-        const x = band.x + (band.w - w) / 2;
-        const box = clampRect({ x, y: cursor, w, h: s.h });
-        const text = s.copyKey ? beat.copy[s.copyKey] : undefined;
-        elements.push({
-            elId: `${beat.id}-${s.role}`,
-            role: s.role,
-            box,
-            styleRole: s.styleRole,
-            z: s.z ?? "front",
-            ...(text ? { text } : {}),
-            ...(s.typeScaleStep != null ? { typeScaleStep: s.typeScaleStep } : {}),
-        });
-        cursor += s.h + GAP;
-    }
-    return { version: GRAPHICS_PLAN_VERSION, beatId: beat.id, frame: ctx.frame, keepOut: ctx.keepOut, safe: ctx.safe, elements };
-}
-/** True iff two rects overlap (used by tests + the P4 agent-proposal validator). */
-export function rectsOverlap(a, b) {
-    return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
-}

package/dist/_members/composition/index.js

@@ -1,5 +0,0 @@
-export * from "./validators";
-export * from "./invariants";
-export * from "./projection";
-export { pickColorGradePreset, colorMoodFromBrand } from "./color-grade.js";
-export { pickGeometricFocus, deriveReframedComposition } from "./reframe/derive.js";

package/dist/_members/composition/invariants/clipPlacement.js

@@ -1,69 +0,0 @@
-/** What a track of this kind is allowed to carry, for the kinds we can judge.
- *  Anything absent here is not judged. */
-const AUDIO_TRACK_KINDS = new Set(['audio']);
-const VISUAL_TRACK_KINDS = new Set(['video', 'image']);
-/**
- * @param composition the FOLDED composition — checked on the result rather than
- *   on the ops, so it cannot be walked around by the shape of the batch (the
- *   same reasoning as the component gate beside it).
- * @param mediaKindById `mediaId -> kind`. The desktop passes
- *   `getContext().media`; a server caller passes its media rows. A missing entry
- *   means "not judged".
- */
-export function collectClipPlacementIssues(composition, mediaKindById) {
-    const issues = [];
-    const tracks = composition.tracks;
-    if (!Array.isArray(tracks))
-        return issues;
-    for (const track of tracks) {
-        const trackKind = typeof track.kind === 'string' ? track.kind : '';
-        const contents = Array.isArray(track.contents) ? track.contents : [];
-        for (const clip of contents) {
-            const clipId = typeof clip.id === 'string' ? clip.id : '(unnamed clip)';
-            // ── 1. A clip that occupies no time is not an edit ──────────────────
-            //
-            // The render lattice DROPS a clip too short to occupy a whole frame at
-            // its position (`timelineSpanFrames`), so a zero-duration clip is
-            // guaranteed to contribute nothing — it just makes the composition read
-            // as 0:00.00 while appearing to hold media.
-            const duration = clip.duration;
-            if (typeof duration !== 'number' || !(duration > 0)) {
-                issues.push({
-                    clipId,
-                    message: `clip \`${clipId}\` on track \`${trackKind || '?'}\` has duration ${String(duration)}. ` +
-                        `A clip must occupy time: the render lattice drops anything shorter than one frame, ` +
-                        `so this contributes nothing and leaves the composition reading 0:00.`,
-                });
-                continue;
-            }
-            // ── 2. Audio on a picture track (and the reverse) ───────────────────
-            const source = clip.source;
-            if (!source || source.kind !== 'media')
-                continue;
-            const mediaId = typeof source.mediaId === 'string' ? source.mediaId : '';
-            const mediaKind = mediaKindById[mediaId];
-            // Not probed / not in the pool → not judged. Absence is not evidence.
-            if (!mediaKind)
-                continue;
-            const mediaIsAudio = mediaKind === 'audio';
-            const mediaIsVisual = mediaKind === 'video' || mediaKind === 'image';
-            if (mediaIsAudio && VISUAL_TRACK_KINDS.has(trackKind)) {
-                issues.push({
-                    clipId,
-                    message: `clip \`${clipId}\` puts AUDIO media (\`${mediaId}\`) on a \`${trackKind}\` track. ` +
-                        `Audio belongs on an \`audio\` track — the cloud refuses this as ` +
-                        `\`media_family_track_mismatch\`, and the local renderer draws nothing for it.`,
-                });
-            }
-            else if (mediaIsVisual && AUDIO_TRACK_KINDS.has(trackKind)) {
-                issues.push({
-                    clipId,
-                    message: `clip \`${clipId}\` puts ${mediaKind.toUpperCase()} media (\`${mediaId}\`) on an ` +
-                        `\`audio\` track. Picture belongs on a \`video\` or \`image\` track — the cloud ` +
-                        `refuses this as \`media_family_track_mismatch\`.`,
-                });
-            }
-        }
-    }
-    return issues;
-}

package/dist/_members/composition/invariants/composition.js

@@ -1,28 +0,0 @@
-import { checkTracks } from "./tracks";
-import { checkSceneMarkerPartition } from "./markers";
-import { checkIdCollisions } from "./ids";
-import { checkKeyframes } from "./keyframes";
-/**
- * Run every structural invariant against a Composition.
- * Returns a flat list of violations; empty array = valid.
- */
-export function checkComposition(composition) {
-    return [
-        ...checkIdCollisions(composition),
-        ...checkTracks(composition),
-        ...checkSceneMarkerPartition(composition),
-        ...checkKeyframes(composition),
-    ];
-}
-/** Convenience: duration = max(startTime + duration) across every Track's contents. */
-export function compositionDuration(composition) {
-    let max = 0;
-    for (const track of composition.tracks) {
-        for (const c of track.contents) {
-            const e = c.startTime + c.duration;
-            if (e > max)
-                max = e;
-        }
-    }
-    return max;
-}

package/dist/_members/composition/invariants/errors.js

@@ -1,10 +0,0 @@
-export class InvariantError extends Error {
-    code;
-    details;
-    constructor(violation) {
-        super(`${violation.code}: ${violation.message}`);
-        this.code = violation.code;
-        this.details = violation.details;
-        this.name = "InvariantError";
-    }
-}

package/dist/_members/composition/invariants/etag.js

@@ -1,38 +0,0 @@
-// Pure-JS SHA-256 (no `node:crypto`) so this module bundles into Convex's V8
-// isolate — importing it transitively (via the invariants barrel) previously
-// broke `npx convex deploy` with "Could not resolve node:crypto". @noble/hashes
-// is sync + dependency-free and its output is byte-identical to node's
-// createHash("sha256").update(utf8).digest("hex"), so every existing etag /
-// If-Match (OCC) value is unchanged. (Pairs with projection.ts's inlined computeEtag.)
-import { sha256 } from "@noble/hashes/sha256";
-import { bytesToHex } from "@noble/hashes/utils";
-/**
- * Canonicalize an object for deterministic hashing:
- * - object keys sorted lexicographically at every depth
- * - arrays preserve order
- * - undefined fields dropped (JSON semantics)
- * - null / number / string / boolean preserved as-is
- */
-export function canonicalJSON(value) {
-    return JSON.stringify(canonicalize(value));
-}
-function canonicalize(value) {
-    if (value === null || typeof value !== "object")
-        return value;
-    if (Array.isArray(value))
-        return value.map(canonicalize);
-    const out = {};
-    const keys = Object.keys(value).sort();
-    for (const key of keys) {
-        const v = value[key];
-        if (v === undefined)
-            continue;
-        out[key] = canonicalize(v);
-    }
-    return out;
-}
-export function etag(composition) {
-    const canonical = canonicalJSON(composition);
-    const hash = bytesToHex(sha256(new TextEncoder().encode(canonical)));
-    return `"${hash}"`;
-}

package/dist/_members/composition/invariants/ids.js

@@ -1,33 +0,0 @@
-/**
- * Entity ids share a single namespace within the Composition.
- * TimelineClip.id, Track.id, Gap.id, Marker.id must all be unique.
- *
- * composition_id_collision { existingKind, newKind, id }
- */
-export function checkIdCollisions(composition) {
-    const seen = new Map();
-    const out = [];
-    const record = (id, kind) => {
-        const existing = seen.get(id);
-        if (existing) {
-            out.push({
-                code: "composition_id_collision",
-                message: `Id ${id} used by both ${existing} and ${kind}`,
-                details: { id, existingKind: existing, newKind: kind },
-            });
-        }
-        else {
-            seen.set(id, kind);
-        }
-    };
-    for (const track of composition.tracks) {
-        record(track.id, "track");
-        for (const content of track.contents) {
-            record(content.id, "source" in content ? "clip" : "gap");
-        }
-    }
-    for (const marker of composition.markers ?? []) {
-        record(marker.id, "marker");
-    }
-    return out;
-}

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

@@ -1,9 +0,0 @@
-export * from "./errors";
-export * from "./etag";
-export * from "./tracks";
-export * from "./markers";
-export * from "./ids";
-export * from "./keyframes";
-export * from "./composition";
-export * from "./time";
-export * from "./clipPlacement.js";

package/dist/_members/composition/invariants/keyframes.js

@@ -1,45 +0,0 @@
-/** Float slack — two keyframes closer than this are the same instant. */
-const TIME_EPSILON = 1e-6;
-export function checkClipKeyframes(clip) {
-    const animate = clip.animate;
-    if (!animate)
-        return [];
-    const violations = [];
-    for (const [param, channel] of Object.entries(animate)) {
-        if (!channel)
-            continue;
-        const sorted = [...channel].sort((a, b) => a.time - b.time);
-        for (const kf of sorted) {
-            if (kf.time > clip.duration + TIME_EPSILON) {
-                violations.push({
-                    code: "varying_keyframe_time_out_of_range",
-                    message: `clip "${clip.id}" animates "${param}" at ${kf.time}s, past its own ` +
-                        `duration of ${clip.duration}s — that keyframe can never be reached`,
-                    details: { clipId: clip.id, param, time: kf.time, duration: clip.duration },
-                });
-            }
-        }
-        for (let i = 1; i < sorted.length; i++) {
-            if (Math.abs(sorted[i].time - sorted[i - 1].time) < TIME_EPSILON) {
-                violations.push({
-                    code: "varying_keyframe_duplicate_time",
-                    message: `clip "${clip.id}" has two "${param}" keyframes at ${sorted[i].time}s — ` +
-                        `the value at that instant is undefined`,
-                    details: { clipId: clip.id, param, time: sorted[i].time },
-                });
-            }
-        }
-    }
-    return violations;
-}
-export function checkKeyframes(composition) {
-    const violations = [];
-    for (const track of composition.tracks) {
-        for (const item of track.contents) {
-            if (!("source" in item))
-                continue;
-            violations.push(...checkClipKeyframes(item));
-        }
-    }
-    return violations;
-}

package/dist/_members/composition/invariants/markers.js

@@ -1,29 +0,0 @@
-const end = (m) => m.endTime ?? m.startTime;
-/**
- * Markers with `kind: 'scene'` cannot overlap (single-partition rule).
- * Other kinds (chapter, note, agent, custom) are free to overlap.
- *
- * scene_marker_overlap { markerAId, markerBId, overlapRange }
- */
-export function checkSceneMarkerPartition(composition) {
-    const scenes = (composition.markers ?? [])
-        .filter((m) => m.kind === "scene")
-        .sort((a, b) => a.startTime - b.startTime);
-    const out = [];
-    for (let i = 1; i < scenes.length; i++) {
-        const prev = scenes[i - 1];
-        const cur = scenes[i];
-        if (cur.startTime < end(prev)) {
-            out.push({
-                code: "scene_marker_overlap",
-                message: `Scene markers ${prev.id} and ${cur.id} overlap at [${cur.startTime}, ${Math.min(end(prev), end(cur))})`,
-                details: {
-                    markerAId: prev.id,
-                    markerBId: cur.id,
-                    overlapRange: [cur.startTime, Math.min(end(prev), end(cur))],
-                },
-            });
-        }
-    }
-    return out;
-}

package/dist/_members/composition/invariants/time.js

@@ -1,20 +0,0 @@
-/**
- * OTIO / native-renderer time quantization rule.
- * See data-model.md §OTIO time export rule and §Native renderer time quantization.
- */
-export function otioFrames(seconds, fps) {
-    return Math.round(seconds * fps);
-}
-export function otioRationalTime(seconds, fps) {
-    return { value: Math.round(seconds * fps), rate: fps };
-}
-/**
- * Per-output-frame source-frame mapping (renderer contract).
- * Matches the OTIO writer's quantization at the boundary.
- */
-export function sourceFrame(params) {
-    const { outputFrame, formatFps, clipStartTime, trimStart, playbackRate, sourceFps } = params;
-    const outSeconds = outputFrame / formatFps;
-    const sourceSeconds = trimStart + (outSeconds - clipStartTime) * playbackRate;
-    return Math.round(sourceSeconds * sourceFps);
-}