@cueframe/kernel 0.0.1

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

@@ -0,0 +1,59 @@
+/**
+ * Agent — the public API for @cueframe/authoring.
+ *
+ * One class, one run() method. Supports:
+ * - Tool-based runs (with capabilities → tools)
+ * - Text-generation runs (no capabilities → pure text)
+ * - Optional criteria-based quality loop (evaluate → refine → retry)
+ */
+import { type PrepareStepFunction, type ToolSet } from 'ai';
+import type { AgentConfig, AgentRunOptions, AgentRunResult } from './types.js';
+/**
+ * RESERVE-VERIFY-STEP (P0.2): wrap a base `prepareStep` so the LAST budgeted
+ * step exposes only `finalStepTools` (∩ the run's tool set). A mutation can
+ * then never be the loop's unread final act — the last possible mutation lands
+ * one step earlier and its result (or error) is READ on the reserved step.
+ * Deterministic enforcement at the loop layer, not a prompt plea. Exported for
+ * tests.
+ */
+export declare function reserveFinalStep(base: PrepareStepFunction<ToolSet>, maxSteps: number, finalStepTools: readonly string[], toolNames: readonly string[]): PrepareStepFunction<ToolSet>;
+/**
+ * B6: an INFRA-class tool failure (dead scratch/session — codes minted by
+ * @cueframe/mcp's InfraToolError) is unfixable by the model: the AI SDK catches
+ * the tool's throw into a `tool-error` step part and would render it back as
+ * text, burning the step budget (prod dogfood: ×49 renders → design-lock).
+ * Detect the sentinel STRUCTURALLY (name+infra flag — deliberately no import
+ * edge to @cueframe/mcp, mirroring its structural guard) so the loop can halt
+ * at that step and the run can rethrow the original error. Exported for tests.
+ */
+export declare function infraErrorFromSteps(steps: ReadonlyArray<unknown>): Error | null;
+export declare class Agent {
+    private config;
+    private capabilities;
+    private messages;
+    private excludedTools;
+    private log;
+    /** Monotonic step index for onStepMetrics; reset per run(). */
+    private stepCounter;
+    constructor(config: AgentConfig);
+    /** Reset conversation history (new session). */
+    reset(): void;
+    /**
+     * Run the agent with a prompt.
+     *
+     * Without criteria/rubric: single generation pass.
+     * With criteria + maxAttempts > 1: generate → evaluate → refine loop (criteria mode).
+     * With rubric + maxAttempts > 1: generate → evaluate → refine loop (rubric mode).
+     */
+    run(prompt: string, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    private runWithCriteria;
+    private runWithRubric;
+    private executeOnce;
+    private executeText;
+    private executeWithTools;
+    private wrapToolsWithHooks;
+    private evaluateResult;
+    private evaluateWithRubric;
+    private buildRefinementPrompt;
+    private buildRubricRefinementPrompt;
+}

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

@@ -0,0 +1,306 @@
+/**
+ * Capability interfaces — what consumers inject into the Director.
+ * Required capabilities must always be provided.
+ * Optional capabilities determine which tools are available.
+ */
+import type { TimelineWord } from '../composition/index.js';
+import type { BrandKit } from '../composition/brand-kit.js';
+import type { CompositionOps, CompositionOpsState } from '../composition/ops/index.js';
+/**
+ * The agent operates on the v2 wire-shape composition. `CompositionOps` is
+ * the v2 op surface (addClip, addOverlay, addAudioClip, addMarker,
+ * cutAndRipple, ripple, etc.) and `CompositionOpsState` carries
+ * `composition: Composition` plus selection state.
+ */
+import type { PoolItemData, PlayerStateData, FontResult, LottieResult, SubjectFaceInfo } from './types.js';
+/** Read/write composition state. Both zustand and headless stores implement this. */
+export interface CompositionStore extends CompositionOps {
+    getState(): CompositionOpsState;
+    /**
+     * Gesture/agent transaction: every mutation inside `fn` commits as ONE
+     * history entry and one store flush (the desktop store's semantics). A
+     * store with no history (headless/bench) implements it as `fn()`.
+     */
+    batch(fn: () => void): void;
+}
+/** Access to transcript word timings. */
+export interface TranscriptProvider {
+    getTimelineWords(): TimelineWord[];
+    getWordTimings(startTime: number, endTime: number): string;
+}
+export interface PlayerControls {
+    seek(time: number): void;
+    play(): void;
+    pause(): void;
+    getPlayerState(): PlayerStateData;
+    setPlaybackRate(rate: number): void;
+}
+/**
+ * An error the AGENT can fix, in this turn, from the message alone — an invalid composition,
+ * an exhausted capture budget. It is NOT an infrastructure failure.
+ *
+ * The distinction is load-bearing, and conflating the two cost a real compose:
+ *  - retrying it is pointless (it will fail identically three times), and
+ *  - it must NOT blind the run — the agent is supposed to read it and fix the composition.
+ *
+ * Everything that is NOT this is infrastructure (render backend down, R2 unreachable, timeout):
+ * retry it, and if it stays broken the author has LOST ITS EYES — see `FrameCapture.isBlind`.
+ */
+export declare class AgentFixableCaptureError extends Error {
+    readonly agentFixable = true;
+    constructor(message: string);
+}
+export interface FrameCapture {
+    /**
+     * Capture stills at the given frames.
+     *
+     * `size` is the pixel box to render into. Absent means the implementation's
+     * default — on the desktop a 480x270 thumbnail, chosen so a routine look costs
+     * ~170 vision tokens rather than ~1840. Pass one only when the question needs
+     * it (typography, legibility, whether a graphic is truncated): a caller that
+     * always asks for full size pays 11x on every look.
+     */
+    captureFrames(frames: number[], size?: {
+        width: number;
+        height: number;
+    }): Promise<string[]>;
+    /**
+     * True once an INFRASTRUCTURE capture failure has exhausted its retries — the author is
+     * BLIND and every subsequent edit is a guess.
+     *
+     * A blind run is a FAILED run, not a quiet degrade. On 2026-07-13 `capture_frames` died on
+     * every call of a live compose, nothing noticed, the author authored an entire composition
+     * without ever seeing a pixel of it, and the candidate still scored 6.14 and was reported as
+     * a normal below-threshold result. Capability loss must be DECLARED, never inferred.
+     *
+     * Optional so existing consumers (desktop) compile unchanged; absent ⇒ never blind.
+     */
+    isBlind?(): boolean;
+    /**
+     * Compute COGS accrued by this capture set so far, in USD.
+     *
+     * In-loop captures are real Modal seconds that the compose run causes but
+     * nobody was counting: they execute under the PLATFORM identity, so
+     * `isBillableCaller` is false and they are neither billed to the customer nor
+     * added to the run's cost. That made the measured base LLM-only and pushed
+     * the gap into the markup, where it could not be audited.
+     *
+     * Optional so existing consumers compile unchanged; absent ⇒ contributes 0.
+     */
+    computeCostUsd?(): number;
+}
+/** Score the CURRENT working composition against the CueFrame rubric. Renders the
+ *  meaningful beats, runs the vision judge, returns a compact per-criterion verdict
+ *  string (composite + per-criterion score/critique, weakest criterion first). The
+ *  author's objective check — distinct from `capture_frames`, which only returns pixels. */
+export interface CompositionVerifier {
+    verify(): Promise<string>;
+}
+/** apply_motion_preset args — the P2 motion pass's structural lane for static
+ *  cards: the agent picks the preset + timing; the shell generation, component
+ *  mint, and clip-source swap are code (the consumer's capability). */
+export interface MotionPresetArgs {
+    clipId: string;
+    preset: string;
+    enterMs?: number;
+    exitMs?: number;
+    staggerMs?: number;
+}
+/** Apply a vetted motion preset to a STATIC card clip: wrap the approved markup
+ *  in a frame-driven shell, mint it as a component, swap the clip source in
+ *  place. Returns a one-line summary the agent reads. Throws on an unknown
+ *  clip/preset or a non-card clip (the tool framework surfaces it). */
+export interface MotionPresetApplier {
+    apply(args: MotionPresetArgs): Promise<string>;
+}
+export interface MediaProvider {
+    importVideoToPool(url: string, name: string): Promise<{
+        poolItemId: string;
+        duration: number;
+    }>;
+    importMedia(url: string, name: string, mediaType: 'video' | 'photo' | 'gif' | 'audio'): Promise<{
+        poolItemId?: string;
+        assetId?: string;
+        assetUrl: string;
+        duration?: number;
+    }>;
+    downloadImage(url: string, filename: string): Promise<string>;
+    extractVideoFrames(poolItemId: string, count?: number): Promise<string[]>;
+    getPoolItemPath(poolItemId: string): string | null;
+}
+export interface TemplateProvider {
+    getTemplateCatalog(): Promise<Array<{
+        id: string;
+        name: string;
+        description: string;
+        category: string;
+    }>>;
+    getTemplateSource(id: string): Promise<string | undefined>;
+    saveUserTemplate(entry: any): Promise<void>;
+    searchTemplates(query: string, topK?: number): Promise<any[]>;
+    ensureTemplatesIndexed(): Promise<void>;
+}
+export interface BrandKitProvider {
+    getActiveBrandKit(): BrandKit | undefined;
+    saveBrandKit(kit: any): string;
+}
+export interface ResourceProvider {
+    searchFonts?(query: string): Promise<FontResult[]>;
+    searchLottie?(query: string, limit?: number): Promise<{
+        items: LottieResult[];
+    }>;
+    searchLibrary?(query: string, limit?: number): Promise<any[]>;
+    analyzeClipSuggestions?(poolItemId: string): Promise<{
+        suggestions: any[];
+    }>;
+}
+export interface Transpiler {
+    transpile(jsxSource: string): Promise<{
+        success: boolean;
+        code?: string;
+        error?: string;
+    }>;
+    /** Allowed global names in the sandbox (e.g., 'Write', 'FadeIn', 'Graph'). Injected, not imported. */
+    sandboxScopeNames: string[];
+}
+export interface ScreenshotProvider {
+    screenshotUrl(opts: {
+        url: string;
+        width?: number;
+        height?: number;
+        maxTiles?: number;
+    }): Promise<string[]>;
+}
+/** AI-powered design review (uses a separate LLM call with visual inspection). */
+export interface DesignReviewProvider {
+    runDesignReview(contextJson: string, task: string, onProgress: (event: any) => void): Promise<string>;
+}
+/** Desktop-only: cross-scope navigation (delegate tool). */
+export interface NavigationProvider {
+    navigate(scope: string, params?: Record<string, string>): void;
+}
+export interface Logger {
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+}
+/** Pool items provider — for tools that need to list/query pool items. */
+export interface PoolProvider {
+    getPoolItems(): PoolItemData[];
+}
+/**
+ * Subject provider — surfaces the source clip's detected-face roster
+ * (`face-0..N` + active-speaker share) into get_context, so the agent authors
+ * `{ kind: "face", faceId }` crop intents against REAL faces rather than
+ * guessing. Backed by the cached detect_subjects roster (source-level).
+ */
+export interface SubjectProvider {
+    getFaces(): SubjectFaceInfo[];
+    /**
+     * The detected face GEOMETRY over time + the output frame — everything needed
+     * to decide whether a `shotScale` punch-in is EARNED (is the face actually
+     * small? is there room around it? can the source afford the crop?). Null when
+     * detection did not run, in which case `set_crop_intents` cannot check a
+     * punch-in and says so rather than waving it through.
+     *
+     * The roster above answers "who is there"; this answers "how are they framed".
+     */
+    getFraming?(): SubjectFramingInfo | null;
+}
+/** Per-second face geometry + the output frame, as the punch-in warrant needs it. */
+export interface SubjectFramingInfo {
+    srcW: number;
+    srcH: number;
+    outW: number;
+    outH: number;
+    /** One entry per source second: `{faceId → {heightFrac, cx, cy}}`, source-normalized. */
+    perSecond: Array<Record<string, {
+        heightFrac: number;
+        cx: number;
+        cy: number;
+    }>>;
+}
+/**
+ * Skill provider — loads on-demand craft skill bodies for the `load_skill` tool
+ * (progressive disclosure). The LOADER is OSS; the CONTENT location is per
+ * platform (cloud: bundled markdown in the worker image; desktop: plugin), so
+ * the body is fetched through this capability rather than read here.
+ */
+export interface SkillProvider {
+    /** Full markdown body for a skill name, or null if the name is unknown. */
+    loadSkill(name: string): Promise<string | null>;
+}
+/**
+ * Compose PLANNER output channel — `submit_compose_plan` delivers the raw plan
+ * args here. Present only in planning-phase runs. The arg is `unknown` on
+ * purpose: this package stays decoupled from the ComposePlan shape; the worker
+ * re-validates with the canonical `@cueframe/composition` ComposePlan.
+ */
+export interface PlanSink {
+    submit(plan: unknown): void;
+}
+export interface DirectorCapabilities {
+    composition: CompositionStore;
+    transcript: TranscriptProvider;
+    player?: PlayerControls;
+    capture?: FrameCapture;
+    verify?: CompositionVerifier;
+    /** P2 motion pass: preset motion shells for static card clips. */
+    motionPreset?: MotionPresetApplier;
+    media?: MediaProvider;
+    templates?: TemplateProvider;
+    brandKit?: BrandKitProvider;
+    resources?: ResourceProvider;
+    transpile?: Transpiler;
+    screenshot?: ScreenshotProvider;
+    designReview?: DesignReviewProvider;
+    navigation?: NavigationProvider;
+    pool?: PoolProvider;
+    subjects?: SubjectProvider;
+    skills?: SkillProvider;
+    /** Compose planning-phase only: receives the submit_compose_plan output. */
+    planSink?: PlanSink;
+    logger?: Logger;
+}
+/**
+ * Alias for DirectorCapabilities — used by the new Agent class.
+ * Same shape for now; Phase 3 may diverge as handlers migrate to typed capabilities.
+ */
+export type AgentCapabilities = DirectorCapabilities;
+/**
+ * The IN-PROCESS tools whose availability depends on an OPTIONAL capability,
+ * mapped to the capability that backs them.
+ *
+ * This is a closed map over `COMPOSE_ROLE_TOOLS` (tools/composeRoleTools.ts) —
+ * the ONLY in-process tool vocabulary left. Until 2026-08-08 the exclusion list
+ * carried ~18 further names (`seek`, `search_lottie`, `search_stock_media`,
+ * `undo`, `move_content`, `load_skill`, …) inherited from the deleted 81-verb
+ * desktop registry. None of them had been buildable since that registry was
+ * removed, so every one was a gate on a tool that could not exist: exclusion
+ * logic that reads as policy and enforces nothing. That is the failure mode the
+ * one-vocabulary merge exists to end, so the map is now DERIVED FROM and gated
+ * against the in-process table (see tools/__tests__/composeRoleTools.test.ts).
+ *
+ * Not every optional capability belongs here. The two deliberate exclusions:
+ *
+ *  - `planSink` backs submit/amend_compose_plan, which stay ALWAYS-AVAILABLE on
+ *    purpose: they are the planner's only output channel, and hiding them
+ *    outside the planning phase would turn "you are not in the planning phase" —
+ *    a message the model can act on — into a silently missing tool.
+ *  - `transpile` is a CONDITIONAL dependency of `update_overlay`: needed only on
+ *    the branch that passes new `sourceCode`/`jsxSource` (composeRoleTools.ts
+ *    ~326), never for the timing/param tuning that is the motion pass's actual
+ *    use. Gating the whole tool on it would delete the motion pass's only
+ *    mutation from every consumer that cannot transpile. That branch refuses
+ *    in-handler ('Transpiler not available') instead.
+ *
+ * The rule the gate enforces: a capability belongs here only when its ABSENCE
+ * makes the tool useless for EVERY call, not for one argument shape.
+ */
+export declare const CAPABILITY_GATED_TOOLS: Readonly<Record<string, keyof DirectorCapabilities>>;
+/**
+ * Tool names to EXCLUDE based on missing capabilities.
+ * The Agent filters these out of the LLM's tool set.
+ */
+export declare function getExcludedTools(capabilities: DirectorCapabilities): Set<string>;

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

@@ -0,0 +1,2 @@
+export type { ComposerScope } from './scopes.js';
+export { editorScope, EDITOR_TOOLS } from './scopes.js';

package/dist/_members/authoring/composer/scopes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Composer-agent scopes.
+ *
+ * EDITOR_TOOLS is the editor agent's subset of the /v1 tool surface
+ * (@cueframe/mcp curation — the SSOT for names/schemas/descriptions). The
+ * agent gets these via `buildCuratedToolSet(executor, { allowedNames:
+ * EDITOR_TOOLS })`, which builds from `[...INTERNAL_LOOP_TOOLS,
+ * ...CURATED_TOOLS]` — so every entry here must be a curated OR internal-loop
+ * tool name. There are NO hand-written tool implementations behind this list.
+ * Adding a capability to the editor chat = adding that name here.
+ *
+ * An internal-loop name (get_context, search_library, analyze_transcript,
+ * wait_job) is deliberately NOT on the public MCP server; being buildable here
+ * is not publication there. See internalLoopTools.ts.
+ *
+ * Deliberately excluded in v1: `compose`/`create_brief`/`resume` (the chat
+ * agent delegating to the cloud Director is a product decision to make
+ * explicitly, not a default), and the destructive project/webhook ops.
+ */
+export interface ComposerScope {
+    name: string;
+    tools: readonly string[];
+    projectId?: string;
+}
+export declare const EDITOR_TOOLS: readonly ["get_context", "get_composition", "apply_composition", "validate_composition", "new_composition", "list_media", "get_media_context", "import_media", "search_library", "analyze_transcript", "list_catalog", "search_fonts", "search_resources", "import_resource", "create_component", "get_component_source", "preview_frame", "score_composition", "create_render", "wait_job", "generate_media"];
+export declare function editorScope(projectId: string): ComposerScope;

package/dist/_members/authoring/context/brand.d.ts

@@ -0,0 +1,37 @@
+import type { BrandKit } from '../../composition/brand-kit.js';
+/**
+ * Extract brand kit data into a context-friendly format.
+ * Returns undefined if no brand kit is active.
+ */
+export declare function buildBrandKitData(activeBrandKit: BrandKit | null | undefined): {
+    customFonts?: string[] | undefined;
+    bgMusic?: string | undefined;
+    jingle?: string | undefined;
+    watermark?: string | undefined;
+    outro?: string | undefined;
+    intro?: string | undefined;
+    colors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+        background: string;
+        text: string;
+    };
+    extraColors: {
+        usage?: string | undefined;
+        hex: string;
+        label: string;
+    }[];
+    headingFont: {
+        fontFamily: string;
+        fontWeight: number;
+    };
+    bodyFont: {
+        fontFamily: string;
+        fontWeight: number;
+    };
+    voiceGuidelines: string;
+    secondaryTagline?: string | undefined;
+    tagline?: string | undefined;
+    name: string;
+} | undefined;

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

@@ -0,0 +1,6 @@
+/**
+ * Re-export brand token resolver from tools.
+ * The canonical implementation lives in tools/brandTokens.ts — no duplication.
+ */
+export { resolveOverlayParams } from '../tools/brandTokens.js';
+export type { TemplateMeta, ResolveContext } from '../tools/brandTokens.js';

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

@@ -0,0 +1,8 @@
+import type { DirectorCapabilities } from '../capabilities.js';
+import type { DirectorContext } from '../types.js';
+export type { DirectorContext };
+export interface BuildContextOptions {
+    /** Maximum total characters for the serialized context. */
+    maxChars?: number;
+}
+export declare function buildDirectorContext(capabilities: DirectorCapabilities, opts?: BuildContextOptions): DirectorContext;

package/dist/_members/authoring/context/timeline.d.ts

@@ -0,0 +1,33 @@
+import type { TimelineClip } from '../../composition/validators/index.js';
+import type { ClipData, OverlayData } from '../types.js';
+/**
+ * Project v2 wire-shape video-track clips into the legacy ClipData shape.
+ * Skips non-media clips (the agent's ClipData has no representation for
+ * component/effect sources).
+ */
+export declare function buildClipData(clips: TimelineClip[]): ClipData[];
+/**
+ * Project v2 overlay-track clips into the legacy context overlay shape.
+ * Each overlay has a primitiveId + params bag on its source.
+ */
+export declare function buildOverlayData(overlays: TimelineClip[]): {
+    id: string;
+    template: string;
+    startTime: number;
+    duration: number;
+    text: string;
+    subtext: string | undefined;
+    position: "left" | "center" | "right" | undefined;
+    accentColor: string | undefined;
+    isCustom: boolean;
+    transition: "fade" | "slide" | "wipe" | "none" | undefined;
+    sequenceGroup: string | undefined;
+}[];
+/** Compute the timeline duration from clips and overlays (v2 wire-shape). */
+export declare function computeTimelineDuration(clips: TimelineClip[], overlays: TimelineClip[]): number;
+/**
+ * Re-export for tests / sub-builders that previously imported `OverlayData`
+ * from `@cueframe/core` — keep the type alias here so they don't have to
+ * walk back to the core module.
+ */
+export type { OverlayData };

package/dist/_members/authoring/context/transcript.d.ts

@@ -0,0 +1,24 @@
+import type { TimelineClip } from '../../composition/validators/index.js';
+import type { TimelineWord } from '../../composition/index.js';
+import type { PoolItemData } from '../types.js';
+/**
+ * Sanitize user-provided strings before embedding in LLM context.
+ */
+export declare function sanitize(s: string, maxLen?: number): string;
+export interface TranscriptResult {
+    transcript: string | undefined;
+    transcriptTruncated: boolean;
+    transcriptHasTimings: boolean;
+}
+/**
+ * Build the transcript section of the agent context.
+ *
+ * Note: in v2 there are no `deletedRanges` — cuts are baked into clip splits.
+ * The `deletedRanges` parameter is kept for back-compat (always empty in v2)
+ * but the strikethrough rendering it triggers is effectively dead code on the
+ * v2 path.
+ */
+export declare function buildTranscript(words: TimelineWord[], overlays: TimelineClip[], deletedRanges: Array<{
+    start: number;
+    end: number;
+}>, poolItems: PoolItemData[]): TranscriptResult;

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

@@ -0,0 +1,5 @@
+/**
+ * Re-export types needed by the context sub-builders.
+ * Avoids each sub-builder importing from scattered locations.
+ */
+export type { TimelineClip } from '../../composition/validators/index.js';

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

@@ -0,0 +1,17 @@
+/**
+ * Decomposer — breaks complex tasks into sequential phases.
+ *
+ * Deterministic pre-filter: simple tasks skip decomposition entirely.
+ * Complex tasks get LLM decomposition into timeline_edit and artifact phases.
+ */
+import type { LanguageModel } from 'ai';
+import type { Phase } from './types.js';
+/**
+ * Deterministic pre-filter: trivial tasks get a single phase, no decomposition needed.
+ * Returns true if the task is complex enough to warrant LLM decomposition.
+ */
+export declare function shouldDecompose(task: string, hasTranscript: boolean): boolean;
+/** Create a single-phase plan for simple tasks. No evaluation, no decomposition. */
+export declare function singlePhase(task: string): Phase[];
+/** LLM decomposes a complex task into multiple phases. */
+export declare function decompose(model: LanguageModel, task: string, context: string): Promise<Phase[]>;

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

@@ -0,0 +1,37 @@
+/**
+ * Criteria-based evaluator for the Agent quality loop.
+ *
+ * Unlike the rubric-based evaluator (evaluator.ts) which uses weighted numeric
+ * scores, this evaluator works with plain-language criteria — each criterion
+ * gets a pass/fail verdict with optional feedback.
+ *
+ * Three evaluation modes (auto-detected):
+ * - Vision: frames provided → multimodal evaluation with image content
+ * - State: compositionState provided → evaluate against composition JSON
+ * - Text: artifact provided → evaluate the text directly
+ */
+import type { LanguageModel } from 'ai';
+import type { CriteriaResult } from './types.js';
+export interface EvaluateOptions {
+    /** Language model for evaluation. */
+    model: LanguageModel;
+    /** The original task / prompt that was being fulfilled. */
+    task: string;
+    /** Plain-language criteria. Keys = names, values = descriptions. */
+    criteria: Record<string, string>;
+    /** Composition state JSON (for state-based evaluation). */
+    compositionState?: string;
+    /** Text artifact (for text-based evaluation). */
+    artifact?: string;
+    /** Base64 frame captures (for vision-based evaluation). */
+    frames?: string[];
+}
+/**
+ * Evaluate work against plain-language criteria.
+ *
+ * Auto-detects evaluation mode:
+ * - frames present → vision evaluation
+ * - compositionState present (no frames) → state evaluation
+ * - artifact present (no state, no frames) → text evaluation
+ */
+export declare function evaluate(options: EvaluateOptions): Promise<CriteriaResult>;

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

@@ -0,0 +1,22 @@
+/**
+ * Evaluator — skeptical QA reviewer for Director output.
+ *
+ * Two modes:
+ * - evaluateArtifact: generateText for text artifacts (blog posts, show notes)
+ * - evaluateTimeline: generateText with vision for timeline edits (composition state + frame captures)
+ *
+ * Anti-leniency: calibrated scoring rubrics prevent the model from being generous.
+ */
+import type { LanguageModel } from 'ai';
+import type { EvaluatorRubric, EvaluationResult } from './types.js';
+export declare const TIMELINE_RUBRIC: EvaluatorRubric;
+export declare const ARTIFACT_RUBRIC: EvaluatorRubric;
+/**
+ * Evaluate a text artifact (blog post, show notes, description).
+ */
+export declare function evaluateArtifact(model: LanguageModel, artifact: string, task: string, rubric: EvaluatorRubric, verificationCriteria: string[]): Promise<EvaluationResult>;
+/**
+ * Evaluate a timeline edit phase.
+ * Uses vision (base64 frame captures) when available.
+ */
+export declare function evaluateTimeline(model: LanguageModel, task: string, rubric: EvaluatorRubric, verificationCriteria: string[], compositionContext: string, capturedFrames?: string[]): Promise<EvaluationResult>;

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

@@ -0,0 +1,25 @@
+export { Agent } from './agent/index.js';
+export type { AgentConfig, AgentRunOptions, AgentRunResult, CriteriaResult, StepMetrics } from './types.js';
+export { evaluate, type EvaluateOptions } from './evaluate.js';
+export { evaluateArtifact, evaluateTimeline, TIMELINE_RUBRIC, ARTIFACT_RUBRIC } from './evaluator.js';
+export type { EvaluatorRubric, RubricDimension, EvaluationResult } from './types.js';
+export type { DirectorCapabilities, AgentCapabilities, CompositionStore, TranscriptProvider, FrameCapture, CompositionVerifier, MotionPresetApplier, MotionPresetArgs, PlayerControls, MediaProvider, TemplateProvider, BrandKitProvider, ResourceProvider, Transpiler, Logger, ScreenshotProvider, DesignReviewProvider, NavigationProvider, PoolProvider, SkillProvider, } from './capabilities.js';
+export { getExcludedTools, AgentFixableCaptureError } from './capabilities.js';
+export { buildDirectorTools, buildPlannerTools, buildToolsFromSchemas, type BuildToolsParams } from './agent/index.js';
+export { buildPrepareStep, type ContextManagementPolicy } from './agent/contextManagement.js';
+export { createAgentMemory, type AgentMemory } from './agent/memoryTool.js';
+export { cachePrepareStep } from './agent/promptCache.js';
+export { renderSkillContent, type AgentScope } from './scope.js';
+export { extractProviderError, ZERO_USAGE } from './agent/index.js';
+export type { DirectorContext, DirectorContext as AgentContext, ProgressEvent, OnProgressCallback, DirectorResult, ToolResult, OverlayData, ClipData, PoolItemData, PlayerStateData, AgentRole, FontResult, LottieResult, StockMediaResult, SoundEffectResult, GifClipResult, ResourceSearchResult, VisualIssue, VisualVerdict, DirectorMode, Phase, PhaseResult, } from './types.js';
+export { shouldDecompose, singlePhase, decompose } from './decomposer.js';
+export { buildDirectorContext, buildDirectorContext as buildAgentContext, type BuildContextOptions } from './context/index.js';
+export { buildModel, buildFastModel, makeLangfuseFetch, type LlmSettings, type ModelConfig, type LangfuseMetadata, } from './models/modelFactory.js';
+export { COMPOSE_PLANNER_TOOLS, COMPOSE_PLANNER_REPAIR_TOOLS, COMPOSE_MOTION_TOOLS, COMPOSE_MOTION_VERIFY_TOOLS, COMPOSE_ROLE_TOOLS, COMPOSE_ROLE_TOOL_NAMES, dispatchComposeRoleTool, type ToolMeta, type ToolHandlerOptions, type ToolHandler, type ToolHandlerResult, } from './tools/index.js';
+export type { ApprovalFn } from './types.js';
+export type { PipelineTraceInterface as PipelineTrace } from './pipelineTrace.js';
+export type { PipelineTraceInterface as RequestTraceInterface } from './pipelineTrace.js';
+export { type PlanStep, formatPlanSteps, buildExecutionTask, buildPlannerUserMessage, PLANNING_INSTRUCTIONS, DESIGN_REVIEWER_PROMPT, DESIGN_REVIEWER_TOOLS, CODE_GEN_FEW_SHOT_EXAMPLES, COMPONENT_CONTRACT, TOOLKIT_REFERENCE, DESIGN_QUALITY_RULES, type ManagedPrompt, initCodeGenPrompts, EVALUATOR_PROMPT, } from './prompts/index.js';
+export { PipelineTrace as RequestTrace } from './pipelineTrace.js';
+export { generateMotionShell, MOTION_PRESETS, resolveMotionPresetCard, MotionPresetError, materializeMotionPresetOpsCore, isMotionPresetOp, hasMotionPresetOp } from './motion/index.js';
+export type { MotionPresetName, MotionShellOptions, MotionPresetErrorCode, ApplyMotionPresetOp, MaterializedMotionShell, MaterializeMotionPresetDeps } from './motion/index.js';