npm - wiki-viewer - Versions diffs - 2.16.0 → 2.16.1 - Mend

wiki-viewer 2.16.0 → 2.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (124) hide show

package/.next/standalone/.scratch/tweak-running-app/mockups.html ADDED Viewed

@@ -0,0 +1,305 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Comments + Suggestions — better UX mockups</title>
+<style>
+:root{
+  --background:#ECEAE3; --foreground:#201F1B; --card:#F4F2EB; --popover:#F4F2EB;
+  --primary:#55552F; --primary-foreground:#F4F2EB; --secondary:#E2DFD6;
+  --muted:#E2DFD6; --muted-foreground:#75726A; --accent:#DEDBD1; --accent-soft:#D9D4AE;
+  --success:#16a34a; --success-soft:#dcfce7; --destructive:#dc2626; --destructive-soft:#fee2e2;
+  --warning:#d97706; --warning-soft:#fef3c7; --warning-ink:#a16207;
+  --border:#D8D5CB; --input:#B8B4A6; --link:#5C5C33; --radius:8px;
+  --shadow-card:0 4px 16px rgba(0,0,0,.04); --shadow-pop:0 8px 24px rgba(0,0,0,.10);
+  --shadow-dialog:0 16px 48px rgba(0,0,0,.14);
+}
+*{box-sizing:border-box}
+html,body{margin:0}
+body{
+  background:var(--background); color:var(--foreground);
+  font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  font-size:15px; line-height:1.5; padding:32px 20px 96px;
+}
+.wrap{max-width:1080px;margin:0 auto}
+h1.page{font-size:24px;margin:0 0 4px;font-weight:650}
+.sub{color:var(--muted-foreground);margin:0 0 4px;max-width:80ch}
+.legend{display:flex;gap:16px;flex-wrap:wrap;margin:16px 0 32px;font-size:12.5px;color:var(--muted-foreground)}
+.legend b{color:var(--foreground);font-weight:600}
+section{margin:0 0 40px}
+.sec-h{display:flex;align-items:baseline;gap:10px;margin:0 0 4px}
+.sec-h .n{font:600 12px ui-monospace,Menlo,monospace;background:var(--primary);color:var(--primary-foreground);border-radius:5px;padding:2px 7px}
+.sec-h h2{font-size:17px;margin:0;font-weight:600}
+.sec-note{color:var(--muted-foreground);font-size:13px;margin:2px 0 14px;max-width:74ch}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:20px;align-items:start}
+.stage{
+  background:var(--card);border:1px solid var(--border);border-radius:12px;
+  padding:22px;position:relative;box-shadow:var(--shadow-card);overflow:hidden;
+}
+.stage.paper{background:#F7F5EE}
+.cap{font-size:12px;color:var(--muted-foreground);margin-top:10px}
+.cap b{color:var(--foreground);font-weight:600}
+.doc{font-family:Georgia,"Times New Roman",serif;font-size:16px;line-height:1.7;color:#2a2823}
+.doc h3{font-size:19px;margin:.2em 0 .5em;font-weight:600}
+.doc p{margin:0 0 1em}
+.btn{font:500 13px inherit;border-radius:7px;padding:7px 12px;border:1px solid var(--border);
+  background:var(--card);color:var(--foreground);cursor:default;display:inline-flex;align-items:center;gap:6px}
+.btn.pri{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}
+.btn.ghost{background:transparent}
+.btn.sm{padding:4px 9px;font-size:12px}
+.btn.link{border:none;background:none;color:var(--muted-foreground);padding:4px 6px}
+.kbd{font:600 11px ui-monospace,monospace;color:var(--muted-foreground)}
+.bubble{display:inline-flex;align-items:center;gap:2px;background:var(--popover);
+  border:1px solid var(--border);border-radius:8px;padding:5px;box-shadow:var(--shadow-pop)}
+.bubble .ic{width:30px;height:30px;display:grid;place-items:center;border-radius:6px;color:#3a3831;font-size:14px}
+.bubble .ic.act{color:var(--primary);font-weight:600}
+.bubble .sep{width:1px;height:20px;background:var(--border);margin:0 4px}
+.bubble .lab{font-size:12px;padding:0 8px;height:30px;display:inline-flex;align-items:center;gap:6px;border-radius:6px;color:#3a3831}
+.bubble .lab.hl{background:var(--accent-soft)}
+.composer{background:var(--popover);border:1px solid var(--border);border-radius:10px;
+  padding:12px;box-shadow:var(--shadow-pop);max-width:400px}
+.ta{width:100%;border:1px solid var(--input);border-radius:7px;background:#FBFAF5;
+  padding:9px 10px;font:15px inherit;color:var(--foreground);resize:none;min-height:60px}
+.ta::placeholder{color:var(--muted-foreground)}
+.crow{display:flex;align-items:center;justify-content:space-between;margin-top:10px;gap:8px}
+.crow .left{display:flex;align-items:center;gap:6px}
+.hint{font-size:11px;color:var(--muted-foreground)}
+.icard{border:1px solid var(--border);border-radius:9px;background:var(--card);padding:11px 12px;max-width:400px}
+.icard .top{display:flex;align-items:center;gap:7px;font-size:12px;color:var(--muted-foreground);margin-bottom:5px}
+.icard .body{font-family:Georgia,serif;font-size:14.5px;color:#2a2823}
+.icard .meta{font-size:11.5px;color:var(--muted-foreground);margin-top:6px}
+.icard .acts{display:flex;gap:6px;justify-content:flex-end;margin-top:9px}
+.pill{font:600 11px inherit;border-radius:999px;padding:2px 8px;display:inline-flex;gap:5px;align-items:center}
+.pill.open{background:var(--secondary);color:var(--muted-foreground)}
+.pill.agent{background:var(--accent-soft);color:#4a4a26}
+.pill.drift{background:var(--warning-soft);color:var(--warning-ink)}
+.ins{color:var(--success);text-decoration:underline;text-decoration-thickness:2px;text-underline-offset:2px}
+.del{color:var(--destructive);text-decoration:line-through;text-decoration-thickness:1.5px}
+.rep-old{color:var(--destructive);text-decoration:line-through}
+.rep-new{color:var(--success);text-decoration:underline;text-underline-offset:2px}
+.blk-ins{border-left:3px solid var(--success);background:var(--success-soft);padding:2px 10px;border-radius:0 6px 6px 0;display:block}
+.blk-del{border-left:3px solid var(--destructive);background:var(--destructive-soft);padding:2px 10px;border-radius:0 6px 6px 0;display:block;opacity:.85}
+.agent-range{background-image:repeating-linear-gradient(45deg,transparent,transparent 4px,rgba(85,85,47,.10) 4px,rgba(85,85,47,.10) 6px);border-radius:3px;padding:0 2px}
+.caret-badge{display:inline-grid;place-items:center;width:16px;height:16px;border-radius:4px;background:var(--primary);
+  color:var(--primary-foreground);font-size:10px;vertical-align:middle;margin:0 2px;transform:translateY(-1px)}
+.comment-pip{display:inline-grid;place-items:center;width:16px;height:16px;border-radius:4px;background:var(--accent-soft);
+  color:#4a4a26;font-size:10px;vertical-align:middle;margin:0 2px;transform:translateY(-1px)}
+.pop{background:var(--popover);border:1px solid var(--border);border-radius:10px;box-shadow:var(--shadow-dialog);
+  padding:11px;max-width:340px}
+.pop .ph{display:flex;align-items:center;justify-content:space-between;font-size:11.5px;color:var(--muted-foreground);margin-bottom:8px}
+.switch{display:inline-flex;align-items:center;gap:8px;font:600 11.5px inherit;color:var(--foreground)}
+.switch button{border:none;background:var(--secondary);border-radius:5px;width:20px;height:20px;color:var(--foreground)}
+.diff{font-family:Georgia,serif;font-size:14px;background:#FBFAF5;border:1px solid var(--border);border-radius:7px;padding:8px 10px;line-height:1.6}
+.pop .acts{display:flex;gap:7px;justify-content:flex-end;margin-top:10px}
+.banner{display:flex;align-items:center;gap:8px;background:var(--accent-soft);color:#4a4a26;
+  border-radius:8px;padding:7px 11px;font-size:12.5px;max-width:400px}
+.statusbar{display:flex;align-items:center;gap:14px;background:var(--card);border:1px solid var(--border);
+  border-radius:8px;padding:7px 12px;font-size:12px;color:var(--muted-foreground);max-width:460px}
+.statusbar .chip{margin-left:auto;background:var(--secondary);border-radius:999px;padding:3px 10px;color:var(--foreground);font-weight:600;display:inline-flex;gap:6px;align-items:center}
+.radio{display:inline-flex;gap:4px;background:var(--secondary);border-radius:7px;padding:3px}
+.radio span{padding:4px 10px;border-radius:5px;font-size:12px;color:var(--muted-foreground)}
+.radio span.on{background:var(--card);color:var(--foreground);box-shadow:0 1px 2px rgba(0,0,0,.06)}
+/* copy-as-prompt panel */
+.panel{background:var(--popover);border:1px solid var(--border);border-radius:10px;box-shadow:var(--shadow-pop);max-width:440px}
+.panel .ph{display:flex;align-items:center;justify-content:space-between;padding:10px 12px;border-bottom:1px solid var(--border);font-weight:600;font-size:13px}
+.plist{padding:6px}
+.pitem{display:flex;gap:9px;align-items:flex-start;padding:8px 8px;border-radius:7px}
+.pitem:hover{background:var(--secondary)}
+.pitem .k{font:600 10.5px ui-monospace,monospace;border-radius:5px;padding:2px 6px;flex:none;margin-top:1px}
+.k.comment{background:var(--accent-soft);color:#4a4a26}
+.k.sugg{background:var(--success-soft);color:#166534}
+.pitem .txt{font-size:12.5px;color:#2a2823;line-height:1.4}
+.pitem .txt code{font-family:ui-monospace,monospace;font-size:11px;background:var(--secondary);border-radius:4px;padding:1px 4px}
+.pitem .copy{margin-left:auto;flex:none}
+.pfoot{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:10px 12px;border-top:1px solid var(--border)}
+.promptbox{width:100%;border:1px solid var(--input);border-radius:7px;background:#FBFAF5;padding:9px;
+  font:12px ui-monospace,monospace;color:#2a2823;white-space:pre-wrap;line-height:1.55}
+.toast{background:#201F1B;color:#F4F2EB;border-radius:8px;padding:9px 12px;font-size:12.5px;display:flex;gap:9px;align-items:center;max-width:380px;box-shadow:var(--shadow-dialog)}
+.anno{position:absolute;top:10px;right:12px;font:600 10.5px ui-monospace,monospace;color:var(--muted-foreground);background:var(--secondary);border-radius:5px;padding:2px 7px}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1 class="page">Comments + Suggestions — better UX</h1>
+  <p class="sub">No new modes. Exactly two actions, both already persisted: <b>Comment</b> (discuss/annotate) and <b>Suggest</b> (propose an edit to review). The work is (S) making Suggest a real inline tracked-change experience, and (T) a <b>Copy as prompt</b> surface that serializes the comments/suggestions you already have into a prompt you can paste into your own agent.</p>
+  <div class="legend">
+    <span><span class="ins">green underline</span> = insertion</span>
+    <span><span class="del">red strike</span> = deletion</span>
+    <span><span class="rep-old">old</span> <span class="rep-new">new</span> = replacement</span>
+    <span><span class="agent-range">✦ hatched</span> = agent-authored</span>
+  </div>
+  <!-- ============ COMMENT (existing, minor polish) ============ -->
+  <section>
+    <div class="sec-h"><span class="n">T · 1</span><h2>Comment — unchanged, already persisted</h2></div>
+    <p class="sec-note">Nothing new here. Select text → Comment → a persisted thread anchored to the block. This is where you "say what you want" in prose. Shown for completeness; it is the raw material Copy-as-prompt reads.</p>
+    <div class="grid">
+      <div class="stage" style="text-align:center;padding:30px">
+        <div class="bubble" style="margin:0 auto">
+          <span class="ic act">B</span><span class="ic" style="font-style:italic">I</span>
+          <span class="ic" style="text-decoration:underline">U</span><span class="ic">&lt;/&gt;</span>
+          <span class="sep"></span><span class="ic">🔗</span><span class="sep"></span>
+          <span class="lab hl">💬 Comment</span><span class="lab hl">✎ Suggest</span>
+        </div>
+        <div class="cap">The two actions. No third button, no mode toggle.</div>
+      </div>
+      <div class="stage">
+        <div class="icard">
+          <div class="top"><span>💬</span><span>you</span><span class="pill open">open</span></div>
+          <div class="body">"Tighten this paragraph, keep the citation."</div>
+          <div class="meta">on block <code style="font-family:ui-monospace,monospace;font-size:11px">“The rendering pipeline…”</code></div>
+          <div class="acts"><span class="btn ghost sm">Reply</span><span class="btn ghost sm">Resolve</span></div>
+        </div>
+        <div class="cap">A normal, persisted comment. Exactly today's feature.</div>
+      </div>
+    </div>
+  </section>
+  <!-- ============ COPY AS PROMPT (new surface over existing) ============ -->
+  <section>
+    <div class="sec-h"><span class="n">T · 2</span><h2>Copy as prompt — a surface over existing comments + suggestions</h2></div>
+    <p class="sec-note">This does not create anything. It gathers the <b>open comments and pending suggestions already on the document</b> and serializes them into a prompt string. Copy one item, or copy all. Paste into whatever agent you use. Same string format the old tweak flow produced.</p>
+    <div class="grid">
+      <div class="stage">
+        <span class="anno">panel</span>
+        <div class="panel">
+          <div class="ph"><span>Copy as prompt · notes.md</span><span class="btn ghost sm">Copy all</span></div>
+          <div class="plist">
+            <div class="pitem"><span class="k comment">comment</span><span class="txt"><code>The rendering pipeline…</code> — Tighten this paragraph, keep the citation.</span><span class="copy btn ghost sm">⎘</span></div>
+            <div class="pitem"><span class="k comment">comment</span><span class="txt"><code>Next steps</code> — Add a short TODO list here.</span><span class="copy btn ghost sm">⎘</span></div>
+            <div class="pitem"><span class="k sugg">suggestion</span><span class="txt"><code>paints the result…</code> — replace with "renders to the canvas"</span><span class="copy btn ghost sm">⎘</span></div>
+          </div>
+          <div class="pfoot"><span class="hint">3 open items · unresolved only</span><span class="btn ghost sm">Show text ▾</span></div>
+        </div>
+        <div class="cap"><b>Where it lives:</b> comments panel header + a per-item ⎘ on each comment/suggestion. Reads the persisted sidecar; touches nothing.</div>
+      </div>
+      <div class="stage">
+        <span class="anno">Show text</span>
+        <div class="composer" style="max-width:440px">
+          <div style="font-weight:600;font-size:13px;margin-bottom:6px">Prompt</div>
+          <div class="promptbox">Edit the file `notes.md` (a Markdown document). Apply these changes:
+1. `The rendering pipeline…`: Tighten this paragraph, keep the citation.
+2. `Next steps`: Add a short TODO list here.
+3. `paints the result…`: replace with "renders to the canvas"</div>
+          <div class="crow"><span class="hint">Clipboard needs https — copy manually if blocked.</span><span class="btn pri sm">Done</span></div>
+        </div>
+        <div class="cap">Manual-copy fallback for non-secure contexts. One code path, always numbered.</div>
+      </div>
+    </div>
+  </section>
+  <!-- ============ TRACK S ============ -->
+  <section>
+    <div class="sec-h"><span class="n">S · 1</span><h2>Suggest — inline redline in the prose (the real upgrade)</h2></div>
+    <p class="sec-note">Today suggestions render as cards floating beside the block, which is why they feel like comments. Instead, render them <b>inside</b> the document as tracked changes (ProseMirror decorations — never written to the <code>.md</code>). Word-level where small; block treatment when the change spans most of a block.</p>
+    <div class="stage paper">
+      <div class="doc">
+        <h3>Rendering pipeline</h3>
+        <p>The pipeline parses the source into an AST, <span class="del">then eventually </span>transforms it, and <span class="rep-old">paints the result to screen</span> <span class="rep-new">renders to the canvas</span>. Each stage is <span class="ins">independently </span>testable.</p>
+        <p><span class="blk-del">This paragraph is proposed for deletion in full — it repeats the intro and adds nothing.</span></p>
+        <p><span class="blk-ins">New paragraph proposed: caching happens between transform and paint, keyed by content hash, so unchanged blocks skip re-rendering.</span></p>
+      </div>
+      <div class="cap"><b>Word-level:</b> small insert/delete/replace shown in place. <b>Block-level:</b> left bar + soft wash for whole-block changes.</div>
+    </div>
+  </section>
+  <section>
+    <div class="sec-h"><span class="n">S · 2</span><h2>Review affordance + overlap switcher</h2></div>
+    <p class="sec-note">A change-anchored popover (opened from a small <span class="caret-badge">▾</span> badge, 44px touch slop) with the word-level diff and in-place Accept/Reject. Overlapping suggestions on one range cycle through a <b>1 of N</b> switcher instead of piling on the same pixel.</p>
+    <div class="grid">
+      <div class="stage paper">
+        <span class="anno">single</span>
+        <div class="doc" style="margin-bottom:14px">…and <span class="rep-old">paints the result to screen</span><span class="rep-new">renders to the canvas</span><span class="caret-badge">▾</span>.</div>
+        <div class="pop">
+          <div class="ph"><span>✎ suggestion · you</span></div>
+          <div class="diff"><span class="rep-old">paints the result to screen</span> → <span class="rep-new">renders to the canvas</span></div>
+          <div class="acts"><span class="btn ghost sm">Reject</span><span class="btn pri sm">Accept</span></div>
+        </div>
+        <div class="cap">Accept writes the <code>.md</code> (existing engine, base-hash gated). Reject discards.</div>
+      </div>
+      <div class="stage paper">
+        <span class="anno">overlap</span>
+        <div class="doc" style="margin-bottom:14px">Each stage is <span class="ins">independently </span><span class="caret-badge">▾3</span>testable.</div>
+        <div class="pop">
+          <div class="ph"><span>✎ suggestion</span><span class="switch"><button>◂</button> 1 of 3 <button>▸</button></span></div>
+          <div class="diff">insert <span class="ins">independently</span></div>
+          <div class="ph" style="margin:8px 0 0">by <b style="color:var(--foreground)">ana</b> · human</div>
+          <div class="acts"><span class="btn ghost sm">Reject</span><span class="btn pri sm">Accept</span></div>
+        </div>
+        <div class="cap">Accept supersedes the conflicting others (existing engine behavior).</div>
+      </div>
+    </div>
+  </section>
+  <section>
+    <div class="sec-h"><span class="n">S · 3</span><h2>Author attribution (human vs agent)</h2></div>
+    <p class="sec-note">Suggestions can be written by you or by an agent (an agent that edits your file writes ordinary suggestions). Same grammar, distinct styling so you can tell them apart at a glance: agent ranges get a hatched texture + <b>✦</b>.</p>
+    <div class="stage paper">
+      <div class="doc" style="margin-bottom:14px">
+        <span class="agent-range rep-old">The rendering pipeline is a fairly involved multi-stage process that</span> <span class="agent-range rep-new">The pipeline</span> parses, transforms, and paints. <span class="agent-range ins">(Smith 2021)</span><span class="caret-badge">▾</span>
+      </div>
+      <div class="pop">
+        <div class="ph"><span class="pill agent">✦ agent · claude</span></div>
+        <div class="diff"><span class="rep-old">The rendering pipeline is a fairly involved multi-stage process that</span> → <span class="rep-new">The pipeline</span></div>
+        <div class="acts"><span class="btn ghost sm">Reject</span><span class="btn pri sm">Accept</span></div>
+      </div>
+      <div class="cap">No special "instruction" linkage or lifecycle — it is just a suggestion with an author.</div>
+    </div>
+  </section>
+  <section>
+    <div class="sec-h"><span class="n">S · 4</span><h2>Suggesting mode (silent-revert killed)</h2></div>
+    <p class="sec-note">Keep the Editing / Suggesting radio. In Suggesting mode your typed edits show as <b>live inline redline</b> and post as suggestions on block-exit — instead of today's capture-then-silently-revert. A failed post keeps your text as a plain edit + a toast, so nothing is lost.</p>
+    <div class="grid">
+      <div class="stage">
+        <div class="banner" style="margin-bottom:12px">✎ Suggesting mode · your edits become suggestions</div>
+        <div class="statusbar">
+          <span>notes.md</span>
+          <span class="radio"><span>Editing</span><span class="on">Suggesting</span></span>
+          <span class="chip">✎ 3 suggestions</span>
+        </div>
+        <div class="cap">The status-bar chip jumps between changes.</div>
+      </div>
+      <div class="stage">
+        <span class="anno">post failed</span>
+        <div class="toast">⚠ Couldn't save that suggestion — kept as an edit. <span style="color:#D9D4AE;text-decoration:underline">Retry</span></div>
+        <div class="cap">Data-loss path closed. If the sidecar write fails, the text stays in the doc rather than vanishing on blur.</div>
+      </div>
+    </div>
+  </section>
+  <section>
+    <div class="sec-h"><span class="n">S · 5</span><h2>View-mode Suggest &nbsp;·&nbsp; drift / stale anchor</h2></div>
+    <p class="sec-note">The missing read-only affordance (contract drift today): a Suggest button beside Comment's view-mode twin. And an honest state when a suggestion's target moved.</p>
+    <div class="grid">
+      <div class="stage" style="text-align:center;padding:30px">
+        <div class="bubble" style="margin:0 auto"><span class="lab hl">💬 Comment</span><span class="lab hl">✎ Suggest</span></div>
+        <div class="cap"><b>View mode.</b> Both actions available read-only; redline popover hides Accept/Reject for a non-owner.</div>
+      </div>
+      <div class="stage paper">
+        <span class="anno">drift</span>
+        <div class="doc" style="margin-bottom:12px">…parses, transforms, and paints.<span class="caret-badge" style="background:var(--warning);color:#3a2a00">⚠</span></div>
+        <div class="icard" style="max-width:360px">
+          <div class="top"><span class="pill drift">⚠ target changed</span></div>
+          <div class="meta" style="margin-top:0">The block this suggestion pointed at was edited. Re-anchor to review, or remove it.</div>
+          <div class="acts"><span class="btn ghost sm">Re-anchor</span><span class="btn ghost sm">Remove</span></div>
+        </div>
+        <div class="cap">Never silently dropped. Accept-time 409 stays in the popover: "Document changed — refresh review."</div>
+      </div>
+    </div>
+  </section>
+</div>
+</body>
+</html>

package/.next/standalone/.scratch/tweak-running-app/ops1-updated.md ADDED Viewed

@@ -0,0 +1,215 @@
+# Spec: Tweak on a running app (proxied node-app runtime)
+## Problem Statement
+A user running wiki-viewer can already visually **Tweak** two kinds of content:
+select an element, queue an instruction, let an agent propose a rewrite, review
+it, and Accept to persist the change. This works for markdown blocks and for the
+static HTML preview.
+It does **not** work for a **proxied live surface** — a surface that must run
+same-origin to function, of which a running node app is the first case. When a
+user launches an app through the node-app runner and views it through the app
+proxy, there is no Tweak surface at all. The picker is intentionally not injected
+into proxied apps. So the one place a user most wants to point-and-fix ("make
+this button bigger", "this heading is wrong") is the one place Tweak is
+unavailable. The user has to leave the app, find the source by hand, and edit it
+blind.
+**Scope of the gap (verified against code).** Self-contained HTML — including
+client-scripted *dynamic* HTML — is *already* fully tweakable today. The static
+surface re-fetches the raw source, injects the picker, and renders it as an
+opaque-origin `srcDoc` (`allow-scripts`, no `allow-same-origin`); the page's own
+scripts execute and the picker targets the live script-rendered DOM. The gap is
+not "dynamic HTML" in general. It is exactly the surfaces that **cannot** use
+that opaque-origin trick because they must stay same-origin to work (real
+backend/fetch, a running server). Those are served through the proxy. So the
+real foundation this spec builds is a **surface-agnostic proxied live-surface
+Tweak path**, with a running node app as its first and driving consumer; a
+future "serve a dynamic HTML file through the proxy" case rides the identical
+mechanism with no new machinery.
+## Solution
+Bring Tweak to the running app. The user opens their app in the proxied view,
+enters Tweak mode, and points at real elements on the live page. They queue one
+or more instructions with the same queue model they already know (Comment /
+Suggest / Tweak; select-again-to-update; remove one or Cancel all). Dispatching
+sends the batch to the attached agent.
+The agent proposes changes and, when the user Accepts, the source is written by
+the **agent**, not the server. On Accept, wiki-viewer sends an approval to the
+agent; the agent writes the multi-file source change, rebuilds/reloads the app,
+and returns a receipt. wiki-viewer shows the user success (the running app now
+reflects the change) or a clear failure with the reason, and the queue survives
+a failure so the user can retry.
+The experience matches the existing Tweak surfaces (core parity): same
+vocabulary, same queue, same presence indicator, same single-outstanding-request
+discipline, same Cancel/Connect affordances.
+## User Stories
+ 1. As a user viewing my running app through the proxy, I want to enter Tweak mode, so that I can point at real elements on the live page.
+ 2. As a user, I want to click an element in the running app and see it highlighted as the Tweak target, so that I know exactly what I am about to change.
+ 3. As a user, I want to type an instruction for the selected element ("make this heading larger"), so that the agent knows what to change.
+ 4. As a user, I want selecting the same element again to update its queued instruction in place, so that the queued count does not inflate.
+ 5. As a user, I want to queue several element tweaks before dispatching, so that I can describe a whole set of changes as one batch.
+ 6. As a user, I want to remove a single queued tweak, so that I can drop one idea without losing the rest.
+ 7. As a user, I want a Cancel action that clears all queued selections without dispatching, so that I can back out cleanly.
+ 8. As a user, I want the dispatch button to carry a surface-appropriate label, so that the action reads naturally on the running-app surface (core parity with markdown "Rewrite" / HTML "Apply").
+ 9. As a user, I want a presence indicator that shows whether an agent is listening, so that I know whether dispatching will be picked up.
+10. As a user with queued tweaks but no attached agent, I want the dispatch button to become "Connect an agent" and open the agent panel, so that I can attach one without losing my queue.
+11. As a user, I want only one Tweak run outstanding at a time, so that I am not racing multiple agent runs against the same app.
+12. As a user who dispatches while a run is already outstanding, I want a clear rejection that keeps my queued work, so that nothing is lost.
+13. As a user, I want the agent to return one or more reviewable proposals for my batch, so that I can decide before anything is written.
+14. As a user, I want to review a proposal for each queued element, so that I can accept the good ones.
+15. As a user, I want to Accept a proposal, so that the change is written to my app's source.
+16. As a user, when I Accept, I want wiki-viewer to send approval to the agent and have the agent perform the write, so that the write uses the agent's real toolchain across multiple files.
+17. As a user, I want the app to rebuild/reload after an accepted write, so that I immediately see the change live.
+18. As a user, I want a receipt after Accept that says success or failure, so that I am never left guessing whether the write landed.
+19. As a user whose accepted write fails, I want a clear reason and my queue preserved, so that I can retry or adjust.
+20. As a user, I want to Discard a proposal, so that the app source is left byte-identical.
+21. As a user, I want to Cancel a run while it is waiting on the agent, so that I free the outstanding slot without writing anything.
+22. As a user, I want a single accepted tweak to be able to span multiple source files, so that changes that legitimately touch several files still work.
+23. As a user, I want the running-app Tweak to refuse a stale write when the underlying source changed since the proposal, so that I do not silently clobber a concurrent edit.
+24. As a user, I want Tweak on a proxied app to respect the same path-containment and workspace-isolation guarantees as every other write, so that a tweak cannot escape its workspace.
+25. As a user editing a markdown file that a human has open, I want proxied-app writes to still honor the file-vs-collab safety, so that a live human edit is never overwritten by a tweak.
+26. As an agent, I want to receive a proxied-app Tweak batch through the same poll/reply channel I already use, so that I do not need a new transport.
+27. As an agent, I want to attach reviewable proposals to each queued item, so that the human can review before any write.
+28. As an agent, I want to receive an explicit Accept approval carrying the selected proposal and per-file base hashes, so that I write exactly what was approved.
+29. As an agent, I want to return a structured receipt (success with written files, or failure with a reason), so that wiki-viewer can report the outcome.
+30. As an admin, I want proxied-app Tweak to obey the existing app-runner permission model, so that only permitted users can drive writes against a running app.
+## Implementation Decisions
+**Accept authority — agent writes on accept, returns receipt.** On human Accept,
+wiki-viewer does not write source itself. It transitions the proposal to an
+"approval sent" state and hands the agent an approval message containing the
+selected proposal identity and the per-file base hashes captured at proposal
+time. The agent performs the multi-file write, triggers the app
+rebuild/reload, and replies with a receipt. wiki-viewer records the receipt and
+surfaces success or failure to the user. This differs from the current static
+HTML resolve flow, where the server commits the agent-supplied candidate
+verbatim.
+**Runtime attachment — inject the picker into the proxied running app.** Tweak
+targets are chosen on the real running page served through the app proxy, not on
+a static snapshot. The existing picker/protocol (postMessage, data-only ops,
+origin+shape validation) is injected into the proxied app HTML. The isolated
+origin and the injection layer must be **surface-agnostic** — keyed on "a
+proxied live surface," not hard-wired to node-app specifics — so any future
+proxied surface reuses the same path unchanged. The picker injection is already
+surface-agnostic (it takes an HTML string); the work here is the origin and the
+proxy wiring around it. This requires
+serving proxied node-apps from a **dedicated isolated origin**, because the
+proxied app iframe must keep allow-same-origin to function, so page JS could
+otherwise reach the wiki-viewer parent document and forge an Accept. The static
+preview gets its opaque origin free via srcDoc; a running app cannot, so a
+separate origin is the only way to restore the postMessage/Accept trust
+boundary. Serving from that isolated origin is the frontier work all other
+running-app Tweak work blocks on. No HMR/dev-server variant machinery is
+introduced; live per-variant preview before Accept is out of scope for this
+phase.
+**Source patch scope — agent-owned multi-file.** A single accepted tweak may
+write more than one source file. The current v1 "candidate must edit exactly one
+file" cap is lifted for this flow. Because the agent owns the write, multi-file
+is natural; wiki-viewer's role is to carry the approval and record the receipt.
+**UX — core parity.** The running-app surface reuses the shared Tweak
+vocabulary, queue model, presence indicator, single-outstanding-request rule,
+and the Cancel / Connect-an-agent affordances already defined for the markdown
+and HTML surfaces. The dispatch button label is surface-specific.
+**Transport reuse.** Dispatch continues to flow through the existing human→agent
+request channel and the agent poll/reply channel. The request kinds and the live
+store gain the states needed for the agent-write receipt loop rather than a new
+transport.
+**Receipt state machine (from the decisions above).** The per-item proposal
+lifecycle for this flow extends the existing preview lifecycle with an
+agent-write tail:
+```
+requested -> ready -> resolving -> approval-sent -> writing -> committed
+                                          \-> receipt-failed (queue preserved, retryable)
+   ready -> discarded            (Discard: no write, source byte-identical)
+   waiting -> cancelled          (Cancel run: outstanding slot freed, no write)
+   (base hash mismatch at approval time) -> invalidated (refused, no write)
+```
+`committed` is reached only when the agent's receipt reports success. A failed
+receipt lands `receipt-failed` and preserves the queue for retry. Accept is
+refused if the per-file base hashes no longer match at approval time (stale
+guard).
+**Write-safety obligations for the agent-performed write.** The agent's
+multi-file write must still land inside workspace path containment and must
+honor the file-vs-collab authority: a markdown file a human currently has open
+(collab state `active`) must not be raw-overwritten by an accepted tweak. These
+are existing guarantees the receipt loop must not bypass.
+## Testing Decisions
+Good tests here exercise external behavior at the highest existing seams and
+avoid asserting implementation details. No real dev server, browser, or E2E
+harness is introduced in this phase.
+**Primary seam — in-process route-handler tests.** Follow the established
+pattern (point `HOME` at a temp dir, reset the live stores, call the exported
+route handlers directly with `Request` objects), as in the existing
+route-level live tests. Cover: batch dispatch and the single-outstanding-request
+409; agent attaching reviewable proposals to each queued item; the Accept
+approval transition; the agent receipt path for both success (`committed`) and
+failure (`receipt-failed`, queue preserved); Discard leaving source
+byte-identical; Cancel-while-waiting freeing the slot with no write; multi-file
+accepted write (cap lifted); base-hash drift refusing the write; and
+workspace isolation in both directions.
+**Secondary seam — pure-function picker injection.** Follow the existing
+picker/protocol pure-function tests: injection placement into proxied-app HTML,
+message origin and shape validation, and the guarantee that a picker message can
+never encode a write/accept command shape.
+**Store-level — receipt state machine.** Unit-test the new proposal state
+transitions (approval-sent → writing → committed / receipt-failed) at the store
+level, mirroring the existing live-store state tests.
+**Prior art.** The route-level live collab tests, the batch markdown tests, the
+web-tweak collab tests, the web-tweak picker pure-function tests, and the app
+runner lifecycle tests are the models to extend. New tests raise the test floor
+deliberately.
+## Out of Scope
+* HMR / dev-server variant machinery and live per-variant preview before Accept
+  (the full "runtime adapter" option was not chosen).
+* Server-side verbatim commit of the agent's patch for the proxied-app flow (the
+  server-commit accept authority was not chosen; the agent performs the write).
+* A real-runtime end-to-end test harness that boots a sample app and drives a
+  browser (may be added later as its own ticket).
+* Changing the existing markdown or static-HTML Tweak surfaces beyond what core
+  parity requires.
+* Any change to the app-runner permission model itself.
+## Further Notes
+**Already delivered (Phase 1, committed).** Markdown Tweak run recovery is done:
+Cancel frees the outstanding request and discards previews; a run-generation
+guard drops superseded/late dispatches; generation failures preserve the queue;
+resolve failures retry the same proposal; the no-agent Rewrite button becomes
+"Connect an agent"; dispatch uses the freshest snapshot revision. That work
+establishes the core-parity affordances this phase reuses on the running-app
+surface.
+**Security gate.** Injecting the picker into a proxied app is the one genuinely
+new risk surface. The picker was deliberately excluded from proxied app HTML
+because the app must stay same-origin, letting page JS reach the parent and
+forge an Accept. The gate is therefore a dedicated isolated proxy origin (the
+frontier ticket), not a sandbox/CSP tweak: dropping allow-same-origin breaks the
+app, and keeping it leaves the parent reachable. Only a separate origin restores
+the trust boundary.
+**Docs obligations.** `docs/ux-contracts.md` and the isometric architecture map
+must be updated in the same change that ships behavior, per repo convention.

package/.next/standalone/.scratch/tweak-running-app/ops12-continuation.md ADDED Viewed

@@ -0,0 +1,44 @@
+# OPS-12 continuation brief — static-HTML live-tweak tracer bullet
+Status as of this session. Read before resuming.
+## Done + committed (verified green)
+- **OPS-9/10/11 prefactors** — committed `7894ead`, `88c5c5b`, `5940791`. denied-segments (`.impeccable` contained everywhere), `injectOverlay` (pure), `carbonizeLiveVariant` (pure). Full suite green, review findings F1–F4 fixed.
+- **OPS-12 contained-write** — committed `7c2c2a5`. `src/lib/fs/contained-write.ts`: `containedWrite({rootDir,relPath,expectedBaseHash?,content,baseFiles?})→{ok:true,written}|{ok:false,code:"BASE_DRIFT"|"PATH_DENIED"}`, `hashContent()`. `commitCandidate` delegates to it. Tests green.
+- **OPS-12 engine lifecycle** — committed `117f6c2`. `src/lib/live-engine/{paths,client,supervisor}.ts` + `POST/DELETE /api/wiki/live-web/session` + stub-engine test. Contracts:
+  - `startEngine({workspaceId,relPath,appRoot})→LiveEngineInfo{port,token,state,generation,...}`, `getEngine(key)`, `stopEngine(key)`, `__setSpawnerForTest`.
+  - `LiveEngineClient({port,token,fetch?,host?})`: `.health/.poll({timeoutMs,leaseMs,types,signal})/.reply(body)/.status/.stop`.
+  - session route: loopback + CSRF + auth + workspace-containment guarded; returns `{ok,port,token}`.
+Full suite last run: **726/726**, floor 691.
+## Remaining (the interlocking backend spine + UI + docs)
+Owned target files: `src/lib/proof/live/scaffold-store.ts`, `src/lib/proof/live/web-bridge.ts`, `src/app/api/wiki/live-web/{resolve,status}/route.ts`, `src/tests/proof/live-web-bridge.test.ts`, plus viewer wiring (`website-viewer.tsx` + a `use-live-web-session` hook) and `docs/ux-contracts.md` §1.4 + isometric map.
+Two worker rounds (gpt-5.6-sol, ids `7f063da6`) failed to produce files — spent turns on recon, never implemented. Do NOT re-delegate this to the same worker profile; either implement inline or use a stronger model with the full design inline.
+## BLOCKING FINDING — variant representation mismatch (needs a decision)
+The plan said "reuse `web.tweak.variants`, no schema change." Verified against source: that does not hold cleanly.
+- `src/lib/web-tweak/preview-store.ts` stores a variant as `{variantId,label,domPreviewOps,candidateSourcePatch{files:[{path,content}]},baseFiles:[{path,sha256}]}`. Accept commits `candidateSourcePatch` **verbatim** iff base hashes match. No carbonize.
+- The OPS-10/11 prefactors assume the **Impeccable scaffold** model: overlay `live.js` mounts variant `<div data-impeccable-variant>` scaffolds with scoped CSS + `--p-*` knobs; Accept = `carbonizeLiveVariant(scaffold,...)`.
+- The agent's reply path today (`/api/agent/live/web-preview` → `attachVariants`) delivers the wiki-viewer format, **not** an Impeccable scaffold string. So the bridge cannot obtain a scaffold to reply `done --file` to the engine, nor feed `carbonize`, without a new scaffold-carrying reply path.
+### Options
+- **B (spike's chosen topology — recommended): bridge translates; add a scaffold-carrying reply.** wiki-viewer server runs the engine `/poll` loop; on `generate/steer` it enqueues on its attached-agent channel; the attached agent replies with an **Impeccable scaffold string**; bridge relays scaffold to engine (`done --file`); Accept = `carbonize` + `containedWrite`. Uses OPS-10/11 as designed. COST: needs a scaffold reply payload/route beyond the original 5 owned files (extend `/api/agent/live/*` or add one) — a scoping expansion, not just the 5 files. Requires the attached agent to know the Impeccable variant format (Impeccable skill).
+- **C: reuse existing web-tweak variant model fully; drop carbonize for web.** Variants = existing DOM-ops + verbatim candidate patches; Accept = verbatim `containedWrite`; engine used only for picker/overlay/transport. Simplest reuse; but abandons OPS-11 carbonize for web surfaces and diverges from the engine overlay's native scaffold expectation (overlay would need to render candidate DOM ops instead of Impeccable variant divs — may fight `live.js`).
+- **A: engine-native generation.** The user's chat agent (running the Impeccable skill) drives the engine `/poll` directly; wiki-viewer hosts engine + overlay + accept-through-writer only. Truest to OPS-11; thinnest wiki-viewer generate role; but wiki-viewer's attached-agent channel isn't the generator, which is a different product UX than the ticket's "existing attached agent" wording implies.
+Recommendation: **B**, matching the spike's "product hosts engine, existing agent generates" topology, accepting the scaffold-reply-channel scope expansion. Confirm before building the spine.
+## Spine design (assuming B)
+- `scaffold-store.ts`: own WAL connection to `~/.wiki-viewer/live.db` (getDb there is private; open a second connection w/ busy_timeout). Table `live_web_scaffold {id,workspace_id,rel_path,original_source,disk_base_hash,scaffold,scaffold_hash,chosen_variant_id,param_values(json),state,created_at,resolved_at}` + idempotency map `live_web_event {engine_event_id PK,workspace_id,rel_path,live_request_id,reply_json,created_at}`. Persist so recovery survives restart.
+- `web-bridge.ts`: one loop per `{workspaceId,relPath}`; long-poll engine; on generate/steer → `enqueueRequest(kind:"web.tweak.variants")` for `getOrCreateSession(workspaceId)`; idempotent on `engine_event_id` (replay re-sends stored reply); backpressure on `OUTSTANDING_REQUEST`; when the agent's scaffold reply lands, store scaffold+hash and reply `done` to engine; generation + AbortController cancels stale loop on teardown; NO engine mutators; NO disk write.
+- `resolve/route.ts` POST `{action,path,chosenVariantId?,paramValues?}`: accept → `carbonizeLiveVariant(scaffold,scaffoldHash,...)` (409 on NO_MARKERS/NO_VARIANT/BASE_DRIFT) → `containedWrite(expectedBaseHash:diskBaseHash)` (409 on BASE_DRIFT) → mark accepted + stopEngine; discard → drop scaffold + stopEngine. auth+containment+CSRF+loopback. Invariant: no write before Accept; Accept writes iff BOTH hashes match.
+- `status/route.ts` GET `?path=`: session+bridge+engine liveness; engine dead + scaffold present ⇒ `recoverable:true`.
+- test `live-web-bridge.test.ts`: stub engine via `__setSpawnerForTest` or injected client; mirror `web-tweak-collab.test.ts`; assert the 10 items in the ticket AC.
+- viewer: `website-viewer.tsx` static-`.html` tweak mode starts a session and points the sandboxed `srcDoc` iframe at the engine (S0 GREEN: opaque-origin can reach `127.0.0.1:<port>` via `?token=`). Put lifecycle in `src/hooks/use-live-web-session.ts`.
+- docs: `docs/ux-contracts.md` §1.4 + isometric map, same commit.
+## S0 (resolved GREEN)
+`live-server.mjs:709` reflects `Access-Control-Allow-Origin` for any request carrying a valid `?token=` regardless of origin (comment covers opaque/remote overlay origins incl. OPTIONS preflight; OPTIONS returns 204 with CORS headers). So a sandboxed `srcDoc` iframe (Origin: null) drives the engine directly. No reverse proxy for the localhost static tracer bullet; proxy transport stays deferred to OPS-6.