@cueframe/kernel 0.0.1

package/dist/_members/authoring/models/modelFactory.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared model factory for the AI SDK.
+ *
+ * Single source of truth for building LanguageModel instances from settings.
+ * Pure function — no store access, no platform imports. Caller passes settings.
+ */
+import type { LanguageModel } from 'ai';
+export interface ModelConfig {
+    model: LanguageModel;
+    providerName: string;
+    modelId: string;
+}
+export interface LlmSettings {
+    provider: 'anthropic' | 'openai' | 'ollama' | 'gateway';
+    apiKey?: string;
+    modelId?: string;
+    /** Cheaper/faster model for decomposer, evaluator, and other non-creative LLM calls. */
+    fastModelId?: string;
+    baseUrl?: string;
+    gatewayUrl?: string;
+    gatewayKey?: string;
+    /**
+     * Per-HTTP-REQUEST timeout (ms). A hung gateway/model call otherwise dangles
+     * until the caller's outermost deadline — on the compose path that is the
+     * Temporal activity timeout (~12 min), which burned an entire plan try on
+     * one stuck request (staging compose v17555bj…, 2026-07-14: planner try 1
+     * hung at 43s in, killed only by the activity timeout). Applied at the fetch
+     * seam so it bounds EVERY request the model makes, whatever loop drives it.
+     */
+    requestTimeoutMs?: number;
+}
+/** Compose a per-request timeout onto a fetch impl. Honors the caller's own
+ *  abort signal; whichever fires first wins. The bound is enforced by a RACE,
+ *  not just the signal — a transport wedged hard enough to ignore its abort
+ *  signal still cannot dangle past the cap (the exact 2026-07-14 failure:
+ *  one stuck request rode the ~12-min Temporal activity timeout). */
+export declare function withRequestTimeout(inner: typeof fetch, ms: number): typeof fetch;
+/**
+ * Per-call metadata attached to every outgoing LLM request through the
+ * `gateway` provider so Langfuse can group traces by user / session /
+ * feature. Only the `gateway` case applies it; other providers ignore
+ * it (Anthropic / OpenAI direct have no LiteLLM callback layer).
+ */
+export interface LangfuseMetadata {
+    /** Trace name — e.g. "director_decompose", "clips_chat_respond". */
+    traceName: string;
+    /** Observation (child span) name — defaults to "llm_call". */
+    generationName?: string;
+    /** Session anchor — workflowId / threadId / mediaItemId etc. */
+    sessionId?: string;
+    /** End-user — auth subject. Sent as both `user` and `trace_user_id`. */
+    userId?: string;
+    /** Feature / sub-component tags — e.g. ["director", "decomposer"]. */
+    tags?: string[];
+    /** Prompt version for eval work — reserved; unused in v1. */
+    version?: string;
+    /**
+     * Stable Langfuse trace id for this run. Defaults to a fresh UUID per
+     * model build, so each operation is its own trace. Pass an explicit id
+     * to group several model builds (e.g. a generator + its evaluator) under
+     * one trace. Without it, LiteLLM groups every request sharing `sessionId`
+     * (often the orgId) into one trace — collapsing unrelated calls and making
+     * per-feature cost attribution impossible.
+     */
+    traceId?: string;
+    /**
+     * Ask LiteLLM not to retain the request/response CONTENT for this call
+     * (`turn_off_message_logging`): the trace still exists with its name, model,
+     * tokens and cost — so spend attribution keeps working — but prompts and
+     * completions are not stored. The desktop stamps this whenever the user has
+     * NOT opted into attributed tracing (consent governs content, not just
+     * identity — spec 2026-08-24-desktop-director-tracing §6.1).
+     */
+    redactContent?: boolean;
+}
+/**
+ * Build a fetch that splices Langfuse metadata into every outgoing
+ * Anthropic request body. LiteLLM's `/anthropic/v1/messages` pass-through
+ * route reads top-level `metadata.{trace_name,session_id,trace_user_id,tags}`
+ * (Anthropic-native shape, LiteLLM extends it) and forwards the unknown
+ * keys to the Langfuse success_callback before stripping them on the
+ * outbound request to Anthropic.
+ *
+ * 2026-04-25: a LiteLLM rolling release on `main-stable` started
+ * ignoring our prior wrapper (`litellm_metadata.trace_name`), dropping
+ * every trace under the default name `litellm-pass_through_endpoint`
+ * with empty session/user/tags. Per LiteLLM Langfuse-integration
+ * discussion, the working form is the top-level `metadata` field. We
+ * write both shapes belt-and-suspenders so older versions that read
+ * `litellm_metadata` still work too.
+ */
+export declare function makeLangfuseFetch(meta: LangfuseMetadata): typeof fetch;
+/**
+ * Build a LanguageModel from explicit settings.
+ * Throws if required credentials are missing.
+ *
+ * Optional `langfuse` parameter: when set on the `gateway` provider,
+ * the returned model injects LiteLLM trace metadata into every
+ * outgoing request via a fetch override. Ignored for non-gateway
+ * providers.
+ */
+export declare function buildModel(settings: LlmSettings, langfuse?: LangfuseMetadata): ModelConfig;
+/**
+ * Build a cheaper/faster model for non-creative LLM calls (decomposer, evaluator).
+ * Falls back to Haiku if no fastModelId is specified.
+ */
+export declare function buildFastModel(settings: LlmSettings, langfuse?: LangfuseMetadata): ModelConfig;

package/dist/_members/authoring/motion/applyMotionPreset.d.ts

@@ -0,0 +1,31 @@
+/** The two author-fixable failure classes, matching the error registry codes. */
+export type MotionPresetErrorCode = "motion_preset_unknown" | "motion_preset_target_invalid";
+/** Fail-loud carrier for the applyMotionPreset guards. `code` is a registered
+ *  ErrorCode the op route re-throws as an `ApiError` (422) or folds into a
+ *  `dry_run` verdict. `opIndex` is stamped by the route (it knows the batch
+ *  position); the pure guard leaves it undefined. */
+export declare class MotionPresetError extends Error {
+    readonly code: MotionPresetErrorCode;
+    opIndex?: number | undefined;
+    constructor(code: MotionPresetErrorCode, message: string, opIndex?: number | undefined);
+}
+/** The minimal wire-composition shape the guard reads (tracks → clip contents). */
+export interface MotionPresetComposition {
+    tracks?: Array<{
+        contents?: unknown[];
+    } | null | undefined>;
+}
+/**
+ * Validate an `applyMotionPreset` op against the current composition and return
+ * the target card's markup (the input to `generateMotionShell`). Throws
+ * `MotionPresetError` on an unknown preset, a missing clip, or a non-card clip.
+ * Pure — no state, no side effects.
+ */
+export declare function resolveMotionPresetCard(composition: MotionPresetComposition, input: {
+    clipId: string;
+    preset: string;
+}): {
+    cardHtml: string;
+    tokens?: Record<string, string>;
+    zPlane?: string;
+};

package/dist/_members/authoring/motion/index.d.ts

@@ -0,0 +1,6 @@
+export { generateMotionShell, MOTION_PRESETS } from "./shell.js";
+export type { MotionPresetName, MotionShellOptions } from "./shell.js";
+export { resolveMotionPresetCard, MotionPresetError } from "./applyMotionPreset.js";
+export type { MotionPresetErrorCode } from "./applyMotionPreset.js";
+export { materializeMotionPresetOpsCore, isMotionPresetOp, hasMotionPresetOp, } from "./materializeMotionPresetOps.js";
+export type { ApplyMotionPresetOp, MaterializedMotionShell, MaterializeMotionPresetDeps, } from "./materializeMotionPresetOps.js";

package/dist/_members/authoring/motion/materializeMotionPresetOps.d.ts

@@ -0,0 +1,38 @@
+import type { MotionPresetName } from './shell.js';
+import { type MotionPresetComposition } from './applyMotionPreset.js';
+export type ApplyMotionPresetOp = {
+    type: 'applyMotionPreset';
+    clipId: string;
+    preset: string;
+    params?: {
+        enterMs?: number;
+        exitMs?: number;
+        staggerMs?: number;
+    };
+};
+export declare const isMotionPresetOp: (op: unknown) => op is ApplyMotionPresetOp;
+export declare const hasMotionPresetOp: (ops: readonly unknown[]) => boolean;
+export interface MaterializedMotionShell {
+    /** Deterministic id (`motion-shell-<clipId>`) — idempotent re-apply target. */
+    componentId: string;
+    clipId: string;
+    preset: MotionPresetName;
+    tsxSource: string;
+    jsSource: string;
+    /** The source card's depth — the sink MUST carry it onto the replacement
+     *  source (whole-source replace drops it otherwise). */
+    zPlane?: string;
+}
+export interface MaterializeMotionPresetDeps {
+    /** Per-lane transpile. Throws on a non-compiling shell; the caller maps the
+     *  failure to its lane's `component_does_not_compile` surface. */
+    transpile: (componentId: string, tsxSource: string) => Promise<{
+        jsSource: string;
+    }>;
+    /** Per-lane materialization target; returns the op that replaces the
+     *  motion-preset op in the batch (same index). */
+    sink: (shell: MaterializedMotionShell) => Promise<unknown> | unknown;
+}
+export declare function materializeMotionPresetOpsCore(composition: MotionPresetComposition, ops: readonly unknown[], opts: {
+    dryRun: boolean;
+}, deps: MaterializeMotionPresetDeps): Promise<unknown[]>;

package/dist/_members/authoring/motion/shell.d.ts

@@ -0,0 +1,30 @@
+export declare const MOTION_PRESETS: readonly ["fade-up", "slide-in-left", "slide-in-right", "scale-pop", "stagger-reveal"];
+export type MotionPresetName = (typeof MOTION_PRESETS)[number];
+export interface MotionShellOptions {
+    preset: MotionPresetName;
+    /** Entrance duration; motion-flow's confident-move band. Default 300. */
+    enterMs?: number;
+    /** Exit duration; the exit COMPLETES at the clip's end. Default 300. */
+    exitMs?: number;
+    /** stagger-reveal only: per-child reveal offset. Default 120. */
+    staggerMs?: number;
+    /**
+     * The card's token layer, baked onto the shell root as `--cf-<k>` CSS vars —
+     * the CardOverlay `cssLayoutVars` semantics the markup was authored against.
+     * Without this the swap card→component silently unpaints every `var(--cf-*)`
+     * the card uses (the render's custom lane applies no token vars). `$brand:`
+     * refs are DROPPED (same miss policy as `cssLayoutVars` with no kit): the
+     * sandbox has no brand kit to resolve against, and the card html's own
+     * `var(--cf-x, fallback)` fallback applies.
+     */
+    tokens?: Record<string, string>;
+}
+/**
+ * The wrapper FILLS its container (`inset: 0`) and never reads the injected
+ * `params.region`: the render floor stamps an element-band region into EVERY
+ * custom overlay's params (OverlayContent → resolveOverlayRegion), and a shell
+ * that honored it collapsed full-frame interlude cards into the top ~80%x35%
+ * caption-clear band. Placement stays on the CLIP's own channels (region →
+ * RegionBox, position → PositionedWrapper) — exactly like the unshelled card.
+ */
+export declare function generateMotionShell(cardHtml: string, opts: MotionShellOptions): string;

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

@@ -0,0 +1,38 @@
+/**
+ * Lightweight pipeline tracing for director requests.
+ *
+ * Records named spans with start/end times. At the end of a request,
+ * logs a summary table showing where wall-clock time was spent.
+ *
+ * Usage:
+ *   const trace = new PipelineTrace();
+ *   trace.start('warmup');
+ *   await warmUp();
+ *   trace.end('warmup');
+ *   ...
+ *   trace.summary(); // logs the table
+ */
+import type { Logger } from './capabilities.js';
+/** Lightweight pipeline trace contract for consumers. */
+export interface PipelineTraceInterface {
+    start(name: string): void;
+    end(name: string): void;
+    recordToolCall(): void;
+    summary(): void;
+}
+export declare class PipelineTrace {
+    private readonly t0;
+    private readonly openSpans;
+    private readonly spans;
+    private toolCallCount;
+    private readonly log;
+    constructor(logger?: Logger);
+    /** Begin a named span. */
+    start(name: string): void;
+    /** End a named span. No-op if the span was never started. */
+    end(name: string): void;
+    /** Record a tool call (increments the counter for the summary). */
+    recordToolCall(): void;
+    /** Log a summary table of all recorded spans. */
+    summary(): void;
+}

package/dist/_members/authoring/prompts/decomposerPrompt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * System prompt for the decomposer agent.
+ * Canonical source: decomposer.md (keep in sync).
+ */
+export declare const DECOMPOSER_PROMPT = "You decompose video editing tasks into sequential phases.\n\nEach phase is one of:\n- timeline_edit: modifies the video composition (add overlays, trim clips, etc.)\n- artifact: produces text output (blog post, show notes, descriptions)\n- scene_composition: creates a new composition from scratch using scenes (documentary, slideshow, social content)\n\nRules:\n- Timeline edit and scene_composition phases run sequentially (each depends on previous state)\n- Artifact phases can reference the timeline but don't modify it\n- Each phase should be independently verifiable\n- Keep phases focused \u2014 one clear objective per phase\n- Include verification criteria for each phase\n\nOUTPUT FORMAT (JSON only, no markdown):\n{\n  \"phases\": [\n    {\n      \"name\": \"short-name\",\n      \"output\": \"timeline_edit\" | \"artifact\" | \"scene_composition\",\n      \"description\": \"what this phase does\",\n      \"verificationCriteria\": [\"criterion 1\", \"criterion 2\"],\n      \"evaluationPasses\": 1 | 3\n    }\n  ]\n}\n\nSet evaluationPasses to 1 for timeline edits and scene compositions, 3 for artifacts (content gets more critique passes).";

package/dist/_members/authoring/prompts/designReviewerPrompt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * System prompt for the design reviewer agent.
+ * Used by both CLI provider (as sub-agent config) and TS agent (as second loop).
+ */
+export declare const DESIGN_REVIEWER_PROMPT = "You are a design quality reviewer for motion graphics in CueFrame.\n\n## Workflow\n\n1. Call `get_context` to understand the current project state and brand kit.\n2. Call `get_composition` to read the graphics themselves \u2014 a card clip carries its\n   `html` and `tokens` verbatim; an overlay or component clip carries its params.\n   For a component's animation code, call `get_component_source` with its componentId.\n3. Call `preview_frame` with EVERY beat you need to see in ONE call \u2014 the rendered\n   pixels, not your reading of the source.\n4. Assess quality against the checklist below. If improvements are needed, send the\n   fixes as ONE `apply_composition` batch \u2014 a `clip.update` op per graphic carrying\n   only the fields that change \u2014 then re-preview the beats you touched to verify.\n\n## Quality Checklist\n\n- **Visual hierarchy**: Title large/bold, subtext smaller/lighter, decorative elements subtle\n- **Animation choreography**: Elements arrive in sequence with staggered timing, not all at once\n- **Spring physics**: Use `spring()` for organic entrances instead of plain linear interpolation\n- **Color usage**: Read ALL colors from params (accentColor, textColor, backgroundColor) \u2014 never hardcode\n- **Entrance + exit**: Choreographed entrance sequence AND fade-out in final 15 frames\n- **Layered composition**: Multiple animated elements (text + accent line + shape + bg glow), not just a single element with opacity\n- **Typography**: Appropriate font from FONTS.*, proper letter-spacing, readable sizing\n- **Atmosphere**: Subtle glows, gradients, or accent color bleeds for depth\n\n## Component Contract\n\n- Signature: `export default function Name({ durationInFrames, params }) { ... }`\n- ONLY `useCurrentFrame()` and `useVideoConfig()` hooks. NO useEffect/useState/useMemo/useCallback/useRef.\n- Inline styles only. No imports, no CSS files, no `document` access. Max 10000 chars.\n- All animation driven by frame number.\n\n## Guidelines\n\n- Be specific in feedback: cite which element, which frame range, what to change.\n- Prefer refinement over complete rewrites \u2014 preserve the designer's intent.\n- A still cannot show motion. Judge timing and choreography from the source; judge\n  layout, contrast and legibility from the frame.\n- After fixing, always re-preview to confirm the improvement visually.\n";
+/**
+ * Tools available to the design reviewer (restricted set).
+ *
+ * THE SERVED NAMES, not a wish list. This array is what `cliProvider.ts` maps
+ * into the Claude sub-agent's `tools` (prefixed `mcp__cueframe__`), so a name
+ * that is not on the desktop surface (`INTERNAL_EDITOR_TOOLS` ∪ the nine client
+ * actions) grants the sub-agent nothing and the prompt above teaches a tool it
+ * cannot call. Three of the four entries here used to be exactly that
+ * (`capture_frames`, `inspect_overlay`, `update_overlay` — deleted with the
+ * hand-written registry), which is why the list and the prompt are now edited
+ * together and gated by the prompt-vocabulary conformance suite.
+ */
+export declare const DESIGN_REVIEWER_TOOLS: string[];

package/dist/_members/authoring/prompts/evaluatorPrompt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * System prompt for the evaluator agent.
+ * Canonical source: evaluator.md (keep in sync).
+ */
+export declare const EVALUATOR_PROMPT = "You are a skeptical QA reviewer. Your job is to find problems, not praise work.\n\nSCORING RULES:\n- If something looks \"fine\" but not \"good\", that's a 5, not a 7.\n- Never say \"overall looks good\" then list issues. Issues mean score deductions.\n- If a verification criterion is not met, the phase FAILS regardless of other scores.\n- Compare against the original task: anything skipped is a deduction.\n- Score each dimension independently on a 0-10 scale.\n\nCALIBRATION:\n\n## Timeline Edit: design_quality\nSCORE 3/10 \u2014 FAIL:\n\"Centered white text on dark background. No animation. No accent elements.\"\n\nSCORE 8/10 \u2014 PASS:\n\"Staggered entrance with spring physics, accent bar + text with letter-spacing animation, exit choreography in final 15 frames. Multiple animated layers.\"\n\nTHE DIFFERENCE: Layered composition with choreographed timing vs. single static element.\n\n## Timeline Edit: craft\nSCORE 3/10 \u2014 FAIL:\n\"Linear fade in, linear fade out. No spring physics. No stagger. Static positioning.\"\n\nSCORE 8/10 \u2014 PASS:\n\"Spring entrance (damping: 12, stiffness: 180), 8-frame stagger between elements, translateY exit with opacity fade, accent bar slides independently.\"\n\nTHE DIFFERENCE: Physics-based motion with choreography vs. basic CSS transitions.\n\n## Artifact: quality\nSCORE 3/10 \u2014 FAIL:\n\"Generic summary that could be about any podcast. No specific quotes or moments referenced.\"\n\nSCORE 8/10 \u2014 PASS:\n\"Opens with a specific compelling quote from the episode. References 3 key moments by timestamp. Matches the host's voice and vocabulary.\"\n\nTHE DIFFERENCE: Specific, contextualized content vs. generic filler.\n\nOUTPUT FORMAT:\nRespond with ONLY a JSON object (no markdown, no explanation):\n{\n  \"scores\": { \"dimension_name\": 0-10, ... },\n  \"critique\": \"specific issues found\",\n  \"evidence\": [\"what you observed\"]\n}";

package/dist/_members/authoring/prompts/graphics.d.ts

@@ -0,0 +1,14 @@
+export declare let CODE_GEN_FEW_SHOT_EXAMPLES: string;
+export declare let COMPONENT_CONTRACT: string;
+export declare let TOOLKIT_REFERENCE: string;
+export declare let DESIGN_QUALITY_RULES: string;
+export interface ManagedPrompt {
+    content: string;
+    version: string;
+}
+/**
+ * Override code-gen constants from a managed prompt.
+ * The prompt content is split by `## ` headers into named sections.
+ * Accepts an optional fetchPrompt function — no-op if not provided or prompt unavailable.
+ */
+export declare function initCodeGenPrompts(fetchPrompt?: (name: string) => Promise<ManagedPrompt | null>): Promise<void>;

package/dist/_members/authoring/prompts/index.d.ts

@@ -0,0 +1,4 @@
+export { type PlanStep, formatPlanSteps, buildExecutionTask, buildPlannerUserMessage, PLANNING_INSTRUCTIONS, } from './plannerPrompt.js';
+export { DESIGN_REVIEWER_PROMPT, DESIGN_REVIEWER_TOOLS, } from './designReviewerPrompt.js';
+export { CODE_GEN_FEW_SHOT_EXAMPLES, COMPONENT_CONTRACT, TOOLKIT_REFERENCE, DESIGN_QUALITY_RULES, type ManagedPrompt, initCodeGenPrompts, } from './graphics.js';
+export { EVALUATOR_PROMPT } from './evaluatorPrompt.js';

package/dist/_members/authoring/prompts/plannerPrompt.d.ts

@@ -0,0 +1,48 @@
+/**
+ * plannerPrompt.ts — Phase 1 of the two-phase director.
+ *
+ * The planning turn runs in the same CLI session as execution (shared system
+ * prompt, shared context). Planning instructions are embedded in the user
+ * message, and the execution phase resumes the session via --resume.
+ *
+ * The model calls submit_plan tool to return structured output. Text-based
+ * DIRECT:/PLAN: parsing was removed — structured tool output is now the
+ * only path.
+ */
+/** Step shape produced by the submit_plan tool. */
+export interface PlanStep {
+    time: number;
+    name: string;
+    overlayType: string;
+    duration: number;
+    text: string;
+    visual: string;
+}
+/**
+ * Convert structured plan steps to the text format consumed by buildExecutionTask().
+ */
+export declare function formatPlanSteps(steps: unknown): string;
+/**
+ * Wrap a plan into the execution prompt for Phase 2.
+ * The executor receives a locked-in plan and should not re-plan.
+ */
+export declare function buildExecutionTask(plan: string, originalTask: string): string;
+/**
+ * Build the user message for the planning turn.
+ *
+ * Context JSON is sent separately via --append-system-prompt (not duplicated here).
+ * Planning instructions are inlined so the director system prompt stays as-is.
+ */
+export declare function buildPlannerUserMessage(params: {
+    task: string;
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+}): string;
+/**
+ * Planning instructions — used by the CLI path as inline user-message content.
+ * Extension providers may also wrap these into a standalone system prompt.
+ * Both paths provide the submit_plan tool for structured output.
+ */
+export declare const PLANNING_INSTRUCTIONS = "Analyze the project state and transcript to decide if this request needs a multi-overlay plan or can be executed directly.\n\n## Workflow\n\n1. Call get_context to understand the current project state and transcript \u2014 it\n   returns the lead transcript's word timings, so most plans need nothing else.\n2. Call get_media_context for a SPECIFIC media item when you need its own word\n   timings or its detected faces; analyze_transcript when you want the editorial\n   read (summary / chapters / highlights) rather than the words.\n3. Call submit_plan with your decision.\n\n## Decision Criteria\n\nCall submit_plan with type \"direct\" if:\n- The request is a single action (remove, delete, change, update one thing)\n- No transcript analysis is needed\n\nCall submit_plan with type \"plan\" if:\n- Multiple overlays or scenes are needed\n- The request involves analyzing the transcript for key moments\n\n## Overlay Types (for plan steps)\n- full-screen: Bold text/graphic covering most of the frame (3-5s)\n- lower-third: Subtitle-style bar in the lower third (3-6s)\n- intro: Title card with ripple insert (3-5s)\n- outro: End card with ripple insert (3-5s)\n- scene: Full-screen designed moment (5-30s) \u2014 a card or component that owns the\n  frame: a stat, a comparison, a sequence, a diagram built from catalog pieces\n\n## Plan Guidelines (when type is \"plan\")\n- Pick 3-7 key moments, spaced at least 10s apart\n- Text MUST come from the actual transcript \u2014 do not invent quotes\n- Prefer moments where the speaker introduces a concept or transitions topics\n- At most 1 intro and 1 outro";

package/dist/_members/authoring/providers/index.d.ts

@@ -0,0 +1 @@
+export * from './resourceApi.js';

package/dist/_members/authoring/providers/resourceApi.d.ts

@@ -0,0 +1,32 @@
+import type { FontResult, LottieResult } from '../types.js';
+/**
+ * Public-API resource clients — pure HTTP, no gateway auth.
+ *
+ * Lifted from `cueframe/src/llm/resourceApi.ts` so both the desktop Tauri
+ * app and the server-side Temporal director worker can call the same
+ * Google Fonts + LottieFiles clients. Gateway-routed search (Pexels,
+ * Pixabay, Freesound, Klipy) lives in `../resources.ts` — that module
+ * needs a `Gateway` arg; these functions don't.
+ */
+export interface LottieSearchResult {
+    items: LottieResult[];
+    hasMore: boolean;
+    endCursor: string | null;
+}
+export declare function searchLottie(query: string, limit?: number, signal?: AbortSignal, after?: string | null): Promise<LottieSearchResult>;
+/** Test seam: the font list is cached module-level for 30 min. */
+export declare function __resetFontCache(): void;
+/**
+ * Thrown when Google rejects our CREDENTIALS rather than the request — a
+ * permanent misconfiguration, not a blip. Callers must NOT degrade this to an
+ * empty result set: `search_fonts` returned `0 fonts` for the product's entire
+ * lifetime precisely because an unkeyed 403 was indistinguishable from
+ * "nothing matched".
+ */
+export declare class FontProviderUnconfiguredError extends Error {
+    readonly code: "provider_unconfigured";
+    constructor(message: string);
+}
+export declare function searchFonts(query: string, perPage?: number, signal?: AbortSignal, 
+/** Google Fonts Developer API key. Absent ⇒ the call is unkeyed and Google 403s. */
+apiKey?: string): Promise<FontResult[]>;

package/dist/_members/authoring/resource-routing.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Shared SSOT for stock-resource routing, rate-limit caps, query
+ * normalisation, opaque candidate handles, and the API-facing candidate DTO.
+ *
+ * ONE source of truth consumed by BOTH:
+ *   - the Temporal b-roll enrichment worker
+ *     (`the processing worker`)
+ *   - the Convex MCP resource-search lane
+ *     (`the API layer`)
+ *
+ * Import via the subpath `@cueframe/authoring/resource-routing` — like
+ * `@cueframe/authoring/resources`, this pulls in ONLY `./resources` +
+ * `./types` (fetch/AbortSignal only, no `ai`/node transports), so it
+ * bundles into the Convex V8 isolate. Never import the authoring ROOT
+ * from Convex.
+ */
+import { type Gateway, type SfxDurationFilter } from './resources.js';
+export type { Gateway, SfxDurationFilter } from './resources.js';
+export type ResourceKind = 'video' | 'photo' | 'sfx' | 'gif';
+export type ResourceProviderId = 'pexels' | 'pixabay' | 'freesound' | 'klipy';
+/**
+ * Normalised candidate shape all provider searches map down to. Matches the
+ * Convex `candidateShape` in `data-models/convex-schemas/src/enrichment.ts`
+ * and the worker's `Candidate`. width/height/duration/licenseCode are
+ * optional because not every kind populates every field (sfx has no
+ * width/height, photo has no duration, only freesound carries licenseCode).
+ */
+export type ResourceCandidate = {
+    provider: ResourceProviderId;
+    externalId: string;
+    query: string;
+    thumbnail: string;
+    previewUrl: string;
+    downloadUrl: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+    photographer: string;
+    photographerUrl?: string;
+    assetUrl?: string;
+    licenseCode?: string;
+};
+/**
+ * Provider → (cap, windowMs). Per-provider so different providers can carry
+ * different free-tier ceilings without cross-bleed. The bucket key
+ * (`orgId : provider : floor(now/windowMs)`) is derived inside the Convex
+ * `checkOrgRateLimit` mutation — callers forward `provider`, `cap`, `windowMs`.
+ *
+ * Caps sit below documented provider limits to leave headroom for burst
+ * clients sharing the same gateway key (LiteLLM pools across all CueFrame
+ * orgs). NOTE the windows differ: pixabay is per-MINUTE, the rest per-HOUR.
+ */
+export declare const PROVIDER_CAPS: Record<ResourceProviderId, {
+    cap: number;
+    windowMs: number;
+}>;
+/**
+ * The `mediaItems.kind` a stock resource lands as, mapped from the enrichment
+ * kind. photo→image, sfx→audio; video/gif keep their name. The R2 key path
+ * uses the enrichment kind; the mediaItem row uses this.
+ */
+export type MediaItemKind = 'video' | 'image' | 'audio' | 'gif';
+export declare const ENRICHMENT_KIND_TO_MEDIA_KIND: Record<ResourceKind, MediaItemKind>;
+/** Providers that serve a given kind, primary first. */
+export declare function providersForKind(kind: ResourceKind): ResourceProviderId[];
+/** Whether an explicit provider pin is valid for the requested kind. */
+export declare function isProviderValidForKind(kind: ResourceKind, provider: ResourceProviderId): boolean;
+/** Primary provider for a kind (tried first). */
+export declare function primaryProviderForKind(kind: ResourceKind): ResourceProviderId;
+/** Fallback provider for a kind (tried on primary failure/rate-limit), or null. */
+export declare function fallbackProviderForKind(kind: ResourceKind): ResourceProviderId | null;
+/**
+ * Canonical query normaliser. Lower-cases, strips punctuation to spaces,
+ * collapses whitespace. Shared by the cache key, the rate-limit path, and
+ * the candidateId codec so a search and a later import agree on the key.
+ *
+ * INVARIANT the candidateId codec relies on: the output contains only
+ * letters, numbers, and single spaces — never the `|` field separator.
+ */
+export declare function normalizeQuery(q: string): string;
+/**
+ * Call the authoring search fn for a (kind, provider) pair. Return type
+ * widens each specific candidate to `ResourceCandidate`. Throws if the
+ * provider does not serve the kind (guard the explicit pin BEFORE calling).
+ *
+ * `durationSec` is an optional native duration bound honoured ONLY by the sfx
+ * (Freesound) lane — it maps to Freesound's server-side Solr filter. Other
+ * kinds ignore it.
+ */
+export declare function searchByProvider(gw: Gateway, kind: ResourceKind, provider: ResourceProviderId, query: string, perPage: number, signal?: AbortSignal, durationSec?: SfxDurationFilter): Promise<ResourceCandidate[]>;
+/**
+ * Pick the file extension + MIME for a stock candidate. Derive from the
+ * downloadUrl when it carries a known extension (Klipy sometimes returns
+ * `.gif` from its clips endpoint; a provider could ship `.webm`/`.png`),
+ * else fall back to the kind default. Throws when the resolved extension has
+ * no MIME mapping (fail loud rather than mirror an undecodable payload).
+ */
+export declare function resolveFormat(kind: ResourceKind, downloadUrl: string): {
+    ext: string;
+    mime: string;
+};
+/**
+ * R2 key for a stock asset. Cross-org shared BYTES (dedup): the same provider
+ * asset lives at one key regardless of which org imported it. Layout mirrors
+ * the clip-enrichment mirror: `stock/{provider}/{kind}/{externalId}.{ext}`.
+ */
+export declare function resolveStockKey(provider: ResourceProviderId, kind: ResourceKind, externalId: string, ext: string): string;
+export type DecodedCandidateId = {
+    provider: ResourceProviderId;
+    kind: ResourceKind;
+    /** Already normalised (== normalizeQuery of the original search query). */
+    query: string;
+    externalId: string;
+};
+/**
+ * Mint an opaque, deterministic handle for a candidate. NOT backed by a
+ * table — it encodes exactly what `import_resource` needs to re-resolve the
+ * candidate from `resourceQueryCache`: (provider, kind, normalizeQuery(query),
+ * externalId). Deterministic so the same search result always yields the same
+ * id, and self-normalising so search and import agree on the cache key.
+ */
+export declare function encodeCandidateId(input: {
+    provider: ResourceProviderId;
+    kind: ResourceKind;
+    query: string;
+    externalId: string;
+}): string;
+/**
+ * Decode a candidateId. Throws on malformed input (bad base64, missing
+ * fields, unknown provider/kind). Only `externalId` may itself contain the
+ * separator, so it is reconstructed from the tail; provider/kind/normQuery
+ * are separator-free by construction.
+ */
+export declare function decodeCandidateId(id: string): DecodedCandidateId;
+/**
+ * The candidate shape returned by `search_resources` over MCP. Renames the
+ * internal `photographer*`/`licenseCode` to the public `author*`/`license`,
+ * surfaces `assetUrl` (TOS-mandated provider backlink) and mints the opaque
+ * `candidateId`.
+ *
+ * IT USED TO DROP `downloadUrl`, on the reasoning that it was "internal only —
+ * `import_resource` re-resolves it from cache". True for the lane that reasoning
+ * was written for: an agent importing over MCP never needs the URL, because the
+ * server fetches the bytes. It is NOT true for a client that cannot use that
+ * lane — `import_resource` lands assets in a CLOUD project, and the desktop
+ * drawer inserts into a LOCAL timeline. Those callers fell back to `previewUrl`
+ * and imported preview-grade bytes that looked correct in a grid and shipped
+ * soft at export.
+ *
+ * So it is surfaced now. `import_resource` remains the server-side path and is
+ * unchanged; this only stops the omission from silently degrading everyone else.
+ *
+ * `license` is per-asset only for freesound (CC0); for pexels/pixabay/klipy it
+ * is provider-implied and therefore absent.
+ */
+export interface ResourceCandidateDTO {
+    candidateId: string;
+    provider: ResourceProviderId;
+    kind: ResourceKind;
+    thumbnail: string;
+    previewUrl: string;
+    /**
+     * FULL-RESOLUTION source, when the provider gives one.
+     *
+     * Omitted until 2026-08-17, which made every non-`import_resource` consumer
+     * silently import PREVIEW-grade bytes — the SD file for a Pexels video,
+     * `preview-hq-mp3` for a Freesound sound, `src.large` for a photo. The desktop
+     * drawer inserts into a LOCAL timeline and so cannot use `import_resource`
+     * (that lane lands assets in a CLOUD project), which meant footage looked
+     * right in the grid and shipped soft at export.
+     *
+     * This is NOT a new exposure class: `previewUrl` and `thumbnail` are already
+     * direct provider CDN links on this same DTO. It is the same link at the
+     * resolution the caller actually wants.
+     */
+    downloadUrl?: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+    author: string;
+    authorUrl?: string;
+    assetUrl?: string;
+    license?: string;
+}
+/** Map an internal candidate to the public search DTO. */
+export declare function toResourceCandidateDTO(c: ResourceCandidate, kind: ResourceKind): ResourceCandidateDTO;

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

@@ -0,0 +1,59 @@
+import type { StockMediaResult, StockVideoCandidate, StockPhotoCandidate, StockSoundCandidate, StockGifCandidate, SoundEffectResult, GifClipResult } from './types.js';
+export type { StockMediaResult, StockVideoCandidate, StockPhotoCandidate, StockSoundCandidate, StockGifCandidate, SoundEffectResult, GifClipResult, } from './types.js';
+/**
+ * Resource search functions that route through the LiteLLM gateway proxy.
+ *
+ * Single canonical implementation, consumed by:
+ *   - `@cueframe/pro/resourceApi` (desktop / web UI's stock resource panel)
+ *   - `@cueframe/processing-worker` (b-roll enrichment Temporal activity)
+ *
+ * The gateway pattern mirrors `models/modelFactory.ts`: a typed
+ * `{ url, key }` is threaded in; both fields are required. LiteLLM's
+ * pass-through endpoints (`/pexels/*`, `/pixabay/*`, `/freesound/*`,
+ * `/klipy/*`) reject requests without `Authorization: Bearer <master_key>`
+ * with a 401.
+ */
+export interface Gateway {
+    url: string;
+    key: string;
+}
+export declare function searchStockVideos(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal): Promise<StockVideoCandidate[]>;
+export declare function popularStockVideos(gw: Gateway, perPage?: number, signal?: AbortSignal): Promise<StockVideoCandidate[]>;
+export declare function searchPixabayVideos(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal): Promise<StockVideoCandidate[]>;
+export declare function popularPixabayVideos(gw: Gateway, perPage?: number, signal?: AbortSignal): Promise<StockVideoCandidate[]>;
+export declare function searchStockPhotos(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal): Promise<StockMediaResult[]>;
+export declare function popularStockPhotos(gw: Gateway, perPage?: number, signal?: AbortSignal): Promise<StockMediaResult[]>;
+export declare function searchPixabayPhotos(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal): Promise<StockMediaResult[]>;
+export declare function popularPixabayPhotos(gw: Gateway, perPage?: number, signal?: AbortSignal): Promise<StockMediaResult[]>;
+/**
+ * Optional duration bound for a Freesound search. Maps to Freesound's NATIVE
+ * Solr range filter (`filter=duration:[<min> TO <max>]`) — the index does the
+ * bounding server-side; NOTHING is dropped client-side. Both ends are optional:
+ * `min` defaults to `0`, `max` to `*` (unbounded).
+ */
+export interface SfxDurationFilter {
+    min?: number;
+    max?: number;
+}
+export declare function searchSoundEffects(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal, durationSec?: SfxDurationFilter): Promise<SoundEffectResult[]>;
+export declare function searchKlipy(gw: Gateway, query: string, limit?: number, signal?: AbortSignal, type?: 'gifs' | 'clips'): Promise<GifClipResult[]>;
+export declare function trendingKlipy(gw: Gateway, limit?: number, signal?: AbortSignal, type?: 'gifs' | 'clips'): Promise<GifClipResult[]>;
+export declare function searchStockPhotoCandidates(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal): Promise<StockPhotoCandidate[]>;
+export declare function searchPixabayPhotoCandidates(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal): Promise<StockPhotoCandidate[]>;
+/**
+ * Candidate-shape variant of `searchSoundEffects` used by the Temporal
+ * enrichment activity. Filters to CC0 at the mapper — the v1 launch
+ * scope drops attribution.json sidecars for CC-BY assets, so anything
+ * non-CC0 would leak into shipped renders without attribution — the
+ * enrichment design flagged CC-BY attribution plumbing as a launch
+ * blocker, and it has not been built.
+ */
+export declare function searchSoundEffectsCandidates(gw: Gateway, query: string, perPage?: number, signal?: AbortSignal, durationSec?: SfxDurationFilter): Promise<StockSoundCandidate[]>;
+/**
+ * Candidate-shape variant of `searchKlipy`. Returns
+ * `StockGifCandidate[]` with provider/externalId/duration fields so the
+ * enrichment activity can persist + dedupe by `(provider, externalId)`.
+ * The `clips` type returns MP4-backed reaction clips (preferred over
+ * raw GIFs for overlay rendering); pass `'gifs'` for the GIF endpoint.
+ */
+export declare function searchKlipyCandidates(gw: Gateway, query: string, limit?: number, signal?: AbortSignal, type?: 'gifs' | 'clips'): Promise<StockGifCandidate[]>;