mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-17 16:46:31 +03:00
Paul BakausandClaude Fable 5
90f9eeb99b
The public repo keeps the OSS promise surface: skill, CLI, extension, tests, and the provider build. The site, labs, concept/composition catalogs, image pipeline, Cloudflare functions, and authoring guide move to pbakaus/impeccable-site. concept-seed tests run against a synthetic fixture catalog; the plugin icon and skill categories moved in-repo; build validation narrows to README prose and non-site counts; release notes read from a sibling impeccable-site checkout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
893 lines
82 KiB
HTML
893 lines
82 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>/impeccable live | Impeccable</title>
|
||
<meta name="description" content="Iterate on UI in the browser. Pick an element, drop a comment, get three variants. Accept one and it writes to source.">
|
||
<meta name="theme-color" content="#fafafa">
|
||
<link rel="canonical" href="https://impeccable.style/docs/live">
|
||
<link rel="icon" type="image/svg+xml" href="../favicon.svg">
|
||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||
<link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,400;0,600;1,400&family=Instrument+Sans:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600&display=swap" rel="stylesheet">
|
||
<link rel="stylesheet" href="../css/sub-pages.css">
|
||
|
||
</head>
|
||
<body class="sub-page skills-layout-page">
|
||
<a href="#main" class="skip-link">Skip to content</a>
|
||
<!-- site-header v1 -->
|
||
<header class="site-header" data-site-header>
|
||
<a href="/" class="site-header-brand" aria-label="Impeccable home">
|
||
<svg class="site-header-brand-logo" viewBox="0 0 32 32" aria-hidden="true"><rect width="32" height="32" rx="6" fill="#1a1a1a"/><text x="16" y="24" font-family="system-ui, -apple-system, sans-serif" font-size="22" font-weight="500" fill="#f5f3ef" text-anchor="middle">/</text></svg>
|
||
<span class="site-header-brand-name">Impeccable</span>
|
||
</a>
|
||
<div class="site-header-right">
|
||
<nav class="site-header-nav" aria-label="Primary">
|
||
<a href="/" data-nav="home">Home</a>
|
||
<a href="/designing" data-nav="designing">Designing</a>
|
||
<a href="/docs" data-nav="docs" aria-current="page">Docs</a>
|
||
<a href="/slop" data-nav="slop">Slop</a>
|
||
<a href="/live-mode" data-nav="live">Live</a>
|
||
</nav>
|
||
<a href="https://github.com/pbakaus/impeccable" class="site-header-github" target="_blank" rel="noopener" aria-label="Impeccable on GitHub, 21k stars">
|
||
<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"/></svg>
|
||
<span class="site-header-github-label">21k</span>
|
||
<svg class="site-header-github-star" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 2l2.76 6.36L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l7.24-.91L12 2z"/></svg>
|
||
</a>
|
||
</div>
|
||
</header>
|
||
<main id="main">
|
||
|
||
<div class="skills-layout">
|
||
|
||
<aside class="skills-sidebar" aria-label="Documentation">
|
||
<button class="skills-sidebar-toggle" type="button" aria-expanded="false" aria-controls="skills-sidebar-inner">
|
||
<span class="skills-sidebar-toggle-label">/live</span>
|
||
<svg class="skills-sidebar-toggle-chevron" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" aria-hidden="true"><path d="M6 9l6 6 6-6"/></svg>
|
||
</button>
|
||
<div class="skills-sidebar-inner" id="skills-sidebar-inner">
|
||
<p class="skills-sidebar-label">Docs</p>
|
||
|
||
<div class="skills-sidebar-group" data-category="tutorials">
|
||
<p class="skills-sidebar-group-title">Tutorials</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/tutorials/getting-started">Getting started</a></li>
|
||
<li><a href="/tutorials/iterate-live">Iterate on UI with Live Mode</a></li>
|
||
<li><a href="/tutorials/brand-vs-product">Brand vs product, pick a register</a></li>
|
||
<li><a href="/tutorials/critique-with-overlay">Critique with the visual overlay</a></li>
|
||
</ul>
|
||
</div>
|
||
<hr class="skills-sidebar-divider">
|
||
|
||
<div class="skills-sidebar-group" data-category="create">
|
||
<p class="skills-sidebar-group-title">Create</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/docs/impeccable">/impeccable</a></li>
|
||
<li><a href="/docs/craft">craft</a></li>
|
||
<li><a href="/docs/shape">shape</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="skills-sidebar-group" data-category="evaluate">
|
||
<p class="skills-sidebar-group-title">Evaluate</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/docs/audit">audit</a></li>
|
||
<li><a href="/docs/critique">critique</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="skills-sidebar-group" data-category="refine">
|
||
<p class="skills-sidebar-group-title">Refine</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/docs/animate">animate</a></li>
|
||
<li><a href="/docs/bolder">bolder</a></li>
|
||
<li><a href="/docs/colorize">colorize</a></li>
|
||
<li><a href="/docs/delight">delight</a></li>
|
||
<li><a href="/docs/layout">layout</a></li>
|
||
<li><a href="/docs/overdrive">overdrive</a></li>
|
||
<li><a href="/docs/quieter">quieter</a></li>
|
||
<li><a href="/docs/typeset">typeset</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="skills-sidebar-group" data-category="simplify">
|
||
<p class="skills-sidebar-group-title">Simplify</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/docs/adapt">adapt</a></li>
|
||
<li><a href="/docs/clarify">clarify</a></li>
|
||
<li><a href="/docs/distill">distill</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="skills-sidebar-group" data-category="harden">
|
||
<p class="skills-sidebar-group-title">Harden</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/docs/harden">harden</a></li>
|
||
<li><a href="/docs/onboard">onboard</a></li>
|
||
<li><a href="/docs/optimize">optimize</a></li>
|
||
<li><a href="/docs/polish">polish</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="skills-sidebar-group" data-category="system">
|
||
<p class="skills-sidebar-group-title">System</p>
|
||
<ul class="skills-sidebar-list">
|
||
<li><a href="/docs/document">document</a></li>
|
||
<li><a href="/docs/extract">extract</a></li>
|
||
<li><a href="/docs/live" aria-current="page">live</a></li>
|
||
<li><a href="/docs/teach">teach</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
</div>
|
||
</aside>
|
||
<div class="skills-main">
|
||
|
||
<article class="skill-detail">
|
||
<div class="skill-detail-hero">
|
||
<header class="skill-detail-header">
|
||
<p class="skill-detail-eyebrow"><a href="/docs">Docs</a> / System</p>
|
||
<h1 class="skill-detail-title"><span class="skill-detail-title-namespace"><span class="skill-detail-title-slash">/</span>impeccable</span>live</h1>
|
||
<p class="skill-detail-tagline">Iterate on UI in the browser. Pick an element, drop a comment, get three variants. Accept one and it writes to source.</p>
|
||
|
||
<div class="skill-meta-strip">
|
||
<span class="skill-meta-chip skill-meta-category" data-category="system">System</span>
|
||
<span class="skill-meta-chip">User-invocable</span>
|
||
|
||
</div>
|
||
</header>
|
||
|
||
</div>
|
||
|
||
<section class="skill-detail-editorial prose">
|
||
<div class="docs-live-callout">
|
||
<span class="docs-live-callout-icon" aria-hidden="true">▸</span>
|
||
<span class="docs-live-callout-text">See it in action, with the animated demo, at <a href="/live-mode">/live-mode</a>. This page is the reference for what your AI harness reads when the command runs.</span>
|
||
</div>
|
||
|
||
<div class="docs-live-callout">
|
||
<span class="docs-live-callout-icon" aria-hidden="true">▸</span>
|
||
<span class="docs-live-callout-text"><strong>Status: alpha.</strong> Live Mode works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups, and please report what breaks.</span>
|
||
</div>
|
||
|
||
<div class="docs-viz-hero docs-viz-hero--plain">
|
||
<div class="docs-viz-live-frame">
|
||
<div class="docs-viz-live-chrome">
|
||
<span class="docs-viz-live-dot"></span>
|
||
<span class="docs-viz-live-dot"></span>
|
||
<span class="docs-viz-live-dot"></span>
|
||
<span class="docs-viz-live-url">localhost:3000</span>
|
||
</div>
|
||
<div class="docs-viz-live-stage docs-viz-live-stage--tall">
|
||
<div class="docs-viz-live-target">
|
||
<span class="docs-viz-live-kicker">No. 04</span>
|
||
<h3 class="docs-viz-live-title">Letters, <em>occasionally</em>.</h3>
|
||
<p class="docs-viz-live-body">A postcard from the editor, about once a month. No tracking pixels, no "just checking in."</p>
|
||
<button class="docs-viz-live-btn" type="button">Send me one</button>
|
||
</div>
|
||
<div class="docs-viz-live-outline" aria-hidden="true"></div>
|
||
<div class="docs-viz-live-ctx" aria-hidden="true">
|
||
<button class="docs-viz-live-ctx-nav" type="button" aria-label="Previous">‹</button>
|
||
<span class="docs-viz-live-ctx-counter">2 / 3</span>
|
||
<button class="docs-viz-live-ctx-nav" type="button" aria-label="Next">›</button>
|
||
<span class="docs-viz-live-ctx-divider"></span>
|
||
<button class="docs-viz-live-ctx-accept" type="button">Accept</button>
|
||
</div>
|
||
<div class="docs-viz-live-gbar" aria-hidden="true">
|
||
<span class="docs-viz-live-gbar-brand">/</span>
|
||
<span class="docs-viz-live-gbar-btn is-active">Pick</span>
|
||
<span class="docs-viz-live-gbar-divider"></span>
|
||
<span class="docs-viz-live-gbar-x">✕</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p class="docs-viz-caption">Live Mode mid-cycle: the picker outlines the element you chose, the context bar shows which variant you're on, and the global bar stays pinned to the bottom. Accept on this one writes Variant 2 back to source.</p>
|
||
</div>
|
||
|
||
<h2 id="when-to-use-it">When to use it</h2>
|
||
<p>Reach for <code>/impeccable live</code> when you want to iterate on something visually the way you would in a design tool, but keep production code as the output. The canvas-like flow of Figma without the round trip to an implementation step.</p>
|
||
<p>Use it for:</p>
|
||
<ul>
|
||
<li><strong>Exploring directions on a real element.</strong> A hero section, a newsletter card, a pricing tier. Three genuinely different takes, side by side, on the actual page with the actual context.</li>
|
||
<li><strong>Polishing a piece of UI that is almost right.</strong> You know what feels off but cannot quite say it. Pick the element, scribble "more playful" or draw a stroke through the bit that bugs you, hit Go.</li>
|
||
<li><strong>A quick A/B between two directions your team is debating.</strong> Generate variants, accept nothing, walk away. The point was the comparison.</li>
|
||
</ul>
|
||
<p>It is NOT for new greenfield features (reach for <code>/impeccable craft</code>) or whole-page redesigns (reach for <code>/impeccable</code> or a specialized refine command).</p>
|
||
<h2 id="how-it-works">How it works</h2>
|
||
<p>One command brings up a picker overlay on top of your running dev server. You pick any element. A small context bar appears next to it. Type a freeform description or pick one of the action chips (<code>bolder</code>, <code>quieter</code>, <code>distill</code>, <code>polish</code>, <code>typeset</code>, <code>colorize</code>, <code>layout</code>, <code>animate</code>, <code>delight</code>, <code>overdrive</code>). Optionally drop comment pins or draw strokes directly on the element first, and the skill reads those as intent.</p>
|
||
<p>Hit Go. Three <strong>production-quality variants</strong> get generated, each anchored to a genuinely different design archetype (not three riffs on color) and hot-swapped into the page via your framework's HMR. Cycle through them with arrow keys. Accept one and the variant is written back to source. Discard all three and the original stays.</p>
|
||
<p>It supports Vite, Next.js (including monorepos), SvelteKit, Astro, Nuxt, and plain static HTML. If your dev server has a strict Content Security Policy, the first-run setup detects it and offers a one-time, dev-only patch so the picker can load. <code>DESIGN.md</code> wins on visual decisions, <code>PRODUCT.md</code> wins on voice: if you have both, variants stay on-brand without being told.</p>
|
||
<h2 id="try-it">Try it</h2>
|
||
<div class="code-block-wrap"><pre class="code-block"><code>/impeccable live</code></pre><button class="code-block-copy" type="button" data-copy="/impeccable live" aria-label="Copy to clipboard"></button></div>
|
||
<p>Open your dev server URL, pick the newsletter signup card, click the <code>delight</code> chip, hit Go. You will get three variants that vary across personality dimensions (a stamp-and-postcard feel, a typographic-surprise version, an illustrated-accent one), not three riffs on the same treatment.</p>
|
||
<p>Or pick a hero, type "more editorial, less SaaS", hit Go. The three variants anchor to different editorial archetypes (broadsheet masthead, catalog-style spec rows, oversized-glyph poster) rather than three shades of the same idea.</p>
|
||
<p>Stop live mode when you are done: say "stop live mode", close the tab, or hit the exit button on the picker bar.</p>
|
||
<h2 id="pitfalls">Pitfalls</h2>
|
||
<ul>
|
||
<li><strong>Running it on a page that is still half-written.</strong> Live variant generation needs context. If the element has placeholder copy, generic Lorem ipsum, or pre-stylesheet default formatting, variants will reflect that. Fill the content first.</li>
|
||
<li><strong>Expecting it to make macro decisions.</strong> Live mode iterates on a single picked element. For "redo the entire pricing page", reach for <code>/impeccable</code> or <code>/impeccable craft</code> instead.</li>
|
||
<li><strong>Ignoring the fallback messages.</strong> If the element lives in a generated file (a compiled template, a build output), the picker says so explicitly and offers to route the accept into true source. Do not force the accept into the generated file: the next build will wipe it.</li>
|
||
<li><strong>Running it without PRODUCT.md or DESIGN.md when you care about brand fit.</strong> Live will still generate, but the variants will lean toward generic defaults. Run <code>/impeccable teach</code> and <code>/impeccable document</code> first if the result needs to sound like your product.</li>
|
||
</ul>
|
||
|
||
</section>
|
||
|
||
|
||
|
||
<section class="skill-source-card">
|
||
<header class="skill-source-card-header">
|
||
<span class="skill-source-card-label">reference/live.md</span>
|
||
<span class="skill-source-card-subtitle">Loaded when the impeccable skill routes to this command.</span>
|
||
</header>
|
||
<div class="skill-source-card-body prose">
|
||
<p>Interactive live variant mode: select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR.</p>
|
||
<h2 id="prerequisites">Prerequisites</h2>
|
||
<p>A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.</p>
|
||
<h2 id="the-contract-read-once">The contract (read once)</h2>
|
||
<p>Execute in order. No step skipped, no step reordered.</p>
|
||
<ol>
|
||
<li><code>live.mjs</code> — boot.</li>
|
||
<li>Navigate to the URL that serves <code>pageFile</code> (infer from <code>package.json</code>, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use <code>serverPort</code> as that URL — it's the helper, not the app.</li>
|
||
<li>Poll loop with the default long timeout (600000 ms). After every event or <code>--reply</code>, run <code>live-poll.mjs</code> again immediately. Never pass a short <code>--timeout=</code>.</li>
|
||
<li>On <code>generate</code> — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; <code>--reply done</code>; poll again.</li>
|
||
<li>On <code>accept</code> / <code>discard</code> — the poll script already cleaned up; just poll again.</li>
|
||
<li>On <code>exit</code> — run the cleanup at the bottom.</li>
|
||
</ol>
|
||
<p>Harness policy:</p>
|
||
<ul>
|
||
<li><strong>Claude Code</strong>: run the poll as a <strong>background task</strong> (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell.</li>
|
||
<li><strong>Cursor</strong>: run the poll in the <strong>foreground</strong> (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout.</li>
|
||
<li><strong>Codex</strong>: run the poll in the <strong>foreground</strong> (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode.</li>
|
||
<li><strong>Other harnesses</strong>: foreground unless you know stdout reliably returns to this session.</li>
|
||
</ul>
|
||
<p>Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.</p>
|
||
<h2 id="start">Start</h2>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--bash"><code>node {{scripts_path}}/live.mjs</code></pre><button class="code-block-copy" type="button" data-copy="node {{scripts_path}}/live.mjs" aria-label="Copy to clipboard"></button></div>
|
||
<p>Output JSON: <code>{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath, migrated }</code>. <code>pageFiles</code> is the list of HTML entries the live script was injected into. Keep PRODUCT.md and DESIGN.md in mind for variant generation — <strong>DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.</strong> When DESIGN.md is missing, identity is <strong>not</strong> absent — extract it from CSS variables, computed styles, and sibling components on the page (see Step 4 Phase A). Identity preservation is the default; departure from existing identity requires an explicit trigger from PRODUCT.md anti-references or the user's freeform prompt. If <code>migrated: true</code>, the loader auto-renamed legacy <code>.impeccable.md</code> to <code>PRODUCT.md</code>; mention this once and suggest <code>/impeccable document</code> for the matching DESIGN.md.</p>
|
||
<p><code>serverPort</code> and <code>serverToken</code> belong to the small <strong>Impeccable live helper</strong> HTTP server (serves <code>/live.js</code>, SSE, and <code>/poll</code>). That port is <strong>not</strong> your dev server and is usually not the URL you open to view the app. The browser page is whatever origin serves one of the <code>pageFiles</code> entries (Vite / Next / Bun / tunnel / LAN hostname).</p>
|
||
<p>If output is <code>{ ok: false, error: "config_missing" | "config_invalid", path }</code>, this project hasn't been configured for live mode (or its config is stale). See <strong>First-time setup</strong> at the bottom.</p>
|
||
<h2 id="poll-loop">Poll loop</h2>
|
||
<div class="code-block-wrap"><pre class="code-block"><code>LOOP:
|
||
node {{scripts_path}}/live-poll.mjs # default long timeout; no --timeout=
|
||
Read JSON; dispatch on "type"
|
||
|
||
"generate" → Handle Generate; reply done; LOOP
|
||
"accept" → Handle Accept; LOOP
|
||
"discard" → Handle Discard; LOOP
|
||
"prefetch" → Handle Prefetch; LOOP
|
||
"timeout" → LOOP
|
||
"exit" → break → Cleanup</code></pre><button class="code-block-copy" type="button" data-copy="LOOP:
|
||
node {{scripts_path}}/live-poll.mjs # default long timeout; no --timeout=
|
||
Read JSON; dispatch on "type"
|
||
|
||
"generate" → Handle Generate; reply done; LOOP
|
||
"accept" → Handle Accept; LOOP
|
||
"discard" → Handle Discard; LOOP
|
||
"prefetch" → Handle Prefetch; LOOP
|
||
"timeout" → LOOP
|
||
"exit" → break → Cleanup" aria-label="Copy to clipboard"></button></div>
|
||
<h2 id="handle-generate">Handle <code>generate</code></h2>
|
||
<p>Event: <code>{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}</code>.</p>
|
||
<p>Speed matters — the user is watching a spinner. Minimize tool calls by using the <code>wrap</code> helper and writing all variants in a single edit.</p>
|
||
<h3 id="1-read-the-screenshot-if-present">1. Read the screenshot (if present)</h3>
|
||
<p><code>event.screenshotPath</code> is <strong>only sent when the user placed at least one comment or stroke before Go.</strong> When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. <strong>Read it before planning</strong> — annotations encode user intent not recoverable from <code>element.outerHTML</code> alone.</p>
|
||
<p>When <code>screenshotPath</code> is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from <code>element.outerHTML</code>, the computed styles in <code>event.element</code>, and the freeform prompt if present.</p>
|
||
<p><code>event.comments</code> and <code>event.strokes</code> carry structured metadata alongside the visual. Treat the screenshot as primary; use the structured data for specifics worth quoting (e.g. the exact text of a comment).</p>
|
||
<p>Reading annotations precisely:</p>
|
||
<ul>
|
||
<li><strong>Comment position is load-bearing.</strong> Its <code>{x, y}</code> is element-local CSS px (same coord space as <code>element.boundingRect</code>). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.</li>
|
||
<li><strong>Comments and strokes are independent annotations</strong> unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.</li>
|
||
<li><strong>Strokes are gestures — read them by shape.</strong> Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."</li>
|
||
<li><strong>When a stroke's intent is ambiguous</strong> (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.</li>
|
||
</ul>
|
||
<h3 id="2-wrap-the-element">2. Wrap the element</h3>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--bash"><code>node {{scripts_path}}/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"</code></pre><button class="code-block-copy" type="button" data-copy="node {{scripts_path}}/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"" aria-label="Copy to clipboard"></button></div>
|
||
<p>Flag mapping — keep them separate, don't collapse into <code>--query</code>:</p>
|
||
<ul>
|
||
<li><code>--element-id</code> ← <code>event.element.id</code></li>
|
||
<li><code>--classes</code> ← <code>event.element.classes</code> joined with commas</li>
|
||
<li><code>--tag</code> ← <code>event.element.tagName</code></li>
|
||
<li><code>--text</code> ← first ~80 chars of <code>event.element.textContent</code> (trim, single-line). <strong>Pass this every call.</strong> When the picked element shares classes + tag with sibling components (a list of <code><Card></code>s, repeating sections), this is what disambiguates which branch in source to wrap. Without it, wrap silently lands on the first match and may rewrite the wrong element.</li>
|
||
</ul>
|
||
<p>The helper searches ID first, then classes, then tag + class combo. If <code>event.pageUrl</code> implies the file (e.g. <code>/</code> is usually <code>index.html</code>), pass <code>--file PATH</code> to skip the search. <code>--query</code> is a fallback for raw text search only — do not use it for normal element lookups.</p>
|
||
<p>If <code>--text</code> matches multiple candidates equally well, wrap exits with <code>{ error: "element_ambiguous", candidates: [...] }</code> and <code>fallback: "agent-driven"</code> — read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.</p>
|
||
<p>Output on success: <code>{ file, insertLine, commentSyntax }</code>.</p>
|
||
<p><strong>Fallback errors.</strong> Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's <code>generatedFiles</code>). If it can't land on a source file, it errors without writing — accepting a variant into a generated file is silent data loss. Three shapes:</p>
|
||
<ul>
|
||
<li><code>{ error: "file_is_generated", file, hint }</code> — user-supplied <code>--file</code> points at a generated file.</li>
|
||
<li><code>{ error: "element_not_in_source", generatedMatch, hint }</code> — element exists only in a generated file (the next build would wipe any edits).</li>
|
||
<li><code>{ error: "element_not_found", hint }</code> — element isn't in any project file; likely runtime-injected (JS component, data-driven render).</li>
|
||
</ul>
|
||
<p>All three carry <code>fallback: "agent-driven"</code>. Follow <strong>Handle fallback</strong> below.</p>
|
||
<h3 id="3-load-the-actions-reference">3. Load the action's reference</h3>
|
||
<p>If <code>event.action</code> is <code>impeccable</code> (the default freeform action), use SKILL.md's shared laws plus the loaded register reference (<code>brand.md</code> or <code>product.md</code>). Do not load a sub-command reference. <strong>Freeform is not a pass to skip parameters:</strong> you still follow the composition budget and the freeform bias in <strong>§7 Parameters</strong> below. Sub-command files list MUST-have signature knobs; freeform has no such file, so sizing knobs from surface weight and primary axes is entirely on you.</p>
|
||
<p>Any other <code>event.action</code> (<code>bolder</code>, <code>quieter</code>, <code>distill</code>, <code>polish</code>, <code>typeset</code>, <code>colorize</code>, <code>layout</code>, <code>adapt</code>, <code>animate</code>, <code>delight</code>, <code>overdrive</code>): Read <code>reference/<action>.md</code> before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.</p>
|
||
<h3 id="4-plan-three-variants-identity-first-then-mode-then-axes">4. Plan three variants — identity first, then mode, then axes</h3>
|
||
<p>The wrong frame for live mode is "show three different design directions." Live runs on an existing surface — the brand has already been chosen. The job is variation <strong>within identity</strong>, not selection between identities. Failure mode: three editorial-typographic variants on a brief that wasn't editorial. Bigger failure mode: three off-brand variants the user can't accept because they don't look like their product.</p>
|
||
<p>Four phases. Do them in order.</p>
|
||
<h4 id="phase-a-extract-the-identity-non-skippable">Phase A: Extract the identity (non-skippable)</h4>
|
||
<p>The existing surface has an identity already. Read it before planning anything. Sources, in priority order:</p>
|
||
<ol>
|
||
<li><strong>DESIGN.md</strong> if loaded — read the visual system fields (palette, type pairing, motion, components). This is the authoritative answer.</li>
|
||
<li><strong>CSS custom properties</strong> in the page's stylesheets (<code>:root { --color-...; --font-...; ... }</code>) — these are de-facto tokens.</li>
|
||
<li><strong>Computed styles</strong> on the picked element and its parent — colors, fonts, spacing scales, corner radii.</li>
|
||
<li><strong>Sibling components on the page</strong> — what visual rhetoric do existing components use? (Asymmetric or centered? Dense or airy? Bold or quiet?)</li>
|
||
</ol>
|
||
<p>Write down what you see in <strong>one sentence</strong>. The sentence describes the surface that's actually on screen — it is not aspirational, not opinionated, not edited toward what the brand "should" be. Capture, in roughly this order:</p>
|
||
<ul>
|
||
<li>The dominant surface color and accent color, by hex or token name (use the actual values, not categories like "warm" or "neutral").</li>
|
||
<li>The type pairing — the actual font names loaded, primary first.</li>
|
||
<li>The layout topology — how the dominant elements are arranged (stacked / side-by-side / grid / asymmetric / overlay).</li>
|
||
<li>The surface treatment — corners, borders, shadows, density of decoration.</li>
|
||
<li>The voice tone you read off the copy itself, not off the aesthetic feel.</li>
|
||
</ul>
|
||
<p>Be specific. "Modern" is not a color, "elegant" is not a type pairing, "clean" is not a layout. If you can't extract a real value for an axis, skip it rather than fabricate. The point is to record what is, not to describe what you wish it were.</p>
|
||
<p>Do not include adjectives that name an aesthetic family ("editorial-leaning", "terminal-flavored", "brutalist") — those are conclusions, not data. They belong to Phase C lane selection in departure mode, not to identity description. Letting them sneak into Phase A is how the identity-lock collapses into a self-fulfilling prophecy.</p>
|
||
<p>This sentence is the <strong>identity lock</strong>. Every variant must be readable as the same brand if rendered side by side. Skipping this phase is the primary cause of off-brand variants. Absence of DESIGN.md is never an excuse — extract from CSS and computed styles instead.</p>
|
||
<h4 id="phase-b-pick-mode-default-vs-departure">Phase B: Pick mode (default vs departure)</h4>
|
||
<p><strong>Default mode</strong> — the existing identity is preserved. Variants vary expression axes within it. <em>This is the right mode for ~90% of live sessions.</em> The user picked an element on a real product they're shipping; they expect variants of <em>their</em> hero, not three different brands' heroes.</p>
|
||
<p><strong>Departure mode</strong> — the existing identity is rejected. Variants propose alternatives consistent with PRODUCT.md voice. Trigger only when at least one is true:</p>
|
||
<ul>
|
||
<li>PRODUCT.md anti-references explicitly call out the current surface ("the current <code>index.html</code> is itself an example"; "diffuse away from this"; "the page on screen is the failure"). Generic anti-references that describe what to avoid in general do <strong>not</strong> trigger departure mode — only ones that point at <em>this</em> surface specifically.</li>
|
||
<li>The user's freeform prompt explicitly asks for departure ("rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different").</li>
|
||
</ul>
|
||
<p>If you're unsure, you're in default mode. The cost of being wrong about default is "three on-brand variants with similar feel" — recoverable, the user picks none. The cost of being wrong about departure is "three off-brand variants" — unrecoverable, the user is annoyed.</p>
|
||
<h4 id="phase-c-plan-three-variants">Phase C: Plan three variants</h4>
|
||
<p><strong>Default mode.</strong> Each variant commits to a different <strong>primary axis</strong> of difference, while preserving the identity sentence. The six axes:</p>
|
||
<ol>
|
||
<li><strong>Hierarchy</strong> — which element commands the eye?</li>
|
||
<li><strong>Layout topology</strong> — stacked / side-by-side / grid / asymmetric / overlay</li>
|
||
<li><strong>Typographic system</strong> — pairing logic, scale ratio, case/weight strategy <em>within the available faces</em></li>
|
||
<li><strong>Color strategy</strong> — which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.</li>
|
||
<li><strong>Density</strong> — minimal / comfortable / dense</li>
|
||
<li><strong>Structural decomposition</strong> — merge, split, progressive disclosure</li>
|
||
</ol>
|
||
<p>Three variants → three DIFFERENT axes. The trio reads as <em>the same brand at three angles</em>. Do not introduce new fonts, new palette hues, or new aesthetic-family signals — those belong to departure mode.</p>
|
||
<p><strong>Departure mode.</strong> Each variant anchors to a different <strong>aesthetic lane</strong>, drawn from non-monoculture options. Lanes (illustrative, not exhaustive):</p>
|
||
<ul>
|
||
<li>Tech-minimal (Stripe / Linear / Vercel-restraint)</li>
|
||
<li>Brutalist-utility (system fonts, raw HTML defaults, Craigslist-energy)</li>
|
||
<li>Terminal-native (actual code surface, syntax-highlighted UI as the design)</li>
|
||
<li>Industrial-signage (dimensional type, arrow systems, ISO standards, wayfinding)</li>
|
||
<li>Technical-drawing (isometric line art, callout numbers, blueprint blue, exploded-view diagrams)</li>
|
||
<li>Drenched-saturated (Liquid Death / Mailchimp full-palette / single-hue commitment)</li>
|
||
<li>Swiss-grid-rigorous (visible grid as voice, tight type, accumulated systems)</li>
|
||
</ul>
|
||
<p>Avoid the <strong>reflex-reject lanes</strong> in <a href="brand.md">brand.md</a>. Don't trade one monoculture for another. <em>Editorial-typographic is currently a reflex-reject lane</em> — three variants that all read as "magazine cover" is the second-order training reflex, the trap one tier deeper than SaaS-cream.</p>
|
||
<h4 id="phase-d-squint-test">Phase D: Squint test</h4>
|
||
<p><strong>Default mode squint.</strong> Read each variant's identity sentence and compare to the locked identity from Phase A. If any variant has drifted to a different palette, type voice, or visual rhetoric, it has crossed into departure mode by accident — rework. Then check that each variant commits to a different primary axis. Three "tighter density" variants is failure.</p>
|
||
<p><strong>Departure mode squint.</strong> Two passes, family before sentence:</p>
|
||
<ol>
|
||
<li><strong>Family pass.</strong> Label each variant with one design-family word: <em>editorial / brutalist / terminal / signage / drenched / swiss / technical-drawing / tech-minimal</em>. If any two variants share a family label, rework. <em>This pass is non-negotiable in departure mode and catches the editorial-monoculture failure that the sentence pass misses.</em></li>
|
||
<li><strong>Sentence pass.</strong> Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.</li>
|
||
</ol>
|
||
<p><strong>When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.</strong> Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.</p>
|
||
<p><strong>For action-specific invocations</strong>, each variant must vary along the dimension the action names:</p>
|
||
<ul>
|
||
<li><code>bolder</code> — amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.</li>
|
||
<li><code>quieter</code> — pull back a different dimension (color / ornament / spacing).</li>
|
||
<li><code>distill</code> — remove a different class of excess (visual noise / redundant content / nested structure).</li>
|
||
<li><code>polish</code> — target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).</li>
|
||
<li><code>typeset</code> — different type pairing AND different scale ratio each. Not three riffs on one pairing.</li>
|
||
<li><code>colorize</code> — different hue family each (not shades of one hue). Vary chroma and contrast strategy.</li>
|
||
<li><code>layout</code> — different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.</li>
|
||
<li><code>adapt</code> — different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.</li>
|
||
<li><code>animate</code> — different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.</li>
|
||
<li><code>delight</code> — different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).</li>
|
||
<li><code>overdrive</code> — different convention broken (scale / structure / motion / input model / state transitions). Skip <code>overdrive.md</code>'s "propose and ask" step — live mode is non-interactive.</li>
|
||
</ul>
|
||
<h3 id="5-apply-the-freeform-prompt-if-present">5. Apply the freeform prompt (if present)</h3>
|
||
<p><code>event.freeformPrompt</code> is the user's ceiling on direction — all variants must honor it — but still explore meaningfully different <em>interpretations</em>. The interpretations stay within whichever mode you picked in Phase B.</p>
|
||
<p>In <strong>default mode</strong>, the prompt narrows the axes you choose, not the identity. <em>"Make it feel more confident"</em> → variant 1 amplifies hierarchy (one element commands the eye), variant 2 commits the existing accent color (Committed strategy on the brand's hue), variant 3 tightens density and removes decorative slack. Three different axes, same brand.</p>
|
||
<p>In <strong>departure mode</strong>, the prompt narrows the lanes you draw from, not the families. <em>"Make it feel like a newspaper front page"</em> would itself be a departure-mode prompt; honor it but pick three meaningfully different newspaper-adjacent lanes (broadsheet vs. tabloid vs. trade journal), and run the family pass to confirm they don't collapse into one.</p>
|
||
<p>When the prompt and PRODUCT.md anti-references conflict (the prompt asks for X, the anti-references ban X), the anti-references win — they describe the brand's standing position, the prompt is one moment.</p>
|
||
<h3 id="6-write-all-variants-in-a-single-edit">6. Write all variants in a single edit</h3>
|
||
<p>Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from <code>event.element</code>).</p>
|
||
<p>Write CSS + all variants in ONE edit at the <code>insertLine</code> reported by <code>wrap</code>. Colocate scoped CSS as a <code><style></code> tag inside the variant wrapper — <code><style></code> works anywhere in modern browsers and this ensures CSS and HTML arrive atomically (no FOUC).</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--html"><code><!-- Variants: insert below this line -->
|
||
<style data-impeccable-css="SESSION_ID">
|
||
@scope ([data-impeccable-variant="1"]) { ... }
|
||
@scope ([data-impeccable-variant="2"]) { ... }
|
||
</style>
|
||
<div data-impeccable-variant="1">
|
||
<!-- variant 1: full element replacement (single top-level element) -->
|
||
</div>
|
||
<div data-impeccable-variant="2" style="display: none">
|
||
<!-- variant 2: full element replacement -->
|
||
</div>
|
||
<div data-impeccable-variant="3" style="display: none">
|
||
<!-- variant 3: full element replacement -->
|
||
</div></code></pre><button class="code-block-copy" type="button" data-copy="<!-- Variants: insert below this line -->
|
||
<style data-impeccable-css="SESSION_ID">
|
||
@scope ([data-impeccable-variant="1"]) { ... }
|
||
@scope ([data-impeccable-variant="2"]) { ... }
|
||
</style>
|
||
<div data-impeccable-variant="1">
|
||
<!-- variant 1: full element replacement (single top-level element) -->
|
||
</div>
|
||
<div data-impeccable-variant="2" style="display: none">
|
||
<!-- variant 2: full element replacement -->
|
||
</div>
|
||
<div data-impeccable-variant="3" style="display: none">
|
||
<!-- variant 3: full element replacement -->
|
||
</div>" aria-label="Copy to clipboard"></button></div>
|
||
<p><strong>Each variant div contains exactly one top-level element — the full replacement for the original.</strong> Use the same tag as the original (e.g. <code><section></code> if the user picked a <code><section></code>). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.</p>
|
||
<p>The first variant has no <code>display: none</code> (visible by default). All others do. If variants use only inline styles and no scoped CSS, omit the <code><style></code> tag entirely. Use <code>@scope</code> for CSS isolation (Chrome 118+ / Firefox 128+ / Safari 17.4+).</p>
|
||
<p>One edit, all variants — the browser's MutationObserver picks everything up in one pass.</p>
|
||
<p><strong>Author every <code>:scope</code> rule with a descendant combinator.</strong> The <code>@scope</code> boundary is the <strong>variant wrapper <code><div data-impeccable-variant="N"></code></strong>, not the element you're designing. A bare <code>:scope { background: cream; }</code> styles the wrapper, not the inner replacement, so the cream lands on a <code>display: contents</code> shell while the actual element keeps page defaults. Always step in: <code>:scope > .card</code>, <code>:scope > section</code>, <code>:scope .hero-title</code>, etc. The fake test agent's CSS in <code>tests/live-e2e/agent.mjs</code> is a faithful template — every rule starts <code>:scope > ...</code>.</p>
|
||
<p><strong>JSX / TSX target files.</strong> Wrap <code><style></code> content in a template literal so the CSS <code>{</code> / <code>}</code> aren't parsed as JSX expressions, and use <code>className=</code> / <code>style={{…}}</code> on every variant element. Keep <code>data-impeccable-*</code> attributes as-is — they're plain strings:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--tsx"><code><style data-impeccable-css="SESSION_ID">{`
|
||
@scope ([data-impeccable-variant="1"]) { ... }
|
||
@scope ([data-impeccable-variant="2"]) { ... }
|
||
`}</style>
|
||
<div data-impeccable-variant="1">
|
||
{/* variant 1 */}
|
||
</div>
|
||
<div data-impeccable-variant="2" style={{ display: 'none' }}>
|
||
{/* variant 2 */}
|
||
</div></code></pre><button class="code-block-copy" type="button" data-copy="<style data-impeccable-css="SESSION_ID">{`
|
||
@scope ([data-impeccable-variant="1"]) { ... }
|
||
@scope ([data-impeccable-variant="2"]) { ... }
|
||
`}</style>
|
||
<div data-impeccable-variant="1">
|
||
{/* variant 1 */}
|
||
</div>
|
||
<div data-impeccable-variant="2" style={{ display: 'none' }}>
|
||
{/* variant 2 */}
|
||
</div>" aria-label="Copy to clipboard"></button></div>
|
||
<p>The wrap script already gives you a single-rooted JSX wrapper — a <code><div data-impeccable-variants="…"></code> outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.</p>
|
||
<h3 id="7-parameters-composition-sized-04-per-variant">7. Parameters (composition-sized, 0–4 per variant)</h3>
|
||
<p>Each variant can expose <strong>coarse</strong> knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.</p>
|
||
<p><strong>What “optional” does not mean.</strong> Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”</p>
|
||
<p><strong>When to add.</strong> As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” <strong>without</strong> wanting a full regeneration, wire that axis. <strong>Not</strong> micro-margins or one-off nudges; those are not parameters.</p>
|
||
<p><strong>Freeform (<code>action</code> is <code>impeccable</code>) bias.</strong> You did not load <code>reference/bolder.md</code> (etc.), so you must <strong>choose</strong> 1–2 signature-like axes yourself. Prefer knobs that sit on the same dimensions as your three directions (e.g. all three riffs on editorial density → expose <code>density</code> or a <code>steps</code> “air / snug / packed”; two directions differ mostly in chroma → add <code>color-amount</code>). A hero, section, or other <strong>large</strong> surface that ships with <strong>0</strong> params needs a one-line reason in your head (e.g. “truly a fixed-point A/B/C comparison, no shared dial”), not a default habit.</p>
|
||
<p><strong>Budget scales with the element's visual weight, not token budget.</strong> Knobs need real estate to read as tunable; three sliders on a single control are noise.</p>
|
||
<ul>
|
||
<li><strong>Leaf / tiny</strong> — a single button, icon, input, bare heading, solitary paragraph: <strong>0 params.</strong></li>
|
||
<li><strong>Small composition</strong> — labeled input, simple card, short callout (≤ ~5 visual children): <strong>0–1</strong> params when one dominant axis is obvious; otherwise <strong>0.</strong></li>
|
||
<li><strong>Medium composition</strong> — section component, nav cluster, dense card, short feature block (6–15 visual children): <strong>target 2</strong>; <strong>1</strong> is acceptable if the block is simple; <strong>0</strong> only when variants are truly fixed points.</li>
|
||
<li><strong>Large composition</strong> — hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): <strong>target 2–3</strong>; <strong>up to 4</strong> when several independent axes (e.g. structure <code>steps</code> + <code>density</code> + one accent) are all authored in scoped CSS.</li>
|
||
</ul>
|
||
<p><strong>When in doubt, ask whether a dial exists before defaulting to zero.</strong> The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; <strong>under-shipping</strong> knobs on a dense composition is the more common failure for freeform. Count by <strong>visual</strong> children, not DOM depth; a shallow-but-wide hero is still large.</p>
|
||
<p><strong>Hard cap per variant</strong> — at most <strong>four</strong> parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.</p>
|
||
<p><strong>How to declare.</strong> Put a JSON manifest on the variant wrapper:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--html"><code><div data-impeccable-variant="1" data-impeccable-params='[
|
||
{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
|
||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||
{"value":"airy","label":"Airy"},
|
||
{"value":"snug","label":"Snug"},
|
||
{"value":"packed","label":"Packed"}
|
||
]},
|
||
{"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
|
||
]'>
|
||
...variant content...
|
||
</div></code></pre><button class="code-block-copy" type="button" data-copy="<div data-impeccable-variant="1" data-impeccable-params='[
|
||
{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
|
||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||
{"value":"airy","label":"Airy"},
|
||
{"value":"snug","label":"Snug"},
|
||
{"value":"packed","label":"Packed"}
|
||
]},
|
||
{"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
|
||
]'>
|
||
...variant content...
|
||
</div>" aria-label="Copy to clipboard"></button></div>
|
||
<p><strong>Three kinds:</strong></p>
|
||
<ul>
|
||
<li><code>range</code> — smooth slider. Drives a CSS custom property <code>--p-<id></code> on the variant wrapper. Author CSS with <code>var(--p-color-amount, 0.5)</code>. Fields: <code>min</code>, <code>max</code>, <code>step</code>, <code>default</code> (number), <code>label</code>.</li>
|
||
<li><code>steps</code> — segmented radio. Drives a data attribute <code>data-p-<id></code> on the variant wrapper. Author CSS with <code>:scope[data-p-density="airy"] .grid { ... }</code>. Fields: <code>options</code> (array of <code>{value, label}</code>), <code>default</code> (string), <code>label</code>.</li>
|
||
<li><code>toggle</code> — on/off switch. Drives BOTH a CSS var (<code>--p-<id>: 0|1</code>) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: <code>default</code> (boolean), <code>label</code>.</li>
|
||
</ul>
|
||
<p><strong>Signature params per action.</strong> For named sub-commands, read that action’s <code>reference/<action>.md</code> for one or two <strong>MUST</strong> params (e.g. <code>layout</code> → <code>density</code>). Those are non-negotiable when the design can express them. <strong>Freeform has no file-level MUST</strong>; the <strong>Freeform (<code>impeccable</code>) bias</strong> in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. <code>colorize</code>), the sub-command’s MUST list takes precedence for its axes; still respect the <strong>Hard cap</strong> and add no redundant duplicate knobs.</p>
|
||
<p><strong>Reset on variant switch.</strong> User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.</p>
|
||
<p><strong>On accept</strong>, the browser sends the user's current values in the accept event. <code>live-accept.mjs</code> writes them as a sibling comment:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--html"><code><!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} --></code></pre><button class="code-block-copy" type="button" data-copy="<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} -->" aria-label="Copy to clipboard"></button></div>
|
||
<p>The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For <code>steps</code>/<code>toggle</code> attribute selectors: keep only the branch matching the chosen value, drop the others, collapse <code>:scope[data-p-density="packed"] .grid</code> to a semantic class rule. For <code>range</code> vars: either substitute the literal or keep the var with the chosen value as its new default.</p>
|
||
<h3 id="8-signal-done">8. Signal done</h3>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--bash"><code>node {{scripts_path}}/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH</code></pre><button class="code-block-copy" type="button" data-copy="node {{scripts_path}}/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH" aria-label="Copy to clipboard"></button></div>
|
||
<p><code>RELATIVE_PATH</code> is relative to project root (<code>public/index.html</code>, <code>src/App.tsx</code>, etc.) — the browser fetches source directly if the dev server lacks HMR.</p>
|
||
<p>Then run <code>live-poll.mjs</code> again immediately.</p>
|
||
<h3 id="aborting-an-in-flight-session">Aborting an in-flight session</h3>
|
||
<p>If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the <strong>browser</strong> so its bar resets to PICKING:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--bash"><code>node {{scripts_path}}/live-poll.mjs --reply EVENT_ID error "Short reason"</code></pre><button class="code-block-copy" type="button" data-copy="node {{scripts_path}}/live-poll.mjs --reply EVENT_ID error "Short reason"" aria-label="Copy to clipboard"></button></div>
|
||
<p>Don't run <code>live-accept --discard</code> for this — that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). <code>--discard</code> is only correct when the <strong>browser</strong> initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.</p>
|
||
<h2 id="handle-fallback">Handle fallback</h2>
|
||
<p>When wrap returns <code>fallback: "agent-driven"</code>, the deterministic flow doesn't apply. Pick up here.</p>
|
||
<p>The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.</p>
|
||
<h3 id="step-1-identify-where-the-element-actually-lives">Step 1: Identify where the element actually lives</h3>
|
||
<p>Use the error payload:</p>
|
||
<ul>
|
||
<li><code>element_not_in_source</code> with <code>generatedMatch: "public/docs/foo.html"</code> — the served HTML is generated. Find the generator (grep for writers of that path, e.g. <code>scripts/build-sub-pages.js</code>, an Astro/Next template) and locate the template or partial that emits this element.</li>
|
||
<li><code>element_not_found</code> — the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.</li>
|
||
<li><code>file_is_generated</code> with <code>file: "..."</code> — user pointed at a generated file explicitly. Same resolution as <code>element_not_in_source</code>.</li>
|
||
</ul>
|
||
<p>Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.</p>
|
||
<h3 id="step-2-show-three-variants-in-the-dom-for-preview">Step 2: Show three variants in the DOM for preview</h3>
|
||
<p>The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:</p>
|
||
<ol>
|
||
<li>Manually write the wrapper scaffold into the <strong>served</strong> file (the one the browser actually loaded). Use the same structure <code>live-wrap.mjs</code> produces — <code><!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end --></code>.</li>
|
||
<li>Insert your three variant divs inside it, same shape as the deterministic path.</li>
|
||
<li>Signal done with <code>--reply EVENT_ID done --file <served file></code>. The browser's no-HMR fallback will fetch and inject.</li>
|
||
</ol>
|
||
<p>This served-file edit is <strong>temporary</strong> — next regen wipes it, and that's fine. The real work happens on accept.</p>
|
||
<h3 id="step-3-on-accept-write-to-true-source">Step 3: On accept, write to true source</h3>
|
||
<p>When the accept event arrives (<code>_acceptResult.handled</code> will usually be <code>false</code> here because accept also refuses to persist into generated files — see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:</p>
|
||
<ul>
|
||
<li>Structural change → edit the template / component source.</li>
|
||
<li>Visual-only change → add or update rules in the appropriate stylesheet; remove the inline <code><style></code> scope.</li>
|
||
<li>Data-driven → update the data source or the render logic.</li>
|
||
</ul>
|
||
<p>Then remove the temporary wrapper from the served file if it's still there.</p>
|
||
<h3 id="step-4-on-discard-clean-up-the-served-file">Step 4: On discard, clean up the served file</h3>
|
||
<p>Remove the wrapper you inserted in Step 2. Nothing else to do.</p>
|
||
<h2 id="handle-accept">Handle <code>accept</code></h2>
|
||
<p>Event: <code>{id, variantId, _acceptResult}</code>. The poll script already ran <code>live-accept.mjs</code> to handle the file operation deterministically; the browser DOM is already updated.</p>
|
||
<ul>
|
||
<li><code>_acceptResult.handled: true</code> and <code>carbonize: false</code> — nothing to do. Poll again.</li>
|
||
<li><code>_acceptResult.handled: true</code> and <code>carbonize: true</code> — <strong>post-accept cleanup is required before the next poll.</strong> See the "Required after accept (carbonize)" section below. The <code>event._acceptResult.todo</code> field and a stderr banner both list the steps explicitly; neither is decorative.</li>
|
||
<li><code>_acceptResult.handled: false, mode: "fallback"</code> — the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.</li>
|
||
<li><code>_acceptResult.handled: false</code> without <code>mode</code> — manual cleanup: read file, find markers, edit.</li>
|
||
</ul>
|
||
<h3 id="required-after-accept-carbonize">Required after accept (carbonize)</h3>
|
||
<p>When <code>_acceptResult.carbonize === true</code>, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is <strong>temporary</strong>. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead <code>@scope</code> rules for unaccepted variants, a pointless <code>data-impeccable-variant</code> wrapper, and <code>impeccable-carbonize-start/end</code> comment noise in the source file — all of which accumulate across sessions.</p>
|
||
<p>Do these five steps in the current thread, synchronously, before the next poll. Do not poll again until the file is clean.</p>
|
||
<ol>
|
||
<li><strong>Locate the carbonize block</strong> in the source file (<code>_acceptResult.file</code>). It's bracketed by <code><!-- impeccable-carbonize-start SESSION_ID --></code> and <code><!-- impeccable-carbonize-end SESSION_ID --></code> and contains a <code><style data-impeccable-css="SESSION_ID"></code> element. If the variant declared parameters, an <code><!-- impeccable-param-values SESSION_ID: {...} --></code> comment sits alongside the style tag with the user's chosen values — read it first; it drives steps 3 and 4 below.</li>
|
||
<li><strong>Move the CSS rules</strong> into the project's real stylesheet. Which stylesheet depends on the project (e.g. <code>public/css/workflow.css</code> for this repo, or the component's co-located CSS file for a Vite/Next project — pick whichever already owns styling for the surrounding element).</li>
|
||
<li><strong>Bake in parameter values while rewriting selectors.</strong> For <code>@scope ([data-impeccable-variant="N"])</code> wrappers: retarget to real, semantic classes on the accepted HTML (<code>.why-visual--v2 .v2-label { … }</code>). For <code>:scope[data-p-<id>="VALUE"]</code> selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For <code>var(--p-<id>, DEFAULT)</code> in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.</li>
|
||
<li><strong>Unwrap the accepted content.</strong> Delete the <code><div data-impeccable-variant="N" style="display: contents"></code> that wraps it. Drop <code>data-impeccable-params</code> and any <code>data-p-*</code> attributes from it — those are live-mode plumbing, not source.</li>
|
||
<li><strong>Delete the inline <code><style></code> block, the <code><!-- impeccable-param-values --></code> comment if present, and both <code><!-- impeccable-carbonize-start/end --></code> markers.</strong> Also drop any <code>@scope</code> rules for variants other than the accepted one — those are dead code now.</li>
|
||
</ol>
|
||
<p>Then poll again.</p>
|
||
<p>A background agent may be used for the rewrite, but the current thread is responsible for verifying the five steps are complete before issuing the next poll. In practice, inline is usually faster and less error-prone.</p>
|
||
<h2 id="handle-discard">Handle <code>discard</code></h2>
|
||
<p>Event: <code>{id, _acceptResult}</code>. The poll script already restored the original and removed all variant markers. Nothing to do. Poll again.</p>
|
||
<h2 id="handle-prefetch">Handle <code>prefetch</code></h2>
|
||
<p>Event: <code>{pageUrl}</code>. The browser fires this the first time the user selects an element on a given route, as a latency shortcut — it signals the user is likely about to Go on a page you haven't read yet.</p>
|
||
<p>Resolve <code>pageUrl</code> to the underlying file:</p>
|
||
<ul>
|
||
<li>Root <code>/</code> → the <code>pageFile</code> returned by <code>live.mjs</code> (usually <code>public/index.html</code> or equivalent).</li>
|
||
<li>Sub-routes (e.g. <code>/docs</code>, <code>/docs/live</code>) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve <code>/foo</code> → <code>public/foo/index.html</code>; SPAs may map all routes to a single entry).</li>
|
||
</ul>
|
||
<p>Read the file into context, then poll again. No <code>--reply</code> — this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.</p>
|
||
<p>Dedupe is the browser's job (one prefetch per unique pathname per session) — trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.</p>
|
||
<h2 id="exit">Exit</h2>
|
||
<p>The user can stop live mode by:</p>
|
||
<ul>
|
||
<li>Saying "stop live mode" / "exit live" in chat</li>
|
||
<li>Closing the browser tab (SSE drops, poll returns <code>exit</code> after 8s)</li>
|
||
<li>The browser's exit button</li>
|
||
</ul>
|
||
<p>When the poll returns <code>exit</code>, proceed to cleanup. If the poll is still running as a background task, kill it first.</p>
|
||
<h2 id="cleanup">Cleanup</h2>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--bash"><code>node {{scripts_path}}/live-server.mjs stop</code></pre><button class="code-block-copy" type="button" data-copy="node {{scripts_path}}/live-server.mjs stop" aria-label="Copy to clipboard"></button></div>
|
||
<p>Stops the HTTP server and runs <code>live-inject.mjs --remove</code> to strip <code>localhost:…/live.js</code> from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use <code>stop --keep-inject</code>. <code>config.json</code> persists for future sessions.</p>
|
||
<p>Then:</p>
|
||
<ul>
|
||
<li>Remove any leftover variant wrappers (search for <code>impeccable-variants-start</code> markers).</li>
|
||
<li>Remove any leftover carbonize blocks (search for <code>impeccable-carbonize-start</code> markers).</li>
|
||
</ul>
|
||
<h2 id="first-time-setup-config-missing-or-invalid">First-time setup (config missing or invalid)</h2>
|
||
<p>If <code>live.mjs</code> outputs <code>{ ok: false, error: "config_missing" | "config_invalid", path }</code>, write <code>config.json</code> at the reported path.</p>
|
||
<p>Schema:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--json"><code>{
|
||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||
"exclude": ["<optional-glob>", ...],
|
||
"insertBefore": "</body>",
|
||
"commentSyntax": "html",
|
||
"cspChecked": true
|
||
}</code></pre><button class="code-block-copy" type="button" data-copy="{
|
||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||
"exclude": ["<optional-glob>", ...],
|
||
"insertBefore": "</body>",
|
||
"commentSyntax": "html",
|
||
"cspChecked": true
|
||
}" aria-label="Copy to clipboard"></button></div>
|
||
<p><code>files</code> is the inject target — <strong>the HTML files the browser actually loads</strong>, not necessarily source. Each entry is either a literal path (<code>"public/index.html"</code>) or a glob pattern (<code>"public/**/*.html"</code>). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.</p>
|
||
<p><code>exclude</code> (optional) is a list of glob patterns matching files to skip, even if a <code>files</code> glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.</p>
|
||
<p><code>cspChecked</code> tracks whether the CSP detection step below has already run. Absent on first setup; set to <code>true</code> after CSP is checked (whether patched, declined, or not needed).</p>
|
||
<p><strong>Hard-excluded paths (cannot be overridden).</strong> <code>**/node_modules/**</code> and <code>**/.git/**</code> are never matched regardless of what the user writes. These are vendor/metadata directories and injecting into them would silently instrument third-party code.</p>
|
||
<p><strong>Glob syntax.</strong> <code>**</code> matches any number of path segments (including zero), <code>*</code> matches any characters except <code>/</code>, <code>?</code> matches a single character except <code>/</code>. Paths are always relative to the project root with forward slashes.</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Framework</th>
|
||
<th><code>files</code></th>
|
||
<th><code>insertBefore</code></th>
|
||
<th><code>commentSyntax</code></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>SPA with single shell (Vite / React / Plain HTML)</td>
|
||
<td><code>["index.html"]</code></td>
|
||
<td><code></body></code></td>
|
||
<td><code>html</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Next.js (App Router)</td>
|
||
<td><code>["app/layout.tsx"]</code></td>
|
||
<td><code></body></code></td>
|
||
<td><code>jsx</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Next.js (Pages)</td>
|
||
<td><code>["pages/_document.tsx"]</code></td>
|
||
<td><code></body></code></td>
|
||
<td><code>jsx</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Nuxt</td>
|
||
<td><code>["app.vue"]</code></td>
|
||
<td><code></body></code></td>
|
||
<td><code>html</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Svelte / SvelteKit</td>
|
||
<td><code>["src/app.html"]</code></td>
|
||
<td><code></body></code></td>
|
||
<td><code>html</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Astro</td>
|
||
<td><code>[" <root layout .astro>"]</code></td>
|
||
<td><code></body></code></td>
|
||
<td><code>html</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Multi-page (separate HTML per route)</td>
|
||
<td><code>["public/**/*.html"]</code> — a glob covering the served directory</td>
|
||
<td><code></body></code></td>
|
||
<td><code>html</code></td>
|
||
</tr>
|
||
</tbody></table>
|
||
<p>Pick an anchor that exists in every file (<code></body></code> almost always works). Use <code>insertAfter</code> if the anchor should match <strong>after</strong> a specific line.</p>
|
||
<p>For multi-page sites, <strong>prefer a glob over a literal file list</strong>. New pages added later are picked up automatically on the next <code>live-inject.mjs</code> run; no config maintenance needed.</p>
|
||
<p>For multi-page sites whose pages are <em>rebuilt</em> by a generator (Astro, static-site generators, custom scripts like <code>build-sub-pages.js</code>), the inject survives only until the next regeneration. Re-run <code>live.mjs</code> after each build. Accept is unaffected — it writes to true source via the fallback flow.</p>
|
||
<h3 id="drift-heal-warning">Drift-heal warning</h3>
|
||
<p>On every <code>live.mjs</code> boot, after inject, the project is scanned for HTML files under common page-source roots (<code>public/</code>, <code>src/</code>, <code>app/</code>, <code>pages/</code>). If any exist that aren't covered by the resolved <code>files</code> list, the output includes a <code>configDrift</code> field:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--json"><code>{
|
||
"ok": true,
|
||
"serverPort": 8400,
|
||
"pageFiles": [ "..." ],
|
||
"configDrift": {
|
||
"orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
|
||
"orphanCount": 2,
|
||
"hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
|
||
}
|
||
}</code></pre><button class="code-block-copy" type="button" data-copy="{
|
||
"ok": true,
|
||
"serverPort": 8400,
|
||
"pageFiles": [ "..." ],
|
||
"configDrift": {
|
||
"orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
|
||
"orphanCount": 2,
|
||
"hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
|
||
}
|
||
}" aria-label="Copy to clipboard"></button></div>
|
||
<p>When <code>configDrift</code> is present, surface it to the user once per session before entering the poll loop:</p>
|
||
<blockquote>
|
||
<p>Noticed N HTML file(s) in the project that aren't in <code>config.files</code>:</p>
|
||
<ul>
|
||
<li><code>public/new-section/index.html</code></li>
|
||
<li><code>public/docs/new-command.html</code></li>
|
||
</ul>
|
||
<p>Add them, or switch <code>files</code> to a glob like <code>["public/**/*.html"]</code> and let it track new pages automatically?</p>
|
||
</blockquote>
|
||
<p>Don't auto-update the config — let the user decide. <code>configDrift</code> is <code>null</code> when there's no drift.</p>
|
||
<h3 id="csp-detection-first-time-only">CSP detection (first-time only)</h3>
|
||
<p>If <code>config.cspChecked === true</code>, skip this entire section. You already asked this user once; the answer sticks.</p>
|
||
<p>Otherwise, run the detection helper:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--bash"><code>node {{scripts_path}}/detect-csp.mjs</code></pre><button class="code-block-copy" type="button" data-copy="node {{scripts_path}}/detect-csp.mjs" aria-label="Copy to clipboard"></button></div>
|
||
<p>Output: <code>{ shape, signals }</code> where <code>shape</code> is one of <code>append-arrays</code>, <code>append-string</code>, <code>middleware</code>, <code>meta-tag</code>, or <code>null</code>. The shape is named by <em>patch mechanism</em>, so one template covers many frameworks.</p>
|
||
<ul>
|
||
<li><strong><code>null</code></strong> — no CSP; skip to writing <code>config.json</code> with <code>cspChecked: true</code>.</li>
|
||
<li><strong><code>append-arrays</code></strong> — CSP defined as structured directive arrays. Auto-patchable. See <em>append-arrays</em> below. Covers:<ul>
|
||
<li>Monorepo helpers with <code>additionalScriptSrc</code> / <code>additionalConnectSrc</code> options (Next.js + shared config package)</li>
|
||
<li>SvelteKit <code>kit.csp.directives</code></li>
|
||
<li>Nuxt <code>nuxt-security</code> module's <code>contentSecurityPolicy</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><strong><code>append-string</code></strong> — CSP written as a literal value string. Auto-patchable. See <em>append-string</em> below. Covers:<ul>
|
||
<li>Inline <code>next.config.*</code> <code>headers()</code> with a CSP literal</li>
|
||
<li>Nuxt <code>routeRules</code> / <code>nitro.routeRules</code> headers</li>
|
||
</ul>
|
||
</li>
|
||
<li><strong><code>middleware</code></strong> or <strong><code>meta-tag</code></strong> — rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add <code>http://localhost:8400</code> to <code>script-src</code> and <code>connect-src</code> manually, then mark <code>cspChecked: true</code> and proceed.</li>
|
||
</ul>
|
||
<h4 id="consent-prompt-template">Consent prompt template</h4>
|
||
<p>Use this phrasing so the experience is consistent across agents:</p>
|
||
<blockquote>
|
||
<p><strong>CSP patch needed.</strong> I detected a Content Security Policy in your project that blocks <code>http://localhost:8400</code> — the live picker won't load without an allowance. Here's the change I'd make:</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--diff"><code>[file: <patchTarget>]
|
||
[exact diff, 2–5 lines]</code></pre><button class="code-block-copy" type="button" data-copy="[file: <patchTarget>]
|
||
[exact diff, 2–5 lines]" aria-label="Copy to clipboard"></button></div>
|
||
<p>It's guarded by <code>NODE_ENV === "development"</code> so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]</p>
|
||
</blockquote>
|
||
<p>On "no": skip the patch, mention live won't work until the user adds the allowance manually, still write <code>cspChecked: true</code> (the question's been asked).</p>
|
||
<p>On "yes": apply the Shape-specific patch below, then write <code>cspChecked: true</code>.</p>
|
||
<h4 id="append-arrays">append-arrays</h4>
|
||
<p>CSP expressed as structured directive arrays. Patch mechanism: declare a dev-only array, spread it into the script-src and connect-src arrays.</p>
|
||
<p><strong>Declare near the top of the file that holds the CSP arrays:</strong></p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--ts"><code>// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||
const __impeccableLiveDev =
|
||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];</code></pre><button class="code-block-copy" type="button" data-copy="// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||
const __impeccableLiveDev =
|
||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];" aria-label="Copy to clipboard"></button></div>
|
||
<p><strong>Append <code>...__impeccableLiveDev</code> to the script-src and connect-src directive arrays.</strong> Per-framework specifics:</p>
|
||
<ul>
|
||
<li><strong>Next.js + monorepo helper</strong> — edit the <em>app's</em> <code>next.config.*</code> (not the shared helper), appending to <code>additionalScriptSrc</code> and <code>additionalConnectSrc</code> passed into <code>createBaseNextConfig</code> (or equivalent). Keeps the shared package clean.</li>
|
||
<li><strong>SvelteKit</strong> — edit <code>svelte.config.js</code>, appending to <code>kit.csp.directives['script-src']</code> and <code>kit.csp.directives['connect-src']</code>.</li>
|
||
<li><strong>Nuxt + nuxt-security</strong> — edit <code>nuxt.config.*</code>, appending to <code>security.headers.contentSecurityPolicy['script-src']</code> and <code>['connect-src']</code>.</li>
|
||
</ul>
|
||
<p>Reference outputs:</p>
|
||
<ul>
|
||
<li><code>tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts</code> (Next.js)</li>
|
||
<li><code>tests/framework-fixtures/sveltekit-csp/expected-after-patch.js</code> (SvelteKit)</li>
|
||
</ul>
|
||
<p>Idempotency: if <code>__impeccableLiveDev</code> already exists in the file, the patch is already applied; skip asking and just mark <code>cspChecked: true</code>.</p>
|
||
<h4 id="append-string">append-string</h4>
|
||
<p>CSP built as a literal value string. Two-point patch: declare a dev-only string near the top, interpolate it into the CSP at the <code>script-src</code> and <code>connect-src</code> directives.</p>
|
||
<div class="code-block-wrap"><pre class="code-block code-block--ts"><code>// Dev-only allowance so impeccable live mode can load.
|
||
const __impeccableLiveDev =
|
||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";</code></pre><button class="code-block-copy" type="button" data-copy="// Dev-only allowance so impeccable live mode can load.
|
||
const __impeccableLiveDev =
|
||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";" aria-label="Copy to clipboard"></button></div>
|
||
<p>Then in the CSP value string:</p>
|
||
<ul>
|
||
<li><code>script-src 'self' 'unsafe-inline'</code> → <code>`script-src 'self' 'unsafe-inline'${__impeccableLiveDev}`</code></li>
|
||
<li><code>connect-src 'self'</code> → <code>`connect-src 'self'${__impeccableLiveDev}`</code></li>
|
||
</ul>
|
||
<p>(Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)</p>
|
||
<p>Per-framework specifics:</p>
|
||
<ul>
|
||
<li><strong>Next.js inline <code>headers()</code></strong> — edit <code>next.config.*</code>, splicing the variable into the CSP value.</li>
|
||
<li><strong>Nuxt <code>routeRules</code></strong> — edit <code>nuxt.config.*</code>, splicing into the CSP in <code>routeRules['/**'].headers['Content-Security-Policy']</code>.</li>
|
||
</ul>
|
||
<p>Reference outputs:</p>
|
||
<ul>
|
||
<li><code>tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js</code> (Next.js)</li>
|
||
<li><code>tests/framework-fixtures/nuxt-csp/expected-after-patch.ts</code> (Nuxt)</li>
|
||
</ul>
|
||
<h3 id="troubleshooting">Troubleshooting</h3>
|
||
<p>If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks <code>http://localhost:8400</code>. Fix: delete <code>cspChecked</code> from <code>config.json</code> and re-run <code>live.mjs</code> — setup will ask again.</p>
|
||
<p>Then re-run <code>live.mjs</code>.</p>
|
||
|
||
</div>
|
||
</section>
|
||
|
||
|
||
</article>
|
||
|
||
</div>
|
||
</div>
|
||
</main>
|
||
<script>
|
||
// Copy buttons on rendered code blocks
|
||
document.addEventListener('click', (e) => {
|
||
const btn = e.target.closest('[data-copy]');
|
||
if (!btn) return;
|
||
const text = btn.getAttribute('data-copy');
|
||
if (!text) return;
|
||
navigator.clipboard.writeText(text).then(() => {
|
||
btn.classList.add('is-copied');
|
||
setTimeout(() => btn.classList.remove('is-copied'), 1500);
|
||
}).catch(() => {});
|
||
});
|
||
|
||
// Mobile sidebar toggle (shown on narrow viewports, hidden on desktop).
|
||
document.addEventListener('click', (e) => {
|
||
const toggle = e.target.closest('.skills-sidebar-toggle');
|
||
if (!toggle) return;
|
||
const expanded = toggle.getAttribute('aria-expanded') === 'true';
|
||
toggle.setAttribute('aria-expanded', String(!expanded));
|
||
});
|
||
|
||
// Before/after split-compare: drag on touch, hover OR drag on mouse.
|
||
// Pointer events attach to the padded .split-comparison wrapper so
|
||
// there is a ~20px invisible buffer around the visible box. The
|
||
// divider only snaps back when the pointer leaves that outer buffer.
|
||
(function initSplitCompare() {
|
||
const wrappers = document.querySelectorAll('.split-comparison');
|
||
if (wrappers.length === 0) return;
|
||
const hasHover = matchMedia('(hover: hover)').matches;
|
||
const DEFAULT_POSITION = 50;
|
||
|
||
for (const wrapper of wrappers) {
|
||
const container = wrapper.querySelector('.split-container');
|
||
const splitAfter = wrapper.querySelector('.split-after');
|
||
const splitDivider = wrapper.querySelector('.split-divider');
|
||
if (!container || !splitAfter || !splitDivider) continue;
|
||
|
||
const tanAngle = Math.tan(10 * Math.PI / 180);
|
||
let skewOffset = 8;
|
||
const recalcSkew = () => {
|
||
const r = container.getBoundingClientRect();
|
||
if (r.width > 0 && r.height > 0) {
|
||
skewOffset = 50 * r.height * tanAngle / r.width;
|
||
}
|
||
};
|
||
recalcSkew();
|
||
window.addEventListener('resize', recalcSkew, { passive: true });
|
||
|
||
let targetX = DEFAULT_POSITION;
|
||
let currentX = DEFAULT_POSITION;
|
||
let rafId = null;
|
||
|
||
const paint = (pct) => {
|
||
const x = Math.max(-skewOffset, Math.min(100 + skewOffset, pct));
|
||
splitAfter.style.clipPath =
|
||
`polygon(${x + skewOffset}% 0%, 100% 0%, 100% 100%, ${x - skewOffset}% 100%)`;
|
||
splitDivider.style.left = `${x}%`;
|
||
};
|
||
|
||
const step = () => {
|
||
currentX += (targetX - currentX) * 0.2;
|
||
if (Math.abs(targetX - currentX) < 0.1) {
|
||
currentX = targetX;
|
||
rafId = null;
|
||
} else {
|
||
rafId = requestAnimationFrame(step);
|
||
}
|
||
paint(currentX);
|
||
};
|
||
|
||
const setTarget = (pct) => {
|
||
targetX = pct;
|
||
if (rafId === null) rafId = requestAnimationFrame(step);
|
||
};
|
||
|
||
paint(DEFAULT_POSITION);
|
||
|
||
// Percentage is always relative to the VISIBLE .split-container,
|
||
// not the padded .split-comparison wrapper. The pointer event
|
||
// target is the wrapper but the clip-path math uses the inner box.
|
||
const pctFromClientX = (clientX) => {
|
||
const rect = container.getBoundingClientRect();
|
||
return ((clientX - rect.left) / rect.width) * 100;
|
||
};
|
||
|
||
let hovering = false;
|
||
let dragging = false;
|
||
|
||
wrapper.addEventListener('pointerenter', (e) => {
|
||
if (hasHover && e.pointerType === 'mouse') {
|
||
hovering = true;
|
||
}
|
||
});
|
||
|
||
wrapper.addEventListener('pointerdown', (e) => {
|
||
dragging = true;
|
||
wrapper.setPointerCapture(e.pointerId);
|
||
setTarget(pctFromClientX(e.clientX));
|
||
});
|
||
|
||
wrapper.addEventListener('pointermove', (e) => {
|
||
if (dragging || hovering) {
|
||
setTarget(pctFromClientX(e.clientX));
|
||
}
|
||
});
|
||
|
||
const endDrag = (e) => {
|
||
if (dragging) {
|
||
dragging = false;
|
||
try { wrapper.releasePointerCapture(e.pointerId); } catch {}
|
||
}
|
||
};
|
||
|
||
wrapper.addEventListener('pointerup', endDrag);
|
||
wrapper.addEventListener('pointercancel', endDrag);
|
||
|
||
wrapper.addEventListener('pointerleave', (e) => {
|
||
endDrag(e);
|
||
if (hovering) {
|
||
hovering = false;
|
||
setTarget(DEFAULT_POSITION);
|
||
}
|
||
});
|
||
}
|
||
})();
|
||
</script>
|
||
</body>
|
||
</html>
|