@nodaro/shared 1.4.2

package/src/scene-helper-types.ts

@@ -0,0 +1,249 @@
+import { z } from "zod"
+import { ImageCriticVerdictSchema } from "./image-critic-types.js"
+import { ShotSpecSchema } from "./scene-node-types.js"
+
+/**
+ * All 10 helpers — 7 text/planning helpers shipped in Phase 1B.3 +
+ * 3 vision-keyframe helpers activated in Phase 1C.1.
+ * Names match the §6.11 spec sub-section labels (URL-safe form).
+ */
+export const SCENE_HELPER_NAMES = [
+  // Text/planning-only — shipped in 1B.3
+  "audit_prompt",
+  "improve_prompt",
+  "generate_motion",
+  "optimize_for_model",
+  "add_broll",
+  "bridge_to_next_scene",
+  "anchor_scene_style",
+  // Vision-keyframe — activated in Phase 1C.1
+  "audit_images",
+  "fix_continuity",
+  "validate_match_cut",
+] as const
+
+export const SceneHelperNameSchema = z.enum(SCENE_HELPER_NAMES)
+export type SceneHelperName = z.infer<typeof SceneHelperNameSchema>
+
+/**
+ * UI-gating set used by `scene-helper-buttons.tsx` to render active vs disabled
+ * buttons. Phase 1C.1 promoted the 3 vision-keyframe helpers from disabled →
+ * active; the constant name is preserved for compat (it remains "the set of
+ * helpers currently shipped"), and {@link ACTIVE_SCENE_HELPERS} is a clearer
+ * alias for new code.
+ */
+export const HELPERS_SHIPPED_IN_1B3: ReadonlySet<SceneHelperName> = new Set([
+  "audit_prompt",
+  "improve_prompt",
+  "generate_motion",
+  "optimize_for_model",
+  "add_broll",
+  "bridge_to_next_scene",
+  "anchor_scene_style",
+  // Phase 1C.1 — activated
+  "audit_images",
+  "fix_continuity",
+  "validate_match_cut",
+])
+
+/** Cleaner-named alias for {@link HELPERS_SHIPPED_IN_1B3}. */
+export const ACTIVE_SCENE_HELPERS = HELPERS_SHIPPED_IN_1B3
+
+// ─── 6.11.2 Audit Prompt — Haiku, text-only ────────────────────────────────────
+
+export const AuditPromptIssueSchema = z.object({
+  shot_id: z.string(),
+  severity: z.enum(["blocking", "warning", "info"]),
+  issue_type: z.enum([
+    "contradiction",
+    "missing_beat",
+    "off_format",
+    "camera_motion_mismatch",
+  ]),
+  message: z.string(),
+  suggested_fix: z.string(),
+})
+
+export const AuditPromptResultSchema = z.object({
+  scene_id: z.string(),
+  ok: z.boolean(),
+  issues_per_shot: z.array(AuditPromptIssueSchema),
+  scene_level_notes: z.string().max(400),
+})
+export type AuditPromptResult = z.infer<typeof AuditPromptResultSchema>
+
+// ─── 6.11.3 Improve Prompt — Sonnet, target enum ────────────────────────────────
+
+export const ImprovePromptInputSchema = z.object({
+  shot_ids: z.array(z.string()).min(1),
+  field_targets: z.array(z.enum(["action", "motion_prompt", "dialogue"])).min(1),
+})
+export type ImprovePromptInput = z.infer<typeof ImprovePromptInputSchema>
+
+export const ImprovePromptResultSchema = z.object({
+  scene_id: z.string(),
+  shots: z.array(
+    z.object({
+      shot_id: z.string(),
+      action: z.string().max(300).optional(),
+      motion_prompt: z.string().max(200).optional(),
+      dialogue_line: z.string().max(200).optional(),
+      reasoning: z.string().max(300),
+    }),
+  ),
+})
+export type ImprovePromptResult = z.infer<typeof ImprovePromptResultSchema>
+
+// ─── 6.11.5 Generate Motion — Haiku, fills motion_prompt ───────────────────────
+
+export const GenerateMotionInputSchema = z.object({
+  shot_ids: z.array(z.string()).min(1),
+})
+
+export const GenerateMotionResultSchema = z.object({
+  scene_id: z.string(),
+  shots: z.array(
+    z.object({
+      shot_id: z.string(),
+      motion_prompt: z.string().max(200),
+    }),
+  ),
+})
+export type GenerateMotionResult = z.infer<typeof GenerateMotionResultSchema>
+
+// ─── 6.11.6 Optimize for Model — Sonnet, rewrites for new prompting_style ─────
+
+export const OptimizeForModelInputSchema = z.object({
+  target_model: z.string(),
+})
+
+export const OptimizeForModelResultSchema = z.object({
+  scene_id: z.string(),
+  target_model: z.string(),
+  shots: z.array(
+    z.object({
+      shot_id: z.string(),
+      action: z.string().max(300),
+      motion_prompt: z.string().max(200),
+    }),
+  ),
+  rationale: z.string().max(300),
+})
+export type OptimizeForModelResult = z.infer<typeof OptimizeForModelResultSchema>
+
+// ─── 6.11.7 Add B-Roll — Sonnet, proposes new shots ────────────────────────────
+
+export const AddBRollResultSchema = z.object({
+  scene_id: z.string(),
+  candidates: z
+    .array(
+      z.object({
+        proposed_insert_after_shot_id: z.string(),
+        insert_kind: z.enum(["reaction_shot", "cutaway", "establishing", "transition"]),
+        shot: ShotSpecSchema,
+        rationale: z.string().max(200),
+      }),
+    )
+    .min(1)
+    .max(4),
+  scene_duration_delta: z.number(),
+})
+export type AddBRollResult = z.infer<typeof AddBRollResultSchema>
+
+// ─── 6.11.10 Bridge to Next Scene — Sonnet, generates bridge_image_prompt ──────
+
+export const BridgeToNextSceneInputSchema = z.object({
+  target_shot_id: z.string(),
+})
+
+export const BridgeToNextSceneResultSchema = z.object({
+  scene_id: z.string(),
+  target_shot_id: z.string(),
+  bridge_image_prompt: z.string().max(500),
+  reasoning: z.string().max(300),
+})
+export type BridgeToNextSceneResult = z.infer<typeof BridgeToNextSceneResultSchema>
+
+// ─── 6.11.11 Anchor Scene Style — Sonnet plans + image_model generates ─────────
+
+export const AnchorSceneStyleResultSchema = z.object({
+  scene_id: z.string(),
+  anchor_prompt: z.string().max(800),
+  asset_id: z.string().uuid(),
+  asset_url: z.string().url(),
+  credits_spent: z.number(),
+})
+export type AnchorSceneStyleResult = z.infer<typeof AnchorSceneStyleResultSchema>
+
+// ─── 6.11.12 Audit Images — Sonnet vision, per-shot keyframe critic loop ──────
+//
+// Runs `runImageCritic` over every shot's keyframe_url in the scene (no body
+// inputs). Aggregates verdicts into a per-shot issue list. `ok` rolls up to
+// scene-level: false when any shot has a blocking issue.
+
+export const AuditImagesShotEntrySchema = z.object({
+  shot_id: z.string(),
+  ok: z.boolean(),
+  /** Verdict body — empty when the shot has no `keyframe_url` yet (skipped). */
+  verdict: ImageCriticVerdictSchema.nullable(),
+  /** True when the shot had no keyframe to audit. */
+  skipped: z.boolean(),
+})
+export type AuditImagesShotEntry = z.infer<typeof AuditImagesShotEntrySchema>
+
+export const AuditImagesResultSchema = z.object({
+  scene_id: z.string(),
+  ok: z.boolean(),
+  shot_issues: z.array(AuditImagesShotEntrySchema),
+  /** Roll-up summary suitable for in-app display ("3 of 5 shots have issues"). */
+  summary: z.string().max(400),
+})
+export type AuditImagesResult = z.infer<typeof AuditImagesResultSchema>
+
+// ─── 6.11.13 Fix Continuity — Sonnet vision + i2i regen ──────────────────────
+//
+// Body: { target_shot_id }. Runs Image Critic against the target shot's
+// keyframe with its PRIOR shot's `last_frame_url`. If a `continuity_break`
+// blocking issue is found, regenerates the keyframe via
+// `pipelineGenerateImage` using the prior last_frame as a strong reference,
+// and persists the new keyframe_url back to the scene's shots[target].
+
+export const FixContinuityInputSchema = z.object({
+  target_shot_id: z.string(),
+})
+export type FixContinuityInput = z.infer<typeof FixContinuityInputSchema>
+
+export const FixContinuityResultSchema = z.object({
+  scene_id: z.string(),
+  target_shot_id: z.string(),
+  action: z.enum(["regenerated", "no_action_needed"]),
+  critic_verdict: ImageCriticVerdictSchema,
+  /** Populated only when `action === "regenerated"`. */
+  new_keyframe_url: z.string().url().optional(),
+  new_keyframe_asset_id: z.string().uuid().optional(),
+})
+export type FixContinuityResult = z.infer<typeof FixContinuityResultSchema>
+
+// ─── 6.11.14 Validate Match Cut — Sonnet vision ──────────────────────────────
+//
+// Body: { target_shot_id }. Loads the target shot's keyframe + the NEXT shot's
+// keyframe and asks the Image Critic to evaluate the match-cut quality.
+// Returns a `match_strength` summary + the critic's full verdict. Returns 400
+// `not_a_match_cut` from the route layer when `shot_intent.is_match_cut`
+// is false on the target shot (pre-flight check before credit reservation).
+
+export const ValidateMatchCutInputSchema = z.object({
+  target_shot_id: z.string(),
+})
+export type ValidateMatchCutInput = z.infer<typeof ValidateMatchCutInputSchema>
+
+export const ValidateMatchCutResultSchema = z.object({
+  scene_id: z.string(),
+  /** Tuple [shot_id_a, shot_id_b] — the target shot + the next shot. */
+  shot_pair: z.tuple([z.string(), z.string()]),
+  match_strength: z.enum(["strong", "moderate", "weak", "break"]),
+  critic_verdict: ImageCriticVerdictSchema,
+  /** Optional follow-up actions the user could take (free-form, ≤300 chars). */
+  suggested_adjustments: z.string().max(300),
+})
+export type ValidateMatchCutResult = z.infer<typeof ValidateMatchCutResultSchema>

package/src/scene-node-types.ts

@@ -0,0 +1,281 @@
+import { z } from "zod"
+
+// SceneInputMode lives in model-constants.ts — re-export so all SceneNodeData
+// consumers import from one place.
+import { SceneInputModeSchema } from "./model-constants.js"
+
+/**
+ * TransitionType — the set of allowed shot-to-shot transitions emitted by the
+ * Editor LLM stage. Single source of truth shared across:
+ *   - ShotSpec.cut_decision.transition_to_next (this file)
+ *   - backend/src/ee/pipelines/llms/editor.ts (LLM result schema)
+ *   - backend/src/ee/pipelines/services/pipeline-final-merge.ts
+ *   - backend/src/ee/pipelines/freecut-export.ts
+ */
+export const TransitionTypeSchema = z.enum([
+  "hard_cut",
+  "dissolve",
+  "match_cut",
+  "overlap",
+])
+export type TransitionType = z.infer<typeof TransitionTypeSchema>
+
+/**
+ * ShotSpec — one shot inside a SceneNodeData.
+ * Mirrors Architecture §6.9.1 + v4.1 Method-2/3/5/7/8/10 field additions.
+ */
+export const ShotSpecSchema = z.object({
+  shot_id: z.string().regex(/^shot_\d{2,3}$/, "shot_id must be shot_NN or shot_NNN"),
+  camera: z.object({
+    shot_type: z.enum([
+      "wide", "medium", "close_up", "extreme_close_up", "pov", "over_shoulder",
+    ]),
+    angle: z.enum(["eye_level", "low", "high", "dutch", "birds_eye"]),
+    motion: z.enum(["static", "pan", "tilt", "dolly", "tracking", "handheld"]),
+  }),
+  shot_intensity_kind: z.enum([
+    "establishing_shot", "action_shot", "dialogue_shot",
+    "reaction_shot", "climactic_shot", "transition_shot",
+  ]),
+
+  action: z.string().max(300),
+  dialogue_line: z.string().max(200).nullable(),
+  duration_seconds: z.number().min(0.3).max(8),
+
+  motion_prompt: z.string().max(200),
+
+  // Internal continuity within this scene
+  start_state: z.string().max(200),
+  end_state: z.string().max(200),
+  continuity_with_previous: z.string().max(200).nullable(),
+
+  // Provider-neutral intent — engine maps to provider-specific directives at call time
+  shot_intent: z.object({
+    needs_multishot_reference: z.boolean().default(false),
+    is_loopable: z.boolean().default(false),
+    needs_music_suppression: z.boolean().default(true),
+    is_match_cut: z.boolean().default(false), // v4.1 Method 7
+  }),
+
+  visual_keyframe_prompt: z.string().min(1).max(1000),
+
+  // v4.1 Method 2 — pre-planned paired keyframes (required when shot_input_mode='first_last_frame')
+  end_keyframe_prompt: z.string().max(1000).optional(),
+
+  // v4.1 Method 3 — video continuation (this shot extends extends_shot_id's clip)
+  extends_shot_id: z.string().optional(),
+
+  // v4.1 Method 5 — i2i bridge applied to prior last_frame before this shot animates
+  bridge_image_prompt: z.string().max(500).optional(),
+
+  // v4.1 Method 8 — sparse keyframes for interpolation models
+  interpolation_keyframes: z
+    .array(
+      z.object({
+        timestamp_sec: z.number().nonnegative(),
+        prompt: z.string().min(10).max(1000),
+      }),
+    )
+    .max(16)
+    .optional(),
+
+  // Phase 1C.3 Method 8 — generated R2 URLs of the sub-keyframes, one per
+  // `interpolation_keyframes[N].prompt`. Stage 6 writes these BEFORE Stage 7
+  // runs so the animate step can pass them to the interpolation provider.
+  // Length MUST equal `interpolation_keyframes.length` when populated.
+  interpolation_keyframe_urls: z.array(z.string().url()).max(16).optional(),
+
+  // v4.1 Method 10 — parametric 3D camera path
+  camera_path_directive: z
+    .object({
+      path_kind: z.enum(["orbit", "dolly", "crane", "arc", "reveal"]),
+      parameters: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+
+  // ─── Execution state (engine writes; null on planning) ─────────────────────
+  // Phase 1C.1: per-shot execution state lands directly on the shot record so
+  // the SceneNode internal pipeline + continuity chain can read/write them in
+  // one place. All optional — planning-time ShotSpec carries none of these.
+
+  // Stage 6 (scene_images) writes these after keyframe generation.
+  keyframe_asset_id: z.string().uuid().optional(),
+  keyframe_url: z.string().url().optional(),
+
+  // Stage 7 (animate_audio_edit) step 3 (animate) writes these after the
+  // image-to-video / text-to-video call succeeds.
+  video_asset_id: z.string().uuid().optional(),
+  video_url: z.string().url().optional(),
+
+  // Stage 7 step 3 (extract_frame chain — sequential mode only) writes these
+  // after each shot's last frame is extracted at duration - 0.1s. Used by the
+  // next shot's continuity chain (Method 1).
+  last_frame_asset_id: z.string().uuid().optional(),
+  last_frame_url: z.string().url().optional(),
+
+  // Stage 7 step 4 (speech) writes these per shot with dialogue_line.
+  audio_asset_id: z.string().uuid().optional(),
+  audio_url: z.string().url().optional(),
+
+  // Stage 7 step 5 (lip-sync) writes these when lipsync_enabled and the shot
+  // has dialogue. The lipsynced clip replaces the shot's video_url in the
+  // step-6 combine call.
+  lipsynced_asset_id: z.string().uuid().optional(),
+  lipsynced_url: z.string().url().optional(),
+
+  // Phase 1C.3 — bridged frame (Method 5). Defensive placeholder; never set
+  // in 1C.1 (continuity.applyContinuityToStartFrame already reads this).
+  bridged_frame_url: z.string().url().optional(),
+
+  // Phase 1D.1 Method 7 — set true when the user accepts a MatchCutCritic
+  // 'break' verdict for this shot's pair. Stage 6 reads this to know the
+  // break is resolved and the scene can advance to Stage 7.
+  accepted_match_cut_break: z.boolean().optional(),
+
+  // ─── Phase 1C.2 — dialogue + editor cut metadata ───────────────────────────
+  // All optional; planning-time ShotSpec carries none of these. Populated by
+  // the Editor LLM (Stage 7) and the silent-cut-preview sub-gate handler.
+
+  // True when `dialogue_line` is non-null AND the speech generator produced
+  // an audio track. The Editor LLM uses this to gate cut-in / cut-out into
+  // the dialogue_no_cut_zone (Method 5.13.1 — never trim a syllable).
+  has_dialogue: z.boolean().default(false),
+
+  // Measured length of the per-shot speech audio (Stage 7 step 4 writes this).
+  // Separate from `duration_seconds` (the planning intent) — the actual
+  // recording can run longer/shorter than the spec.
+  actual_audio_duration_sec: z.number().optional(),
+
+  // Inclusive [start, end] window (seconds, relative to the shot's video clip)
+  // during which the Editor LLM MUST NOT cut. Computed from
+  // `actual_audio_duration_sec` + small padding by the Editor LLM stage.
+  // null when has_dialogue=false (no zone to protect).
+  dialogue_no_cut_zone: z
+    .object({ start: z.number(), end: z.number() })
+    .nullable()
+    .optional(),
+
+  // Editor LLM output (Phase 1C.2). Populated by the Editor LLM stage; the
+  // silent-cut-preview sub-gate may patch it via user-applied overrides.
+  // Mirrors the editor_decisions audit row shape (migration 135).
+  cut_decision: z
+    .object({
+      in_offset_sec: z.number().min(0).max(2).default(0),
+      out_offset_sec: z.number().min(0).max(2).default(0),
+      transition_to_next: TransitionTypeSchema,
+      transition_duration_sec: z.number().min(0).max(2).optional(),
+      beat_snap_seconds: z.number().nullable().optional(),
+    })
+    .optional(),
+})
+export type ShotSpec = z.infer<typeof ShotSpecSchema>
+
+/**
+ * AssetRef — minimal asset reference shape for execution-state fields.
+ * Phase 1B.2 doesn't populate these (Stage 6+ work) but the schema must accept them
+ * for parse round-trips.
+ */
+export const AssetRefSchema = z.object({
+  asset_id: z.string().uuid(),
+  url: z.string().url(),
+})
+export type AssetRef = z.infer<typeof AssetRefSchema>
+
+/**
+ * SceneNodeData — what the Scene Director emits, what the SceneNode renders,
+ * what the engine persists on `pipeline_entities.metadata` (for entity_type='scene').
+ * Mirrors Architecture §6.9.1.
+ */
+export const SceneNodeDataSchema = z.object({
+  // Plan fields (Scene Director fills; user editable)
+  scene_index: z.number().int().min(1),
+  description: z.string().max(500),
+  emotional_beat: z.string(),
+  duration_seconds: z.number().positive(),
+
+  // Input mode — gates which video_model values are valid
+  shot_input_mode: SceneInputModeSchema,
+
+  // Echoed inputs (Scene Director copies from SceneSpec)
+  cast_keys: z.array(z.string()),
+  location_key: z.string(),
+  object_keys: z.array(z.string()),
+  continuity_from_prev: z.enum(["hard_cut", "match_last_frame", "dissolve"]),
+
+  // Model picks
+  image_model: z.string(),
+  video_model: z.string(),
+
+  // Shot list
+  shots: z.array(ShotSpecSchema).min(1).max(8),
+
+  // v4.1 Method 6 — pre-generated master keyframe (set in 1C; Phase 1B.2 always null)
+  scene_anchor_keyframe: AssetRefSchema.nullable().default(null),
+
+  // Optional per-scene style override
+  style_directives: z
+    .object({
+      visualStyle: z.string().optional(),
+      colorPalette: z.string().optional(),
+      lighting: z.string().optional(),
+      cameraLanguage: z.string().optional(),
+      avoid: z.string().optional(),
+    })
+    .partial()
+    .optional(),
+
+  // Execution state (engine writes; null on planning — Phase 1C populates)
+  generated_keyframes: z.array(AssetRefSchema).default([]),
+  generated_clips: z.array(AssetRefSchema).default([]),
+  composite_video: AssetRefSchema.nullable().default(null),
+  last_frame: AssetRefSchema.nullable().default(null),
+  scene_audio_track: AssetRefSchema.nullable().default(null),
+
+  // Phase 1C.1 Stage 7 result — composite video assembled from the per-shot
+  // clips inside this scene. Optional flat fields kept alongside
+  // `composite_video` (AssetRefSchema) so consumers can read either shape.
+  composite_video_asset_id: z.string().uuid().optional(),
+  composite_video_url: z.string().url().optional(),
+})
+export type SceneNodeData = z.infer<typeof SceneNodeDataSchema>
+
+/**
+ * SceneMetadataSchema — what gets persisted on `pipeline_entities.metadata`
+ * for entity_type='scene'. The discriminated union in pipeline-types.ts already has
+ * Character/Object/Location entries from 1A; this Phase 1B.2 task extends it.
+ */
+export const SceneMetadataSchema = z.object({
+  entity_type: z.literal("scene"),
+  scene_id: z.string(),
+  shot_ids: z.array(z.string()),
+  emotional_beat: z.string(),
+  // Canonical pointer to the canvas SceneNode (workflows.nodes[i].id)
+  scene_node_id: z.string(),
+  // Opt-in Explode tracking (Phase 2 — null in 1B.2)
+  exploded_to_workflow_id: z.string().uuid().nullable().default(null),
+  // Phase 1B.2 stashes the full SceneNodeData here so the orchestrator + panel UI
+  // don't have to re-resolve it from canvas state.
+  // Optional because Stage 5 inserts the entity row BEFORE the Scene Director runs
+  // (status='pending' / 'generating') — the field lands after the Scene Director succeeds.
+  scene_node_data: SceneNodeDataSchema.optional(),
+})
+export type SceneMetadata = z.infer<typeof SceneMetadataSchema>
+
+/**
+ * MatchCutVerdictSchema — Phase 1D.1 Method 7.
+ *
+ * What Stage 6 persists in `pipeline_stages.output.match_cut_verdicts` for
+ * each match-cut shot pair. Keyed by the TARGET shot_id (the shot with
+ * `shot_intent.is_match_cut=true`). The pair is [target, next-shot].
+ *
+ * Stage 6 runs `runValidateMatchCut` for every eligible target and stores
+ * one MatchCutVerdict per pair. The `pendingBreaks` list in the orchestrator
+ * result identifies shots the user must explicitly accept before Stage 7 runs.
+ */
+export const MatchCutVerdictSchema = z.object({
+  shot_pair: z.tuple([z.string(), z.string()]),
+  match_strength: z.enum(["strong", "moderate", "weak", "break"]),
+  suggested_adjustments: z.string().max(300),
+  checked_at: z.string().datetime(),
+})
+export type MatchCutVerdict = z.infer<typeof MatchCutVerdictSchema>

package/src/scraper-actors.ts

@@ -0,0 +1,57 @@
+export const SCRAPER_ACTOR_IDS = [
+  "content-crawler",
+  "google-search",
+  "instagram",
+  "tiktok",
+  "rss",
+] as const
+
+export type ScraperActorId = (typeof SCRAPER_ACTOR_IDS)[number]
+
+export const SCRAPER_ACTOR_LABELS: Record<ScraperActorId, string> = {
+  "content-crawler": "Website Content (Markdown)",
+  "google-search":   "Google Search",
+  "instagram":       "Instagram",
+  "tiktok":          "TikTok",
+  "rss":             "RSS Feed",
+}
+
+/** Credit costs per composite SKU — must stay in sync with STATIC_CREDIT_COSTS in backend. */
+export const SCRAPER_CREDIT_COSTS: Record<string, number> = {
+  "web-scrape": 2,
+  "web-scrape:google-search": 3,
+  "web-scrape:content-crawler": 1,
+  "web-scrape:content-crawler:site": 5,
+  "web-scrape:instagram": 1,
+  "web-scrape:tiktok": 1,
+  "web-scrape:rss": 1,
+}
+
+export function isScraperActor(value: unknown): value is ScraperActorId {
+  return typeof value === "string" && (SCRAPER_ACTOR_IDS as readonly string[]).includes(value)
+}
+
+export interface ScraperCreditInput {
+  actor: ScraperActorId
+  mode?: "page" | "site"
+}
+
+export function buildScraperCreditId(input: ScraperCreditInput): string {
+  if (input.actor === "content-crawler") {
+    const mode = input.mode ?? "page"
+    return mode === "site" ? "web-scrape:content-crawler:site" : "web-scrape:content-crawler"
+  }
+  return `web-scrape:${input.actor}`
+}
+
+/**
+ * Resolve the credit identifier from an unvalidated request body.
+ * Falls back to a fixed default SKU (google-search) on missing/invalid actor
+ * so misrouted requests reserve a known mid-tier price, not the max-cost tier.
+ */
+export function resolveScraperCreditId(body: unknown): string {
+  const raw = body as { actor?: unknown; mode?: unknown } | undefined
+  if (!raw || !isScraperActor(raw.actor)) return "web-scrape:google-search"
+  const mode = raw.mode === "site" ? "site" : "page"
+  return buildScraperCreditId({ actor: raw.actor, mode })
+}

package/src/scraper-output-schemas.ts

@@ -0,0 +1,25 @@
+import type { ScraperActorId } from "./scraper-actors.js"
+
+/**
+ * Scalar fields exposed in the Extract Field dropdown when the direct
+ * upstream is a web-scrape node. Nested / non-scalar fields (authorMeta,
+ * musicMeta) are intentionally omitted — users access them via the
+ * "Custom path..." option.
+ *
+ * content-crawler paths are pre-dotted (`pages.url`, `pages.markdown`)
+ * because its root shape is `{ pages: [...] }`, not a top-level array.
+ */
+export const SCRAPER_OUTPUT_FIELDS: Record<ScraperActorId, readonly string[]> = {
+  "content-crawler": ["pages.url", "pages.markdown"],
+  "google-search":   ["title", "url", "description"],
+  "instagram":       [
+    "url", "shortCode", "caption", "displayUrl", "videoUrl",
+    "timestamp", "likesCount", "commentsCount", "ownerUsername", "type",
+    "childPosts",
+  ],
+  "tiktok":          [
+    "id", "webVideoUrl", "videoUrl", "text", "createTime",
+    "diggCount", "shareCount", "playCount", "commentCount",
+  ],
+  "rss":             ["title", "url", "description", "pubDate", "guid"],
+} as const

package/src/seasons.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical catalog of seasons.
+ *
+ * 4 universal seasonal labels — used by the Location Studio's Seasons tab
+ * and (in the future) by any season-picker parameter node. Independent of
+ * lighting (time-of-day), atmosphere (weather), and color/look.
+ *
+ * Northern-hemisphere reference is implicit. Promp t hints describe the
+ * visual hallmarks of each season so downstream generators reproduce them
+ * faithfully across diverse settings (interior, exterior, character, etc.).
+ */
+
+export interface Season {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const SEASONS: ReadonlyArray<Season> = [
+  {
+    id: "spring",
+    label: "Spring",
+    description: "Fresh growth, blossoms, mild weather",
+    promptHint: "spring season, fresh new growth with green buds and emerging foliage, blossoming flowers, mild fresh air, soft directional sunlight, occasional light rain, pastel color palette of pale greens and pinks",
+  },
+  {
+    id: "summer",
+    label: "Summer",
+    description: "Full bloom, warm light, lush green",
+    promptHint: "summer season, lush full foliage in deep saturated greens, warm bright sunlight with strong overhead sun, deep shadows, vibrant warm color palette, clear blue skies or scattered cumulus clouds",
+  },
+  {
+    id: "autumn",
+    label: "Autumn",
+    description: "Falling leaves, warm amber palette",
+    promptHint: "autumn season, foliage transitioning to warm amber tones — red, orange, yellow, and rust — falling leaves drifting on the breeze, soft golden directional light, crisp cool air with low sun angles",
+  },
+  {
+    id: "winter",
+    label: "Winter",
+    description: "Bare branches, snow, cool palette",
+    promptHint: "winter season, bare branches against a cold sky, snow accumulation on every surface, breath visible in cold air, desaturated cool color palette of blues and grays with isolated warm artificial light sources",
+  },
+]