@cueframe/kernel 0.0.1

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

@@ -0,0 +1,261 @@
+/**
+ * Graphics-plan IR — the structure-first authoring contract (plan
+ * 2026-07-07-structure-first-graphics-pipeline). Instead of the designer
+ * authoring Remotion JSX blind, it produces these three inspectable,
+ * versioned artifacts; a compiler turns them into brand-bound, animatable
+ * Remotion. The SAME schema is the client-agent CHECKPOINT payload AND the
+ * compiler input — no translation layer to drift.
+ *
+ * Split by concern so each stage boundary is a review/edit point:
+ *   ContentPlan  — WHAT to say (editorial, text-owned; never pixels).
+ *   LayoutPlan   — WHERE it sits (spatial structure, content-aware: element
+ *                  boxes are solved CLEAR of the face keep-outs the
+ *                  composition-floor already computes → text-over-face is
+ *                  impossible by construction, not by prompt).
+ *   MotionPlan   — HOW it animates (entrance / emphasis / exit intent).
+ *
+ * `styleRole` binds to brand tokens (never a raw hex/font) so off-brand
+ * output is impossible; the compiler resolves it via the same `$brand:`
+ * mechanism as packages/authoring/src/tools/brandTokens.ts.
+ */
+import { z } from "zod";
+import { Region } from "../validators/composition.js";
+/** Bump when a field's meaning changes; the compiler + checkpoint clients
+ *  branch on it. Kept a literal so an old client sees a hard mismatch, not a
+ *  silent misread. */
+export const GRAPHICS_PLAN_VERSION = "gp-1";
+const Version = z.literal(GRAPHICS_PLAN_VERSION);
+/** A rect in output-frame fractions [0,1] — the SAME placement vocabulary as
+ *  the composition-floor `Rect` and the wire `Region` (reused so a plan box and
+ *  a rendered layer can never disagree about coordinates). */
+export const PlanRect = Region;
+// ── ContentPlan ────────────────────────────────────────────────────────────
+/**
+ * What the beat must COMMUNICATE. An EDITORIAL vocabulary — deliberately not a list of
+ * primitive names.
+ *
+ * The first six are named after primitive families, and that was the bug: the DESIGNER's
+ * decision (which component draws this) had leaked into the PLANNER's schema. It meant the
+ * vocabulary could only grow by adding primitive names, so it could never keep up with the
+ * catalog — and on 2026-07-13 a brief demanding a chain-trace, comparison bars and a
+ * three-item build got exactly ONE lower-third, because a lower-third was close to the most
+ * the planner was ABLE to say. It was not being lazy. It had no word for what the brief wanted.
+ *
+ * The last three are the fix, and they name a JOB, not a picture:
+ *   the planner says "this beat must show a sequence"; the DESIGNER decides whether that is
+ *   `reasoning-trace`, `tool-call-stack`, or something it writes itself.
+ *
+ * Closed on purpose (the critics and the layout solver switch on it) — but closed around
+ * editorial intent, which is a small and stable set, instead of around a 103-component catalog,
+ * which is neither.
+ */
+export const GraphicRole = z.enum([
+    "title-card", // topic-setter / opener card
+    "stat", // a single headline number + label
+    "lower-third", // name/title tag over the speaker
+    "pull-quote", // a short quoted line
+    "hero", // big behind-subject phrase (zPlane: behind-subject)
+    "logo-tag", // small brand mark / watermark beat
+    // ── the beat carries an ARGUMENT, not a caption ──
+    "enumeration", // a list of short items ("LBO modelling / VDR diligence / customer cubes")
+    "sequence", // an ordered chain of steps — often the POINT is that it is too long
+    "comparison", // labelled values set against each other (a benchmark, a before/after)
+]);
+/**
+ * The words for a beat — ALWAYS plan-owned (a text-to-image model can't spell; the Remotion code
+ * renders these crisply). All optional; a role uses the subset it needs
+ * (stat → value+label; title-card → headline+sub; enumeration/sequence → items; comparison → series).
+ *
+ * `items` and `series` exist because the plan OWNS the words, and a role it cannot supply the
+ * words for is a role it cannot actually request. Four scalars could not carry a list or a
+ * labelled series, so even a widened role vocabulary would have had nowhere to put its content —
+ * the second half of the same 2026-07-13 bug, and the one that would have silently defeated the
+ * fix for the first half.
+ */
+export const Copy = z
+    .object({
+    headline: z.string().max(120).optional(),
+    sub: z.string().max(200).optional(),
+    value: z.string().max(40).optional(),
+    label: z.string().max(80).optional(),
+    /** Ordered short items — an `enumeration`'s bullets, a `sequence`'s steps. */
+    items: z.array(z.string().max(80)).max(8).optional(),
+    /**
+     * Labelled values for a `comparison`.
+     *
+     * `value` is a STRING, deliberately — not `number | string`. The plan owns the words, and a
+     * comparison's words include their units: a planner writes "10 min", "98%", "$4.2M", never
+     * 600. A number would have to be re-unitised downstream by someone who doesn't know what it
+     * meant.
+     *
+     * It is also a hard constraint: `submit_compose_plan` is a STRICT Anthropic tool
+     * (`strict: true`, schemas.ts), and a `z.union` here becomes an `anyOf` in the tool schema.
+     * That is what stalled the planner on 2026-07-13 — it ran, could not satisfy the schema, and
+     * never called the tool at all. Keep every field in this schema a single concrete type.
+     */
+    series: z
+        .array(z.object({ label: z.string().max(40), value: z.string().max(16) }))
+        .max(8)
+        .optional(),
+})
+    .strict();
+export const ContentBeat = z
+    .object({
+    id: z.string().min(1),
+    /** Clip-relative seconds. */
+    atSec: z.number().min(0),
+    durSec: z.number().positive(),
+    role: GraphicRole,
+    copy: Copy,
+    /** Editorial WHY — the beat this graphic serves (for review + the judge). */
+    intent: z.string().min(1).max(400),
+    /** Higher = more important; drives drop order under budget. */
+    priority: z.number().int().min(0).max(10).default(5),
+})
+    .strict();
+export const ContentPlan = z
+    .object({
+    version: Version,
+    beats: z.array(ContentBeat),
+})
+    .strict();
+// ── LayoutPlan ───────────────────────────────────────────────────────────────
+/** The role of ONE element within a graphic — maps to a primitive slot. */
+export const ElementRole = z.enum([
+    "headline", // primary large text
+    "value", // the stat number / the one word to remember
+    "label", // supporting text
+    "sublabel", // secondary supporting text
+    "logo", // brand mark
+    "accent-shape", // decorative block/line/underline
+    "backdrop", // solid fill (takeover cards only)
+]);
+/** Semantic style binding → resolved to `$brand:` refs by the compiler; NEVER a
+ *  raw hex/font. This is the guarantee that on-brand is the only option.
+ *  Mapping (compiler): heading→fonts.heading+colors.text, accent→colors.accent,
+ *  body→fonts.body+colors.text, surface→colors.surface/background,
+ *  on-accent→colors.textOnAccent, on-surface→colors.textOnSurface. */
+export const StyleRole = z.enum([
+    "heading",
+    "body",
+    "accent",
+    "surface",
+    "on-accent",
+    "on-surface",
+]);
+/** Depth plane — matches OverlayClipSource.zPlane. `behind-subject` is the
+ *  intentional hero look (the subject cut-out bites the letters). */
+export const ZPlane = z.enum(["front", "behind-subject"]);
+export const LayoutElement = z
+    .object({
+    elId: z.string().min(1),
+    role: ElementRole,
+    /** Solved CLEAR of `keepOut` (except intentional behind-subject heroes). */
+    box: PlanRect,
+    styleRole: StyleRole,
+    z: ZPlane.default("front"),
+    /** The text this element renders (from the ContentPlan). Omitted for
+     *  logo / accent-shape / backdrop. */
+    text: z.string().max(200).optional(),
+    /** Index into the editorial type scale (mirrors composition-floor
+     *  Treatment.typeScaleStep) — a SCALE STEP, not a raw px guess. */
+    typeScaleStep: z.number().int().min(0).max(8).optional(),
+})
+    .strict();
+const EPS = 1e-6;
+const rectsOverlapEps = (a, b) => a.x < b.x + b.w - EPS && a.x + a.w > b.x + EPS && a.y < b.y + b.h - EPS && a.y + a.h > b.y + EPS;
+export const LayoutPlan = z
+    .object({
+    version: Version,
+    beatId: z.string().min(1),
+    /** Output aspect context (pixels); placement itself is in [0,1] fractions. */
+    frame: z.object({ w: z.number().positive(), h: z.number().positive() }).strict(),
+    /** INPUT (not authored): face keep-out rects at this beat, from the
+     *  composition-floor. The layout stage MUST place `front` elements clear of
+     *  these — carried on the plan so a reviewer/compiler can verify it. */
+    keepOut: z.array(PlanRect),
+    /** INPUT: safe-zone insets (title-safe / action-safe fractions). */
+    safe: z
+        .object({
+        titleSafe: z.number().min(0).max(1),
+        actionSafe: z.number().min(0).max(1),
+    })
+        .strict(),
+    elements: z.array(LayoutElement),
+    /** Set when the solver could NOT place a beat's graphic legally (e.g. the
+     *  face fills the legal area). Makes a drop OBSERVABLE — distinct from a
+     *  beat that legitimately had no copy (both yield elements:[]). The producer
+     *  can surface it; the compiler skips it. */
+    dropped: z.object({ reason: z.string().min(1) }).strict().optional(),
+})
+    .strict()
+    // The IR ENFORCES its own headline invariant: a `front` element box must be
+    // in-frame AND clear of every face keep-out. A mis-solved OR (P4) agent-
+    // proposed plan that puts text on the speaker FAILS parse — the guarantee is
+    // structural, not just solver-code-dependent. behind-subject heroes are
+    // exempt (the subject intentionally occludes them).
+    .superRefine((plan, ctx) => {
+    for (const el of plan.elements) {
+        if (el.z === "behind-subject")
+            continue;
+        const b = el.box;
+        if (b.x + b.w > 1 + EPS || b.y + b.h > 1 + EPS) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `element ${el.elId} box spills past the frame`, path: ["elements"] });
+        }
+        for (const ko of plan.keepOut) {
+            if (rectsOverlapEps(b, ko)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `element ${el.elId} overlaps a face keep-out (text on the speaker)`, path: ["elements"] });
+            }
+        }
+    }
+});
+// ── MotionPlan ───────────────────────────────────────────────────────────────
+export const EnterType = z.enum(["reveal", "fade", "rise", "count-up", "wipe"]);
+export const EmphasisType = z.enum(["pulse", "underline", "color-shift"]);
+export const ExitType = z.enum(["fade", "fall", "wipe", "cut"]);
+/** Ease vocabulary → compiler maps to real spring/interpolate. Named, not raw
+ *  bezier/ms, so the brand's motion pace stays a decision not a magic number. */
+export const Ease = z.enum(["spring", "ease-out", "ease-in-out", "linear"]);
+export const EnterMotion = z
+    .object({
+    type: EnterType,
+    atMs: z.number().min(0),
+    durMs: z.number().positive(),
+    ease: Ease.default("spring"),
+    /** Per-child stagger (ms) for multi-part reveals. */
+    stagger: z.number().min(0).optional(),
+})
+    .strict();
+export const EmphasisMotion = z
+    .object({ type: EmphasisType, atMs: z.number().min(0), durMs: z.number().positive() })
+    .strict();
+export const ExitMotion = z
+    .object({ type: ExitType, atMs: z.number().min(0), durMs: z.number().positive() })
+    .strict();
+export const MotionElement = z
+    .object({
+    elId: z.string().min(1),
+    enter: EnterMotion,
+    emphasis: EmphasisMotion.optional(),
+    exit: ExitMotion.optional(),
+})
+    .strict();
+export const MotionPlan = z
+    .object({
+    version: Version,
+    beatId: z.string().min(1),
+    elements: z.array(MotionElement),
+})
+    .strict();
+// ── Bundle ───────────────────────────────────────────────────────────────────
+/** The full graphics plan for a compose run: one ContentPlan, and a
+ *  Layout+Motion pair per beat (keyed by beatId). This is the object a
+ *  checkpoint returns and the compiler consumes. */
+export const GraphicsPlan = z
+    .object({
+    version: Version,
+    content: ContentPlan,
+    layouts: z.array(LayoutPlan),
+    motions: z.array(MotionPlan),
+})
+    .strict();

package/dist/_members/composition/graphics-plan/solve.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { type Rect } from "../projection/composition-floor.js";
+import { type ContentBeat, type LayoutPlan } from "./schemas.js";
+export interface LayoutContext {
+    frame: {
+        w: number;
+        h: number;
+    };
+    /** Face keep-out rects at this beat (from the composition-floor). */
+    keepOut: Rect[];
+    safe: {
+        titleSafe: number;
+        actionSafe: number;
+    };
+}
+/**
+ * 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 declare function solveLayout(beat: ContentBeat, ctx: LayoutContext): LayoutPlan;
+/** True iff two rects overlap (used by tests + the P4 agent-proposal validator). */
+export declare function rectsOverlap(a: Rect, b: Rect): boolean;

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

@@ -0,0 +1,145 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,7 @@
+export * from "./validators/index.js";
+export * from "./invariants/index.js";
+export * from "./projection/index.js";
+export { pickColorGradePreset, colorMoodFromBrand } from "./color-grade.js";
+export type { TimelineWord, TimedWordAttrs } from "./ops/timeline-word.js";
+export { pickGeometricFocus, deriveReframedComposition } from "./reframe/derive.js";
+export type { RosterFace, ClipFaceRoster, TargetFormat } from "./reframe/derive.js";

package/dist/_members/composition/index.js

@@ -0,0 +1,5 @@
+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.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CLIP↔TRACK PLACEMENT — the DB-free half of the rule, in the KERNEL so both
+ * lanes can run ONE implementation.
+ *
+ * THE GAP THIS NARROWS. `applyHandler`'s dry-run advertises itself as partial
+ * (`LOCAL_VALIDATION_PARTIAL`): the server also runs `the backend
+ * composition/` projection guards that the desktop cannot import, so a local
+ * `valid: true` is not a promise the cloud would accept the same composition.
+ * Two of those guards need nothing the desktop lacks, and their absence cost a
+ * real project.
+ *
+ * WHAT WENT WRONG (2026-08-18, project "launch"). An agent wrote, and the local
+ * lane accepted:
+ *
+ *     video track  start=0  duration=0   perfect-wave-…mp3
+ *     video track  start=0  duration=0   perfect-wave-…mp3   (the same clip twice)
+ *     video track  start=0  duration=0   mouse-click-…mp3
+ *
+ * Three zero-length clips stacked at 0, and MP3 AUDIO on a VIDEO track. The
+ * composition's duration came out 0:00.00 — nothing to play, nothing to fix
+ * from the UI, and the project was effectively dead. The cloud refuses exactly
+ * this (`media_family_track_mismatch`), but that check is DB-bound there: it
+ * needs the media row's kind. The desktop has that kind ALREADY, in
+ * `ProjectContextPayload.media[].kind` — so the reason it was not checked here
+ * is that nobody wired it, not that it could not be known.
+ *
+ * WHY IT LIVES HERE AND NOT IN THE DESKTOP. The first cut of this WAS a
+ * desktop-only copy — which is exactly the drift this repo spends real effort
+ * avoiding (the lane-conformance table exists because a rule added to ONE lane
+ * is a rule the other lane does not have). `applyHandler` already prescribed
+ * the fix in prose: "closing the gap for real means hoisting those validators
+ * into `@cueframe/composition`". So it is hoisted, not duplicated.
+ *
+ * STILL OUTSTANDING, said plainly so nobody assumes otherwise: the CLOUD keeps
+ * its own implementation in `the server's composition projection`. This
+ * is now the shared HOME, not yet the single CALLER. Pointing the cloud guard
+ * at this function is the remaining step, and until it happens the two can
+ * still drift.
+ *
+ * DELIBERATELY NARROW. Only two facts are asserted, and both are establishable
+ * without a database — which is what makes them shareable at all:
+ *
+ *   1. A media clip whose media KIND is known and whose family plainly
+ *      contradicts the track it sits on.
+ *   2. A clip with a non-positive duration.
+ *
+ * An UNKNOWN kind is not an error — the pool may not have probed the item yet,
+ * and refusing on absence would block legitimate authoring against media that
+ * is still ingesting. That is the same "absence is not evidence" rule the
+ * transcript panel had to learn.
+ */
+import type { Composition } from "../validators/composition.js";
+export interface ProjectionIssue {
+    clipId: string;
+    message: string;
+}
+/**
+ * @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 declare function collectClipPlacementIssues(composition: Composition, mediaKindById: Record<string, string>): ProjectionIssue[];

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

@@ -0,0 +1,69 @@
+/** 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.d.ts

@@ -0,0 +1,9 @@
+import type { Composition } from "../validators/composition.js";
+import type { InvariantViolation } from "./errors.js";
+/**
+ * Run every structural invariant against a Composition.
+ * Returns a flat list of violations; empty array = valid.
+ */
+export declare function checkComposition(composition: Composition): InvariantViolation[];
+/** Convenience: duration = max(startTime + duration) across every Track's contents. */
+export declare function compositionDuration(composition: Composition): number;

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

@@ -0,0 +1,28 @@
+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.d.ts

@@ -0,0 +1,11 @@
+export type InvariantCode = "track_clips_overlap" | "transition_no_predecessor" | "transition_too_long" | "clip_source_track_kind_mismatch" | "scene_marker_overlap" | "composition_id_collision" | "varying_keyframe_time_out_of_range" | "varying_keyframe_duplicate_time" | "compound_cycle" | "compound_depth_exceeded" | "compound_unresolved" | "etag_canonicalization_failed" | "brand_kit_invalid_easing" | "excluded_range_invalid" | "excluded_range_out_of_bounds" | "excluded_range_overlap" | "excluded_range_duration_mismatch" | "clip_duration_trim_mismatch";
+export interface InvariantViolation {
+    code: InvariantCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare class InvariantError extends Error {
+    readonly code: InvariantCode;
+    readonly details?: Record<string, unknown>;
+    constructor(violation: InvariantViolation);
+}

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

@@ -0,0 +1,10 @@
+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";
+    }
+}