@nodaro/shared 1.4.2

package/src/lottie-overlay-catalog.ts

@@ -0,0 +1,175 @@
+/**
+ * Built-in Lottie Overlay catalog — single source of truth.
+ *
+ * The Lottie Overlay node ships a curated set of 12 animations the overlay LLM
+ * can pick from. They were originally served from the third-party lottie.host
+ * CDN, which went dead (origin returns 403) and broke every catalog-based
+ * overlay render in production. The replacements were authored with our own
+ * Lottie engine, baked (slots resolved, no `sid` refs), and are now self-hosted
+ * on the Nodaro CDN at `https://cdn.nodaro.ai/lottie-catalog/<slug>.json`.
+ *
+ * This module is the ONE place the catalog lives:
+ *   - `LOTTIE_OVERLAY_CATALOG` feeds the overlay system prompt (the LLM's menu).
+ *   - `LEGACY_LOTTIE_HOST_REMAP` + `resolveLottieOverlaySrc` heal saved overlay
+ *     plans at render time — a plan authored before the cut-over still points at
+ *     a dead lottie.host URL, so the renderer rewrites it to its self-hosted
+ *     replacement before fetching.
+ */
+
+export interface LottieOverlayCatalogEntry {
+  /** Stable system key — the R2 object is `lottie-catalog/<slug>.json`. */
+  readonly slug: string
+  /** Display name — mirrors the original prompt's catalog labels. */
+  readonly name: string
+  /** Catalog group (drives the grouped layout in the system prompt). */
+  readonly group:
+    | "Celebration"
+    | "Social / Reactions"
+    | "UI / Indicators"
+    | "Ambient / Decorative"
+  /** One placement-intent line for the overlay LLM. */
+  readonly description: string
+  /** Public CDN URL: `https://cdn.nodaro.ai/lottie-catalog/<slug>.json`. */
+  readonly url: string
+  /** Whether the animation is continuous (loop) or a one-shot effect. */
+  readonly loop: boolean
+}
+
+const CDN_BASE = "https://cdn.nodaro.ai/lottie-catalog"
+
+export const LOTTIE_OVERLAY_CATALOG: readonly LottieOverlayCatalogEntry[] = [
+  // ── Celebration ────────────────────────────────────────────────────────────
+  {
+    slug: "confetti-burst",
+    name: "Confetti burst",
+    group: "Celebration",
+    description: "Multicolor confetti shower — large coverage at a celebratory peak; one-shot.",
+    url: `${CDN_BASE}/confetti-burst.json`,
+    loop: false,
+  },
+  {
+    slug: "fireworks",
+    name: "Fireworks",
+    group: "Celebration",
+    description: "Bursting fireworks against the sky — big-moment payoff over the upper frame; one-shot.",
+    url: `${CDN_BASE}/fireworks.json`,
+    loop: false,
+  },
+  {
+    slug: "party-popper",
+    name: "Party popper",
+    group: "Celebration",
+    description: "Party popper streamers from a corner — a quick celebratory accent; one-shot.",
+    url: `${CDN_BASE}/party-popper.json`,
+    loop: false,
+  },
+  {
+    slug: "stars-sparkle",
+    name: "Stars sparkle",
+    group: "Celebration",
+    description: "Twinkling stars/sparkles — small accent over a highlight; loops.",
+    url: `${CDN_BASE}/stars-sparkle.json`,
+    loop: true,
+  },
+  // ── Social / Reactions ──────────────────────────────────────────────────────
+  {
+    slug: "heart-pulse",
+    name: "Heart pulse",
+    group: "Social / Reactions",
+    description: "Pulsing heart reaction — medium size at a corner or edge; loops.",
+    url: `${CDN_BASE}/heart-pulse.json`,
+    loop: true,
+  },
+  {
+    slug: "thumbs-up",
+    name: "Thumbs up",
+    group: "Social / Reactions",
+    description: "Thumbs-up approval reaction — medium size, pops in once; one-shot.",
+    url: `${CDN_BASE}/thumbs-up.json`,
+    loop: false,
+  },
+  {
+    slug: "fire-flame",
+    name: "Fire emoji",
+    group: "Social / Reactions",
+    description: "Flickering flame reaction (“this is fire”) — small size at an edge; loops.",
+    url: `${CDN_BASE}/fire-flame.json`,
+    loop: true,
+  },
+  // ── UI / Indicators ─────────────────────────────────────────────────────────
+  {
+    slug: "loading-spinner",
+    name: "Loading spinner",
+    group: "UI / Indicators",
+    description: "Circular loading spinner — small, centered, signals progress; loops.",
+    url: `${CDN_BASE}/loading-spinner.json`,
+    loop: true,
+  },
+  {
+    slug: "checkmark-success",
+    name: "Checkmark success",
+    group: "UI / Indicators",
+    description: "Animated success checkmark — small, marks a completed/correct moment; one-shot.",
+    url: `${CDN_BASE}/checkmark-success.json`,
+    loop: false,
+  },
+  {
+    slug: "arrow-pointer",
+    name: "Arrow pointer",
+    group: "UI / Indicators",
+    description: "Animated arrow drawing attention to a spot — small, timed to a key area; loops.",
+    url: `${CDN_BASE}/arrow-pointer.json`,
+    loop: true,
+  },
+  // ── Ambient / Decorative ────────────────────────────────────────────────────
+  {
+    slug: "floating-particles",
+    name: "Floating particles",
+    group: "Ambient / Decorative",
+    description: "Soft drifting particles — large coverage, low opacity, full-duration ambience; loops.",
+    url: `${CDN_BASE}/floating-particles.json`,
+    loop: true,
+  },
+  {
+    slug: "glowing-ring",
+    name: "Glowing ring",
+    group: "Ambient / Decorative",
+    description: "Pulsing glowing ring/halo — decorative accent around a focal point; loops.",
+    url: `${CDN_BASE}/glowing-ring.json`,
+    loop: true,
+  },
+] as const
+
+/**
+ * Dead lottie.host URLs (origin returns 403) → their replacement catalog URLs.
+ * Heals saved plans at render time. The keys are copied EXACTLY from the
+ * original `lottie-overlay-system.ts` prompt — they are the literal `src`
+ * strings the overlay LLM emitted before the cut-over.
+ */
+export const LEGACY_LOTTIE_HOST_REMAP: Readonly<Record<string, string>> = {
+  // Celebration
+  "https://lottie.host/d7313e87-e4c9-4e0d-8e03-c3a59e87d8fb/TjHnrCGBjI.json": `${CDN_BASE}/confetti-burst.json`,
+  "https://lottie.host/d5cad0dd-4e93-4bbe-b023-e94a04bc1581/JHEZMrqfMk.json": `${CDN_BASE}/fireworks.json`,
+  "https://lottie.host/0060c9cd-75da-42d5-af7c-1a191fa8a8fd/c1xHMRnGTO.json": `${CDN_BASE}/party-popper.json`,
+  "https://lottie.host/c04a2758-a1d9-40a9-b81f-6f3e4e13a88c/xKCYDU2w0O.json": `${CDN_BASE}/stars-sparkle.json`,
+  // Social / Reactions
+  "https://lottie.host/44c9e8d1-856c-4641-bfbe-d0e2a5c9850e/GIBsMSIkkq.json": `${CDN_BASE}/heart-pulse.json`,
+  "https://lottie.host/9a611d56-1f35-4f51-9fa4-6a4daa6b8714/EH71MjHKPD.json": `${CDN_BASE}/thumbs-up.json`,
+  "https://lottie.host/66db1de9-c1a8-4d0b-bb03-47a8932a8a86/q5JBGQ8fxu.json": `${CDN_BASE}/fire-flame.json`,
+  // UI / Indicators
+  "https://lottie.host/b03d748c-3b4a-4c07-a10c-e9eb3c967349/eMVAVEnb5x.json": `${CDN_BASE}/loading-spinner.json`,
+  "https://lottie.host/3ffaab4a-58b0-4a72-9f1c-5eaa484d8c88/g27v7IPaJc.json": `${CDN_BASE}/checkmark-success.json`,
+  "https://lottie.host/6f831c6e-693a-4d1d-90a0-d7e2b3f00e68/PFj0MwSPrj.json": `${CDN_BASE}/arrow-pointer.json`,
+  // Ambient / Decorative
+  "https://lottie.host/9c8e1aef-f8e5-4ce8-bc80-1647ffb0724d/mNDClfKJVB.json": `${CDN_BASE}/floating-particles.json`,
+  "https://lottie.host/b5d3e7e7-40bc-44fa-9a53-78b98ad66e80/pQVdNsVDmQ.json": `${CDN_BASE}/glowing-ring.json`,
+}
+
+/**
+ * Resolve an overlay `src` through the legacy remap: a dead lottie.host URL is
+ * rewritten to its self-hosted replacement; everything else (already-migrated
+ * catalog URLs, user-provided assets) passes through unchanged.
+ */
+export function resolveLottieOverlaySrc(src: string): string {
+  return LEGACY_LOTTIE_HOST_REMAP[src] ?? src
+}

package/src/lottie-slots.ts

@@ -0,0 +1,309 @@
+/**
+ * Lottie slot substitution — single source of truth (design §5).
+ *
+ * A slotted property is an object containing a `sid` key (canonically exactly
+ * `{"sid": "name"}`; tolerantly also the annotation form `{a, k, sid}`). The
+ * slot manifest maps sid → { p: <whatever belongs at the reference position> }.
+ * Overrides map sid → raw value (what UI controls write).
+ *
+ * KEY CONVENTION: a slot's `p` is, by design, EXACTLY what belongs at the
+ * reference position — and we substitute it VERBATIM, never auto-wrapping it in
+ * an `{a:0,k:...}` envelope. At a property position (a fill color, a shape size)
+ * that means `p` is a property object like `{"a":0,"k":[1,0,0,1]}`. At a RAW
+ * position inside a text document — `layers[].t.d.k[0].s.t`, where lottie-web's
+ * `buildFinalText` iterates string characters — `p` is a BARE string, e.g.
+ * `{ "nameText": { "p": "John Smith" } }` substitutes the string `"John Smith"`
+ * straight onto `s.t`. (Auto-wrapping there produced `{a:0,k:"John Smith"}` and
+ * broke text rendering — the defect this contract fixes.)
+ *
+ * An override is wrapped ONLY when it lands on a property-object default: the
+ * `{...p, k: override}` form preserves the default's envelope (animated/static
+ * flags). On a raw default (or a missing slot) the override is substituted
+ * verbatim too — so a raw text override stays a bare string.
+ *
+ * Substitution is renderer-agnostic: we replace every sid node ourselves and
+ * never rely on lottie-web's version-dependent native slot support.
+ */
+
+type JsonRecord = Record<string, unknown>
+
+function isPlainObject(v: unknown): v is JsonRecord {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+/** True when `p` already looks like a lottie animated-property object. */
+function isPropertyObject(v: unknown): v is JsonRecord {
+  return isPlainObject(v) && "k" in v
+}
+
+function resolveSlotNode(
+  node: JsonRecord,
+  slots: JsonRecord,
+  overrides: JsonRecord,
+): unknown {
+  const sid = node.sid as string
+  const slot = slots[sid]
+  const slotP = isPlainObject(slot) ? (slot as JsonRecord).p : undefined
+  const override = overrides[sid]
+
+  if (override !== undefined) {
+    // Wrap into the default's property-object envelope when the default IS one
+    // (preserves animated/static flags); otherwise substitute the raw override
+    // verbatim — a raw text override must stay a bare string at `s.t`.
+    if (isPropertyObject(slotP)) return { ...slotP, k: structuredClone(override) }
+    return structuredClone(override)
+  }
+  if (slotP !== undefined) {
+    // `p` is by convention exactly what belongs at the reference position —
+    // substitute it verbatim, never auto-wrap (a bare string stays a string).
+    return structuredClone(slotP)
+  }
+  // No slot, no override — leave the node as-is (validator rule #6 should
+  // prevent this; belt-and-braces for hand-fed documents).
+  return node
+}
+
+function walk(value: unknown, slots: JsonRecord, overrides: JsonRecord): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => walk(item, slots, overrides))
+  }
+  if (isPlainObject(value)) {
+    if (typeof value.sid === "string") {
+      const resolved = resolveSlotNode(value, slots, overrides)
+      // The original node comes back only in the missing-slot case; replacements
+      // are leaf property objects and need no further walking.
+      if (resolved === value) {
+        const copy: JsonRecord = {}
+        for (const [k, v] of Object.entries(value)) copy[k] = walk(v, slots, overrides)
+        return copy
+      }
+      return resolved
+    }
+    const copy: JsonRecord = {}
+    for (const [k, v] of Object.entries(value)) copy[k] = walk(v, slots, overrides)
+    return copy
+  }
+  return value
+}
+
+/** Pure: returns a new document; never mutates inputs. */
+export function applySlots(
+  lottie: JsonRecord,
+  slots: JsonRecord | undefined,
+  overrides: JsonRecord | undefined,
+): JsonRecord {
+  return walk(lottie, slots ?? {}, overrides ?? {}) as JsonRecord
+}
+
+// ── Playback normalization ───────────────────────────────────────────────────
+//
+// lottie-web computes a layer's local time as `frame - layer.st` and gates the
+// layer on `local >= ip && local < op`. A layer missing `st` yields NaN, fails
+// the gate, and stays `display:none` forever — the document "loads" (DOMLoaded
+// fires) but every frame renders blank (prod incident 2026-06-12: all authored
+// lottie renders came out as empty frames in headless Chrome). `st` and `sr`
+// are spec-optional with defaults, so documents routinely omit them; complete
+// them at the playback boundary so any source — authored plan, baked export,
+// catalog asset, external URL — renders. Mutates `doc` in place and returns it
+// (callers pass freshly fetched or freshly copied documents).
+
+export function normalizeLottieLayers<T>(doc: T): T {
+  if (!isPlainObject(doc)) return doc
+  const fix = (layers: unknown): void => {
+    if (!Array.isArray(layers)) return
+    for (const layer of layers) {
+      if (!isPlainObject(layer)) continue
+      if (typeof layer.st !== "number") layer.st = 0
+      if (typeof layer.sr !== "number") layer.sr = 1
+    }
+  }
+  fix((doc as JsonRecord).layers)
+  const assets = (doc as JsonRecord).assets
+  if (Array.isArray(assets)) {
+    for (const asset of assets) {
+      if (isPlainObject(asset)) fix(asset.layers)
+    }
+  }
+  return doc
+}
+
+// ── Slot control descriptors (Phase 2 — UI mapping) ──────────────────────────
+//
+// A slot manifest entry is `{ p: <whatever belongs at the reference position> }`
+// (Amendment 1). `describeSlotControl` unwraps that envelope to the editable raw
+// value and classifies it into the control kind the config panel should render.
+// `p` is either a property object `{a, k}` (colors, sizes, scalars) whose `k`
+// holds the value, or a bare raw value (text strings live unwrapped at `s.t`).
+
+export type SlotControlKind = "color" | "text" | "number" | "point"
+export interface SlotControlDescriptor {
+  kind: SlotControlKind
+  value: unknown
+}
+
+/**
+ * Unwraps a slot entry to its editable raw value and classifies it:
+ *   {p:{a:0,k:[1,0,0,1]}} → { kind:"color", value:[1,0,0,1] }
+ *   {p:"John"}            → { kind:"text",  value:"John" }
+ *   {p:{a:0,k:42}}        → { kind:"number", value:42 }
+ *   {p:{a:0,k:[10,20]}}   → { kind:"point", value:[10,20] }
+ * Animated property objects (`a:1`) and anything that doesn't map to a known
+ * control kind return null (no editable control).
+ */
+export function describeSlotControl(slot: unknown): SlotControlDescriptor | null {
+  if (!isPlainObject(slot)) return null
+  const p = (slot as JsonRecord).p
+  let value: unknown = p
+  if (isPropertyObject(p)) {
+    if ((p as JsonRecord).a === 1) return null
+    value = (p as JsonRecord).k
+  }
+  if (typeof value === "string") return { kind: "text", value }
+  if (typeof value === "number") return { kind: "number", value }
+  if (
+    Array.isArray(value) &&
+    value.length === 4 &&
+    value.every((n) => typeof n === "number" && n >= 0 && n <= 1)
+  ) {
+    return { kind: "color", value }
+  }
+  if (Array.isArray(value) && value.length === 2 && value.every((n) => typeof n === "number")) {
+    return { kind: "point", value }
+  }
+  return null
+}
+
+function clamp01(n: number): number {
+  if (Number.isNaN(n)) return 0
+  return n < 0 ? 0 : n > 1 ? 1 : n
+}
+
+function toHexByte(component: number): string {
+  return Math.round(clamp01(component) * 255)
+    .toString(16)
+    .padStart(2, "0")
+}
+
+/**
+ * RGBA array (components 0..1) → hex string. The alpha component is omitted
+ * when it is exactly 1 (`[1,0,0,1]` → `"#ff0000"`); otherwise an 8-digit hex is
+ * emitted (`[0,1,0,0.5]` → `"#00ff0080"`). Output is always lowercase.
+ */
+export function rgbaArrayToHex(rgba: number[]): string {
+  const [r = 0, g = 0, b = 0, a = 1] = rgba
+  const base = `#${toHexByte(r)}${toHexByte(g)}${toHexByte(b)}`
+  return a >= 1 ? base : `${base}${toHexByte(a)}`
+}
+
+/**
+ * Hex string → RGBA array (components 0..1). Accepts `#rgb`, `#rrggbb`, and
+ * `#rrggbbaa`; alpha defaults to 1 when absent. Leading `#` is optional.
+ */
+export function hexToRgbaArray(hex: string): number[] {
+  let h = hex.trim().replace(/^#/, "")
+  if (h.length === 3) {
+    h = h
+      .split("")
+      .map((c) => c + c)
+      .join("")
+  }
+  const r = parseInt(h.slice(0, 2), 16) / 255
+  const g = parseInt(h.slice(2, 4), 16) / 255
+  const b = parseInt(h.slice(4, 6), 16) / 255
+  const a = h.length >= 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1
+  return [r, g, b, a]
+}
+
+/** Manifest sids in insertion order (drives the slot-control list ordering). */
+export function listSlotSids(slots: Record<string, unknown>): string[] {
+  return Object.keys(slots ?? {})
+}
+
+// ── Slot → app-field derivation (Phase 3 — single source of truth) ────────────
+//
+// `deriveLottieSlotFields` turns a lottie-graphic plan's slot manifest into
+// ExposableField-shaped descriptors. ONE function feeds three surfaces: the
+// editor's publish picker, the published-app runtime, and the backend MCP
+// schema extractor — so the set of slots an app exposes can never drift between
+// them. It deliberately mirrors `describeSlotControl`'s classification (the
+// editor's live slot controls use the same source of truth).
+
+/** Prefix for the synthetic field key of a derived slot field: `slot:<sid>`. */
+export const LOTTIE_SLOT_FIELD_PREFIX = "slot:"
+
+/** "primaryColor" → "Primary Color"; "bar_size" → "Bar Size". */
+export function humanizeSlotSid(sid: string): string {
+  return sid
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+/** ExposableField-shaped descriptor derived from one slot. */
+export interface LottieSlotField {
+  /** Synthetic field key: `slot:<sid>`. */
+  key: string
+  /** Humanized sid (camelCase / snake_case → Title Case). */
+  label: string
+  /** Maps onto the `ExposableField.type` members used in apps. */
+  type: "color" | "text" | "slider"
+  min?: number
+  max?: number
+  step?: number
+  /** Hex string for color; raw value for text/number. */
+  defaultValue?: unknown
+}
+
+/**
+ * Derive ExposableField-shaped descriptors from a motion-graphics node's plan.
+ *
+ * Returns [] unless `motionPlan.planType === "lottie-graphic"` and `slots` is a
+ * non-empty object — the elements engine and absent plans expose nothing.
+ *
+ * Per slot, via `describeSlotControl`:
+ *   - color  → `{ type: "color", defaultValue: rgbaArrayToHex(value) }`
+ *   - text   → `{ type: "text", defaultValue: value }`
+ *   - number → `{ type: "slider", min, max, step, defaultValue: value }`
+ *             (0–1 values → 0..1 step 0.01; larger → 0..ceil(value*2) step 1)
+ *   - point / null → SKIPPED. Point-kind slots are intentionally not exposed in
+ *     apps (no paired-number card; positions are rarely end-user-meaningful).
+ */
+export function deriveLottieSlotFields(
+  motionPlan: Record<string, unknown> | undefined,
+): LottieSlotField[] {
+  if (!motionPlan || motionPlan.planType !== "lottie-graphic") return []
+  const slots = motionPlan.slots
+  if (!isPlainObject(slots)) return []
+
+  const fields: LottieSlotField[] = []
+  for (const [sid, slot] of Object.entries(slots)) {
+    const control = describeSlotControl(slot)
+    if (!control) continue
+    const base = { key: `${LOTTIE_SLOT_FIELD_PREFIX}${sid}`, label: humanizeSlotSid(sid) }
+
+    if (control.kind === "color") {
+      fields.push({
+        ...base,
+        type: "color",
+        defaultValue: rgbaArrayToHex(control.value as number[]),
+      })
+    } else if (control.kind === "text") {
+      fields.push({ ...base, type: "text", defaultValue: control.value })
+    } else if (control.kind === "number") {
+      const value = Number(control.value)
+      const isUnit = value <= 1
+      fields.push({
+        ...base,
+        type: "slider",
+        min: 0,
+        max: isUnit ? 1 : Math.ceil(value * 2) || 100,
+        step: isUnit ? 0.01 : 1,
+        defaultValue: control.value,
+      })
+    }
+    // point / unrecognized kinds are intentionally not exposed.
+  }
+  return fields
+}