repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

fix brainstorming visual feedback loop

a5263eebd21cb61fe1f23f1fa1689f56486ab4ec

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

skills/super/brainstorming/scripts/companion.mjs

Modified
21 21 Commands:
22 22 start-choice --project-dir DIR --name NAME --title TITLE --option choice|title|description
23 23 start-screen --project-dir DIR --name NAME (--html HTML | --html-file FILE)
24 - open-choice --project-dir DIR --name NAME --title TITLE --option choice|title|description [--timeout-ms MS<=30000]
25 - open-screen --project-dir DIR --name NAME (--html HTML | --html-file FILE) [--timeout-ms MS<=30000]
24 + open-choice --project-dir DIR --name NAME --title TITLE --option choice|title|description [--timeout-ms MS<=3600000]
25 + open-screen --project-dir DIR --name NAME (--html HTML | --html-file FILE) [--timeout-ms MS<=3600000]
26 26 stop SESSION_DIR
27 27 cleanup
28 28 write-screen SESSION_DIR --name NAME (--html HTML | --html-file FILE)
29 29 choice-screen SESSION_DIR --name NAME --title TITLE [--subtitle TEXT] --option choice|title|description [--multi]
30 - ask-choice SESSION_DIR --name NAME --title TITLE [--subtitle TEXT] --option choice|title|description [--timeout-ms MS<=30000]
31 - ask-screen SESSION_DIR --name NAME (--html HTML | --html-file FILE) [--timeout-ms MS<=30000]
30 + ask-choice SESSION_DIR --name NAME --title TITLE [--subtitle TEXT] --option choice|title|description [--timeout-ms MS<=3600000]
31 + ask-screen SESSION_DIR --name NAME (--html HTML | --html-file FILE) [--timeout-ms MS<=3600000]
32 32 waiting-screen SESSION_DIR --name NAME
33 33 events SESSION_DIR [--clear]
34 - wait-choice SESSION_DIR [--timeout-ms MS<=30000]
34 + listen --project-dir DIR [--clear] [--timeout-ms MS<=3600000]
35 + wait-choice SESSION_DIR [--timeout-ms MS<=3600000]
37 38 function die(message) {
77 +function latestSession(projectDir) {
78 + if (!projectDir) die("Missing --project-dir");
79 + const root = path.join(projectDir, ".super", "brainstorm");
80 + if (!fs.existsSync(root)) die("No brainstorm sessions found");
81 + const sessions = fs
82 + .readdirSync(root, { withFileTypes: true })
83 + .filter((entry) => entry.isDirectory())
84 + .map((entry) => path.join(root, entry.name))
85 + .filter((sessionDir) =>
86 + fs.existsSync(path.join(sessionDir, "state", "server-info")),
87 + )
88 + .map((sessionDir) => ({
89 + sessionDir,
90 + mtime: fs.statSync(path.join(sessionDir, "state", "server-info")).mtimeMs,
91 + }))
92 + .sort((a, b) => b.mtime - a.mtime);
93 + if (sessions.length === 0) die("No running brainstorm session found");
94 + return sessions[0].sessionDir;
76 97 function requireAlive(paths) {
77 98 if (!fs.existsSync(path.join(paths.stateDir, "server-info")))
78 99 die("Brainstorm server is not running; start it first.");
121 142 function timeoutMs(flags) {
122 - const value = Number(flags["timeout-ms"] ?? 30_000);
143 + const value = Number(flags["timeout-ms"] ?? 600_000);
123 144 if (!Number.isFinite(value) || value <= 0)
124 145 die("--timeout-ms must be a positive number");
125 - if (value > 30_000) die("--timeout-ms max is 30000ms");
146 + if (value > 3_600_000) die("--timeout-ms max is 3600000ms");
126 147 return value;
227 248 die(`Timed out waiting for choice after ${timeoutMs}ms`);
251 +async function listen(projectDir, { clear = false, timeoutMs = 0 } = {}) {
252 + const sessionDir = latestSession(projectDir);
253 + const { eventsFile } = sessionPaths(sessionDir);
254 + const deadline = Date.now() + timeoutMs;
255 + let events = readEvents(eventsFile);
256 + while (events.length === 0 && Date.now() <= deadline) {
257 + await sleep(50);
258 + events = readEvents(eventsFile);
260 + if (clear) fs.rmSync(eventsFile, { force: true });
261 + console.log(JSON.stringify({ session_dir: sessionDir, events }));
230 264 async function waitChoice(sessionDir, timeoutMs) {
231 265 console.log(JSON.stringify(await waitChoiceEvent(sessionDir, timeoutMs)));
417 451 return;
454 + if (command === "listen") {
455 + const flags = parseFlags(rest);
456 + await listen(flags["project-dir"], {
457 + clear: Boolean(flags.clear),
458 + timeoutMs: flags["timeout-ms"] === undefined ? 0 : timeoutMs(flags),
459 + });
460 + return;
420 463 if (command === "wait-choice") {
421 464 const [sessionDir, ...args] = rest;
422 465 const flags = parseFlags(args);

skills/super/brainstorming/scripts/helper.js

Modified
3 3 (() => {
4 4 const WS_URL = "ws://" + window.location.host;
5 5 let ws = null;
6 6 let eventQueue = [];
8 + function ensureHumanNotes() {
9 + if (document.getElementById("human-notes")) return;
10 + const bar = document.createElement("div");
11 + bar.id = "human-notes-bar";
12 + bar.innerHTML =
13 + '<div class="human-notes-brand"><span class="human-notes-sigil">N</span><span><b>Nugu notes</b><small>sent with click</small></span></div><textarea id="human-notes" aria-label="Notes to agent" placeholder="what you like · what sucks · what to change"></textarea>';
14 + document.body.appendChild(bar);
15 + const style = document.createElement("style");
16 + style.textContent = `
17 + #human-notes-bar { position: fixed; left: 50%; bottom: 18px; transform: translateX(-50%); z-index: 2147483647; width: min(960px, calc(100vw - 28px)); display: grid; grid-template-columns: max-content 1fr; gap: 0.9rem; align-items: center; padding: 0.75rem; background: linear-gradient(135deg, rgba(18,18,18,0.98), rgba(34,20,34,0.98)); border: 1px solid #d86dd8; border-radius: 14px; box-shadow: 0 18px 48px rgba(0,0,0,0.55), 0 0 0 1px rgba(216,109,216,0.25) inset; color: #ededed; font: 13px "IBM Plex Sans", system-ui, sans-serif; }
18 + .human-notes-brand { display: grid; grid-template-columns: 34px max-content; gap: 0.65rem; align-items: center; color: #ededed; }
19 + .human-notes-sigil { width: 34px; height: 34px; display: grid; place-items: center; border: 2px solid #d86dd8; color: #d86dd8; background: #121212; font: 900 18px "IBM Plex Mono", monospace; box-shadow: 4px 4px 0 #000; }
20 + .human-notes-brand b { display:block; color:#ededed; font: 800 13px "IBM Plex Mono", monospace; letter-spacing: .04em; text-transform: uppercase; }
21 + .human-notes-brand small { display:block; color:#a8a8a8; font-size: 11px; margin-top: 1px; }
22 + #human-notes { min-height: 2.65rem; max-height: 9rem; resize: vertical; width: 100%; border: 1px solid rgba(216,109,216,0.55); border-radius: 10px; background: #0f0f0f; color: #ededed; caret-color: #d86dd8; padding: 0.62rem 0.75rem; font: 14px "IBM Plex Sans", system-ui, sans-serif; outline: none; }
23 + #human-notes:focus { border-color: #d86dd8; box-shadow: 0 0 0 3px rgba(216,109,216,0.18); }
24 + #human-notes::placeholder { color: #777; }
25 + body { padding-bottom: 6.25rem !important; }
26 + `;
27 + document.head.appendChild(style);
28 + }
30 + function humanNotes() {
31 + return document.getElementById("human-notes")?.value?.trim() || "";
32 + }
8 34 function connect() {
9 35 ws = new WebSocket(WS_URL);
26 52 function sendEvent(event) {
27 53 event.timestamp = Date.now();
54 + event.humanNotes = humanNotes();
28 55 if (ws && ws.readyState === WebSocket.OPEN) {
29 56 ws.send(JSON.stringify(event));
30 57 } else {
62 + ensureHumanNotes();
63 + if (document.readyState === "loading")
64 + document.addEventListener("DOMContentLoaded", ensureHumanNotes);
35 66 // Capture clicks on choice elements
36 67 document.addEventListener("click", (e) => {
37 68 const target = e.target.closest("[data-choice]");

skills/super/brainstorming/visual-companion.md

Modified
78 78 --html-file /tmp/first-mockup.html
81 +**Thinking time rule:** Do not use short blocking waits for visual decisions that need real thinking time: logo direction, style exploration, layout comparison, subjective polish, multi-option mockups, or anything the user may want to inspect. Blocking commands now default to 10 minutes and allow up to 1 hour, but for open-ended design thinking prefer `write-screen` or `start-screen`, give the URL, and later read clicks with `events`.
83 +**Human notes rule:** Every visual screen includes a human notes textarea. Browser click events include `humanNotes`; use those notes as first-class user feedback, not an afterthought. If the notes contradict the clicked option, ask one clarifying question or iterate toward the notes.
85 +**NON-NEGOTIABLE FIRST ACTION after any visual screen:** before replying, before reading files, before making new mockups, before explaining, run:
87 +```bash
88 +node scripts/companion.mjs listen --project-dir PROJECT --clear
89 +```
91 +This finds the newest project session, so there is no session ID for the agent to remember. Skipping this is a skill violation. Do not use `events SESSION_DIR` unless debugging the companion itself. Treat returned clicks and `humanNotes` as the user's current visual answer unless the terminal message explicitly overrides them. Never ask the user to repeat a clicked choice in chat. If there are no events, proceed from the terminal text.
81 93 If `open-choice` / `open-screen` cannot open a browser in the current environment, fall back to `start-choice` / `start-screen`, save `session_dir` from the response, and tell the user to open the URL. Never use `start` alone; it is rejected because the browser would show the waiting page.
83 95 **Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.super/brainstorm/` for the session directory.
114 126 ## The Loop
116 -1. **For visual choices, ask and wait in one deterministic command.** It checks the server, writes a fresh filename, clears old events, blocks for the browser click, then prints the selected event JSON:
128 +1. **For quick visual choices only, ask and wait in one deterministic command.** It checks the server, writes a fresh filename, clears old events, blocks for the browser click, then prints the selected event JSON. Do not use this path for subjective design thinking; use the thinking time rule above.
118 130 ```bash
119 131 node scripts/companion.mjs ask-choice "$SESSION_DIR" \
122 134 --subtitle "Consider readability and visual hierarchy" \
123 135 --option "single|Single Column|Clean, focused reading experience" \
124 136 --option "two|Two Column|Sidebar navigation with main content" \
125 - --timeout-ms 30000
137 + --timeout-ms 600000
128 - Do not tell the user "reply here after clicking" for normal visual choices. The click itself returns to the agent through the tool result while the turn is active. Never set `--timeout-ms` above `30000`; the script rejects slower waits.
140 + Do not tell the user "reply here after clicking" for normal visual choices. The click itself returns to the agent through the tool result while the turn is active. Use long waits for user-facing visual choices; never rush subjective decisions.
130 142 2. **For custom visual choices, write HTML to a file, then ask and wait.** Do not embed large HTML in shell args or heredocs.
134 146 node scripts/companion.mjs ask-screen "$SESSION_DIR" \
135 147 --name layout-custom \
136 148 --html-file /tmp/layout-options.html \
137 - --timeout-ms 30000
149 + --timeout-ms 600000
140 152 The HTML must include clickable elements with `data-choice` and `onclick="toggleSelect(this)"`.
151 163 Remind them of the URL and ask for terminal feedback only when the answer is open-ended text, not a choice.
153 -4. **For existing browser feedback, use the script:**
165 +4. **For existing browser feedback, only use `listen`:**
155 167 ```bash
156 - node scripts/companion.mjs events "$SESSION_DIR"
157 - node scripts/companion.mjs wait-choice "$SESSION_DIR" --timeout-ms 30000
158 - node scripts/companion.mjs events "$SESSION_DIR" --clear
168 + node scripts/companion.mjs listen --project-dir /path/to/project --clear
169 + node scripts/companion.mjs listen --project-dir /path/to/project --timeout-ms 600000 --clear
161 - Merge browser events with any terminal text if both exist. Terminal text is primary for open-ended feedback; browser events are primary for visual choices.
172 + Required before every response while visual mode is active. Merge browser events with any terminal text if both exist. Terminal text is primary only when it explicitly overrides browser feedback; otherwise browser clicks + `humanNotes` are primary.
163 174 5. **Iterate or advance** — if feedback changes current screen, push a new screen name (e.g., `layout-v2`). Only move to the next question when the current step is validated.