@cueframe/kernel 0.1.0 → 0.1.2

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

@@ -1,5 +1 @@
-/**
- * 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

@@ -1,18 +1,2 @@
-/**
- * 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

@@ -1,5 +1 @@
-/**
- * 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

@@ -6,9 +6,4 @@ 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/plannerPrompt.d.ts

@@ -1,15 +1,3 @@
-/**
- * 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;
@@ -18,21 +6,8 @@ export interface PlanStep {
     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<{
@@ -40,9 +15,4 @@ export declare function buildPlannerUserMessage(params: {
         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/resourceApi.d.ts

@@ -1,32 +1,13 @@
 import type { FontResult, LottieResult } from '../types.js';
-/**
- * Public-API resource clients — pure HTTP, no gateway auth.
- *
- * Lifted from `apps/studio/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[]>;
+export declare function searchFonts(query: string, perPage?: number, signal?: AbortSignal, apiKey?: string): Promise<FontResult[]>;

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

@@ -1,30 +1,7 @@
-/**
- * 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;
@@ -40,139 +17,42 @@ export type ResourceCandidate = {
     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;
@@ -182,5 +62,4 @@ export interface ResourceCandidateDTO {
     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

@@ -1,18 +1,5 @@
 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;
@@ -25,12 +12,6 @@ export declare function searchStockPhotos(gw: Gateway, query: string, perPage?:
 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;
@@ -40,20 +21,5 @@ export declare function searchKlipy(gw: Gateway, query: string, limit?: number,
 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[]>;

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

@@ -1,31 +1,7 @@
-/**
- * AgentScope — the agent-neutral operating policy for one agent context: which
- * tools it may call, its system-prompt direction, the skills it can load on
- * demand, and how its context window is managed.
- *
- * Cloud-first by design. The primary consumer is the cloud compose author
- * (`the Director worker` builds a `composeAuthorScope` whose `prompt` is the
- * per-run suggestion craft prompt). The desktop `PageScope` simply EXTENDS this
- * type with its route/store/navigation fields — it adapts to the core, the core
- * does not bend to it. The scope is a plain data bundle the caller destructures
- * into the existing `AgentConfig`/`AgentRunOptions` seams (`activeTools` →
- * `opts.tools`, `prompt` → `systemPrompt`, `contextManagement` → `AgentConfig`),
- * so adopting it requires no new Agent API.
- */
 import type { ContextManagementPolicy } from './agent/contextManagement.js';
 export interface AgentScope {
-    /** Tool names this scope may call — passed to the AI SDK as activeTools. */
     readonly activeTools: readonly string[];
-    /**
-     * System-prompt direction for this scope. The cloud author computes this
-     * per-run (the suggestion craft prompt); desktop scopes are static strings.
-     */
     readonly prompt: string;
-    /** Context-window management policy for the tool loop (stale-content eviction). */
     readonly contextManagement?: ContextManagementPolicy;
 }
-/** Bake a craft skill's FULL content into the scope prompt. Structural craft:
- *  the compose loop's `load_skill` was measured at a 0% load rate over a full
- *  week — craft offered as a tool the loop may skip gets skipped (spec
- *  2026-07-13-phased-card-first §2.5). Static per phase → prompt-cache-friendly. */
 export declare function renderSkillContent(name: string, body: string): string;

package/dist/_members/authoring/tools/brandTokens.d.ts

@@ -1,16 +1,3 @@
-/**
- * Brand Token Resolver -- auto-fills overlay params from template defaults and
- * (for brand-driven fields) semantic brand-token refs resolved at render time.
- *
- * Pure function module. No class, no state, no store imports at runtime.
- *
- * Resolution strategy:
- *   1. Explicit LLM args                → stored as literals (always wins)
- *   2. Template paramDefaults            → stored as literals (non-content fields)
- *   3. Brand-driven slots unset by caller → stored as `"$brand:<path>"` refs
- *      resolved by `@cueframe/compose` at render time, so brand-kit edits
- *      propagate to existing overlays without rewriting persisted rows.
- */
 export interface TemplateMeta {
     id: string;
     name: string;
@@ -22,13 +9,4 @@ export interface TemplateMeta {
 export interface ResolveContext {
     templateMeta?: TemplateMeta;
 }
-/**
- * Fill gaps in overlay params using template defaults and brand-token refs.
- * Never mutates the input -- returns a new params object.
- *
- * Note: brand-driven slots store a `"$brand:<path>"` ref when unset. The
- * render-time inflater (`@cueframe/compose/inflatePrimitiveProps`) resolves
- * refs against the active brand kit. This keeps brand-kit edits live for
- * existing overlays instead of baking a snapshot.
- */
 export declare function resolveOverlayParams(params: Record<string, unknown>, ctx: ResolveContext): Record<string, unknown>;

package/dist/_members/authoring/tools/composeRoleTools.d.ts

@@ -1,51 +1,6 @@
-/**
- * The IN-PROCESS compose-role tools — what is left after the 81-tool registry.
- *
- * ── WHY ANYTHING SURVIVED ───────────────────────────────────────────────────
- * The one-vocabulary merge moved every AGENT-FACING surface onto the curated
- * `/v1` manifest (`buildCuratedToolSet`): the hosted MCP server, the Convex
- * editor agent, the desktop Director (over `LocalExecutor`) and the cloud
- * Director's author / assembler / designer roles all speak the same names now,
- * and `TOOL_SCHEMAS` / `TOOL_REGISTRY` / `handlers/` are deleted.
- *
- * TWO Director roles do not, BY DESIGN: `shouldUseMcpSurface`
- * (the Director worker) returns false for
- * `planner` and `motion`. Their verbs are not API calls and cannot be:
- *
- *   submit_compose_plan / amend_compose_plan  deliver a value to the RUNNING
- *       ACTIVITY's `planSink` — a Temporal-local closure. There is no project
- *       to POST to; the plan is validated and locked by the workflow.
- *   capture_frames / score_composition        drive the run's in-loop capture
- *       and verify budgets (one Modal render instance per activity, cost-capped
- *       per run). The /v1 twins (`preview_frame`, `score_composition`) bill per
- *       call against a project the candidate does not have yet.
- *   apply_motion_preset                       mutates the run's headless store
- *       and mints a tenant component; the storyboard is APPROVED at that point
- *       and must not round-trip through a scratch session.
- *   get_context / get_word_timings / inspect_overlay / update_overlay /
- *   search_library                            read and write THAT store and the
- *       run's pre-curated candidate pool — neither exists server-side.
- *
- * So this module is not a surviving fragment of the old vocabulary; it is the
- * in-process compose lane's own tool set, ten names, all reachable only from
- * `COMPOSE_PLANNER_TOOLS`, `COMPOSE_PLANNER_REPAIR_TOOLS` and
- * `COMPOSE_MOTION_TOOLS`. Anything an EDITING agent can ask for lives in the
- * manifest. If a role ever moves onto the MCP surface, its entries leave here.
- *
- * ── NO `registerToolHandlers` ───────────────────────────────────────────────
- * The old registry was mutable at runtime, and three consumers reached in to
- * swap handlers (the pro extension, the Director's compose `search_library`
- * formatter, the Director's `add_overlay` validator). That global mutability is
- * gone with it: handlers are bound here, once. The compose-lane `search_library`
- * formatting is IN the handler below (it was the only real override left), and
- * a consumer that needs different behaviour supplies a different CAPABILITY,
- * which is the seam that was always meant to carry it.
- */
 import { z } from 'zod';
 import type { AgentCapabilities } from '../capabilities.js';
-/** Options bag passed to tool handlers. */
 export type ToolHandlerOptions = Record<string, unknown>;
-/** The shapes handlers actually produce. */
 export type ToolHandlerResult = {
     error: string;
 } | {
@@ -57,56 +12,22 @@ export type ToolHandler = (args: Record<string, unknown>, capabilities: AgentCap
 export interface ToolMeta {
     name: string;
     description: string;
-    /**
-     * Zod object schema for the tool's input parameters.
-     *
-     * Typed to its OUTPUT shape rather than `z.ZodType<any>`: AI SDK v7 infers a
-     * tool's input from this schema, and `any` collapses that inference to
-     * `never` — every `tool()` built from this registry then fails to typecheck.
-     * These are all object schemas, so saying so is a truer declaration, not a
-     * workaround.
-     */
     schema: z.ZodType<Record<string, unknown>>;
     metadata: {
         label: string;
-        /** True for tools that return image data (base64) — routed to vision blocks. */
         imageResponse?: boolean;
-        /**
-         * True for read/verification tools whose whole purpose is to be re-issued
-         * with identical args after an edit. The dedup loop-guard skips these:
-         * re-rendering the same beat to confirm a fix is progress, not a stuck
-         * loop, and cost is bounded by the per-run capture budget instead.
-         */
         dedupExempt?: boolean;
     };
-    /** When true, the AI SDK enforces strict schema matching. */
     strict?: boolean;
-    /** Example inputs for AI SDK tool hints. */
     inputExamples?: Array<{
         input: Record<string, unknown>;
     }>;
-    /** Custom output formatter (truncate, summarize). */
     toModelOutput?: (result: unknown) => {
         type: 'text';
         value: string;
     };
     handler: ToolHandler;
 }
-/**
- * FROZEN. The registry this replaces was a mutable process-global that three
- * consumers reached into at module load (`registerToolHandlers`), so a worker's
- * tool behaviour depended on import order and one consumer's override silently
- * became everyone's. `Object.freeze` makes the successor's shape a compile-time
- * AND runtime fact: a re-introduced mutation throws in strict mode instead of
- * quietly re-creating the failure mode this deletion removed.
- */
 export declare const COMPOSE_ROLE_TOOLS: Readonly<Record<string, ToolMeta>>;
-/** Every name this module serves — the in-process lane's whole vocabulary. */
 export declare const COMPOSE_ROLE_TOOL_NAMES: readonly string[];
-/**
- * Dispatch one in-process tool call. Args are validated against the tool's own
- * schema first — LLM-generated args are routinely malformed, and a type error
- * inside a handler reads as an infrastructure failure rather than a fixable
- * one.
- */
 export declare function dispatchComposeRoleTool(toolName: string, args: Record<string, unknown>, capabilities: AgentCapabilities, opts?: ToolHandlerOptions): Promise<ToolHandlerResult>;

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

@@ -1,4 +1,3 @@
-/** Barrel re-export for the tool system. */
 export { COMPOSE_PLANNER_TOOLS, COMPOSE_PLANNER_REPAIR_TOOLS, COMPOSE_MOTION_TOOLS, COMPOSE_MOTION_VERIFY_TOOLS, } from './toolSets.js';
 export { COMPOSE_ROLE_TOOLS, COMPOSE_ROLE_TOOL_NAMES, dispatchComposeRoleTool, } from './composeRoleTools.js';
 export type { ToolMeta, ToolHandler, ToolHandlerOptions, ToolHandlerResult, } from './composeRoleTools.js';

package/dist/_members/authoring/tools/toolSets.d.ts

@@ -1,54 +1,4 @@
-/**
- * The IN-PROCESS compose ROLE scopes — which tool names the planner and the
- * motion pass may use.
- *
- * Names only; no schemas, no handlers. They are read by the in-process factory
- * over `COMPOSE_ROLE_TOOLS` (composeRoleTools.ts), the ten verbs that
- * structurally cannot be `/v1` calls.
- *
- * ONLY those two roles. The MCP roles' scopes (author / assembler / designer)
- * are NOT here — they are `CURATED_AUTHOR_TOOLS` / `CURATED_DESIGNER_TOOLS` in
- * the director's `agent/composeToolScopes.ts` (moved out of @cueframe/mcp
- * 2026-08-22 — the scopes are director steering). Until
- * 2026-08-08 this file also carried `COMPOSE_AUTHOR_TOOLS` /
- * `COMPOSE_ASSEMBLER_TOOLS` / `COMPOSE_DESIGNER_TOOLS`, whose ~18 entries
- * (`add_clip`, `set_captions`, `add_overlay`, `view_asset`, `verify_graphic`, …)
- * had been deleted verbs since the registry went: `runAuthorOnMcpSurface`'s
- * factory ignores the Agent's `allowedTools` and builds the CURATED set, so the
- * lists scoped nothing while reading exactly like a live scope. They cannot be
- * restated here without first ADDING a `@cueframe/mcp` dependency to this
- * package — which nothing mechanically forbids (dependency-cruiser only flags
- * the UNDECLARED import; a declared edge would resolve and pass), so treat the
- * one-way vocabulary flow as convention held up by where the gates sit. That is
- * precisely why the MCP scopes belong on the MCP side. The director joins the
- * two (agent/composeAuthorScope.ts) and gates the join
- * (agent/__tests__/oneVocabularyPerSurface.test.ts).
- *
- * The per-skill sets that used to live beside these (ANALYSIS_TOOLS,
- * EDITING_TOOLS, GRAPHICS_TOOLS, CAPTIONS_TOOLS, RESOURCES_TOOLS,
- * EXPORT_TOOLS — 81 desktop-only verbs) are DELETED with the registry: the
- * desktop editor agent's scope is now `INTERNAL_EDITOR_TOOLS`
- * (packages/mcp/src/curation.ts) plus the nine client actions.
- */
-/** The compose PLANNER's tool subset — read-only context + VISION + the plan
- *  tool. `capture_frames` lets the planner SEE the raw source (judge shot types:
- *  wide establishing vs tight speaker) before deciding framing/trims — presence
- *  data alone can't distinguish a framable tight shot from an un-framable wide
- *  one. No mutation tools: the planner decides, the assembler builds. */
 export declare const COMPOSE_PLANNER_TOOLS: readonly ["get_context", "get_word_timings", "search_library", "capture_frames", "submit_compose_plan"];
-/** REPAIR-round planner scope (plan-ops, 2026-07-18): same recon set, but
- *  amend_compose_plan REPLACES submit_compose_plan — a repair round cannot
- *  re-emit the full plan, so un-amended sections cannot drift (run-3 root
- *  cause: the bounce path regenerated the whole plan and deleted graphics). */
 export declare const COMPOSE_PLANNER_REPAIR_TOOLS: readonly ["get_context", "get_word_timings", "search_library", "capture_frames", "amend_compose_plan"];
-/** The P2 MOTION pass's tool subset (phased card-first §3): the storyboard is
- *  APPROVED, so motion may tune and shell but never restructure — no add/remove,
- *  no framing, no captions. update_overlay tunes library timing/params;
- *  apply_motion_preset shells static cards; capture/score verify the motion. */
 export declare const COMPOSE_MOTION_TOOLS: readonly ["get_context", "get_word_timings", "inspect_overlay", "capture_frames", "update_overlay", "apply_motion_preset", "score_composition"];
-/** The motion pass's READ/VERIFY subset — COMPOSE_MOTION_TOOLS minus its two
- *  mutations. The Agent's reserve-verify-step (finalStepTools, P0.2) restricts
- *  the LAST budgeted step to these, so a mutation can never be the loop's
- *  unread final act (staging v17b1hsx: the pass's only mutation errored on step
- *  12/12 and nobody read the error — the card shipped static). */
 export declare const COMPOSE_MOTION_VERIFY_TOOLS: ("capture_frames" | "score_composition" | "get_context" | "get_word_timings" | "inspect_overlay")[];

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

@@ -1,40 +1,6 @@
-/**
- * transpileComponent — TSX → sandbox-ready JS for the Bakeless Render Lane.
- *
- * A `live` component renders as a `custom` overlay inside the render-page sandbox
- * (`evaluateInSandbox`, packages/execution/render-entry/src/sandbox-scope.ts), whose wrapper is:
- *
- *   (function(){ "use strict"; const exports = {}; <CODE> return exports.default; })()
- *
- * So the transpiled `<CODE>` must (a) contain NO `import`/`export` statements —
- * they are syntax errors inside a function body, and the sandbox INJECTS React /
- * remotion / animate as endowments — and (b) assign `exports.default = <Component>`.
- *
- * This is the Node/native-esbuild sibling of the desktop `transpileJsx`
- * (apps/studio/src/llm/transpile.ts, esbuild-wasm) and the director's
- * `serverTranspiler` (activities/director.ts). All three share ONE transpile
- * config — the SSOT `ESBUILD_JSX_OPTIONS` + `postProcessForSandbox` in
- * ./transpileHelper — so a live component transpiled here is byte-identical to
- * what those paths produce. Do NOT inline a second config here.
- *
- * Native (not wasm) esbuild `transformSync`: this runs in a Node runtime (a Convex
- * `"use node"` action or the director), never the Convex V8 isolate. Synchronous +
- * throwing so the save path can turn a compile failure into a 422
- * `component_does_not_compile` in one call.
- */
-/** A live component's TSX did not compile. Carries the esbuild message (the
- *  author-fixable detail the save path surfaces as `component_does_not_compile`). */
 export declare class TranspileError extends Error {
     constructor(message: string);
 }
-/**
- * Transpile a component's authored `tsxSource` to sandbox-ready `jsSource`.
- * Throws `TranspileError` (with the esbuild message) on a compile failure.
- *
- * `componentId` is used only to name the virtual source file so esbuild's error
- * messages point at the component (`<componentId>.tsx`), never at an anonymous
- * `<stdin>`.
- */
 export declare function transpileComponent(tsxSource: string, componentId: string): {
     jsSource: string;
 };