wiki-viewer 2.16.0 → 2.16.1

package/.next/standalone/.scratch/tweak-running-app/two-actions-interaction-spec.md

@@ -0,0 +1,234 @@
+> SUPERSEDED (2026-08-23): the "Ask agent" composer mode, the instruction-comment
+> dispatch/lifecycle, and the pending/answered cards below are NO LONGER in scope.
+> Per user direction there is NO agent-triggering. The re-home is: Comment +
+> Suggest with better UX, plus a Copy-as-prompt surface that serializes EXISTING
+> comments/suggestions. Authoritative current design: ../tweak-running-app/mockups.html
+> + suggest-inline-interaction-spec.md + craft-checklist.md. Keep this file only
+> for the parts still valid (two-actions framing, copy-as-prompt string format,
+> dedup-by-reply reasoning).
+
+# Tweak UX ported into Comment + Suggest — interaction spec (OPS-22, rev 2)
+
+Reference-only design artifact. Supersedes `tweak-interaction-spec.md` decision A
+(third button — REJECTED). Decisions B/C/D/E of that spec are carried forward and
+re-attached to the two existing actions. Bubble menu stays exactly:
+
+```
+[ B I U S <> | sup sub | link | 💬 Comment  ✎ Suggest ]
+```
+
+- **Comment** = talk about this target — to a human *or* to an agent (one-line semantics).
+- **Suggest** = an edit to review — written by a human, *or* arrived from an agent.
+
+Nothing in the chrome changes count. What changes is what Comment's composer can
+produce and how Suggest's card can be reached.
+
+---
+
+## 1. The mapping — which ported affordance lives where
+
+### Comment absorbs (human → agent intent)
+
+| Ported affordance | Where it lands in Comment |
+|---|---|
+| Targeting panel "What should change?" | The comment composer's **instruction mode** (see §2). Same anchor-to-block geometry. |
+| "Ask agent" dispatch | Composer primary button when in instruction mode. Writes `comment.add {kind:"instruction", instructionState:"queued"}` immediately. No queue step. |
+| Copy-as-prompt | Secondary button inside the composer footer, and on every pending/answered instruction card (§3, §7). |
+| Connect-an-agent | Replaces primary-button label in instruction mode when no agent attached; opens AI panel; instruction already persisted so nothing is lost (§7 no-agent state). |
+| Dedup / re-target | Re-targeting a block with a pending instruction opens its existing thread, not a new composer (§6). |
+| Doc-level "N pending" chip | Toolbar chip counts pending **instruction-kind comments**; click jumps to first. Replaces the deleted queue bar's only real value. |
+
+### Suggest absorbs (agent → human review)
+
+| Ported affordance | Where it lands in Suggest |
+|---|---|
+| The agent's rewrite | Arrives as ordinary `suggestion.add` (replace/insert/delete), reviewed in the existing `suggestion-card.tsx`. No UI change to the card's Accept/Reject mechanics. |
+| Linkage to intent | Card header gains one optional line above the reason: `In response to: "<instruction text>"` when the suggestion carries `fromInstructionId` (open question 2 from prior spec — recommend the explicit field). |
+| Settling the instruction | Accept **or** Reject of the linked suggestion flips the instruction to `answered`/resolved. Agent clarification without a suggestion lands as a reply on the instruction thread instead. |
+
+### Volunteered improvement over the "likely shape" in the brief
+
+The brief's shape is confirmed, with one sharpening: **Suggest itself stays
+human-only as an entry point.** The bubble-menu Suggest button keeps its current
+meaning (human proposes an edit). The agent never needs an entry point — it
+writes to the sidecar directly. So "Suggest absorbs the agent rewrite" means the
+*suggestion surface* (card + review loop) absorbs it, not the Suggest button.
+This keeps both buttons' semantics single-clause and avoids implying the user
+can click Suggest to summon an agent.
+
+Resulting one-liners:
+
+- **Comment — "say something about this: discuss it, or tell your agent what to change."**
+- **Suggest — "review a proposed edit: yours, or your agent's answer."**
+
+---
+
+## 2. One composer, two kinds — the kind picker
+
+**Decision: ONE composer. A two-option segmented control at the top of the
+composer, defaulting to the context-appropriate segment.**
+
+Not two buttons, not a kind dropdown buried in a menu, not a magic prefix
+("@agent"). A segmented control because: the choice is binary, both options must
+be visible before typing (the user's mental model of *who reads this* shapes
+what they write), and it must be flippable mid-draft without losing text.
+
+Default segment rule (resolves the open decision):
+
+- **Selection has no agent attached and file is markdown → default "Ask agent" is NOT the default.** Default = **Discuss** (plain comment). Rationale: the dominant, established Comment path pays zero new friction; the instruction path is one click away and its controls (targeting placeholder, footer) teach it on hover.
+- **If the user has used "Ask agent" before in this session** → remember last-used segment for the session. Sticky, not global.
+- Text/code surfaces: same control, same default. Comment pip unchanged.
+
+```
+┌─ composer (anchored to block, existing comment geometry) ─────────┐
+│ ┌─────────────┬─────────────┐                                     │
+│ │ ● Discuss   │ ○ Ask agent │   ← segmented, 44px hit, 11px type  │
+│ └─────────────┴─────────────┘                                     │
+│ ┌──────────────────────────────────────────────────────────────┐ │
+│ │ Add a comment…            (Discuss placeholder)              │ │
+│ │ What should change?       (Ask agent placeholder)            │ │
+│ └──────────────────────────────────────────────────────────────┘ │
+│ [⎘ Copy as prompt]*              ⏎ Comment / ⏎ Ask   esc Cancel │
+└───────────────────────────────────────────────────────────────────┘
+* Copy as prompt visible only in Ask-agent mode (see §3).
+```
+
+Behavioral rules:
+
+- Flipping the segment swaps placeholder + primary button label + footer hints. Draft text survives the flip. Flipping Ask→Discuss with text present: keep text, no warning (a plain comment with imperative text is harmless).
+- Flipping Discuss→Ask with text present: keep text, no warning. The text becomes the instruction.
+- Cmd+Enter dispatches per active segment: `kind:"comment"` or `kind:"instruction", instructionState:"queued"`. Immediate persist. No queue, no batch.
+- Outside-click with empty input = cancel (ported unchanged).
+- Read-only mode: Discuss only. Ask-agent is hidden in read-only (writing an instruction implies the agent may later write the doc; surfaces that are read-only for the human should not queue machine edits — keeps one mental rule: read-only = discuss).
+
+---
+
+## 3. Copy-as-prompt placement
+
+Reachable with and without an agent, in three places, always the same string
+format (`Edit the file \`X\` (a Markdown document). Apply these changes:\n\n1. \`<snippet>\`: <instruction>`), always with clipboard-gate + "Show" textarea fallback:
+
+1. **Composer, Ask-agent mode** — footer secondary button `[⎘ Copy as prompt]`. Copies draft-as-instruction without persisting anything. This is the true no-agent escape hatch at authoring time. Hidden in Discuss mode (a discussion comment is not a prompt).
+2. **Pending instruction card** (§4) — `[Copy prompt]` button. Available even after dispatch; the durable artifact and the clipboard path coexist.
+3. **Answered/stale instruction card** — same `[Copy prompt]`, for re-asking elsewhere after drift.
+
+Numbering: keep `1.` prefix always, one code path (carried from prior spec F.2).
+
+**Connect-an-agent placement:** in Ask-agent mode with no agent attached, the
+primary button reads `Connect an agent` and opens the AI panel. Dispatch has
+*already happened on Cmd+Enter* if the user pressed it first — button relabel is
+a CTA, not a gate. The instruction sits queued in the sidecar either way. Copy
+as prompt stays visible beside it.
+
+---
+
+## 4. Chrome without the queue bar
+
+No bottom bar. The sidecar is the store. Three pieces of chrome total:
+
+**Composer** — as §2. Exists only while open.
+
+**Pending instruction card** (block gutter / margin, pip exactly like a comment
+pip, distinct glyph — reuse the instruction styling from `comment-thread.tsx`'s
+"Turn into an instruction" output):
+
+```
+┌─ instruction card (pending) ──────────────────────────────────────┐
+│ ✦ you · waiting for your agent                                    │
+│ "Tighten this paragraph, keep the citation."                      │
+│ Your agent picks this up when it next reads this file.            │
+│                                        [Copy prompt]  [Remove]    │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+No spinner. No fake progress. State line is a true statement about `queued`.
+`sent` state (when lifecycle is driven) swaps the line to "sent to your agent —
+waiting for answer"; chrome otherwise identical.
+
+**Answered state** — markdown: the suggestion-card appears inline (existing);
+the instruction card collapses to one line anchored above it:
+
+```
+┌─ instruction (answered) ──────────────────────────────────────────┐
+│ ✦ answered — review the suggestion below            [Copy prompt] │
+└───────────────────────────────────────────────────────────────────┘
+┌─ suggestion-card (existing, unchanged) ───────────────────────────┐
+│ agent suggests replacing this block                               │
+│ In response to: "Tighten this paragraph…"                         │
+│ ─ current ─ / ─ proposed ─                       [Accept][Reject] │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+Text/code answered: reply lands in the instruction thread with fenced code;
+card gains `[Mark done]` (human-settles, no doc write) beside `[Copy prompt]`.
+
+---
+
+## 5. Review loop — confirmed
+
+**Markdown (full loop):** agent reads queued instruction → writes
+`suggestion.add` + flips instruction to `answered` → user reviews in
+suggestion-card → Accept pushes block op with `baseRevision` (409 → one retry
+with `getLatestRevision()`, existing behavior) → instruction resolves when the
+suggestion settles. Clarifying questions arrive as thread replies, not
+suggestions. **Confirmed as designed.**
+
+**Text/code (degraded, honest):** instruction persists at the lineAnchor; agent
+cannot suggest; answer arrives as a comment reply containing fenced replacement
+lines; user hand-applies. Expectation set **at dispatch time** — footnote under
+the composer's Ask button on non-md surfaces: *"On this file type the agent
+replies with a comment; you apply the change."* **Confirmed.**
+
+**HTML iframe:** nothing. Source view only. **Confirmed** (permanently dropped
+with the old engine).
+
+---
+
+## 6. Re-targeting a block with a pending instruction (no `comment.update`)
+
+Three options — picking **reuse the existing thread via a prefilled composer**, with an explicit cost note:
+
+| Option | Verdict | Cost |
+|---|---|---|
+| **(a) Reuse thread: open the pending instruction's thread in place of a fresh composer; composer's Ask field prefilled with current instruction text; Cmd+Enter posts a `comment.reply`** | **PICK** | A "revised instruction" is a reply, not an edit — the instruction card needs latest-reply-wins display logic (show newest reply from the instruction author as the effective instruction). Small client-side rule, zero schema change, zero new op. |
+| (b) Add `comment.update` op | Rejected for v1 | New op type, new revision/idempotency edge cases, server + tests, for one affordance. Disproportionate. |
+| (c) Just create another instruction | Rejected | Two pending instructions on one block = agent sees contradictory intent; dedup was a named good-part of the old UX. |
+
+Concretely (a): Comment button on a block whose only open thread is a pending
+instruction **opens that thread directly** (skip the composer). The thread's own
+reply box uses Ask-agent styling when replying on an instruction thread:
+placeholder "Revise this instruction…", Cmd+Enter = reply. Card body renders the
+latest author reply as the instruction text, with a subtle `edited` marker. The
+agent reads the thread top-down; recency-semantics ("last instruction wins") is
+a one-line note in the context doc, not new machinery.
+
+---
+
+## 7. States
+
+| State | Chrome | Copy-as-prompt | Connect-an-agent |
+|---|---|---|---|
+| **Composing (Discuss)** | Composer, Discuss segment | hidden | hidden |
+| **Composing (Ask agent)** | Composer, Ask segment, "What should change?" | footer secondary | visible only if no agent (as primary relabel) |
+| **No agent** | Ask mode fully functional; instruction persists queued | present (composer + card) | primary CTA → AI panel; nothing lost |
+| **Queued/pending** | Instruction card + gutter pip; toolbar "✦ N pending" chip if N>0 | card button | toolbar chip area / AI panel entry point |
+| **Answered (md)** | Collapsed instruction + suggestion-card | card button | n/a |
+| **Answered (text/code)** | Thread reply + `[Mark done]` | card button | n/a |
+| **Drift / stale anchor** (ref/textHash miss) | Pip → `⚠ target changed`; actions: `[Re-anchor]` (re-open composer targeting best-effort match), `[Copy prompt]`, `[Remove]` | present — this is its most important state | hidden |
+| **Empty** | Zero chrome. No bar, no placeholder | n/a | n/a |
+
+Accept-collision drift (409 after retry, fingerprint mismatch) stays inside
+suggestion-card: "Document changed since this suggestion — refresh review."
+Unchanged from current implementation.
+
+---
+
+## Summary
+
+1. Two actions stay two. Comment = say something (discuss or instruct); Suggest = review an edit (human or agent).
+2. One composer with a Discuss / Ask-agent segmented control; defaults to Discuss; session-sticky; draft survives flips.
+3. Ask-agent dispatch writes `comment.add {kind:"instruction", queued}` immediately — no queue bar, sidecar is the store.
+4. Copy-as-prompt lives in the composer footer (Ask mode), on every instruction card, and in every drift state — the constant escape hatch; Connect-an-agent only appears when no agent is attached.
+5. Agent answers land in the existing suggestion-card (md, full Accept-writes-doc) or as thread replies (text/code, hand-apply, limitation stated at dispatch).
+6. Re-target dedup = open existing thread, revise via reply, latest-reply-wins display — no `comment.update` op in v1.
+7. **Riskiest assumption:** the agent actually consumes the sidecar and answers with a suggestion op. If it never integrates, every Ask-agent comment dead-ends at "queued + Copy prompt" — acceptable only because copy-as-prompt is one click away in every state, which is why its placement is non-negotiable.

package/.next/standalone/.scratch/tweak-running-app/unified-live-spec.md

@@ -0,0 +1,261 @@
+# Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+> Supersedes OPS-1 ("Tweak on a running app / proxied node-app runtime") and the
+> canceled OPS-2..6 isolated-origin/grant/hardening line. Those described an
+> embed-in-iframe architecture; this spec replaces the whole approach with the
+> Impeccable `live` model. Feasibility confirmed by the B1 spike (see Further
+> Notes).
+
+## Problem Statement
+
+A user running wiki-viewer wants to point at any element on a rendered web page,
+say what they want ("make this bolder", "try a different layout"), see a few live
+design variants they can compare and tune, and Accept the one they like straight
+into source. Today this only half-exists, in fragmented and inconsistent forms:
+
+- **Static HTML** gets a bespoke tweak flow (opaque-origin sandbox, DOM ops,
+  "Iterate" variants) that is limited and SPA-hostile.
+- **Running node apps / dynamic surfaces** get **no tweak surface at all** — the
+  picker is deliberately not injected into proxied apps. The one place the user
+  most wants to point-and-fix is the one place the feature is missing.
+- The two surfaces behave differently, so there is no single mental model.
+
+The user is forced to leave the rendered page, hunt for the right source by hand,
+edit blind, and reload to check. The visual, direct-manipulation promise is
+broken for exactly the surfaces where it matters most.
+
+## Solution
+
+One unified live-tweak experience across all web/visual surfaces (static HTML,
+dynamic/server-rendered HTML, running node apps), modeled on the Impeccable `live`
+skill. The user opens a surface, points at an element, picks a design action or
+types a freeform instruction, and hits Go. The system produces 2 to 5 full-element
+variants, each with 0 to 4 tunable knobs (sliders, toggles, segmented controls).
+The user cycles variants and drags knobs with instant feedback, then Accepts the
+chosen variant, which lands in the real source file. Discard restores the
+original. Nothing is written to disk until Accept.
+
+The variants are generated by the user's existing attached agent (the same AI
+channel that already powers markdown and static-HTML tweak today), so no new AI
+plumbing is introduced. The Impeccable live engine (a local helper server plus
+its browser overlay and source-mutation logic) is hosted and driven by the
+wiki-viewer product itself, not by a chat agent running the skill by hand.
+
+Because Impeccable injects its overlay into the app's own page (the user edits
+their own app, in place), there is no parent frame to protect. That relocation of
+trust deletes the isolated-origin security problem that the previous
+(now-canceled) design was built to solve.
+
+### Surface-specific experience (user-facing)
+
+The top-level flow (point, instruct, Go, compare variants, tune knobs, Accept or
+Discard) is identical on every surface. The only user-visible difference is how
+variants first appear on screen.
+
+- **Static HTML file.** No dev server involved; the file is both served and
+  source. After Go, variants appear via an instant client-side swap: no reload, no
+  flicker, no lost state. Cycling variants and dragging knobs are instant. Accept
+  writes into the `.html` file directly. This is the flagship, flicker-free
+  experience and ships first.
+
+- **Dynamic / server-rendered HTML that maps to editable templates.** Where the
+  served HTML corresponds to real editable source (raw templates, not compiled
+  component trees), the same fetch-source swap applies and the reload below is
+  usually avoided.
+
+- **Running node apps (compiled frameworks: React, Vue, Next, etc.).** The app
+  must be running and viewed through the proxy. Variant markup is written into the
+  app's real component/template source. To render compiled source, the page
+  performs **one full reload per Go**; the overlay re-attaches automatically (it
+  remembers its session per page). After that single reload, all variants are
+  already present in the page, so cycling and knob-tuning are instant and
+  client-side, exactly like static. Accept bakes the choice into source and may
+  trigger one more brief reload for the clean final render.
+
+  The one felt cost on compiled apps: a full reload resets transient in-app state
+  (open modals, form input, deep scroll, SPA sub-route). Static HTML never has
+  this. Closing that gap (flicker-free, state-preserving hot-swap) is deferred
+  optional work; see Out of Scope.
+
+## User Stories
+
+1. As a wiki-viewer user, I want to point at any element on a rendered web page and have it highlight, so that I can target exactly what I want to change.
+2. As a user, I want to pick a named design action (bolder, quieter, distill, polish, typeset, colorize, layout, adapt, animate, delight) for the selected element, so that I can steer the direction without writing a prompt.
+3. As a user, I want to type a freeform instruction for the selected element, so that I can express intent the named actions do not cover.
+4. As a user, I want to scribble or annotate directly on the element before generating, so that I can point at sub-parts and give spatial direction.
+5. As a user, I want 2 to 5 distinct variants generated per request, so that I can compare real alternatives rather than accept the first idea.
+6. As a user, I want to cycle between the generated variants quickly, so that I can judge them side by side in the real page.
+7. As a user, I want each variant to expose a few tunable knobs (sliders, toggles, segmented controls), so that I can fine-tune a direction without regenerating.
+8. As a user, I want knob changes to update the preview instantly, so that tuning feels direct.
+9. As a user, I want to Accept a chosen variant and have it written into the real source file, so that the change persists in my project.
+10. As a user, I want Discard to restore the original exactly, so that experimenting is risk-free.
+11. As a user, I want nothing written to disk until I Accept, so that previews never corrupt my files.
+12. As a user, I want Accept refused if the underlying source changed since the preview began, so that a concurrent edit is never silently overwritten.
+13. As a user editing a static HTML file, I want variants to appear instantly with no reload or flicker, so that the experience feels live.
+14. As a user tweaking a running node app, I want the tweak overlay available on the proxied app page, so that I can point-and-fix without leaving the app.
+15. As a user tweaking a running node app, I want the overlay to re-attach itself after the post-generate reload, so that my session is not interrupted.
+16. As a user tweaking a compiled app, I want cycling and knob-tuning to stay instant after the initial reload, so that only the first render costs a reload.
+17. As a user, I want the accepted change written to the true source (template or component), never to a generated build output, so that my change is not wiped by the next build.
+18. As a user, I want a clear indication when a surface is generating variants versus ready to review, so that I know what the system is doing.
+19. As a user, I want to steer the whole page (a page-level instruction with no specific element), so that I can request broad direction.
+20. As a user, I want to start a tweak on a static HTML surface with no dev server or app launch required, so that the simplest case is frictionless.
+21. As an admin in authenticated mode, I want node-app launching to remain gated to me (or explicitly allowed runners), so that arbitrary users cannot start host processes just to tweak.
+22. As a user, I want the tweak overlay to only load where I am authorized for the workspace, so that the feature respects existing access boundaries.
+23. As a user, I want the tweak engine's runtime files kept out of my served pages, my file browser, and my commits, so that internal state never leaks into my project or repo.
+24. As a user, I want an interrupted tweak session (reload, crash, disconnect) to recover to a safe state, so that I never end up with half-applied variants.
+25. As a user, I want at most one outstanding generate request per surface session, so that rapid clicks do not stack conflicting generations.
+26. As a user, I want the accepted variant's knob values baked into the final source, so that what I tuned is what persists.
+27. As a user, I want the previous bespoke static-HTML tweak flow replaced by this unified one, so that I do not have to learn two different behaviors.
+28. As a user, I want the markdown prose tweak flow to keep working as it does today, so that this change does not regress non-visual editing.
+29. As a user, I want variants that respect my app's existing visual identity by default, so that I can actually accept them rather than getting off-brand results.
+30. As a user, I want a departure (redesign) direction only when I explicitly ask for it, so that "make it better" does not throw away my brand.
+31. As a user, I want a live indication when the overlay cannot reach the engine, so that I know to reconnect rather than assume it is working.
+32. As a user viewing a remotely-hosted wiki-viewer (not localhost), I want the tweak overlay to still function, so that the feature is not limited to local use.
+33. As a user, I want a failed variant render to surface as a recoverable error rather than a blank page, so that one bad generation does not break the session.
+34. As a developer, I want the accept/carbonize write path to go through wiki-viewer's own containment and locking, so that tweak writes obey the same safety as every other file write.
+
+## Implementation Decisions
+
+- **Topology: product hosts the engine; the existing attached agent generates.**
+  wiki-viewer spawns and supervises the Impeccable live helper server (one per
+  served surface, keyed like the node-app runner keys apps), injects the overlay,
+  and runs the engine's poll loop **server-side**. On a generate event, wiki-viewer
+  translates it into a request on its existing attached-agent live channel, so the
+  user's current AI session produces the variants. wiki-viewer applies the variant
+  writes and replies to the engine; on Accept it runs the accept/carbonize
+  mutation through its own writer.
+
+- **Primary new module: the live bridge.** A product-side bridge translates
+  Impeccable poll events (generate, steer, accept, discard, prefetch,
+  variant-mount-failed, manual-edit-apply) into the existing live-store request
+  kinds and back. It owns the reconciliation between the engine's poll/lease model
+  and wiki-viewer's one-outstanding-per-session, delivered/working/resolved state
+  machine, and idempotency keying. This is the single primary seam.
+
+- **Injection as a shared pure transform.** A single string transform injects the
+  engine prelude globals plus the overlay `<script>`. It is reused by the app-proxy
+  serve-time HTML rewrite (for running apps) and the static-HTML viewer render (for
+  files). Serve-time injection means no source files are edited to enable tweak and
+  no removal step is needed. The stock live-inject source-file editor is not used.
+
+- **Accept/carbonize as a pure mutator over wiki-viewer's writer.** The engine's
+  accept logic (locate markers, extract the chosen variant, carbonize/bake knob
+  values, produce clean final source) is hosted as a pure transform whose writes
+  go through `resolveWorkspacePath` containment plus wiki-viewer's existing write
+  lock and collab-state checks. The engine's own raw file write and separate
+  lockfile are not used for source mutation, so there is exactly one authoritative
+  write/lock spine.
+
+- **Speculative-until-Accept invariant preserved.** Previews never write source.
+  Accept is the only operation that writes, and only if the base content hash still
+  matches (drift refuses the accept). This mirrors the current web-tweak accept
+  contract and the engine's accept-receipt idempotency.
+
+- **Browser-to-helper transport must survive remote hosting.** Because the overlay
+  runs on wiki-viewer's origin and the browser may be remote, the engine endpoints
+  the overlay needs (overlay bundle, event downlink/SSE, uplink, source read,
+  design-system read, annotation upload) are exposed through wiki-viewer's own
+  origin, and the injected globals point the overlay at those proxied paths rather
+  than a hardcoded localhost helper port. Proxied endpoints inherit wiki-viewer
+  session/agent auth and CSRF Origin checks.
+
+- **Dynamic-app rendering uses full-reload-through-proxy.** HMR WebSocket does not
+  pass through the app-proxy today (confirmed). For compiled apps, a post-generate
+  full page reload renders the written variants; the overlay re-attaches via its
+  durable per-origin session. Cycling and knobs remain client-side after that one
+  reload. Static and template-mapped surfaces use the instant client-side / fetch-
+  source swap and do not reload.
+
+- **Engine runtime state is denied and ignored.** The engine's runtime directory
+  is added to path-containment denied segments (so it is never served, traversed,
+  or reachable via file routes) and to gitignore (so it is never committed),
+  consistent with the existing treatment of `.proof` and `.git`.
+
+- **Node-app authorization unchanged.** Launching an app to tweak it obeys the
+  existing app-runner permission model (admin-only in auth mode unless the runner
+  allowance is set). Overlay availability follows workspace access.
+
+- **Variant quality contract inherited from the engine.** Identity-preserving
+  "default" mode is the norm; a "departure" redesign direction is used only on
+  explicit user request. This is engine behavior wiki-viewer surfaces, not new
+  product logic.
+
+- **Recovery via the engine journal.** Session state is the engine's append-only
+  per-session journal; interrupted sessions replay to a safe state on reconnect
+  rather than leaving half-applied variants.
+
+## Testing Decisions
+
+- **Good tests assert external behavior, not internals.** Tests drive the feature
+  through its route handlers and pure transforms and assert the observable
+  contract: previews never write; Accept writes verbatim only on matching base
+  hash; one-outstanding-per-session; idempotent replay; original restored on
+  Discard; runtime dir denied. They do not assert internal call sequences.
+
+- **Primary seam: the live bridge at the route-handler level.** Tested exactly
+  like the existing live-collab proof tests: a temp workspace and registered
+  agent, drive the poll/reply loop through the real route handlers, assert the
+  reconciled state machine, idempotency, and that source is written only on Accept.
+  Prior art: `live-collab.test.ts`, `live-md-batch.test.ts`.
+
+- **Injection transform: pure-function test.** Assert the transform injects the
+  prelude globals and overlay script at the correct anchor, is idempotent, and does
+  not corrupt surrounding HTML. Prior art: the existing app-proxy HTML-rewrite
+  tests and `web-tweak-picker.test.ts`.
+
+- **Accept/carbonize mutator: pure-function + verbatim-commit test.** Assert marker
+  location, variant extraction, knob-value baking, clean final output, and the
+  base-hash drift guard (accept refused when source drifted; committed verbatim
+  when unchanged). Prior art: `web-tweak-collab.test.ts`.
+
+- **Authorization and containment.** Assert overlay/endpoints reject unauthorized
+  workspace access and that the runtime dir is unreachable through file routes and
+  path resolution. Prior art: `app-proxy-auth.test.ts`.
+
+- **Helper-server process lifecycle is integration-only.** The live helper is a
+  spawned child process; its lifecycle is not part of the unit seam, mirroring how
+  `app-runner.test.ts` treats spawned apps. The bridge is tested against the
+  engine's HTTP/file contract, not a live child.
+
+- **Test floor.** New proof tests are added under the proof suite and the floor is
+  updated only via the sanctioned `--update-floor` path.
+
+## Out of Scope
+
+- **Flicker-free, state-preserving hot-swap for compiled node apps.** Requires
+  adding WebSocket-upgrade passthrough to the proxy (forwarding the app's HMR
+  socket). Deliberately deferred to a later ticket; compiled apps ship with
+  full-reload-through-proxy first. Not a blocker.
+- **Markdown / prose tweak redesign.** The existing markdown variants-in-place flow
+  stays as is; this spec covers web/visual surfaces only.
+- **Non-web surfaces** (PDFs, images, binary previews).
+- **Re-implementing the Impeccable live engine natively.** The engine is reused,
+  not rebuilt. Rejected during the spike as large, duplicated, security-sensitive
+  work.
+- **Multi-user concurrent tweaking of the same element.** Single-user-at-a-time per
+  surface session is assumed, consistent with the existing one-outstanding model.
+- **Changing the node-app authorization model.** Existing app-runner permissions
+  are reused unchanged.
+
+## Further Notes
+
+- **Feasibility is established.** The B1 spike confirmed the engine is HTTP plus
+  file-based state with no hard chat-agent dependency, that wiki-viewer's proxy and
+  static viewer are natural injection points, that the accept/carbonize logic can
+  be hosted over wiki-viewer's writer, and that the engine poll loop maps 1:1 onto
+  the existing attached-agent channel. The single confirmed constraint (HMR does
+  not traverse the proxy) is handled by full-reload-through-proxy and does not gate
+  shipping.
+- **Highest remaining risk is the remote-hosting transport bridge** (proxying the
+  overlay's engine endpoints through wiki-viewer's origin). It is bounded and
+  defined, but it is real new code and should be an early ticket for any non-
+  localhost use.
+- **Suggested tracer bullet** (for to-tickets): the static-HTML surface end to end
+  (spawn/host engine, inject overlay, run the product-side poll loop, wire one
+  generate through the existing agent channel, land one Accept through wiki-viewer's
+  writer). It proves the whole spine on the simplest surface; dynamic apps and the
+  transport bridge layer on top.
+- **Repo conventions:** every implementing ticket must fold in the matching
+  `docs/ux-contracts.md` update (the unified flow replaces the current §1.4
+  HTML-tweak/Iterate behavior) and the isometric codebase-map update, in the same
+  change as the behavior.

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wiki-viewer",
-	"version": "2.16.0",
+	"version": "2.16.1",
 	"description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
 	"license": "MIT",
 	"type": "module",

package/.next/standalone/server.js

@@ -15,7 +15,7 @@ const currentPort = parseInt(process.env.PORT, 10) || 3000
 const hostname = process.env.HOSTNAME || '0.0.0.0'
 
 let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
-const nextConfig = {"env":{"NEXT_PUBLIC_APP_VERSION":"2.16.0"},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/runner/work/wiki-viewer/wiki-viewer","allowedDevOrigins":["localhost"],"cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":false,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"partialFallbacks":false,"dynamicOnHover":false,"varyParams":false,"prefetchInlining":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":3,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","turbopack":{"root":"/home/runner/work/wiki-viewer/wiki-viewer"},"distDirRoot":".next"}
+const nextConfig = {"env":{"NEXT_PUBLIC_APP_VERSION":"2.16.1"},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/sil/wiki-viewer","allowedDevOrigins":["localhost"],"cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":false,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"partialFallbacks":false,"dynamicOnHover":false,"varyParams":false,"prefetchInlining":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":3,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","turbopack":{"root":"/home/sil/wiki-viewer"},"distDirRoot":".next"}
 
 process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wiki-viewer",
-	"version": "2.16.0",
+	"version": "2.16.1",
 	"description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
 	"license": "MIT",
 	"type": "module",