@cueframe/kernel 0.0.1

package/dist/_members/primitives/lib/schema.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Zod → JSON Schema → controls / defaults.
+ *
+ * One canonical zod schema per primitive (declared in `config.ts`); this
+ * module derives:
+ *   - JSON Schema for the agent's `apply_template` validation (Ajv).
+ *   - Prop defaults (materialized from `.default()` calls).
+ *   - Customizer controls for the drawer UI.
+ *
+ * No drift: all three derive from the same source.
+ */
+import { z } from 'zod';
+export declare function zodToJsonSchemaFor(schema: z.ZodTypeAny, name: string): Record<string, unknown>;
+/**
+ * Walk a zod schema and extract all `.default()` values into a flat object.
+ *
+ * Supports `ZodObject` at the top level. Nested objects are walked
+ * recursively; arrays / unions / records are skipped (their defaults must
+ * be declared at the array level via `.default([...])`).
+ */
+export declare function zodToDefaults(schema: z.ZodTypeAny): Record<string, unknown>;
+export type ControlType = 'string' | 'number' | 'boolean' | 'select' | 'color';
+export interface ControlConfig {
+    /** Field name in the params object (top-level only — nested not supported). */
+    name: string;
+    /** Display label (defaults to humanized field name). */
+    label?: string;
+    /** Description for tooltip / hover (from zod `.describe()`). */
+    description?: string;
+    /** Control widget type. */
+    type: ControlType;
+    /** Default value (from zod `.default()`). */
+    defaultValue?: unknown;
+    /** For type='number': min/max/step. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** For type='select': allowed values. */
+    options?: readonly string[];
+    /** Whether the field is required. */
+    required: boolean;
+}
+/**
+ * Derive controls from a zod schema for the drawer customizer UI.
+ *
+ * Heuristics:
+ *   - `z.string()` → `'string'` (or `'color'` if name matches /color|colour|hex/i)
+ *   - `z.number()` → `'number'` with min/max from `.min()`/`.max()`
+ *   - `z.boolean()` → `'boolean'`
+ *   - `z.enum([...])` → `'select'` with options
+ *   - Wrapped in `.optional()` / `.default()` → unwrapped, defaultValue extracted
+ */
+export declare function zodToControls(schema: z.ZodTypeAny): ControlConfig[];

package/dist/_members/primitives/lib/schema.js

@@ -0,0 +1,12 @@
+import {
+  zodToControls,
+  zodToDefaults,
+  zodToJsonSchemaFor
+} from "../chunk-DH5TRZK2.js";
+import "../chunk-UVKRO5ER.js";
+export {
+  zodToControls,
+  zodToDefaults,
+  zodToJsonSchemaFor
+};
+//# sourceMappingURL=schema.js.map

package/dist/_members/primitives/lib/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/seeded-random.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Seeded random helpers.
+ *
+ * Wraps Remotion's deterministic `random(seed)` with helpers commonly
+ * needed by primitives: `pick`, `range`, `gauss`, plus a small PRNG class
+ * for primitives that want a stateful sequence (Particles, Grain).
+ *
+ * Why centralized:
+ *   - Several primitives reimplement the same xorshift / linear
+ *     congruential generator inline. One source of truth.
+ *   - Determinism across renders (Lambda + local) requires every random
+ *     call to derive from a stable seed.
+ */
+/** Pick one element from `arr` deterministically using `seed`. */
+export declare function pick<T>(seed: number | string, arr: readonly T[]): T;
+/** Uniform random in `[min, max)` using `seed`. */
+export declare function range(seed: number | string, min: number, max: number): number;
+/**
+ * Approximate Gaussian sample using the Box-Muller method, deterministic per seed.
+ * Returns a value with mean=0, stddev=1 by default.
+ */
+export declare function gauss(seed: number | string, mean?: number, stddev?: number): number;
+/**
+ * Linear congruential generator. Same algorithm cueframe's existing
+ * Particles/Grain primitives use inline; promoted here so they share one impl.
+ */
+export declare class SeededPRNG {
+    private state;
+    constructor(seed: number);
+    next(): number;
+    nextInt(maxExclusive: number): number;
+    nextRange(min: number, max: number): number;
+}

package/dist/_members/primitives/lib/seeded-random.js

@@ -0,0 +1,14 @@
+import {
+  SeededPRNG,
+  gauss,
+  pick,
+  range
+} from "../chunk-YN7WTZZ7.js";
+import "../chunk-UVKRO5ER.js";
+export {
+  SeededPRNG,
+  gauss,
+  pick,
+  range
+};
+//# sourceMappingURL=seeded-random.js.map

package/dist/_members/primitives/lib/seeded-random.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/contrast.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Legibility floor for text-on-video surfaces.
+ *
+ * Only Captions/Karaoke baked a contrast shadow before this; every other text
+ * primitive shipped raw `#171717`-on-transparent with no shadow and vanished on
+ * real footage. This is the shared module the consolidation spec named but never
+ * built. Default text color is an off-white (#F7F2EA) — softer than pure white,
+ * resolved through the brand `colors.textOnMedia` first — plus the proven
+ * two-layer drop shadow (lifted from Captions) so white text survives on any
+ * video. behind-subject hosts (HeroText) opt out of the shadow because the
+ * subject silhouette supplies the depth, but still get a real off-white color.
+ */
+export interface ContrastResult {
+    textColor: string;
+    textShadow: string;
+}
+/**
+ * Single source of truth for the legibility floor. Every text primitive's
+ * default color + baked shadow derive from these — import them rather than
+ * re-typing the literals, so the floor changes in exactly one place.
+ */
+export declare const FLOOR_TEXT = "#F7F2EA";
+export declare const FLOOR_SHADOW = "0 1px 6px rgba(0,0,0,0.55)";
+export declare function resolveContrast(opts?: {
+    brandTextOnMedia?: string;
+    behindSubject?: boolean;
+}): ContrastResult;

package/dist/_members/primitives/lib/text/contrast.js

@@ -0,0 +1,12 @@
+import {
+  FLOOR_SHADOW,
+  FLOOR_TEXT,
+  resolveContrast
+} from "../../chunk-7RRPFPQK.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  FLOOR_SHADOW,
+  FLOOR_TEXT,
+  resolveContrast
+};
+//# sourceMappingURL=contrast.js.map

package/dist/_members/primitives/lib/text/contrast.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/fill.d.ts

@@ -0,0 +1,8 @@
+import type { CSSProperties } from 'react';
+import type { TextFill } from './spec.js';
+/**
+ * CSS for a text fill. `solid` → a plain text color; `gradient` → a CSS gradient
+ * painted INTO the glyphs via bg-clip-text (the emphasis-gradient axis, extracted
+ * verbatim from Captions). Pure.
+ */
+export declare function fillStyle(fill: TextFill): CSSProperties;

package/dist/_members/primitives/lib/text/fill.js

@@ -0,0 +1,8 @@
+import {
+  fillStyle
+} from "../../chunk-HIWVFZVH.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  fillStyle
+};
+//# sourceMappingURL=fill.js.map

package/dist/_members/primitives/lib/text/fill.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/fitText.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Auto-fit text for render primitives.
+ *
+ * Text slots used to render at a FIXED font size with no overflow handling, so each
+ * carried a hard `maxLength` cap — natural agent copy overflowed it and the write-
+ * boundary validation rejected it (guess-and-check churn). `<FitText>` measures the
+ * text and shrinks-to-fit → wraps → ellipsizes so any length renders gracefully, which
+ * lets the caps be raised to a generous legibility ceiling.
+ *
+ * `resolveFitFontSize` is the pure decision (unit-tested); the component wires
+ * remotion's `fitText` (impure DOM measurement) to feed it.
+ */
+import React from 'react';
+import { type TextTransform } from '@remotion/layout-utils';
+export interface ResolveFitInput {
+    /** Largest single-line font size that fits the text in the container, per remotion
+     *  `fitText`. `Infinity` for empty/whitespace text (nothing to shrink). */
+    singleLineFitFontSize: number;
+    /** Floor below which we stop shrinking and wrap+ellipsize instead. */
+    minFontSize: number;
+    /** The primitive's design font size — the ceiling; we never upscale past it. */
+    maxFontSize: number;
+}
+export interface ResolveFitResult {
+    fontSize: number;
+    /** True when the text can't fit on one line even at `minFontSize` — the caller
+     *  should wrap to `maxLines` and clip with an ellipsis. */
+    overflow: boolean;
+}
+/** Clamp the measured single-line fit size into [min, max] and report floor overflow.
+ *  Never upscales past the design size; a fit at/above the floor is clean. */
+export declare function resolveFitFontSize({ singleLineFitFontSize, minFontSize, maxFontSize, }: ResolveFitInput): ResolveFitResult;
+export interface FitTextProps {
+    /** The text to render (the single source that used to carry a maxLength cap). */
+    children: string | null | undefined;
+    /** Available width of the text's box, in px (the primitive's own layout knows this). */
+    maxWidth: number;
+    /** The primitive's design font size — the ceiling; text never renders larger. */
+    maxFontSize: number;
+    /** Lines the text may wrap to before it clamps + ellipsizes. Default 1 (titles/labels);
+     *  use 2–3 for bodies. */
+    maxLines?: number;
+    /** Floor below which we stop shrinking and clamp+ellipsize. Default 55% of maxFontSize. */
+    minFontSize?: number;
+    fontFamily: string;
+    fontWeight?: number | string;
+    letterSpacing?: string;
+    /** The measurer's CLOSED union, not csstype's open `string & {}` one — the
+     *  measurement must see exactly the value the DOM will render, so arbitrary
+     *  strings are refused at compile time (they'd measure as a no-op). */
+    textTransform?: TextTransform;
+    /** Extra styles (color, textShadow, background, padding, …) merged last. */
+    style?: React.CSSProperties;
+}
+/**
+ * Render `children` at the largest size that fits `maxWidth` on `maxLines`, shrinking
+ * from `maxFontSize` down to `minFontSize`; anything longer clamps to the floor and
+ * ellipsizes. Replaces the raw `<div style={{fontSize}}>{text}</div>` in text primitives
+ * so long copy degrades gracefully instead of overflowing — which is what lets the
+ * `maxLength` caps be raised.
+ */
+export declare const FitText: React.FC<FitTextProps>;

package/dist/_members/primitives/lib/text/fitText.js

@@ -0,0 +1,10 @@
+import {
+  FitText,
+  resolveFitFontSize
+} from "../../chunk-ROV2ODWC.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  FitText,
+  resolveFitFontSize
+};
+//# sourceMappingURL=fitText.js.map

package/dist/_members/primitives/lib/text/fitText.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/marker.d.ts

@@ -0,0 +1,15 @@
+import type { TextMarker } from './spec.js';
+/**
+ * Hand-drawn marker scribble (a rough circle or underline) that draws itself on
+ * as `progress` goes 0→1. Stretches to fill its positioned parent (an emphasis
+ * plate / word group), so it always frames the word.
+ *
+ * The single implementation of the caption scribble — extracted verbatim from
+ * Captions' private `MarkerAnnotation`. Pure: the caller samples the frame and
+ * passes the scalar `progress`. The highlighter-BAR mechanism (marker-highlight's
+ * `scaleX` span) is a structurally different surface and is intentionally NOT here.
+ */
+export declare function Marker({ spec, progress }: {
+    spec: TextMarker;
+    progress: number;
+}): import("react").JSX.Element;

package/dist/_members/primitives/lib/text/marker.js

@@ -0,0 +1,8 @@
+import {
+  Marker
+} from "../../chunk-XHU3WBEI.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  Marker
+};
+//# sourceMappingURL=marker.js.map

package/dist/_members/primitives/lib/text/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/motion.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The shared per-word entrance vocabulary. Three NAMED pure functions (not one
+ * accreting switch): each is a faithful extraction of one surface's entrance
+ * math, so migrating that surface to call it is provably byte-identical. A
+ * surface whose transform doesn't reduce to one of these stays bespoke.
+ *
+ * Pure: the caller samples the frame and passes scalars in (no `useCurrentFrame`).
+ */
+/**
+ * `word-pop` (Captions): cubic-eased opacity + spring scale-settle, per word.
+ * `restScale` is the pre-settle scale (Captions uses 0.86 emphasis / 0.92 plain).
+ */
+export declare function wordPop(frame: number, fps: number, startFrame: number, durationFrames: number, restScale: number): {
+    opacity: number;
+    scale: number;
+};
+/**
+ * `fade` (HeroText): per-word reveal fraction 0→1 over `windowMs`, from the
+ * word's `revealAtMs`. The caller applies `opacity = k` and
+ * `translateY((1 - k) * 0.25em)` while `k < 1`.
+ */
+export declare function fadeProgress(tMs: number, revealAtMs: number, windowMs: number): number;
+/**
+ * `stagger-up` (staggered-fade-up): per-word opacity 0→1 + translateY
+ * `distance`px→0 over `windowFrames`, staggered by `index * staggerDelay`.
+ */
+export declare function staggerUp(frame: number, index: number, staggerDelay: number, windowFrames: number, distance: number): {
+    opacity: number;
+    y: number;
+};
+/**
+ * `stagger-up` vertical-rise companion to {@link staggerUp}: a word rises from
+ * `distance`px to 0 as `progress` (the same 0→1 reveal `staggerUp` returns as
+ * `opacity`) eases in:  `distance * (1 - ease(progress))`.
+ *
+ * Division-free on purpose. The schema permits `distance: 0` (`.min(0)`); the
+ * earlier `distance - ease(1 - y / distance) * distance` form divided by
+ * `distance`, so a 0-distance render computed 0/0 = NaN → `translateY(NaNpx)`.
+ * This form collapses cleanly to 0 at distance 0 and is byte-identical for
+ * distance > 0 (the old `y` satisfied `y = distance * (1 - progress)`, so
+ * `1 - y/distance === progress`).
+ */
+export declare function staggerRise(distance: number, progress: number, ease: (t: number) => number): number;
+/**
+ * Map a brand `motion.easing` keyword to a Remotion easing function for the
+ * `interpolate({ easing })` option. This is the bind target for
+ * `$brand:motion.easing` on the text family: the brand cascade resolves the
+ * keyword string into the surface's `easing` param, and the surface applies the
+ * returned curve to its per-word reveal.
+ *
+ * The keywords mirror the brand `EasingValue` STRING form. The object
+ * (cubic-bezier) form never reaches here — the brand-cascade `resolveTokenValue`
+ * only materializes string values, so an object easing misses and the binding
+ * falls to its keyword fallback. Unknown / absent → `linear` (the identity
+ * curve), so an unset easing is a no-op and existing renders are unchanged.
+ */
+export declare function resolveEasing(name?: string): (t: number) => number;

package/dist/_members/primitives/lib/text/motion.js

@@ -0,0 +1,16 @@
+import {
+  fadeProgress,
+  resolveEasing,
+  staggerRise,
+  staggerUp,
+  wordPop
+} from "../../chunk-G2B3G4HK.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  fadeProgress,
+  resolveEasing,
+  staggerRise,
+  staggerUp,
+  wordPop
+};
+//# sourceMappingURL=motion.js.map

package/dist/_members/primitives/lib/text/motion.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/recolor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Recolor a token from `from` to `to` by `progress` (0..1).
+ *
+ * The single implementation of the per-word color swap that inline-highlight,
+ * marker-highlight, and (the progress-ramped surfaces) duplicate today via
+ * `interpolateColors(progress, [0, 1], [from, to])`. Pure: no `useCurrentFrame`
+ * — the caller samples the frame and passes the scalar `progress` in.
+ *
+ * Note: Captions' emphasis recolor (Captions.tsx) is a plain CONDITIONAL color
+ * assignment (no progress ramp), so it does NOT route through this function.
+ */
+export declare function recolor(progress: number, from: string, to: string): string;

package/dist/_members/primitives/lib/text/recolor.js

@@ -0,0 +1,8 @@
+import {
+  recolor
+} from "../../chunk-W4EIIF2I.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  recolor
+};
+//# sourceMappingURL=recolor.js.map

package/dist/_members/primitives/lib/text/recolor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/spec.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared text vocabulary — the one set of types every text-bearing render
+ * surface speaks (Captions, HeroText, behind-subject text, the `text/*` effects).
+ *
+ * Seeded from the richest existing surface, `CaptionStyle`/`CaptionWord`
+ * (`@cueframe/core/render/types`), lifted to surface-neutral names. These are the
+ * VOCABULARY, not a base component: each surface maps its own props to/from these
+ * groups and renders via the `lib/text/*` modules (recolor, marker, plate, fill,
+ * motion, normalize, contrast, stage). They are deliberately DISTINCT exported
+ * sub-interfaces — never one union — so a decorative effect can import
+ * `TextTypography` alone and the type system FORBIDS it reaching emphasis fields.
+ *
+ * Design: internal spec 2026-06-14
+ */
+/** Base typographic group. `fontSizePct` is font size as a % of composition height. */
+export interface TextTypography {
+    fontFamily: string;
+    fontSizePct: number;
+    fontWeight: number;
+    fontStyle?: 'normal' | 'italic';
+    /** px */
+    letterSpacing?: number;
+    textTransform?: 'none' | 'uppercase' | 'capitalize';
+}
+/** Per-word recolor axis — interpolate a token's color from `from` to `to`. */
+export interface TextRecolor {
+    from: string;
+    to: string;
+}
+/**
+ * Hand-drawn marker annotation (scribble) over a word. The highlighter-BAR
+ * (marker-highlight's `scaleX` span) is a structurally different mechanism and
+ * is intentionally NOT part of this group — it stays its own surface.
+ */
+export interface TextMarker {
+    kind: 'circle' | 'underline';
+    color: string;
+}
+/** Editorial highlighter plate behind a contiguous emphasis run; two-tone via the `alt*` pair. */
+export interface TextPlate {
+    color: string;
+    altColor?: string;
+    textColor?: string;
+    altTextColor?: string;
+    /** px */
+    radius?: number;
+    /** fraction of emphasis font size */
+    padX?: number;
+    /** fraction of emphasis font size */
+    padY?: number;
+}
+/** Text fill — a solid color or a bg-clip-text gradient painted into the glyphs. */
+export interface TextFill {
+    kind: 'solid' | 'gradient';
+    /** hex for `solid`; a CSS gradient string for `gradient` */
+    value: string;
+}
+/**
+ * Per-word entrance/exit motion. This is the single `$brand:motion` bind target:
+ * a surface authors `durationMs`/`easing` as `$brand:motion.*` refs, which the
+ * brand model resolves at PROJECTION time (no render-time resolver change).
+ */
+export interface TextMotion {
+    entrance: 'none' | 'fade' | 'word-pop' | 'stagger-up';
+    durationMs: number;
+    /** min gap between consecutive word entrances so two never fire together */
+    staggerMs?: number;
+    easing?: string;
+    /** phrase fade-out over the page's last N ms before the next builds (0 = hard cut) */
+    exitMs?: number;
+}
+/**
+ * The per-word model. Timing is optional so untimed surfaces share the shape;
+ * `startMs`/`endMs` are composition-absolute after `normalize.tokenize()`.
+ */
+export interface TextWord {
+    text: string;
+    startMs?: number;
+    endMs?: number;
+    emphasis?: boolean;
+    marker?: TextMarker['kind'];
+}

package/dist/_members/primitives/lib/text/spec.js

@@ -0,0 +1 @@
+//# sourceMappingURL=spec.js.map

package/dist/_members/primitives/lib/text/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/stage.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+export interface TextStageProps {
+    /**
+     * Full-frame background. Default `'transparent'` — a text OVERLAY must not
+     * paint over the video. Pass a concrete/brand color only for a genuine
+     * full-frame card. (Fixes the white-card overlay bug: the surfaces this
+     * replaces hardcoded `background:"white"`. See
+     * Issues/hookstat-overlay-white-card-brand-bg.)
+     */
+    background?: string;
+    children: React.ReactNode;
+}
+/**
+ * The shared anchored layout shell for text surfaces: an absolutely-positioned,
+ * inset-0, centered container. Replaces the hand-rolled
+ * `position:absolute; inset:0; flex-center; background:"white"` wrapper
+ * duplicated across inline-highlight, marker-highlight, text-fade-replace, and
+ * strikethrough-replace.
+ *
+ * This is a thin LAYOUT shell, not an assembly base — it has no word/emphasis/
+ * motion opinion; surfaces render their own content inside it.
+ */
+export declare const TextStage: React.FC<TextStageProps>;

package/dist/_members/primitives/lib/text/stage.js

@@ -0,0 +1,8 @@
+import {
+  TextStage
+} from "../../chunk-4IS6TMEG.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  TextStage
+};
+//# sourceMappingURL=stage.js.map

package/dist/_members/primitives/lib/text/stage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_members/primitives/lib/text/typeface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Typeface resolution for text primitives.
+ *
+ * Every text-on-video surface resolves its font by ROLE through this module:
+ * brand kit first, then a deliberately chosen designed fallback — NEVER
+ * `inherit` / `sans-serif` / `monospace` (the generic system face is the #1
+ * "AI-default" tell, and the remocn fork stripped the real faces). The floor
+ * pairing is Bricolage Grotesque (display) + Schibsted Grotesk (caption), both
+ * OFL and bundled in the render harness; mono reuses the already-bundled
+ * Space Mono.
+ */
+export type TextRole = 'display' | 'caption' | 'mono';
+export interface TypefaceBrandKit {
+    fonts?: Partial<Record<'heading' | 'caption' | 'mono', string>>;
+}
+export declare function resolveTypeface(role: TextRole, brandKit?: TypefaceBrandKit): string;

package/dist/_members/primitives/lib/text/typeface.js

@@ -0,0 +1,8 @@
+import {
+  resolveTypeface
+} from "../../chunk-3IQUH6KK.js";
+import "../../chunk-UVKRO5ER.js";
+export {
+  resolveTypeface
+};
+//# sourceMappingURL=typeface.js.map

package/dist/_members/primitives/lib/text/typeface.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}