@cueframe/kernel 0.0.1

package/dist/_members/authoring/types.d.ts

@@ -0,0 +1,572 @@
+export interface RubricDimension {
+    name: string;
+    weight: number;
+    description: string;
+}
+export interface EvaluatorRubric {
+    dimensions: RubricDimension[];
+    passThreshold: number;
+}
+export interface EvaluationResult {
+    scores: Record<string, number>;
+    weightedScore: number;
+    passed: boolean;
+    critique: string;
+    evidence: string[];
+}
+export type DirectorMode = 'auto' | 'single-pass' | 'multi-phase';
+export interface Phase {
+    name: string;
+    output: 'timeline_edit' | 'artifact' | 'scene_composition';
+    description: string;
+    verificationCriteria: string[];
+    /** Number of evaluation passes. 0 = skip evaluation, 1 for timeline, 3 for content. */
+    evaluationPasses: number;
+    /** Tool names to include for this phase. Empty = all tools available. */
+    tools: string[];
+    status: 'pending' | 'executing' | 'passed' | 'failed' | 'skipped';
+}
+export interface PhaseResult {
+    success: boolean;
+    textResponse?: string;
+    error?: string;
+    usage: import('ai').LanguageModelUsage;
+}
+export interface OverlayData {
+    id: string;
+    template: 'custom' | 'gif' | 'image' | 'lottie' | (string & {});
+    startTime: number;
+    duration: number;
+    rippled?: boolean;
+    params: {
+        text: string;
+        subtext?: string;
+        position?: 'left' | 'center' | 'right';
+        accentColor?: string;
+        textColor?: string;
+        fontFamily?: string;
+        backgroundColor?: string;
+        sourceCode?: string;
+        jsxSource?: string;
+        transition?: 'fade' | 'slide' | 'wipe' | 'none';
+        sequenceGroup?: string;
+        src?: string;
+        heroImageUrl?: string;
+        loop?: boolean;
+        widthPercent?: number;
+        xPercent?: number;
+        yPercent?: number;
+    };
+}
+export interface PoolItemData {
+    id: string;
+    name: string;
+    /** Pool kind (video|audio|image). Optional: headless lanes may omit it. */
+    kind?: string;
+    /** Local/presigned URL for the bytes — what view_asset fetches for a still. */
+    assetUrl?: string;
+    duration: number;
+    width: number;
+    height: number;
+}
+export interface ClipData {
+    id: string;
+    poolItemId: string;
+    sourceIn: number;
+    sourceOut: number;
+    timelineStart: number;
+    timelineEnd: number;
+    playbackRate?: number;
+    volume?: number;
+    muted?: boolean;
+}
+export interface PlayerStateData {
+    currentTime: number;
+    isPlaying: boolean;
+    playbackRate: number;
+}
+export interface DirectorContext {
+    currentTime: number;
+    timelineDuration: number;
+    fps: number;
+    /** Canvas format: aspect ratio, optional fps + resolution. Mirrors the wire-shape `Composition.format`. */
+    format?: {
+        aspectRatio: '16:9' | '9:16' | '1:1' | '4:5';
+        fps?: 24 | 30 | 60;
+        resolution?: 'hd' | 'fhd' | '4k';
+    };
+    transcript?: string;
+    /** True when word-level timings were stripped to fit context budget */
+    transcriptTruncated?: boolean;
+    /** True when word-level timings are included in the transcript, false when stripped for budget */
+    transcriptHasTimings?: boolean;
+    clips: ClipData[];
+    sceneLabels?: Array<{
+        clipId: string;
+        name: string;
+        layout?: string;
+    }>;
+    overlays: Array<{
+        id: string;
+        template: string;
+        text: string;
+        subtext?: string;
+        startTime: number;
+        duration: number;
+        position?: 'left' | 'center' | 'right';
+        accentColor?: string;
+        isCustom?: boolean;
+        transition?: 'fade' | 'slide' | 'wipe' | 'none';
+        sequenceGroup?: string;
+    }>;
+    brandKit?: {
+        name: string;
+        tagline?: string;
+        secondaryTagline?: string;
+        colors: {
+            primary: string;
+            secondary: string;
+            accent: string;
+            background: string;
+            text: string;
+        };
+        extraColors: Array<{
+            hex: string;
+            label: string;
+            usage?: string;
+        }>;
+        headingFont: {
+            fontFamily: string;
+            fontWeight: number;
+        };
+        bodyFont: {
+            fontFamily: string;
+            fontWeight: number;
+        };
+        voiceGuidelines: string;
+        heroImageUrl?: string;
+    };
+    /**
+     * Detected faces in the source clip(s) — the `face-0..N` roster from
+     * source-level subject detection (faces + active-speaker). Lets the agent
+     * author `{ kind: "face", faceId }` crop intents against REAL detected faces
+     * instead of guessing. Empty when detection hasn't run for this clip.
+     */
+    faces?: SubjectFaceInfo[];
+}
+/** One detected face surfaced to the agent via get_context. */
+export interface SubjectFaceInfo {
+    /** Stable id within the clip's source window; `face-0` = largest/primary. */
+    faceId: string;
+    /** Fraction of the clip this face is the active speaker (0..1), if known. */
+    speakingShare?: number;
+    /** Median normalized bbox over the window (0..1) — a placement hint. */
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface StockMediaResult {
+    id: string | number;
+    title: string;
+    thumbnail: string;
+    previewUrl?: string;
+    downloadUrl: string;
+    duration?: number;
+    width: number;
+    height: number;
+    photographer: string;
+    mediaType: 'video' | 'photo';
+}
+/**
+ * Stock video candidate returned by `searchStockVideos` / `searchPixabayVideos`.
+ *
+ * Stricter than `StockMediaResult`:
+ *   - `provider` is required (so consumers can render attribution + key by it)
+ *   - `externalId` is always a string (Pexels uses numeric IDs, Pixabay
+ *     too — normalise here so downstream cache keys / dedupe sets don't
+ *     have to coerce)
+ *   - `query` echoes the search term that surfaced the candidate (used by
+ *     the b-roll enrichment pipeline to attribute hits to suggestions)
+ *   - `duration`, `previewUrl` are required (b-roll filter relies on
+ *     duration; UI always shows a hover preview)
+ *   - `photographerUrl` + `assetUrl` enable Pexels / Pixabay TOS-mandated
+ *     backlinks
+ *
+ * `StockMediaResult` is retained for the photo path where these fields
+ * don't apply (no duration, no provider page per asset on the photo APIs we use).
+ */
+export interface StockVideoCandidate {
+    provider: 'pexels' | 'pixabay';
+    externalId: string;
+    query: string;
+    thumbnail: string;
+    previewUrl: string;
+    downloadUrl: string;
+    duration: number;
+    width: number;
+    height: number;
+    photographer: string;
+    photographerUrl?: string;
+    /** Provider-specific page for this asset (Pexels `url`, Pixabay `pageURL`).
+     *  Used by the UI to satisfy Pexels TOS ("link to the photo page on Pexels"). */
+    assetUrl?: string;
+}
+export interface SoundEffectResult {
+    id: number;
+    name: string;
+    previewUrl: string;
+    downloadUrl: string;
+    duration: number;
+    tags: string[];
+    license: string;
+}
+/**
+ * Photo candidate returned by the activity-shape variant of
+ * `searchStockPhotos` / `searchPixabayPhotos`. Mirrors
+ * `StockVideoCandidate` minus `duration` (photos have no duration).
+ * Used by the Temporal clip-enrichment activity which persists rows
+ * matching `data-models/convex-schemas/src/enrichment.ts` candidateShape.
+ */
+export interface StockPhotoCandidate {
+    provider: 'pexels' | 'pixabay';
+    externalId: string;
+    query: string;
+    thumbnail: string;
+    previewUrl: string;
+    downloadUrl: string;
+    width: number;
+    height: number;
+    photographer: string;
+    photographerUrl?: string;
+    assetUrl?: string;
+}
+/**
+ * Sound-effect candidate returned by `searchSoundEffectsCandidates`.
+ * Shaped like `StockVideoCandidate` minus width/height (sfx has no
+ * spatial dimensions) and with required `licenseCode` so the call site
+ * can filter to CC0 before persistence. `assetUrl` points to the
+ * Freesound sound page (TOS-mandated attribution link).
+ */
+export interface StockSoundCandidate {
+    provider: 'freesound';
+    externalId: string;
+    query: string;
+    thumbnail: string;
+    previewUrl: string;
+    downloadUrl: string;
+    duration: number;
+    photographer: string;
+    photographerUrl?: string;
+    assetUrl: string;
+    licenseCode: string;
+}
+/**
+ * GIF/clip candidate returned by `searchKlipyCandidates` (clips API
+ * variant — MP4-backed reaction clips, better suited for overlay than
+ * raw GIFs). `duration` is optional because Klipy doesn't always
+ * surface it; the enrichment activity's duration filter treats
+ * `undefined` as permissive (GIFs loop on playback).
+ */
+export interface StockGifCandidate {
+    provider: 'klipy';
+    externalId: string;
+    query: string;
+    thumbnail: string;
+    previewUrl: string;
+    downloadUrl: string;
+    duration?: number;
+    width: number;
+    height: number;
+    photographer: string;
+    photographerUrl?: string;
+    assetUrl?: string;
+}
+export interface FontResult {
+    family: string;
+    category: string;
+    variants: string[];
+    cssUrl: string;
+    previewText: string;
+}
+export interface GifClipResult {
+    id: string;
+    title: string;
+    gifUrl: string;
+    mp4Url?: string;
+    width: number;
+    height: number;
+    type: 'gif' | 'clip';
+}
+export interface LottieResult {
+    id: string;
+    name: string;
+    jsonUrl: string;
+    lottieUrl: string;
+    previewUrl: string;
+    tags: string[];
+}
+export type ResourceSearchResult = {
+    type: 'stock_media';
+    results: StockMediaResult[];
+} | {
+    type: 'sound_effects';
+    results: SoundEffectResult[];
+} | {
+    type: 'fonts';
+    results: FontResult[];
+} | {
+    type: 'gif_clip';
+    results: GifClipResult[];
+} | {
+    type: 'lottie';
+    results: LottieResult[];
+};
+export interface ToolResult {
+    toolName: string;
+    success: boolean;
+    message: string;
+    overlayId?: string;
+    clipId?: string;
+    /** Tool execution wall-clock, measured around execute() by the hook wrapper
+     *  (instrumentation 2026-07-17 — tool time was invisible in every trace;
+     *  the audit had to reconstruct it from inter-generation gaps). */
+    durationMs?: number;
+    /** Serialized argument / result sizes (bytes) — the context-growth ledger
+     *  (fat tool results were +10k-token jumps nobody could attribute). */
+    argsBytes?: number;
+    resultBytes?: number;
+}
+/** Per-step loop metrics — emitted by the Agent's onStepFinish so hidden
+ *  (thinking) output, cache efficiency, and step latency are first-class
+ *  telemetry instead of a trace-archaeology exercise (2026-07-17 audit:
+ *  94% of output tokens were invisible thinking; nobody had measured). */
+export interface StepMetrics {
+    stepIndex: number;
+    toolNames: string[];
+    /** Model-visible output: text chars + serialized tool-call arg chars. */
+    visibleChars: number;
+    outputTokens?: number;
+    /** Uncached prompt tokens this step (the re-billed conversation tail). */
+    inputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** reasoning tokens when the provider reports them; else derive
+     *  hidden ≈ outputTokens - visibleChars/4 downstream. */
+    reasoningTokens?: number;
+    finishReason?: string;
+}
+export interface DirectorResult {
+    success: boolean;
+    results: ToolResult[];
+    textResponse?: string;
+    error?: string;
+    /** CLI session ID — enables session resumption on the next invocation. */
+    cliSessionId?: string;
+    /** Token usage from the LLM provider. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface VisualIssue {
+    type: 'text' | 'positioning' | 'animation' | 'color' | 'visibility' | 'layout' | 'artifact' | 'error';
+    description: string;
+    suggestedFix: string;
+}
+export interface VisualVerdict {
+    approved: boolean;
+    issues: VisualIssue[];
+    summary: string;
+}
+export type AgentRole = 'router' | 'timeline' | 'graphics' | 'resources';
+export type ProgressEvent = {
+    type: 'agent-start';
+    agent: AgentRole;
+    task: string;
+    timestamp: number;
+} | {
+    type: 'tool-call';
+    agent: AgentRole;
+    toolName: string;
+    args: Record<string, unknown>;
+    toolCallId: string;
+    timestamp: number;
+} | {
+    type: 'tool-result';
+    agent: AgentRole;
+    toolName: string;
+    success: boolean;
+    message: string;
+    toolCallId: string;
+    timestamp: number;
+} | {
+    type: 'text-delta';
+    agent: AgentRole;
+    text: string;
+    timestamp: number;
+} | {
+    type: 'thinking-delta';
+    agent: AgentRole;
+    text: string;
+    timestamp: number;
+} | {
+    type: 'agent-finish';
+    agent: AgentRole;
+    text?: string;
+    timestamp: number;
+} | {
+    type: 'agent-error';
+    agent: AgentRole;
+    error: string;
+    timestamp: number;
+} | {
+    type: 'suggestions';
+    suggestions: string[];
+    timestamp: number;
+} | {
+    type: 'phase-change';
+    phase: 'analyzing' | 'planning' | 'awaiting-approval' | 'executing';
+    detail?: string;
+    timestamp: number;
+} | {
+    type: 'plan-proposal';
+    plan: string;
+    timestamp: number;
+} | {
+    type: 'iteration';
+    iteration: number;
+    maxIterations: number;
+    agent: AgentRole;
+    timestamp: number;
+};
+export type OnProgressCallback = (event: ProgressEvent) => void;
+export type ApprovalFn = (toolCallId: string, toolName: string, args?: Record<string, unknown>) => Promise<boolean>;
+/** Per-criterion pass/fail with structured feedback. */
+export interface CriteriaResult {
+    passed: boolean;
+    criteria: Array<{
+        name: string;
+        passed: boolean;
+        feedback?: string;
+    }>;
+    bestAttempt: number;
+}
+/** Configuration for the Agent class. */
+export interface AgentConfig {
+    /** Language model to use for generation. */
+    model: import('ai').LanguageModel;
+    /** System prompt for the agent. */
+    systemPrompt: string;
+    /** Capabilities — without these, the agent has no tools. */
+    capabilities?: import('./capabilities.js').AgentCapabilities;
+    /** Lifecycle hooks. */
+    hooks?: {
+        beforeToolCall?: (name: string, args: Record<string, unknown>) => boolean | Promise<boolean>;
+        afterToolCall?: (name: string, result: ToolResult) => void;
+        /** Per-step metrics sink (usage split, visible vs hidden output, cache
+         *  efficiency). Called after each loop step with StepMetrics. */
+        onStepMetrics?: (metrics: StepMetrics) => void;
+        afterEvaluate?: (criteria: Record<string, string>, result: CriteriaResult) => void;
+    };
+    /** Model to use for evaluation. Defaults to model. */
+    evaluationModel?: import('ai').LanguageModel;
+    /** Max tool-loop steps per run. Default: 20. */
+    maxSteps?: number;
+    /**
+     * Max output tokens per LLM turn. Default: 16000. UNSET before 2026-07-12,
+     * which silently inherited the AI SDK Anthropic default of 4096 — a planner
+     * writing a full ComposePlan tool call (or an author writing a large
+     * apply_composition) got truncated at exactly 4096 tokens and the tool call
+     * was LOST (the verify-rerun planner stall: output stopped mid-answer,
+     * tool_calls=[]).
+     */
+    maxOutputTokens?: number;
+    /**
+     * Provider-scoped request options forwarded to every LLM turn (the AI SDK
+     * `providerOptions` passthrough — e.g. `{ anthropic: { thinking: { type:
+     * 'disabled' } } }`). The caller owns the policy; the agent just forwards.
+     * Typed structurally (per-provider JSON object) — the nominal ProviderOptions
+     * export moved across ai@6 minor versions.
+     */
+    providerOptions?: Record<string, Record<string, unknown>>;
+    /** Logger. */
+    logger?: import('./capabilities.js').Logger;
+    /**
+     * Context-management policy for the tool loop. When set, a `prepareStep`
+     * evicts stale tool-call/result content (accumulating tool-result text +
+     * base64 capture images) between steps so a long, tool-heavy run stays under
+     * the model's context window. Off by default (no pruning).
+     */
+    contextManagement?: import('./agent/contextManagement.js').ContextManagementPolicy;
+    /**
+     * Optional tool-set factory (the Subsystem-3 swap seam). When present, the
+     * tool-based run builds its `ToolSet` from this factory instead of the
+     * in-process `buildDirectorTools` — the Director's author LLM then drives the
+     * curated `/v1` MCP tools over the network. Absent (default) → unchanged
+     * in-process path. `packages/authoring` stays free of any `@cueframe/mcp`
+     * dependency: it only knows the structural `ToolSet` (from `ai`).
+     */
+    buildToolSet?: (opts: {
+        allowedTools: string[];
+        onProgress: OnProgressCallback;
+    }) => import('ai').ToolSet;
+    /**
+     * The tool names this agent may use — the config-level default `run()` falls
+     * back to.
+     *
+     * REQUIRED alongside `buildToolSet` (unless every `run()` names its own
+     * `tools`): the injected factory speaks a DIFFERENT vocabulary from the
+     * in-process compose-role tool set (tools/composeRoleTools.ts), and
+     * `buildCuratedToolSet` silently skips names it does not recognise — so
+     * inheriting that key list would quietly build whatever happened to overlap.
+     * Absent + no factory ⇒ every in-process compose-role tool.
+     */
+    allowedTools?: readonly string[];
+    /**
+     * Tools merged into the built ToolSet VERBATIM — after buildToolSet /
+     * buildDirectorTools and after hook wrapping, so provider-defined tools
+     * (e.g. the Anthropic memory tool, whose serialization the provider owns)
+     * pass through untouched. Keys collide last-wins; callers own uniqueness.
+     */
+    extraTools?: import('ai').ToolSet;
+    /**
+     * RESERVE-VERIFY-STEP (P0.2, ledger 2026-07-17): tool names allowed on the
+     * LAST budgeted step. When set, `prepareStep` restricts `activeTools` to this
+     * list on step maxSteps-1, so a MUTATION can never be the loop's unread final
+     * act — the last possible mutation lands at maxSteps-2 and its result (or
+     * error) is read on the reserved step. Motivation: the motion pass's only
+     * mutation errored on step 12/12 and the activity still "succeeded" with zero
+     * motion landed (staging v17b1hsx). Unset (default) → no restriction.
+     */
+    finalStepTools?: readonly string[];
+}
+/** Options for Agent.run(). */
+export interface AgentRunOptions {
+    /** Restrict available tools for this run. */
+    tools?: string[];
+    /** Plain-language quality criteria. Keys are criterion names, values are descriptions. */
+    criteria?: Record<string, string>;
+    /** Weighted rubric with numeric scoring per dimension. */
+    rubric?: EvaluatorRubric;
+    /** Verification criteria — each must be met independently. */
+    verificationCriteria?: string[];
+    /** Max evaluation attempts. Default 1 (no retry). >1 enables quality loop. */
+    maxAttempts?: number;
+    /** Headless mode (generateText, no streaming). */
+    headless?: boolean;
+    /** Abort signal for cancellation. */
+    abortSignal?: AbortSignal;
+}
+/** Result from Agent.run(). */
+export interface AgentRunResult {
+    success: boolean;
+    text?: string;
+    evaluation?: CriteriaResult;
+    /** Rubric evaluation result (when rubric mode is used). */
+    rubricEvaluation?: EvaluationResult;
+    attempts: number;
+    usage: import('ai').LanguageModelUsage;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Derivation constants — pure data, ZERO side effects, ZERO heavy imports.
+ *
+ * This module deliberately imports NOTHING (no apca-w3, no culori). Render-side
+ * consumers (e.g. @cueframe/primitives) need only the ramp poles / floors and
+ * must not drag the contrast MATH (apca-w3 + culori) into their bundle just for
+ * two string constants. `contrastSafe.ts` re-exports these so the package root
+ * stays the single source of truth; leaf consumers import from
+ * `@cueframe/brand-derivation/constants`.
+ */
+/** Version of the derivation RULES. Bump when the math changes; downstream stamps
+ *  this so re-derivation is explicit, never a silent fleet-wide shift.
+ *  v2: Tier-2 derivation expansion — adds surface/card/gridLine/accentMuted fills
+ *  and textOnAccent/textOnSurface paired foregrounds. Re-derives the fleet. */
+export declare const DERIVATION_VERSION = 2;
+/** Forward-only APCA floors. The clamp only ever INCREASES legibility. */
+export declare const FLOORS: {
+    readonly body: 75;
+    readonly nonBody: 60;
+    readonly headline: 45;
+};
+/** The two neutral poles. `onDark` (white) is the safe default text color when the
+ *  background is unknown; `onLight` (near-black) is the safe plate / dark pole. */
+export declare const NEUTRAL_RAMP: {
+    readonly onDark: "#FFFFFF";
+    readonly onLight: "#0A0A0A";
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Derivation constants — pure data, ZERO side effects, ZERO heavy imports.
+ *
+ * This module deliberately imports NOTHING (no apca-w3, no culori). Render-side
+ * consumers (e.g. @cueframe/primitives) need only the ramp poles / floors and
+ * must not drag the contrast MATH (apca-w3 + culori) into their bundle just for
+ * two string constants. `contrastSafe.ts` re-exports these so the package root
+ * stays the single source of truth; leaf consumers import from
+ * `@cueframe/brand-derivation/constants`.
+ */
+/** Version of the derivation RULES. Bump when the math changes; downstream stamps
+ *  this so re-derivation is explicit, never a silent fleet-wide shift.
+ *  v2: Tier-2 derivation expansion — adds surface/card/gridLine/accentMuted fills
+ *  and textOnAccent/textOnSurface paired foregrounds. Re-derives the fleet. */
+export const DERIVATION_VERSION = 2;
+/** Forward-only APCA floors. The clamp only ever INCREASES legibility. */
+export const FLOORS = { body: 75, nonBody: 60, headline: 45 };
+/** The two neutral poles. `onDark` (white) is the safe default text color when the
+ *  background is unknown; `onLight` (near-black) is the safe plate / dark pole. */
+export const NEUTRAL_RAMP = { onDark: "#FFFFFF", onLight: "#0A0A0A" };

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

@@ -0,0 +1,47 @@
+export { DERIVATION_VERSION, FLOORS, NEUTRAL_RAMP } from "./constants.js";
+export interface ContrastSafeColors {
+    background: string;
+    text: string;
+    textMuted: string;
+    accent: string;
+    captionScrim: string;
+    captionFg: string;
+    surface: string;
+    card: string;
+    gridLine: string;
+    accentMuted: string;
+    textOnAccent: string;
+    textOnSurface: string;
+}
+/** 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 declare function relativeLuminance(hex: string): number;
+/** 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 declare function apcaLcFromLuminance(fgY: number, bgY: number): number;
+/** APCA Lc magnitude between two hex colors (fg over bg). Hex-input sibling of
+ *  `apcaLcFromLuminance`; the brand cascade and tests use it directly. */
+export declare function apcaLc(fg: string, bg: string): number;
+/** 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 declare function clampToFloor(fg: string, bg: string, floor: number): string;
+/** 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 declare function deriveContrastSafe(seed: {
+    background: string;
+    text: string;
+    accent: string;
+}): ContrastSafeColors;