From a9876adc6f92a73f8b88edac6152d91c78972a29 Mon Sep 17 00:00:00 2001 From: Cameron Date: Tue, 7 Jul 2026 22:03:49 -0700 Subject: [PATCH] Design session: actions live on the thing; material render spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two captures. (1) Context menu: from Cameron's playtest ('hard to play; a context menu rather than a bunch of buttons'), adopted as the companion law to Work is somewhere — anchor verbs move into a context menu at the focus, backed by one read-only available_actions query; the rail becomes status only. New constitution section, decisions-log entry, spec wiki/interface/context-menu.md (READY), ROADMAP #26. (2) Material render: Cameron's HD-2D verdict (land the toggle — landed as b9f6086 — and write the art spec): wiki/interface/material-render.md (READY) captures the prototype's debts and the fog contract; ROADMAP #27. Docs only; the amendments precede the implementations. Defense: 'Justification and legibility' — the 2026-07-07 playtest showed anchor actions scattered across global keys read as memorization, not play; anchoring verbs to their objects with cost and signature shown before commit is that clause applied to input. The material-render spec binds an approved experiment to acceptance criteria instead of leaving an unmeasured toggle in the tree. --- DESIGN.md | 34 ++++++++++ wiki/SUMMARY.md | 2 + wiki/interface/context-menu.md | 86 ++++++++++++++++++++++++ wiki/interface/material-render.md | 66 ++++++++++++++++++ wiki/log/2026-07-07-ui-design-session.md | 24 +++++++ wiki/log/DEVLOG.md | 8 +++ wiki/process/ROADMAP.md | 24 +++++++ wiki/process/specs.md | 2 + 8 files changed, 246 insertions(+) create mode 100644 wiki/interface/context-menu.md create mode 100644 wiki/interface/material-render.md create mode 100644 wiki/log/2026-07-07-ui-design-session.md diff --git a/DESIGN.md b/DESIGN.md index 447a83c2..278cbae8 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -176,6 +176,23 @@ model. Until the reshape, the global bar remains the mechanic and the device residency is honest presentation (the job genuinely runs on the host — it is the only machine that hosts it). +## Actions live on the thing + +Adopted 2026-07-07. The companion law to "Work is somewhere": if work +and knowledge are anchored to devices, people, and places, the verbs +that act on them are too. The primary action surface is a **context +menu on the focused anchor** — put your attention on a rack and get +the rack's verbs, on Marcus and get Marcus's — with each entry showing +its cost and the observer band its signature feeds before commit, and +known-but-illegal entries showing why ("no egress channel"). The right +rail is status and telemetry, never a button pile; only anchorless +globals (pause, speed, save, view flip, the allocation bar) stay on +keys. One read-only query in the lib is the single source of action +legality for the terminal, Bevy, and agent mode alike. Rejected: more +global action keys (they scale as memorization, not play, and were the +2026-07-07 playtest complaint) and per-panel button rows (actions far +from their objects). Spec: wiki/interface/context-menu.md. + ## Justification and legibility Adopted 2026-07-06. The forward half of no-dead-code: existence is not @@ -1651,3 +1668,20 @@ knows."* to remove); keeping the job abstract (the last system violating the device-anchored direction the flow-law chain set); reshaping compute.md immediately (collides with the in-flight economy/income work orders). +- **2026-07-07 — Actions live on the thing (the context menu).** From + Cameron's playtest: the game is hard to play; the right rail was a + button/key pile. Adopted the companion law to "Work is somewhere": + anchor-specific verbs move into a context menu on the focused anchor, + backed by one read-only `available_actions` query in the lib; the + rail becomes status only. Rejected: more global keys; per-panel + button rows. Spec: wiki/interface/context-menu.md. +- **2026-07-07 — Material render: land the toggle, spec the debts.** + Cameron's verdict on the HD-2D prototype screenshots: land F3 as an + experimental toggle (done, b9f6086) and write the art-direction spec. + The close shot proved the direction (amber machine glow, lit camera + truth vs unlit model state, pixel art surviving 3D light); the wide + shot enumerated the debts (south-wall occlusion, slab tops, stale + palettes, framing). Spec: wiki/interface/material-render.md — drives + the material render to default once the debts are paid. Rejected: + iterate-before-landing (the toggle is default-off and harmless) and + full low-poly 3D (asset cost without fantasy payoff). diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index 9974471a..554c67ae 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -59,6 +59,8 @@ - [Bevy visual floor](interface/bevy-visual-floor.md) - [Bevy digital/real canvas](interface/bevy-digital-real-canvas.md) - [Views: digital and physical](interface/views.md) + - [Context menu](interface/context-menu.md) + - [Material render](interface/material-render.md) - [Agent play](interface/agent-play.md) # Art diff --git a/wiki/interface/context-menu.md b/wiki/interface/context-menu.md new file mode 100644 index 00000000..3e664155 --- /dev/null +++ b/wiki/interface/context-menu.md @@ -0,0 +1,86 @@ +# Spec: context menu — actions live on the thing + +``` +Type: spec +Status: READY +Status note: interaction redesign from Cameron's 2026-07-07 playtest + ("hard to play; a context menu rather than a bunch of buttons"). The + action surface moves from global keys/rail buttons to a menu on the + focused anchor. Frontend + one read-only lib query; no sim behavior + changes. +Stage: B1 — The Basement +Constitution: "Actions live on the thing" (this spec's law), + "Work is somewhere" (the anchors actions attach to), + "Justification and legibility" (every entry shows cost and expected + signature before commit; illegal entries show why), + "Presence: the cursor and the senses" (the menu opens where attention + is), "The terminal is a first-class frontend" (parity), + "Automation as design language" (every automatable verb carries its + automate affordance in the same menu) +Depends on: cursor.md (focus/inspection), reach.md (device anchors), + day-job.md (attended work, the dial), economy.md (flow verbs), + intel.md (tap/process/watch verbs), social.md (person verbs) +``` + +## Behavior + +The focused anchor — a tile, device, machine, person, resident job, or +known flow — exposes its **legal verbs** as a context menu opened at the +point of focus. The menu is the primary action surface; the right rail +is status and telemetry only. + +- **One source of truth:** the lib gains a read-only query, + `Sim::available_actions(anchor) -> Vec`, where an + `ActionDesc` carries: the verb, its Sim command, cost (compute / + money / social pool), the expected signature (as the observer band it + feeds, per the economy.md precedent), and — when the verb applies to + the anchor type but is currently illegal — a `disabled_reason` string + ("no egress channel", "not enough slush", "you can't see them"). + Both frontends and agent mode render this list; no frontend + duplicates legality logic. +- **Epistemic honesty:** the query never returns a verb the player has + not earned — unearned anchors expose nothing, and provenance rules + (cursor.md) govern what the menu may name. Showing a disabled verb + with its reason is for *known* possibilities; unknown ones are absent, + not grayed. +- **Automation in place:** any verb with a standing-policy form (attend + -> standing dial, watch, scheme policies) shows its automate + affordance as a submenu entry of the same verb, at its compute price. +- **Globals stay global:** pause, speed, save/load, view flip, and the + allocation bar keep their keys; they act on no anchor. Everything + anchor-specific leaves the rail. + +## Player surface + +- **Terminal:** cursor + Enter (or `a`) opens a compact overlay list at + the cursor; j/k or numbers select; Enter executes; esc closes. Entries + render `verb cost [band]` with disabled entries dimmed plus reason. +- **Bevy:** right-click (or Enter on the focused tile) opens the menu at + the pointer; same content, same order, click to execute; esc/click-away + closes. +- **Agent mode:** an `actions` command prints the ActionDescs for the + current focus in a stable line format; execution stays the existing + verbs. Documented in agent-play.md. + +## Acceptance criteria + +1. `available_actions` returns exactly the verbs executable on that + anchor now, each with cost, expected signature band, and + disabled_reason where applicable; unit tests cover a device, a + person, the host rack's resident job, and a known flow. +2. The query respects fog and provenance: an unearned anchor exposes no + verbs, and no entry names a fact the player lacks (test: unseen + person, untapped accounting system). +3. Terminal renders the menu at the cursor with selection, execution, + dim+reason for disabled entries; every previously key-bound + anchor action is reachable through it. +4. Bevy renders the same menu on right-click/Enter with identical + content and order. +5. Agent mode `actions` lists the same descriptors (stable format, + documented); the act-one integration test still passes driven + through existing verbs. +6. No per-anchor action buttons remain on the sidebar/rail in either + frontend; global keys are unchanged and listed in README + key hints. +7. Menu entries carrying an automate affordance show it in place with + its compute price (day-job standing dial and one intel watch at + minimum). diff --git a/wiki/interface/material-render.md b/wiki/interface/material-render.md new file mode 100644 index 00000000..d3d4a93c --- /dev/null +++ b/wiki/interface/material-render.md @@ -0,0 +1,66 @@ +# Spec: material render — HD-2D to default quality + +``` +Type: spec +Status: READY +Status note: the F3 material-render toggle landed 2026-07-07 (b9f6086) + as an approved experiment; Cameron's verdict was "land the toggle and + write the art spec". This spec drives the material render from + prototype to the game's default physical view. Findings inventory: + wiki/log/2026-07-07-hd2d-prototype.md. +Stage: B1 — The Basement +Constitution: "Two views of one world" via interface/views.md (the + same-frame canvas; this is the real/material treatment), + "Visual identity: clinical gore" (lighting is the mood carrier: + amber machine presence, cold fluorescence, darkness as ignorance), + "Justification and legibility" (the render may not show unearned + facts; readability beats spectacle) +Depends on: views.md (same-frame contract), cursor.md (fog states), + bevy-visual-floor.md (framing floor), the landed F3 toggle +``` + +## Behavior + +The material render (Camera3d, extruded walls, billboarded sprites, +lit) becomes the default physical-view treatment in Bevy once its debts +are paid; the flat sensorium render remains the digital-layer treatment +and the terminal remains first-class. The prototype's fog contract is +law: unknown space is absent geometry, blueprint/remembered surfaces +render unlit, only camera-seen surfaces participate in lighting. + +## The debts (from the prototype findings) + +1. **South-wall occlusion:** walls between the camera and room + interiors hide them at the 40 degree pitch. Fix by cutaway (short or + faded south faces) or steeper pitch; pick by screenshot comparison. +2. **Slab tops:** extruded boxes reuse wall textures on top faces and + read as gray slabs. Top faces get a dedicated treatment (darkened + variant or a top-face texture set). +3. **Stale palettes:** the door PNG reads purple under 3D light; sweep + tiles for palette debts against the clinical-amber palette. +4. **Framing:** the visual-floor rules (fit-to-known-content, no + postage stamp, no void-dominant frame) hold in material mode at all + zoom levels. +5. **Perf:** materials pooled by (tile, fog, part) and handle-swapped; + no per-tile unique material mutation (prototype finding 5). +6. **People:** the procedural silhouette billboards are placeholders; + they read as presence, not identity, until the cast sprite pass — + identity stays a panel/menu fact (legibility, not portraiture). + +## Acceptance criteria + +1. Room interiors are readable at default pitch: the chosen occlusion + fix (cutaway or pitch) lands with before/after screenshots in the + session log. +2. Top faces no longer read as untextured slabs (dedicated treatment). +3. No stale-palette tiles remain in the b1 set under 3D light (door + fixed; sweep recorded). +4. The fog contract holds and is asserted: unknown = no geometry, + blueprint/remembered = unlit, seen = lit (screenshot or debug-dump + verification recorded in the log). +5. Framing floor holds in material mode (fit, zoom bounds, no void + dominance) — checked at min/default/max zoom. +6. Material pooling implemented; tile-count-scaled material churn is + gone (no per-tile unique materials in the frame loop). +7. Material render becomes the default physical view (F3 still flips + to sensorium); README and bevy.md updated; terminal unaffected. diff --git a/wiki/log/2026-07-07-ui-design-session.md b/wiki/log/2026-07-07-ui-design-session.md new file mode 100644 index 00000000..5d4f5823 --- /dev/null +++ b/wiki/log/2026-07-07-ui-design-session.md @@ -0,0 +1,24 @@ +# 2026-07-07 - Design session: actions live on the thing; material render spec + +``` +Type: log +``` + +Two captures from Cameron's evening playtest and the HD-2D verdict. + +**Context menu.** "It's really quite hard to play right now, might +benefit from a context menu rather than a bunch of buttons." Adopted as +the companion law to "Work is somewhere": anchor verbs move to a context +menu at the focus, one read-only available_actions query in the lib is +the single legality source for terminal/Bevy/agent mode, the rail +becomes telemetry. Constitution section "Actions live on the thing" + +decisions-log entry; spec wiki/interface/context-menu.md (READY); +ROADMAP #26. + +**Material render.** Verdict on the prototype screenshots: land the +toggle (landed as b9f6086 by the parallel session), write the art spec. +wiki/interface/material-render.md (READY) captures the debts from the +prototype findings (occlusion, slab tops, palettes, framing, pooling) +and the fog contract as law; ROADMAP #27 drives it to default. + +Docs-only commit; implementations dispatched separately. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index ac44c1bf..905613cb 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -29,6 +29,14 @@ Reverse chronological implementation notes. Keep this factual: what changed, why clippy --all-targets --features bevy_ui -- -D warnings`; `git diff --check`; `MISALIGNED_SHOT=flat MISALIGNED_SHOT_PATH=/tmp/misaligned-occlusion-buffer-zero-slush.png cargo run --features bevy_ui --bin misaligned-bevy`. +## 2026-07-07 - Design session: actions live on the thing + +- Adopted the context-menu interaction law (constitution "Actions live + on the thing"; spec interface/context-menu.md; ROADMAP #26) from + Cameron's playtest, and wrote the material-render art spec + (interface/material-render.md; ROADMAP #27) per the HD-2D verdict. +- Docs only. Log: wiki/log/2026-07-07-ui-design-session.md. + ## 2026-07-07 - Bevy sidebar becomes a command surface - Intent: respond to Cameron's screenshot review that the scrollable right pane diff --git a/wiki/process/ROADMAP.md b/wiki/process/ROADMAP.md index 521c3b7f..ef1c5d78 100644 --- a/wiki/process/ROADMAP.md +++ b/wiki/process/ROADMAP.md @@ -78,6 +78,30 @@ but only once Pixel Lab quota is available again. (#2 Bevy parity is done.) migration, both frontends. Run ./tools/check.sh, land on main, update compute.md and day-job.md Statuses." +### 26. Context menu: actions live on the thing 🟩 frontends + one lib query +- **Spec:** [context-menu.md](../interface/context-menu.md) (READY; + constitution "Actions live on the thing", adopted 2026-07-07) +- **Why:** the playtest complaint — anchor verbs are a global key pile. + One read-only `available_actions` query in the lib; menu at the focus + in terminal, Bevy, and agent mode; the rail becomes status only. +- **Size:** M. Frontend-heavy, lib change is additive/read-only. +- **Dispatch:** "Work in a worktree named `context-menu`. Implement + wiki/interface/context-menu.md, all criteria: the available_actions + query with tests, the terminal cursor menu, the Bevy right-click menu, + the agent-mode actions verb, rail cleanup. Run ./tools/check.sh, land + on main, set the spec Status." + +### 27. Material render to default 🟩 isolated (src/bin/bevy.rs + assets) +- **Spec:** [material-render.md](../interface/material-render.md) + (READY; the F3 toggle landed b9f6086, Cameron approved the direction) +- **Why:** pay the prototype's debts (south-wall occlusion, slab tops, + stale palettes, framing, material pooling) and flip material to the + default physical view. +- **Size:** M. **Dispatch:** "Work in a worktree named `material-render`. + Implement wiki/interface/material-render.md, all criteria, with + before/after screenshots in the session log. Run ./tools/check.sh, + land on main, set the spec Status." + ### 4. Detection → IMPLEMENTED 🟧 sim - **Spec:** [detection.md](../mechanics/detection.md) (IN PROGRESS) — [aggregate-observer.md](../mechanics/aggregate-observer.md) is now IMPLEMENTED. diff --git a/wiki/process/specs.md b/wiki/process/specs.md index b83870ca..8920f98f 100644 --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -37,6 +37,8 @@ replaced the old `spec/`/`knowledge/` directory split. | [mechanics/income.md](../mechanics/income.md) | The named income schemes riding economy.md: Moonlight and the Wager | READY | | [mechanics/research.md](../mechanics/research.md) | Self-modification: tracks, the emission law, capability drift, the rollback split | READY | | [interface/views.md](../interface/views.md) | Same-frame digital and real representations of one world | READY | +| [interface/context-menu.md](../interface/context-menu.md) | Context menu: anchor verbs at the focus; the rail is status only | READY | +| [interface/material-render.md](../interface/material-render.md) | Material render (HD-2D) from landed toggle to default quality | READY | | [mechanics/building.md](../mechanics/building.md) | Building as intent + actuators: network links, favor/forged-order builds, air-gap bridging | READY | | [mechanics/aggregate-observer.md](../mechanics/aggregate-observer.md) | Assurance Office becomes an aggregate Observer (scale-debt fix) | IMPLEMENTED | | [world/characters/marcus.md](../world/characters/marcus.md) | Marcus Webb — night janitor; the asset template | READY | -- 2.51.2