docs(design): modules, buses, panels — ratified design + glossary - #230
Merged
Conversation
…tion Normative design for the nested-projects redesign: project/module mitosis, binding-is-publicity, panel as recursive view of scope channels, lazy runtime panel writers with throttled persistence. Supersedes the direction of the #218 spike (harvest inventory in §9). Plan: planning/2026-07-31-1002-modules-buses-panels. Also: agent-context.toml gains a planning_root fallback (the env var is unset in non-interactive shells). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- modules.md R8: panel is a first-class per-node concept (leaf = bound slots, module = scope channels, playlist = active entry), hosted by faces, standalone in play mode; legacy panel flag subsumption raised as Q13. Spike references stripped — the doc now states what is. - New ADR records the moment-in-time context: spike relationship, harvest inventory, defect pins, alternatives. - docs/glossary.md created (sectioned; module-model terms marked). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…wn imports Everything in the project folder is user-owned content except .lp/, the single framework-owned dir (panel state moves to .lp/state.json; future caches/locks land there). Imported modules stay visible and committed under modules/ — copy-to-own, shadcn-inspired; provenance records origin. Local sub-modules are plain folders with explicit refs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The panel gets its own normative doc, sibling of modules.md. Two ratified frames anchor it: panel state is lighting-console-programmer / DAW-latch capture (hold until explicit clear), and controls shape but never integrate (slew ok; phasors are nodes + bus vocabulary). P1-P13 cover identity, Read/Latch/Clear, takeover (jump; pickup reserved for hardware), live-value display, raw-preserve/clamp-emission under meta changes, PanelWrite/PanelClear wire ops, engine-authority multi-client, restore-before-first-render, .lp/state.json, play mode, and MIDI/OSC as future panel writers. modules.md R9-R13 slim to summaries; Q3/Q11 move to panel.md's register, Q12 is resolved by the latch model. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The old-lightPlayer fluid drawing use case pressure-tests the model and exposes one real gap: gesture channels (multi-touch pads, buttons) cannot latch. panel.md P14 adds the momentary control class — writes while the gesture is active, despawns on release, and the despawn IS the fallback mechanism (resolution falls through to a host camera or an idle-generator node). Idle detection stays a node concern (a gate with a public timeout param) because 'no data' is semantic: a connected camera seeing nobody is a live writer producing an empty set, invisible to any writer-priority scheme. modules.md gains E7 (fluid-draw module walk) and a vocabulary-pressure note (touch sets, phase); P-Q5 tracks the touch-set shape with MultiTouchInput.Touch as prior art. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The ratified design for the nested-projects redesign (G1 passed
2026-07-31; plan: `planning/2026-07-31-1002-modules-buses-panels`).
mitosis, binding-is-publicity, scoped buses with writer-shadowing, sink
scopes, module output interface (auto `visual.out` + authored exports),
worked examples E1–E7, two-tier file layout (`.lp/` vs user content,
copy-to-own imports), rename plan (`project` kind → `module`).
(Read/Latch/Clear), shape-don't-integrate, momentary controls for
gesture channels, takeover, multi-client authority,
restore-before-first-render, `.lp/state.json` persistence.
composite-effects spike direction (PR Scoped buses + embeddable projects (effects slice) #218, unmerged), harvest
inventory, defect classes to pin.
Docs-only (plus one config line). Next: M2 UX spike (G2 visual gate),
then implementation planning (M3).
🤖 Generated with Claude Code