@nebutra/cinema 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { CapabilityError } from '@nebutra/capability-kit';
+
+/**
+ * Consistency-ranked best-frame selection — ViMax-distinct IP, re-expressed.
+ *
+ * Generate N candidate frames, then have an MLLM rank them for character /
+ * spatial / semantic consistency against the target description and pick the
+ * best. The ranking is injected (a model call in production); this module
+ * owns only the orchestration + validation invariants.
+ */
+interface FrameCandidate {
+    readonly id: string;
+    readonly uri: string;
+}
+/** Injected ranker: returns the winning candidate id + a human reason. */
+type RankFrames = (candidates: readonly FrameCandidate[], targetDescription: string) => Promise<{
+    bestId: string;
+    reason: string;
+}>;
+interface BestFrame {
+    readonly best: FrameCandidate;
+    readonly reason: string;
+}
+/**
+ * Select the most consistent frame. Throws if there are no candidates or if
+ * the ranker returns an id that is not among them (a model contract breach
+ * must never silently pick the wrong frame).
+ */
+declare function selectBestFrame(candidates: readonly FrameCandidate[], targetDescription: string, rank: RankFrames): Promise<BestFrame>;
+
+/**
+ * Camera-continuity tree — the ViMax-distinct IP, re-expressed.
+ *
+ * A film is shot by multiple cameras; a parent camera's footage encompasses
+ * its children's, so a child shot can inherit the parent's frames for
+ * temporal/character continuity. The parent inference itself is a model call
+ * (injected — never bound to a provider here). The structural invariants are
+ * enforced locally with the neutral `@nebutra/graph-model` acyclic guard
+ * (governance: reuse, don't re-implement cycle detection).
+ */
+interface Camera {
+    readonly id: string;
+    readonly shotIds: readonly string[];
+}
+interface CameraParent {
+    readonly cameraId: string;
+    /** Null = this camera is a root. */
+    readonly parentCameraId: string | null;
+    /** Which parent shot subsumes this camera (null at root). */
+    readonly parentShotId: string | null;
+    readonly fullyCovers: boolean;
+    readonly missingInfo?: string;
+}
+/** Injected: infer each camera's parent (a model call in production). */
+type InferParents = (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;
+interface CameraTree {
+    readonly rootId: string;
+    readonly cameras: readonly Camera[];
+    /** Parent camera id, or null for the root. */
+    parentOf(cameraId: string): string | null;
+}
+/**
+ * Build the camera tree: infer parents, enforce that the first camera is the
+ * root, and that the parent relation is acyclic (a parent's footage cannot
+ * transitively depend on its descendant).
+ */
+declare function buildCameraTree(cameras: readonly Camera[], infer: InferParents): Promise<CameraTree>;
+/** Root→node camera order — the frame-inheritance chain for continuity. */
+declare function resolveContinuityChain(tree: CameraTree, cameraId: string): string[];
+
+/**
+ * Film-director composition — the ViMax pipeline form, re-expressed as a
+ * thin, fully-injected orchestrator. Every stage (write script, split shots,
+ * build cameras, infer parents, render a shot) is supplied by the caller and
+ * wired to Sailor primitives (`@nebutra/agents`, `@nebutra/reel`,
+ * `@nebutra/cinema` camera tree). This module owns only the sequencing and
+ * the cross-shot continuity guarantee — no model, no I/O.
+ */
+
+interface FilmInput {
+    readonly idea: string;
+}
+interface FilmSteps {
+    readonly writeScript: (idea: string) => Promise<string>;
+    readonly splitShots: (script: string) => Promise<readonly string[]>;
+    readonly buildCameras: (shots: readonly string[]) => Promise<readonly Camera[]>;
+    readonly inferParents: (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;
+    readonly renderShot: (shot: string, index: number) => Promise<{
+        uri: string;
+    }>;
+}
+interface FilmResult {
+    readonly script: string;
+    readonly shots: readonly string[];
+    readonly cameraTree: CameraTree;
+    readonly clips: ReadonlyArray<{
+        shot: string;
+        uri: string;
+    }>;
+}
+/**
+ * Run idea → script → shots → cameras (acyclic continuity tree) → per-shot
+ * render → assembled clip list. Shots render in narrative order so a later
+ * shot can reuse an earlier one's frames for continuity.
+ */
+declare function runFilmPipeline(input: FilmInput, steps: FilmSteps): Promise<FilmResult>;
+
+/** Every cinema failure is a CinemaError (code + actionable suggestion). */
+declare class CinemaError extends CapabilityError {
+    constructor(message: string, init: {
+        code: string;
+        suggestion: string;
+        cause?: unknown;
+    });
+}
+
+/**
+ * Novel → compressed chunks → scene units — ViMax-distinct IP, re-expressed.
+ *
+ * Long-form adaptation: compress chapters (preserving plot/character) then
+ * segment into filmable scenes. Both steps are model calls — injected via a
+ * `CompleteFn` (the same injection shape `@nebutra/reel/storyboard` uses, so
+ * callers wire it to `@nebutra/agents` once). RAG retrieval, when used, is
+ * supplied by `@nebutra/knowledge-rag` through the same injection — not a
+ * hard dependency here.
+ */
+/** Injected model call: prompt in, completion text out. */
+type CompleteFn = (prompt: string) => Promise<string>;
+/** Compress each chunk independently; order is preserved. */
+declare function compressNovel(chunks: readonly string[], complete: CompleteFn): Promise<string[]>;
+/**
+ * Extract ordered scene units from compressed text. The model is asked for a
+ * JSON array of scene strings; parsing tolerates surrounding prose but a
+ * non-array response is a hard error (a silent empty list would drop story).
+ */
+declare function extractScenes(compressed: string, complete: CompleteFn): Promise<string[]>;
+
+export { type BestFrame, type Camera, type CameraParent, type CameraTree, CinemaError, type CompleteFn, type FilmInput, type FilmResult, type FilmSteps, type FrameCandidate, type InferParents, type RankFrames, buildCameraTree, compressNovel, extractScenes, resolveContinuityChain, runFilmPipeline, selectBestFrame };

package/dist/index.js

@@ -0,0 +1,137 @@
+// src/errors.ts
+import { CapabilityError } from "@nebutra/capability-kit";
+var CinemaError = class extends CapabilityError {
+  constructor(message, init) {
+    super(message, init, {
+      name: "CinemaError",
+      emptySuggestionFallback: "No suggestion was provided. This is a bug in @nebutra/cinema \u2014 report it with the failing stage."
+    });
+  }
+};
+
+// src/best-frame.ts
+async function selectBestFrame(candidates, targetDescription, rank) {
+  if (candidates.length === 0) {
+    throw new CinemaError("No candidate frames to select from.", {
+      code: "CINEMA_NO_CANDIDATES",
+      suggestion: "Generate at least one candidate frame before ranking."
+    });
+  }
+  const { bestId, reason } = await rank(candidates, targetDescription);
+  const best = candidates.find((c) => c.id === bestId);
+  if (!best) {
+    throw new CinemaError(`Ranker chose "${bestId}", which is not among the candidates.`, {
+      code: "CINEMA_RANKER_CONTRACT",
+      suggestion: "The injected ranker must return one of the provided candidate ids; constrain its output schema."
+    });
+  }
+  return { best, reason };
+}
+
+// src/camera-tree.ts
+import { wouldCreateCycle } from "@nebutra/graph-model";
+async function buildCameraTree(cameras, infer) {
+  if (cameras.length === 0) {
+    throw new CinemaError("Cannot build a camera tree from zero cameras.", {
+      code: "CINEMA_NO_CAMERAS",
+      suggestion: "Pass at least one camera (the root)."
+    });
+  }
+  const parents = await infer(cameras);
+  const parentById = /* @__PURE__ */ new Map();
+  for (const p of parents) parentById.set(p.cameraId, p.parentCameraId);
+  const firstId = cameras[0]?.id;
+  if (parentById.get(firstId)) {
+    throw new CinemaError(`The first camera "${firstId}" must be the tree root.`, {
+      code: "CINEMA_BAD_ROOT",
+      suggestion: "Ensure the inference returns parentCameraId=null for the first camera."
+    });
+  }
+  const edges = [];
+  for (const p of parents) {
+    if (p.parentCameraId == null) continue;
+    if (wouldCreateCycle(edges, p.parentCameraId, p.cameraId)) {
+      throw new CinemaError(`Camera parent assignment is cyclic at "${p.cameraId}".`, {
+        code: "CINEMA_CYCLIC_TREE",
+        suggestion: "A parent camera must not transitively depend on its descendant; re-infer parents or break the cycle."
+      });
+    }
+    edges.push({ from: p.parentCameraId, to: p.cameraId });
+  }
+  return {
+    rootId: firstId,
+    cameras,
+    parentOf: (id) => parentById.get(id) ?? null
+  };
+}
+function resolveContinuityChain(tree, cameraId) {
+  const chain = [];
+  let cur = cameraId;
+  const seen = /* @__PURE__ */ new Set();
+  while (cur) {
+    if (seen.has(cur)) break;
+    seen.add(cur);
+    chain.push(cur);
+    cur = tree.parentOf(cur);
+  }
+  return chain.reverse();
+}
+
+// src/director.ts
+async function runFilmPipeline(input, steps) {
+  const script = await steps.writeScript(input.idea);
+  const shots = await steps.splitShots(script);
+  const cameras = await steps.buildCameras(shots);
+  const cameraTree = await buildCameraTree(cameras, steps.inferParents);
+  const clips = [];
+  for (let i = 0; i < shots.length; i++) {
+    const shot = shots[i];
+    const { uri } = await steps.renderShot(shot, i);
+    clips.push({ shot, uri });
+  }
+  return { script, shots, cameraTree, clips };
+}
+
+// src/novel-segment.ts
+async function compressNovel(chunks, complete) {
+  return Promise.all(
+    chunks.map(
+      (chunk) => complete(
+        `Compress this passage, preserving plot, character and emotional beats; output prose only:
+
+${chunk}`
+      )
+    )
+  );
+}
+async function extractScenes(compressed, complete) {
+  const raw = await complete(
+    `Split the following into a JSON array of self-contained, filmable scene descriptions in narrative order. Output ONLY the array:
+
+${compressed}`
+  );
+  const match = raw.match(/\[[\s\S]*\]/);
+  if (match) {
+    try {
+      const parsed = JSON.parse(match[0]);
+      if (Array.isArray(parsed) && parsed.every((s) => typeof s === "string")) {
+        return parsed;
+      }
+    } catch {
+    }
+  }
+  throw new CinemaError("Scene extraction did not return a JSON string array.", {
+    code: "CINEMA_SCENE_PARSE",
+    suggestion: "Constrain the model to emit a JSON array of strings (use a schema / response-format), or retry \u2014 output was not parseable."
+  });
+}
+export {
+  CinemaError,
+  buildCameraTree,
+  compressNovel,
+  extractScenes,
+  resolveContinuityChain,
+  runFilmPipeline,
+  selectBestFrame
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/best-frame.ts","../src/camera-tree.ts","../src/director.ts","../src/novel-segment.ts"],"sourcesContent":["import { CapabilityError } from \"@nebutra/capability-kit\";\n\n/** Every cinema failure is a CinemaError (code + actionable suggestion). */\nexport class CinemaError extends CapabilityError {\n  constructor(message: string, init: { code: string; suggestion: string; cause?: unknown }) {\n    super(message, init, {\n      name: \"CinemaError\",\n      emptySuggestionFallback:\n        \"No suggestion was provided. This is a bug in @nebutra/cinema — \" +\n        \"report it with the failing stage.\",\n    });\n  }\n}\n","/**\n * Consistency-ranked best-frame selection — ViMax-distinct IP, re-expressed.\n *\n * Generate N candidate frames, then have an MLLM rank them for character /\n * spatial / semantic consistency against the target description and pick the\n * best. The ranking is injected (a model call in production); this module\n * owns only the orchestration + validation invariants.\n */\n\nimport { CinemaError } from \"./errors\";\n\nexport interface FrameCandidate {\n  readonly id: string;\n  readonly uri: string;\n}\n\n/** Injected ranker: returns the winning candidate id + a human reason. */\nexport type RankFrames = (\n  candidates: readonly FrameCandidate[],\n  targetDescription: string,\n) => Promise<{ bestId: string; reason: string }>;\n\nexport interface BestFrame {\n  readonly best: FrameCandidate;\n  readonly reason: string;\n}\n\n/**\n * Select the most consistent frame. Throws if there are no candidates or if\n * the ranker returns an id that is not among them (a model contract breach\n * must never silently pick the wrong frame).\n */\nexport async function selectBestFrame(\n  candidates: readonly FrameCandidate[],\n  targetDescription: string,\n  rank: RankFrames,\n): Promise<BestFrame> {\n  if (candidates.length === 0) {\n    throw new CinemaError(\"No candidate frames to select from.\", {\n      code: \"CINEMA_NO_CANDIDATES\",\n      suggestion: \"Generate at least one candidate frame before ranking.\",\n    });\n  }\n  const { bestId, reason } = await rank(candidates, targetDescription);\n  const best = candidates.find((c) => c.id === bestId);\n  if (!best) {\n    throw new CinemaError(`Ranker chose \"${bestId}\", which is not among the candidates.`, {\n      code: \"CINEMA_RANKER_CONTRACT\",\n      suggestion:\n        \"The injected ranker must return one of the provided candidate ids; \" +\n        \"constrain its output schema.\",\n    });\n  }\n  return { best, reason };\n}\n","/**\n * Camera-continuity tree — the ViMax-distinct IP, re-expressed.\n *\n * A film is shot by multiple cameras; a parent camera's footage encompasses\n * its children's, so a child shot can inherit the parent's frames for\n * temporal/character continuity. The parent inference itself is a model call\n * (injected — never bound to a provider here). The structural invariants are\n * enforced locally with the neutral `@nebutra/graph-model` acyclic guard\n * (governance: reuse, don't re-implement cycle detection).\n */\n\nimport type { GraphEdge } from \"@nebutra/graph-model\";\nimport { wouldCreateCycle } from \"@nebutra/graph-model\";\nimport { CinemaError } from \"./errors\";\n\nexport interface Camera {\n  readonly id: string;\n  readonly shotIds: readonly string[];\n}\n\nexport interface CameraParent {\n  readonly cameraId: string;\n  /** Null = this camera is a root. */\n  readonly parentCameraId: string | null;\n  /** Which parent shot subsumes this camera (null at root). */\n  readonly parentShotId: string | null;\n  readonly fullyCovers: boolean;\n  readonly missingInfo?: string;\n}\n\n/** Injected: infer each camera's parent (a model call in production). */\nexport type InferParents = (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;\n\nexport interface CameraTree {\n  readonly rootId: string;\n  readonly cameras: readonly Camera[];\n  /** Parent camera id, or null for the root. */\n  parentOf(cameraId: string): string | null;\n}\n\n/**\n * Build the camera tree: infer parents, enforce that the first camera is the\n * root, and that the parent relation is acyclic (a parent's footage cannot\n * transitively depend on its descendant).\n */\nexport async function buildCameraTree(\n  cameras: readonly Camera[],\n  infer: InferParents,\n): Promise<CameraTree> {\n  if (cameras.length === 0) {\n    throw new CinemaError(\"Cannot build a camera tree from zero cameras.\", {\n      code: \"CINEMA_NO_CAMERAS\",\n      suggestion: \"Pass at least one camera (the root).\",\n    });\n  }\n\n  const parents = await infer(cameras);\n  const parentById = new Map<string, string | null>();\n  for (const p of parents) parentById.set(p.cameraId, p.parentCameraId);\n\n  const firstId = cameras[0]?.id;\n  if (parentById.get(firstId as string)) {\n    throw new CinemaError(`The first camera \"${firstId}\" must be the tree root.`, {\n      code: \"CINEMA_BAD_ROOT\",\n      suggestion: \"Ensure the inference returns parentCameraId=null for the first camera.\",\n    });\n  }\n\n  // Acyclic guard via graph-model: add parent→child edges incrementally.\n  const edges: GraphEdge[] = [];\n  for (const p of parents) {\n    if (p.parentCameraId == null) continue;\n    if (wouldCreateCycle(edges, p.parentCameraId, p.cameraId)) {\n      throw new CinemaError(`Camera parent assignment is cyclic at \"${p.cameraId}\".`, {\n        code: \"CINEMA_CYCLIC_TREE\",\n        suggestion:\n          \"A parent camera must not transitively depend on its descendant; \" +\n          \"re-infer parents or break the cycle.\",\n      });\n    }\n    edges.push({ from: p.parentCameraId, to: p.cameraId });\n  }\n\n  return {\n    rootId: firstId as string,\n    cameras,\n    parentOf: (id) => parentById.get(id) ?? null,\n  };\n}\n\n/** Root→node camera order — the frame-inheritance chain for continuity. */\nexport function resolveContinuityChain(tree: CameraTree, cameraId: string): string[] {\n  const chain: string[] = [];\n  let cur: string | null = cameraId;\n  const seen = new Set<string>();\n  while (cur) {\n    if (seen.has(cur)) break; // defensive; tree is acyclic by construction\n    seen.add(cur);\n    chain.push(cur);\n    cur = tree.parentOf(cur);\n  }\n  return chain.reverse();\n}\n","/**\n * Film-director composition — the ViMax pipeline form, re-expressed as a\n * thin, fully-injected orchestrator. Every stage (write script, split shots,\n * build cameras, infer parents, render a shot) is supplied by the caller and\n * wired to Sailor primitives (`@nebutra/agents`, `@nebutra/reel`,\n * `@nebutra/cinema` camera tree). This module owns only the sequencing and\n * the cross-shot continuity guarantee — no model, no I/O.\n */\n\nimport { buildCameraTree, type Camera, type CameraParent, type CameraTree } from \"./camera-tree\";\n\nexport interface FilmInput {\n  readonly idea: string;\n}\n\nexport interface FilmSteps {\n  readonly writeScript: (idea: string) => Promise<string>;\n  readonly splitShots: (script: string) => Promise<readonly string[]>;\n  readonly buildCameras: (shots: readonly string[]) => Promise<readonly Camera[]>;\n  readonly inferParents: (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;\n  readonly renderShot: (shot: string, index: number) => Promise<{ uri: string }>;\n}\n\nexport interface FilmResult {\n  readonly script: string;\n  readonly shots: readonly string[];\n  readonly cameraTree: CameraTree;\n  readonly clips: ReadonlyArray<{ shot: string; uri: string }>;\n}\n\n/**\n * Run idea → script → shots → cameras (acyclic continuity tree) → per-shot\n * render → assembled clip list. Shots render in narrative order so a later\n * shot can reuse an earlier one's frames for continuity.\n */\nexport async function runFilmPipeline(input: FilmInput, steps: FilmSteps): Promise<FilmResult> {\n  const script = await steps.writeScript(input.idea);\n  const shots = await steps.splitShots(script);\n  const cameras = await steps.buildCameras(shots);\n  const cameraTree = await buildCameraTree(cameras, steps.inferParents);\n\n  const clips: Array<{ shot: string; uri: string }> = [];\n  for (let i = 0; i < shots.length; i++) {\n    const shot = shots[i] as string;\n    const { uri } = await steps.renderShot(shot, i);\n    clips.push({ shot, uri });\n  }\n\n  return { script, shots, cameraTree, clips };\n}\n","/**\n * Novel → compressed chunks → scene units — ViMax-distinct IP, re-expressed.\n *\n * Long-form adaptation: compress chapters (preserving plot/character) then\n * segment into filmable scenes. Both steps are model calls — injected via a\n * `CompleteFn` (the same injection shape `@nebutra/reel/storyboard` uses, so\n * callers wire it to `@nebutra/agents` once). RAG retrieval, when used, is\n * supplied by `@nebutra/knowledge-rag` through the same injection — not a\n * hard dependency here.\n */\n\nimport { CinemaError } from \"./errors\";\n\n/** Injected model call: prompt in, completion text out. */\nexport type CompleteFn = (prompt: string) => Promise<string>;\n\n/** Compress each chunk independently; order is preserved. */\nexport async function compressNovel(\n  chunks: readonly string[],\n  complete: CompleteFn,\n): Promise<string[]> {\n  return Promise.all(\n    chunks.map((chunk) =>\n      complete(\n        `Compress this passage, preserving plot, character and emotional ` +\n          `beats; output prose only:\\n\\n${chunk}`,\n      ),\n    ),\n  );\n}\n\n/**\n * Extract ordered scene units from compressed text. The model is asked for a\n * JSON array of scene strings; parsing tolerates surrounding prose but a\n * non-array response is a hard error (a silent empty list would drop story).\n */\nexport async function extractScenes(compressed: string, complete: CompleteFn): Promise<string[]> {\n  const raw = await complete(\n    `Split the following into a JSON array of self-contained, filmable ` +\n      `scene descriptions in narrative order. Output ONLY the array:\\n\\n${compressed}`,\n  );\n  const match = raw.match(/\\[[\\s\\S]*\\]/);\n  if (match) {\n    try {\n      const parsed: unknown = JSON.parse(match[0]);\n      if (Array.isArray(parsed) && parsed.every((s) => typeof s === \"string\")) {\n        return parsed as string[];\n      }\n    } catch {\n      // fall through to the structured error below\n    }\n  }\n  throw new CinemaError(\"Scene extraction did not return a JSON string array.\", {\n    code: \"CINEMA_SCENE_PARSE\",\n    suggestion:\n      \"Constrain the model to emit a JSON array of strings (use a schema / \" +\n      \"response-format), or retry — output was not parseable.\",\n  });\n}\n"],"mappings":";AAAA,SAAS,uBAAuB;AAGzB,IAAM,cAAN,cAA0B,gBAAgB;AAAA,EAC/C,YAAY,SAAiB,MAA6D;AACxF,UAAM,SAAS,MAAM;AAAA,MACnB,MAAM;AAAA,MACN,yBACE;AAAA,IAEJ,CAAC;AAAA,EACH;AACF;;;ACoBA,eAAsB,gBACpB,YACA,mBACA,MACoB;AACpB,MAAI,WAAW,WAAW,GAAG;AAC3B,UAAM,IAAI,YAAY,uCAAuC;AAAA,MAC3D,MAAM;AAAA,MACN,YAAY;AAAA,IACd,CAAC;AAAA,EACH;AACA,QAAM,EAAE,QAAQ,OAAO,IAAI,MAAM,KAAK,YAAY,iBAAiB;AACnE,QAAM,OAAO,WAAW,KAAK,CAAC,MAAM,EAAE,OAAO,MAAM;AACnD,MAAI,CAAC,MAAM;AACT,UAAM,IAAI,YAAY,iBAAiB,MAAM,yCAAyC;AAAA,MACpF,MAAM;AAAA,MACN,YACE;AAAA,IAEJ,CAAC;AAAA,EACH;AACA,SAAO,EAAE,MAAM,OAAO;AACxB;;;AC1CA,SAAS,wBAAwB;AAiCjC,eAAsB,gBACpB,SACA,OACqB;AACrB,MAAI,QAAQ,WAAW,GAAG;AACxB,UAAM,IAAI,YAAY,iDAAiD;AAAA,MACrE,MAAM;AAAA,MACN,YAAY;AAAA,IACd,CAAC;AAAA,EACH;AAEA,QAAM,UAAU,MAAM,MAAM,OAAO;AACnC,QAAM,aAAa,oBAAI,IAA2B;AAClD,aAAW,KAAK,QAAS,YAAW,IAAI,EAAE,UAAU,EAAE,cAAc;AAEpE,QAAM,UAAU,QAAQ,CAAC,GAAG;AAC5B,MAAI,WAAW,IAAI,OAAiB,GAAG;AACrC,UAAM,IAAI,YAAY,qBAAqB,OAAO,4BAA4B;AAAA,MAC5E,MAAM;AAAA,MACN,YAAY;AAAA,IACd,CAAC;AAAA,EACH;AAGA,QAAM,QAAqB,CAAC;AAC5B,aAAW,KAAK,SAAS;AACvB,QAAI,EAAE,kBAAkB,KAAM;AAC9B,QAAI,iBAAiB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,GAAG;AACzD,YAAM,IAAI,YAAY,0CAA0C,EAAE,QAAQ,MAAM;AAAA,QAC9E,MAAM;AAAA,QACN,YACE;AAAA,MAEJ,CAAC;AAAA,IACH;AACA,UAAM,KAAK,EAAE,MAAM,EAAE,gBAAgB,IAAI,EAAE,SAAS,CAAC;AAAA,EACvD;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR;AAAA,IACA,UAAU,CAAC,OAAO,WAAW,IAAI,EAAE,KAAK;AAAA,EAC1C;AACF;AAGO,SAAS,uBAAuB,MAAkB,UAA4B;AACnF,QAAM,QAAkB,CAAC;AACzB,MAAI,MAAqB;AACzB,QAAM,OAAO,oBAAI,IAAY;AAC7B,SAAO,KAAK;AACV,QAAI,KAAK,IAAI,GAAG,EAAG;AACnB,SAAK,IAAI,GAAG;AACZ,UAAM,KAAK,GAAG;AACd,UAAM,KAAK,SAAS,GAAG;AAAA,EACzB;AACA,SAAO,MAAM,QAAQ;AACvB;;;ACnEA,eAAsB,gBAAgB,OAAkB,OAAuC;AAC7F,QAAM,SAAS,MAAM,MAAM,YAAY,MAAM,IAAI;AACjD,QAAM,QAAQ,MAAM,MAAM,WAAW,MAAM;AAC3C,QAAM,UAAU,MAAM,MAAM,aAAa,KAAK;AAC9C,QAAM,aAAa,MAAM,gBAAgB,SAAS,MAAM,YAAY;AAEpE,QAAM,QAA8C,CAAC;AACrD,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,OAAO,MAAM,CAAC;AACpB,UAAM,EAAE,IAAI,IAAI,MAAM,MAAM,WAAW,MAAM,CAAC;AAC9C,UAAM,KAAK,EAAE,MAAM,IAAI,CAAC;AAAA,EAC1B;AAEA,SAAO,EAAE,QAAQ,OAAO,YAAY,MAAM;AAC5C;;;AChCA,eAAsB,cACpB,QACA,UACmB;AACnB,SAAO,QAAQ;AAAA,IACb,OAAO;AAAA,MAAI,CAAC,UACV;AAAA,QACE;AAAA;AAAA,EACkC,KAAK;AAAA,MACzC;AAAA,IACF;AAAA,EACF;AACF;AAOA,eAAsB,cAAc,YAAoB,UAAyC;AAC/F,QAAM,MAAM,MAAM;AAAA,IAChB;AAAA;AAAA,EACsE,UAAU;AAAA,EAClF;AACA,QAAM,QAAQ,IAAI,MAAM,aAAa;AACrC,MAAI,OAAO;AACT,QAAI;AACF,YAAM,SAAkB,KAAK,MAAM,MAAM,CAAC,CAAC;AAC3C,UAAI,MAAM,QAAQ,MAAM,KAAK,OAAO,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ,GAAG;AACvE,eAAO;AAAA,MACT;AAAA,IACF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,QAAM,IAAI,YAAY,wDAAwD;AAAA,IAC5E,MAAM;AAAA,IACN,YACE;AAAA,EAEJ,CAAC;AACH;","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nebutra/cinema",
+  "version": "0.2.0",
+  "description": "Agentic film-production IP: acyclic camera-continuity tree, consistency-ranked best-frame selection, novel→scene/event segmentation, film-director composition. Pure + dependency-injected; sits on reel/agents/graph-model.",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "featureId": "cinema",
+    "category": "ai",
+    "summary": "Multi-agent film-production orchestration over the reel media graph"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@nebutra/capability-kit": "0.2.0",
+    "@nebutra/graph-model": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/cinema#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/cinema"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/cinema.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { selectBestFrame } from "../best-frame";
+import { buildCameraTree, resolveContinuityChain } from "../camera-tree";
+import { runFilmPipeline } from "../director";
+import { CinemaError } from "../errors";
+import { compressNovel, extractScenes } from "../novel-segment";
+
+const cams = [
+  { id: "c0", shotIds: ["s0", "s1"] },
+  { id: "c1", shotIds: ["s2"] },
+  { id: "c2", shotIds: ["s3"] },
+];
+
+describe("buildCameraTree", () => {
+  it("builds an acyclic tree with the first camera as root", async () => {
+    const tree = await buildCameraTree(cams, async () => [
+      { cameraId: "c0", parentCameraId: null, parentShotId: null, fullyCovers: true },
+      { cameraId: "c1", parentCameraId: "c0", parentShotId: "s0", fullyCovers: true },
+      { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: false },
+    ]);
+    expect(tree.rootId).toBe("c0");
+    expect(tree.parentOf("c1")).toBe("c0");
+  });
+
+  it("rejects a cyclic parent assignment (graph-model guard)", async () => {
+    await expect(
+      buildCameraTree(cams, async () => [
+        { cameraId: "c0", parentCameraId: "c2", parentShotId: "s3", fullyCovers: true },
+        { cameraId: "c1", parentCameraId: "c0", parentShotId: "s0", fullyCovers: true },
+        { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
+      ]),
+    ).rejects.toBeInstanceOf(CinemaError);
+  });
+
+  it("rejects when the first camera is not a root", async () => {
+    await expect(
+      buildCameraTree(cams, async () => [
+        { cameraId: "c0", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
+        { cameraId: "c1", parentCameraId: null, parentShotId: null, fullyCovers: true },
+        { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
+      ]),
+    ).rejects.toThrow(/root/i);
+  });
+
+  it("resolveContinuityChain returns the root→node inheritance order", async () => {
+    const tree = await buildCameraTree(cams, async () => [
+      { cameraId: "c0", parentCameraId: null, parentShotId: null, fullyCovers: true },
+      { cameraId: "c1", parentCameraId: "c0", parentShotId: "s0", fullyCovers: true },
+      { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
+    ]);
+    expect(resolveContinuityChain(tree, "c2")).toEqual(["c0", "c1", "c2"]);
+    expect(resolveContinuityChain(tree, "c0")).toEqual(["c0"]);
+  });
+});
+
+describe("selectBestFrame", () => {
+  const cands = [
+    { id: "a", uri: "data:a" },
+    { id: "b", uri: "data:b" },
+  ];
+  it("returns the ranked best and its reason", async () => {
+    const r = await selectBestFrame(cands, "Alice on the left", async () => ({
+      bestId: "b",
+      reason: "best character consistency",
+    }));
+    expect(r.best.id).toBe("b");
+    expect(r.reason).toMatch(/consistency/);
+  });
+  it("throws CinemaError on empty candidates", async () => {
+    await expect(
+      selectBestFrame([], "x", async () => ({ bestId: "", reason: "" })),
+    ).rejects.toBeInstanceOf(CinemaError);
+  });
+  it("throws when the ranker picks an unknown id", async () => {
+    await expect(
+      selectBestFrame(cands, "x", async () => ({ bestId: "zzz", reason: "" })),
+    ).rejects.toThrow(/not among/i);
+  });
+});
+
+describe("novel segmentation", () => {
+  it("compressNovel preserves chunk order", async () => {
+    const out = await compressNovel(["AAA", "BBB"], async (p) => `c:${p.slice(-3)}`);
+    expect(out).toEqual(["c:AAA", "c:BBB"]);
+  });
+  it("extractScenes parses a JSON array, tolerating prose wrapping", async () => {
+    const scenes = await extractScenes("novel", async () => 'noise ["scene 1","scene 2"] tail');
+    expect(scenes).toEqual(["scene 1", "scene 2"]);
+  });
+  it("extractScenes throws CinemaError on unparseable output", async () => {
+    await expect(extractScenes("x", async () => "no array here")).rejects.toBeInstanceOf(
+      CinemaError,
+    );
+  });
+});
+
+describe("runFilmPipeline", () => {
+  it("threads idea→script→shots→cameras→frames in order and returns the assembly", async () => {
+    const calls: string[] = [];
+    const result = await runFilmPipeline(
+      { idea: "a dog learns to fly" },
+      {
+        writeScript: async (idea) => {
+          calls.push("script");
+          return `SCRIPT(${idea})`;
+        },
+        splitShots: async (script) => {
+          calls.push("shots");
+          return [`${script}#0`, `${script}#1`];
+        },
+        buildCameras: async (shots) => {
+          calls.push("cameras");
+          return shots.map((_, i) => ({ id: `c${i}`, shotIds: [`s${i}`] }));
+        },
+        inferParents: async (cameras) =>
+          cameras.map((c, i) => ({
+            cameraId: c.id,
+            parentCameraId: i === 0 ? null : `c${i - 1}`,
+            parentShotId: i === 0 ? null : `s${i - 1}`,
+            fullyCovers: true,
+          })),
+        renderShot: async (shot) => {
+          calls.push(`render:${shot}`);
+          return { uri: `mp4:${shot}` };
+        },
+      },
+    );
+    expect(calls).toEqual([
+      "script",
+      "shots",
+      "cameras",
+      "render:SCRIPT(a dog learns to fly)#0",
+      "render:SCRIPT(a dog learns to fly)#1",
+    ]);
+    expect(result.clips.map((c) => c.uri)).toEqual([
+      "mp4:SCRIPT(a dog learns to fly)#0",
+      "mp4:SCRIPT(a dog learns to fly)#1",
+    ]);
+    expect(result.cameraTree.rootId).toBe("c0");
+  });
+});

package/src/best-frame.ts

@@ -0,0 +1,55 @@
+/**
+ * Consistency-ranked best-frame selection — ViMax-distinct IP, re-expressed.
+ *
+ * Generate N candidate frames, then have an MLLM rank them for character /
+ * spatial / semantic consistency against the target description and pick the
+ * best. The ranking is injected (a model call in production); this module
+ * owns only the orchestration + validation invariants.
+ */
+
+import { CinemaError } from "./errors";
+
+export interface FrameCandidate {
+  readonly id: string;
+  readonly uri: string;
+}
+
+/** Injected ranker: returns the winning candidate id + a human reason. */
+export type RankFrames = (
+  candidates: readonly FrameCandidate[],
+  targetDescription: string,
+) => Promise<{ bestId: string; reason: string }>;
+
+export interface BestFrame {
+  readonly best: FrameCandidate;
+  readonly reason: string;
+}
+
+/**
+ * Select the most consistent frame. Throws if there are no candidates or if
+ * the ranker returns an id that is not among them (a model contract breach
+ * must never silently pick the wrong frame).
+ */
+export async function selectBestFrame(
+  candidates: readonly FrameCandidate[],
+  targetDescription: string,
+  rank: RankFrames,
+): Promise<BestFrame> {
+  if (candidates.length === 0) {
+    throw new CinemaError("No candidate frames to select from.", {
+      code: "CINEMA_NO_CANDIDATES",
+      suggestion: "Generate at least one candidate frame before ranking.",
+    });
+  }
+  const { bestId, reason } = await rank(candidates, targetDescription);
+  const best = candidates.find((c) => c.id === bestId);
+  if (!best) {
+    throw new CinemaError(`Ranker chose "${bestId}", which is not among the candidates.`, {
+      code: "CINEMA_RANKER_CONTRACT",
+      suggestion:
+        "The injected ranker must return one of the provided candidate ids; " +
+        "constrain its output schema.",
+    });
+  }
+  return { best, reason };
+}

package/src/camera-tree.ts

@@ -0,0 +1,103 @@
+/**
+ * Camera-continuity tree — the ViMax-distinct IP, re-expressed.
+ *
+ * A film is shot by multiple cameras; a parent camera's footage encompasses
+ * its children's, so a child shot can inherit the parent's frames for
+ * temporal/character continuity. The parent inference itself is a model call
+ * (injected — never bound to a provider here). The structural invariants are
+ * enforced locally with the neutral `@nebutra/graph-model` acyclic guard
+ * (governance: reuse, don't re-implement cycle detection).
+ */
+
+import type { GraphEdge } from "@nebutra/graph-model";
+import { wouldCreateCycle } from "@nebutra/graph-model";
+import { CinemaError } from "./errors";
+
+export interface Camera {
+  readonly id: string;
+  readonly shotIds: readonly string[];
+}
+
+export interface CameraParent {
+  readonly cameraId: string;
+  /** Null = this camera is a root. */
+  readonly parentCameraId: string | null;
+  /** Which parent shot subsumes this camera (null at root). */
+  readonly parentShotId: string | null;
+  readonly fullyCovers: boolean;
+  readonly missingInfo?: string;
+}
+
+/** Injected: infer each camera's parent (a model call in production). */
+export type InferParents = (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;
+
+export interface CameraTree {
+  readonly rootId: string;
+  readonly cameras: readonly Camera[];
+  /** Parent camera id, or null for the root. */
+  parentOf(cameraId: string): string | null;
+}
+
+/**
+ * Build the camera tree: infer parents, enforce that the first camera is the
+ * root, and that the parent relation is acyclic (a parent's footage cannot
+ * transitively depend on its descendant).
+ */
+export async function buildCameraTree(
+  cameras: readonly Camera[],
+  infer: InferParents,
+): Promise<CameraTree> {
+  if (cameras.length === 0) {
+    throw new CinemaError("Cannot build a camera tree from zero cameras.", {
+      code: "CINEMA_NO_CAMERAS",
+      suggestion: "Pass at least one camera (the root).",
+    });
+  }
+
+  const parents = await infer(cameras);
+  const parentById = new Map<string, string | null>();
+  for (const p of parents) parentById.set(p.cameraId, p.parentCameraId);
+
+  const firstId = cameras[0]?.id;
+  if (parentById.get(firstId as string)) {
+    throw new CinemaError(`The first camera "${firstId}" must be the tree root.`, {
+      code: "CINEMA_BAD_ROOT",
+      suggestion: "Ensure the inference returns parentCameraId=null for the first camera.",
+    });
+  }
+
+  // Acyclic guard via graph-model: add parent→child edges incrementally.
+  const edges: GraphEdge[] = [];
+  for (const p of parents) {
+    if (p.parentCameraId == null) continue;
+    if (wouldCreateCycle(edges, p.parentCameraId, p.cameraId)) {
+      throw new CinemaError(`Camera parent assignment is cyclic at "${p.cameraId}".`, {
+        code: "CINEMA_CYCLIC_TREE",
+        suggestion:
+          "A parent camera must not transitively depend on its descendant; " +
+          "re-infer parents or break the cycle.",
+      });
+    }
+    edges.push({ from: p.parentCameraId, to: p.cameraId });
+  }
+
+  return {
+    rootId: firstId as string,
+    cameras,
+    parentOf: (id) => parentById.get(id) ?? null,
+  };
+}
+
+/** Root→node camera order — the frame-inheritance chain for continuity. */
+export function resolveContinuityChain(tree: CameraTree, cameraId: string): string[] {
+  const chain: string[] = [];
+  let cur: string | null = cameraId;
+  const seen = new Set<string>();
+  while (cur) {
+    if (seen.has(cur)) break; // defensive; tree is acyclic by construction
+    seen.add(cur);
+    chain.push(cur);
+    cur = tree.parentOf(cur);
+  }
+  return chain.reverse();
+}