@cueframe/kernel 0.0.1

package/dist/_members/composition/audio/palette.d.ts

@@ -0,0 +1,82 @@
+import type { SfxEnvelopeClass } from "./pack.js";
+import type { AudioRole } from "./mixStaging.js";
+/** Where a palette entry came from — the provenance discriminant. */
+export type AudioPaletteSource = "pack" | "org" | "generated";
+/** The numeric envelope probe evidence (present-if-probed; the pack SSOT carries
+ *  only the class, an org probe fills the numbers). Mirrors mediaItems.envelope. */
+export interface AudioEnvelopeEvidence {
+    envelopeClass: SfxEnvelopeClass;
+    attackMs?: number;
+    spectralCentroidHz?: number;
+    meanVolumeDb?: number;
+    maxVolumeDb?: number;
+}
+/** The UNIFORM palette entry — the same shape for pack, org, and generated. */
+export interface AudioPaletteEntry {
+    /** The placement handle: a pack `soundId`/`bedId` (import_resource {kind}),
+     *  or an org media id (place directly as a clip `mediaId`). */
+    ref: string;
+    /** DECLARED role for mix policy — what this sound IS. */
+    role: AudioRole;
+    /** Coarse envelope shape — the browse grouping. */
+    envelopeClass: SfxEnvelopeClass;
+    description: string;
+    durationSec: number;
+    /** Envelope probe evidence (always carries `envelopeClass`). */
+    evidence: AudioEnvelopeEvidence;
+    source: AudioPaletteSource;
+    /** License token: "CC0" (pack), "org-owned" (an upload), a real CC token
+     *  (a stock import), or "generated" (a generator produced it). */
+    license: string;
+    /** Human-legible provenance: pack attribution, "org-owned", or the generator
+     *  + prompt for a generated sound. */
+    provenance: string;
+    /** Tempo (bpm) — present for music-role entries (pack beds carry the catalog
+     *  bpm; generated/org music carries its beatGrid bpm). */
+    bpm?: number;
+    /** Editorial mood tags — present for pack music beds. */
+    mood?: string[];
+}
+/** A raw org audio row (the structural subset of mediaItems this module needs).
+ *  Both the Convex query result and the director's HTTP result map into this. */
+export interface OrgAudioRow {
+    mediaId: string;
+    name?: string;
+    durationSec?: number;
+    audioRole?: AudioRole;
+    mediaSource?: string;
+    license?: string;
+    generator?: string;
+    generationPrompt?: string;
+    envelope?: AudioEnvelopeEvidence;
+    beatGrid?: {
+        bpm: number;
+    };
+    /** Shared/owned R2 key — threaded to the compose capture path so an org sound
+     *  the org-first draw substitutes resolves without a Convex round-trip. */
+    filePath?: string;
+}
+/**
+ * Assemble the full org sound palette: pack (SFX ∪ music beds) ∪ org-owned ∪
+ * generated. Deterministic given the input rows (pack halves are catalog-ordered;
+ * org rows keep their input order). Every entry carries source + license +
+ * provenance; music entries carry bpm.
+ */
+export declare function assembleAudioPalette(orgAudioRows: OrgAudioRow[]): AudioPaletteEntry[];
+/** One org SFX sound the compose org-first draw can substitute for a pack pick. */
+export interface OrgSfxPaletteEntry {
+    mediaId: string;
+    envelopeClass: SfxEnvelopeClass;
+    durationSec: number;
+    /** R2 key of the org sound's bytes — stamped into the capture path's media map. */
+    filePath?: string;
+}
+/**
+ * The org-owned SFX subset for the compose org-first draw: every org/generated
+ * (NOT pack) sound of role "sfx" that carries an envelope class, in a STABLE
+ * order (by mediaId) so the draw is deterministic. The director substitutes one
+ * of these for a pack pick when the org has a sound of the requested class — the
+ * grounding move (an org that uploads its product's real UI sounds hears ITS
+ * product), mirroring how a brand kit overrides the default font.
+ */
+export declare function orgSfxPalette(orgAudioRows: OrgAudioRow[]): OrgSfxPaletteEntry[];

package/dist/_members/composition/audio/palette.js

@@ -0,0 +1,134 @@
+/**
+ * The org sound palette (audio-substrate Phase 2) — ONE browse surface over the
+ * union of every sound an org can reach: the curated CC0 packs (SFX + music
+ * beds), the org's own audio-kind uploads/imports, and its generated audio. The
+ * uniform entry shape lets a driving agent pick a sound by role + envelope class
+ * without caring where it came from — provenance rides every entry.
+ *
+ * PURE: raw org audio rows in → palette entries out. The pack halves come from
+ * the closed catalogs (SFX_PACK_ENTRIES / MUSIC_PACK_ENTRIES); the org/generated
+ * halves are projected from the caller's org audio rows. Consumed by BOTH the
+ * `list_catalog` audio section (the agent browse) and the director's compose
+ * org-first SFX draw (which reads only the sfx-role org subset). One assembler,
+ * so the two surfaces can never disagree on what the org owns.
+ */
+import { SFX_PACK_ENTRIES } from "./pack";
+import { MUSIC_PACK_ENTRIES } from "./musicPack";
+/** The pack SFX half of the palette (source:"pack", role:"sfx"). */
+function packSfxEntries() {
+    return SFX_PACK_ENTRIES.map((e) => ({
+        ref: e.soundId,
+        role: "sfx",
+        envelopeClass: e.envelopeClass,
+        description: e.description,
+        durationSec: e.durationSec,
+        evidence: { envelopeClass: e.envelopeClass },
+        source: "pack",
+        license: e.source.license,
+        provenance: e.attribution,
+    }));
+}
+/** The pack MUSIC half of the palette (source:"pack", role:"music", carries bpm). */
+function packMusicEntries() {
+    return MUSIC_PACK_ENTRIES.map((e) => ({
+        ref: e.bedId,
+        role: "music",
+        // A bed is an unbounded loop — envelope class "ambient" in the browse grouping.
+        envelopeClass: "ambient",
+        description: e.description,
+        durationSec: e.durationSec,
+        evidence: { envelopeClass: "ambient" },
+        source: "pack",
+        license: e.source.license,
+        provenance: e.attribution,
+        bpm: e.bpm,
+        mood: e.mood,
+    }));
+}
+/** True when a row is a curated-pack org row (minted by the pack import/compose
+ *  lanes over shared bytes). Those are ALREADY represented by the pack half of
+ *  the palette, so they're excluded from the org half — a placement artifact,
+ *  not a distinct library item. */
+function isPackRow(row) {
+    return row.mediaSource === "cueframe-pack";
+}
+/** Project one org audio row → a palette entry. Requires envelope evidence (the
+ *  browse grouping key) — a row without it is not yet palette-ready. Returns null
+ *  to skip such rows AND minted pack rows. */
+function orgRowToEntry(row) {
+    if (isPackRow(row))
+        return null;
+    const envelope = row.envelope;
+    const role = row.audioRole;
+    // The browse groups by envelope class; a music/ambience bed with a beatGrid but
+    // no envelope still classes as "ambient" (an unbounded bed).
+    const envelopeClass = envelope?.envelopeClass ??
+        (role === "music" || role === "ambience" ? "ambient" : undefined);
+    if (!role || !envelopeClass)
+        return null;
+    const generated = Boolean(row.generator);
+    const source = generated ? "generated" : "org";
+    const license = generated
+        ? "generated"
+        : row.license ?? "org-owned";
+    const provenance = generated
+        ? `${row.generator}${row.generationPrompt ? `: ${row.generationPrompt}` : ""}`
+        : row.license
+            ? `org-owned (${row.license})`
+            : "org-owned";
+    const bpm = row.beatGrid?.bpm;
+    return {
+        ref: row.mediaId,
+        role,
+        envelopeClass,
+        description: row.name ?? row.mediaId,
+        durationSec: row.durationSec ?? 0,
+        evidence: envelope ?? { envelopeClass },
+        source,
+        license,
+        provenance,
+        ...(bpm !== undefined ? { bpm } : {}),
+    };
+}
+/**
+ * Assemble the full org sound palette: pack (SFX ∪ music beds) ∪ org-owned ∪
+ * generated. Deterministic given the input rows (pack halves are catalog-ordered;
+ * org rows keep their input order). Every entry carries source + license +
+ * provenance; music entries carry bpm.
+ */
+export function assembleAudioPalette(orgAudioRows) {
+    const org = [];
+    for (const row of orgAudioRows) {
+        const e = orgRowToEntry(row);
+        if (e)
+            org.push(e);
+    }
+    return [...packSfxEntries(), ...packMusicEntries(), ...org];
+}
+/**
+ * The org-owned SFX subset for the compose org-first draw: every org/generated
+ * (NOT pack) sound of role "sfx" that carries an envelope class, in a STABLE
+ * order (by mediaId) so the draw is deterministic. The director substitutes one
+ * of these for a pack pick when the org has a sound of the requested class — the
+ * grounding move (an org that uploads its product's real UI sounds hears ITS
+ * product), mirroring how a brand kit overrides the default font.
+ */
+export function orgSfxPalette(orgAudioRows) {
+    const out = [];
+    for (const row of orgAudioRows) {
+        if (isPackRow(row))
+            continue;
+        if (row.audioRole !== "sfx")
+            continue;
+        const envelopeClass = row.envelope?.envelopeClass;
+        if (!envelopeClass)
+            continue;
+        out.push({
+            mediaId: row.mediaId,
+            envelopeClass,
+            durationSec: row.durationSec ?? 0,
+            ...(row.filePath ? { filePath: row.filePath } : {}),
+        });
+    }
+    return out.sort((a, b) => a.mediaId.localeCompare(b.mediaId));
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Auto-zoom segment generator — clean-room.
+ *
+ * Turns caller-supplied focus points (timed cursor/click positions from an
+ * automation tool, OR a pixel-derived activity hotspot track) into a gapless
+ * tiling of `ReframeSegment`s: neutral `frame-center` spans where nothing
+ * happens, and `point` punch-ins centered on the activity.
+ *
+ * The caller supplies WHERE/WHEN (the points); this module owns HOW it looks
+ * (easing, zoom amount, padding) via `STYLE` presets — the caller never tunes
+ * smoothness, only optionally picks a coarse style. CONSUMER-AGNOSTIC: it knows
+ * "timed focus points", never "clicks" or any specific product/use-case. The
+ * recipe for a given product (what a "click" is, which style, what polish to
+ * layer on) lives in a use-case skill, not here.
+ *
+ * The timing heuristic (group → pad → merge → min-duration → fixed zoom) is a
+ * clean-room reimplementation of well-tested screen-recorder behavior, written
+ * from described behavior; constants are adopted as parameters.
+ */
+import type { ReframeSegment } from "../validators/composition.js";
+/** A caller event — a click or sampled cursor position. `(x,y)` normalized [0,1]. */
+export interface ZoomEvent {
+    t: number;
+    x: number;
+    y: number;
+}
+/** One sampled instant of a pixel-derived activity track. */
+export interface ActivitySample extends ZoomEvent {
+    /** Fraction of the frame that changed (0–1); high = pan/scroll, reject. */
+    changePct: number;
+    /** Change-mass concentration near the hotspot (0–1); high = a focused target. */
+    concentration: number;
+}
+export type ZoomStyle = "subtle" | "standard" | "punchy";
+interface Tuning {
+    zoom: number;
+    prePad: number;
+    postPad: number;
+    minZoom: number;
+    mergeGap: number;
+}
+/** CueFrame-owned look presets. The caller picks a name; never the numbers. */
+export declare const STYLE: Record<ZoomStyle, Tuning>;
+/**
+ * Timed focus points (e.g. cursor/click positions — every point a
+ * high-confidence anchor) → reframe segments. No detection.
+ */
+export declare function autoZoom(points: ZoomEvent[], durationSec: number, style?: ZoomStyle): ReframeSegment[];
+/**
+ * Pixel-derived activity track → reframe segments. Keeps only focused,
+ * low-global-change samples (rejects pan/scroll) before tiling.
+ */
+export declare function autoZoomFromActivity(activity: ActivitySample[], durationSec: number, style?: ZoomStyle, thresholds?: {
+    minConcentration?: number;
+    maxChangePct?: number;
+}): ReframeSegment[];
+export {};

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

@@ -0,0 +1,83 @@
+/** CueFrame-owned look presets. The caller picks a name; never the numbers. */
+export const STYLE = {
+    subtle: { zoom: 0.80, prePad: 0.5, postPad: 1.2, minZoom: 1.2, mergeGap: 1.0 },
+    standard: { zoom: 0.67, prePad: 0.4, postPad: 1.0, minZoom: 1.0, mergeGap: 0.8 },
+    punchy: { zoom: 0.55, prePad: 0.3, postPad: 0.8, minZoom: 0.8, mergeGap: 0.6 },
+};
+const median = (xs) => {
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+const neutral = (startSec, endSec) => ({
+    startSec, endSec, intent: "auto-zoom:neutral",
+    focus: { mode: "frame-center" }, zoom: 1.0,
+});
+/** Core: a list of focused (t,x,y) anchors + clip duration → gapless tiling. */
+function tile(anchors, durationSec, t) {
+    if (durationSec <= 0 || anchors.length === 0)
+        return [];
+    const sorted = [...anchors].sort((a, b) => a.t - b.t);
+    // group temporally-adjacent anchors
+    const groups = [];
+    let cur = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i].t - sorted[i - 1].t <= t.mergeGap)
+            cur.push(sorted[i]);
+        else {
+            groups.push(cur);
+            cur = [sorted[i]];
+        }
+    }
+    groups.push(cur);
+    // pad → clamp → drop too-short → median focal point
+    const windows = groups.map((g) => ({
+        start: Math.max(0, g[0].t - t.prePad),
+        end: Math.min(durationSec, g[g.length - 1].t + t.postPad),
+        x: median(g.map((e) => e.x)),
+        y: median(g.map((e) => e.y)),
+    })).filter((w) => w.end - w.start >= t.minZoom);
+    if (windows.length === 0)
+        return [];
+    // merge overlapping padded windows (keep earlier focal point)
+    const merged = [windows[0]];
+    for (let i = 1; i < windows.length; i++) {
+        const prev = merged[merged.length - 1];
+        if (windows[i].start <= prev.end)
+            prev.end = Math.max(prev.end, windows[i].end);
+        else
+            merged.push(windows[i]);
+    }
+    // emit gapless tiling: neutral fills gaps, point punch-ins cover windows
+    const out = [];
+    let cursor = 0;
+    for (const w of merged) {
+        if (w.start > cursor)
+            out.push(neutral(cursor, w.start));
+        out.push({
+            startSec: w.start, endSec: w.end, intent: "auto-zoom:punch-in",
+            focus: { mode: "point", x: w.x, y: w.y }, zoom: t.zoom,
+        });
+        cursor = w.end;
+    }
+    if (cursor < durationSec)
+        out.push(neutral(cursor, durationSec));
+    return out;
+}
+/**
+ * Timed focus points (e.g. cursor/click positions — every point a
+ * high-confidence anchor) → reframe segments. No detection.
+ */
+export function autoZoom(points, durationSec, style = "standard") {
+    return tile(points, durationSec, STYLE[style]);
+}
+/**
+ * Pixel-derived activity track → reframe segments. Keeps only focused,
+ * low-global-change samples (rejects pan/scroll) before tiling.
+ */
+export function autoZoomFromActivity(activity, durationSec, style = "standard", thresholds = {}) {
+    const minC = thresholds.minConcentration ?? 0.6;
+    const maxCh = thresholds.maxChangePct ?? 0.12;
+    const anchors = activity.filter((s) => s.concentration >= minC && s.changePct <= maxCh);
+    return tile(anchors, durationSec, STYLE[style]);
+}

package/dist/_members/composition/brand-kit.d.ts

@@ -0,0 +1,58 @@
+import type { BrandKit as WireBrandKit } from "./validators/brandKit.js";
+export interface BrandColor {
+    hex: string;
+    label: string;
+    usage?: string;
+}
+export interface BrandTypography {
+    fontFamily: string;
+    fontWeight: number;
+}
+export interface BrandAsset {
+    path: string;
+    name: string;
+}
+export interface BrandFont {
+    path: string;
+    name: string;
+    fontFamily?: string;
+}
+export interface BrandKit {
+    id: string;
+    name: string;
+    description?: string;
+    colors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+        background: string;
+        text: string;
+    };
+    extraColors: BrandColor[];
+    headingFont: BrandTypography;
+    bodyFont: BrandTypography;
+    syncCaptions: boolean;
+    /** Full caption style profile (replaces shallow 2-field sync) */
+    captionProfile?: Record<string, unknown>;
+    logo?: WireBrandKit["logo"];
+    intro?: WireBrandKit["intro"];
+    outro?: WireBrandKit["outro"];
+    watermark?: WireBrandKit["watermark"];
+    /** Primary brand tagline/slogan — prompt context only. */
+    tagline?: string;
+    /** Secondary tagline or CTA phrase — prompt context only. */
+    secondaryTagline?: string;
+    /** Free-text brand voice, injected into LLM prompts. */
+    voiceGuidelines: string;
+    /** Custom fonts (loaded via FontFace API on kit activation) — editor UI only. */
+    customFonts: BrandFont[];
+    /** Audio asset — authoring metadata, not a render input. */
+    jingle?: BrandAsset;
+    /** Audio asset — authoring metadata, not a render input. */
+    bgMusic?: BrandAsset;
+    /** Hero/background image from website — authoring metadata, not a render input. */
+    heroImage?: BrandAsset;
+    createdAt: number;
+    modifiedAt: number;
+}
+export declare const DEFAULT_BRAND_KIT: Omit<BrandKit, 'id' | 'createdAt' | 'modifiedAt'>;

package/dist/_members/composition/brand-kit.js

@@ -0,0 +1,45 @@
+// @cueframe/composition/brand-kit — the editor-side Brand Kit (composition-level fact).
+//
+// Brand is a composition-level fact per the architecture spec ("composition-level
+// facts: format, brand, captions"), so the editor's brand kit lives in the
+// composition contract — imported by Authoring to build context, never reaching
+// into the renderer.
+//
+// Reconciled with the wire `BrandKit` (zod, ./validators/brandKit): the
+// render-relevant overlay assets — `logo`, `intro`, `outro`, `watermark` — are
+// the SAME shapes the wire schema defines, re-used here directly so they project
+// onto the wire/render contract with no lossy re-map. The wire schema is the
+// single source of truth for those fields; the fully-materialized read shape is
+// `ResolvedBrandKit` (./projection). Everything else on this type is the editor's
+// authored INPUT (flat colors / typography the dashboard collects, plus
+// authoring-only metadata that never reaches render — see below).
+// Moved from @cueframe/core/types.ts in Phase-3 Slice 1 (decouple authoring from
+// the renderer): its only consumer is the authoring agent.
+export const DEFAULT_BRAND_KIT = {
+    name: 'CueFrame',
+    description: 'AI-native video editor. Spend less time editing, more time creating stories that matter.',
+    tagline: 'Your Story Deserves Better Than a Timeline',
+    colors: {
+        primary: '#7C3AED',
+        secondary: '#4F46E5',
+        accent: '#7C3AED',
+        background: '#121212',
+        text: '#ffffff',
+    },
+    extraColors: [
+        { hex: '#1a1a1a', label: 'Surface', usage: 'Cards, elevated backgrounds' },
+        { hex: '#262626', label: 'Muted', usage: 'Borders, subtle backgrounds' },
+        { hex: '#a3a3a3', label: 'Muted Text', usage: 'Secondary text, captions' },
+    ],
+    // Vendored families only (`VENDORED_FONT_FAMILIES`): the picker lists exactly
+    // those, and the render sandbox has no font egress, so a default outside the
+    // list is a value the user cannot re-select and a face that rasterizes as
+    // the generic fallback. The previous defaults ('DM Serif Display', 'Geist')
+    // were both.
+    headingFont: { fontFamily: 'Instrument Serif', fontWeight: 400 },
+    bodyFont: { fontFamily: 'Inter', fontWeight: 400 },
+    syncCaptions: false,
+    captionProfile: {},
+    customFonts: [],
+    voiceGuidelines: 'Premium and sophisticated. Focus on storytelling over technical complexity. Approachable but confident. Emphasize the creative process, not the tool. Minimal, clear language.',
+};

package/dist/_members/composition/brief/contract.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The BRIEF CONTRACT — what the customer pinned, and what no downstream stage may undo.
+ *
+ * ── AUTHORITY ────────────────────────────────────────────────────────────────────────────
+ * The brief owns WHAT CONTENT EXISTS. The planner owns HOW IT IS FRAMED. A planner that
+ * deletes footage is not making a framing decision — it is exercising the brief's authority,
+ * and no downstream guard can ever repair that.
+ *
+ * On 2026-07-13 the planner shipped 52.9s against a brief pinning 87.1s. It deleted the
+ * product demo and the call-to-action, reasoning "No subject detected — cut for pace". Nothing
+ * objected, because the contract was never even THREADED to the director: the beats are
+ * resolved by `deriveBriefComposeSource` and then thrown away, and `DirectorInput.compose`
+ * carries the brief flattened into a "suggestion" (caption / hook / motionStyle). The planner
+ * could not honor a contract it was never shown.
+ *
+ * A beat's `source` window is documented as "honored TO THE FRAME or refused". So on the brief
+ * path, deleting pinned footage is a contract violation, full stop.
+ *
+ * ── WHY 'trim' IS EFFECTIVELY FORBIDDEN HERE ─────────────────────────────────────────────
+ * Brief creation ALREADY refuses a `durationSec` that differs from the pinned window by more
+ * than ±1.5s (`brief_duration_unhonorable`). So by construction the contracted duration IS the
+ * pinned window — the customer has declared there is no filler. Any deletion beyond the
+ * tolerance therefore breaks the duration contract. A customer who wants footage cut pins
+ * tighter beats; that is the channel for it.
+ *
+ * `'keep'` (SHOW this span AS-IS, no reframe) is the legal move for footage with nothing to
+ * track. It was added 2026-07-12 for exactly this, and the planner still reaches for 'trim'.
+ * A vocabulary the model may ignore is not a constraint — hence this module.
+ *
+ * Pure arithmetic, zero runtime imports (structural param types only), so it is safe in BOTH
+ * the Convex V8 isolate (brief-creation gate) and the Temporal workflow sandbox (the plan
+ * gate). One definition of the tolerances, no drift.
+ */
+/** Gap tolerance between adjacent pinned beats — a larger gap means the [min,max] hull would
+ *  include footage the client never pinned. */
+export declare const BEAT_CONTIGUITY_TOLERANCE_S = 0.75;
+/** Per-beat tolerance used by BRIEF CREATION: a sourced beat's own `durationSec` must match its
+ *  own window to within this. (Not the plan gate's rule — see BEAT_MAX_LOSS_FRACTION.) */
+export declare const BEAT_DURATION_TOLERANCE_S = 0.5;
+/** How far the whole output may drift from the contracted duration. THE contract (documented,
+ *  customer-facing) — and, because deletions only ever shrink the output, it already caps how
+ *  much a plan can remove in ABSOLUTE terms. */
+export declare const BRIEF_DURATION_TOLERANCE_S = 1.5;
+/**
+ * The most of ITSELF a single pinned beat may lose. A FRACTION, deliberately — not an absolute.
+ *
+ * Rule B already caps total deletion at ±1.5s, so no beat can lose much in absolute terms. What
+ * Rule B cannot see is a SHORT beat being erased outright: a 1.5s beat deleted whole still
+ * clears the aggregate. That is the only gap Rule A exists to close, so it must be expressed as
+ * "did this beat survive recognisably", not as a stopwatch.
+ *
+ * An absolute 0.5s was tried first and was WRONG — it refused the planner's removal of a 1.44s
+ * HARD PAUSE between two sentences (measured 2026-07-13). Cutting dead air is editing, which the
+ * planner owns; deleting the product demo is content, which it does not. A rule that cannot tell
+ * those apart is not enforcing authority, it is just being obstructive.
+ */
+export declare const BEAT_MAX_LOSS_FRACTION = 0.5;
+/** A beat the customer pinned. SOURCE-absolute seconds (the brief's own frame of reference). */
+export interface BriefBeatWindow {
+    id: string;
+    startSec: number;
+    endSec: number;
+    /**
+     * Structured graphics MANDATE on this beat (brief `beats[].graphic`): the plan
+     * must carry a `graphics` request of this `role` whose window OVERLAPS the
+     * beat (overlap, not exact pin — the planner keeps timing latitude), and any
+     * mandated `items` must appear verbatim in the request's copy. Prose
+     * mustIncludes cannot be gate-checked; this is the checkable form. `role` is
+     * structurally a string here (zero runtime imports — the zod GraphicRole
+     * enum validates at the brief door).
+     */
+    graphic?: {
+        role: string;
+        items?: readonly string[];
+    };
+}
+/** What the plan gate needs in order to know what it may not undo. */
+export interface BriefContract {
+    /** The customer's pinned beats, SOURCE-absolute. */
+    beats: readonly BriefBeatWindow[];
+    /** The A-roll clip's trim start (source seconds). Converts beats → CLIP-RELATIVE, which is
+     *  the frame of reference the plan is authored in. This offset is the single most common
+     *  way a plan goes wrong; it is applied here once, centrally. */
+    windowStartSec: number;
+    /** The contracted output duration = the pinned window span (see the header). */
+    targetDurationSec: number;
+}
+/** The plan shape this reads. Structural, so no import of the zod model. */
+interface PlanLike {
+    framing: ReadonlyArray<{
+        startSec: number;
+        endSec: number;
+        action: string;
+        intent?: string;
+    }>;
+    cuts?: ReadonlyArray<{
+        startSec: number;
+        endSec: number;
+        reason?: string;
+    }>;
+    /** PlanGraphicRequest, structurally (Rule C reads role/window/copy.items). */
+    graphics?: ReadonlyArray<{
+        id: string;
+        atSec: number;
+        durSec: number;
+        role: string;
+        copy?: {
+            items?: ReadonlyArray<string>;
+        };
+    }>;
+}
+/**
+ * Every way this plan breaks the brief's content contract, as planner-addressed messages.
+ * Empty array ⇒ the plan honors the brief.
+ *
+ * Three rules, and ALL are needed:
+ *  - Rule A (per beat): a pinned beat may not be deleted. Catches surgical beat removal that
+ *    Rule B could mask by keeping filler elsewhere.
+ *  - Rule B (aggregate): the contracted duration must survive. Catches death by a thousand
+ *    cuts that individually clear the per-beat tolerance.
+ *  - Rule C (per mandated beat): a beat's graphics MANDATE must be planned — same
+ *    honor-or-refuse as A/B. Before this, a graphics-less plan against a graphics-mandating
+ *    brief sailed through and cost a full plan→assemble→eval cycle for the judge to discover
+ *    what the brief said in writing (prod 2026-07-14, rs7fanev…) — and with one candidate
+ *    attempt there is no critique retry to rescue it: this gate is the only line of defense.
+ *
+ * The messages ARE the fix: each names the beat, quotes the planner's own reason back at it,
+ * and prescribes the exact shape — because `runPlanPhase` feeds these straight back as the
+ * planner's next-turn instruction.
+ */
+export declare function planBriefViolations(plan: PlanLike, contract: BriefContract): string[];
+export {};