feat(brainstorming): Alpine-driven interactive visual companion (SUP-215)

[arittr]

What problem are you trying to solve?

The visual companion serves HTML mockups for brainstorming, but in practice it treats most screens as static visuals with optional [data-choice] clicks. When the interaction itself is the design question — tabs, accordions, modals, wizard next/back, simple add/remove forms, lightweight validation — agents burn tokens hand-rolling JavaScript scaffolding inline, or punt and describe the interaction in prose. The brainstorming sessions where I've hit this most are UI flows where you can't really tell whether the layout works until you can poke at it. The mockups end up either over-elaborate (a full bespoke script per screen) or under-informative (a static screenshot of one tab).

A specific example: working through a meal-planner mockup, agents wrote ~40 lines of vanilla JS each screen to wire up the tab switch between "Week" and "Grocery list" views, then re-wrote a near-identical block to manage an editable list. That's not surfacing design tradeoffs; it's framework code the agent is reinventing every screen.

What does this PR change?

Vendors Alpine.js 3.15.12 (MIT) into skills/brainstorming/scripts/vendor/ and wires the brainstorm server's frame template to auto-load it for content fragments (full-document screens are unchanged). Updates visual-companion.md to teach agents when Alpine is and isn't appropriate, and to keep [data-choice] reserved for deliberate A/B/C selection events. Adds provenance + a third-party notice for the vendored artifact. Extends the codex-plugin sync script + its test fixture so vendored files flow into the mirrored plugin.

Is this change appropriate for the core library?

This is the project's standing third-party rule (Superpowers is a zero-dependency plugin by design) deliberately overridden for one local, browser-only vendored artifact in the visual companion runtime — approved as the V1 scope of SUP-215. The design doc at docs/superpowers/specs/2026-05-08-visual-companion-alpine-design.md calls this out explicitly:

"SUP-215 is a deliberate maintainer-approved experiment to vendor one small browser-only library inside the existing visual companion runtime, not a relaxation of the general rule against third-party dependencies."

Why this belongs in core rather than a plugin:

• Visual companion is itself a core brainstorming feature; the proposed change improves that default path, it doesn't add a new surface.
• The capability is general-purpose — interactive mockups for tabs/toggles/forms apply to any project domain.
• Alpine here is browser-only, no package install, no external service, runs against localhost inside the existing companion process.
• The vendored artifact is one minified file with pinned version + SHA256 + npm integrity + license notice + refresh recipe — no supply-chain surface beyond the existing skills/ tree.

The PR is consciously cut from a clean branch (origin/dev..HEAD is exactly this one commit) per the design doc's instruction not to land SUP-215 alongside unrelated eval/migration changes.

What alternatives did you consider?

From the design doc, in order of how seriously they were weighed:

• No library, keep custom JS per screen. Preserves zero-dep purity but each interactive mockup pays the scaffolding tax again. The token cost compounds across a brainstorming session.
• Vanilla helper patterns shipped from the frame template. Sounded clean — a small set of data-toggle / data-tab directives. It quickly drifts into a Superpowers-specific mini-framework that agents must learn and that we have to evolve. We'd be reinventing Alpine, badly.
• Standalone plugin. Aligns with the project's "domain-specific → plugin" guidance, but visual companion is core brainstorming infrastructure; pulling interactive support out of core would split that one rendering path in two.
• Alpine CSP build. Useful if CSP becomes a hard requirement, but the localhost coding-harness threat model doesn't justify starting on the constrained build (and the CSP build has known feature gaps vs. the default).

Does this PR contain multiple unrelated changes?

No. One feature: Alpine support in the visual companion (SUP-215). Everything in the diff is either the vendored artifact, the server/template/skill changes that consume it, tests covering the new behavior, or the sync-script changes needed to ship the vendored file through the codex-plugin mirror.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: none address mockup interactivity. Adjacent PRs on the visual companion are:
  • fix(brainstorming): HARD-GATE visual companion per-question decision #1037 (open) — hard-gate the visual companion per-question decision. Unrelated: trigger gating, not interaction.
  • fix(brainstorming): auto-open visual companion URL on WSL2/macOS/Linux #759 (open) — auto-open companion URL on WSL2/macOS/Linux. Unrelated: launch UX.
  • fix: make visual companion idle timeout configurable #1596 (closed) — configurable idle timeout. Unrelated: lifecycle.
  • fix: make visual companion script paths skill-relative #1591 (closed) — skill-relative script paths. Unrelated: pathing; this PR's Reverts "Make visual-companion.md script paths skill-rooted, not plugin-rooted" is already in dev.
  • fix(brainstorm-server): validate Host header to defeat DNS rebinding #1553 (open) — DNS-rebinding Host header validation. Unrelated: server security.

No prior attempt to add interactive mockups was found.

Environment tested

Harness (e.g. Claude Code, Cursor)	Harness version	Model	Model version/ID
Claude Code	2.x	Opus 4.7	claude-opus-4-7

Both relevant test suites pass on macOS 25.4 (darwin arm64, bash 5 via homebrew for the codex-sync test):

• tests/brainstorm-server/server.test.js — 34/34 pass, including new assertions: vendored Alpine provenance hash, frame wrap preserves Alpine attributes, waiting page does not inject Alpine, vendor route allowlist rejects non-allowlisted paths.
• tests/codex-plugin-sync/test-sync-to-codex-plugin.sh — all assertions pass, including new vendored-section assertions on the generated sync PR body (vendored Alpine path, package/version, approval artifact, license notice path, provenance path, SHA256) and round-trip preservation of vendored files in a clean no-op apply.

The mockups themselves were exercised in a brainstorming session via Claude Code with Opus 4.7; tabs/toggles/forms/lists rendered and behaved correctly, [data-choice] still produced selection events in state/events, and terminal feedback remained the source of truth.

New harness support (required if this PR adds a new harness)

N/A. No new harness.

Notes for reviewers

• The empty ||||||| parent of … block you may see referenced elsewhere is gone. An earlier rebase landed unresolved 3-way conflict markers into tests/codex-plugin-sync/test-sync-to-codex-plugin.sh. The committed file now resolves them by keeping both sides (hooks + vendor paths are independent additions). Both test suites pass against the resolved file.
• Alpine is loaded only for frame-wrapped fragments. Full HTML documents and the waiting page do not load it (assertion covered).
• [data-choice] selection semantics are unchanged. Ordinary Alpine interactions (tabs, toggles, forms) are intentionally not recorded as choice events; terminal feedback remains primary. Skill text and example all reinforce this.