@nodaro/shared 3.4.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/image-overlay-credits.test.ts

@@ -0,0 +1,24 @@
+/**
+ * The worked examples here are repeated verbatim in
+ * docs/nodes/processing-video/image-overlay.md — change both or neither.
+ */
+import { describe, it, expect } from "vitest"
+import { imageOverlayCredits, imageOverlayBillableVariants, IMAGE_OVERLAY_BASE_CREDITS, IMAGE_OVERLAY_VARIANT_CREDITS } from "../credit-estimators/image-overlay"
+import { OVERLAY_PLATFORM_IDS } from "../image-overlay-platforms"
+
+describe("imageOverlayCredits", () => {
+  it("base + 2 per extra platform: 0 → 10, 2 → 14, all twelve → 34", () => {
+    expect(IMAGE_OVERLAY_BASE_CREDITS).toBe(10)
+    expect(IMAGE_OVERLAY_VARIANT_CREDITS).toBe(2)
+    expect(imageOverlayCredits(undefined)).toBe(10)
+    expect(imageOverlayCredits([])).toBe(10)
+    expect(imageOverlayCredits(["instagram-post", "youtube-thumbnail"])).toBe(14)
+    expect(OVERLAY_PLATFORM_IDS.length).toBe(12)
+    expect(imageOverlayCredits(OVERLAY_PLATFORM_IDS)).toBe(34)
+  })
+
+  it("counts only distinct, real platform ids — duplicates and junk are free because they are not rendered", () => {
+    expect(imageOverlayBillableVariants(["instagram-post", "instagram-post", 7, "not-a-platform", "x-header"])).toEqual(["instagram-post", "x-header"])
+    expect(imageOverlayCredits(["instagram-post", "instagram-post", 7, "not-a-platform", "x-header"])).toBe(14)
+  })
+})

package/src/__tests__/scene3d-v2.test.ts

@@ -364,6 +364,30 @@ describe("scene3d v2 — entities", () => {
     expectRejects(plan, 'declares anchor "roof" twice')
   })
 
+  it("round-trips an explicit node-local anchor on an asset", () => {
+    const plan = planV2()
+    const anchor = { name: "door.tip", nodeName: "car/door.hinge", position: [1, 0, 0] as [number, number, number] }
+    plan.objects[1].anchors = [anchor]
+    expect(scene3DPlanV2Schema.parse(JSON.parse(JSON.stringify(plan))).objects[1].anchors).toEqual([anchor])
+  })
+
+  it("rejects a bound anchor on a primitive", () => {
+    const plan = planV2()
+    plan.objects[2].anchors = [{ name: "top", nodeName: "mesh", position: [0, 1, 0] }]
+    expectRejects(plan, "can bind anchor nodes only with an asset visual")
+  })
+
+  it("bounds raw anchor node names without imposing the root-ID charset", () => {
+    const plan = planV2()
+    plan.objects[1].anchors = [{ name: "tip", nodeName: `${"a".repeat(64)}/${"b".repeat(64)}`,
+      position: [0, 0, 0] }]
+    expect(scene3DPlanV2Schema.safeParse(plan).success).toBe(true)
+    for (const nodeName of ["", "bad\nname", "x".repeat(SCENE3D_V2_LIMITS.maxNodeNameLength + 1)]) {
+      plan.objects[1].anchors = [{ name: "tip", nodeName, position: [0, 0, 0] }]
+      expect(scene3DPlanV2Schema.safeParse(plan).success).toBe(false)
+    }
+  })
+
   it("bounds an animation binding to the timeline", () => {
     const past = planV2()
     past.objects[1].visual = {

package/src/credit-estimators/image-overlay.ts

@@ -0,0 +1,30 @@
+import { overlayPlatformById } from "../image-overlay-platforms.js"
+
+/**
+ * Image Overlay pricing — one formula shared by the backend route
+ * (creditGuard computeCredits), the orchestrator's reservation override, the
+ * workflow estimator and the canvas Run button, so every surface quotes and
+ * charges the same number.
+ *
+ *   credits = BASE + PER_VARIANT × (number of distinct, valid platform ids)
+ *
+ * The base covers the composite and its mask; every extra platform render is
+ * one more resize + encode + upload. Worked examples (pinned by the tests and
+ * repeated in docs/nodes/processing-video/image-overlay.md — keep them equal):
+ *   0 variants → 10,  2 → 14,  12 (every platform) → 34.
+ */
+export const IMAGE_OVERLAY_BASE_CREDITS = 10
+export const IMAGE_OVERLAY_VARIANT_CREDITS = 2
+
+/** Distinct platform ids the registry knows — the count the price is built from. */
+export function imageOverlayBillableVariants(variants: ReadonlyArray<unknown> | undefined): string[] {
+  const seen = new Set<string>()
+  for (const v of variants ?? []) {
+    if (typeof v === "string" && overlayPlatformById(v)) seen.add(v)
+  }
+  return [...seen]
+}
+
+export function imageOverlayCredits(variants: ReadonlyArray<unknown> | undefined): number {
+  return IMAGE_OVERLAY_BASE_CREDITS + IMAGE_OVERLAY_VARIANT_CREDITS * imageOverlayBillableVariants(variants).length
+}

package/src/credit-estimators/index.ts

@@ -7,6 +7,13 @@ export {
   assembleNarratedVideoCredits,
 } from "./video-utils.js"
 
+export {
+  IMAGE_OVERLAY_BASE_CREDITS,
+  IMAGE_OVERLAY_VARIANT_CREDITS,
+  imageOverlayBillableVariants,
+  imageOverlayCredits,
+} from "./image-overlay.js"
+
 export type {
   LoopVideoEstimatorInput,
   TrimVideoEstimatorInput,

package/src/image-overlay-layers.ts

@@ -0,0 +1,149 @@
+/**
+ * Image Overlay — the layer KINDS a node can carry beyond a wired image, and
+ * the wire contract for each. Shared by the route's Zod, the MCP tool, the
+ * worker's renderer and the canvas preview/editor, so a field exists once.
+ *
+ *   image — a wired picture (logo, cut-out, sticker); placement + effects
+ *   text  — real typography from a bundled font (rendered server-side from
+ *           the same TTF the browser previews with, so the two agree)
+ *   qr    — a QR code generated from a payload string
+ *   shape — a flat rectangle / pill / circle / ribbon (badges, price tags,
+ *           text backgrounds)
+ *
+ * Sizes are PERCENT of the base image (text `fontSize` = % of base height),
+ * pixels are only used where a real pixel count is the honest unit (stroke,
+ * padding, radius, blur — on the base image).
+ */
+import { z } from "zod"
+
+export const OVERLAY_LAYER_KINDS = ["image", "text", "qr", "shape"] as const
+export type OverlayLayerKind = (typeof OVERLAY_LAYER_KINDS)[number]
+
+export const OVERLAY_TEXT_ALIGNS = ["left", "center", "right"] as const
+export type OverlayTextAlign = (typeof OVERLAY_TEXT_ALIGNS)[number]
+
+import { OVERLAY_SHAPES } from "./image-overlay-shapes.js"
+
+export const OVERLAY_IMAGE_MASKS = ["none", "circle"] as const
+export type OverlayImageMask = (typeof OVERLAY_IMAGE_MASKS)[number]
+
+/**
+ * The bundled font faces. `file` names the TTF under
+ * backend/src/assets/fonts (served at GET /v1/fonts/:file for the preview);
+ * `variable` faces carry a `wght` axis and honour any weight 100–900, static
+ * faces render at their single weight. `scripts` tells the picker which faces
+ * can set Hebrew / Arabic.
+ */
+export const OVERLAY_FONTS = [
+  { id: "inter", family: "Inter", file: "Inter.ttf", variable: true, scripts: ["latin"], category: "sans" },
+  { id: "montserrat", family: "Montserrat", file: "Montserrat.ttf", variable: true, scripts: ["latin"], category: "sans" },
+  { id: "space-grotesk", family: "Space Grotesk", file: "SpaceGrotesk.ttf", variable: true, scripts: ["latin"], category: "sans" },
+  { id: "playfair-display", family: "Playfair Display", file: "PlayfairDisplay.ttf", variable: true, scripts: ["latin"], category: "serif" },
+  { id: "oswald", family: "Oswald", file: "Oswald.ttf", variable: true, scripts: ["latin"], category: "display" },
+  { id: "bebas-neue", family: "Bebas Neue", file: "BebasNeue.ttf", variable: false, scripts: ["latin"], category: "display" },
+  { id: "anton", family: "Anton", file: "Anton.ttf", variable: false, scripts: ["latin"], category: "display" },
+  { id: "pacifico", family: "Pacifico", file: "Pacifico.ttf", variable: false, scripts: ["latin"], category: "script" },
+  { id: "rubik", family: "Rubik", file: "Rubik.ttf", variable: true, scripts: ["latin", "hebrew"], category: "sans" },
+  { id: "heebo", family: "Heebo", file: "Heebo.ttf", variable: true, scripts: ["latin", "hebrew"], category: "sans" },
+] as const
+
+export type OverlayFontId = (typeof OVERLAY_FONTS)[number]["id"]
+export const OVERLAY_FONT_IDS = OVERLAY_FONTS.map((f) => f.id) as unknown as readonly [OverlayFontId, ...OverlayFontId[]]
+
+export function overlayFontById(id: string): (typeof OVERLAY_FONTS)[number] | undefined {
+  return OVERLAY_FONTS.find((f) => f.id === id)
+}
+
+const hex6 = z.string().regex(/^#[0-9a-fA-F]{6}$/, "Expected a #RRGGBB color")
+
+export const overlayStrokeSchema = z.object({
+  /** px on the base image */
+  width: z.number().min(0).max(50),
+  color: hex6,
+})
+
+/** Text layer style — everything the renderer and the preview need. */
+export const overlayTextStyleSchema = z.object({
+  text: z.string().min(1).max(500),
+  fontId: z.enum(OVERLAY_FONT_IDS).default("inter"),
+  fontWeight: z.number().int().min(100).max(900).default(700),
+  /** % of the BASE height */
+  fontSize: z.number().min(1).max(50).default(8),
+  color: hex6.default("#ffffff"),
+  align: z.enum(OVERLAY_TEXT_ALIGNS).default("center"),
+  /** em */
+  letterSpacing: z.number().min(-0.2).max(1).default(0),
+  lineHeight: z.number().min(0.8).max(2.5).default(1.15),
+  uppercase: z.boolean().default(false),
+  stroke: overlayStrokeSchema.optional(),
+  /** A filled box behind the text — a pill, a badge, a lower third. */
+  background: z
+    .object({
+      color: hex6,
+      opacity: z.number().min(0).max(1).default(1),
+      /** px on the base image */
+      padding: z.number().min(0).max(300).default(24),
+      /** px corner radius; a huge value makes a pill */
+      radius: z.number().min(0).max(1000).default(0),
+    })
+    .optional(),
+})
+export type OverlayTextStyle = z.infer<typeof overlayTextStyleSchema>
+
+export const overlayQrStyleSchema = z.object({
+  /** The link / text the code opens. May be empty ONLY while `fromInput` is
+   *  set — the run then fills it from the node's "QR link" text handle. */
+  text: z.string().max(2000).default(""),
+  /** Take the payload from the node's QR link handle (a Text node, a List
+   *  column, any text output) instead of this style's `text`. */
+  fromInput: z.boolean().optional(),
+  color: hex6.default("#000000"),
+  /** Absent = transparent quiet zone and background. */
+  background: hex6.optional(),
+  /** Quiet-zone modules */
+  margin: z.number().int().min(0).max(8).default(1),
+})
+export type OverlayQrStyle = z.infer<typeof overlayQrStyleSchema>
+
+export const overlayShapeStyleSchema = z.object({
+  shape: z.enum(OVERLAY_SHAPES).default("rect"),
+  color: hex6.default("#ff0073"),
+  stroke: overlayStrokeSchema.optional(),
+})
+export type OverlayShapeStyle = z.infer<typeof overlayShapeStyleSchema>
+
+/** Finishing for IMAGE layers: cut to a circle, fade the edges, outline, glow. */
+export const overlayImageEffectsSchema = z.object({
+  mask: z.enum(OVERLAY_IMAGE_MASKS).optional(),
+  /** px on the base image — edge fade width */
+  feather: z.number().min(0).max(500).optional(),
+  stroke: overlayStrokeSchema.optional(),
+  glow: z
+    .object({
+      blur: z.number().min(0).max(200),
+      color: hex6,
+      opacity: z.number().min(0).max(1),
+    })
+    .optional(),
+})
+export type OverlayImageEffects = z.infer<typeof overlayImageEffectsSchema>
+
+/** Sensible starting points for a freshly added non-image layer. */
+export const DEFAULT_OVERLAY_TEXT: OverlayTextStyle = {
+  text: "Your text",
+  fontId: "inter",
+  fontWeight: 700,
+  fontSize: 8,
+  color: "#ffffff",
+  align: "center",
+  letterSpacing: 0,
+  lineHeight: 1.15,
+  uppercase: false,
+}
+export const DEFAULT_OVERLAY_QR: OverlayQrStyle = { text: "https://nodaro.ai", color: "#000000", background: "#ffffff", margin: 1 }
+export const DEFAULT_OVERLAY_SHAPE: OverlayShapeStyle = { shape: "pill", color: "#ff0073" }
+
+/** True when the string carries a right-to-left script (Hebrew / Arabic ranges). */
+export function isRtlText(text: string): boolean {
+  return /[֐-׿؀-ۿݐ-ݿࢠ-ࣿיִ-﷿ﹰ-]/.test(text)
+}

package/src/image-overlay-platforms.ts

@@ -0,0 +1,88 @@
+/**
+ * Image Overlay — platform canvas presets. Picking one sets the output canvas
+ * to the platform's pixel size and draws its SAFE AREA in the preview (the
+ * part of the image every surface actually shows — a YouTube banner is
+ * cropped to a 1546×423 strip on phones, a LinkedIn personal cover has the
+ * profile photo over its bottom-left, an Instagram story hides the top and
+ * bottom under the UI). The same ids drive "export also for" — one
+ * composition rendered into several platform sizes in one run.
+ *
+ * Safe areas are FRACTIONS of the canvas (x, y, w, h in 0..1). Sizes are the
+ * platforms' documented recommendations as of 2026-09.
+ */
+export interface OverlayPlatformPreset {
+  readonly id: string
+  readonly label: string
+  readonly width: number
+  readonly height: number
+  /** The always-visible region, as fractions of the canvas. Absent = whole canvas. */
+  readonly safe?: { readonly x: number; readonly y: number; readonly w: number; readonly h: number }
+  /** Per-device viewports drawn as nested boxes (the YouTube banner shows TV /
+   *  desktop / every device). `safe` is the innermost one. Ids are stable
+   *  keys the UI localises; absent = only `safe` is drawn. */
+  readonly zones?: readonly OverlayPlatformZone[]
+  readonly note?: string
+}
+
+export interface OverlayPlatformZone {
+  readonly id: "tv" | "desktop" | "all"
+  readonly x: number
+  readonly y: number
+  readonly w: number
+  readonly h: number
+}
+
+const YT_BANNER_ALL = { x: (2560 - 1546) / 2 / 2560, y: (1440 - 423) / 2 / 1440, w: 1546 / 2560, h: 423 / 1440 }
+
+export const OVERLAY_PLATFORMS: readonly OverlayPlatformPreset[] = [
+  { id: "youtube-thumbnail", label: "YouTube thumbnail", width: 1280, height: 720, safe: { x: 0, y: 0, w: 1, h: 0.86 }, note: "The bottom-right corner carries the duration badge." },
+  {
+    id: "youtube-banner", label: "YouTube channel banner", width: 2560, height: 1440,
+    safe: YT_BANNER_ALL,
+    zones: [
+      { id: "tv", x: 0, y: 0, w: 1, h: 1 },
+      { id: "desktop", x: 0, y: (1440 - 423) / 2 / 1440, w: 1, h: 423 / 1440 },
+      { id: "all", ...YT_BANNER_ALL },
+    ],
+    note: "TV shows the whole banner, desktop a 2560×423 strip, phones only the centre 1546×423.",
+  },
+  { id: "linkedin-company", label: "LinkedIn company cover", width: 1128, height: 191, safe: { x: 0.18, y: 0, w: 0.82, h: 1 }, note: "The company logo sits over the left ~200px." },
+  { id: "linkedin-personal", label: "LinkedIn personal cover", width: 1584, height: 396, safe: { x: 0.24, y: 0, w: 0.76, h: 0.9 }, note: "The profile photo covers the bottom-left." },
+  { id: "x-header", label: "X / Twitter header", width: 1500, height: 500, safe: { x: 0.2, y: 0.05, w: 0.78, h: 0.9 }, note: "The profile photo covers the bottom-left." },
+  { id: "facebook-cover", label: "Facebook page cover", width: 820, height: 312, safe: { x: 0.05, y: 0.08, w: 0.9, h: 0.84 } },
+  { id: "instagram-post", label: "Instagram post (1:1)", width: 1080, height: 1080 },
+  { id: "instagram-portrait", label: "Instagram post (4:5)", width: 1080, height: 1350 },
+  { id: "instagram-story", label: "Instagram / TikTok story (9:16)", width: 1080, height: 1920, safe: { x: 0, y: 250 / 1920, w: 1, h: (1920 - 500) / 1920 }, note: "The top and bottom 250px sit under the story UI." },
+  { id: "open-graph", label: "Link preview (Open Graph)", width: 1200, height: 630 },
+  { id: "presentation", label: "Presentation slide (16:9)", width: 1920, height: 1080 },
+  { id: "a4-print", label: "Print A4 @300dpi", width: 2480, height: 3508, safe: { x: 0.05, y: 0.05, w: 0.9, h: 0.9 }, note: "5% bleed margin." },
+] as const
+
+export type OverlayPlatformId = (typeof OVERLAY_PLATFORMS)[number]["id"]
+export const OVERLAY_PLATFORM_IDS = OVERLAY_PLATFORMS.map((p) => p.id) as unknown as readonly [OverlayPlatformId, ...OverlayPlatformId[]]
+
+export function overlayPlatformById(id: string | undefined | null): OverlayPlatformPreset | undefined {
+  return id ? OVERLAY_PLATFORMS.find((p) => p.id === id) : undefined
+}
+
+/** How many extra platform renders one run may produce — every platform in
+ *  the registry, so "all of them" is one run. The node's handle column is
+ *  sized for this (image-overlay-handles.test.ts pins it). */
+export const OVERLAY_MAX_VARIANTS = OVERLAY_PLATFORMS.length
+
+/**
+ * Every platform ticked under "export also for" is ALSO a source handle on
+ * the node — `variant:<platformId>` — so the X header can feed an X publisher
+ * while the YouTube thumbnail feeds YouTube, in one run. The main `image`
+ * handle stays the primary composite.
+ */
+export const OVERLAY_VARIANT_HANDLE_PREFIX = "variant:"
+export function overlayVariantHandle(platformId: string): string {
+  return `${OVERLAY_VARIANT_HANDLE_PREFIX}${platformId}`
+}
+/** The platform id a variant handle names, or null for any other handle. */
+export function overlayVariantIdFromHandle(handle: string | null | undefined): string | null {
+  if (!handle || !handle.startsWith(OVERLAY_VARIANT_HANDLE_PREFIX)) return null
+  const id = handle.slice(OVERLAY_VARIANT_HANDLE_PREFIX.length)
+  return overlayPlatformById(id) ? id : null
+}

package/src/image-overlay-shapes.ts

@@ -0,0 +1,89 @@
+/**
+ * Flat-shape vocabulary for Image Overlay shape layers, and the ONE geometry
+ * both renderers draw: the server serialises the element to SVG for sharp,
+ * the editor renders the same element in an inline <svg> — so the stage shows
+ * exactly the shape the run produces. Every shape fills its w × h box.
+ */
+
+export const OVERLAY_SHAPES = [
+  "rect",
+  "rounded",
+  "pill",
+  "circle",
+  "ribbon",
+  "triangle",
+  "diamond",
+  "hexagon",
+  "star",
+  "burst",
+  "arrow",
+] as const
+export type OverlayShape = (typeof OVERLAY_SHAPES)[number]
+
+export interface OverlayShapeElement {
+  readonly tag: "rect" | "ellipse" | "polygon"
+  /** Plain SVG attributes (already valid React props too: rx, cx, points…). */
+  readonly attrs: Readonly<Record<string, number | string>>
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100
+}
+
+function points(list: ReadonlyArray<readonly [number, number]>): string {
+  return list.map(([x, y]) => `${round(x)},${round(y)}`).join(" ")
+}
+
+/** A radial polygon: `n` outer points at (rx, ry), an inner point between each at `inner` × radius. */
+function radial(cx: number, cy: number, rx: number, ry: number, n: number, inner: number): string {
+  const pts: Array<readonly [number, number]> = []
+  for (let i = 0; i < n * 2; i++) {
+    const a = -Math.PI / 2 + (i * Math.PI) / n
+    const f = i % 2 === 0 ? 1 : inner
+    pts.push([cx + Math.cos(a) * rx * f, cy + Math.sin(a) * ry * f])
+  }
+  return points(pts)
+}
+
+/**
+ * The element for `shape` inside a w × h box. `inset` keeps a stroke inside
+ * the box (pass half the stroke width); geometry is identical for inset 0.
+ */
+export function overlayShapeElement(shape: OverlayShape, w: number, h: number, inset = 0): OverlayShapeElement {
+  const i = Math.max(0, inset)
+  const iw = Math.max(0, w - 2 * i)
+  const ih = Math.max(0, h - 2 * i)
+  const cx = w / 2
+  const cy = h / 2
+  switch (shape) {
+    case "rounded":
+      return { tag: "rect", attrs: { x: i, y: i, width: iw, height: ih, rx: round(Math.min(iw, ih) * 0.18) } }
+    case "pill":
+      return { tag: "rect", attrs: { x: i, y: i, width: iw, height: ih, rx: round(ih / 2) } }
+    case "circle":
+      return { tag: "ellipse", attrs: { cx, cy, rx: round(iw / 2), ry: round(ih / 2) } }
+    case "ribbon": {
+      // A banner with notched ends — the "50% OFF" strip.
+      const notch = Math.min(w / 4, h / 2)
+      return { tag: "polygon", attrs: { points: points([[i, i], [w - i, i], [w - notch, cy], [w - i, h - i], [i, h - i], [notch, cy]]) } }
+    }
+    case "triangle":
+      return { tag: "polygon", attrs: { points: points([[cx, i], [w - i, h - i], [i, h - i]]) } }
+    case "diamond":
+      return { tag: "polygon", attrs: { points: points([[cx, i], [w - i, cy], [cx, h - i], [i, cy]]) } }
+    case "hexagon":
+      return { tag: "polygon", attrs: { points: points([[w * 0.25, i], [w * 0.75, i], [w - i, cy], [w * 0.75, h - i], [w * 0.25, h - i], [i, cy]]) } }
+    case "star":
+      return { tag: "polygon", attrs: { points: radial(cx, cy, iw / 2, ih / 2, 5, 0.42) } }
+    case "burst":
+      return { tag: "polygon", attrs: { points: radial(cx, cy, iw / 2, ih / 2, 14, 0.82) } }
+    case "arrow":
+      // Right-pointing: a shaft half the box tall, a head on the last 40 %.
+      return {
+        tag: "polygon",
+        attrs: { points: points([[i, h * 0.25], [w * 0.6, h * 0.25], [w * 0.6, i], [w - i, cy], [w * 0.6, h - i], [w * 0.6, h * 0.75], [i, h * 0.75]]) },
+      }
+    default:
+      return { tag: "rect", attrs: { x: i, y: i, width: iw, height: ih } }
+  }
+}

package/src/index.ts

@@ -1004,6 +1004,9 @@ export * from "./audio-fx-presets.js"
 
 // --- Remotion renderer: supported font names (shared with backend Zod validation) ---
 export * from "./supported-fonts.js"
+export * from "./image-overlay-layers.js"
+export * from "./image-overlay-shapes.js"
+export * from "./image-overlay-platforms.js"
 // --- Shot-sequence visual elements (text/shape/image; shared with backend Zod validation) ---
 export type { ShotElement, ShotTextElement, ShotShapeElement, ShotImageElement } from "./shot-element.js"
 // --- Entity image-handle parity (entity `image` source handle → plain image) ---

package/src/scene3d-v2-plan.ts

@@ -155,6 +155,12 @@ function checkEntities(plan: Scene3DPlanV2, byId: Map<string, Scene3DEntityV2>,
 
     const anchorNames = new Set<string>()
     ;(entity.anchors ?? []).forEach((anchor, anchorIndex) => {
+      if (anchor.nodeName !== undefined && entity.visual.kind !== "asset") {
+        issues.push({
+          path: at("anchors", anchorIndex, "nodeName"),
+          message: `entity "${entity.id}" can bind anchor nodes only with an asset visual`,
+        })
+      }
       if (anchorNames.has(anchor.name)) {
         issues.push({
           path: at("anchors", anchorIndex, "name"),

package/src/scene3d-v2.ts

@@ -123,6 +123,7 @@ export const SCENE3D_V2_LIMITS = {
   maxIdLength: SCENE3D_LIMITS.maxIdLength,
   maxAssetIdLength: 128,
   maxNodeIdLength: 128,
+  maxNodeNameLength: 256,
   maxNameLength: SCENE3D_LIMITS.maxNameLength,
   maxLabelLength: SCENE3D_LIMITS.maxNameLength,
   maxMaterialNameLength: 120,
@@ -257,13 +258,17 @@ export type Scene3DClayLightingPreset = (typeof SCENE3D_CLAY_LIGHTING_PRESETS)[n
 // Types
 // ---------------------------------------------------------------------------
 
-/** A stable contact/selection location in entity-local space. Names are free
+/** A stable contact/selection location in entity-local space, or in the local
+ *  space of an explicitly bound GLB node. Names are free
  *  structural labels (`face`, `seat`, `wheel.frontLeft`, `roof`, `lookAt`) —
  *  human anatomy is never required. */
 export interface Scene3DAnchor {
   name: string
   position: Vec3
-  /** Euler XYZ radians. Absent = identity orientation. */
+  /** Owned raw GLB node name. When present, position/rotation use that node's
+   *  local coordinates and follow its animation. Only asset visuals bind nodes. */
+  nodeName?: string
+  /** Euler XYZ radians in the same space as position. Absent = identity. */
   rotation?: Vec3
 }
 
@@ -447,6 +452,10 @@ export const scene3DNodeIdSchema = z
   .max(SCENE3D_V2_LIMITS.maxNodeIdLength)
   .regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/, "node id must be an exporter-generated stable id")
 
+/** Subparts retain raw GLB names, including separators that a root ID forbids. */
+export const scene3DNodeNameSchema = z.string().min(1).max(SCENE3D_V2_LIMITS.maxNodeNameLength)
+  .regex(/^[^\u0000-\u001f\u007f]+$/, "node name must not contain control characters")
+
 export const scene3DSha256Schema = z
   .string()
   .regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters")
@@ -492,6 +501,7 @@ export const scene3DAnchorSchema = z
   .object({
     name: scene3DAnchorNameSchema,
     position: vec3Schema,
+    nodeName: scene3DNodeNameSchema.optional(),
     rotation: rotationVec3Schema.optional(),
   })
   .strict()