Patchies Objects

Patchies Objects

Object Modules First

Before adding, moving, or migrating object code, read ui/src/objects/README.md. Treat it as the source of truth for object-module ownership.

Object-owned code belongs under ui/src/objects/<object-or-family>/. Each object, or small obvious object family, should own the files specific to that object:

• Svelte node components
• object schemas
• audio or text object runtime classes
• object-specific AI prompts
• default data, render-node type members, settings, constants, helpers, and tests
• workers or system classes that are not shared infrastructure

There is no required subfolder shape beyond keeping object-owned files colocated. Use subfolders when they make the module easier to scan:

ui/src/objects/<object-or-family>/
  components/
  workers/
  native-dsp/
  render-types.ts
  schema.ts
  prompt.ts
  *.test.ts

Markdown object docs stay in ui/static/content/objects/.

Shared infrastructure belongs outside ui/src/objects only when it is not owned by one object or a small object family. Examples: registries, schema helper utilities, shared layout components used by unrelated objects, object service plumbing, rendering infrastructure, and native DSP framework code.

Use the $objects alias for object-owned imports.

Files outside ui/src/objects should import object modules only when they are registry-style files whose job is to gather object definitions, such as component, audio, text-object, schema, prompt, shorthand, default-data, or render-type registries.

If a non-registry file outside ui/src/objects needs behavior from an object module, reconsider the boundary: move shared behavior to ui/src/lib, or move the object-specific caller into the owning object module.

When migrating many objects, move in small validated batches. Do not group unrelated objects merely because they share a layout component.

Handles

Use StandardHandle for node handles:

<StandardHandle port="inlet|outlet" type="video|audio|message" id="optional" title="Description" total={count} index={idx} />

Handle colors: video is orange, audio is blue, message is gray.

ID generation:

• type and id: ${type}-${portDir}-${id}, for example audio-in-0.
• type only: ${type}-${portDir}, for example message-in.
• id only: ${portDir}-${id}, for example in-0.
• Neither: the port value.

Common patterns:

• Simple single inlet/outlet: omit id.
• Multiple indexed handles: id={index}.
• Complex dynamic handles: include index, name, and type in id.

Node Data Undo/Redo

When adding any new node option or setting, add undo/redo tracking with useNodeDataTracker.

Discrete changes, such as toggles, color pickers, dropdowns, and radio buttons, should commit immediately:

const tracker = useNodeDataTracker(node.id);

function handleColorChange(newColor: string) {
  const oldColor = color;

  updateNodeData(node.id, { color: newColor });
  tracker.commit('color', oldColor, newColor);
}

Continuous changes, such as text inputs, sliders, and number inputs, should track from focus/pointerdown through blur/pointerup:

const textTracker = tracker.track('text', () => node.data.text ?? '');

CodeEditor handles code undo internally through codeCommit; pass the correct dataKey instead of adding useNodeDataTracker for code.

See PostItNode.svelte, SliderNode.svelte, and docs/design-docs/specs/68-undo-redo-system.md.

Visual or Expression Nodes

When adding a visual/expression node, update the relevant surfaces:

• Component in the owning ui/src/objects/<module>/ unless it is genuinely shared UI infrastructure.
• Node type registry.
• Default node data.
• Object browser category and description.
• Documentation and object schema when user-visible.
• AI object prompts: object-descriptions-types.ts, object prompt file, and prompt index.
• CodeMirror completions for JavaScript-based nodes that expose API functions.

Runtime Object Kinds

Patchies has separate editor representations that can share runtime lifecycle and message routing:

• Object-box text objects use { expr, name, params } and are loadable through ObjectNode.
• Dedicated visual nodes use object-shaped node.data, such as { value, min, max, step, isFloat }.
• Audio nodes keep their audio-specific params[] runtime contract unless the audio object explicitly provides a higher-level message/settings adapter.

Keep these registries distinct in ui/src/lib/objects/v2/nodes/index.ts:

• TEXT_OBJECTS: object-box objects only.
• VISUAL_OBJECTS: dedicated Svelte-node-backed visual objects.
• RUNTIME_OBJECTS: union used for runtime registration and schema generation.

Do not put a dedicated visual node in TEXT_OBJECTS just to make schemas or headless runtime work. ObjectNode should only search/load TEXT_OBJECTS plus audio object names.

EditorRuntimeReconciler may branch on editor representation (object node versus dedicated node), but must not mention concrete object names. Visual runtime data is the dedicated node's object-shaped node.data; put defaults in the object/view helpers that read the data, and use explicit migrations for saved shape changes.