Repository navigation
SignalChainUIPlan
This page describes the accepted interface boundary for building signal chains and comparing their rendered output. The app route is currently a scaffold, so the page distinguishes domain requirements from implemented UI.
A signal chain is an ordered domain aggregate. The interface edits that aggregate; it does not define an independent browser model.
zero or more pre-effects
-> exactly one head or full-rig amplifier capture
-> optional effects-loop blocks
-> one impulse response when the amplifier is a head
-> zero or more post-effects
A full-rig capture already contains its cabinet response, so it forbids an additional impulse response and effects-loop blocks. The domain SignalChainValidator returns stable error codes for these rules.
The builder belongs at /app/build in the Vite and React application. It shares state with the gear browser, selected slot, filters, draft changes and validation results.
The builder must use:
- TanStack Router for app navigation.
- TanStack Query and the generated OpenAPI client for server state.
- React state for the active draft and local interaction.
- GTS design tokens and dense components.
- Stable
data-testidattributes.
HTMX, Alpine and Jinja2 do not split this workflow. They remain valid for small public-surface interactions.
The accepted desktop workspace has:
- A compact application shell.
- A gear browser with search, facets and model-level selection.
- A central chain canvas.
- A detail or action area for the selected block.
- A comparison area when a group produces several permutations.
The layout must keep its primary action and validation state visible without requiring the user to scroll back to a control.
The catalogue distinguishes a gear item from a model:
- A gear item is a capture pack or physical-device entry.
- A model is one selectable capture within that item.
- A user-gear record grants the user access to that selectable item.
- A signal-chain block references the user's gear record and records its gear type and position.
The browser loads typed API projections. It does not import T3K source schemas or infer block compatibility from source metadata.
The interface:
- Loads or creates a draft
SignalChain. - Lets the user select a chain position.
- Filters compatible gear through API guidance.
- Adds, removes or reorders a block.
- Requests domain validation.
- Shows errors next to the relevant position.
- Saves the aggregate through the signal-chain API.
Drag and drop may improve desktop interaction, but every operation must also work through keyboard and explicit controls.
A SignalChainGroup marks positions that may vary and records the allowed gear choices for each position. Core calculates the Cartesian product and caps it at 27 permutations.
The UI shows the estimated count before generation. It must not generate extra combinations in the browser or silently truncate the set.
The optional null choice means "no block at this position". It is valid for optional effects, not for the amplifier or required impulse response.
The builder creates source aggregates. The comparison player reads a completed shootout manifest. These are separate concerns:
- Builder state is editable.
- A published manifest is immutable.
- The player switches between rendered per-chain segments.
- The player does not read the current builder state or
master.wav.
The shared player will run as an Astro island on public pages and as a component in /app/shootouts.
The final interface must:
- Give every slot and action an accessible name.
- Support keyboard add, remove, select and reorder operations.
- Expose validation errors through associated text.
- Use semantic controls rather than clickable generic elements.
- Announce the active comparison chain and playback state.
- Provide touch targets suitable for mobile use.
data-testid names remain stable across styling changes. They identify behaviour such as chain-slot-0, chain-block-remove and gear-model-select.
Implemented backend pieces include:
-
SignalChainandSignalChainBlock. -
SignalChainValidator. -
SignalChainGroupand permutation calculation. - Signal-chain and group JSON APIs.
- Block-type guidance.
- A generated TypeScript API schema.
The app shell and /app/build route exist, but the route currently displays a placeholder. A temporary /app/probe route contains a study of interface density and is not product code.
The previous React island builder under the Astro tree is legacy implementation. It may provide reusable behaviour, but it is not the settled app host.