@nodaro/shared 3.1.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "3.1.0",
+  "version": "3.4.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__/scene3d-base-visibility.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest"
+import { scene3DPlanV2Schema } from "../scene3d-v2-plan.js"
+import { applyScene3DV2EditOperations } from "../scene3d-v2-edit.js"
+import { computeScene3DPlanV2ContentHash, verifyScene3DPlanV2ContentHash } from "../scene3d-v2-resources.js"
+import { planV2 } from "./scene3d-v2-fixtures.js"
+
+describe("baked entity visibility", () => {
+  it("round-trips false without adding a default to existing revisions", async () => {
+    const original = planV2()
+    const hidden = { ...original, objects: original.objects.map(e => ({ ...e, visible: false })) }
+    expect(scene3DPlanV2Schema.parse(hidden).objects.every(e => e.visible === false)).toBe(true)
+    expect(scene3DPlanV2Schema.parse(original).objects.every(e => !("visible" in e))).toBe(true)
+    expect(await computeScene3DPlanV2ContentHash(hidden)).not.toBe(await computeScene3DPlanV2ContentHash(original))
+    expect(scene3DPlanV2Schema.safeParse({ ...hidden, objects: hidden.objects.map(e => ({ ...e, visible: "false" })) }).success).toBe(false)
+  })
+
+  it("keeps baked visibility when a temporary show override is added and removed", async () => {
+    const original = planV2()
+    const hidden = { ...original, overrides: [], objects: original.objects.map(e => ({ ...e, visible: e.id !== "e2" })) }
+    hidden.provenance = { ...hidden.provenance, contentHash: await computeScene3DPlanV2ContentHash(hidden) }
+    const shown = await applyScene3DV2EditOperations(hidden, [{ op: "set-override", override: {
+      kind: "entity-visibility", entityId: "e2", visible: true,
+    } }], { expectedRevisionId: hidden.revisionId })
+    expect(shown.ok).toBe(true)
+    if (!shown.ok) return
+    const override = shown.plan.overrides!.find(o => o.kind === "entity-visibility")!
+    const reset = await applyScene3DV2EditOperations(shown.plan, [{ op: "remove-override", overrideId: override.id }], {
+      expectedRevisionId: shown.plan.revisionId,
+    })
+    expect(reset.ok).toBe(true)
+    if (!reset.ok) return
+    expect(reset.plan.objects.find(e => e.id === "e2")?.visible).toBe(false)
+    expect(reset.plan.overrides).toEqual([])
+    expect(await verifyScene3DPlanV2ContentHash(reset.plan)).toBe(true)
+  })
+})

package/src/__tests__/scene3d-input-assets.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest"
+import { scene3DInputAssetsForEngine, scene3DInputAssetsSchema } from "../scene3d-input-assets.js"
+import { buildPro3DRenderSource } from "../pro-3d-render.js"
+
+const asset = { id: "vehicle", revisionId: "00000000-0000-4000-8000-000000000010",
+  assetId: "00000000-0000-4000-8000-000000000011", label: "Vehicle" }
+
+describe("immutable scene input selectors", () => {
+  it("requires unique bounded selectors and excludes receipts and URLs", () => {
+    expect(scene3DInputAssetsSchema.parse([asset])).toEqual([asset])
+    for (const value of [[{ ...asset, url: "https://example.com/model.glb" }], [{ ...asset, sha256: "a".repeat(64) }],
+      [{ ...asset, revisionId: "../other" }], [{ ...asset, label: "bad\nlabel" }],
+      [asset, { ...asset, id: "another" }], [asset, { ...asset, assetId: asset.revisionId }], Array(9).fill(asset)]) {
+      expect(scene3DInputAssetsSchema.safeParse(value).success).toBe(false)
+    }
+  })
+  it("refuses Basic imports instead of silently ignoring geometry", () => {
+    for (const engine of [undefined, "basic", "unknown"]) {
+      expect(() => scene3DInputAssetsForEngine([asset], engine)).toThrow("advanced scene engine")
+    }
+    expect(scene3DInputAssetsForEngine(undefined, undefined)).toEqual([])
+    expect(scene3DInputAssetsForEngine([asset], "blender-cloud")).toEqual([asset])
+  })
+  it("carries inputs on new Pro scenes while export keeps its existing revision", () => {
+    expect(buildPro3DRenderSource({ prompt: "Drive past the camera", inputAssets: [asset] }))
+      .toEqual({ ok: true, source: { kind: "prompt", prompt: "Drive past the camera", inputAssets: [asset] } })
+    expect(buildPro3DRenderSource({ sourceMode: "scene", revisionId: asset.revisionId, inputAssets: [asset] }))
+      .toEqual({ ok: true, source: { kind: "scene", revisionId: asset.revisionId } })
+    expect(buildPro3DRenderSource({ prompt: "Drive", inputAssets: [{ ...asset, url: "https://example.com" } as never] }).ok).toBe(false)
+  })
+})

package/src/__tests__/sequence-execution.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest"
+import { assertCanvasExecutionAllowed, requiresSequenceExecution, STUDIO_DEPENDENT_FRAMES_CAPABILITY } from "../sequence-execution"
+
+describe("dependency execution boundary", () => {
+  it.each([
+    { requiredCapabilities: [STUDIO_DEPENDENT_FRAMES_CAPABILITY] },
+    { keyframeId: "A" }, { sequenceBinding: { startKeyframeId: "A", endKeyframeId: "B" } },
+    { keyframeId: null }, { sequenceBinding: null },
+  ])("refuses declared or recognizable dependency nodes: %j", (data) => {
+    expect(() => assertCanvasExecutionAllowed([{ id: "linked", data }])).toThrow(expect.objectContaining({
+      code: "sequence_execution_required", nodeIds: ["linked"],
+    }))
+  })
+  it("keeps ordinary nodes runnable and reports only the blocked nodes", () => {
+    expect(requiresSequenceExecution({ data: { provider: "wan-3", imageUrl: "start", endFrameUrl: "end" } })).toBe(false)
+    expect(() => assertCanvasExecutionAllowed([{ id: "ordinary", data: {} }])).not.toThrow()
+    expect(() => assertCanvasExecutionAllowed([{ id: "ordinary", data: {} }, { id: "linked", data: { keyframeId: "A" } }]))
+      .toThrow(expect.objectContaining({ nodeIds: ["linked"] }))
+  })
+})

package/src/index.ts

@@ -1072,4 +1072,6 @@ export {
 } from "./studio-transient.js"
 
 export * from "./scene3d-v2-edit.js"
+export { STUDIO_DEPENDENT_FRAMES_CAPABILITY, SequenceExecutionRequiredError, requiresSequenceExecution, assertCanvasExecutionAllowed } from "./sequence-execution"
 export * from "./scene3d-authoring-engine.js"
+export * from "./scene3d-input-assets.js"

package/src/pro-3d-render.ts

@@ -34,6 +34,7 @@
 import { z } from "zod"
 import { SCENE3D_LIMITS, type Scene3DReference } from "./scene3d.js"
 import { scene3DAnyPlanSchema, type Scene3DPlan } from "./scene3d-v2-plan.js"
+import { scene3DInputAssetsSchema, type Scene3DInputAsset } from "./scene3d-input-assets.js"
 
 /** Canvas/API/MCP node type. */
 export const PRO3D_RENDER_NODE_TYPE = "pro-3d-render"
@@ -140,6 +141,7 @@ export interface Pro3DRenderPromptSource {
   kind: "prompt"
   prompt: string
   references?: readonly Scene3DReference[]
+  inputAssets?: readonly Scene3DInputAsset[]
 }
 
 /**
@@ -384,6 +386,7 @@ export const pro3DRenderCoreOutputSchema = z
 
 /** What a canvas node / DAG builder holds before it can name a source. */
 export interface Pro3DRenderSourceInput {
+  inputAssets?: readonly Scene3DInputAsset[]
   /** `"scene"` selects the existing-revision path; anything else is a brief. */
   sourceMode?: string
   /** The brief, already resolved and affix-applied by the caller. */
@@ -431,9 +434,12 @@ export function buildPro3DRenderSource(input: Pro3DRenderSourceInput): Pro3DRend
     return { ok: false, message: "no brief — describe the scene, or wire a prompt in." }
   }
   const references = input.references ?? []
+  const parsedAssets = scene3DInputAssetsSchema.safeParse(input.inputAssets ?? [])
+  if (!parsedAssets.success) return { ok: false, message: "invalid scene input assets" }
   return {
     ok: true,
-    source: { kind: "prompt", prompt, ...(references.length > 0 ? { references } : {}) },
+    source: { kind: "prompt", prompt, ...(references.length > 0 ? { references } : {}),
+      ...(parsedAssets.data.length ? { inputAssets: parsedAssets.data } : {}) },
   }
 }
 

package/src/scene3d-input-assets.ts

@@ -0,0 +1,27 @@
+import { z } from "zod"
+
+/** Immutable 3D inputs are selected by revision and artifact, never by URL or caller receipt. */
+export const scene3DInputAssetSchema = z.object({
+  id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/),
+  revisionId: z.uuid(),
+  assetId: z.uuid(),
+  label: z.string().min(1).max(64).regex(/^[^\u0000-\u001f]+$/).optional(),
+}).strict()
+
+export const scene3DInputAssetsSchema = z.array(scene3DInputAssetSchema).max(8).superRefine((values, ctx) => {
+  if (new Set(values.map(value => value.id)).size !== values.length ||
+      new Set(values.map(value => value.assetId)).size !== values.length) {
+    ctx.addIssue({ code: "custom", message: "Scene input assets must have unique identities" })
+  }
+})
+
+export type Scene3DInputAsset = z.infer<typeof scene3DInputAssetSchema>
+
+/** Both workflow engines refuse unsupported imports before starting a paid Basic run. */
+export function scene3DInputAssetsForEngine(value: unknown, engine: string | undefined): Scene3DInputAsset[] {
+  const assets = scene3DInputAssetsSchema.parse(value ?? [])
+  if (assets.length && engine !== "blender-cloud" && engine !== "blender-local") {
+    throw new Error("Imported 3D assets require an advanced scene engine")
+  }
+  return assets
+}

package/src/scene3d-v2.ts

@@ -314,6 +314,8 @@ export interface Scene3DEntityV2 {
   position?: Vec3
   rotation?: Vec3
   scale?: Vec3
+  /** Baked visibility before manual overlays. Absent means visible. */
+  visible?: boolean
   /** The selection/identity chip colour. Opaque hex, sRGB. */
   identityColor?: string
   anchors?: Scene3DAnchor[]
@@ -541,6 +543,7 @@ export const scene3DEntityV2Schema = z
     position: vec3Schema.optional(),
     rotation: rotationVec3Schema.optional(),
     scale: scaleVec3Schema.optional(),
+    visible: z.boolean().optional(),
     identityColor: scene3DColorSchema.optional(),
     anchors: z.array(scene3DAnchorSchema).max(SCENE3D_V2_LIMITS.maxAnchorsPerEntity).optional(),
     capabilities: z.array(scene3DEntityCapabilitySchema).max(SCENE3D_ENTITY_CAPABILITIES.length).optional(),

package/src/sequence-execution.ts

@@ -0,0 +1,24 @@
+/** Public workflow capability marker; creative planning stays in the Studio codec. */
+export const STUDIO_DEPENDENT_FRAMES_CAPABILITY = "studio-dependent-frames-v1"
+
+export class SequenceExecutionRequiredError extends Error {
+  readonly code = "sequence_execution_required"
+  readonly statusCode = 400
+  constructor(readonly nodeIds: readonly string[]) {
+    super("Generate linked frames and clips in Studio or through its production API so the reviewed images are used.")
+    this.name = "SequenceExecutionRequiredError"
+  }
+}
+
+/** A missing declaration must not make a recognizable dependency node runnable. */
+export function requiresSequenceExecution(node: { data?: unknown }): boolean {
+  if (!node.data || typeof node.data !== "object" || Array.isArray(node.data)) return false
+  const data = node.data as Record<string, unknown>
+  return data.keyframeId !== undefined || data.sequenceBinding !== undefined
+    || (Array.isArray(data.requiredCapabilities) && data.requiredCapabilities.includes(STUDIO_DEPENDENT_FRAMES_CAPABILITY))
+}
+
+export function assertCanvasExecutionAllowed(nodes: readonly { id: string; data?: unknown }[]): void {
+  const blocked = nodes.filter(requiresSequenceExecution).map((node) => node.id)
+  if (blocked.length) throw new SequenceExecutionRequiredError(blocked)
+}