peachsim 0.1.1644 → 0.1.1653

package/src/screenshots/screenshotContract.ts

@@ -0,0 +1,971 @@
+import { isRecord } from '../is-record.ts'
+import {
+  BACKGROUND_PRESET_NAMES,
+  POSE_PRESET_NAMES,
+  SCREENSHOT_CANVAS_NAMES,
+  TEXT_PRESET_NAMES,
+  type BackgroundPresetName,
+  type PosePresetName,
+  type ScreenshotCanvasName,
+  type TextPresetName,
+} from './preset-names.ts'
+import type { DeviceModel } from '../device-catalog.ts'
+
+export {
+  BACKGROUND_PRESET_NAMES,
+  POSE_PRESET_NAMES,
+  SCREENSHOT_CANVAS_NAMES,
+  TEXT_PRESET_NAMES,
+  type BackgroundPresetName,
+  type PosePresetName,
+  type ScreenshotCanvasName,
+  type TextPresetName,
+}
+
+// shared serialized scene contract, also used by the optional 3d renderer.
+export const THREE_MODE_SETTING_IDS = [
+  'none',
+  'room',
+  'window-wall',
+  'white-backdrop',
+  'cyclorama',
+  'terrain',
+] as const
+
+export type ThreeModeSetting = (typeof THREE_MODE_SETTING_IDS)[number]
+
+export const THREE_WINDOW_LIGHT_OFFSET_RANGE: readonly [number, number] = [-3, 3]
+
+export function isThreeModeSetting(value: unknown): value is ThreeModeSetting {
+  return typeof value === 'string' && THREE_MODE_SETTING_IDS.some((id) => id === value)
+}
+
+export interface CanvasPreset {
+  name: ScreenshotCanvasName
+  label: string
+  width: number
+  height: number
+  store: 'apple' | 'google'
+  deviceModel?: DeviceModel
+}
+
+export interface GradientStop {
+  offset: number
+  color: string
+}
+
+export interface BackgroundSpec {
+  type: 'solid' | 'gradient'
+  color?: string
+  direction?: number
+  stops?: GradientStop[]
+  glow?: string
+}
+
+export interface FrameShadowSpec {
+  color: string
+  blur: number
+  spread: number
+  opacity: number
+}
+
+export const SCREENSHOT_CANVASES: Record<ScreenshotCanvasName, CanvasPreset> = {
+  'iphone-6-9': {
+    name: 'iphone-6-9',
+    label: 'iPhone 6.7"',
+    width: 1284,
+    height: 2778,
+    store: 'apple',
+  },
+  'iphone-6-1': {
+    name: 'iphone-6-1',
+    label: 'iPhone 6.5"',
+    width: 1242,
+    height: 2688,
+    store: 'apple',
+  },
+  'ipad-pro-13': {
+    name: 'ipad-pro-13',
+    label: 'iPad Pro 13-inch',
+    width: 2064,
+    height: 2752,
+    store: 'apple',
+    deviceModel: 'ipad-pro-13',
+  },
+  'android-phone': {
+    name: 'android-phone',
+    label: 'Google Play phone',
+    width: 1080,
+    height: 1920,
+    store: 'google',
+  },
+  'android-tablet-7': {
+    name: 'android-tablet-7',
+    label: 'Google Play 7" tablet',
+    width: 1200,
+    height: 1920,
+    store: 'google',
+  },
+  'android-tablet-10': {
+    name: 'android-tablet-10',
+    label: 'Google Play 10" tablet',
+    width: 1600,
+    height: 2560,
+    store: 'google',
+  },
+}
+
+export const BACKGROUND_PRESETS: Record<BackgroundPresetName, BackgroundSpec> = {
+  dark: {
+    type: 'gradient',
+    direction: 180,
+    glow: '#4caeff',
+    stops: [
+      { offset: 0, color: '#111827' },
+      { offset: 40, color: '#101725' },
+      { offset: 100, color: '#06080d' },
+    ],
+  },
+  cyan: {
+    type: 'gradient',
+    direction: 180,
+    glow: '#25c3ec',
+    stops: [
+      { offset: 0, color: '#1b465c' },
+      { offset: 32, color: '#122336' },
+      { offset: 100, color: '#05070b' },
+    ],
+  },
+  gold: {
+    type: 'gradient',
+    direction: 180,
+    glow: '#ffc25a',
+    stops: [
+      { offset: 0, color: '#3b2f1a' },
+      { offset: 34, color: '#18140d' },
+      { offset: 100, color: '#050505' },
+    ],
+  },
+  red: {
+    type: 'gradient',
+    direction: 180,
+    glow: '#ff6178',
+    stops: [
+      { offset: 0, color: '#3e1018' },
+      { offset: 35, color: '#17080c' },
+      { offset: 100, color: '#050405' },
+    ],
+  },
+}
+
+export const DEFAULT_FRAME_SHADOW: FrameShadowSpec = {
+  color: '#25c3ec',
+  blur: 120,
+  spread: 52,
+  opacity: 0.34,
+}
+
+export const DEFAULT_FRAME_STYLE: DeviceModel = 'iphone-17-pro'
+
+// stage / canvas-rect FLIP animation. used by DeviceFrame.tsx for the live
+// stage tween and by the composer's compose.ts for parity.
+export const SCREENSHOT_MODE_ANIM = {
+  durationMs: 250,
+  easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+} as const
+
+// css clamp() rules for text layers. live mode uses container queries keyed
+// off the floating canvas rect; the composer writes the same clamp() rules
+// in its exported html so the two painters render matching headlines at
+// matching canvas sizes.
+export const SCREENSHOT_TEXT_CLAMP = {
+  headline: 'clamp(2rem, 5.6cqi, 5.5rem)',
+  subhead: 'clamp(1rem, 2.4cqi, 2.25rem)',
+} as const
+
+// safe-area percentages inside the canvas rect — reserves headroom and side
+// padding for the text layer so the device frame never crowds the edges.
+export const SCREENSHOT_TEXT_SAFE_AREA = {
+  topPct: 8,
+  sidePct: 7,
+  bottomGapPct: 4,
+} as const
+
+// ─── screenshot project config (live multi-frame mode) ───────────────────
+//
+// a project carries one screenshot composition: a target store/canvas
+// preset, the device to pose, and an ordered list of frame slides. each
+// slide owns its own copy/theme/pose so the App-Store strip can show
+// different posed screens side by side. the closed plugin-screenshot owns
+// the visual mapping for ScreenshotThemeName; the name union lives here so
+// the engine projects store can persist it without importing the plugin.
+
+// the background is a two-stop vertical gradient: the user picks a top
+// color and a bottom color independently (two flyouts in the rail). the
+// palette includes white + a grey ramp so a screenshot can stay basically
+// grey, plus the brand hues.
+export type ScreenshotBgColorName =
+  | 'white'
+  | 'gray-light'
+  | 'gray'
+  | 'gray-dark'
+  | 'slate'
+  | 'black'
+  | 'cyan'
+  | 'blue'
+  | 'teal'
+  | 'green'
+  | 'lime'
+  | 'gold'
+  | 'orange'
+  | 'coral'
+  | 'red'
+  | 'berry'
+  | 'magenta'
+
+export interface ScreenshotBgColor {
+  name: ScreenshotBgColorName
+  value: string
+}
+
+export const SCREENSHOT_BG_COLORS: ScreenshotBgColor[] = [
+  { name: 'white', value: '#ffffff' },
+  { name: 'gray-light', value: '#d1d5db' },
+  { name: 'gray', value: '#6b7280' },
+  { name: 'gray-dark', value: '#3b4350' },
+  { name: 'slate', value: '#2a3644' },
+  { name: 'black', value: '#000000' },
+  { name: 'cyan', value: '#25c3ec' },
+  { name: 'blue', value: '#3f7cff' },
+  { name: 'teal', value: '#1fc7b4' },
+  { name: 'green', value: '#42c95d' },
+  { name: 'lime', value: '#92d21b' },
+  { name: 'gold', value: '#f5c518' },
+  { name: 'orange', value: '#ff912e' },
+  { name: 'coral', value: '#ff6f5b' },
+  { name: 'red', value: '#ff4f6f' },
+  { name: 'berry', value: '#d054ff' },
+  { name: 'magenta', value: '#ff4eb8' },
+]
+
+const BG_COLOR_MAP: Record<string, string> = Object.fromEntries(
+  SCREENSHOT_BG_COLORS.map((c) => [c.name, c.value]),
+)
+
+export function resolveBgColorValue(name: string): string {
+  return BG_COLOR_MAP[name] ?? BG_COLOR_MAP.gray
+}
+
+export interface ScreenshotBackgroundStyles {
+  background: string
+  foreground: string
+  eyebrow: string
+  subtitle: string
+  placeholder: string
+}
+
+export const DEFAULT_BG_TOP: ScreenshotBgColorName = 'gray'
+
+export const DEFAULT_BG_BOTTOM: ScreenshotBgColorName = 'gray-dark'
+
+// per-slide persistence of the 3d composition state (camera pose, scene
+// look, env state) so a slide captured in 3d can re-open into the same
+// scene. `null` titleColor means "auto contrast against bgTop" (the
+// historical behavior); any palette name overrides.
+// the operator's grade over the finished frame, as serializable ids. this is
+// the one definition of the grade's shape: the 3d mode's own ThreeGradeState
+// is this type, and the renderer maps each id to its number. It lives here
+// because the plugins depend on the engine and not the other way round.
+export interface ScreenshotThreeGrade {
+  contrast: 'low' | 'neutral' | 'high' | 'max'
+  saturation: 'low' | 'neutral' | 'high' | 'max'
+  brightness: 'low' | 'neutral' | 'high'
+  blackPoint: 'lifted' | 'neutral' | 'deep' | 'crushed'
+  grain: 'off' | 'subtle' | 'strong'
+}
+
+export const SCREENSHOT_THREE_GRADE_IDS: {
+  [K in keyof ScreenshotThreeGrade]: readonly ScreenshotThreeGrade[K][]
+} = {
+  contrast: ['low', 'neutral', 'high', 'max'],
+  saturation: ['low', 'neutral', 'high', 'max'],
+  brightness: ['low', 'neutral', 'high'],
+  blackPoint: ['lifted', 'neutral', 'deep', 'crushed'],
+  grain: ['off', 'subtle', 'strong'],
+}
+
+// identity. a restored slide that saved no grade is put back onto this rather
+// than left on whatever the previous slide was graded to.
+export const SCREENSHOT_THREE_GRADE_DEFAULT: ScreenshotThreeGrade = {
+  contrast: 'neutral',
+  saturation: 'neutral',
+  brightness: 'neutral',
+  blackPoint: 'neutral',
+  grain: 'off',
+}
+
+// the Cyclorama setting's light rig and sweep. angles are degrees, sweepMs is
+// authored timeline time, curveRadius and shadowSoftness are fractions of the
+// device's longest side. Same ownership reason as the grade above.
+export interface ScreenshotThreeCyclorama {
+  keyAzimuthDeg: number
+  keyElevationDeg: number
+  keyRiseDeg: number
+  sweepMs: number
+  keyIntensity: number
+  warmIntensity: number
+  coolIntensity: number
+  curveRadius: number
+  shadowSoftness: number
+  // the two tints the operator picks. warmColor drives the warm contribution
+  // and coolColor the cool one, each carried by its existing intensity field.
+  warmColor: string
+  coolColor: string
+  warmColorEnd: string | null
+  coolColorEnd: string | null
+}
+
+// the two colors are authored as strings, so the numeric ranges cover the
+// numeric fields only rather than widening to a union nothing can clamp.
+type ScreenshotThreeCycloramaNumericKey = {
+  [K in keyof ScreenshotThreeCyclorama]: ScreenshotThreeCyclorama[K] extends number
+    ? K
+    : never
+}[keyof ScreenshotThreeCyclorama]
+
+export const SCREENSHOT_THREE_CYCLORAMA_RANGES: {
+  [K in ScreenshotThreeCycloramaNumericKey]: readonly [number, number]
+} = {
+  keyAzimuthDeg: [-360, 360],
+  keyElevationDeg: [1, 89],
+  keyRiseDeg: [1, 89],
+  sweepMs: [0, 600_000],
+  keyIntensity: [0, 40],
+  warmIntensity: [0, 40],
+  coolIntensity: [0, 40],
+  curveRadius: [0.05, 6],
+  shadowSoftness: [0, 0.5],
+}
+
+// the rig a Cyclorama slide opens on, calibrated against the rendered frame.
+export const SCREENSHOT_THREE_CYCLORAMA_DEFAULT: ScreenshotThreeCyclorama = {
+  keyAzimuthDeg: 23.55,
+  keyElevationDeg: 59.7,
+  keyRiseDeg: 62.2,
+  sweepMs: 0,
+  keyIntensity: 3,
+  warmIntensity: 0.9,
+  coolIntensity: 1.1,
+  curveRadius: 0.08,
+  shadowSoftness: 0.06,
+  warmColor: '#ffcb12',
+  coolColor: '#2879ff',
+  warmColorEnd: null,
+  coolColorEnd: null,
+}
+
+// six-digit #RRGGBB only. a three-digit or named color parses differently in
+// the picker, the film validator and the renderer's color conversion, so the
+// one spelling every owner agrees on is the only one accepted.
+const SCREENSHOT_THREE_CYCLORAMA_COLOR_KEY_SET: ReadonlySet<string> = new Set([
+  'warmColor',
+  'coolColor',
+  'warmColorEnd',
+  'coolColorEnd',
+])
+
+const SCREENSHOT_THREE_CYCLORAMA_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/
+
+export function isScreenshotThreeCycloramaColorKey(
+  key: string,
+): key is 'warmColor' | 'coolColor' | 'warmColorEnd' | 'coolColorEnd' {
+  return SCREENSHOT_THREE_CYCLORAMA_COLOR_KEY_SET.has(key)
+}
+
+export function isScreenshotThreeCycloramaColor(value: unknown): value is string {
+  return typeof value === 'string' && SCREENSHOT_THREE_CYCLORAMA_COLOR_PATTERN.test(value)
+}
+
+// null holds the starting tint throughout an authored sweep.
+export function normalizeScreenshotThreeCycloramaEndColor(
+  value: unknown,
+  base: string | null = null,
+): string | null {
+  return value === null
+    ? null
+    : isScreenshotThreeCycloramaColor(value)
+      ? value.toLowerCase()
+      : base
+}
+
+/**
+ * The one place a cyclorama tint is turned into state. Anything that is not a
+ * six-digit hex takes the fallback rather than reaching the renderer, and a
+ * valid one is lower-cased so the picker, a saved slide and an authored film
+ * all hold the same spelling.
+ */
+export function normalizeScreenshotThreeCycloramaColor(
+  value: unknown,
+  fallback: string,
+): string {
+  return isScreenshotThreeCycloramaColor(value) ? value.toLowerCase() : fallback
+}
+
+export interface ScreenshotThreeAppearance extends Record<string, unknown> {
+  caseStyle?: 'standard' | 'edge-to-edge'
+  grade?: ScreenshotThreeGrade
+  cyclorama?: ScreenshotThreeCyclorama
+}
+
+export interface ScreenshotThreeScene {
+  device: 'iphone-17-air' | 'iphone-17-pro' | 'pixel-10'
+  // [x, y, z]
+  cameraPosition: [number, number, number]
+  cameraUp?: [number, number, number]
+  // orbit-controls target the camera looks at
+  target: [number, number, number]
+  // phone model transform
+  phonePosition: [number, number, number]
+  phoneRotation: [number, number, number]
+  colorway: string
+  background: string
+  // custom gradient override (caller color stops). when present it takes
+  // precedence over `background` so the deck's shared brand palette is
+  // restored on re-open instead of the named preset.
+  customGradient?: {
+    stops: { offset: number; color: string }[]
+    angleDeg?: number
+  } | null
+  // ids follow the shared serialized contract; appearance is renderer-owned.
+  setting: ThreeModeSetting
+  appearance?: ScreenshotThreeAppearance
+  focus?: Record<string, string | boolean | null | undefined> | null
+  // env state. shape mirrors the bridge — kept as serializable plain
+  // objects, normalized at apply time.
+  environmentActive: boolean
+  environmentPins?: Record<string, string | null | undefined>
+  environmentEffects?: Record<string, boolean>
+}
+
+export type TitleSize = 'sm' | 'md' | 'lg'
+
+export type TitleUnderlay = 'black' | 'white'
+
+export type TitleShadow = 'light' | 'medium' | 'strong'
+
+export type ScreenshotTextAlign = 'left' | 'center' | 'right'
+
+export interface ScreenshotFontChoice {
+  family: string
+}
+
+export interface ScreenshotTextPosition {
+  // normalized canvas coordinates for the text block's aligned top anchor.
+  x: number
+  y: number
+}
+
+export interface ScreenshotImageLayer {
+  // ref into the same capture store used by screen/capture/clean layers.
+  ref: string
+  // normalized canvas coordinates for the image center.
+  x: number
+  y: number
+  // rendered image width as a fraction of the canvas width.
+  scale: number
+  // clockwise rotation in degrees.
+  rotation: number
+}
+
+export interface ScreenshotPhone2DTransform {
+  // percentage of the phone silhouette width.
+  x: number
+  // percentage of the phone silhouette height.
+  y: number
+  deg: number
+  scale: number
+}
+
+export const DEFAULT_PHONE_2D_TRANSFORM: ScreenshotPhone2DTransform = {
+  x: 0,
+  y: 0,
+  deg: 0,
+  scale: 1,
+}
+
+export const PHONE_2D_TRANSFORM_LIMITS = {
+  x: { min: -32, max: 32, step: 1 },
+  y: { min: -32, max: 32, step: 1 },
+  deg: { min: -18, max: 18, step: 1 },
+  scale: { min: 0.72, max: 1.28, step: 0.01 },
+}
+
+export interface ScreenshotSlide {
+  id: string
+  title: string
+  subtitle: string
+  bgTop: ScreenshotBgColorName
+  bgBottom: ScreenshotBgColorName
+  pose: PosePresetName
+  // override for the title/subtitle copy color. when undefined, copy
+  // contrast is derived automatically from bgTop. used by the rail's
+  // text-color picker so a designer can pin "white text on a light bg"
+  // intentionally, including in 3d mode where bgTop isn't the painted bg.
+  titleColor?: ScreenshotBgColorName
+  // type-scale preset for the title block (subtitle scales with it).
+  // undefined → 'md' default, same point size the rail shipped at.
+  titleSize?: TitleSize
+  // optional gradient underlay painted behind the title text — solid at
+  // the top of the slide, fading to transparent ~100px below the title.
+  // designed for 3d-mode shots where the live backdrop can be busy and
+  // copy needs a guaranteed legibility floor; in 2d mode it's purely
+  // stylistic. undefined → no underlay.
+  titleUnderlay?: TitleUnderlay
+  // text-shadow preset for the title/subtitle. boosts legibility on
+  // photographic / 3d backgrounds. undefined → no shadow.
+  titleShadow?: TitleShadow
+  // one Google Fonts family shared by title and subtitle. title/subtitle
+  // weights are selected from the curated family metadata at render time.
+  // undefined keeps the native SF Pro display/text stacks.
+  font?: ScreenshotFontChoice
+  // normalized top anchor for the complete title/subtitle block. the x
+  // coordinate follows textAlign (left edge, center, or right edge).
+  // undefined keeps the current top-center placement.
+  textPosition?: ScreenshotTextPosition
+  textAlign?: ScreenshotTextAlign
+  // decorative capture-store images. the editable overlay stack is the
+  // composed background/device base, these images, the text underlay, then
+  // text. keeping images above the reusable clean base means image and copy
+  // edits re-bake without booting the app or re-rendering a 3d scene.
+  images?: ScreenshotImageLayer[]
+  // ref into the binary capture store (cloud R2) for the COMPOSED App-Store
+  // deliverable — bg + title + posed phone + screen baked into one image (or
+  // the 3D-baked scene). this is what review shows edge-to-edge and what the
+  // zip exports. present once a slide has been captured.
+  captureRef?: string
+  // ref into the capture store for the COMPOSED deliverable WITHOUT the title
+  // block — same bg + posed phone + screen (or 3d scene), text omitted. baked
+  // alongside `captureRef` on every capture. lets a copy edit drop a live text
+  // overlay onto this and re-bake `captureRef` with NO device/screen repaint
+  // and, for 3d slides, NO scene re-render. absent on slides captured before
+  // this layer existed (and on composed-only org pushes) — callers fall back to
+  // recompose-from-screen / record-new there.
+  cleanRef?: string
+  // ref into the capture store for the BARE phone-screen pixels (screen only,
+  // no chrome). drives the fake-screen overlay so a slide can be re-posed /
+  // re-styled and re-baked into a new `captureRef` without booting a build.
+  // absent on composed-only org pushes, so Position is disabled until a slide
+  // has been captured with the 3-layer pipeline.
+  screenRef?: string
+  // 2d phone transform used by Position mode when 3d is off. x/y are stored as
+  // percentages of the phone silhouette width/height so preview and export
+  // apply the same transform regardless of card/canvas size.
+  phone2d?: ScreenshotPhone2DTransform
+  // 3d composition state, persisted on capture so re-opening the slide
+  // restores the exact scene the user shot.
+  threeScene?: ScreenshotThreeScene
+}
+
+function isTitleSize(value: unknown): value is TitleSize {
+  return value === 'sm' || value === 'md' || value === 'lg'
+}
+
+function isTitleUnderlay(value: unknown): value is TitleUnderlay {
+  return value === 'black' || value === 'white'
+}
+
+function isTitleShadow(value: unknown): value is TitleShadow {
+  return value === 'light' || value === 'medium' || value === 'strong'
+}
+
+function isScreenshotTextAlign(value: unknown): value is ScreenshotTextAlign {
+  return value === 'left' || value === 'center' || value === 'right'
+}
+
+function clampNumber(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  return Math.min(max, Math.max(min, value))
+}
+
+export function normalizeScreenshotPhone2DTransform(
+  input: unknown,
+): ScreenshotPhone2DTransform | undefined {
+  if (!isRecord(input)) return undefined
+  const value = input
+  const x = clampNumber(
+    value.x,
+    PHONE_2D_TRANSFORM_LIMITS.x.min,
+    PHONE_2D_TRANSFORM_LIMITS.x.max,
+    DEFAULT_PHONE_2D_TRANSFORM.x,
+  )
+  const y = clampNumber(
+    value.y,
+    PHONE_2D_TRANSFORM_LIMITS.y.min,
+    PHONE_2D_TRANSFORM_LIMITS.y.max,
+    DEFAULT_PHONE_2D_TRANSFORM.y,
+  )
+  const deg = clampNumber(
+    value.deg,
+    PHONE_2D_TRANSFORM_LIMITS.deg.min,
+    PHONE_2D_TRANSFORM_LIMITS.deg.max,
+    DEFAULT_PHONE_2D_TRANSFORM.deg,
+  )
+  const scale = clampNumber(
+    value.scale,
+    PHONE_2D_TRANSFORM_LIMITS.scale.min,
+    PHONE_2D_TRANSFORM_LIMITS.scale.max,
+    DEFAULT_PHONE_2D_TRANSFORM.scale,
+  )
+  return { x, y, deg, scale }
+}
+
+function normalizeScreenshotFont(input: unknown): ScreenshotFontChoice | undefined {
+  if (!isRecord(input)) return undefined
+  const family = input.family
+  if (typeof family !== 'string') return undefined
+  const trimmed = family.trim()
+  return trimmed ? { family: trimmed.slice(0, 100) } : undefined
+}
+
+function normalizeScreenshotTextPosition(
+  input: unknown,
+): ScreenshotTextPosition | undefined {
+  if (!isRecord(input)) return undefined
+  const position = input
+  if (typeof position.x !== 'number' || typeof position.y !== 'number') return undefined
+  if (!Number.isFinite(position.x) || !Number.isFinite(position.y)) return undefined
+  return {
+    x: clampNumber(position.x, 0, 1, 0.5),
+    y: clampNumber(position.y, 0, 1, 0.06),
+  }
+}
+
+function normalizeScreenshotImages(input: unknown): ScreenshotImageLayer[] | undefined {
+  if (!Array.isArray(input)) return undefined
+  const images: ScreenshotImageLayer[] = []
+  for (const candidate of input.slice(0, 32)) {
+    if (!isRecord(candidate)) continue
+    const image = candidate
+    if (typeof image.ref !== 'string' || !image.ref.trim()) continue
+    images.push({
+      ref: image.ref.trim(),
+      x: clampNumber(image.x, 0, 1, 0.5),
+      y: clampNumber(image.y, 0, 1, 0.5),
+      scale: clampNumber(image.scale, 0.02, 2, 0.25),
+      rotation: clampNumber(image.rotation, -360, 360, 0),
+    })
+  }
+  return images.length > 0 ? images : undefined
+}
+
+function normalizeCustomGradient(
+  input: unknown,
+): ScreenshotThreeScene['customGradient'] | undefined {
+  if (!isRecord(input)) return undefined
+  const g = input
+  if (!Array.isArray(g.stops)) return undefined
+  const stops = g.stops
+    .filter(
+      (s): s is { offset: number; color: string } =>
+        isRecord(s) && typeof s.color === 'string' && typeof s.offset === 'number',
+    )
+    .map((s) => ({ offset: s.offset, color: s.color }))
+  if (stops.length === 0) return undefined
+  return {
+    stops,
+    ...(typeof g.angleDeg === 'number' ? { angleDeg: g.angleDeg } : {}),
+  }
+}
+
+// every dimension is checked against its own id list, and anything unknown
+// falls back to identity for that dimension. A string that merely looks like
+// an id is exactly what must not reach the renderer: it would be dropped
+// there, silently restoring a slide to a look it was never graded with.
+function normalizeThreeSceneGrade(input: Record<string, unknown>): ScreenshotThreeGrade {
+  const read = <K extends keyof ScreenshotThreeGrade>(
+    key: K,
+  ): ScreenshotThreeGrade[K] => {
+    const value = input[key]
+    const ids: readonly ScreenshotThreeGrade[K][] = SCREENSHOT_THREE_GRADE_IDS[key]
+    return ids.find((id) => id === value) ?? SCREENSHOT_THREE_GRADE_DEFAULT[key]
+  }
+  return {
+    contrast: read('contrast'),
+    saturation: read('saturation'),
+    brightness: read('brightness'),
+    blackPoint: read('blackPoint'),
+    grain: read('grain'),
+  }
+}
+
+// authored numbers, clamped to the same ranges the 3d bridge validates
+// against. A missing or non-finite field takes the default rather than
+// dropping out of the saved rig.
+function normalizeThreeSceneCyclorama(value: unknown): ScreenshotThreeCyclorama {
+  const input = isRecord(value) ? value : {}
+  const read = (key: ScreenshotThreeCycloramaNumericKey): number => {
+    const [min, max] = SCREENSHOT_THREE_CYCLORAMA_RANGES[key]
+    return clampNumber(input[key], min, max, SCREENSHOT_THREE_CYCLORAMA_DEFAULT[key])
+  }
+  const readColor = (key: 'warmColor' | 'coolColor'): string =>
+    normalizeScreenshotThreeCycloramaColor(
+      input[key],
+      SCREENSHOT_THREE_CYCLORAMA_DEFAULT[key],
+    )
+  return {
+    keyAzimuthDeg: read('keyAzimuthDeg'),
+    keyElevationDeg: read('keyElevationDeg'),
+    keyRiseDeg: read('keyRiseDeg'),
+    sweepMs: read('sweepMs'),
+    keyIntensity: read('keyIntensity'),
+    warmIntensity: read('warmIntensity'),
+    coolIntensity: read('coolIntensity'),
+    curveRadius: read('curveRadius'),
+    shadowSoftness: read('shadowSoftness'),
+    warmColor: readColor('warmColor'),
+    coolColor: readColor('coolColor'),
+    warmColorEnd: normalizeScreenshotThreeCycloramaEndColor(
+      'warmColorEnd' in input ? input.warmColorEnd : null,
+    ),
+    coolColorEnd: normalizeScreenshotThreeCycloramaEndColor(
+      'coolColorEnd' in input ? input.coolColorEnd : null,
+    ),
+  }
+}
+
+/**
+ * The 3d bridge options that put a saved slide's scene back. Every dimension
+ * the slide can carry is named here, including the ones it saved at their
+ * default: configure() merges partial input onto the LIVE state, which is
+ * what live editing wants and exactly what restoring must not do. Leaving
+ * caseStyle, grade or the cyclorama rig out is how a standard slide opened
+ * after an edge-to-edge one came back wearing the other slide's case, its
+ * grain and its lighting.
+ */
+export function screenshotThreeSceneRestoreOptions(scene: ScreenshotThreeScene) {
+  return {
+    ...scene.appearance,
+    device: scene.device,
+    caseStyle: scene.appearance?.caseStyle ?? 'standard',
+    colorway: scene.colorway,
+    background: scene.background,
+    ...(scene.customGradient ? { customGradient: scene.customGradient } : {}),
+    setting: scene.setting,
+    grade: scene.appearance?.grade ?? SCREENSHOT_THREE_GRADE_DEFAULT,
+    // a slide saved before the tints existed carries a rig without them, and
+    // configure() merges partials onto the live state: hand the renderer a
+    // complete rig here or the previous slide's tints stay lit.
+    cyclorama: scene.appearance?.cyclorama
+      ? normalizeThreeSceneCyclorama(scene.appearance.cyclorama)
+      : SCREENSHOT_THREE_CYCLORAMA_DEFAULT,
+    focus: scene.focus,
+    environment: scene.environmentActive
+      ? {
+          pins: scene.environmentPins ?? {},
+          effects: scene.environmentEffects ?? {},
+        }
+      : false,
+    pose: {
+      phonePosition: scene.phonePosition,
+      phoneRotation: scene.phoneRotation,
+      cameraPosition: scene.cameraPosition,
+      cameraUp: scene.cameraUp,
+      target: scene.target,
+    },
+  }
+}
+
+function normalizeSceneRecord<T>(
+  input: unknown,
+  isValue: (value: unknown) => value is T,
+): Record<string, T> | undefined {
+  if (!isRecord(input)) return undefined
+  return Object.fromEntries(
+    Object.entries(input).filter((entry): entry is [string, T] => isValue(entry[1])),
+  )
+}
+
+function isScreenshotBgColorName(value: unknown): value is ScreenshotBgColorName {
+  return SCREENSHOT_BG_COLORS.some((color) => color.name === value)
+}
+
+function normalizeThreeScene(input: unknown): ScreenshotThreeScene | undefined {
+  if (!isRecord(input)) return undefined
+  const s = input
+  const vec3 = (v: unknown): [number, number, number] | null => {
+    if (!Array.isArray(v) || v.length !== 3) return null
+    if (!v.every((n) => typeof n === 'number' && Number.isFinite(n))) return null
+    return [v[0], v[1], v[2]]
+  }
+  const cam = vec3(s.cameraPosition)
+  const cameraUp = vec3(s.cameraUp)
+  const tgt = vec3(s.target)
+  const pp = vec3(s.phonePosition)
+  const pr = vec3(s.phoneRotation)
+  if (!cam || !tgt || !pp || !pr) return undefined
+  const customGradient = normalizeCustomGradient(s.customGradient)
+  let appearance: ScreenshotThreeAppearance | undefined
+  if (isRecord(s.appearance)) {
+    const { caseStyle, grade, cyclorama, ...rest } = s.appearance
+    appearance = rest
+    if (
+      typeof appearance.windowLightOffset !== 'number' ||
+      !Number.isFinite(appearance.windowLightOffset) ||
+      appearance.windowLightOffset < THREE_WINDOW_LIGHT_OFFSET_RANGE[0] ||
+      appearance.windowLightOffset > THREE_WINDOW_LIGHT_OFFSET_RANGE[1]
+    )
+      delete appearance.windowLightOffset
+    if (caseStyle === 'standard' || caseStyle === 'edge-to-edge')
+      appearance.caseStyle = caseStyle
+    if (isRecord(grade)) appearance.grade = normalizeThreeSceneGrade(grade)
+    if (isRecord(cyclorama))
+      appearance.cyclorama = normalizeThreeSceneCyclorama(cyclorama)
+  }
+  const focus = normalizeSceneRecord(
+    s.focus,
+    (value) => value == null || typeof value === 'string' || typeof value === 'boolean',
+  )
+  const environmentPins = normalizeSceneRecord(
+    s.environmentPins,
+    (value) => value == null || typeof value === 'string',
+  )
+  const environmentEffects = normalizeSceneRecord(
+    s.environmentEffects,
+    (value) => typeof value === 'boolean',
+  )
+  return {
+    device:
+      s.device === 'iphone-17-pro' || s.device === 'pixel-10'
+        ? s.device
+        : 'iphone-17-air',
+    cameraPosition: cam,
+    ...(cameraUp ? { cameraUp } : {}),
+    target: tgt,
+    phonePosition: pp,
+    phoneRotation: pr,
+    colorway: typeof s.colorway === 'string' ? s.colorway : 'black',
+    background: typeof s.background === 'string' ? s.background : 'black',
+    ...(customGradient ? { customGradient } : {}),
+    setting: isThreeModeSetting(s.setting) ? s.setting : 'none',
+    ...(appearance ? { appearance } : {}),
+    ...(focus ? { focus } : {}),
+    environmentActive: !!s.environmentActive,
+    environmentPins,
+    environmentEffects,
+  }
+}
+
+// normalize a (possibly legacy / partial) slide so the rest of the code
+// has exactly one shape. pre-production: a legacy `theme` slide just
+// resets to the grey default rather than carrying a compat shim.
+export function normalizeScreenshotSlide(input: unknown, index = 0): ScreenshotSlide {
+  const s = isRecord(input) ? input : {}
+  const threeScene = normalizeThreeScene(s.threeScene)
+  const phone2d = normalizeScreenshotPhone2DTransform(s.phone2d)
+  const font = normalizeScreenshotFont(s.font)
+  const textPosition = normalizeScreenshotTextPosition(s.textPosition)
+  const images = normalizeScreenshotImages(s.images)
+  return {
+    id: typeof s.id === 'string' && s.id ? s.id : makeScreenshotSlide(index).id,
+    title: typeof s.title === 'string' ? s.title : '',
+    subtitle: typeof s.subtitle === 'string' ? s.subtitle : '',
+    bgTop: isScreenshotBgColorName(s.bgTop) ? s.bgTop : DEFAULT_BG_TOP,
+    bgBottom: isScreenshotBgColorName(s.bgBottom) ? s.bgBottom : DEFAULT_BG_BOTTOM,
+    pose: POSE_PRESET_NAMES.find((pose) => pose === s.pose) ?? 'straight',
+    ...(isScreenshotBgColorName(s.titleColor) ? { titleColor: s.titleColor } : {}),
+    ...(isTitleSize(s.titleSize) ? { titleSize: s.titleSize } : {}),
+    ...(isTitleUnderlay(s.titleUnderlay) ? { titleUnderlay: s.titleUnderlay } : {}),
+    ...(isTitleShadow(s.titleShadow) ? { titleShadow: s.titleShadow } : {}),
+    ...(font ? { font } : {}),
+    ...(textPosition ? { textPosition } : {}),
+    ...(isScreenshotTextAlign(s.textAlign) ? { textAlign: s.textAlign } : {}),
+    ...(images ? { images } : {}),
+    ...(typeof s.captureRef === 'string' ? { captureRef: s.captureRef } : {}),
+    ...(typeof s.cleanRef === 'string' ? { cleanRef: s.cleanRef } : {}),
+    ...(typeof s.screenRef === 'string' ? { screenRef: s.screenRef } : {}),
+    ...(phone2d ? { phone2d } : {}),
+    ...(threeScene ? { threeScene } : {}),
+  }
+}
+
+export interface ThreeProjectConfig {
+  colorway: string
+  background: string
+  // remaining 3d decor/script state is folded in during Phase 6.
+}
+
+export interface ScreenshotProjectConfig {
+  store: 'apple' | 'google'
+  canvas: ScreenshotCanvasName
+  deviceModel: DeviceModel
+  // false until the user picks a device from the screenshot rail. while
+  // false, entering screenshot mode adopts whatever device you were
+  // already on (the "default to current device" behavior); once true the
+  // project's device is authoritative and pushed to the engine on enter.
+  // single rule, no fallback ambiguity.
+  deviceModelExplicit?: boolean
+  frames: ScreenshotSlide[]
+  activeSlideId: string
+  three?: ThreeProjectConfig
+}
+
+// fresh projects open with a single slide; the user adds more from the
+// overview gallery's + tile. matches the App-Store editor's blank-state
+// expectation — empty canvas, not a grid of pre-seeded placeholders.
+export const DEFAULT_SCREENSHOT_FRAME_COUNT = 1
+
+// Apple allows up to 10 screenshots per device, Google Play 8.
+export const SCREENSHOT_FRAME_LIMITS: Record<'apple' | 'google', number> = {
+  apple: 10,
+  google: 8,
+}
+
+export function makeScreenshotSlide(index: number): ScreenshotSlide {
+  return {
+    id: `slide_${Date.now().toString(36)}_${index}_${Math.random().toString(36).slice(2, 7)}`,
+    title: '',
+    subtitle: '',
+    bgTop: DEFAULT_BG_TOP,
+    bgBottom: DEFAULT_BG_BOTTOM,
+    pose: 'straight',
+  }
+}
+
+export function defaultScreenshotProjectConfig(
+  deviceModel: DeviceModel,
+  canvas: ScreenshotCanvasName = deviceModel === 'ipad-pro-13'
+    ? 'ipad-pro-13'
+    : 'iphone-6-9',
+): ScreenshotProjectConfig {
+  const frames = Array.from({ length: DEFAULT_SCREENSHOT_FRAME_COUNT }, (_, i) =>
+    makeScreenshotSlide(i),
+  )
+  const store = SCREENSHOT_CANVASES[canvas]?.store ?? 'apple'
+  return {
+    store,
+    canvas,
+    deviceModel,
+    frames,
+    activeSlideId: frames[0].id,
+  }
+}
+
+export function resolveCanvasPreset(name: string): CanvasPreset | null {
+  const preset = SCREENSHOT_CANVAS_NAMES.find((preset) => preset === name)
+  return preset ? SCREENSHOT_CANVASES[preset] : null
+}
+
+export function cloneBackgroundSpec(background: BackgroundSpec): BackgroundSpec {
+  return {
+    type: background.type,
+    color: background.color,
+    direction: background.direction,
+    glow: background.glow,
+    stops: background.stops?.map((stop) => ({ ...stop })),
+  }
+}
+
+export function resolveBackgroundPreset(name: string): BackgroundSpec | null {
+  const preset = BACKGROUND_PRESET_NAMES.find((preset) => preset === name)
+  return preset ? cloneBackgroundSpec(BACKGROUND_PRESETS[preset]) : null
+}