Skip to content

feat: projector fixture kind, interleaved 12×2 layout, dormant projector control API - #152

Merged
pyramation merged 3 commits into
mainfrom
devin/1794506706-projector-fixture-kind
Nov 13, 2026
Merged

pyramation merged 3 commits into
mainfrom
devin/1794506706-projector-fixture-kind

Conversation

@pyramation

@pyramation pyramation commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

First step for mixed cannon + projector shows (Nu-Salt NSL-2000 Model Z, Pangolin FB4-XE). Plan: constructive-planning #2501 (this PR = #2502 + #2503).

Fixture kind. FixtureKind = 'cannon' | 'projector' on layout Fixture.kind (default cannon, so every existing preset/layout is unchanged) and on UnifiedCannon / DeviceCannon / CannonRoute.kind, carried through routing generation to the receiver. validateUnifiedRouting now rejects a projector on an fb4 target: the FB4 color_* OSC addresses are the box's persistent colour-balance settings, not live colour, and would silently detune a calibrated projector. Projectors route to BEYOND like everything else — colour + brightness already work through the existing /beyond/zone/{n}/livecontrol/{red,green,blue,alpha,Brightness} path, so the HSB pipeline (server, receiver, UI tabs) is untouched.

Interleaved layout for Saturday. interleavedLayout({ cols, rows, stagger = 0.15, first = 'cannon' }): even columns one kind, odd columns the other, projectors offset stagger cells below their row so the two kinds read apart while the rows still read as rows. Row-major indices, row/col are the plain grid's (topology: 'grid', hasGridCoords), so grid animations, shift and brush behave exactly as on a grid. Preset interleaved-12x2 (12 cannons + 12 projectors), shorthand interleaved:12x2, spec { kind: 'interleaved', cols, rows, stagger?, first? }. examples/routing-interleaved-12x2.json. The artist UI GridDisplay, the desktop light-map canvas and FixtureRow draw projectors as rounded squares instead of orbs.

Aspect-aware canvas. GridDisplay now sizes its canvas to the layout's aspect ratio when fixtures carry world x/y (square grids and rings are unchanged, ±15% tolerance keeps them square). A 12×2 band fills the width and keeps its row spacing instead of being stretched to a square, so all 24 fixtures sit in one contiguous finger-paintable strip with the classic orb-to-cell ratio. Hit-testing and the rotate/flip inverse use the canvas height for y.

Dormant projector control API (no UI). In @wavegrid/osc:

interface ProjectorControl { size?, sizex?, sizey?, zoom?, posx?, posy?, anglez?, rotoz?, anispeed?, scanrate?, visiblepoints?, fx?: [n,n,n,n] }
type ProjectorCueCommand = { cueDown: {page, cue} } | { stopZone: n } | { stopAllNow: true }
encodeBeyondProjectorMessages(controls, projectorMap)  // → /beyond/zone/{n}/livecontrol/<fn>, clamped to Pangolin's ranges
encodeBeyondCueMessage(cmd)                             // → /beyond/general/CueDown|StopZone|StopAllNow (int32 args)
OutputAdapter.sendProjector?() / sendCue?()             // optional; BeyondOscOutput implements, RoutedOscOutput fans out

RoutedOscOutput.sendProjector drops any index whose route is not kind: 'projector', so a cannon can never be resized/moved. Wire: client { type: 'projector', indices, control } / { type: 'projector_cue', command } → server keeps only layout.fixtures[i].kind === 'projector' → command relay → receiver re-bases global indices to its shard → output.sendProjector. Documented in docs/command-api.md. EnableLaserOutput / DisableLaserOutput / BlackOut deliberately not exposed.

Tests: interleaved generator (counts, kinds, stagger, indices), spec parsing/preset, routing kind carry-through + projector-on-FB4 error, projector/cue encoders with clamping, routed filter. Runtime test drive with loopback OSC in the PR comments.

Link to Devin session: https://app.devin.ai/sessions/e6939c79261649988b8277ba34725160
Open in Devin Desktop: https://app.devin.ai/desktop/session/e6939c79261649988b8277ba34725160?variant=devin
Requested by: @pyramation

…tor control API

Cannon | projector fixture kind in layout and routing (projectors must route
to BEYOND; FB4 OSC colour is a persistent setting), interleavedLayout with a
vertical stagger and the interleaved-12x2 preset, projector squares on the
UI/desktop canvases, and a dormant BEYOND zone livecontrol + cue API behind
OutputAdapter.sendProjector/sendCue with a server/receiver command relay.
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@luxor-code-review

luxor-code-review Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Review complete. 🟠 1 high · 🟡 3 medium

💬 Inline comments (4)


The change introduces a new interleaved layout generator (generators.ts, layout-spec.ts, presets.ts, types.ts) supporting a first fixture kind and fractional row stagger, with a matching interleaved-12x2 preset and spec parser. Routing (routing.ts) now carries and validates per-fixture kind, rejecting projectors bound to FB4 targets, and an example config demonstrates a 12x2 interleaved show. The OSC package (osc-adapters.ts, index.ts) gains BEYOND adapter support: projector ranges, fx/cue encoding, and per-target projector maps. The receiver (receiver.ts, command-types.ts, adapters.ts) re-bases global projector indices to local shard ranges and forwards projector/projector_cue commands to adapters. The desktop app (light-map.ts, ipc.ts, lights-route.tsx, grid-display.tsx) renders projector fixtures as distinct shapes and threads the new kind through IPC view rows.

Files Change
packages/layout/src/generators.ts, layout-spec.ts, presets.ts, types.ts, client.ts, index.ts Add interleavedLayout generator with first/stagger options, spec parsing, and preset registration
packages/layout/src/routing.ts, packages/layout/__tests__/routing.test.ts Thread kind through unified/device routing with projector-on-FB4 validation
packages/osc/src/osc-adapters.ts, packages/osc/src/index.ts Add BEYOND adapter: projector range clamping, cue/fx encoding, per-target projector maps
packages/receiver/src/receiver.ts, command-types.ts, adapters.ts Shard-aware projector command re-basing and adapter fan-out
packages/desktop/src/main/light-map.ts, project-config.ts, packages/desktop/src/types/ipc.ts, renderer/routes/lights-route.tsx, packages/ui/src/components/grid-display.tsx Render projector fixtures in desktop UI and carry kind in IPC fixture rows
packages/desktop/src/main/project-config.ts, examples/routing-interleaved-12x2.json, docs and test files Config support, example show file, and coverage for the new generator/adapter paths

Reviewed commit: 871c274

@luxor-code-review luxor-code-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR adds interleaved projector+cannon layout generation with staggered rows, kind-aware unified routing validation, BEYOND projector-cue OSC encoding, shard-aware projector control re-basing in the receiver, and desktop UI rendering of projector fixtures.

Key findings

Comment on lines +134 to +142
const other: FixtureKind = first === 'cannon' ? 'projector' : 'cannon';
const cx = (cols - 1) / 2;
const cy = (rows - 1) / 2;
const raw: RawFixture[] = [];
for (let r = 0; r < rows; r++) {
for (let c = 0; c < cols; c++) {
const kind = c % 2 === 0 ? first : other;
const drop = kind === 'projector' ? stagger : 0;
raw.push({ x: c - cx, y: r - cy + drop, row: r, col: c, label: `${r}:${c}`, kind });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

Validate first kind in interleavedLayout

interleavedLayout validates cols/rows/stagger but never validates first (packages/layout/src/generators.ts:134): any string other than exactly 'cannon' makes other compute to 'cannon' while even columns silently receive the raw value as their Fixture.kind. Since resolveLayout forwards spec.first straight from user-authored JSON config or IPC (packages/layout/src/presets.ts:98-105), a typo like "cannonn" persists an invalid kind into every even-column fixture, and downstream === 'projector' checks misclassify them.

📋 Prompt for AI Agents

In packages/layout/src/generators.ts, inside interleavedLayout (around lines 129-133), add a validation immediately after the stagger check: throw an Error when first is neither 'cannon' nor 'projector', mirroring the message style of the stagger validation. This is needed because first arrives from unvalidated config JSON via resolveLayout (packages/layout/src/presets.ts ~line 98), and without the check a typo like 'cannonn' becomes the kind of every even-column fixture, leaking an invalid FixtureKind into layouts, receivers, and the UI.

Comment on lines +197 to +200
function clamp(v: number, [lo, hi]: [number, number]): number {
if (!Number.isFinite(v)) return lo;
return Math.min(hi, Math.max(lo, v));
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

NaN projector controls clamp to range minimum

clamp returns lo for any non-finite value (packages/osc/src/osc-adapters.ts:197-200), so a non-finite control produced upstream (pattern math, or an unvalidated wire value reaching the receiver) is encoded as the most extreme command in its range: posx: NaN emits -32768 slamming the scanning head to a corner, size: NaN sends -400, scanrate: NaN sends 10, and a NaN fx slot becomes -1, which stops a running BEYOND effect (osc-adapters.ts:219, 223). These are valid, physically meaningful commands, so the corruption is invisible at the protocol level and reaches the projector.

📋 Prompt for AI Agents

In packages/osc/src/osc-adapters.ts, change the encoding loop in encodeBeyondProjectorMessages (lines 216-225): for scalar controls (lines 217-219), skip the field with continue when !Number.isFinite(v) instead of calling clamp (which currently maps NaN to the range minimum, e.g. size -400, scanrate 10). For fx slots (lines 222-224), skip the slot when !Number.isFinite(v) before the Math.round/clamp, since NaN currently clamps to -1 which stops a running BEYOND effect. Keep clamping for finite out-of-range values.

Comment on lines +910 to +913
case 'projector_cue':
if (msg.command && typeof msg.command === 'object') {
broadcastCommand({ action: 'projector_cue', command: msg.command });
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

Malformed cue command falls through to StopAllNow

The server relays projector_cue after only checking typeof msg.command === 'object' (packages/server/src/server.ts:910-913), and the receiver passes it straight to BeyondOscOutput.sendCue. In encodeBeyondCueMessage (osc-adapters.ts:231-238), any object matching none of the three variants — e.g. {foo: 1} or {cueDown: {}} with missing fields — falls through to the StopAllNow branch, immediately stopping every laser in the show, and a cueDown with non-numeric page/cue sends NaN int32 args. A malformed client message therefore has a destructive default instead of being rejected.

📋 Prompt for AI Agents

In packages/server/src/server.ts around lines 910-913, in the case 'projector_cue': handler, replace the bare typeof msg.command === 'object' check with structural validation: accept only {cueDown:{page:number,cue:number}}, {stopZone:number}, or {stopAllNow:true} with finite numbers, and ignore anything else (optionally export an isValidProjectorCueCommand guard from @wavegrid/osc next to ProjectorCueCommand and use it in both server and receiver). This prevents a malformed command from falling through encodeBeyondCueMessage's default branch in packages/osc/src/osc-adapters.ts:231-238, which sends a destructive /beyond/general/StopAllNow.

Comment on lines +537 to +545
sendProjector(controls: Record<number, ProjectorControl>): void {
const filtered: Record<number, ProjectorControl> = {};
for (const [key, control] of Object.entries(controls)) {
const idx = Number(key);
if (this.projectorIndices.has(idx)) filtered[idx] = control;
}
if (Object.keys(filtered).length === 0) return;
for (const adapter of this.beyondAdapters) adapter.sendProjector(filtered);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 bug · high

Projector controls leak across BEYOND targets

RoutedOscOutput.sendProjector filters controls by a single global projectorIndices set and broadcasts the filtered map to ALL beyond adapters (packages/osc/src/osc-adapters.ts:537-545); each adapter re-filters only by its own projectorMap (osc-adapters.ts:287). With two BEYOND targets, a control intended for a projector on target A is also delivered to target B whenever B has any route with the same logical index — including an ordinary cannon route, whose logical index is in B's projectorMap — so B's zone receives livecontrol size/posx/rotz commands meant for a different fixture on a different machine.

📋 Prompt for AI Agents

In packages/osc/src/osc-adapters.ts, RoutedOscOutput (constructor lines 482-507 and sendProjector lines 537-545): replace the flat projectorIndices: Set<number> with a per-target mapping, e.g. projectorIndicesByTarget: Map<string, Set<number>>, populated in the constructor only when cannon.kind === 'projector' AND the cannon lands in beyondMaps[cannon.target]. In sendProjector, for each beyond target, build the filtered subset of controls whose logical index is in that target's projector set and pass only that subset to that target's adapter (store the target name alongside each adapter). Update the projectorLogicals getter accordingly.

@devin-ai-integration

Copy link
Copy Markdown
Contributor

Local test drive (Electron desktop + browser artist UI + real loopback UDP OSC listener on 127.0.0.1:8000; no laser hardware).

Artist UI, interleaved-12x2, red paint on cannon 0 + projector 1 Desktop Lights map, 24 fixtures
Painted cannon and projector Desktop fixture map
Ocean scene (all 24 lit) Rainbow animation
Ocean Rainbow

OSC captured on the wire:

OSC capture

  • Both painted zones emit red 255 / green 0 / blue 0 / alpha 255 / Brightness 100 — projectors take colour + brightness exactly like cannons.
  • {type:"projector", indices:[0,1], control:{size:60, rotoz:45}} → only /beyond/zone/1/livecontrol/size 60 and /rotoz 45; zone 0 (cannon) receives nothing. {type:"projector_cue", command:{cueDown:{page:0,cue:2}}} → /beyond/general/CueDown ,ii [0, 2].
  • ring-6 still renders six round orbs and paints. examples/routing-interleaved-12x2.json imports; a copy with projector 1 on an FB4 target is rejected with "Projector 1 drives FB4 target …".
  • Docs fix pushed in db3da9c: client messages are type-keyed (the earlier examples said action).

A wide layout (12x2) now fills the canvas width and keeps its row spacing
instead of being stretched to a square, so the 24 fixtures sit in one
contiguous finger-paintable band. Projector stagger default drops from
0.35 to 0.15 cells so the rows read as two rows, not four.
@pyramation
pyramation merged commit a5430a2 into main Nov 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant