@nodaro/shared 3.0.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "3.0.0",
+  "version": "3.2.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__/presentation-utils.test.ts

@@ -12,6 +12,7 @@ import {
   getItemSortId,
   cleanOrphanedItems,
 } from "../presentation-utils.js"
+import { AUDIO_PRODUCER_TYPES, VIDEO_PRODUCER_TYPES } from "../producer-types.js"
 import type { GenericNode, GenericEdge } from "../types.js"
 import type { PresentationItem } from "../presentation-types.js"
 
@@ -1135,3 +1136,99 @@ describe("presentation-utils — action-fx", () => {
     expect(getInputFieldSchema("action-fx")).toEqual({ key: "actionFx", type: "select" })
   })
 })
+
+// ---------------------------------------------------------------------------
+// Canonical output typing — the presentation classifier vs the producer sets
+// ---------------------------------------------------------------------------
+
+/**
+ * `getOutputType` is what a published app renders from and what `/v1` app
+ * schemas and run results declare (`routes/api-tokens.ts`). A node it calls
+ * `"data"` is shown as a JSON blob instead of a player, is skipped by the
+ * lightbox media list, and is announced to API consumers with the wrong type.
+ *
+ * The literal sets in the module are the classifier's own opinion and win; the
+ * tail is derived from the producer vocabularies the canvas validators already
+ * maintain, so a node cannot be a declared video producer and be typed `"data"`
+ * at the same time.
+ */
+describe("getOutputType — derived from the producer vocabularies", () => {
+  it("types 3D Render Pro as video (it settles with the standard videoUrl)", () => {
+    expect(getOutputType("pro-3d-render")).toBe("video")
+  })
+
+  it("types every declared video producer as video", () => {
+    for (const t of VIDEO_PRODUCER_TYPES) expect([t, getOutputType(t)]).toEqual([t, "video"])
+  })
+
+  it("types every declared audio producer as audio, except the dual-mode ones the literal sets claim", () => {
+    for (const t of AUDIO_PRODUCER_TYPES) {
+      // voice-changer / voice-changer-pro / dubbing can emit video; the
+      // classifier's own list still calls them audio, which is their default.
+      expect([t, getOutputType(t)]).toEqual([t, "audio"])
+    }
+  })
+
+  it("leaves a run-time-decided producer as data — there is no honest static answer", () => {
+    expect(getOutputType("list")).toBe("data")
+    expect(getOutputType("sub-workflow")).toBe("data")
+    expect(getOutputType("split-media")).toBe("data")
+  })
+
+  it("keeps the literal sets authoritative where they and the producer sets disagree", () => {
+    // adjust-volume is in AUDIO_PRODUCER_TYPES and DYNAMIC_PRODUCER_TYPES;
+    // upload-video is a video producer AND an input node.
+    expect(getOutputType("adjust-volume")).toBe("audio")
+    expect(getOutputType("upload-video")).toBe("video")
+    expect(getOutputType("text-prompt")).toBe("text")
+  })
+})
+
+describe("published-app / API-token output mapping for 3D Render Pro", () => {
+  const proNode = mkNode("pro", "pro-3d-render", { presentationOutput: true, label: "Render" })
+
+  it("declares the app-schema output type the SDK and MCP read (mirrors routes/api-tokens.ts)", () => {
+    // The route builds `{ nodeId, label, type: getOutputType(node.type) }` for
+    // both the app schema and the run result.
+    const outputs = getOutputNodes([proNode], []).map((n) => ({
+      nodeId: n.id,
+      type: getOutputType(n.type),
+    }))
+    expect(outputs).toEqual([{ nodeId: "pro", type: "video" }])
+  })
+
+  it("is an OUTPUT, not an input — the picker must not offer it as an app input", () => {
+    expect(INPUT_NODE_TYPES.has("pro-3d-render")).toBe(false)
+    expect(getInputNodes([mkNode("pro", "pro-3d-render", { presentationVisible: true })])).toEqual([])
+  })
+})
+
+describe("legacy presentationVisible rules for a media producer", () => {
+  it("stays an output when its composition ALSO feeds something downstream", () => {
+    // The Pro node's `composition` handle commonly feeds an editor or a
+    // re-render; the legacy rule drops a node with an outgoing edge unless it
+    // produces media of its own.
+    const nodes = [
+      mkNode("pro", "pro-3d-render", { presentationVisible: true }),
+      mkNode("edit", "edit-3d-scene", {}),
+    ]
+    const out = getOutputNodes(nodes, [mkEdge("pro", "edit")])
+    expect(out.map((n) => n.id)).toEqual(["pro"])
+  })
+
+  it("applies the same rule to the other video producers the literal list forgot", () => {
+    const nodes = [
+      mkNode("gv", "generate-video", { presentationVisible: true }),
+      mkNode("cap", "add-captions", {}),
+    ]
+    expect(getOutputNodes(nodes, [mkEdge("gv", "cap")]).map((n) => n.id)).toEqual(["gv"])
+  })
+
+  it("still drops a non-media node that feeds something downstream", () => {
+    const nodes = [
+      mkNode("txt", "text-prompt", { presentationVisible: true }),
+      mkNode("gv", "generate-video", {}),
+    ]
+    expect(getOutputNodes(nodes, [mkEdge("txt", "gv")])).toEqual([])
+  })
+})

package/src/__tests__/scene3d-authoring-engine.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest"
+import {
+  SCENE3D_DEFAULT_ADVANCED_ENGINE,
+  SCENE3D_SUPPORTED_SCHEMA_VERSIONS,
+  resolveScene3DAuthoringEngine,
+} from "../index.js"
+
+/** Only the fields the resolver reads — it must not need a whole valid plan. */
+const v1Plan = { planType: "3d-scene", schemaVersion: 1 }
+const v2Plan = (engine = "blender-cloud") => ({
+  planType: "3d-scene",
+  schemaVersion: 2,
+  provenance: { engine },
+})
+
+describe("resolveScene3DAuthoringEngine", () => {
+  it("keeps a plain generate on Basic, with NO extra wire fields", () => {
+    const choice = resolveScene3DAuthoringEngine({})
+    expect(choice).toEqual({ ok: true, lane: "basic", engine: undefined, fields: {} })
+  })
+
+  it("keeps a v1 edit on Basic", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: v1Plan })
+    expect(choice.ok && choice.lane).toBe("basic")
+    expect(choice.ok && choice.fields).toEqual({})
+  })
+
+  it("sends an explicitly requested advanced engine plus the accepted versions", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      requested: "blender-cloud",
+      availableEngines: ["blender-cloud"],
+    })
+    expect(choice.ok && choice.lane).toBe("advanced")
+    expect(choice.ok && choice.fields).toEqual({
+      engine: "blender-cloud",
+      acceptedSceneSchemaVersions: [...SCENE3D_SUPPORTED_SCHEMA_VERSIONS],
+    })
+  })
+
+  it("routes a v2 edit to the advanced lane with no engine chosen", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: v2Plan() })
+    expect(choice.ok && choice.lane).toBe("advanced")
+    expect(choice.ok && choice.engine).toBe(SCENE3D_DEFAULT_ADVANCED_ENGINE)
+  })
+
+  it("keeps a v2 edit on the engine that authored it", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      plan: v2Plan("blender-local"),
+      availableEngines: ["blender-cloud", "blender-local"],
+    })
+    expect(choice.ok && choice.engine).toBe("blender-local")
+  })
+
+  it("does not send a v2 edit to an authoring engine this install dropped", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      plan: v2Plan("blender-local"),
+      availableEngines: ["blender-cloud"],
+    })
+    expect(choice.ok && choice.engine).toBe("blender-cloud")
+  })
+
+  it("REFUSES a v2 scene pointed at Basic instead of downgrading it", () => {
+    const choice = resolveScene3DAuthoringEngine({ requested: "basic", plan: v2Plan() })
+    expect(choice.ok).toBe(false)
+    expect(!choice.ok && choice.code).toBe("schema_requires_advanced")
+  })
+
+  it("REFUSES a v2 edit when the install has no advanced engine at all", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: v2Plan(), availableEngines: [] })
+    expect(!choice.ok && choice.code).toBe("advanced_unavailable")
+  })
+
+  it("REFUSES an explicit engine this install does not serve — never falls back to Basic", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      requested: "blender-local",
+      availableEngines: ["blender-cloud"],
+    })
+    expect(!choice.ok && choice.code).toBe("engine_unavailable")
+  })
+
+  it("REFUSES an explicit engine on a v2 scene the same way", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      requested: "blender-local",
+      plan: v2Plan(),
+      availableEngines: ["blender-cloud"],
+    })
+    expect(!choice.ok && choice.code).toBe("engine_unavailable")
+  })
+
+  it("REFUSES an engine name the contract does not know", () => {
+    const choice = resolveScene3DAuthoringEngine({ requested: "unknown-renderer" })
+    expect(!choice.ok && choice.code).toBe("unknown_engine")
+  })
+
+  it("REFUSES a scene claiming a schema version nothing here can author against", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: { planType: "3d-scene", schemaVersion: 3 } })
+    expect(!choice.ok && choice.code).toBe("unsupported_schema_version")
+  })
+
+  it("stays permissive when availability is UNKNOWN — the route refuses honestly", () => {
+    const choice = resolveScene3DAuthoringEngine({ requested: "blender-local" })
+    expect(choice.ok && choice.engine).toBe("blender-local")
+  })
+})

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/index.ts

@@ -1061,6 +1061,8 @@ export * from "./scene3d-v2.js"
 export * from "./scene3d-v2-plan.js"
 export * from "./scene3d-v2-resources.js"
 export * from "./scene3d-camera-track.js"
+// --- 3D Render Pro: one durable operation, scene + video in one result ---
+export * from "./pro-3d-render.js"
 
 // --- transient studio keys — the public share read strips them ---
 export {
@@ -1070,3 +1072,4 @@ export {
 } from "./studio-transient.js"
 
 export * from "./scene3d-v2-edit.js"
+export * from "./scene3d-authoring-engine.js"

package/src/model-constants.ts

@@ -1121,6 +1121,12 @@ export const ASPECT_RATIO_DIMENSIONS: Record<string, { width: number; height: nu
   "9:16": { width: 1080, height: 1920 },
   "1:1": { width: 1080, height: 1080 },
   "4:5": { width: 1080, height: 1350 },
+  // Ultra-wide. 1680x720 rather than a 1920-wide pair because the Scene3D v2
+  // admission bounds require even integers on both axes and 1920/(21/9) is
+  // odd; 1680x720 is the pair the scene contract names as supported. Additive:
+  // every consumer here is a keyed lookup with a fallback, and a node only
+  // reaches this entry if its own aspect enum offers 21:9 (today, Pro 3D).
+  "21:9": { width: 1680, height: 720 },
 }
 
 /** Motion transfer providers */
@@ -2637,6 +2643,10 @@ export const COMPOSER_PLAN_MAP: Readonly<Record<string, { planType: string; plan
   // render-video routes either one to the `3d-scene` renderer unchanged.
   "generate-3d-scene": { planType: "3d-scene", planField: "scenePlan" },
   "edit-3d-scene": { planType: "3d-scene", planField: "scenePlan" },
+  // 3D Render Pro authors the SAME `scenePlan` revision (v2) alongside its
+  // MP4, so the render-only re-run reads it through this map exactly as it
+  // reads a Basic revision — no second plan lane, no second render path.
+  "pro-3d-render": { planType: "3d-scene", planField: "scenePlan" },
 }
 
 /** Every composer plan-field name, derived from COMPOSER_PLAN_MAP (single source

package/src/node-mappable-fields.ts

@@ -46,6 +46,7 @@ export const NODE_MAPPABLE_FIELDS: Readonly<Record<string, readonly string[]>> =
   "3d-title":            ["titlePrompt"],
   "generate-3d-scene":   ["scenePrompt"],
   "edit-3d-scene":       ["editPrompt"],
+  "pro-3d-render":       ["scenePrompt"],
   "motion-graphics":     ["motionPrompt"],
   "generate-script":     ["styleGuide"],
   "speech-to-video":     ["prompt", "negativePrompt"],

package/src/presentation-utils.ts

@@ -5,6 +5,7 @@
 
 import type { GenericNode, GenericEdge } from "./types.js"
 import type { PresentationItem } from "./presentation-types.js"
+import { AUDIO_PRODUCER_TYPES, VIDEO_PRODUCER_TYPES } from "./producer-types.js"
 
 // ---------------------------------------------------------------------------
 // Node type sets
@@ -84,6 +85,15 @@ const NON_OUTPUT_TYPES = new Set([
   "component",
 ])
 
+/**
+ * Node types that count as an output even when something is wired to their
+ * output handle (the legacy `presentationVisible` rule below).
+ *
+ * A hand-kept list, and one the platform has outgrown: it is unioned at the use
+ * site with the producer vocabularies the canvas validators already maintain
+ * (see `isMediaProducingType`), so a new media node is covered by the set it
+ * must join anyway rather than by remembering to edit this one.
+ */
 const MEDIA_PRODUCING_TYPES = new Set([
   "generate-image",
   "edit-image",
@@ -121,6 +131,11 @@ const IMAGE_OUTPUT_TYPES = new Set([
   "upload-image",
 ])
 
+/**
+ * Video-output types NOT already declared by `VIDEO_PRODUCER_TYPES` — the two
+ * are unioned in `getOutputType`, which is where the reading order (and the
+ * reason the literal sets win) is documented.
+ */
 const VIDEO_OUTPUT_TYPES = new Set([
   "image-to-video", "text-to-video", "video-to-video", "extend-video",
   "render-video", "video-composer", "after-effects", "lottie-overlay",
@@ -189,7 +204,7 @@ export function getOutputNodes<T extends GenericNode>(
       // Backwards compat: old flag on output-eligible nodes
       if (n.data.presentationVisible === true) {
         if (NON_OUTPUT_TYPES.has(n.type)) return false
-        return !nodesWithOutgoing.has(n.id) || MEDIA_PRODUCING_TYPES.has(n.type)
+        return !nodesWithOutgoing.has(n.id) || isMediaProducingType(n.type)
       }
       return false
     }
@@ -197,16 +212,53 @@ export function getOutputNodes<T extends GenericNode>(
   })
 }
 
-/** Map node type to its output media type. */
+/**
+ * Map node type to its output media type.
+ *
+ * The four literal sets above are read FIRST and win: they are the presentation
+ * classifier's own opinion, including for dual-mode nodes whose default medium
+ * is not their handle set (voice-changer and dubbing are audio here even though
+ * they can emit video).
+ *
+ * Anything they do not name falls through to the producer vocabularies the
+ * canvas validators and the orchestrator already maintain
+ * (`packages/shared/src/producer-types.ts`). Those sets are what a new media
+ * node MUST join for its outputs to connect at all, so deriving the tail from
+ * them is what stops this map from silently drifting behind the node catalogue
+ * — which it had (3D Render Pro, Generate Video, Generate Video Pro and a dozen
+ * ffmpeg nodes all read as `"data"`, so a published app rendered them as a JSON
+ * blob and `/v1` app schemas declared the wrong output type).
+ *
+ * `DYNAMIC_PRODUCER_TYPES` is deliberately NOT consulted: a node whose medium
+ * is decided at run time has no static answer, and `"data"` is the honest one.
+ */
 export function getOutputType(nodeType: string | undefined): OutputType {
   if (!nodeType) return "data"
   if (IMAGE_OUTPUT_TYPES.has(nodeType)) return "image"
   if (VIDEO_OUTPUT_TYPES.has(nodeType)) return "video"
   if (AUDIO_OUTPUT_TYPES.has(nodeType)) return "audio"
   if (TEXT_OUTPUT_TYPES.has(nodeType)) return "text"
+  if (VIDEO_PRODUCER_TYPES.has(nodeType)) return "video"
+  if (AUDIO_PRODUCER_TYPES.has(nodeType)) return "audio"
   return "data"
 }
 
+/**
+ * Whether a node produces media of its own — the test the legacy
+ * `presentationVisible` rule uses to keep a media node as an OUTPUT even when
+ * it also feeds something downstream.
+ *
+ * Same union, same reason as `getOutputType`: the hand-kept list plus the
+ * producer vocabularies. Text producers stay where the literal list put them
+ * (`generate-script`, `ai-writer`, `llm-chat` are members; `transcribe` and
+ * `qa-check` are not) — this is about media, not about every node with a value.
+ */
+function isMediaProducingType(nodeType: string): boolean {
+  if (MEDIA_PRODUCING_TYPES.has(nodeType)) return true
+  const output = getOutputType(nodeType)
+  return output === "image" || output === "video" || output === "audio"
+}
+
 /** Extract the result URL or text from a node's data. */
 export function getNodeResult(
   nodeData: Record<string, unknown>,