@cueframe/kernel 0.0.1

package/dist/_members/brand-derivation/contrastSafe.js

@@ -0,0 +1,114 @@
+import { APCAcontrast, sRGBtoY } from "apca-w3";
+import { converter } from "culori";
+// DERIVATION_VERSION / FLOORS / NEUTRAL_RAMP live in the side-effect-free
+// `./constants` module (no apca-w3/culori) so render-side consumers can import
+// the poles without dragging the contrast math into their bundle. Re-exported
+// here so the package root stays the single source of truth.
+export { DERIVATION_VERSION, FLOORS, NEUTRAL_RAMP } from "./constants";
+import { FLOORS, NEUTRAL_RAMP } from "./constants";
+// Leaf-package color parsing via culori — this package must NOT import composition-model.
+const toRgb = converter("rgb");
+function hexToRgb(hex) {
+    const c = toRgb(hex);
+    if (!c)
+        return [0, 0, 0]; // unparseable → black; the clamp still guarantees a floor
+    return [Math.round(c.r * 255), Math.round(c.g * 255), Math.round(c.b * 255)];
+}
+/** Linear-RGB mix of two hex colors: ratio 0 → `a`, ratio 1 → `b`. Parses `#RGB` / `#RRGGBB`;
+ *  returns `#rrggbb` lowercase. Mirrors composition-model's `colorMix` (we can't import it — leaf
+ *  package boundary). On an unparseable input the clamp downstream still guarantees a floor. */
+function colorMix(a, b, ratio) {
+    const [ar, ag, ab] = hexToRgb(a);
+    const [br, bg, bb] = hexToRgb(b);
+    const t = Math.max(0, Math.min(1, ratio));
+    const inv = 1 - t;
+    const r = Math.round(ar * inv + br * t);
+    const g = Math.round(ag * inv + bg * t);
+    const bl = Math.round(ab * inv + bb * t);
+    return "#" + [r, g, bl].map((v) => v.toString(16).padStart(2, "0")).join("");
+}
+/** Lc magnitude between two hex colors (APCA is signed by polarity; the floor wants the magnitude).
+ *  APCAcontrast is typed `number | string` (a string sentinel for out-of-range luminance, which
+ *  sRGBtoY's 0..1 output never produces); coerce to a number at this single boundary. */
+function lc(fg, bg) {
+    return Math.abs(Number(APCAcontrast(sRGBtoY(hexToRgb(fg)), sRGBtoY(hexToRgb(bg)))));
+}
+/** sRGB relative luminance Y∈[0,1] of a hex color, via apca-w3's `sRGBtoY`.
+ *  Exported so composition-side legibility (which compares text against a
+ *  SAMPLED backdrop luminance, not a second hex) can put text + backdrop on the
+ *  same Y scale without re-deriving the transfer curve. */
+export function relativeLuminance(hex) {
+    return sRGBtoY(hexToRgb(hex));
+}
+/** APCA Lc magnitude between two relative-luminance values (text fg over bg).
+ *  This is the primitive the composition FLOOR's worst-tile legibility check
+ *  consumes: it samples per-tile backdrop luminance from the rendered frame and
+ *  asks "does the caption text clear the floor over the WORST tile?". Polarity-
+ *  signed APCA is reduced to a magnitude (the floor wants legibility, not which
+ *  way the polarity runs). Keep the APCA math in THIS package — the floor must
+ *  not re-implement it (single source of truth, no proxy). */
+export function apcaLcFromLuminance(fgY, bgY) {
+    return Math.abs(Number(APCAcontrast(fgY, bgY)));
+}
+/** APCA Lc magnitude between two hex colors (fg over bg). Hex-input sibling of
+ *  `apcaLcFromLuminance`; the brand cascade and tests use it directly. */
+export function apcaLc(fg, bg) {
+    return lc(fg, bg);
+}
+/** Return `fg` if it clears `floor` over `bg`; else the most legible of {fg, ramp poles} over `bg`
+ *  (never lower contrast than the input — forward-only by construction). Exported so the brand
+ *  cascade (composition-model) can re-clamp its own derived de-emphasis tokens (e.g. the muted
+ *  text mix) back up to a floor without re-implementing the APCA math at the package boundary. */
+export function clampToFloor(fg, bg, floor) {
+    if (lc(fg, bg) >= floor)
+        return fg;
+    const candidates = [fg, NEUTRAL_RAMP.onDark, NEUTRAL_RAMP.onLight];
+    return candidates.reduce((best, c) => (lc(c, bg) > lc(best, bg) ? c : best));
+}
+/** Caption legibility is UNCONDITIONAL. If the brand background can host caption text at the body
+ *  floor, keep it as the scrim. Otherwise fall to a neutral plate (near-black scrim + white fg),
+ *  where the pole-over-pole APCA (~106) clears the floor for ANY brand. */
+function deriveCaption(seedText, background) {
+    const onBrand = clampToFloor(seedText, background, FLOORS.body);
+    if (lc(onBrand, background) >= FLOORS.body) {
+        return { captionScrim: background, captionFg: onBrand };
+    }
+    return { captionScrim: NEUTRAL_RAMP.onLight, captionFg: NEUTRAL_RAMP.onDark }; // near-black plate, white fg
+}
+/** Derive a contrast-safe palette from a brand seed.
+ *  Captions are an UNCONDITIONAL floor: a plate-backed neutral fallback guarantees
+ *  `Lc(captionFg, captionScrim) >= FLOORS.body` for any brand background.
+ *  `text` / `textMuted` directly on a hostile brand background are best-achievable / forward-only
+ *  (the monotone clamp never lowers a brand's own contrast); a tuned solid-background plate for
+ *  body text on hostile backgrounds is Phase 1. */
+export function deriveContrastSafe(seed) {
+    const background = seed.background;
+    const text = clampToFloor(seed.text, background, FLOORS.body);
+    const accent = seed.accent;
+    const { captionScrim, captionFg } = deriveCaption(seed.text, background);
+    // Tier-2 fills: nudge the background toward text for raised surfaces / hairline rhythm.
+    const surface = colorMix(background, text, 0.06); // bg nudged toward text (raised panel)
+    const card = colorMix(background, text, 0.1); // one tonal step above surface
+    const gridLine = colorMix(background, text, 0.08); // hairline rhythm guide
+    const accentMuted = colorMix(accent, background, 0.35); // accent faded for secondary states
+    // textOnAccent is BEST-ACHIEVABLE, not floor-guaranteed: a saturated accent caps APCA below the
+    // body floor (e.g. white over #ff4438 ≈ 65.66), so the clamp returns the most legible pole it can
+    // reach, not necessarily one clearing FLOORS.body. The design NEVER puts body text on raw accent —
+    // body legibility lives on accentMuted / surface / background, where the floor IS guaranteed.
+    const textOnAccent = clampToFloor(text, accent, FLOORS.body);
+    const textOnSurface = clampToFloor(text, surface, FLOORS.body);
+    return {
+        background,
+        text,
+        textMuted: clampToFloor(seed.text, background, FLOORS.nonBody),
+        accent,
+        captionScrim,
+        captionFg,
+        surface,
+        card,
+        gridLine,
+        accentMuted,
+        textOnAccent,
+        textOnSurface,
+    };
+}

package/dist/_members/brand-derivation/index.d.ts

@@ -0,0 +1 @@
+export * from "./contrastSafe.js";

package/dist/_members/brand-derivation/index.js

@@ -0,0 +1 @@
+export * from "./contrastSafe";

package/dist/_members/compose/CompositionRenderer.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { SceneRenderInput } from './sceneToRenderInput.js';
+export interface CompositionRendererProps {
+    input: SceneRenderInput;
+}
+/**
+ * Renders a complete scene composition.
+ *
+ * Lays out scenes as Sequences with proper frame offsets (accounting for
+ * transition overlaps), applies effects, text, layout, global effects, and audio.
+ */
+export declare const CompositionRenderer: React.FC<CompositionRendererProps>;

package/dist/_members/compose/catalog.d.ts

@@ -0,0 +1 @@
+export { allCatalogs } from './primitiveRegistry.js';

package/dist/_members/compose/index.d.ts

@@ -0,0 +1,8 @@
+export type { Scene, ContentSource, EffectConfig, TextConfig, TextEffectConfig, TransitionConfig, LayoutConfig, GlobalEffects, SceneComposition, AudioTrackConfig, TokenOverrides, } from './schema.js';
+export { resolveTokens } from './tokenResolver.js';
+export type { TokenSet } from './tokenResolver.js';
+export { sceneToRenderInput } from './sceneToRenderInput.js';
+export type { SceneRenderInput, SceneFrameData } from './sceneToRenderInput.js';
+export { resolvePrimitive, registerPrimitiveOverride, resetPrimitiveOverrides, listPrimitives, listPrimitivesByCategory, getPrimitiveTextParam, getPrimitiveSubtextParam, getPrimitiveText, getPrimitiveSubtext, inflatePrimitiveProps, resolveTransitionPresentation, isRegisteredTransition, } from './primitiveRegistry.js';
+export type { PrimitiveMeta } from './primitiveRegistry.js';
+export { allCatalogs } from './catalog.js';

package/dist/_members/compose/primitiveRegistry.d.ts

@@ -0,0 +1,90 @@
+import type { ResolvedBrandKit } from '../composition/projection/index.js';
+import type { PrimitiveMeta as NewPrimitiveMeta } from '../primitives/lib/types.js';
+import { listPrimitivesByCategory, getPrimitiveTextParam, getPrimitiveSubtextParam } from '../composition/primitive-catalog/index.js';
+export { listPrimitivesByCategory, getPrimitiveTextParam, getPrimitiveSubtextParam };
+/** Re-export for consumers that want the canonical PrimitiveMeta shape. */
+export type PrimitiveMeta = NewPrimitiveMeta;
+/**
+ * All primitive catalogs merged into a single array.
+ *
+ * Transitions declare `kind: 'transition'` + `createPresentation(params)`.
+ * The render path resolves via `resolveTransitionPresentation(id, params)`
+ * and passes the returned presentation to `<TransitionSeries.Transition>`.
+ * Agent discovery (list_effect_styles filtered by category) surfaces them
+ * as addressable primitives.
+ */
+export declare const allCatalogs: PrimitiveMeta[];
+export declare function registerPrimitiveOverride(meta: PrimitiveMeta, owner: string): void;
+/**
+ * Clear all registered overrides + release the owner. A shared/pooled process MUST
+ * call this between tenants; a per-render process calls it once at bundle init so a
+ * reused render context starts clean (idempotent re-render).
+ */
+export declare function resetPrimitiveOverrides(): void;
+/**
+ * Resolve a primitive by its kebab-case ID.
+ * Returns the PrimitiveMeta (component + metadata) or undefined if not found.
+ */
+export declare function resolvePrimitive(id: string): PrimitiveMeta | undefined;
+/**
+ * List all registered primitive IDs.
+ */
+export declare function listPrimitives(): string[];
+/**
+ * Resolve a transition presentation factory by id. Returns a concrete
+ * Remotion `TransitionPresentation` (typed loosely as `unknown` to avoid
+ * pulling `@remotion/transitions` types into every consumer) built from
+ * the supplied params.
+ *
+ * Returns `undefined` if the id is unknown OR if the registered entry is
+ * not a transition (defensive — lets callers fall back cleanly).
+ */
+export declare function resolveTransitionPresentation(id: string, params?: Record<string, unknown>): unknown | undefined;
+/**
+ * Returns true if an id names a registered transition. Used by ingress
+ * validators (e.g. public schema) to widen the old enum to any registered
+ * transition without losing validation.
+ */
+export declare function isRegisteredTransition(id: string): boolean;
+/**
+ * Read accessor: returns the primary text string from an overlay, respecting
+ * both the canonical location (overlay.params.text) and the legacy
+ * primitive-native location (overlay.params[meta.textParam]). Canonical
+ * wins when present.
+ *
+ * Use this in every consumer that needs "the text of an overlay" —
+ * Inspector, Timeline, transcript, FCPXML, NLE exports.
+ */
+export declare function getPrimitiveText(overlay: {
+    template: string;
+    params: Record<string, unknown>;
+}): string | undefined;
+/**
+ * Read accessor for secondary text. Same fallback pattern as getPrimitiveText.
+ */
+export declare function getPrimitiveSubtext(overlay: {
+    template: string;
+    params: Record<string, unknown>;
+}): string | undefined;
+/**
+ * Render-time translator from overlay-canonical params to primitive-native
+ * props. Used by OverlayLayer and anything else that spreads overlay.params
+ * into the primitive component.
+ *
+ *   params.text   → props[meta.textParam]    (if primitive has textParam)
+ *   params.subtext → props[meta.subtextParam] (if primitive has subtextParam)
+ *   "$brand:<path>" refs → resolved against brandKit (if provided)
+ *   everything else → passed through
+ *
+ * Producers MUST write canonical `text` / `subtext`. Writing under the
+ * primitive's native prop name (e.g. `content`) is no longer auto-mapped —
+ * such payloads fail paramsSchema validation at inflate time with a clear
+ * `<primitive-id>: invalid params — text: Required` error so the producer
+ * can be corrected.
+ */
+export declare function inflatePrimitiveProps(overlay: {
+    template: string;
+    params: Record<string, unknown>;
+}, brandKit?: ResolvedBrandKit, onUnresolved?: (info: {
+    path: string;
+}) => void): Record<string, unknown>;

package/dist/_members/compose/sceneToRenderInput.d.ts

@@ -0,0 +1,51 @@
+import type { Scene, GlobalEffects, AudioTrackConfig } from './schema.js';
+import type { SceneComposition } from './schema.js';
+import { type TokenSet } from './tokenResolver.js';
+import { type ResolvedBrandKit } from '../core/render/index.js';
+/**
+ * The slice of the resolved brand kit the scene timeline needs to size its
+ * bookends — the SAME shape `resolveBookendTimeline` (clips path) reads. The
+ * full `ResolvedBrandKit` (with `intro`/`outro`) is a superset.
+ */
+export type SceneBookendKit = {
+    intro?: ResolvedBrandKit['intro'];
+    outro?: ResolvedBrandKit['outro'];
+};
+/** Per-scene frame data for the renderer. */
+export interface SceneFrameData {
+    scene: Scene;
+    /** Frame offset where this scene starts in the composition */
+    startFrame: number;
+    /** Duration of this scene in frames */
+    durationInFrames: number;
+    /** If this scene has a transition, the overlap in frames with the previous scene */
+    transitionDurationInFrames: number;
+}
+/** Frame-accurate render input for CompositionRenderer. */
+export interface SceneRenderInput {
+    fps: number;
+    width: number;
+    height: number;
+    durationInFrames: number;
+    scenes: SceneFrameData[];
+    global?: GlobalEffects;
+    audio?: AudioTrackConfig[];
+    tokens: TokenSet;
+}
+/**
+ * Convert a SceneComposition to a SceneRenderInput.
+ *
+ * Calculates total duration accounting for transition overlaps:
+ * each scene after the first that has a transition subtracts
+ * transition.duration from the total.
+ *
+ * Brand BOOKENDS: when the resolved `brandKit` carries an `intro`/`outro`
+ * bumper, the registered `durationInFrames` extends by intro + outro (the SAME
+ * fps-driven `resolveBookendTimeline` math the clips path uses in
+ * `compositionToRenderInput`) so the total reflects the bumpers MainComposition
+ * places. The PER-SCENE layout (`startFrame`/`durationInFrames`) is left at the
+ * body offsets — MainComposition's `withBookends` shifts the body inside one
+ * Sequence; folding the intro into scene offsets here would double-count it.
+ * SOFT: an absent/odd/srcless bumper reserves 0 frames → total unchanged.
+ */
+export declare function sceneToRenderInput(composition: SceneComposition, brandKit?: SceneBookendKit): SceneRenderInput;

package/dist/_members/compose/schema.d.ts

@@ -0,0 +1,45 @@
+import type { Scene as _Scene, GlobalEffects as _GlobalEffects } from '../composition/ops/index.js';
+export type { Scene, ContentSource, EffectConfig, TextConfig, TextEffectConfig, TransitionConfig, LayoutConfig, GlobalEffects, } from '../composition/ops/index.js';
+type Scene = _Scene;
+type GlobalEffects = _GlobalEffects;
+/** Configuration for an audio track in the composition. */
+export interface AudioTrackConfig {
+    /** URL or path to the audio file */
+    src: string;
+    /** Volume 0-1 (default 1) */
+    volume?: number;
+    /** Fade-in duration in seconds */
+    fadeIn?: number;
+    /** Fade-out duration in seconds */
+    fadeOut?: number;
+    /** Start offset in seconds from the beginning of the composition */
+    startAt?: number;
+}
+/** Overrides for design tokens — colors, fonts, spacing. */
+export interface TokenOverrides {
+    accent?: string;
+    primary?: string;
+    secondary?: string;
+    background?: string;
+    text?: string;
+    headingFont?: string;
+    bodyFont?: string;
+    [key: string]: unknown;
+}
+/** A complete scene-based composition ready for rendering. */
+export interface SceneComposition {
+    /** Frames per second */
+    fps: number;
+    /** Canvas width in pixels */
+    width: number;
+    /** Canvas height in pixels */
+    height: number;
+    /** Ordered list of scenes */
+    scenes: Scene[];
+    /** Optional background audio tracks */
+    audio?: AudioTrackConfig[];
+    /** Optional global effects applied to the entire composition */
+    global?: GlobalEffects;
+    /** Optional design token overrides */
+    tokens?: TokenOverrides;
+}

package/dist/_members/compose/tokenResolver.d.ts

@@ -0,0 +1,28 @@
+import type { TokenOverrides } from './schema.js';
+/** Resolved design token set. */
+export interface TokenSet {
+    primary: string;
+    secondary: string;
+    accent: string;
+    background: string;
+    text: string;
+    headingFont: string;
+    bodyFont: string;
+    fontWeight: number;
+    spacing: number;
+    spacingLg: number;
+    spacingSm: number;
+    fontSize: number;
+    fontSizeBody: number;
+}
+/**
+ * Resolve a complete TokenSet from optional overrides and canvas width.
+ *
+ * Responsive spacing is calculated as a proportion of width:
+ * - spacing: width * 0.03
+ * - spacingLg: width * 0.05
+ * - spacingSm: width * 0.015
+ * - fontSize: width * 0.04
+ * - fontSizeBody: width * 0.02
+ */
+export declare function resolveTokens(overrides?: TokenOverrides, width?: number): TokenSet;

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

@@ -0,0 +1,67 @@
+/**
+ * AUDIO_MIX — the one SSOT for audio design policy (spec 2026-07-20
+ * time-synced-sfx-audio-design §5). Consumed by the director's sfxCompile
+ * (placement) AND the evaluation audio floors (grading) so the resolver and the
+ * grader can never disagree on what "too dense" means.
+ *
+ * The content-kind split is the restraint rule: real footage (a transcript with
+ * words exists) gets the left column BY CONSTRUCTION — podcasts / talking-head
+ * content cannot be opted into generated-tier density except via the explicit
+ * `dense` intensity.
+ */
+/** How the compose classifies the content for audio policy. */
+export type AudioContentKind = "real-footage" | "generated";
+/** SFX placement intensity (brief `audio.sfx.intensity` / brand `sfxIntensity`). */
+export type SfxIntensity = "off" | "light" | "standard" | "dense";
+export interface SfxDensityPolicy {
+    /** Max SFX hits per rolling 30s window. */
+    maxHitsPer30s: number;
+    /** Min seconds between any two hit transients. */
+    minSpacingSec: number;
+    /** Whether enumeration/sequence items may tick per element entrance. */
+    perElementTicks: boolean;
+    /** Cap on per-element ticks within one graphic (when enabled). */
+    maxTicksPerGraphic: number;
+    /** Default hit level (dB, applied as `volumeDb` on the SFX clip). */
+    hitDb: number;
+}
+/** Density policy per content kind at each intensity. `off` emits nothing (the
+ *  resolver returns [] before consulting this table). `dense` on real footage is
+ *  the explicit opt-in that unlocks the generated-tier caps. */
+export declare const SFX_DENSITY: Record<AudioContentKind, Record<Exclude<SfxIntensity, "off">, SfxDensityPolicy>>;
+/** Default intensity per content kind when brief/brand express audio intent but
+ *  no explicit sfx intensity. */
+export declare const DEFAULT_SFX_INTENSITY: Record<AudioContentKind, Exclude<SfxIntensity, "off">>;
+/** Speech-collision policy (real footage only — generated content has no speech
+ *  unless VO ships): a hit whose transient lands inside a speech word ±150ms is
+ *  attenuated a further -6 dB; risers that would UNDERLAP speech are dropped. */
+export declare const SPEECH_COLLISION: {
+    readonly windowMs: 150;
+    readonly attenuateDb: -6;
+};
+/** Music bed defaults (spec §6): base level, fades, duck. */
+export declare const MUSIC_BED: {
+    readonly volumeDb: -21;
+    readonly fadeInMs: 500;
+    readonly fadeOutMs: 1200;
+    readonly duck: {
+        readonly duckDb: -12;
+        readonly attackMs: 150;
+        readonly releaseMs: 400;
+    };
+};
+/** Ambience bed defaults (audio-substrate P0). Like a music bed — it LOOPS to
+ *  fill the timeline — but the founder ruling is that ambience HOLDS under VO: it
+ *  sits at the BOTTOM of the mix (a further −5 dB below the music bed) and is
+ *  NEVER duck-stamped (no `duck` key — the absence IS the contract; the render's
+ *  duck pass only ever acts on music/vo roles). No beat map, no anchor semantics. */
+export declare const AMBIENCE_BED: {
+    readonly volumeDb: -26;
+    readonly fadeInMs: 500;
+    readonly fadeOutMs: 1200;
+};
+/** Dedicated audio track ids — separate tracks so the no-overlap invariant never
+ *  fights bed-vs-hit, and so eval can address each role's track. */
+export declare const SFX_TRACK_ID = "track-audio-sfx";
+export declare const MUSIC_TRACK_ID = "track-audio-music";
+export declare const AMBIENCE_TRACK_ID = "track-audio-ambience";

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

@@ -0,0 +1,61 @@
+/**
+ * AUDIO_MIX — the one SSOT for audio design policy (spec 2026-07-20
+ * time-synced-sfx-audio-design §5). Consumed by the director's sfxCompile
+ * (placement) AND the evaluation audio floors (grading) so the resolver and the
+ * grader can never disagree on what "too dense" means.
+ *
+ * The content-kind split is the restraint rule: real footage (a transcript with
+ * words exists) gets the left column BY CONSTRUCTION — podcasts / talking-head
+ * content cannot be opted into generated-tier density except via the explicit
+ * `dense` intensity.
+ */
+/** Density policy per content kind at each intensity. `off` emits nothing (the
+ *  resolver returns [] before consulting this table). `dense` on real footage is
+ *  the explicit opt-in that unlocks the generated-tier caps. */
+export const SFX_DENSITY = {
+    "real-footage": {
+        light: { maxHitsPer30s: 3, minSpacingSec: 2.5, perElementTicks: false, maxTicksPerGraphic: 0, hitDb: -18 },
+        standard: { maxHitsPer30s: 3, minSpacingSec: 2.5, perElementTicks: false, maxTicksPerGraphic: 0, hitDb: -18 },
+        dense: { maxHitsPer30s: 8, minSpacingSec: 1.2, perElementTicks: true, maxTicksPerGraphic: 5, hitDb: -12 },
+    },
+    generated: {
+        light: { maxHitsPer30s: 4, minSpacingSec: 2.0, perElementTicks: false, maxTicksPerGraphic: 0, hitDb: -14 },
+        standard: { maxHitsPer30s: 8, minSpacingSec: 1.2, perElementTicks: true, maxTicksPerGraphic: 5, hitDb: -12 },
+        dense: { maxHitsPer30s: 12, minSpacingSec: 0.8, perElementTicks: true, maxTicksPerGraphic: 5, hitDb: -12 },
+    },
+};
+/** Default intensity per content kind when brief/brand express audio intent but
+ *  no explicit sfx intensity. */
+export const DEFAULT_SFX_INTENSITY = {
+    "real-footage": "light",
+    generated: "standard",
+};
+/** Speech-collision policy (real footage only — generated content has no speech
+ *  unless VO ships): a hit whose transient lands inside a speech word ±150ms is
+ *  attenuated a further -6 dB; risers that would UNDERLAP speech are dropped. */
+export const SPEECH_COLLISION = {
+    windowMs: 150,
+    attenuateDb: -6,
+};
+/** Music bed defaults (spec §6): base level, fades, duck. */
+export const MUSIC_BED = {
+    volumeDb: -21,
+    fadeInMs: 500,
+    fadeOutMs: 1200,
+    duck: { duckDb: -12, attackMs: 150, releaseMs: 400 },
+};
+/** Ambience bed defaults (audio-substrate P0). Like a music bed — it LOOPS to
+ *  fill the timeline — but the founder ruling is that ambience HOLDS under VO: it
+ *  sits at the BOTTOM of the mix (a further −5 dB below the music bed) and is
+ *  NEVER duck-stamped (no `duck` key — the absence IS the contract; the render's
+ *  duck pass only ever acts on music/vo roles). No beat map, no anchor semantics. */
+export const AMBIENCE_BED = {
+    volumeDb: -26,
+    fadeInMs: 500,
+    fadeOutMs: 1200,
+};
+/** Dedicated audio track ids — separate tracks so the no-overlap invariant never
+ *  fights bed-vs-hit, and so eval can address each role's track. */
+export const SFX_TRACK_ID = "track-audio-sfx";
+export const MUSIC_TRACK_ID = "track-audio-music";
+export const AMBIENCE_TRACK_ID = "track-audio-ambience";

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

@@ -0,0 +1,5 @@
+export * from "./audioMix.js";
+export * from "./mixStaging.js";
+export * from "./pack.js";
+export * from "./musicPack.js";
+export * from "./palette.js";

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

@@ -0,0 +1,5 @@
+export * from "./audioMix";
+export * from "./mixStaging";
+export * from "./pack";
+export * from "./musicPack";
+export * from "./palette";

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

@@ -0,0 +1,107 @@
+/**
+ * mixStaging — the engine's DEFAULT gain-staging policy + the hierarchy-inversion
+ * advisory (audio-substrate P0, Phase 3 — "the engine owns the default mix").
+ *
+ * The role taxonomy (`audioRole: vo|music|sfx|ambience`) encodes Murch's clarity
+ * hierarchy VO > sfx > music > ambience. Before this pass, relative levels were
+ * per-clip author folklore (authored `volumeDb`; absent ⇒ unity), which produced
+ * a 1.5 dB VO-over-bed mush in the memoir benchmark. This module is the ONE SSOT
+ * for two calibrated behaviours:
+ *
+ *   1. ROLE_DEFAULT_GAIN_DB — the level a role-tagged clip gets WHEN its source
+ *      carries NO authored level. An authored `volumeDb`/`volume` ALWAYS wins
+ *      (author's word); a clip with NO `audioRole` keeps unity (today's behaviour
+ *      — the engine never guesses a role). Applied at render time in exactly one
+ *      place (`compositionToRenderInput`) so every render lane inherits it.
+ *   2. detectMixHierarchyInversion — an ADVISORY (never blocks) raised when
+ *      AUTHORED levels invert the hierarchy (e.g. a music clip effectively louder
+ *      than a vo clip). Compares EFFECTIVE (authored-or-default) dB.
+ *
+ * Mastering (loudnorm −14 LUFS on Modal /master) is orthogonal and UNCHANGED —
+ * this shapes the RELATIVE mix the master then normalises as a whole.
+ */
+import type { Composition } from "../validators/index.js";
+export type AudioRole = "vo" | "sfx" | "music" | "ambience";
+/**
+ * ROLE_DEFAULT_GAIN_DB — engine default level per role (dB relative to source),
+ * calibrated to the doctrine's ≥6 dB-VO-over-bed rule:
+ *
+ *   vo        0 dB  — the clarity reference; the mix anchors on speech.
+ *   sfx      −6 dB  — punctuation: audible under VO, never masks it.
+ *   music   −16 dB  WHEN VO is present anywhere in the composition — a ≥16 dB bed
+ *                   keeps speech intelligible with peak headroom (the 1.5 dB
+ *                   memoir mush becomes ≥16 dB of separation).
+ *            −8 dB  WHEN no VO clip exists — a music-driven montage must not bury
+ *                   its own bed, so it sits forward. (This conditional is the
+ *                   load-bearing one.)
+ *   ambience −22 dB — bottom of the mix; HOLDS under VO (never ducks).
+ */
+export declare const ROLE_DEFAULT_GAIN_DB: {
+    readonly vo: 0;
+    readonly sfx: -6;
+    readonly music: {
+        readonly withVo: -16;
+        readonly withoutVo: -8;
+    };
+    readonly ambience: -22;
+};
+/** The clarity hierarchy, loudest-first. Lower index = should sit higher in the
+ *  mix. Used by the inversion advisory. */
+export declare const ROLE_HIERARCHY: readonly AudioRole[];
+/** Resolve the engine default level (dB) for a role. `music` is conditional on
+ *  whether the composition contains any VO. */
+export declare function roleDefaultGainDb(role: AudioRole, voPresent: boolean): number;
+/**
+ * True when ANY clip in ANY enabled track declares `audioRole: 'vo'`. VO can be a
+ * dedicated audio clip OR a talking-head video clip's own audio, so this scans
+ * every track kind (not just audio) — the music-conditional default depends on it.
+ */
+export declare function compositionHasVo(composition: Composition): boolean;
+/**
+ * Effective level (dB relative to source) of a media clip source under the mix
+ * policy: authored `volumeDb` wins; else authored linear `volume` converted to
+ * dB (`20·log10`); else the role default. A role-less source has no policy level
+ * (returns undefined — it stays at unity, out of the hierarchy comparison).
+ */
+export declare function effectiveClipGainDb(source: {
+    volumeDb?: number;
+    volume?: number;
+    audioRole?: AudioRole;
+}, voPresent: boolean): number | undefined;
+/** One authored sfx transient: a clipId + its timeline position in milliseconds. */
+export interface SfxTransient {
+    clipId: string;
+    startMs: number;
+}
+/**
+ * Authored sfx transients (audio-substrate P0, Phase 4 — the AV-sync floor): every
+ * clip whose source is a media clip tagged `audioRole: 'sfx'`, as {clipId, startMs}
+ * where startMs is the clip's authored timeline position (`startTime`, seconds → ms).
+ * Sorted earliest-first. These are the "expected transients" the delivered-mix onset
+ * analysis matches against — an sfx hit that lands nowhere near a detected onset has
+ * drifted. PURE (no I/O); the render policy (cap, fail/advisory) lives in the director.
+ */
+export declare function sfxTransients(composition: Composition): SfxTransient[];
+/**
+ * Detect a composition with NO deliberate audio at all — no audio-family
+ * track content, no role-tagged media clip, and every video media clip muted
+ * (or all silent stills/cards). "Silence is a level" only when someone CHOSE
+ * it: a marker of kind "intentional-silence" suppresses the advisory.
+ *
+ * ADVISORY only — pushed onto the render `warnings[]` channel, never blocks.
+ * Craft basis: video-craft-standards cross-cutting rule "audio is decided,
+ * never defaulted" (three clean-agent trials shipped silent reels because
+ * nothing asked the question — 2026-07-30).
+ */
+export declare function detectNoAudioTrack(composition: Composition): string[];
+/**
+ * Detect hierarchy inversions across the ROLES PRESENT in the composition and
+ * return one advisory string per offending (higher-role, lower-role) pair. An
+ * inversion is a lower-priority role's LOUDEST clip sitting above a
+ * higher-priority role's QUIETEST clip (e.g. any music clip above any vo clip).
+ *
+ * ADVISORY only — the caller pushes these onto the render `warnings[]` channel;
+ * they NEVER block a render. Because engine defaults are hierarchy-correct by
+ * construction, only AUTHORED levels can trip this.
+ */
+export declare function detectMixHierarchyInversion(composition: Composition): string[];