web: dock editor (mock-only) — grid docking per interaction concept v1

docs/development.md

@@ -86,7 +86,15 @@ npm install
 npm run dev
 ```
 
-Open **http://localhost:8080** in a browser. The mock server (`server/index.js`) handles all REST endpoints and WebSocket, with scenes stored in memory for the duration of the process. Auth is skipped entirely when no environment variables are configured.
+Open **http://localhost:8080** in a browser. The mock server (`server/index.js`) handles all REST endpoints and WebSocket, with scenes stored in memory for the duration of the process.
+
+`npm run dev` expects the auth environment variables (`GITHUB_CLIENT_ID`, `SESSION_SECRET`, `TOKEN_SECRET`, `ALLOWED_GITHUB_USERS`); without them every request redirects to the login. For local work without that setup use:
+
+```bash
+npm run dev:no-auth
+```
+
+The graph editor (mock-only, see the [rework plan](lightwitch-rework-plan.md)'s M8 section) is served from the same process at **http://localhost:8080/graphs.html**.
 
 > Requires Node.js.
 

docs/lightwitch-decisions.md

@@ -65,7 +65,7 @@ in `Config.h`.
 minimal types** (no includes from `src/config`); adapters translate at the
 boundary. Add `[env:native]` plus unit tests with the first engine commit.
 This is less an option than a discipline commitment — without it, §3 (queue,
-scheduler, topological sort, joints) is not reliably developable. The one
+scheduler, topological sort, adapters) is not reliably developable. The one
 thing to decide: does the team accept native tests as a PR gate in CI?
 
 **Resolution (2026-07-24):** deprioritized. No native environment and no
@@ -101,7 +101,7 @@ the user enables them), `off` (ignore graphs from mesh/group entirely).
 
 ### D5 · Canonical graph schema: language & v1 scope ☑️
 
-**Decided: English canonical keys** (`nodes`, `edges`, `requires`), matching
+**Decided: English canonical keys** (`nodes`, `links`, `requires`), matching
 the rest of the repo; German terms appear only as editor labels. This mirrors
 the concept's own §5.5 split between display language and stored form. The v1
 scope additionally includes: the edge list as sketched, the `v` field, the

docs/lightwitch-rework-plan.md

@@ -1,10 +1,28 @@
 # LightWitch rework plan
 
 Derived from the LightWitch system concept v1.0 and the resolved decisions in
-[lightwitch-decisions.md](lightwitch-decisions.md) (D1–D7). Terminology follows
-the repo: **node** (not "Stein"), **graph**, **stage node**, **role**,
-**group**. All identifiers, schema keys, docs, and UI strings are English;
-German appears only as optional editor labels later.
+[lightwitch-decisions.md](lightwitch-decisions.md) (D1–D7).
+
+## Vocabulary
+
+One word per thing, used identically in schema keys, code identifiers, docs,
+and UI strings — there is no separate user-facing vocabulary and no
+translation layer, so a term that reads well in the editor must also be the
+term in the code.
+
+| Term | Meaning |
+|---|---|
+| `graph` | One named, activatable program: nodes plus their links. Stored as one JSON file. |
+| `node` | One building block of logic — a typed unit with ports. Never "Stein"/"stone"/"block". |
+| `port` | A connection point on a node. Input ports sit on the node's left edge, output ports on its right; flow runs left to right. Say "input port"/"output port" when the direction matters. Never "pin" — that means a GPIO pin everywhere else in this project. |
+| `link` | Two ports joined. Arises from adjacency (neighboring columns, row distance ≤ 1), not from a drawn line — so never "wire", "edge", or "connection" (the latter means a network connection everywhere else). |
+| `adapter` | A link between two different signal types, carrying a conversion rule. Which conversions exist is the adapter matrix. |
+| `signal type` | What flows through a port: event, switch, value, color. Shape is the primary code, not colour. |
+| `chip` | The editable default value shown on a free input port. |
+| `arc` | The small curve in the gutter drawn for a link whose two ports sit one row apart — the only line segment in the system. |
+| `rail` | A named portal that links distant nodes without adjacency. |
+| `dock` (verb) | To join two ports by placing their nodes next to each other. |
+| `stage node`, `role`, `group` | As used elsewhere in this repo. |
 
 Scope guardrails (from D3/D7): no native/desktop tooling, no measurement
 suite, no mesh protocol rework. Every milestone ships a usable feature on the
@@ -173,7 +191,7 @@ frozen as of now: bug fixes only, no new trigger types, no new features.
   "nodes": [
     {"id": 1, "type": "button", "role": "button:main", "col": 1, "row": 1, "cfg": {}}
   ],
-  "edges": [[1, "pressed", 2, "start"]],
+  "links": [[1, "pressed", 2, "start"]],
   "notes": [{"col": 1, "row": 5, "text": "registration"}]
 }
 ```
@@ -230,8 +248,8 @@ notice.
 
 ### M4 · Value layer + stage node
 
-Value-layer nodes (`lfo` via LUT, `math`, `hold`, `hsv-mix`, joints/type
-adapters on edges per concept §5.3) and the **stage node**: binds to a light
+Value-layer nodes (`lfo` via LUT, `math`, `hold`, `hsv-mix`, adapters/type
+adapters on links per concept §5.3) and the **stage node**: binds to a light
 role, claims the light through the M1 arbitration, drives its `PatternRunner`
 with a channel-driven pattern (intensity, stimulus, movement, limit, color —
 scenes read the channels they know). Existing patterns stay available as
@@ -275,7 +293,7 @@ ignites its fire scene.
 
 ### M8 · Dock editor (visual)
 
-The concept's dock UI (columns, docking, joints, chain view) on top of the
+The concept's dock UI (columns, docking, adapters, chain view) on top of the
 by-then-proven schema. Explicitly last: the JSON editor (M3) carries all
 functionality until here, and dock details (elbow tolerance, zoom) are decided
 after first editor tests.
@@ -291,6 +309,20 @@ editor tests" this milestone's open dock details wait on. Engine wiring,
 authoritative validation, the full palette, and the remaining dock feature
 set stay here in M8; nothing runs a saved graph until M2.
 
+Two decisions settled while building it:
+
+- **Fan-out runs through rows.** An output port may feed several neighbors,
+  but only as many as it has instance rows — the same `＋` row mechanism that
+  lets an input collect several sources. The number of receivers is therefore
+  visible in the node's height, which keeps "position is the program" intact.
+  An unbounded output with no rows was the alternative and was rejected for
+  hiding that count.
+- **The adapter matrix is provisional.** The four conversions currently
+  offered (value→switch, switch→value, value→color, event→switch) are a
+  working set for the prototype, not the authoritative table — that one lives
+  in system concept §5.3, which is not in this repo yet and replaces these
+  when it lands.
+
 *Touches:* `data/index.html` (likely split into a second page/bundle —
 decide when sizing it).
 

eslint.config.js

@@ -32,4 +32,18 @@ export default [
       'no-var': 'error',
     },
   },
+  {
+    files: ['server/graphs.html'],
+    plugins: { html },
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: globals.browser,
+    },
+    rules: {
+      eqeqeq: 'error',
+      'prefer-const': 'error',
+      'no-var': 'error',
+    },
+  },
 ];