@nodaro/shared 1.4.1

package/src/types.ts

@@ -0,0 +1,272 @@
+/**
+ * Generic node/edge interfaces for structural subtyping.
+ * Both frontend WorkflowNode and backend SimpleNode satisfy these.
+ */
+
+import type { UsageMode } from "./character-usage-mode.js"
+import type { LocationReferencePhotoKind } from "./entity-asset-types.js"
+
+export interface GenericNode {
+  id: string
+  type: string
+  /**
+   * Canvas (React-Flow) position. The editor needs it to lay the node out —
+   * without it React-Flow stacks every node at (0,0). Optional so non-canvas
+   * callers (pure graph data) need not supply it.
+   */
+  position?: { x: number; y: number }
+  /** Fixed canvas width the editor applies (e.g. 220 for generate-image/-video). */
+  width?: number
+  data: Record<string, unknown>
+  hidden?: boolean
+}
+
+export interface GenericEdge {
+  /** Stable edge id — React-Flow requires one to render the connection. */
+  id?: string
+  source: string
+  target: string
+  sourceHandle?: string | null
+  targetHandle?: string | null
+}
+
+export interface CharacterDef {
+  id: string
+  name: string
+  type: "reference" | "description"
+  category?: string
+  referenceImageUrl?: string
+  description?: string
+}
+
+// ---------------------------------------------------------------------------
+// Reference image metadata.
+//
+// An "identity" = (imageIndex, label) — what role this image plays at a given
+// mention. The same image can appear under multiple identities (e.g. image 1
+// used both as `:dragon` and as `:background`). Tokens in the prompt are
+// `{image:N:label}`, with `{image:N}` as a backward-compat positional ref.
+// ---------------------------------------------------------------------------
+
+export type IdentityFidelity = "strict" | "balanced" | "loose" | "custom"
+
+export type ReferenceSource =
+  | "manual"
+  | "wired-image"
+  | "wired-character"
+  | "wired-face"
+  | "wired-object"
+  | "wired-creature"
+  | "wired-location"
+
+/** Per-identity user override stored on the consumer node. */
+export interface IdentityMeta {
+  /** 1-based position of the source image. */
+  imageIndex: number
+  /** Role label this entry covers (e.g. "object", "background", "person"). */
+  label: string
+  fidelity?: IdentityFidelity
+  /** Free-text directive used when fidelity === "custom" (replaces the preset). */
+  customText?: string
+}
+
+/** Computed view of a single connected reference, ready for the prompt builder. */
+export interface ConnectedReference {
+  id: string
+  defaultName: string
+  source: ReferenceSource
+  /** Optional rich text from upstream char/face/object/location node. */
+  description?: string
+  url: string
+  /** Slug of the source character (e.g. "kira") when this entry came from a character node. */
+  readonly characterSlug?: string
+  /** Variant slug (e.g. "smile"). undefined = canonical/default. */
+  readonly variantSlug?: string
+  /** Character's canonical_description. Set on every entry from the same character (used for dedup). */
+  readonly characterCanonicalDescription?: string | null
+  /**
+   * Resolved prompt-fragment for the elements (held-prop / styling / text /
+   * pickers) wired into the SOURCE character node's Assets/Prompt handle. A
+   * mode-INDEPENDENT sibling of `characterCanonicalDescription`: where the
+   * canonical description is only emitted for identity-locking modes, this is
+   * scene composition ("holding a smartphone…") and rides the character's
+   * identity bullet in EVERY mode that emits one (only `none` — which emits no
+   * bullet — drops it). Resolved at assembly time from the wiring (never stored
+   * on the character record). Stamped onto every entry of the same character so
+   * whichever entry produces the primary bullet carries it. Absent/empty →
+   * byte-identical to the pre-elementInjection output.
+   */
+  readonly elementInjection?: string | null
+  /**
+   * Location's canonical_description. Set on every entry derived from a wired
+   * Location node (canonical image + future per-variant entries from Phase 2 #2
+   * @location:1:variant mention syntax). Mirrors `characterCanonicalDescription`
+   * — the directive builder appends this to the `wired-location` ref's subject
+   * line when the location's slug isn't in `suppressedCanonicalLocationIds`.
+   */
+  readonly locationCanonicalDescription?: string | null
+  /** Slug of the source location (e.g. "old-library") when this entry came from a location node. Used by `suppressedCanonicalLocationIds` filtering. */
+  readonly locationSlug?: string
+  /**
+   * Variant bucket for per-variant location entries (Phase 2 #2). One of the
+   * 6 location asset buckets — "timeOfDay" / "weather" / "seasons" / "angles"
+   * / "lighting" / "atmosphereMotions". `undefined` for the canonical
+   * main-image entry.
+   *
+   * Used by `resolveLocationMentions` to find the entry matching a
+   * `@oldlibrary:1:weather/rain` mention token (lookup key is
+   * `${locationSlug}:${locationVariantBucket}/${locationVariantSlug}`).
+   */
+  readonly locationVariantBucket?: string
+  /**
+   * Variant slug for per-variant location entries (e.g. "rain", "neon"). The
+   * raw variant `name` from the location node's bucket array, slugified via
+   * `locationMentionSlug` so the resolver match is case-insensitive and
+   * whitespace-tolerant (`"light rain"` ↔ `"light-rain"`). `undefined` for
+   * the canonical main-image entry.
+   */
+  readonly locationVariantSlug?: string
+  /** Display name for the variant in autocomplete UI (e.g. "rain", "canonical"). */
+  readonly locationVariantDisplayName?: string
+  /**
+   * For user-uploaded reference photos on wired locations, the photo's
+   * `kind` — one of the 6 `LocationReferencePhotoKind` values. Drives the
+   * prompt-builder's subject-line annotation so the model knows the role
+   * (wide-angle establishing shot vs. interior detail vs. mood-board
+   * context). Mirrors `locationVariantBucket` but for user-uploaded refs
+   * instead of generated per-variant assets.
+   *
+   * Reference-photo entries have THIS field set but `locationVariantBucket`
+   * unset — that's how the connectedReferences filter at
+   * `prompt-builder.ts` lines ~1011-1016 distinguishes them from
+   * mention-only variant entries. Reference photos AUTO-ATTACH (they're
+   * not gated by `@-mention`), so the filter must NOT drop them.
+   */
+  readonly locationReferencePhotoKind?: LocationReferencePhotoKind
+  /** The asset's own description (per-variant). null for canonical entries. */
+  readonly variantDescription?: string | null
+  /** Display name for the variant in autocomplete UI (e.g. "smile", "canonical"). */
+  readonly variantDisplayName?: string
+  /**
+   * Character node's `defaultUsageMode` propagated into every entry derived
+   * from that node. Used by `resolveCharacterMentions` as the fallback when
+   * the per-mention slug doesn't carry an explicit mode override. Absent for
+   * non-character refs and for character entries built without a node context
+   * (e.g. character-definition-only entries in legacy paths).
+   */
+  readonly defaultUsageMode?: UsageMode
+  /**
+   * Character node's HYBRID `defaultRole` (the role-dropdown pick: a
+   * `REFERENCE_ROLE_PRESETS["wired-character"]` value or a sanitized Custom
+   * slug) propagated into every entry derived from that node. Read via
+   * `resolveDefaultRole(defaultRole, defaultUsageMode, source)` at the hybrid
+   * resolver sites — it takes precedence over `defaultUsageMode`. Absent for
+   * non-character refs and for nodes that never set a role (fall back to the
+   * `defaultUsageMode`-derived role, then the source default).
+   */
+  readonly defaultRole?: string
+  /**
+   * Marks an entry as a user-attached "extra reference image" (see the
+   * `extraRefs` field on Generate/Modify/Image-to-Video/Text-to-Video/Video-to-Video
+   * node data types in the frontend). Extras are auto-attached to the worker
+   * `referenceImageUrls` AND get a dedicated directive line in the assembled
+   * prompt:
+   *   - character-sourced extras of an already-emitted character →
+   *     "Image N is the same subject as Image M, <description>."
+   *   - character-sourced extras of a previously-unseen character →
+   *     a canonical-style directive using the description as the descriptor
+   *   - manual-sourced extras →
+   *     "Image N (reference): <description>."
+   *
+   * The `description` field carries the per-ref free-text the user typed.
+   * Without this marker, character refs with a variantSlug are treated as
+   * autocomplete-only (the legacy behavior — unmentioned variants don't
+   * auto-attach), which is exactly what we DON'T want for explicit extras.
+   */
+  readonly isExtraRef?: boolean
+  // ─── Character LoRA training (Cloud edition) ──────────────────────────────
+  // Propagated from CharacterNodeData on the upstream character node. Used
+  // by selectLoraRoutingForMentions (`@nodaro/shared` + backend mirror) to
+  // decide whether to route generate-image through `flux-lora-character`
+  // instead of reference-image injection.
+  readonly loraReplicateVersion?: string | null
+  readonly loraTriggerWord?: string | null
+  readonly loraTrainingStatus?: string | null
+  /**
+   * Optional, opt-in identity-lock for this reference. When `enabled === true`,
+   * a short fidelity line is prepended so the model preserves the subject's
+   * exact identity. `text` overrides the built-in default (use `{ref}` as the
+   * placeholder for the reference's binding, e.g. "reference image A"). Default
+   * is OFF for EVERY source: absent or `enabled === false` emits no lock line.
+   * The single new structured-shape field for external (API/MCP/SDK) parity.
+   */
+  readonly identityLock?: { enabled: boolean; text?: string }
+}
+
+/** Default label per source — used by `@` autocomplete and inventory fallback. */
+export const DEFAULT_LABEL_BY_SOURCE: Record<ReferenceSource, string> = {
+  "manual": "object",
+  "wired-image": "object",
+  "wired-character": "person",
+  "wired-face": "face",
+  "wired-object": "object",
+  // A bound Creature (animal/beast/monster) — its directive reads as a living
+  // subject ("match anatomy, markings…"), not a prop. See CREATURE_LABELS in
+  // prompt-builder.ts.
+  "wired-creature": "creature",
+  "wired-location": "background",
+}
+
+// ---------------------------------------------------------------------------
+// Scene node data — minimal interface for buildScenePrompt.
+// Frontend SceneNodeDataType satisfies this via structural subtyping.
+// Backend casts Record<string, unknown> node data to this.
+// ---------------------------------------------------------------------------
+
+export interface SceneCharacterEntry {
+  readonly assetId: string
+  readonly mood: string
+  readonly action: string
+  readonly positionInFrame?: "left" | "center" | "right" | "foreground" | "background"
+}
+
+export interface SceneLocationEntry {
+  readonly assetId: string
+  readonly name?: string
+  readonly isPrimary?: boolean
+  readonly timeOfDay?: string
+  readonly weather?: string
+  readonly lighting?: string
+}
+
+export interface SceneObjectEntry {
+  readonly assetId: string
+  readonly description?: string
+}
+
+export interface SceneDialogueEntry {
+  readonly characterName: string
+  readonly text: string
+  readonly emotion?: string
+}
+
+export interface SceneData {
+  readonly shotType: string
+  readonly cameraAngle: string
+  readonly aspectRatio: string
+  readonly characters: readonly SceneCharacterEntry[]
+  readonly locations?: readonly SceneLocationEntry[]
+  readonly objects: readonly SceneObjectEntry[]
+  readonly mood: readonly string[]
+  readonly visualStyle: string
+  readonly depthOfField: string
+  readonly lensType: string
+  readonly cameraMovement: string
+  readonly colorPalette: readonly string[]
+  readonly summary: string
+  readonly dialogue?: readonly SceneDialogueEntry[]
+  readonly directorNotes?: string
+  readonly timeOfDay: string
+  readonly weather: string
+  readonly lighting: string
+}

package/src/variant-job-id.ts

@@ -0,0 +1,17 @@
+/**
+ * R2-key + result-id suffix for multi-variant jobs. Provider returns multiple
+ * URLs from a single task (Grok = up to 6 images, Suno = 2 tracks); each
+ * variant gets a deterministic suffix-keyed ID so primary stays at the original
+ * jobId for backwards compat and extras land under `${jobId}-v1`, `${jobId}-v2`, …
+ *
+ * Used by:
+ *   - backend `uploadImageVariantsMaybeWatermark` (R2 key)
+ *   - backend Suno `uploadAllSunoTracks` (R2 key)
+ *   - frontend `poll-job.ts handleJobCompleted` (GeneratedResult.jobId)
+ *   - frontend `run-handlers.ts` orchestrator poll loop (GeneratedResult.jobId)
+ *
+ * Changing the suffix scheme requires updating every caller, hence the shared helper.
+ */
+export function variantJobId(baseJobId: string, index: number): string {
+  return index === 0 ? baseJobId : `${baseJobId}-v${index}`
+}

package/src/vehicles.ts

@@ -0,0 +1,213 @@
+/**
+ * Canonical catalog of vehicle presets for the Object entity node.
+ *
+ * When the Object category is "vehicle", users pick a specific vehicle from
+ * this catalog. The picker auto-fills the object's `objectName` and
+ * `description` so the existing `buildObjectPrompt` pipeline just works — no
+ * backend prompt changes needed.
+ *
+ * Organized into everyday sub-categories: classic cars, everyday cars,
+ * performance cars, motorcycles, bicycles (human-powered), trucks, transit
+ * (buses + rail + horse-drawn), aircraft, watercraft, military, construction,
+ * and sci-fi.
+ */
+
+export type VehicleSubcategory =
+  | "cars-classic"
+  | "cars-everyday"
+  | "cars-performance"
+  | "motorcycles"
+  | "bicycles"
+  | "trucks"
+  | "transit"
+  | "aircraft"
+  | "watercraft"
+  | "military"
+  | "construction"
+  | "sci-fi"
+
+export interface Vehicle {
+  readonly id: string
+  readonly label: string
+  readonly subcategory: VehicleSubcategory
+  readonly description: string
+}
+
+export const VEHICLES: ReadonlyArray<Vehicle> = [
+  // -------------------- Classic Cars --------------------
+  { id: "muscle-car",            label: "Muscle Car",            subcategory: "cars-classic", description: "Aggressive American muscle car with a long hood, wide stance, dual chrome exhausts and a deep throaty V8 presence" },
+  { id: "car-57-chevy",          label: "'57 Chevy",             subcategory: "cars-classic", description: "Iconic 1957 Chevrolet Bel Air with tail fins, chrome bumpers, two-tone paint and whitewall tires" },
+  { id: "hot-rod",               label: "Hot Rod",               subcategory: "cars-classic", description: "Chopped and channeled hot rod with flame paint job, exposed chrome engine, fat rear tires and skinny fronts" },
+  { id: "vintage-roadster",      label: "Vintage Roadster",      subcategory: "cars-classic", description: "Pre-war open-top roadster with sweeping fenders, running boards, wire-spoke wheels and a long polished hood" },
+  { id: "model-t",               label: "Ford Model T",          subcategory: "cars-classic", description: "Early 20th-century black Model T with boxy upright body, brass headlamps, spoked wheels and a cranked engine" },
+  { id: "vw-beetle",             label: "VW Beetle",             subcategory: "cars-classic", description: "Rounded pastel-colored Volkswagen Beetle with a curved hood, air-cooled rear engine and cheerful bug-like face" },
+  { id: "checker-cab",           label: "Checker Cab",           subcategory: "cars-classic", description: "Classic yellow New York checker taxi with a boxy body, black-and-white checker band and roof light" },
+  { id: "woody-wagon",           label: "Woody Wagon",           subcategory: "cars-classic", description: "Surf-era station wagon with wood-paneled side doors, chrome bumpers and a long tailgate" },
+  { id: "lowrider",              label: "Lowrider",              subcategory: "cars-classic", description: "Candy-painted lowrider with hydraulic suspension, chrome spoke wheels, whitewall tires and airbrushed murals" },
+
+  // -------------------- Everyday Cars --------------------
+  { id: "sedan",                 label: "Sedan",                 subcategory: "cars-everyday", description: "Four-door midsize sedan with a streamlined silhouette, chrome accents and modern LED headlights" },
+  { id: "suv",                   label: "SUV",                   subcategory: "cars-everyday", description: "Large sport utility vehicle with a tall stance, roof rails, big alloy wheels and a muscular squared-off body" },
+  { id: "hatchback",             label: "Hatchback",             subcategory: "cars-everyday", description: "Compact hatchback with a short rear, lift-up tailgate, nimble proportions and bright paint" },
+  { id: "minivan",               label: "Minivan",               subcategory: "cars-everyday", description: "Family minivan with sliding side doors, a tall spacious cabin, tinted rear windows and a roomy rear hatch" },
+  { id: "station-wagon",         label: "Station Wagon",         subcategory: "cars-everyday", description: "Long-roof station wagon with extended cargo area, rear quarter windows and a family-oriented silhouette" },
+  { id: "crossover",             label: "Crossover",             subcategory: "cars-everyday", description: "Mid-sized crossover SUV with a raised ride height, car-like styling and aerodynamic LED accents" },
+  { id: "electric-car",          label: "Electric Car",          subcategory: "cars-everyday", description: "Sleek modern electric car with a smooth grille-less front, flush door handles and aerodynamic clean lines" },
+  { id: "hatchback-econobox",    label: "Econobox",              subcategory: "cars-everyday", description: "Tiny affordable two-door city car with a stubby hood, small wheels and simple compact styling" },
+  { id: "police-car",            label: "Police Car",            subcategory: "cars-everyday", description: "Black-and-white patrol car with a roof-mounted light bar flashing red and blue, push bar on the front bumper, agency decals on the doors and antenna whips on the trunk" },
+
+  // -------------------- Performance / Exotic --------------------
+  { id: "sports-car",            label: "Sports Car",            subcategory: "cars-performance", description: "Low-slung two-door sports car with a wide aggressive stance, aerodynamic bodywork and bright glossy paint" },
+  { id: "supercar",              label: "Supercar",              subcategory: "cars-performance", description: "Exotic mid-engined supercar with scissor doors, an ultra-low hood, huge rear intakes and a carbon-fiber rear wing" },
+  { id: "convertible",           label: "Convertible",           subcategory: "cars-performance", description: "Two-seat convertible with the soft top down, a long sculpted hood and wind streaming past low-cut doors" },
+  { id: "grand-tourer",          label: "Grand Tourer",          subcategory: "cars-performance", description: "Elegant grand-touring coupe with a long flowing hood, four exhausts and luxurious proportions" },
+  { id: "roadster",              label: "Roadster",              subcategory: "cars-performance", description: "Compact two-seat roadster with a wraparound windshield, soft top tucked away and classic top-down silhouette" },
+  { id: "racing-car",            label: "Racing Car",            subcategory: "cars-performance", description: "Open-wheel formula racing car with slick tires, a large rear wing, halo cockpit and aerodynamic sidepods covered in sponsor logos" },
+  { id: "rally-car",             label: "Rally Car",             subcategory: "cars-performance", description: "Dirt-splattered rally hatchback with knobby tires, huge mud flaps, roof-mounted lights and race liveries" },
+  { id: "drift-car",             label: "Drift Car",             subcategory: "cars-performance", description: "Aggressive drift-tuned coupe with a wide body kit, oversized rear wing, neon underglow and tire smoke trailing behind" },
+
+  // -------------------- Motorcycles --------------------
+  { id: "sportbike",             label: "Sportbike",             subcategory: "motorcycles", description: "Aerodynamic sport motorcycle with a crouched riding stance, full fairings, sticky tires and bright race-style graphics" },
+  { id: "cruiser",               label: "Cruiser",               subcategory: "motorcycles", description: "Low-slung cruiser motorcycle with a long teardrop tank, swept-back handlebars, chrome exhausts and fat rear tire" },
+  { id: "chopper",               label: "Chopper",               subcategory: "motorcycles", description: "Stretched custom chopper with a raked-out front end, tall ape-hanger handlebars, skinny front wheel and chrome everywhere" },
+  { id: "dirt-bike",             label: "Dirt Bike",             subcategory: "motorcycles", description: "Off-road dirt bike with knobby tires, tall suspension, plastic fairings in bright colors and high handlebars" },
+  { id: "scooter",               label: "Scooter",               subcategory: "motorcycles", description: "Compact step-through scooter with a smooth body shell, small wheels, a flat footrest and an under-seat storage bump" },
+  { id: "moped",                 label: "Moped",                 subcategory: "motorcycles", description: "Small pedal-start moped with a simple steel frame, basket up front and a tiny gas engine under the seat" },
+  { id: "cafe-racer",            label: "Cafe Racer",            subcategory: "motorcycles", description: "Stripped-down cafe racer motorcycle with clip-on bars, a humped solo seat, exposed frame and minimalist tank" },
+
+  // -------------------- Bicycles & Human-Powered --------------------
+  { id: "road-bike",             label: "Road Bike",             subcategory: "bicycles", description: "Lightweight road bike with drop handlebars, skinny high-pressure tires and an aerodynamic carbon frame" },
+  { id: "mountain-bike",         label: "Mountain Bike",         subcategory: "bicycles", description: "Rugged mountain bike with knobby tires, front suspension fork, flat handlebars and a mud-splattered frame" },
+  { id: "bmx",                   label: "BMX Bike",              subcategory: "bicycles", description: "Stunt BMX bike with a small frame, pegs on the axles, chunky tires and a cross-brace handlebar" },
+  { id: "cruiser-bike",          label: "Beach Cruiser",         subcategory: "bicycles", description: "Relaxed beach cruiser bicycle with a curved frame, swept-back handlebars, wide seat and balloon tires" },
+  { id: "penny-farthing",        label: "Penny Farthing",        subcategory: "bicycles", description: "Victorian penny-farthing bicycle with an enormous front wheel, tiny rear wheel and a perched leather saddle high above" },
+  { id: "unicycle",              label: "Unicycle",              subcategory: "bicycles", description: "Single-wheeled unicycle with a tall seat post, simple pedals on the hub and a minimalist circus look" },
+  { id: "skateboard",            label: "Skateboard",            subcategory: "bicycles", description: "Wooden skateboard deck with grip tape on top, four polyurethane wheels and colorful graphic art on the underside" },
+  { id: "kick-scooter",          label: "Kick Scooter",          subcategory: "bicycles", description: "Two-wheeled kick scooter with a tall T-handle, narrow deck and small hard wheels" },
+
+  // -------------------- Trucks --------------------
+  { id: "pickup-truck",          label: "Pickup Truck",          subcategory: "trucks", description: "Full-size pickup truck with a tall crew cab, open rear bed, chrome grille and aggressive off-road tires" },
+  { id: "semi-truck",            label: "Semi Truck",            subcategory: "trucks", description: "Long-haul semi truck with a sleeper cab, tall chrome exhaust stacks and a massive articulated trailer behind" },
+  { id: "dump-truck",            label: "Dump Truck",            subcategory: "trucks", description: "Heavy-duty dump truck with a raised tipping bed, massive off-road tires and yellow construction livery" },
+  { id: "tow-truck",             label: "Tow Truck",             subcategory: "trucks", description: "Tow truck with a hydraulic boom, hook and flat recovery bed, rotating amber warning lights and bold signage" },
+  { id: "delivery-van",          label: "Delivery Van",          subcategory: "trucks", description: "White delivery van with a boxy cargo hold, sliding side door, roof racks and corporate livery decals" },
+  { id: "ice-cream-truck",       label: "Ice Cream Truck",       subcategory: "trucks", description: "Cheerful ice cream truck with pastel paint, a window counter displaying treats, colorful decals and a cone-shaped rooftop ornament" },
+  { id: "food-truck",            label: "Food Truck",            subcategory: "trucks", description: "Stylized food truck with a folding service window, chalkboard menu, string lights and a bright custom wrap" },
+  { id: "box-truck",             label: "Box Truck",             subcategory: "trucks", description: "Medium box truck with a plain rectangular cargo box, roll-up rear door and a forward cab" },
+  { id: "ambulance",             label: "Ambulance",             subcategory: "trucks", description: "Emergency medical ambulance with a tall white box body, red cross and EMS livery, flashing red-and-blue lightbar, side warning lights and a high-visibility chevron pattern across the rear doors" },
+
+  // -------------------- Transit (Bus / Rail / Horse-Drawn) --------------------
+  { id: "city-bus",              label: "City Bus",              subcategory: "transit", description: "Modern articulated city bus with a low floor, sliding doors, destination sign up front and an advertising wrap" },
+  { id: "school-bus",            label: "School Bus",            subcategory: "transit", description: "Classic yellow American school bus with black trim, flashing red stop signs, stop-arm out and black stenciled numbers" },
+  { id: "double-decker",         label: "Double-Decker Bus",     subcategory: "transit", description: "Iconic red double-decker bus with a rounded roof, open staircase inside and destination scroll up front" },
+  { id: "coach-bus",             label: "Coach Bus",             subcategory: "transit", description: "Long-distance coach bus with tinted panoramic windows, luggage bays underneath and streamlined bodywork" },
+  { id: "train",                 label: "Train",                 subcategory: "transit", description: "Modern passenger train with a sleek streamlined nose, panoramic windows and a line of gleaming cars" },
+  { id: "steam-locomotive",      label: "Steam Locomotive",      subcategory: "transit", description: "Black steam locomotive with a tall smokestack puffing steam, a boiler, connecting rods and a coal tender behind" },
+  { id: "bullet-train",          label: "Bullet Train",          subcategory: "transit", description: "High-speed bullet train with an aerodynamic pointed nose, smooth white-and-blue livery and narrow windows" },
+  { id: "subway",                label: "Subway Train",          subcategory: "transit", description: "Stainless-steel subway car with graffiti-resistant panels, sliding doors and rows of fluorescent lights inside" },
+  { id: "tram",                  label: "Tram",                  subcategory: "transit", description: "Classic city tram car with a boxy wooden-framed body, overhead pantograph and rails running beneath" },
+  { id: "stagecoach",            label: "Stagecoach",            subcategory: "transit", description: "Wild-west stagecoach with a wooden body, leaf-spring suspension, roof luggage rack and a team of horses harnessed in front" },
+  { id: "horse-carriage",        label: "Horse-Drawn Carriage",  subcategory: "transit", description: "Ornate horse-drawn carriage with polished wood panels, large spoked wheels and a velvet-upholstered cabin" },
+
+  // -------------------- Aircraft --------------------
+  { id: "airliner",              label: "Airliner",              subcategory: "aircraft", description: "Wide-body commercial airliner with twin jet engines under swept wings, rows of oval windows and a tall swept tail fin" },
+  { id: "biplane",               label: "Biplane",               subcategory: "aircraft", description: "Vintage biplane with two stacked wings connected by struts and wire bracing, an open cockpit and a wooden propeller" },
+  { id: "propeller-plane",       label: "Propeller Plane",       subcategory: "aircraft", description: "Small single-engine propeller plane with a spinning nose prop, high wings, fixed landing gear and a bubble cockpit" },
+  { id: "helicopter",            label: "Helicopter",            subcategory: "aircraft", description: "Utility helicopter with a large main rotor on top, a slim tail boom, skids underneath and a bubble-front cockpit" },
+  { 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: "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" },
+  { id: "drone",                 label: "Drone",                 subcategory: "aircraft", description: "Quadcopter camera drone with four spinning rotors on slim arms, a central body and a gimbaled camera underneath" },
+
+  // -------------------- Watercraft --------------------
+  { id: "yacht",                 label: "Yacht",                 subcategory: "watercraft", description: "Sleek luxury motor yacht with multiple decks, tinted windows, a radar mast and glossy white hull cutting through blue water" },
+  { id: "sailboat",              label: "Sailboat",              subcategory: "watercraft", description: "Graceful sailboat with a tall mast, taut white sails catching the wind and a narrow fiberglass hull" },
+  { id: "speedboat",             label: "Speedboat",             subcategory: "watercraft", description: "Fast powerboat with a pointed deep-V hull, low windshield and a roaring outboard motor kicking up a wake" },
+  { id: "cruise-ship",           label: "Cruise Ship",           subcategory: "watercraft", description: "Massive cruise ship with multiple towering decks, rows of balconies, bright funnels and a pointed bow" },
+  { id: "cargo-ship",            label: "Cargo Ship",            subcategory: "watercraft", description: "Giant container cargo ship stacked high with rainbow-colored shipping containers, a bridge tower at the stern" },
+  { id: "canoe",                 label: "Canoe",                 subcategory: "watercraft", description: "Classic wooden canoe with a pointed bow and stern, a cedar-ribbed interior and a single paddle resting inside" },
+  { id: "kayak",                 label: "Kayak",                 subcategory: "watercraft", description: "Slim plastic kayak with a low profile, enclosed cockpit opening and a double-bladed paddle" },
+  { id: "rowboat",               label: "Rowboat",               subcategory: "watercraft", description: "Small wooden rowboat with flat-bottom planks, oarlocks on the gunwales and two wooden oars" },
+  { id: "jet-ski",               label: "Jet Ski",               subcategory: "watercraft", description: "Stand-up personal watercraft with an aggressive fairing, handlebars, a single seat and a jet-propulsion nozzle" },
+  { id: "submarine",             label: "Submarine",             subcategory: "watercraft", description: "Military submarine with a long cylindrical hull, a conning tower with periscopes and a bulbous bow diving through deep water" },
+  { id: "pirate-ship",           label: "Pirate Ship",           subcategory: "watercraft", description: "Wooden pirate galleon with tall masts, square sails, a figurehead on the bow, cannons along the hull and a tattered black flag" },
+  { id: "hovercraft",            label: "Hovercraft",            subcategory: "watercraft", description: "Air-cushion hovercraft riding on a thick inflated rubber skirt billowing outward, large rear ducted fans for propulsion, a flat boxy passenger cabin on top and capable of skimming over both water and land" },
+
+  // -------------------- Military --------------------
+  { id: "tank",                  label: "Tank",                  subcategory: "military", description: "Heavy battle tank with a long cannon barrel, rotating turret, thick sloped armor and wide continuous tracks" },
+  { id: "humvee",                label: "Humvee",                subcategory: "military", description: "Military Humvee with a wide stance, armored angular bodywork, off-road tires and a roof-mounted turret" },
+  { id: "armored-personnel-carrier", label: "Armored Personnel Carrier", subcategory: "military", description: "Tracked armored personnel carrier with a boxy hull, rear ramp and a small turret up top" },
+  { id: "fighter-jet",           label: "Fighter Jet",           subcategory: "military", description: "Supersonic fighter jet with swept delta wings, a sharp pointed nose, twin tail fins and missiles on wing pylons" },
+  { id: "stealth-bomber",        label: "Stealth Bomber",        subcategory: "military", description: "Flying-wing stealth bomber with a matte black triangular silhouette, no tail fins and faceted radar-absorbing surfaces" },
+  { id: "destroyer",             label: "Destroyer",             subcategory: "military", description: "Sleek naval destroyer with a long grey hull, gun turrets, missile launchers and a radar-bristling superstructure" },
+  { id: "aircraft-carrier",      label: "Aircraft Carrier",      subcategory: "military", description: "Massive aircraft carrier with a flat-top flight deck, island tower with radar arrays and fighter jets parked in rows" },
+
+  // -------------------- Construction --------------------
+  { id: "bulldozer",             label: "Bulldozer",             subcategory: "construction", description: "Yellow construction bulldozer with a huge push blade up front, heavy tracks and a tall exhaust stack" },
+  { id: "excavator",             label: "Excavator",             subcategory: "construction", description: "Hydraulic excavator with an articulated arm, toothed bucket, rotating cab and heavy tracked base" },
+  { id: "crane-truck",           label: "Crane Truck",           subcategory: "construction", description: "Mobile crane truck with a massive telescoping boom extended upward, stabilizer outriggers and a heavy counterweight" },
+  { id: "cement-mixer",          label: "Cement Mixer",          subcategory: "construction", description: "Cement mixer truck with a large rotating drum, chute at the rear and a boxy cab" },
+  { id: "forklift",              label: "Forklift",              subcategory: "construction", description: "Warehouse forklift with twin steel fork tines raised in front, a roll cage over the driver and a compact counterweight rear" },
+  { id: "backhoe",               label: "Backhoe",               subcategory: "construction", description: "Backhoe loader with a front bucket for scooping and a rear articulated arm with a toothed digging bucket" },
+  { id: "tractor",               label: "Tractor",               subcategory: "construction", description: "Farm tractor with large knobby rear tires, smaller front tires, a roof canopy and a towing hitch at the back" },
+
+  // -------------------- Sci-Fi / Fantasy --------------------
+  { id: "spaceship",             label: "Spaceship",             subcategory: "sci-fi", description: "Sleek interstellar spaceship with curved fuselage, glowing engine nozzles, antenna arrays and a command bridge window" },
+  { id: "starfighter",           label: "Starfighter",           subcategory: "sci-fi", description: "Agile single-pilot starfighter with swept wings, laser cannons on the wingtips, a bubble cockpit and glowing thrusters" },
+  { id: "hovercar",              label: "Hovercar",              subcategory: "sci-fi", description: "Futuristic hovercar floating above the ground with no wheels, glowing underside thrusters, seamless bodywork and a curved canopy" },
+  { id: "mech",                  label: "Mech",                  subcategory: "sci-fi", description: "Giant bipedal mech robot with armored plating, hydraulic pistons, a cockpit in the torso and heavy weapons mounted on the arms" },
+  { id: "flying-saucer",         label: "Flying Saucer",         subcategory: "sci-fi", description: "Classic UFO flying saucer with a metallic disc body, glowing porthole lights around the rim and a domed cockpit on top" },
+  { id: "space-shuttle",         label: "Space Shuttle",         subcategory: "sci-fi", description: "Space shuttle orbiter with white delta wings, a black heat-shield underbelly and huge rocket nozzles at the rear" },
+  { id: "rocket",                label: "Rocket",                subcategory: "sci-fi", description: "Tall cylindrical rocket with pointed nose cone, tail fins, booster stages and flames roaring from the engines on launch" },
+  { id: "hoverboard",            label: "Hoverboard",            subcategory: "sci-fi", description: "Futuristic hoverboard floating inches above the ground with glowing underside jets and a sleek single-plank body" },
+] as const
+
+const vehicleById = new Map<string, Vehicle>(VEHICLES.map((v) => [v.id, v]))
+
+export function getVehicle(id: string | undefined | null): Vehicle | undefined {
+  if (!id) return undefined
+  return vehicleById.get(id)
+}
+
+export function getVehicleLabel(id: string | undefined | null, fallback?: string): string {
+  const v = getVehicle(id)
+  if (v) return v.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export const VEHICLE_IDS: ReadonlyArray<string> = VEHICLES.map((v) => v.id)
+
+export const VEHICLE_SUBCATEGORY_LABELS: Readonly<Record<VehicleSubcategory, string>> = {
+  "cars-classic": "Classic Cars",
+  "cars-everyday": "Everyday Cars",
+  "cars-performance": "Performance Cars",
+  motorcycles: "Motorcycles",
+  bicycles: "Bicycles & Human-Powered",
+  trucks: "Trucks",
+  transit: "Bus / Rail / Carriage",
+  aircraft: "Aircraft",
+  watercraft: "Watercraft",
+  military: "Military",
+  construction: "Construction",
+  "sci-fi": "Sci-Fi",
+}
+
+export const VEHICLE_SUBCATEGORY_ORDER: ReadonlyArray<VehicleSubcategory> = [
+  "cars-classic",
+  "cars-everyday",
+  "cars-performance",
+  "motorcycles",
+  "bicycles",
+  "trucks",
+  "transit",
+  "aircraft",
+  "watercraft",
+  "military",
+  "construction",
+  "sci-fi",
+]

package/src/video-analysis-pricing.ts

@@ -0,0 +1,74 @@
+/**
+ * Video-analysis pricing — shared duration-bucket credit model.
+ *
+ * Single source of truth for the video-analysis node's NON-monetary credit
+ * math: duration bucketing, the window-batching constants (also consumed by
+ * the backend workers for real chunking, not just pricing), and the
+ * composite credit-id builder. The route (charge at generate-time), the
+ * worker (re-check + settle), and the frontend node UI (via
+ * `buildVideoAnalysisCreditId` + `/v1/credits/model-cost`) all derive from
+ * these.
+ *
+ * The measured-rate constants and the $-derived `videoAnalysisBucketCredits`
+ * formula live in `backend/src/lib/pricing/video-analysis-cost.ts` (core,
+ * not ee/ — the MCP tool description builder needs them regardless of
+ * edition). They were moved out of this package (published Apache-2.0 on
+ * npm — an irrevocable grant) per the 2026-07-06 public-flip IP audit, S5.
+ *
+ * `VIDEO_ANALYSIS_BUCKET_CREDITS` below is the precomputed OUTPUT of that
+ * backend formula for every (model × bucket) combination — a plain credit
+ * lookup table, not a formula, mirroring the same wire-contract pattern
+ * `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.
+ * A backend test (`video-analysis-cost.test.ts`) cross-checks this table
+ * against the live formula so it can't silently drift.
+ */
+
+export const VIDEO_ANALYSIS_DURATION_BUCKETS = [60, 180, 360, 600] as const
+/** Worker re-check grace: route metadata is integer-rounded, provider durations nominal;
+ *  ffprobe floats run 0.05–2 s over. Zero tolerance fails legit videos at 1:00/3:00/6:00/10:00. */
+export const VIDEO_ANALYSIS_DURATION_TOLERANCE_SEC = 3
+export const VIDEO_ANALYSIS_MAX_DURATION_SEC = 600
+const WINDOW_LEN = 150, WINDOW_STRIDE = 145, WINDOW_OVERLAP = 5
+export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, OVERLAP: WINDOW_OVERLAP, SINGLE_MAX: 180 } as const
+
+/**
+ * Precomputed credit cost per (model, bucket) — the OUTPUT of the backend's
+ * `videoAnalysisBucketCredits` formula, not a formula itself. Regenerate by
+ * running that function for every `VIDEO_ANALYSIS_LLM_MODELS` × duration
+ * bucket combination whenever the underlying rate/token constants change
+ * (backend test guards drift). Keep in sync with
+ * `docs/nodes/processing-video/video-analysis.md`.
+ */
+export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
+  "video-analysis:gemini-3-flash:60s": 1,
+  "video-analysis:gemini-3-flash:180s": 1,
+  "video-analysis:gemini-3-flash:360s": 2,
+  "video-analysis:gemini-3-flash:600s": 3,
+  "video-analysis:gemini-3.1-pro:60s": 2,
+  "video-analysis:gemini-3.1-pro:180s": 3,
+  "video-analysis:gemini-3.1-pro:360s": 7,
+  "video-analysis:gemini-3.1-pro:600s": 11,
+}
+
+export function pickVideoAnalysisBucket(durationSec: number): number {
+  for (const b of VIDEO_ANALYSIS_DURATION_BUCKETS) if (durationSec <= b) return b
+  return VIDEO_ANALYSIS_MAX_DURATION_SEC
+}
+
+export function buildVideoAnalysisCreditId(model: string, durationSec?: number): string {
+  const bucket = durationSec !== undefined && durationSec > 0
+    ? pickVideoAnalysisBucket(Math.min(durationSec, VIDEO_ANALYSIS_MAX_DURATION_SEC))
+    : VIDEO_ANALYSIS_MAX_DURATION_SEC // unknown → ceiling composite (the ONLY silent-ceiling path)
+  return `video-analysis:${model}:${bucket}s`
+}
+
+export function bucketSecondsFromCreditId(creditId: string): number | null {
+  const m = /^video-analysis:.+:(\d+)s$/.exec(creditId)
+  return m ? Number(m[1]) : null
+}
+
+export function videoAnalysisNumWindows(bucketSec: number): number {
+  return bucketSec <= VIDEO_ANALYSIS_WINDOW.SINGLE_MAX ? 1 : 1 + Math.ceil((bucketSec - WINDOW_LEN) / WINDOW_STRIDE)
+}