@field/cascade 0.2.22

package/AGENTS.md

@@ -0,0 +1,168 @@
+# Cascade agent guide
+
+Cascade is a reusable generative-design graph runtime with an optional Studio UI. Keep authored algorithms independent from the editor so the same graph can run in Studio, on a server, or in a UI-free browser host.
+
+## Start here
+
+- `DESIGN.md` — product and architecture source of truth.
+- `ARCHITECTURE.md` — repository boundaries and dependency direction.
+- `packages/contracts/` — public types, deterministic node definitions, capabilities, and schemas.
+- `packages/runtime/` — environment-neutral loading, validation, scheduling, and headless APIs.
+- `src/editor/` — Svelte Studio only; never put runtime behavior here.
+- `server/` — project-scoped Node host, compilation, assets, Python, and shell transport.
+- `spec/` — accepted behavior specifications. Read the relevant spec before changing a file format or public API.
+- `tests/` — executable behavior contracts, including performance and end-to-end authoring workflows.
+
+## Project convention
+
+A Cascade project is an ordinary directory or Git repository:
+
+```text
+my-project/
+├── cascade.json          # optional host policy and project settings
+├── index.cascade         # default graph; more .cascade files are allowed
+├── nodes/
+│   └── Multiply/
+│       └── index.ts      # project.Multiply
+├── assets/
+├── panels/
+│   └── AssetBrowser/
+│       └── index.ts      # optional Studio-only project panel
+├── package.json
+└── tsconfig.json
+```
+
+Use `cascade new <name>` to create a project. Run `cascade .` from its root to open Studio, `cascade validate <graph.cascade>` for validation, `cascade check <graph.cascade>` for static definition/type checks, `cascade inspect <graph.cascade>` for a JSON summary, and `cascade run <graph.cascade>` for headless execution.
+
+## Launch Studio
+
+For a browser on the same machine, use the secure loopback default:
+
+```bash
+cascade . --port 3030
+```
+
+For a workstation reached by hostname over a trusted VPN or LAN, bind the
+network interfaces and allow the exact hostname in the browser URL:
+
+```bash
+cascade . --host KURO --port 3030
+```
+
+Open `http://KURO:3030`. Before launching,
+check that the intended port is free or belongs to the expected Cascade process;
+never start a second instance on an occupied/default port or kill an unknown
+process. Verify the named route after startup:
+
+```bash
+curl -fsS http://KURO:3030/health
+curl -fsS http://KURO:3030/api/graph
+```
+
+Remote access is explicit: a specific non-loopback `--host` is also the default
+trusted browser hostname. Use `--trusted-host` only when the bind address and
+browser hostname differ. Hostnames are exact and case-insensitive; wildcard
+binds are rejected. Unknown flags and invalid ports are fatal. Every peer that
+can reach this interface can access trusted project APIs, so use an authenticated
+private VPN/interface and never expose Studio directly to the public internet.
+
+Project panels are trusted Studio extensions, not graph/runtime modules. Put them in `panels/<name>/index.ts`, type them from `cascade/studio/panel`, and return an instance disposer from `mount`. A parameter action such as `panel:asset-browser` opens one. Never import a project panel from a node, runtime host, or headless application.
+
+## Create a deterministic node
+
+Prefer a statically inspectable definition over legacy setup-time calls:
+
+```ts
+import type { NodeDefinition, NodeExecutionContext } from 'cascade/contracts';
+
+export const definition = {
+  apiVersion: 1,
+  label: 'Multiply',
+  runsOn: 'portable',
+  inputs: {
+    value: { kind: 'data', type: 'float', default: 0 },
+    factor: { kind: 'data', type: 'float', default: 2 }
+  },
+  outputs: {
+    result: { kind: 'data', type: 'float' }
+  }
+} as const satisfies NodeDefinition;
+
+export function execute(context: NodeExecutionContext<typeof definition>) {
+  context.outputs.result.set(context.inputs.value * context.inputs.factor);
+}
+```
+
+Definition rules:
+
+- Export `definition` as a literal and `execute` as computation only.
+- Keep the definition JSON-like. Parentheses, arrays, `as const`, and `satisfies` are valid; calls, spreads, computed properties, and imported constants are not.
+- Declare `runsOn`: `portable`, `browser`, or `server`.
+- For equivalent browser/server implementations, keep one portable definition
+  and have the host registration select the executor. Never expose execution
+  location as an artist parameter; parity-test the shared contract.
+- Declare every capability used. File, Python, and shell access are server-only; WebGL is browser-only.
+- Treat graph wires as the primary data boundary. A node may observe only its connected inputs, its props, and declared host capabilities; it must not inspect sibling nodes or the graph to discover data.
+- Deterministic node modules may not retain module-level mutable values, access ambient state such as `globalThis`, browser storage, or `process`, run top-level effects, or import sibling node implementations. `cascade check` reports these as `architecture/*` diagnostics.
+- A cache may memoize computation from wired inputs, but it must never supply unwired data. Make cache use an explicitly labelled prop and keep cache keys derived from the complete wired input and relevant props.
+- Keep model/provider integrations in the project. Cascade core has no Google,
+  Anthropic, OpenAI, or generic `ai` capability. Use normal typed outputs such
+  as `image` or `asset`, and choose the actual execution path explicitly.
+- Use exact Cascade core types or a namespaced project type such as `project.palette`.
+- Never execute a module to discover its ports or metadata.
+
+Use the runtime-native core vocabulary before creating a project wrapper:
+
+- `cascade.core.Input` / `cascade.core.Output` define the public graph or subnet boundary.
+- `cascade.core.Subnet` contains nested nodes.
+- `cascade.core.Switch`, `Merge`, and `Select` provide deterministic routing.
+- `cascade.core.Null` passes any value through unchanged so downstream wiring can remain stable while upstream branches are reorganized.
+- `cascade.core.Random` maps explicit integer `seed` and `sample` inputs to a stable float in `[0, 1)`.
+- `cascade.core.Remap` maps scalar ranges and optionally clamps via its `clamp` prop.
+
+The geometry set is reserved the same way, under `cascade.geo.*`:
+`Rectangle`, `Circle`, `Transform`, `Merge`, `CopyToPoints`, and `SvgExport`.
+They all speak the one `geometry` type, so any output fits any input, and they
+follow Houdini's parameter names where Houdini has an equivalent node. Geometry
+is +Y up; the flip into SVG's frame lives in `SvgExport` alone.
+
+These modules are reserved and need no file under `nodes/`. Do not override a
+`cascade.core.*` module or use ambient random/time state in a portable node.
+
+## Navigate and edit graphs
+
+- `.cascade` documents keep nodes and annotations in flat arrays. Nested elements carry `parent: '<subnet-id>'`; their positions are relative to that subnet.
+- Element IDs are globally unique. Connections address node and port IDs, not array positions.
+- Preserve unknown metadata and existing source fields when editing a graph.
+- Validate hierarchy, ports, and connections together. Do not partially mutate a live graph and then repair it.
+- Use the runtime/controller APIs for structural edits when available; do not reach into `_elements`, `_children`, connection arrays, or editor stores.
+
+## Boundaries
+
+- Contracts have no runtime dependencies.
+- Runtime depends only on contracts and contains no DOM, Svelte, Express, Node filesystem, or child-process imports.
+- Hosts inject capabilities explicitly.
+- Studio consumes runtime through its controller; custom frontends consume runtime directly.
+- User modules are trusted project code, not a sandbox. Static definitions improve tooling and portability, not isolation.
+- Keep legacy support inside the existing Studio/CLI compatibility engine; do not spread compatibility branches into the deterministic runtime.
+
+## Change workflow
+
+Use Node.js 22.13 or newer. Cascade compiles with TypeScript 6; do not move to
+the TypeScript 7 preview until it is stable and the repository gates pass.
+
+1. Add or update a focused regression test.
+2. Make the smallest change at the owning layer.
+3. Prefer deletion or an existing utility over another wrapper.
+4. Run the focused test, then `npm run check`, `npm run test:run`, `npm --prefix server run build`, `npm run build`, and `npm run build:cli` when the affected surface warrants it. Keep the CLI build last because Vite refreshes `dist/`.
+5. For package/public API changes, also test the packed tarball from an empty temporary project.
+
+Do not add dependencies without a concrete need. Do not create extra packages unless they need independent publication or versioning.
+
+## Versioning
+
+Cascade `0.2.0` is the 2026 architecture rework. The current release is
+`0.2.22`. Increment the root package and CLI patch version for every committed
+feature or release change (`0.2.22`, `0.2.22`, …), keeping `package.json`, the
+lockfile, and CLI output aligned. Internal private workspaces do not receive
+independent versions unless they become separately published packages.

package/ARCHITECTURE.md

@@ -0,0 +1,137 @@
+# Cascade architecture
+
+Cascade has four layers with one-way dependencies:
+
+```text
+contracts <- runtime <- hosts/controllers <- applications
+```
+
+The graph engine is a reusable product surface. The neutral runtime is ready for headless hosts; Studio is still migrating from its compatibility `Graph`/`Node` implementation and must not be described as migrated yet.
+
+## Contracts
+
+`packages/contracts` is dependency-free and owns `.cascade` DTOs and schemas, core and namespaced types, deterministic node definitions, capability interfaces, diagnostics, events, presets, and run results.
+
+Contracts contain no DOM, Svelte, Express, filesystem, process, or implementation imports. Public types belong here once; other layers import them rather than recreating variants.
+
+## Runtime
+
+`packages/runtime` depends only on contracts and owns definition extraction, module registration, graph validation, scheduling, triggers, cancellation, outputs, hierarchy, inspection, and serialization semantics.
+
+The runtime is environment-neutral. It works in Node and browsers without importing either platform’s APIs, and it never imports Studio. Registration is sealed after the first graph load. Each graph permits one active run and has explicit lifecycle states.
+
+The reserved `cascade.core.*` registry is owned here. `Subnet`, `Input`,
+`Output`, `Switch`, `Merge`, `Select`, seeded `Random`, and `Remap` resolve
+without a project module loader. Named, typed root Input/Output nodes form an
+explicit headless graph interface; typed child Input/Output nodes form a subnet interface.
+Randomness is a pure function of an authored seed, never ambient process state.
+
+## Hosts
+
+Hosts adapt the neutral runtime to an environment:
+
+- Node: files, assets, media, Python, and shell.
+- Browser: assets, media, and WebGL.
+- Mixed application: an explicit bridge for serializable server stages.
+
+Capabilities are injected. A node’s literal `runsOn` and `capabilities` fields are checked before its `execute` module is loaded.
+
+`portable` describes one graph contract, not necessarily one implementation.
+A registration may load an equivalent browser or server executor for that
+contract. The host selects the executor; graphs and artist-facing parameters do
+not contain backend switches. This is appropriate for operations such as crop,
+resize, composite, and encode when both Canvas/WebGL and native implementations
+exist. Both executors must obey the same definition and should share golden
+parity tests for geometry, metadata, and edge cases.
+
+`server/` is the project-scoped Node application host. It owns project paths, compilation, HTTP transport, media serving, Python workers, shell policy, and credentials. It is separately manifested and is not a third contracts/runtime workspace.
+
+## Applications and controllers
+
+Studio’s Svelte components under `src/editor` own rendering, selection, panels, and interaction state. Its compatibility graph now has one graph-owned cook scheduler, while `StudioGraphController` centralizes an increasing set of structural mutations and publishes view snapshots. Compatibility adapters still present runtime-owned built-ins in Studio; collapse/extract and the remaining legacy nodes must migrate before Studio can consume `packages/runtime` directly.
+
+Studio uses Dockview through the public `dockview` API. Code panels lazy-load
+Monaco and its native editor/TypeScript workers rather than adding Monaco to the
+initial application path. Markdown rendering has one Marked/DOMPurify boundary;
+components do not configure parsers or inject unsanitized Markdown themselves.
+
+Custom server applications and browser frontends use `cascade/runtime` directly and load no Studio code.
+
+## Distribution
+
+The repository has exactly two internal npm workspaces: `@cascade/contracts` and `@cascade/runtime`. The root `cascade` package is the only published package and the only owner of the executable.
+
+Public subpaths are `cascade/contracts`, `cascade/contracts/schema`, `cascade/runtime`, `cascade/runtime/node`, `cascade/runtime/browser`, and the compatibility `cascade/shell`.
+
+Studio-only project extensions use the type-only `cascade/studio/panel` contract. They are compiled and loaded only by Studio; the neutral runtime and headless hosts never discover or import them.
+
+The packed root tarball contains compiled contracts, runtime, declarations, and a self-contained CLI. It must install and type-resolve from an empty project without workspace links or development dependencies. Additional packages require a concrete independent publication/versioning need.
+
+The repository requires Node.js 22.13 or newer and builds with TypeScript 6,
+Vite 8, and the Svelte Vite plugin 7. TypeScript 7 remains deferred while it is
+a preview rather than a stable compiler target.
+
+Model providers are deliberately outside Cascade. Projects own provider SDKs,
+credentials, model selection, retries, and result normalization, using the same
+project-node and host boundaries as any other external service. Cascade keeps
+provider-neutral media and asset types, cancellation, progress, and diagnostics.
+
+## Deterministic nodes
+
+`nodes/<Name>/index.ts` maps to `project.<Name>`. New modules export one literal `definition` with `apiVersion: 1` and one typed `execute(context)` function.
+
+The extractor reads TypeScript syntax and never evaluates the module. Literal primitives, arrays, objects, parentheses, `as const`, and `satisfies` are valid. Identifiers, calls, spreads, computed keys, and other evaluation-dependent syntax are diagnostics.
+
+`execute` performs computation only. Ports, props, types, execution locus, and capabilities are fixed by `definition`. Existing dynamic modules stay in the Studio/CLI compatibility engine during migration; the headless runtime never interprets them, and a malformed deterministic definition never falls back to dynamic execution.
+
+Deterministic node modules are also statically checked for hidden coupling. They cannot declare module-level runtime values, run top-level effects, access ambient process/browser storage, dynamically import code, or import another node implementation. Nodes exchange project data through typed graph wires; declared props and host capabilities are their only other inputs. This is an enforceable architecture contract for trusted code, not process isolation.
+
+## Graph documents and hierarchy
+
+Authored nodes and annotations remain in flat arrays. Optional `parent` IDs describe subnet membership; IDs are globally unique, and child positions are parent-relative. Connections retain their node/port endpoint format across subnet boundaries.
+
+Neutral-runtime load order is:
+
+1. Parse and validate authored DTOs.
+2. Resolve hierarchy, falling back invalid links to root with diagnostics.
+3. Materialize node definitions and ports.
+4. Synchronize nested subnet interfaces deepest-first.
+5. Resolve connections and topology.
+6. Commit the complete candidate once.
+
+The compatibility Studio loader also constructs and validates a complete
+candidate before replacing the live graph. Unknown identifiers in Cascade's
+reserved `cascade.*` namespace fail explicitly; they never become inert base
+nodes or embedded/project modules. Subnet collapse/extract remain the main
+structural transaction gap.
+
+Callbacks and destruction hooks run after a valid structural commit. They are not rollback state.
+
+## Execution
+
+Data runs follow graph dependencies. Explicit triggers use a FIFO queue, authored fan-out order, monotonic per-run sequence IDs, and cycle rejection. A triggered node receives cooked data ancestors before delivery.
+
+Execution failures resolve to a failed `RunResult`; API misuse and invalid preflight reject. Cancellation propagates through capability calls. Inspection and output values are immutable snapshots; browser-only live resources remain host-owned handles.
+
+## Security
+
+Project node modules are trusted code. Capabilities describe support and portability; they are not a sandbox.
+
+All project HTTP APIs require an exact allowed Host. Origin is validated when
+present and hostile or null Origins are rejected; same-origin GETs may omit it.
+Filesystem resolution checks lexical paths and canonical existing targets or
+parents. Project panels may additionally resolve beneath the canonical target
+of the project-owned `shared/` link; other project paths remain root-confined.
+
+Shell execution uses configured aliases and `spawn(executable, args, { shell:
+false })`, bounded input/output/time, dangerous request-environment-key
+rejection, process-tree cancellation, redacted audits, and capability-token
+routes. Sensitive routes are enabled on loopback or through explicit exact
+trusted-host configuration; an untrusted remote bind exposes no capability
+bootstrap.
+
+## Compatibility and migration
+
+`src/nodes` and `src/engine` remain the Studio compatibility surface while Studio migrates onto the neutral runtime. Runtime-owned algorithms stay in `packages/runtime`; compatibility nodes may adapt them but must not fork their semantics. New features belong at the owning contracts/runtime/host/controller layer.
+
+Prefer deletion and direct imports over wrappers. Preserve behavior with focused tests before moving code, then remove the replaced path in the same change when safe.

package/DESIGN.md

@@ -0,0 +1,161 @@
+# Design
+
+## Source of truth
+
+- Status: Active
+- Last refreshed: 2026-08-29
+- Primary product surfaces: reusable graph runtime, optional Studio workbench, headless Node/browser hosts, Inspector, Viewer, node ports, project-defined workbenches
+- Evidence reviewed: `VISION.md`, `ARCHITECTURE.md`, `spec/CASCADE_SUBNET_AND_SHELL_SPEC.md`, `src/types/coreTypes.ts`, `src/editor/Inspector.svelte`, `src/editor/Viewer.svelte`, `src/editor/components/PortEditor.svelte`, `src/editor/components/typeRenderers.ts`, and the approved plans under `.omx/plans/`
+
+## Brand
+
+- Personality: technical, direct, calm, precise, and built for expert creative work
+- Trust signals: visible types, explicit execution locus, inspectable intermediate values, honest errors, stable filesystem paths
+- Avoid: generic AI gradients, decorative card grids, excessive shadows, toy-like controls, hidden conversions, and visual noise that competes with outputs
+
+## Product goals
+
+- Goals: provide a stable reusable platform for generative design across interactive web work, high-resolution print, motion, video, sound, WebGL, Python, and external-service workflows; separate authored algorithms from platform and Studio concerns; make every graph stage inspectable; let projects reuse deterministic custom nodes without rebuilding file, version, preset, workspace, or execution infrastructure
+- Non-goals: spreadsheet-scale data editing, full 3D DCC tooling, silent expensive conversions, bespoke conditionals for every node type, executing user modules to discover metadata, or requiring the Studio UI to run a graph
+- Success signals: the same `.cascade` graph runs in Studio, a Node server, or a UI-free browser host; node contracts are statically inspectable and TypeScript-checkable; every `CORE_TYPES` member has a useful Inspector and Viewer state; connected/output values are clearly read-only; project renderers plug into the same contract; large values remain responsive
+
+## Personas and jobs
+
+- Primary personas: creative coders, technical artists, generative-design engineers
+- User jobs: tune node inputs, understand intermediate outputs, compare execution contexts, detect malformed values, and move fluidly between Python and browser-backed stages
+- Key contexts of use: dense desktop workbenches, long pipelines, large images/geometry, mixed CPU/GPU/server execution
+
+## Information architecture
+
+- Primary navigation: canvas selection determines Inspector and Viewer context
+- Core screens: Graph, Inspector, Viewer, Logs/diagnostics
+- Content hierarchy: value preview first, type and shape metadata second, expandable raw structure last
+
+## Design principles
+
+- One type, one presentation contract: the same type vocabulary drives ports, Inspector, and Viewer.
+- Progressive disclosure: compact summaries in dense panels; richer previews and metadata in Viewer; raw JSON only on demand.
+- Edit only what can be authored honestly: inputs may edit portable values; connected inputs and outputs are read-only; live GPU textures are inspected, not fabricated through form fields.
+- Expensive context changes stay explicit: texture readback, server materialization, and file writes are actions or nodes, never invisible UI coercions.
+- Project types extend by registration, not central switch statements.
+- The graph runtime is a product surface independent from Studio. Headless hosts consume it now; Studio's compatibility graph has one scheduler/controller boundary but still requires a deliberate built-in and structural-command migration before it consumes the neutral runtime directly.
+- Node metadata is deterministic. A literal exported definition declares ports, properties, types, execution locus, and capabilities; `execute` performs computation only.
+- Hosts provide explicit capabilities. File, Python, media, WebGL, and shell access are never ambient runtime assumptions. Provider-specific AI abstractions belong to projects or embedding hosts, not Cascade core.
+- Neutral-runtime graph loads are atomic. Compatibility Studio collapse/extract are a known migration gap and must move behind transactional structural commands before that guarantee applies to every editor operation.
+- Tradeoff: geometry editors favor transparent structured editing and previews over specialized CAD interactions in this pass.
+
+## Architecture
+
+- `@cascade/contracts` is the dependency-free source of truth for graph documents, core and namespaced types, deterministic node definitions, diagnostics, run results, capabilities, and schemas.
+- `@cascade/runtime` is the deterministic environment-neutral graph loader, validator, scheduler, serializer, trigger engine, and hierarchy implementation. It depends only on contracts; dynamic compatibility remains in Studio/CLI during migration.
+- The root `cascade` package is the sole published distribution and CLI owner. It exposes `cascade/contracts`, `cascade/contracts/schema`, `cascade/runtime`, `cascade/runtime/node`, `cascade/runtime/browser`, and the compatibility `cascade/shell` entry point.
+- Node and browser hosts inject only the capabilities they support. Browser-only WebGL and server-only file, Python, and shell capabilities make portability constraints explicit before execution.
+- The Studio owns canvas/view classes and a single `StudioGraphController`; its compatibility `Graph`/`Node` engine is still being reduced. Custom frontends and backend services use the neutral runtime directly and do not load editor code.
+- Python interoperability remains a host capability for exotic libraries and compute stages. Exchange values cross explicit typed node boundaries rather than leaking Python process details into the neutral runtime.
+- Internal packages remain two workspaces until independent versioning or external consumption justifies separate publication. More npm packages are not a goal by themselves.
+
+## Graph and node conventions
+
+- A custom node lives at `nodes/<Name>/index.ts`; its folder identity resolves to `project.<Name>`.
+- The module exports a literal `definition` and a typed `execute`. Static inspection accepts JSON-like literals, arrays, parentheses, `as const`, and `satisfies`; identifiers, calls, spreads, computed properties, and other evaluation-dependent syntax are rejected.
+- Deterministic modules have no module-level values or top-level effects, do not access ambient globals or browser storage, and do not import sibling node implementations. Data dependencies are graph wires; props configure the node; hosts inject declared capabilities. Static architecture diagnostics reject violations before execution.
+- `definition.runsOn` is required (`portable`, `browser`, or `server`), and declared capabilities must be valid for that locus.
+- Trigger events are explicit, queued FIFO, and fan out in authored connection order. Data dependencies cook before a gated trigger target. Trigger cycles are rejected.
+- `.cascade` documents retain a flat authored element list. Optional `parent` identifiers describe nested subnets for nodes and annotations; child positions are relative to their parent network.
+- Loading prepares and validates authored elements, hierarchy, executable nodes, ports, connections, pending connections, and topology before one assignment-only structural commit.
+- Existing dynamic modules remain supported by the current Studio/CLI engine during migration. The headless runtime is deterministic-only, and malformed definitions never fall back to dynamic execution.
+
+## Headless and deployment model
+
+- `createRuntime()` is the common entry point for Studio, Node services, UI-free browser embeds, tests, and custom web frontends.
+- Registration is sealed after the first graph load. A loaded graph supports inspect, input/property/preset mutation, trigger, run, cancel, subscription, output retrieval, and disposal without editor dependencies.
+- One run is active per graph; there is no hidden run queue. API misuse rejects, while graph execution resolves to an explicit success/failure/cancelled result.
+- A graph may run wholly in a backend, wholly in a compatible browser, or across an explicitly designed bridge. The runtime never silently moves a stage between hosts.
+- File loading/saving, format versioning, presets, project paths, and workspace conveniences belong to stable platform services around the neutral runtime, not to individual generative algorithms.
+
+## Security boundaries
+
+- User node modules are trusted project code, not a sandbox. Deterministic definitions and architecture checks prevent common hidden-state designs and improve inspection, tooling, and portability; hard isolation would additionally require a separate realm or worker per node instance.
+- Shell is a server-only capability backed by one project-scoped service. Projects invoke configured aliases as a fixed executable plus argument array with `shell: false`; arbitrary executables, interpolation, unsafe working directories, dangerous request-time environment overrides, and unbounded output are rejected. The subprocess inherits the server environment before project and allowlisted request overrides are applied.
+- Browser shell transport is loopback-only, uses exact Host and Origin checks plus a process-lifetime random capability token, has route-local request limits, and never logs tokens, paths, arguments, environment, stdin, stdout, or stderr.
+- Timeout, cancellation, and output limits terminate the full process tree and wait for closure before reporting completion.
+
+## Agent workflow contract
+
+- Repository guidance must let a code agent find the project manifest, graph documents, nodes, assets, presets, runtime host, and verification commands without reverse-engineering Studio internals.
+- Project creation and node creation use canonical templates and CLI checks. A good agent workflow is: inspect contracts, author a literal definition, implement typed computation, run static definition extraction and TypeScript checks, then run the graph headlessly before opening Studio.
+- Public contracts and examples favor small composable modules, direct imports, explicit capabilities, and deletion of redundant wrappers. Agent guidance must name deprecated compatibility paths and their migration target.
+
+## Visual language
+
+- Color: the workbench resolves through one set of semantic tokens in `src/editor/theme.css`, which carries a dark and a light value for each name; the theme setting follows the system unless the artist picks one. Family colors from `TYPE_COLORS` are unchanged, and color still communicates type family, not decoration
+- Typography: system UI font for labels; compact monospace for values, paths, dimensions, and diagnostics
+- Spacing/layout rhythm: dense 4/6/8px rhythm; metadata rows remain scannable without nested card chrome
+- Shape/radius/elevation: 3–4px radii; borders establish hierarchy; shadows reserved for floating dialogs/menus
+- Motion: immediate updates; brief status transitions only; no decorative motion
+- Imagery/iconography: previews use the actual value; icons clarify actions or execution locus only
+
+## Components
+
+- Existing components to reuse: `PortEditor`, `JsonTree`, `ColorPicker`, Viewer image zoom/pan behavior, type renderer registry
+- New/changed components: shared `TypeValue` presentation shell, structured JSON editor, image/texture inspector, geometry summary/preview, asset inspector, Viewer output list
+- Variants and states: `compact`, `inspect`, `view`; editable/read-only; empty/loading/error/stale; connected source; truncated/expanded
+- Token/component ownership: `coreTypes.ts` owns semantic type metadata; the presentation registry owns components; Inspector/Viewer only choose context and mode
+
+### Core type presentation contract
+
+| Family | Inspector/editor | Viewer |
+| --- | --- | --- |
+| `float`, `int`, `bool`, `string` | native compact controls | large readable value with type metadata |
+| vectors and matrices | labeled numeric fields; integer rounding; identity action for matrices | formatted tuple/grid with dimensions |
+| `color` | swatch plus RGBA fields | swatch, numeric values, colour-space note |
+| `image` | path and descriptor metadata; thumbnail; portable fields editable only when unconnected | zoomable media preview plus size/channels/depth/space/path |
+| `texture` | read-only live GPU metadata and unavailable/stale state | GPU preview when a canvas/source is exposed, otherwise dimensions/format/session metadata |
+| `points`, `lines`, `polyline`, `rects` | count/bounds summary plus validated structured editor for unconnected inputs | lightweight SVG/Canvas2D preview, count, dimensionality, bounds, expandable structure |
+| `mesh` | vertex/triangle/normal/UV summary plus validated structured editor | lightweight projected preview when feasible, statistics, expandable structure |
+| `asset` | validated project-relative path/descriptor editor | media/file metadata and preview when renderable |
+| `array`, `object`, `any` | validated structured editor with tree preview | searchable/expandable tree and concise shape summary |
+| namespaced project types | registered renderer when available; safe generic structured fallback | same registry with richer `view` mode and generic fallback |
+
+## Accessibility
+
+- Target standard: WCAG 2.2 AA for interactive controls and text contrast
+- Keyboard/focus behavior: all fields, expanders, reset/copy/open actions, and output selection are keyboard reachable with visible focus
+- Contrast/readability: type color is never the only carrier of meaning; every value includes a textual type label
+- Screen-reader semantics: groups use labels/headings; summaries announce type, shape, editability, and error state
+- Reduced motion and sensory considerations: respect reduced motion; avoid pulsing status effects
+
+## Responsive behavior
+
+- Supported breakpoints/devices: desktop-first; Inspector remains usable from 240px width; Viewer adapts to Dockview panel size
+- Layout adaptations: vector/matrix fields wrap or scroll; Viewer metadata collapses beneath previews; structured trees virtualize or truncate large collections
+- Touch/hover differences: no essential information exists only in hover tooltips
+
+## Interaction states
+
+- Loading: preserve previous value when possible and show bounded loading status
+- Empty: type-aware “No value” state, not a blank panel
+- Error: inline typed diagnostic with preserved last-known-good preview where applicable
+- Success: edits commit on change/blur and trigger the existing node update/cook path
+- Disabled: connected inputs and all outputs explain why they are read-only
+- Offline/slow network: retain cached preview and show stale/disconnected metadata for file-backed values
+
+## Content voice
+
+- Tone: concise, factual, technically precise
+- Terminology: use the canonical type names and “browser”, “GPU”, and “Python/server” execution contexts consistently
+- Microcopy rules: state the condition and recovery; avoid anthropomorphic or generic “something went wrong” text
+
+## Implementation constraints
+
+- Framework/styling system: Svelte 5, component-local CSS, existing Dockview workbench
+- Design-token constraints: reuse `TYPE_COLORS` and current neutral palette; do not add a second design-token layer in this pass
+- Performance constraints: never dump unbounded JSON into the DOM; image previews use `/api/media`; geometry previews sample large collections; texture UI avoids GPU readback unless explicitly requested
+- Compatibility constraints: normalize legacy `number`, `boolean`, and `curves`; preserve namespaced project renderers and old image paths via `coerceImageRef`
+- Test/screenshot expectations: unit-test type formatting/normalization and renderer resolution; component-test editing/read-only/error states; production build and Svelte check remain green
+
+## Open questions
+
+- [ ] Whether mesh Viewer should gain an interactive WebGL orbit view after the lightweight projected preview proves useful / product / medium impact
+- [ ] Whether project packages can eventually ship Svelte renderers directly rather than app-side registration / architecture / high impact
+- [ ] Whether large structured values need virtualization beyond bounded initial expansion / performance / medium impact

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FIELD.IO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.