npm - @bastani/atomic - Versions diffs - 0.9.13 → 0.9.14-alpha.2 - Mend

@bastani/atomic 0.9.13 → 0.9.14-alpha.2

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

Files changed (762) hide show

package/dist/builtin/workflows/skills/impeccable/scripts/live/frameworks/tag-strategy.mjs ADDED Viewed

@@ -0,0 +1,247 @@
+/**
+ * The generic `tag` injection strategy.
+ *
+ * Frameworks without a dedicated adapter get a literal marker-wrapped
+ * `<script src>` block written into the entry template named by
+ * `.impeccable/live/config.json`. This module owns that block: building it,
+ * inserting it at the configured anchor, removing it again, and the
+ * Content-Security-Policy meta patch that keeps the cross-origin load allowed.
+ *
+ * It is deliberately framework-agnostic. Per-framework knowledge (Astro's
+ * `is:inline`, for instance) arrives as the `scriptAttrs` argument, resolved
+ * from the registry by the caller, so nothing here has to branch on a file
+ * extension or a project shape.
+ */
+import { buildLiveScriptSrc } from './script-src.mjs';
+export const MARKER_OPEN_TEXT = 'impeccable-live-start';
+export const MARKER_CLOSE_TEXT = 'impeccable-live-end';
+/** Markers that identify a file as still carrying our tag-strategy patch. */
+export const TAG_PATCH_MARKERS = Object.freeze([MARKER_OPEN_TEXT, 'data-impeccable-csp-original']);
+function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
+function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
+/**
+ * `scriptAttrs` is a pre-rendered attribute string (trailing space included)
+ * that the registry supplies for the target file. Astro is the only framework
+ * that uses it today: Astro processes `<script>` tags by default and rewrites
+ * src to its own bundled URL, so `is:inline ` opts out and the literal external
+ * src survives.
+ */
+export function buildTagBlock(syntax, port, token, scriptAttrs = '') {
+  const open = commentOpen(syntax);
+  const close = commentClose(syntax);
+  return (
+    open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
+    open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
+  );
+}
+function detectLineEnding(content) {
+  if (content.includes('\r\n')) return '\r\n';
+  if (content.includes('\r')) return '\r';
+  return '\n';
+}
+function normalizeLineEndings(content, lineEnding) {
+  return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
+}
+function readLineEndingAt(content, index) {
+  if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
+  if (content[index] === '\n') return '\n';
+  if (content[index] === '\r') return '\r';
+  return '';
+}
+export function insertTag(content, config, port, token, scriptAttrs = '') {
+  const lineEnding = detectLineEnding(content);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, token, scriptAttrs), lineEnding);
+  // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
+  // belong at the end, and the same literal can appear earlier in code blocks
+  // within rendered documentation pages.
+  if (config.insertBefore) {
+    const idx = content.lastIndexOf(config.insertBefore);
+    if (idx === -1) return content;
+    return content.slice(0, idx) + block + content.slice(idx);
+  }
+  // insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
+  // `<body>` open near the top of the document.
+  const idx = content.indexOf(config.insertAfter);
+  if (idx === -1) return content;
+  const after = idx + config.insertAfter.length;
+  // Preserve an existing trailing newline if the anchor already has one.
+  // Slice the remainder from the original anchor offset, not prefix.length:
+  // in the no-newline case prefix is one char longer than the anchor (the
+  // appended '\n'), so slicing by prefix.length would drop the first real
+  // character after the anchor (#227).
+  const existingNewline = readLineEndingAt(content, after);
+  const prefix = content.slice(0, after) + (existingNewline || lineEnding);
+  const rest = content.slice(after + existingNewline.length);
+  return prefix + block + rest;
+}
+/**
+ * Remove the live script block. Matches either HTML or JSX comment markers
+ * regardless of config (so stale tags from a wrong config can still be cleaned).
+ *
+ * Indent-preserving: captures any whitespace immediately preceding the opener
+ * marker and re-emits it in place of the removed block. `insertTag` inserted
+ * the block *after* the original line's indent and *before* the anchor (e.g.
+ * `</body>`), which moved the indent onto the opener line and left the anchor
+ * unindented. Replacing the whole block (plus its trailing newline) with just
+ * the captured indent hands the indent back to the anchor that follows.
+ */
+export function removeTag(content, _syntax) {
+  const patterns = [
+    /([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
+    /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
+  ];
+  for (const pat of patterns) {
+    let changed = false;
+    let next = content;
+    do {
+      content = next;
+      next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
+        if (/[\r\n]/.test(trailing)) return leadingIndent;
+        return leadingIndent || trailing || '';
+      });
+      if (next !== content) changed = true;
+    } while (next !== content);
+    if (changed) return next;
+  }
+  return content;
+}
+// ---------------------------------------------------------------------------
+// Content-Security-Policy meta-tag patcher
+//
+// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
+// the cross-origin load of /live.js (and the SSE/POST connection back to
+// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
+//
+// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
+// and stash the original `content` value in a `data-impeccable-csp-original`
+// attribute (base64) so revert is exact.
+//
+// On remove: detect the marker attribute, decode it, restore the original
+// content value verbatim, drop the marker.
+//
+// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
+// shared helpers) is NOT patched here — those need framework-specific config
+// edits and are handled via the existing detect-csp.mjs reference output.
+// Only the in-source meta-tag form gets the auto-patch.
+// ---------------------------------------------------------------------------
+const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
+function findCspMetaTags(content) {
+  const out = [];
+  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const attrs = m[1];
+    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
+  }
+  return out;
+}
+function getAttr(attrs, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
+  const m = attrs.match(re);
+  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
+}
+function appendOriginToDirective(csp, directive, origin) {
+  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
+  const m = csp.match(re);
+  if (m) {
+    const tokens = m[4].trim().split(/\s+/);
+    if (tokens.includes(origin)) return csp;
+    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
+  }
+  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
+  // narrow the policy compared to the default-src fallback (most users with
+  // an explicit CSP have 'self' there).
+  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
+}
+export function patchCspMeta(content, port) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  const origin = `http://localhost:${port}`;
+  // Walk last-to-first so prior splices don't invalidate later indices.
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const attrs = tag.attrs;
+    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
+    const contentAttr = getAttr(attrs, 'content');
+    if (!contentAttr) continue;
+    const original = contentAttr.value;
+    let patched = original;
+    patched = appendOriginToDirective(patched, 'script-src', origin);
+    patched = appendOriginToDirective(patched, 'connect-src', origin);
+    // The shader overlay during 'generating' creates a screenshot via
+    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
+    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
+    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
+    if (patched === original) continue;
+    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
+    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
+    // The tagRe captures any whitespace between the last attribute and the
+    // closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
+    // a replace would land it BEFORE that trailing space, leaving a double
+    // space inside attrs and clobbering the space before `/>`. Split off
+    // the trailing whitespace, splice the marker into the attribute body,
+    // and re-append the original trailing whitespace so a self-closing
+    // `<meta … />` round-trips byte-for-byte.
+    const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
+    const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
+    const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
+    const newTag = tag.full.replace(attrs, newAttrs);
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+export function revertCspMeta(content) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
+    if (!origAttr) continue;
+    const contentAttr = getAttr(tag.attrs, 'content');
+    if (!contentAttr) continue;
+    let originalValue;
+    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
+    catch { continue; }
+    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
+    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
+    // Drop the marker attribute and any single space immediately preceding it.
+    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
+    const newTag = tag.full.replace(tag.attrs, newAttrs);
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+/** The journal's undo for a tag-strategy patch: drop the block, restore CSP. */
+export function unpatchTagFile(content) {
+  return revertCspMeta(removeTag(content));
+}

package/dist/builtin/workflows/skills/impeccable/scripts/live/frameworks/tanstack-start.mjs ADDED Viewed

@@ -0,0 +1,70 @@
+/**
+ * TanStack Start registry entry.
+ *
+ * Detection and the apply/remove pair are the existing adapter's
+ * (`../tanstack-adapter.mjs`); this file only declares them to the registry
+ * and names the artifacts the journal has to be able to heal.
+ */
+import {
+  TANSTACK_MARKER_OPEN,
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+  unpatchTanStackRoot,
+} from '../tanstack-adapter.mjs';
+export const tanstackStart = {
+  name: 'tanstack-start',
+  detect(cwd) {
+    return detectTanStackStartProject(cwd);
+  },
+  inject: {
+    kind: 'adapter',
+    apply({ cwd, port, token, project }) {
+      return applyTanStackLiveAdapter({ cwd, port, token, project });
+    },
+    remove({ cwd, project }) {
+      return removeTanStackLiveAdapter({ cwd, project });
+    },
+    // The mount component's extension follows the root route's, so the path
+    // cannot live in the static ignore list.
+    ignorePatterns(project) {
+      return project?.componentFile ? [project.componentFile] : [];
+    },
+    artifacts({ project }) {
+      if (!project) return [];
+      return [
+        {
+          kind: 'created',
+          path: project.componentFile,
+          marker: 'impeccable-live-tanstack',
+          pruneTo: 'src',
+        },
+        {
+          kind: 'patched',
+          path: project.rootRoute,
+          patch: 'tanstack-root',
+          markers: [TANSTACK_MARKER_OPEN],
+        },
+      ];
+    },
+    unpatch: {
+      'tanstack-root': unpatchTanStackRoot,
+    },
+  },
+  source: {
+    extensions: ['.tsx', '.jsx'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'jsx',
+  },
+};

package/dist/builtin/workflows/skills/impeccable/scripts/live/frameworks/vite-generic.mjs ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * Generic Vite registry entry: a bundled app with a real `index.html` entry
+ * and no framework-specific document ownership. React, Vue, Solid, Preact and
+ * a plain TanStack Router SPA all land here — the marker-wrapped script block
+ * goes straight into the HTML entry.
+ *
+ * This is the entry that catches everything with a bundler config; only
+ * static-html sits below it.
+ */
+import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
+const VITE_CONFIG_RE = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+export function detectViteProject(cwd = process.cwd()) {
+  const configFile = findConfigFile(cwd, VITE_CONFIG_RE);
+  if (configFile) return { configFile, via: 'config' };
+  if (hasAnyDependency(cwd, ['vite'])) return { configFile: null, via: 'package' };
+  // A zero-config Vite app is index.html + package.json, the same pair
+  // roots.mjs treats as an app root.
+  if (fileExists(cwd, 'index.html') && fileExists(cwd, 'package.json')) {
+    return { configFile: null, via: 'zero-config' };
+  }
+  return null;
+}
+export const viteGeneric = {
+  name: 'vite-generic',
+  detect(cwd) {
+    return detectViteProject(cwd);
+  },
+  inject: { kind: 'tag' },
+  source: {
+    extensions: ['.tsx', '.jsx'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'jsx',
+  },
+};

package/dist/builtin/workflows/skills/impeccable/scripts/live/instructions.mjs ADDED Viewed

@@ -0,0 +1,169 @@
+/**
+ * Just-in-time agent instructions for live mode.
+ *
+ * The live scripts, not the reference doc, own situational plumbing: every
+ * event printed by live-poll carries an `_instructions` string describing
+ * exactly what to do NEXT, with real ids, paths, and line numbers already
+ * substituted and only the active path's rules included (a svelte-component
+ * session never sees JSX guidance, and vice versa). live.md stays lean: the
+ * session contract, harness policy, and design-quality guidance that is not
+ * situational (identity lock, variation axes, parameter budgets).
+ *
+ * Keep these strings imperative, concrete, and short. They are read by an
+ * agent mid-session; every sentence must earn its tokens. Instructions are
+ * versioned with the scripts, so they cannot drift from behavior the way a
+ * hand-maintained doc can.
+ */
+const PLAN_POINTER = 'Plan per live.md section 4: extract the identity lock, pick default vs departure mode, commit each variant to a DIFFERENT primary axis, squint-test the trio. Size parameter knobs per section 7 budgets.';
+const ANSI_ESCAPE = /\u001b(?:\][^\u0007]*(?:\u0007|\u001b\\)|\[[0-?]*[ -/]*[@-~])/gu;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu;
+const SAFE_REFERENCE_ACTIONS = new Set([
+  'adapt', 'animate', 'audit', 'bolder', 'clarify', 'colorize', 'critique', 'delight', 'distill', 'document',
+  'extract', 'harden', 'init', 'layout', 'onboard', 'optimize', 'overdrive', 'polish', 'quieter', 'shape',
+  'typeset', 'visualize',
+]);
+function safeText(value, fallback = '') {
+  return String(value ?? fallback).replace(ANSI_ESCAPE, '').replace(CONTROL_CHARACTERS, ' ').replaceAll('`', "'").slice(0, 2_000);
+}
+function shellQuote(value) {
+  const text = safeText(value);
+  if (process.platform === 'win32') return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\' + '"')}"`;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+function scriptCommand(scriptsPath, script, ...args) {
+  return `node ${shellQuote(`${safeText(scriptsPath)}/${script}`)}${args.length ? ` ${args.map(shellQuote).join(' ')}` : ''}`;
+}
+function pollCmd(scriptsPath) {
+  return scriptCommand(scriptsPath, 'live-poll.mjs');
+}
+function replyCmd(scriptsPath, id, ...args) {
+  return scriptCommand(scriptsPath, 'live-poll.mjs', '--reply', id, ...args);
+}
+function actionReference(action) {
+  const value = typeof action === 'string' ? action : '';
+  return SAFE_REFERENCE_ACTIONS.has(value) ? `reference/${value}.md` : null;
+}
+export function instructionsForEvent(event, { scriptsPath = '{{scripts_path}}' } = {}) {
+  if (!event || typeof event !== 'object') return undefined;
+  switch (event.type) {
+    case 'generate':
+      return generateInstructions(event, scriptsPath);
+    case 'steer':
+      return `Do what the message asks (page edits, navigation help, or a short answer). Then reply exactly once: ${replyCmd(scriptsPath, event.id, 'steer_done', '["optional short toast"]')} (on failure: ${replyCmd(scriptsPath, event.id, 'error', 'Short reason')}). No pickup ack; poll again immediately after.`;
+    case 'prefetch':
+      return `Speculative pre-read, no reply owed: resolve ${JSON.stringify(safeText(event.pageUrl || '/'))} to its source file (root "/" is usually the boot's pageFile; multi-page sites map /foo to public/foo/index.html; SPAs map all routes to one entry), read it into context, then poll again. Skip if you cannot resolve it confidently.`;
+    case 'variant_mount_failed':
+      return `The browser could NOT render variant ${safeText(event.variant)}${event.url ? ` (module: ${safeText(event.url)})` : ''}${event.error ? `: ${safeText(event.error).slice(0, 200)}` : ''}. The user sees a persistent error card, not variants. Fix the variant source files, then reply ${replyCmd(scriptsPath, event.id, 'done', '--file', '<manifest or source path>')}; the browser retries on its own. Poll again after the reply.`;
+    case 'accept':
+      return acceptInstructions(event, scriptsPath);
+    case 'discard':
+      return event?._completionAck?.ok === true
+        ? 'Original restored and durable completion acknowledged; nothing to do. Poll again.'
+        : `Completion was not acknowledged: run ${scriptCommand(scriptsPath, 'live-complete.mjs', '--id', event.id, '--discarded')}, then poll again.`;
+    case 'manual_edit_apply':
+      return `The user already clicked Apply; never ask, discard, or redirect. Delegate the source edits to the impeccable_manual_edit_applier subagent when available (pass cwd, scripts path, event id, page URL, chunk/deadline, batch, evidencePath); it must not poll or reply. ${event.repair ? 'A `repair` payload is present: the previous Apply changed source but validation failed; fix the CURRENT source, never roll back yourself. ' : ''}Reply exactly once: ${replyCmd(scriptsPath, event.id, 'done', '--data', '{"status":"done","appliedEntryIds":[...],"failed":[],"files":[...],"notes":[]}')} (status "partial"/"error" with failed[] when not every entry applied). Then poll again.`;
+    case 'timeout':
+      return 'No event arrived; poll again immediately.';
+    case 'exit':
+      return `Session over: kill any background poll, then ${scriptCommand(scriptsPath, 'live-server.mjs', 'stop')} (removes the injected script tag). Sweep leftover impeccable-variants-start / impeccable-carbonize-start markers from source.`;
+    default:
+      return undefined;
+  }
+}
+function generateInstructions(event, scriptsPath) {
+  const id = event.id;
+  const scaffold = event.scaffold;
+  const steps = [];
+  if (event.screenshotPath) {
+    steps.push(`Read the annotated screenshot first: ${safeText(event.screenshotPath)}. Comment {x,y} positions bind text to the child under that point; strokes read by shape (loop = emphasis on this thing, arrow = direction, cross = delete).`);
+  } else {
+    steps.push('No screenshot was sent (the user did not annotate); do not ask for one and do not screenshot the page. Work from element.outerHTML, the computed styles, and the prompt.');
+  }
+  if (event.mode === 'insert') {
+    steps.push(insertScaffoldInstructions(event, scriptsPath));
+  } else if (scaffold?.previewMode === 'svelte-component') {
+    steps.push(svelteComponentInstructions(event, scaffold, scriptsPath));
+  } else if (scaffold && scaffold.sourceWritten === false) {
+    steps.push(deferredWrapperInstructions(event, scaffold, scriptsPath));
+  } else if (scaffold) {
+    steps.push(`The wrapper is already written into ${safeText(scaffold.file)}. Splice preview CSS plus all ${safeText(event.count)} variants at line ${safeText(scaffold.insertLine)} in ONE edit, following the returned cssAuthoring contract (styleTag, selector strategy, forbidden patterns). Each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none.`);
+  } else {
+    const element = event.element && typeof event.element === 'object' ? event.element : {};
+    const classes = Array.isArray(element.classes) ? element.classes.map((value) => safeText(value)).join(',') : '';
+    steps.push(`Preflight could not scaffold${event.scaffoldError ? ` (${safeText(event.scaffoldError)})` : ''}. Run ${scriptCommand(scriptsPath, 'live-wrap.mjs', '--id', id, '--count', event.count, '--element-id', element.id || '', '--classes', classes, '--tag', element.tagName || '', '--text', '<first ~80 chars of the picked element textContent>')}. Keep the flags separate; --text disambiguates repeated siblings. On a fallback error, follow live.md's Handle fallback.`);
+  }
+  const reference = actionReference(event.action);
+  steps.push(reference
+    ? `Action is "${safeText(event.action)}": read ${reference} before planning; its MUST params are non-negotiable. ${PLAN_POINTER}`
+    : event.action && event.action !== 'impeccable'
+      ? `The requested action has no approved reference document; do not construct a path from it. Follow SKILL.md rules and the craft floor. ${PLAN_POINTER}`
+      : `Freeform action: work from SKILL.md rules plus craft-floor.md; no sub-command file. ${PLAN_POINTER}`);
+  steps.push(`When all ${safeText(event.count)} variants are delivered: ${replyCmd(scriptsPath, id, 'done', '--file', '<project-root-relative path you wrote>')}. Then poll again. If generation fails after the browser flipped to GENERATING, ${replyCmd(scriptsPath, id, 'error', 'Short reason')} so the bar resets (never live-accept --discard for this).`);
+  return steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+}
+function svelteComponentInstructions(event, scaffold) {
+  const dir = safeText(scaffold.componentDir);
+  const count = safeText(event.count);
+  const file = safeText(scaffold.file);
+  const sourceFile = safeText(scaffold.sourceFile);
+  return `Svelte component preview. EDIT the existing stubs ${dir}/v1.svelte ... v${count}.svelte in place; never delete or recreate them; do not read them back (the prop-substituted markup is in scaffold.componentStubMarkup). Keep the stub's control flow ({#each}, {#if}) and propContract prop names exactly; never flatten a loop into literal items. The stub <style> is seeded with the source rules that style the selection; restyle or delete freely, and know that any seeded rule you do not re-declare is REMOVED from source on accept (the preview never applied it). ALL your CSS goes inside that ONE existing <style> block: Svelte forbids a second top-level style element, and a publish with a non-compiling variant is bounced back to you with file and line. Semantic class selectors only: no @scope, no data-impeccable-* attributes. Params go in ${dir}/params.json keyed by variant number (never an attribute); author knob CSS against var(--p-<id>, default) and :global([data-p-<id>="..."]). Reply with --file ${shellQuote(file)}. Accept later merges everything into ${sourceFile} mechanically; you have no post-accept cleanup.`;
+}
+function deferredWrapperInstructions(event, scaffold) {
+  const start = safeText(scaffold.replaceStartLine);
+  const end = safeText(scaffold.replaceEndLine);
+  const insertNote = Number(scaffold.replaceEndLine) < Number(scaffold.replaceStartLine)
+    ? ` (replaceEndLine < replaceStartLine: this is an INSERTION at line ${start}; remove nothing)`
+    : '';
+  return `The wrapper is NOT in source yet. In ONE edit to ${safeText(scaffold.file)}: splice preview CSS plus all ${safeText(event.count)} variants into scaffold.wrapperBlock at the "Variants: insert below this line" marker, then replace lines ${start}-${end}${insertNote} with the result. Two separate writes reload the framework mid-publish and strand the browser at 0/N. Author CSS per the returned cssAuthoring contract; each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none. On JSX/TSX wrap the <style> content in a template literal and use className / style={{...}}.`;
+}
+function insertScaffoldInstructions(event, scriptsPath) {
+  const scaffold = event.scaffold;
+  const base = `Insert mode: net-new content sized around ${safeText(event.placeholder?.width || '?')}x${safeText(event.placeholder?.height || '?')} at the chosen anchor; load craft-floor.md before writing net-new markup.`;
+  if (scaffold?.previewMode === 'svelte-component') {
+    return `${base} Write each inserted variant as a single-root Svelte component under ${safeText(scaffold.componentDir)} (no data-impeccable-* attributes, CSS in each component's <style>). Never edit the route during generation; reply with --file ${shellQuote(safeText(scaffold.file))}.`;
+  }
+  if (scaffold && scaffold.sourceWritten === false) {
+    return `${base} Splice your variants into scaffold.wrapperBlock at the marker and insert the result at line ${safeText(scaffold.replaceStartLine)} of ${safeText(scaffold.file)} in ONE edit.`;
+  }
+  return `${base} If no scaffold payload is present, run ${scriptCommand(scriptsPath, 'live-insert.mjs', '--id', event.id, '--count', event.count, '--position', event.insert?.position || 'after')} with the anchor flags from event.insert.anchor, then splice variants at the returned insertLine.`;
+}
+function acceptInstructions(event, scriptsPath) {
+  const result = event._acceptResult && typeof event._acceptResult === 'object' ? event._acceptResult : {};
+  const ackOk = event._completionAck?.ok === true;
+  const prefix = ackOk ? '' : `Completion was NOT acknowledged: run ${scriptCommand(scriptsPath, 'live-status.mjs')}, finish any cleanup, then ${scriptCommand(scriptsPath, 'live-complete.mjs', '--id', event.id)}. `;
+  if (result.handled === true && result.carbonize === true) {
+    return `${prefix}Carbonize cleanup is REQUIRED now, before the next poll, in ${safeText(result.file)}: (1) locate the impeccable-carbonize-start/end block and read the impeccable-param-values comment; (2) move the CSS rules into the stylesheet that owns this area; (3) bake params while rewriting selectors (@scope wrappers to semantic classes, keep only the chosen data-p branch, substitute range literals); (4) unwrap the accepted content and drop every data-impeccable-* / data-p-* attribute; (5) delete the inline <style>, the param-values comment, and both markers plus dead @scope rules. Then run ${scriptCommand(scriptsPath, 'live-complete.mjs', '--id', event.id)} and verify phase "completed"; it refuses with source_dirty while leftovers remain. Poll again only after that.`;
+  }
+  if (result.handled === true) return `${prefix}Accept was merged into source mechanically; nothing to clean up. Poll again.`;
+  if (result.mode === 'fallback') return `${prefix}The session lived in a generated file, so accept refused to persist there. Write the accepted variant into the true source you identified during Handle fallback, remove the temporary wrapper from the served file, then poll again.`;
+  if (result.mode === 'error') {
+    if (result.error === 'source_locked') return `${prefix}The source file is briefly locked by a publisher. Re-run the exact same live-accept.mjs command (idempotent); do NOT hand-edit the file, and do not poll past this.`;
+    if (result.error === 'accept_receipt_conflict') return `${prefix}This session already resolved as ${safeText(result.priorOperation || 'a prior operation')}; do not edit anything. Run ${scriptCommand(scriptsPath, 'live-status.mjs')} and tell the user what the session resolved to.`;
+    return `${prefix}Accept failed: ${safeText(result.error || 'unknown error')}. Source was not touched; do not hand-edit. Run ${scriptCommand(scriptsPath, 'live-status.mjs')} before continuing.`;
+  }
+  return `${prefix}No mechanical accept result; read ${safeText(result.file || 'the session source file')}, find the impeccable markers, and finish the merge by hand. Poll again after.`;
+}
+/** Boot instructions attached to live.mjs's success payload. */
+export function bootInstructions({ scriptsPath = '{{scripts_path}}' } = {}) {
+  return `Open the app URL that serves a pageFiles entry (never serverPort; that is the helper). Then start the poll loop per your harness policy in live.md and re-run ${pollCmd(scriptsPath)} immediately after every event or reply. Every event carries _instructions: follow them; they are the authoritative next step with real ids and paths filled in. A poll that is running is a poll you are SERVICING: never announce you are waiting and idle your turn; stay on the exec session until it returns an event, and never end a turn while a poll is outstanding.`;
+}