@nodaro/shared 2.8.0 → 2.11.0

package/src/surround.ts

@@ -1,48 +1,25 @@
 /**
- * Surround continuation — shared single source of truth.
+ * Surround continuation — the shared WIRE CONTRACT.
  *
  * The Location 360° "look-around" builds each ring view (45°, 90°, …) as an
- * image-to-image continuation of the previous view. The platform forces
- * geometric continuity by handing the model a half-done frame: one edge holds
- * the previous view's carried pixels, the rest is flat gray, and the model is
- * asked to paint the gray region.
+ * image-to-image continuation of the previous one.
  *
- * This module owns the bits that are pure and reused across the route Zod
- * schema, the SDK input type, and the worker: the direction enum, the carried
- * fraction defaults, and the fill prompt. The geometry math + sharp compositing
- * + color harmonization live backend-side (they need `sharp`).
+ * This module owns only what the route Zod schema, the SDK input type, and the
+ * worker all need to agree on: the direction enum and the carried-fraction
+ * defaults. The fill prompt lives in `@nodaro/prompts` (never published) and
+ * the compositing/harmonization engine is private.
  */
 
 /**
- * The carry/paint axis for a continuation.
- *
- * PAN (horizontal — half-carry continuation):
- * - `right` — turning right: the new frame's LEFT edge continues the previous
- *   view's RIGHT edge, so the carried band sits on the LEFT, painted on the RIGHT.
- * - `left` — turning left: the new frame's RIGHT edge continues the previous
- *   view's LEFT edge, so the carried band sits on the RIGHT, painted on the LEFT.
- *   (Mirror of `right`. Lets studio chain BOTH ways from a keyframe, capping
- *   chain depth so quality doesn't compound down a long one-way chain.)
- *
- * TILT (vertical — thin-strip, subject-driven re-render):
- * - `up` — tilting straight up: render the open SKY overhead. A thin strip of
- *   the establishing shot's TOP edge is carried into the new frame's BOTTOM for
- *   a soft horizon transition; the rest is painted as sky (NOT a mirrored
- *   landscape).
- * - `down` — tilting straight down: render the GROUND below. A thin strip of the
- *   BOTTOM edge is carried into the new frame's TOP.
+ * The camera move a continuation represents: `right` / `left` pan the view
+ * horizontally, `up` / `down` tilt it vertically.
  */
 export const SURROUND_DIRECTIONS = ["right", "left", "up", "down"] as const
 export type SurroundDirection = (typeof SURROUND_DIRECTIONS)[number]
 
-/** Half the frame is carried for a horizontal pan (matches studio's composite). */
+/** Default carried fraction for a horizontal pan. */
 export const DEFAULT_CARRIED_FRACTION = 0.5
-/**
- * Tilts carry only a thin horizon strip. Carrying half of a horizontal frame is
- * exactly what makes the model echo/mirror the landscape vertically instead of
- * rendering what's actually overhead/underfoot — so tilts keep the carry small
- * and let the tilt prompt drive the subject.
- */
+/** Default carried fraction for a vertical tilt. */
 export const TILT_CARRIED_FRACTION = 0.12
 
 /** True for the vertical tilt directions (up/down), false for the pans. */
@@ -54,60 +31,3 @@ export function isTiltDirection(direction: SurroundDirection): boolean {
 export function defaultCarriedFraction(direction: SurroundDirection): number {
   return isTiltDirection(direction) ? TILT_CARRIED_FRACTION : DEFAULT_CARRIED_FRACTION
 }
-
-/** Which edge of the NEW frame holds the carried pixels vs the painted region. */
-const EDGE: Record<SurroundDirection, { carried: string; painted: string }> = {
-  right: { carried: "left", painted: "right" },
-  left: { carried: "right", painted: "left" },
-  up: { carried: "bottom", painted: "top" },
-  down: { carried: "top", painted: "bottom" },
-}
-
-/** What a tilt must actually render (NOT a continuation of the landscape). */
-const TILT_SUBJECT: Record<"up" | "down", { word: string; subject: string; where: string }> = {
-  up: {
-    word: "up",
-    subject: "the open sky directly overhead — sky, clouds, or (for an interior) the canopy or ceiling",
-    where: "overhead",
-  },
-  down: {
-    word: "down",
-    subject: "the ground directly below — terrain, floor, or water surface",
-    where: "below",
-  },
-}
-
-/**
- * Build the fill prompt the model receives alongside the half-carry composite.
- *
- * `userPrompt` (an optional scene hint from the caller) is woven in front. PAN
- * directions get the seamless-continuation prompt (with the anti-golden-hour
- * negative that fights the documented warm-regrade drift). TILT directions get a
- * subject-forcing prompt — render the sky / ground overhead / below, explicitly
- * NOT a mirrored landscape — which is what stops the vertical echo.
- */
-export function buildSurroundFillPrompt(direction: SurroundDirection, userPrompt?: string): string {
-  const scene = userPrompt && userPrompt.trim() ? `${userPrompt.trim()}. ` : ""
-  const { carried, painted } = EDGE[direction]
-
-  if (direction === "up" || direction === "down") {
-    const t = TILT_SUBJECT[direction]
-    return (
-      `${scene}` +
-      `This is a camera tilted straight ${t.word} from the same scene. The ${carried} strip holds real, finished pixels from the edge of the horizon view; the ${painted} region is flat gray and MUST be painted as ${t.subject}. ` +
-      `Render what is genuinely ${t.where} — do NOT repeat, mirror, or continue the landscape, and do NOT draw a horizon line or distant scenery in the painted region. ` +
-      `CRITICAL: keep the ${carried} strip unchanged and match the scene's EXACT lighting, time of day, white balance, and color grade — the same light as the ${carried} strip; no golden hour, no sunset, no warm relight, no cinematic regrade. ` +
-      `Blend smoothly into the ${carried} strip with no visible seam. No people, no text, no labels, no watermarks.`
-    )
-  }
-
-  // pan (right / left)
-  return (
-    `${scene}` +
-    `This is a partial frame: the ${carried} portion contains real, finished pixels and the ${painted} portion is flat gray that MUST be painted in. ` +
-    `Paint ONLY the ${painted} gray region as a natural, seamless continuation of the ${carried} portion — same scene, same perspective, continuing the horizon, geometry, and content across the boundary with no break. ` +
-    `Keep the ${carried} portion completely unchanged. ` +
-    `CRITICAL: do NOT change the lighting, exposure, white balance, or time of day. Match the ${carried} portion's EXACT light, color temperature, and contrast across the whole frame — if it is flat overcast daylight, keep flat overcast daylight. No golden hour, no sunset, no warm relight, no cinematic regrade. ` +
-    `The seam between the ${carried} and ${painted} portions must be invisible. No people, no text, no labels, no watermarks.`
-  )
-}

package/src/vehicles.ts

@@ -31,6 +31,16 @@ export interface Vehicle {
   readonly label: string
   readonly subcategory: VehicleSubcategory
   readonly description: string
+  /**
+   * Optional authored compact term — the short phrase a professional would
+   * write in a prompt, as opposed to the user-facing `label` (see the `term`
+   * convention in `@nodaro/prompts`'s `term.ts`). Authored ONLY where the
+   * lowercased label is not that phrase — a UI compound naming two things at
+   * once ("Airship / Dirigible" -> "airship", "Plasma Sword / Lightsaber" ->
+   * "plasma sword"). Everywhere else the lowercased label IS the term for a
+   * concrete object ("golden retriever", "katana"), so nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const VEHICLES: ReadonlyArray<Vehicle> = [
@@ -117,7 +127,7 @@ export const VEHICLES: ReadonlyArray<Vehicle> = [
   { id: "seaplane",              label: "Seaplane",              subcategory: "aircraft", description: "Seaplane with twin pontoon floats instead of wheels, high wings and a propeller, resting on calm water" },
   { id: "hot-air-balloon",       label: "Hot Air Balloon",       subcategory: "aircraft", description: "Giant hot-air balloon with a colorful rainbow-striped fabric envelope, a roaring flame burner flaring upward into the mouth and a wicker passenger basket suspended below by braided cables" },
   { id: "blimp",                 label: "Blimp",                 subcategory: "aircraft", description: "Sausage-shaped blimp airship with a sleek silver envelope, small rear fins and a slung gondola beneath" },
-  { id: "airship",               label: "Airship / Dirigible",   subcategory: "aircraft", description: "Massive rigid lighter-than-air dirigible with a long cigar-shaped fabric-covered metal frame, large rear stabilizer fins, multiple slung engine gondolas and a long passenger cabin running underneath the hull" },
+  { id: "airship",               label: "Airship / Dirigible",   subcategory: "aircraft", description: "Massive rigid lighter-than-air dirigible with a long cigar-shaped fabric-covered metal frame, large rear stabilizer fins, multiple slung engine gondolas and a long passenger cabin running underneath the hull", term: "airship" },
   { id: "glider",                label: "Glider",                subcategory: "aircraft", description: "Elegant sailplane glider with ultra-long narrow wings, no engine and a teardrop cockpit pod" },
   { id: "paraglider",            label: "Paraglider",            subcategory: "aircraft", description: "Foot-launched paraglider with a wide elliptical soft-fabric ram-air wing arched overhead, dozens of slender suspension lines converging into a tandem harness with a seated pilot" },
   { id: "microlight",            label: "Microlight Aircraft",   subcategory: "aircraft", description: "Lightweight single-pilot microlight aircraft with an exposed tubular metal frame, fabric-covered high wings, a small pusher propeller engine behind the open seat and tricycle landing gear" },

package/src/video-analysis-pricing.ts

@@ -9,14 +9,12 @@
  * `buildVideoAnalysisCreditId` + `/v1/credits/model-cost`) all derive from
  * these.
  *
- * The measured-rate constants and the $-derived `videoAnalysisBucketCredits`
- * formula that GENERATE these numbers live PRIVATELY in the
- * `@nodaroai/cloud-plugins` package (`src/plugins/video-analysis/cost.ts`) —
- * never in this public repo. They were first moved out of this package
- * (published Apache-2.0 on npm) per the 2026-07-06 public-flip IP audit S5,
- * then out of the app repo entirely alongside the rest of the video-analysis
- * node. A cross-check test in that private package guards this table so the
- * public numbers can't silently drift from the formula.
+ * The rate constants and the formula that GENERATE these numbers live
+ * PRIVATELY in the `@nodaroai/cloud-plugins` package — never in this public
+ * repo. They were first moved out of this package (published Apache-2.0 on
+ * npm), then out of the app repo entirely alongside the rest of the
+ * video-analysis node. A cross-check test in that private package guards
+ * this table so the public numbers can't silently drift from the formula.
  *
  * `VIDEO_ANALYSIS_BUCKET_CREDITS` below is the precomputed OUTPUT of that
  * private formula for every (model × bucket) combination — a plain credit
@@ -24,9 +22,8 @@
  * `VIDEO_CLIP_CREDITS` uses in `film-pricing.ts`. It is what the frontend's
  * client-side cost preview (`estimateNodeCredits` in
  * workflow-editor/types.ts) reads instead of calling the formula directly.
- * The formula's own test in `@nodaroai/cloud-plugins`
- * (`src/plugins/video-analysis/__tests__/cost.test.ts`) cross-checks this table
- * against it and fails on drift. There is deliberately NO app-side formula to
+ * The formula's own test in `@nodaroai/cloud-plugins` cross-checks this
+ * table against it and fails on drift. There is deliberately NO app-side formula to
  * check against — it was moved private in 2026-07 and the old backend test
  * went with it.
  *
@@ -65,27 +62,20 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
 // not 110). The plugin's cost test now covers sentinels as well, so this class
 // of drift fails CI instead of shipping.
 // REGENERATED 2026-07-31 with the smart-tier re-base (formula inputs moved in
-// the plugin: sampling 24→6 fps after a 43-run measurement found 6 equal on
-// content and strictly better on cast stability; the system-prompt and
-// per-window output-token constants trued-up to directly measured values).
-// Net effect: smart drops 27–47% per bucket — the 24 fps token spend was also
-// partly paying for media tokens the provider clamped and never counted — and
-// the economy rows tick up 3–6% from the prompt-token true-up.
+// the plugin: sampling 24→6 fps, which proved equal on content and better on
+// cast stability; system-prompt and per-window output-token constants updated).
+// Net effect: smart drops 27–47% per bucket, and the economy rows tick up 3–6%.
 //
-// REGENERATED 2026-08-03 — V1 hybrid-smart reprice (task A3), from the
-// plugin's own generator (`scripts/gen-va-buckets.mjs`) at
-// nodaroai/nodaro-cloud-plugins commit eef077d (branch fix/va-cost-trueup).
-// This is the V1 true-up of task P6's provisional judge/refine/frame-judge
-// constants, re-derived from a 2026-08-03 staging measurement and approved by
-// Tal (the constants themselves, like the rest of the $-derived formula, stay
-// private in the plugin repo — never in this public package). `smart` is now
-// a HYBRID plan — one native 6fps skeleton pass plus 2 fast + 2 pro donor
-// rolls, always refined (`selectionMode` does not apply to `smart`; it always
-// refines) — and every multi-roll tier now carries its own explicit
-// judge/refine terms instead of an implicit share of a single-pass budget.
-// This is the full, honest reprice Tal approved, including the economy tiers
-// (fast 33->185 @180s ends a below-cost combine exposure that existed at the
-// old price). Net effect, per bucket (every row rises):
+// REGENERATED 2026-08-03 — V1 hybrid-smart reprice, from the plugin's own
+// generator. This is the V1 true-up of the earlier provisional
+// judge/refine/frame-judge constants (the constants themselves, like the rest
+// of the formula, stay private in the plugin repo — never in this public
+// package). `smart` is now a multi-roll plan that always refines its merged
+// result (`selectionMode` does not apply to it), and every multi-roll tier
+// now carries its own explicit judge/refine terms instead of an implicit
+// share of a single-pass budget.
+// The economy tiers rise too (fast 33->185 @180s).
+// Net effect, per bucket (every row rises):
 //
 //   gemini-3-flash    60s   24->180   180s   33->185   360s   86-> 514   600s  143-> 846
 //   gemini-3.6-flash  60s   65->203   180s   92->218   360s  237-> 598   600s  395-> 986
@@ -119,9 +109,8 @@ export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
   "video-analysis:mixed:180s": 289,
   "video-analysis:mixed:360s": 724,
   "video-analysis:mixed:600s": 1169,
-  // SMART — the accuracy tier, and since the 2026-08-03 hybrid re-plan a
-  // multi-roll plan like the others: one native 6fps skeleton pass plus 2
-  // fast + 2 pro donor rolls, always refined (`selectionMode` does not apply
+  // SMART — the accuracy tier, and since the 2026-08-03 re-plan a multi-roll
+  // plan like the others, always refined (`selectionMode` does not apply
   // here — smart always refines; it never offers a cheaper "choose" path).
   // Priced above the economy tiers because it genuinely costs more to run;
   // the only tier whose accuracy is validated against a hand-counted edit
@@ -168,7 +157,7 @@ export function videoAnalysisNumWindows(bucketSec: number): number {
  * Precomputed credit cost for the `video-audit` node ("AI Audit") — the same
  * pattern as `VIDEO_ANALYSIS_BUCKET_CREDITS` above: the OUTPUT of the private
  * `videoAuditBucketCredits` formula in `@nodaroai/cloud-plugins`
- * (`src/plugins/video-analysis/cost.ts`), a plain lookup table never a
+ * (in the plugin repo), a plain lookup table never a
  * formula, cross-checked against that package's own cost test. Shares the
  * SAME duration-bucket ladder as video-analysis (`VIDEO_ANALYSIS_DURATION_BUCKETS`
  * / `pickVideoAnalysisBucket`) — the audit re-watches the same clip, so it
@@ -195,7 +184,7 @@ export function videoAnalysisNumWindows(bucketSec: number): number {
  * `buildVideoAnalysisCreditId`.
  *
  * Values pasted verbatim from the plugin generator's output
- * (`scripts/gen-va-buckets.mjs`) at `@nodaroai/cloud-plugins` v0.102.0 —
+ * (the plugin repo's bucket generator) —
  * never hand computed. The plugin's cost test cross-checks every row.
  */
 export const VIDEO_AUDIT_BUCKET_CREDITS: Record<string, number> = {

package/src/weapons.ts

@@ -30,6 +30,16 @@ export interface Weapon {
   readonly label: string
   readonly subcategory: WeaponSubcategory
   readonly description: string
+  /**
+   * Optional authored compact term — the short phrase a professional would
+   * write in a prompt, as opposed to the user-facing `label` (see the `term`
+   * convention in `@nodaro/prompts`'s `term.ts`). Authored ONLY where the
+   * lowercased label is not that phrase — a UI compound naming two things at
+   * once ("Airship / Dirigible" -> "airship", "Plasma Sword / Lightsaber" ->
+   * "plasma sword"). Everywhere else the lowercased label IS the term for a
+   * concrete object ("golden retriever", "katana"), so nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const WEAPONS: ReadonlyArray<Weapon> = [
@@ -131,7 +141,7 @@ export const WEAPONS: ReadonlyArray<Weapon> = [
   { id: "phaser",               label: "Phaser",              subcategory: "sci-fi", description: "Sleek sci-fi phaser with a minimalist curved grip, glowing emitter tip and a smooth panel controlling intensity" },
   { id: "rail-gun",             label: "Rail Gun",            subcategory: "sci-fi", description: "Heavy electromagnetic rail gun with parallel metal rails, massive capacitors along the body and a glowing projectile chamber" },
   { id: "emp-grenade",          label: "EMP Grenade",         subcategory: "sci-fi", description: "Spherical electromagnetic pulse grenade with exposed coils, glowing blue indicator lights and a holographic arming dial" },
-  { id: "plasma-sword",         label: "Plasma Sword / Lightsaber", subcategory: "sci-fi", description: "Sci-fi energy blade with a metallic ridged hilt projecting a tall column of saturated plasma energy, surrounded by a bright halo of glowing light, casting colored reflections on the wielder and humming softly with contained power" },
+  { id: "plasma-sword",         label: "Plasma Sword / Lightsaber", subcategory: "sci-fi", description: "Sci-fi energy blade with a metallic ridged hilt projecting a tall column of saturated plasma energy, surrounded by a bright halo of glowing light, casting colored reflections on the wielder and humming softly with contained power", term: "plasma sword" },
   { id: "gravity-gun",          label: "Gravity Gun",         subcategory: "sci-fi", description: "Sci-fi physics-manipulating ranged weapon with a chunky metallic body, three articulated prongs at the muzzle that crackle with blue gravitational energy, exposed power conduits along the barrel and a heavy two-handed grip with a glowing trigger assembly" },
 
   // -------------------- Fantasy / Magical --------------------

package/src/workflow-export.ts

@@ -74,6 +74,45 @@ export interface WorkflowExportLocation {
   styleLock?: boolean | null
 }
 
+/** A media URL referenced from a node's data, located by node + field path. */
+export interface WorkflowMediaRef {
+  nodeId: string
+  nodeLabel?: string
+  /** Dot/bracket path inside `node.data`, e.g. `imageUrl` or `referenceImageUrls[1]`. */
+  field: string
+  url: string
+}
+
+/**
+ * Export-time portability analysis (#866). A bundle exported from a private
+ * host carries media URLs only that host can serve (`http://localhost:3000/
+ * storage/…`, a LAN address, a `.internal` name); imported anywhere else, the
+ * nodes fail at Run time with an opaque provider fetch error. The exporter
+ * lists those URLs here so the person exporting is told BEFORE sharing, and
+ * an importer can explain what will not load. Absent when every media URL is
+ * publicly routable.
+ */
+export interface WorkflowPortability {
+  unreachableMedia: WorkflowMediaRef[]
+}
+
+/**
+ * What the importer did about the bundle's media (#866). Publicly reachable
+ * media that is not already on the importing instance's own storage is
+ * copied there (`rehosted`) so the workflow runs from local copies; media on
+ * a host the importer cannot reach is left as-is and listed (`unreachable`);
+ * anything declined for another reason (too large, not a media type, over
+ * the per-import cap, upload failed) is listed with the reason (`skipped`).
+ */
+export interface WorkflowImportReport {
+  rehosted: number
+  unreachable: WorkflowMediaRef[]
+  skipped: Array<WorkflowMediaRef & { reason: string }>
+  /** Anything else the importer should know, e.g. copies were made but the
+   *  workflow could not be updated to use them. */
+  notes?: string[]
+}
+
 export interface WorkflowExport {
   version: 1
   exportedAt: string
@@ -87,6 +126,8 @@ export interface WorkflowExport {
     creatures?: WorkflowExportCreature[]
     locations: WorkflowExportLocation[]
   }
+  /** Present only when the bundle references media another instance cannot fetch. */
+  portability?: WorkflowPortability
 }
 
 /**