Entity Studios Parity — Design Spec

Date: 2026-06-14 Status: Approved (scope confirmed by user); pending implementation plan Scope: Bring location / object / creature(animal) studios to parity with the redesigned character studio, generalize the entity image-output handle, and surface creature voice.

Builds directly on the just-shipped character work: the generic StudioShell + StudioNavConfig, the plain-image output handle (PR #3369 + the connectivity fix in connection-validation.ts/payload-builder.ts), and the voice resource.

1. Goals (all three user-approved)

Studio port + References — move location/object/creature studios off their old monolithic tabbed modals onto the shared config-driven StudioShell, and promote each one’s reference photos (today a section inside appearance-tab.tsx) to a first-class References page in a Resources group. Mirrors character’s Resources → Identity → content structure while keeping each entity’s meaningful content groups.
Entity image output = first-class image producer (all 4 entities) — add a plain image output handle to location/object/creature (character already has it) and generalize the connectivity so every entity’s image output connects anywhere generate-image output can.
Creature voice — surface the already-stored creature voice (migration 220) in the frontend, add a Voice page to the creature studio, and wire creature→text-to-speech auto-fill.

Non-goals

No new shared studio abstraction beyond StudioShell (page files follow the existing per-entity-clone convention, reusing shared leaf components).
No Pickers/LoRA/Personality/Expressions for location/object/creature (those are character-only; the entities have no such data).
No new voice migration (220 already added creatures.voice).

Current state (audited)

All 3 studios are old monolithic modals (location-studio-modal.tsx, object-studio-modal.tsx, creature-studio-modal.tsx), each a near-clone with its own appearance-tab.tsx/angles-tab.tsx/motion-tab.tsx/etc. The character refactor was self-contained — they still compile.
Accents: location + object cyan #22d3ee; creature purple #A78BFA.
Only character has the plain-image source handle. handle-output-types.ts: location: { locationRef: "image" }, object: { objectRef: "imageRef" }, creature: { creatureRef: "imageRef" }.
creatures.voice column + creatures.ts Zod already exist (220); CreatureNodeData (frontend) does NOT have voice.

2. Architecture

Reuse frontend/src/components/editor/studio-shell/ (StudioShell<S,J> + StudioNavConfig + StudioNavContext + DEFAULT_STUDIO_ACCENT_ACTIVE) as-is — it is already entity-agnostic.

For each of location/object/creature:

A nav config <entity>-studio/<entity>-nav-config.tsx (StudioNavConfig<<Entity>StudioState, <Entity>StudioJobs>), groups below, accentActiveClassName set to the entity accent, badges = asset-array .length.
pages/ wrappers: extract the reference-photos section into pages/references-page.tsx; the rest of appearance-tab.tsx becomes pages/appearance-page.tsx; each content tab becomes a thin pages/<tab>-page.tsx wrapper binding the existing tab to StudioPageProps.
The modal becomes a thin <StudioShell config={…} state={studio} jobs={jobs} hasCredits={hasCredits()} header={…} defaultActiveKey="appearance" /> consumer (keeps its header, use-<entity>-studio + -jobs hooks, the pending-job seeding effect).

Per-entity nav structure

Location (cyan): Resources[References] · Identity[Appearance] · Environment[Time of Day, Weather, Seasons] · Composition[Angles, Lighting] · Atmosphere[Motion] · Sheet[Sheet]
Object (cyan): Resources[References] · Identity[Appearance] · Composition[Angles] · Variants[Materials, Variations] · Motion[Motion] · Sheet[Sheet]
Creature (purple): Resources[References] · Identity[Appearance] · Composition[Angles, Poses] · Variants[Variations] · Motion[Motion] · Character[Voice ✨]

Sheet stays via the shared reference-sheet-tab + SHEET_TAB_ADAPTERS.<entity> (location/object only — creature has no sheet, matching today).

3. Entity image output handle (all 4 entities)

Frontend node + types

Add a plain image type="source" <Handle> to location-node.tsx, object-node.tsx, creature-node.tsx, mirroring character-node.tsx:355-356 (identity *Ref handle PLUS a new image handle), with the visual pip (HANDLE_COLORS.image).
handle-output-types.ts: add image: "image" to each entity entry (location, object, creature) alongside its existing *Ref.

Frontend connection-validation (connection-validation.ts)

Generalize the imageSourceType substitution (today: sourceHandle === "image" && rawSourceType === "character") to all four entity types:
```
const ENTITY_IMAGE_HANDLE_TYPES: ReadonlySet<string> = new Set(["character", "location", "object", "creature"])
const imageSourceType =
  connection.sourceHandle === "image" && ENTITY_IMAGE_HANDLE_TYPES.has(rawSourceType ?? "")
    ? "upload-image"
    : rawSourceType ?? ""
```
This is already consumed by the 4 image-consumer dispatch branches (generate-image, generate-video, IMAGE_PRODUCER_VALIDATORS, VIDEO_PRODUCER_VALIDATORS), which the audit confirmed cover the COMPLETE set of image inputs generate-image output reaches. (reference-sheet in is intentionally entity-ref-only — excluded for all, correct.)
- Belt-and-suspenders (per the audit’s residual note): verify video-retake / video-sfx have no image-typed target that accepts IMAGE_PRODUCER_TYPES; if they do, route them through imageSourceType too.

Backend routing (payload-builder.ts)

Add the if (e.sourceHandle === "image") continue guard to the per-entity expand functions: expandWiredLocationRefs (+ the object/creature equivalents — locate them) so the entity’s image handle routes the portrait as a plain reference, not identity/mention. Mirrors resolveSheetEntity + expandWiredCharacterRefs/buildExtraRefCharacterContextLookup (already guarded).

Output emission

Confirm each entity’s output extractor (execution-graph.ts FE + output-extractor.ts BE) returns the portrait/sourceImageUrl for the image handle (the FE resolver’s isPlainImageHandle from #3369 is already entity-agnostic — it keys on the handle, not the type — so it applies to all). Add a sourceHandle-agnostic emission if any entity extractor doesn’t already return the image URL.

“text input” clarification (documented): generate-image output is an image producer and does NOT connect to literal text/prompt inputs (nor should an entity image handle). The image→text bridge is image-to-text (its image input is already covered). This satisfies “any image/reference/text input, just like generate-image output.”

4. Creature voice

Backend storage already exists (220 + creatures.ts Zod, “reuses the character voice plumbing verbatim”). Frontend surfacing only:

Types: add voice: CharacterVoice | null to CreatureNodeData (reuse CharacterVoice). Add voice to the creature save/get path (api.ts saveCreature/getCreature + the creature studio state hook’s payload + refetch-merge, mirroring how character does it).
Voice page: extract the character voice-page’s reusable core (Browse + Clone + Design-audition + selected card + Talk panel + the local pollJobUrl) into a shared frontend/src/components/editor/studio-shell/voice-resource.tsx (or character-studio/voice-resource.tsx) parameterized by a minimal interface { voice, setVoice, sourceImageUrl }. Character’s voice-page.tsx and a new creature pages/voice-page.tsx both render it. (DRY — avoids duplicating ~300 lines. If the coupling proves heavy, fall back to a creature-local clone, but prefer the extraction.)
Auto-wire: generalize the orchestrator TTS auto-wire (input-resolver.ts, currently srcType === "character" && targetType === "text-to-speech") to also fire for creature. Read src.data.voice (creature carries the identical shape). The payload-builder TTS consumer already reads resolvedInputs.voice (entity-agnostic).

5. Testing

connection-validation.test.ts: each of location/object/creature image handle → generate-image references + image-to-image = valid; → identity assets = rejected; their *Ref identity handle behavior unchanged.
payload-builder tests: each entity’s image-handle edge routes a plain portrait reference (no identity expansion); *Ref handle unchanged.
input-resolver test: creature → text-to-speech injects creature.voice.voiceId (+ no-clobber); character unchanged.
Studio shell render tests per entity: nav renders all groups/pages; badges fire; accent applied.
Full FE + BE vitest + tsc both + lints + gen:skills:check before shipping. (Adding voice to CreatureNodeData → run gen:skills if creature is in the generated skills.)

6. Phasing (independently shippable)

Image-handle generalization (FE node handles + handle-output-types + connection-validation + payload-builder guards + tests) — small, high-value, cross-cutting; ship first.
Location studio port + References page.
Object studio port + References page.
Creature studio port + References page + Voice (page + types + auto-wire) + gen:skills.

Each phase: tsc + targeted tests green, independently shippable to dev.