@cueframe/kernel 0.0.1

package/dist/chunk-52AHXNKM.js

@@ -0,0 +1,435 @@
+import {
+  AgentFixableCaptureError
+} from "./chunk-JOURGVOR.js";
+import {
+  getPrimitiveSubtextParam,
+  getPrimitiveTextParam
+} from "./chunk-5I7VDCAC.js";
+import {
+  selectAllOverlays
+} from "./chunk-NV4I6GJV.js";
+import {
+  ComposePlan
+} from "./chunk-TULRCY6U.js";
+import {
+  OverlayClipSource
+} from "./chunk-ATAF24QG.js";
+
+// ../authoring/src/tools/toolSets.ts
+var COMPOSE_PLANNER_TOOLS = [
+  "get_context",
+  "get_word_timings",
+  "search_library",
+  "capture_frames",
+  "submit_compose_plan"
+];
+var COMPOSE_PLANNER_REPAIR_TOOLS = [
+  "get_context",
+  "get_word_timings",
+  "search_library",
+  "capture_frames",
+  "amend_compose_plan"
+];
+var COMPOSE_MOTION_TOOLS = [
+  "get_context",
+  "get_word_timings",
+  "inspect_overlay",
+  "capture_frames",
+  "update_overlay",
+  "apply_motion_preset",
+  "score_composition"
+];
+var COMPOSE_MOTION_VERIFY_TOOLS = COMPOSE_MOTION_TOOLS.filter(
+  (t) => t !== "update_overlay" && t !== "apply_motion_preset"
+);
+
+// ../authoring/src/tools/composeRoleTools.ts
+import { z } from "zod";
+function overlayViews(capabilities) {
+  return selectAllOverlays(capabilities.composition.getState().composition).flatMap(
+    (o) => o.source.kind === "overlay" ? [{
+      id: o.id,
+      template: o.source.primitiveId,
+      startTime: o.startTime,
+      duration: o.duration,
+      params: { ...o.source.params }
+    }] : []
+  );
+}
+var COMPOSE_ROLE_TOOLS = Object.freeze({
+  get_context: {
+    name: "get_context",
+    description: "Get current project state: transcript with word-level timings, clips on timeline, overlays, brand kit, imported assets, playhead time, timeline duration, and FPS. Always call this first.",
+    schema: z.object({}),
+    metadata: { label: "Get Context" },
+    // Always reads the LIVE composition. The session-cached context seeds the
+    // system prompt only; a tool call must see clips added since the run began.
+    handler: async (_args, capabilities) => {
+      const { buildDirectorContext } = await import("./context-CEAKQ5T7.js");
+      return buildDirectorContext(capabilities);
+    }
+  },
+  get_word_timings: {
+    name: "get_word_timings",
+    description: (
+      // NAMES NO OTHER TOOL, DELIBERATELY. It used to say "call this BEFORE
+      // delete_ranges" — a verb deleted with the hand-written registry, and one
+      // neither role that holds this tool could ever have called anyway (the
+      // planner RECORDS cuts in its plan; the motion pass does not cut at all).
+      // Whoever consumes the range differs per lane, so the description stops at
+      // the timings and lets the lane's own prompt say what to do with them.
+      "Get precise word-level timestamps for a section of the transcript. Call this BEFORE you name a cut range, so the range lands on real word boundaries instead of a rounded guess. On the library page, pass poolItemId to read a specific media item."
+    ),
+    schema: z.object({
+      startTime: z.coerce.number().min(0).describe("Start of time range in seconds"),
+      endTime: z.coerce.number().min(0).describe("End of time range in seconds"),
+      poolItemId: z.string().optional().describe("Pool item ID to read. If omitted, reads the current timeline transcript.")
+    }),
+    metadata: { label: "Get Word Timings" },
+    inputExamples: [{ input: { startTime: 12, endTime: 15 } }],
+    handler: async (args, capabilities) => {
+      const startTime = args.startTime;
+      const endTime = args.endTime;
+      if (endTime <= startTime) {
+        return { error: `Invalid range: endTime (${endTime}) must be greater than startTime (${startTime})` };
+      }
+      return capabilities.transcript.getWordTimings(startTime, endTime);
+    }
+  },
+  inspect_overlay: {
+    name: "inspect_overlay",
+    description: "Retrieve the full details of an existing overlay, including its JSX source code. Use this to inspect fonts, colors, animations, or any implementation detail of a placed overlay.",
+    schema: z.object({
+      id: z.string().describe("The ID of the overlay to inspect")
+    }),
+    metadata: { label: "Inspect Overlay" },
+    strict: true,
+    handler: async (args, capabilities) => {
+      const overlay = overlayViews(capabilities).find((o) => o.id === args.id);
+      if (!overlay) return { error: `Overlay ${args.id} not found` };
+      const lines = [
+        `Overlay ${overlay.id}:`,
+        `  template: ${overlay.template}`,
+        `  startTime: ${overlay.startTime}s`,
+        `  duration: ${overlay.duration}s`,
+        `  text: "${overlay.params.text}"`
+      ];
+      if (overlay.params.subtext) lines.push(`  subtext: "${overlay.params.subtext}"`);
+      if (overlay.params.position) lines.push(`  position: ${overlay.params.position}`);
+      if (overlay.params.accentColor) lines.push(`  accentColor: ${overlay.params.accentColor}`);
+      if (overlay.params.transition) lines.push(`  transition: ${overlay.params.transition}`);
+      if (overlay.params.sequenceGroup) lines.push(`  sequenceGroup: ${overlay.params.sequenceGroup}`);
+      if (overlay.params.jsxSource) {
+        lines.push(`
+Source code:
+${overlay.params.jsxSource}`);
+      } else if (overlay.params.sourceCode) {
+        lines.push(`
+(Compiled code only \u2014 no JSX source available)`);
+      } else {
+        lines.push(`
+(No custom source code \u2014 uses built-in template rendering)`);
+      }
+      return lines.join("\n");
+    }
+  },
+  update_overlay: {
+    name: "update_overlay",
+    description: "Update properties of an existing motion graphic overlay. Only include the fields you want to change. You can provide new sourceCode to re-generate the component.",
+    schema: z.object({
+      id: z.string().min(1).describe("The overlay clip ID (a UUID). Use the exact id inspect_overlay reports \u2014 never fabricate IDs."),
+      startTime: z.coerce.number().min(0).optional().describe("New start time in seconds"),
+      duration: z.coerce.number().min(0.5).max(60).optional().describe("New duration in seconds"),
+      text: z.string().min(1).max(200).optional().describe("New primary text"),
+      subtext: z.string().max(200).optional().describe("New secondary text"),
+      position: z.string().optional().transform((v) => {
+        if (!v) return v;
+        const match = v.match(/(left|center|right)/i);
+        return match ? match[1].toLowerCase() : "center";
+      }),
+      accentColor: z.string().regex(/^#[0-9a-fA-F]{3,8}$/, "Must be a hex color (e.g., #D4AF37)").optional().describe("New accent color as hex"),
+      textColor: z.string().regex(/^#[0-9a-fA-F]{3,8}$/, "Must be a hex color").optional().describe("New text color as hex"),
+      fontFamily: z.string().optional().describe("New font family"),
+      backgroundColor: z.string().regex(/^#[0-9a-fA-F]{3,8}$/, "Must be a hex color").optional().describe("New background color as hex"),
+      sourceCode: z.string().max(1e4).optional().describe("New JSX source code for the overlay"),
+      transition: z.enum(["fade", "slide", "wipe", "none"]).optional().describe("New transition type"),
+      sequenceGroup: z.string().optional().describe("New sequence group ID"),
+      // Depth + primitive fields — editing an overlay can change its primitive,
+      // params bag, and depth (zPlane/parallax/anchor) instead of silently
+      // stripping them. Omitting any of these PRESERVES the overlay's existing
+      // value (the handler merges; it does not replace the whole source).
+      primitiveId: z.string().optional().describe(
+        'Switch the overlay to a different primitive component ID (e.g. "lower-third", "heroText"). Omit to keep the current primitive.'
+      ),
+      params: z.record(z.string(), z.unknown()).optional().describe(
+        "Per-primitive params bag to merge over the overlay\u2019s existing params. Only the keys you set change; existing params are preserved."
+      ),
+      zPlane: OverlayClipSource.shape.zPlane.describe(
+        'Depth plane. "front" renders over the video; "behind-subject" renders UNDER the subject cut-out (the launch-video hero-text look). Omit to keep the overlay\u2019s current plane.'
+      ),
+      parallax: OverlayClipSource.shape.parallax.describe(
+        "Depth parallax for a behind-subject overlay (differential motion vs the camera; 0 locks to the scene). Omit to keep the current value."
+      ),
+      anchor: z.object({
+        x: z.number().min(0).max(1).describe("Horizontal anchor, source-normalized [0,1]."),
+        y: z.number().min(0).max(1).describe("Vertical anchor, source-normalized [0,1].")
+      }).optional().describe(
+        "Durable scene-space anchor for a behind-subject overlay. Omit to keep the system-placed (or previously set) anchor."
+      )
+    }),
+    metadata: { label: "Update Overlay" },
+    inputExamples: [
+      { input: { id: "abc-123", text: "Updated Title", accentColor: "#6366f1" } },
+      { input: { id: "def-456", startTime: 10, duration: 5, sourceCode: "export default function..." } },
+      { input: { id: "ghi-789", zPlane: "behind-subject", anchor: { x: 0.5, y: 0.4 }, parallax: 0.1 } }
+    ],
+    handler: async (args, capabilities) => {
+      const composition = capabilities.composition.getState().composition;
+      const allOverlays = selectAllOverlays(composition);
+      const existingClip = allOverlays.find((o) => o.id === args.id);
+      if (!existingClip || existingClip.source.kind !== "overlay") {
+        const valid = allOverlays.filter((o) => o.source.kind === "overlay").map((o) => `'${o.id}'`);
+        return {
+          error: `Overlay ${args.id} not found. ` + (valid.length > 0 ? `Overlay clip ids in this composition: ${valid.join(", ")}.` : `This composition has no overlay clips.`)
+        };
+      }
+      const existingSource = existingClip.source;
+      const updates = {};
+      if (args.startTime != null) updates.startTime = args.startTime;
+      if (args.duration != null) updates.duration = args.duration;
+      const existingTemplate = existingSource.primitiveId;
+      if (args.text != null && existingTemplate) {
+        if (getPrimitiveTextParam(existingTemplate) === null) {
+          return { error: `Overlay template "${existingTemplate}" does not accept a text payload.` };
+        }
+      }
+      if (args.subtext != null && existingTemplate) {
+        if (getPrimitiveSubtextParam(existingTemplate) === null) {
+          return { error: `Overlay template "${existingTemplate}" does not accept a subtext payload.` };
+        }
+      }
+      const newParams = {
+        ...existingSource.params,
+        ...args.params ?? {}
+      };
+      if (args.text != null) newParams.text = args.text;
+      if (args.subtext != null) newParams.subtext = args.subtext;
+      if (args.accentColor != null) newParams.accentColor = args.accentColor;
+      if (args.textColor != null) newParams.textColor = args.textColor;
+      if (args.backgroundColor != null) newParams.backgroundColor = args.backgroundColor;
+      if (args.fontFamily != null) newParams.fontFamily = args.fontFamily;
+      if (args.position != null) newParams.position = args.position;
+      if (args.transition != null) newParams.transition = args.transition;
+      if (args.sequenceGroup != null) newParams.sequenceGroup = args.sequenceGroup;
+      const jsxSource = args.sourceCode ?? args.jsxSource;
+      let primitiveId = args.primitiveId ?? existingTemplate;
+      if (jsxSource) {
+        const transpileFn = capabilities.transpile?.transpile;
+        if (!transpileFn) return { error: "Transpiler not available" };
+        const result = await transpileFn(jsxSource);
+        if (!result.success) return { error: `JSX transpile failed: ${result.error}` };
+        newParams.sourceCode = result.code;
+        newParams.jsxSource = jsxSource;
+        primitiveId = "custom";
+      }
+      const newSource = { ...existingSource, primitiveId, params: newParams };
+      if (args.zPlane != null) newSource.zPlane = args.zPlane;
+      if (args.parallax != null) newSource.parallax = args.parallax;
+      if (args.anchor != null) {
+        const a = args.anchor;
+        newSource.anchor = { space: "scene", x: a.x, y: a.y };
+      }
+      updates.source = newSource;
+      capabilities.composition.updateOverlay(args.id, updates);
+      return { success: true, message: `Updated overlay ${args.id}` };
+    }
+  },
+  capture_frames: {
+    name: "capture_frames",
+    description: "Capture rendered video frames at specific frame numbers for visual verification. Returns base64 JPEG images. Call this after creating/updating overlays to verify they look correct.",
+    schema: z.object({
+      frames: z.array(z.coerce.number().int().min(0)).min(1).max(4).describe("Frame numbers to capture (max 4)")
+    }),
+    metadata: { label: "Capture Frames", imageResponse: true, dedupExempt: true },
+    handler: async (args, capabilities) => {
+      if (!capabilities.capture) return { error: "Frame capture not available." };
+      const MAX_RETRIES = 2;
+      let lastErr;
+      for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+          if (attempt > 0) {
+            console.info("[compose-role-tools] Retrying capture_frames", {
+              attempt,
+              cause: lastErr instanceof Error ? lastErr.message.slice(0, 300) : String(lastErr).slice(0, 300)
+            });
+            await new Promise((r) => setTimeout(r, 500 * attempt));
+          }
+          return await capabilities.capture.captureFrames(args.frames);
+        } catch (err) {
+          if (err instanceof AgentFixableCaptureError) return { error: err.message };
+          lastErr = err;
+        }
+      }
+      return {
+        error: `capture_frames failed after ${MAX_RETRIES + 1} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}. You are now BLIND \u2014 you cannot see what you are authoring. Do not keep editing on guesswork; this run will be failed.`
+      };
+    }
+  },
+  score_composition: {
+    name: "score_composition",
+    description: "Score the CURRENT composition against the CueFrame quality rubric (editorial, spatial, brand, caption). Renders the meaningful beats, runs the vision judge, and returns per-criterion scores (0\u201310) plus the single weakest criterion to fix next. This is your OBJECTIVE check on whether the cut is good enough \u2014 use it instead of judging from your own eyes. Call it before finalizing, and after a fix to confirm the score moved.",
+    schema: z.object({}),
+    metadata: { label: "Score Composition", dedupExempt: true },
+    toModelOutput: (result) => ({ type: "text", value: result.slice(0, 1200) }),
+    // One call (the judge is expensive); a render/eval failure throws and the
+    // tool framework converts it to a tool error — no fallback string.
+    handler: async (_args, capabilities) => {
+      if (!capabilities.verify) return { error: "Composition scoring not available." };
+      return await capabilities.verify.verify();
+    }
+  },
+  apply_motion_preset: {
+    name: "apply_motion_preset",
+    description: "Apply a vetted motion preset to a STATIC card clip: the approved layout is carried verbatim; only entrance/hold/exit animate. Presets: fade-up (calm default) | slide-in-left | slide-in-right (directional) | scale-pop (punchy stat) | stagger-reveal (enumerations \u2014 needs a [data-stagger] container in the markup). Library overlays already animate \u2014 tune their params/timing with update_overlay instead; custom components already carry their authored motion.",
+    schema: z.object({
+      clipId: z.string().min(1).describe("The card clip to animate (its id in the working composition)."),
+      preset: z.enum(["fade-up", "slide-in-left", "slide-in-right", "scale-pop", "stagger-reveal"]),
+      enterMs: z.number().int().min(80).max(1200).optional().describe("Entrance duration; default 300."),
+      exitMs: z.number().int().min(80).max(1200).optional().describe("Exit duration (completes at clip end); default 300."),
+      staggerMs: z.number().int().min(40).max(400).optional().describe("stagger-reveal only: per-child delay; default 120.")
+    }),
+    metadata: { label: "Apply Motion Preset", dedupExempt: true },
+    // The agent decides (preset + timing); the shell/mint/swap mechanics live in
+    // the consumer's capability. A throw surfaces as a tool error — no silent
+    // degrade.
+    handler: async (args, capabilities) => {
+      if (!capabilities.motionPreset) return { error: "Motion presets not available." };
+      return await capabilities.motionPreset.apply(
+        args
+      );
+    }
+  },
+  search_library: {
+    name: "search_library",
+    description: 'Search across all media in the library. Combines transcript text search (fast, exact match) with semantic scene search (CLIP text-to-image similarity). Use for questions like "find clips about pricing" or "find scenes with mountains".',
+    // `mode` is GONE with the branch it steered. It only ever selected between
+    // the transcript and scene halves of the desktop library-search result;
+    // this lane returns a pre-curated candidate pool, where the arg had no
+    // effect. An accepted-and-ignored argument is a lie the schema tells.
+    schema: z.object({
+      query: z.string().min(1).describe("Search query \u2014 a word/phrase or a visual concept")
+    }),
+    metadata: { label: "Search Library" },
+    inputExamples: [{ input: { query: "pricing discussion" } }],
+    /**
+     * ONE result shape, and it is the compose lane's.
+     *
+     * The only caller is the compose PLANNER, whose `resources.searchLibrary`
+     * (`buildComposeCapabilitiesForClip`) returns a RICH ARRAY: the pre-curated,
+     * relevance-scored enrichment pool for the clip being planned, carrying the
+     * editorial context (kind / provider / query / reason) it needs to pick well.
+     *
+     * The `{transcriptMatches, clipMatches}` branch that used to sit under this
+     * one is DELETED: it was the desktop library-search shape, and desktop
+     * `search_library` is a curated `/v1` tool now (`GET /v1/media/search`),
+     * served by `LocalExecutor`. Nothing reaches this handler with that shape,
+     * so keeping the formatter would have been 27 lines of code claiming a
+     * capability that cannot occur — the same phantom-branch class the registry
+     * deletion exists to end. An unexpected shape now says so, loudly.
+     *
+     * This whole formatter used to be a GLOBAL runtime override the Director
+     * installed at module load (`registerToolHandlers({search_library: …})`),
+     * so one consumer's formatting silently replaced every other consumer's —
+     * and it collided by NAME with the curated `/v1` `search_library`. Binding it
+     * to the handler removes the collision by construction.
+     */
+    handler: async (args, capabilities) => {
+      const searchFn = capabilities.resources?.searchLibrary;
+      if (!searchFn) return { error: "Library search not available. Configure a resource provider." };
+      try {
+        const results = await searchFn(args.query);
+        if (!Array.isArray(results)) {
+          return {
+            error: `Library search returned ${results === null ? "null" : typeof results}, not the candidate array this lane expects. The compose capability contract is an array of {mediaId, kind, provider, query, \u2026} \u2014 see composeCapabilities.ts.`
+          };
+        }
+        const candidates = results;
+        if (candidates.length === 0) return "No enrichment candidates available for this clip.";
+        const lines = [
+          `Enrichment candidate pool (${candidates.length} item${candidates.length === 1 ? "" : "s"}, pre-curated by upstream relevance gate):`
+        ];
+        for (const c of candidates) {
+          const score = typeof c.relevanceScore === "number" ? ` (${c.relevanceScore.toFixed(1)}/10)` : "";
+          const dim = c.width && c.height ? ` ${c.width}x${c.height}` : "";
+          const dur = c.duration ? `${c.duration.toFixed(1)}s` : "?s";
+          const reason = c.relevanceReason ? `
+      \u2192 ${c.relevanceReason}` : "";
+          lines.push(`  [${c.mediaId}] ${c.kind}/${c.provider}: "${c.query}" ${dur}${dim}${score}${reason}`);
+        }
+        return lines.join("\n");
+      } catch (err) {
+        return { error: `Library search failed: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    }
+  },
+  submit_compose_plan: {
+    name: "submit_compose_plan",
+    description: "Submit the FULL compose plan \u2014 framing per beat (frame or trim), pacing cuts, caption style intent, asset requests (resolved from the pool), graphics/hero beats, markers. Call exactly once at the end of planning. The plan is validated and then LOCKED for execution.",
+    schema: ComposePlan,
+    metadata: { label: "Submit Compose Plan" },
+    strict: true,
+    // Deliver the raw plan args to the planning run's sink (the worker
+    // re-validates against the canonical ComposePlan).
+    handler: async (args, capabilities) => {
+      if (!capabilities.planSink) {
+        return { error: "submit_compose_plan is only available in the planning phase." };
+      }
+      capabilities.planSink.submit(args);
+      return "Plan received. Planning phase complete \u2014 stop here.";
+    }
+  },
+  amend_compose_plan: {
+    name: "amend_compose_plan",
+    description: "REPAIR the current plan with targeted ops \u2014 you CANNOT resubmit the whole plan in repair mode. Emit ONLY ops for the sections the errors name; every other section is preserved by the system exactly as-is. Ops: framing.set/cuts.set/captions.set/markers.set (replace that whole section), graphics.add|update|remove and assets.add|update|remove (address ONE element by its exact id \u2014 ids are stable addresses; never invent or renumber them). One logical fix per op.",
+    schema: z.object({
+      ops: z.array(z.object({ type: z.string().min(1) }).passthrough()).min(1).max(20).describe(
+        "Amendment ops. The worker validates each op against the canonical PlanOp union and rejects the whole batch on any invalid op (atomic)."
+      )
+    }),
+    metadata: { label: "Amend Compose Plan" },
+    // Same sink, tagged so the worker distinguishes ops from a full plan.
+    // Canonical op validation + apply + post-condition live worker-side.
+    handler: async (args, capabilities) => {
+      if (!capabilities.planSink) {
+        return { error: "amend_compose_plan is only available in the planning phase." };
+      }
+      capabilities.planSink.submit({ __planOps: args.ops });
+      return "Amendment ops received. Repair round complete \u2014 stop here.";
+    }
+  }
+});
+var COMPOSE_ROLE_TOOL_NAMES = Object.keys(COMPOSE_ROLE_TOOLS);
+async function dispatchComposeRoleTool(toolName, args, capabilities, opts) {
+  const entry = COMPOSE_ROLE_TOOLS[toolName];
+  if (!entry) {
+    return {
+      error: `Unknown tool: ${toolName}. This lane serves ${COMPOSE_ROLE_TOOL_NAMES.join(", ")} \u2014 every other verb moved to the curated /v1 surface.`
+    };
+  }
+  const result = entry.schema.safeParse(args);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    return { error: `Invalid tool arguments: ${issues}` };
+  }
+  return entry.handler(result.data, capabilities, opts);
+}
+
+export {
+  COMPOSE_PLANNER_TOOLS,
+  COMPOSE_PLANNER_REPAIR_TOOLS,
+  COMPOSE_MOTION_TOOLS,
+  COMPOSE_MOTION_VERIFY_TOOLS,
+  COMPOSE_ROLE_TOOLS,
+  COMPOSE_ROLE_TOOL_NAMES,
+  dispatchComposeRoleTool
+};