@momentiq/dark-factory-cli 3.0.2 → 3.1.1

package/dist/mode/preview.js

@@ -0,0 +1,802 @@
+// `df mode preview <component-path>` — component-isolation visual evidence
+// (Closes momentiq-ai/dark-factory#357).
+//
+// THE PAIN. Designer Mode's `evidence.visual: required` mandates a visual loop:
+// boot the app, navigate to the changed surface, screenshot it (the `ui-visual`
+// route). On a container-first / k3d repo the app needs auth + seeded data to
+// boot, and a bare component (a `components/Widget.tsx` with no page that renders
+// it) maps to NO navigable route — so the `ui-visual` route FAILS CLOSED
+// (`planCapture` → `uncovered`) and a NON-ENGINEER cannot produce a screenshot.
+// In the #357 dogfood ~5 avenues to a screenshot all dead-ended here.
+//
+// THE FIX (bounded, first version). Render the ONE component in an isolated
+// harness — no full app, no auth, no data — and capture the SAME evidence shape
+// the `ui-visual` route already emits (`agent-reviews/quality-gates/ui/<sha>/
+// <slug>/{aria.snapshot.txt, after.png, meta.json}`, `evidenceKind:"playwright"`).
+// The existing embed/publish path (`discoverUiEvidence` / `buildScreenshotEmbed`
+// / `readUiArtifacts`) consumes it unchanged. This does NOT by itself create a
+// `QualityGateEvidence` gate result — it produces the artifacts that path renders
+// for a human and uploads.
+//
+// This module is the PURE + orchestration half (no browser, no bundler): harness
+// generation and framework detection are pure and unit-tested; `runPreview` takes
+// an injected `CaptureDeps` so the Vite-server + Playwright wiring
+// (`preview-capture.ts`) is never imported by tests. It degrades gracefully —
+// never crashes — when the component genuinely cannot be rendered (no React / no
+// Vite / a server component) or when the local capture tooling is unavailable.
+//
+// FRAMEWORK BOUNDARY (see the PR body — this is the design edge for PJ + the
+// parallel role-redesign): v1 targets the common case, a React client component
+// rendered through Vite. Vue/Svelte/Angular, Webpack/CRA transform, React Server
+// Components, and a prop-fixture/args model are DEFERRED — each degrades with a
+// clear message rather than a wrong render.
+import { mkdtempSync, readFileSync, existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep, basename, dirname } from "node:path";
+import { resolveCommit } from "../git.js";
+import { FRONTEND_ROOT_DIRS } from "./init.js";
+function packageDeclaresReact(dir) {
+    const deps = readPackageDeps(dir);
+    return !!deps && "react" in deps;
+}
+/**
+ * Resolve the frontend workspace for a repo rooted at `cwd`. Mirrors
+ * `df mode init`'s detection (same FRONTEND_ROOT_DIRS): the first of
+ * `web/`,`frontend/`,`client/` whose package.json declares react wins; else the
+ * repo root itself when ITS package.json declares react. Returns `null` when no
+ * react is found anywhere — the caller degrades with the existing no-react
+ * blocker (which keeps the honest "install react" message + exit code). PURE.
+ */
+export function resolveFrontendWorkspace(cwd) {
+    for (const root of FRONTEND_ROOT_DIRS) {
+        const dir = join(cwd, root);
+        if (packageDeclaresReact(dir))
+            return { workspaceDir: dir, relLabel: root };
+    }
+    if (packageDeclaresReact(cwd))
+        return { workspaceDir: cwd, relLabel: "." };
+    return null;
+}
+/**
+ * Strip line (`//`) and block comments from JSONC, STRING-AWARE: a naive
+ * stripper corrupts a value like `"./src/*"` (which contains a literal
+ * slash-star) by treating it as the start of a block comment. Tracks string
+ * state (and escapes) so only real comments are removed. PURE.
+ */
+export function stripJsonComments(text) {
+    let out = "";
+    let inString = false;
+    let inLine = false;
+    let inBlock = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const next = text[i + 1];
+        if (inLine) {
+            if (c === "\n") {
+                inLine = false;
+                out += c;
+            }
+            continue;
+        }
+        if (inBlock) {
+            if (c === "*" && next === "/") {
+                inBlock = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            out += c;
+            if (c === "\\") {
+                // Preserve the escaped char verbatim (e.g. \" \\ ) — it can't close the string.
+                if (next !== undefined) {
+                    out += next;
+                    i++;
+                }
+                continue;
+            }
+            if (c === '"')
+                inString = false;
+            continue;
+        }
+        // Outside string + comment.
+        if (c === '"') {
+            inString = true;
+            out += c;
+            continue;
+        }
+        if (c === "/" && next === "/") {
+            inLine = true;
+            i++;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            inBlock = true;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    return out;
+}
+/** Tolerant JSONC parse: strip comments (string-aware) + trailing commas, then
+ *  JSON.parse. Returns `null` on any failure (caller proceeds with no alias). */
+export function parseJsonc(text) {
+    try {
+        const noComments = stripJsonComments(text);
+        // Drop a trailing comma before `}`/`]`. Applied to comment-free text; tsconfig
+        // `paths` values are globs (`./src/*`), never `, }`, so this is safe here.
+        const noTrailingCommas = noComments.replace(/,(\s*[}\]])/g, "$1");
+        return JSON.parse(noTrailingCommas);
+    }
+    catch {
+        return null;
+    }
+}
+function escapeRegexLiteral(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Classify ONE tsconfig `paths` string (a key OR a target) into the shapes an
+ * alias can faithfully represent. ONE classifier for BOTH sides — so key and
+ * target are judged by the identical rule and there is no third, un-handled case.
+ *  - no `*` → `exact` (prefix = the whole string).
+ *  - a single trailing `/*` with a non-empty segment before the `/*`
+ *    (`"@/*"`, `"./src/*"`, `"./*"`) → `prefix` (prefix = string minus the
+ *    trailing `/*`, e.g. `"@/*"` → `"@"`, `"./src/*"` → `"./src"`).
+ *  - everything else — a mid-pattern wildcard (a `*` with more path segments
+ *    after it, e.g. a `@foo` key with a `bar` suffix, or a monorepo
+ *    `packages`-style target), a bare prefix (`"@*"`), a bare `"*"` catch-all,
+ *    or a degenerate `"/*"` (empty prefix) → `unsupported`.
+ */
+function classifyGlob(str) {
+    const starIdx = str.indexOf("*");
+    if (starIdx === -1)
+        return { kind: "exact", prefix: str };
+    const single = starIdx === str.lastIndexOf("*");
+    // Trailing "/*" (str ends with "/*") AND a non-empty segment before it
+    // (str.length > 2 rules out the degenerate "/*").
+    if (single && str.endsWith("/*") && str.length > 2) {
+        return { kind: "prefix", prefix: str.slice(0, -2) };
+    }
+    return { kind: "unsupported", prefix: "" };
+}
+/**
+ * Convert tsconfig `compilerOptions.paths` (+ `baseUrl`) into Vite alias entries.
+ * `paths` targets resolve relative to `baseUrl` (default `.` = tsconfigDir).
+ * Only the FIRST target is used (Vite alias has no fallback array). PURE.
+ *
+ * A single `classifyGlob` is applied to BOTH the key and the target, and an entry
+ * is emitted ONLY when the two AGREE — so mis-shapen mappings can't leak through
+ * on either side:
+ *  - both `exact` → exact alias (`^<key>$` → resolved target).
+ *  - both `prefix` → prefix alias (`^<keyPrefix>/` → `<resolvedTargetPrefix>/`).
+ *    The find RE-ADDS the boundary `/` so it anchors on a path separator: `"@/*"`
+ *    → `^@/`, which never matches `@scope/pkg` (a bare `^@` WOULD shadow every
+ *    scoped npm package — the bug this guards).
+ *  - ANY other combination — either side `unsupported`, or a KIND MISMATCH like a
+ *    `prefix` key with an `exact` target (`"@/*": ["./src/index.ts"]`, invalid
+ *    TS) — is SKIPPED: the key is returned in `unsupported`, no alias, no throw.
+ *
+ * The common shadcn/Next shapes (`"@/*": ["./src/*"]`, `["./*"]`, exact keys) are
+ * unaffected; monorepo mid-glob mappings (a `@pkg` key mapped to a
+ * `packages`-style target with an inner wildcard) skip.
+ */
+export function tsconfigPathsToAlias(input) {
+    const { paths, tsconfigDir } = input;
+    if (!paths || typeof paths !== "object")
+        return { alias: [], unsupported: [] };
+    const baseAbs = resolve(tsconfigDir, input.baseUrl ?? ".");
+    const alias = [];
+    const unsupported = [];
+    for (const [key, targets] of Object.entries(paths)) {
+        if (!Array.isArray(targets) || targets.length === 0)
+            continue;
+        const target = targets[0];
+        if (typeof target !== "string")
+            continue;
+        const k = classifyGlob(key);
+        const t = classifyGlob(target);
+        if (k.kind === "exact" && t.kind === "exact") {
+            // Exact key → exact-match alias to the resolved (file/dir) target.
+            alias.push({
+                find: new RegExp(`^${escapeRegexLiteral(k.prefix)}$`),
+                replacement: resolve(baseAbs, t.prefix),
+            });
+            continue;
+        }
+        if (k.kind === "prefix" && t.kind === "prefix") {
+            // Re-add the boundary "/" to the KEY find (anchors on a path separator so
+            // `^@/` never matches `@scope/pkg`) and a trailing sep to the resolved
+            // TARGET prefix (the find consumes the source's boundary "/").
+            let replacement = resolve(baseAbs, t.prefix); // strips any trailing sep
+            if (!replacement.endsWith(sep))
+                replacement += sep;
+            alias.push({ find: new RegExp(`^${escapeRegexLiteral(k.prefix)}/`), replacement });
+            continue;
+        }
+        // Either side unsupported, OR a key/target kind mismatch → skip + surface.
+        unsupported.push(key);
+    }
+    return { alias, unsupported };
+}
+/** Read compilerOptions.{paths,baseUrl} + `extends` from a tsconfig/jsconfig
+ *  file (JSONC-tolerant). Returns null when the file is unreadable/unparseable. */
+function readTsconfigFile(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const parsed = parseJsonc(raw);
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const co = parsed.compilerOptions ?? {};
+    return {
+        ...(co.paths ? { paths: co.paths } : {}),
+        ...(typeof co.baseUrl === "string" ? { baseUrl: co.baseUrl } : {}),
+        ...(typeof parsed.extends === "string" ? { extends: parsed.extends } : {}),
+    };
+}
+function toAliasResolution(r) {
+    return {
+        alias: r.alias,
+        warnings: r.unsupported.map((k) => `path alias "${k}" not wired (unsupported glob shape)`),
+    };
+}
+/**
+ * Read the workspace's tsconfig (jsconfig fallback) and return Vite alias
+ * entries for its path map, plus notes for any keys skipped as unsupported. When
+ * the top file has no `paths` but a TRIVIAL relative `extends` (a `./…json` path,
+ * one level), the base file's `paths` are used, resolved relative to the base
+ * file's dir. Non-trivial extends (a bare package specifier, an array of extends,
+ * or multi-level chains) are DEFERRED — proceed with no alias rather than
+ * half-resolve. Missing tsconfig / no `paths` → empty (unchanged behavior; the
+ * harness just has no extra aliases). Impure (fs); the conversion it delegates to
+ * is pure + unit-tested.
+ */
+function readAliasEntries(workspaceDir) {
+    const none = { alias: [], warnings: [] };
+    for (const name of ["tsconfig.json", "jsconfig.json"]) {
+        const filePath = join(workspaceDir, name);
+        const cfg = readTsconfigFile(filePath);
+        if (!cfg)
+            continue;
+        if (cfg.paths) {
+            return toAliasResolution(tsconfigPathsToAlias({ paths: cfg.paths, baseUrl: cfg.baseUrl, tsconfigDir: workspaceDir }));
+        }
+        // One level of trivial relative extends (the common "extends ./tsconfig.base.json").
+        if (typeof cfg.extends === "string" && cfg.extends.startsWith(".")) {
+            let ext = cfg.extends;
+            if (!ext.endsWith(".json"))
+                ext += ".json";
+            const extPath = resolve(workspaceDir, ext);
+            const base = readTsconfigFile(extPath);
+            if (base?.paths) {
+                return toAliasResolution(tsconfigPathsToAlias({
+                    paths: base.paths,
+                    baseUrl: base.baseUrl,
+                    tsconfigDir: dirname(extPath),
+                }));
+            }
+        }
+        return none;
+    }
+    return none;
+}
+export const ENTRY_BASENAME = "df-preview-entry.tsx";
+export const INDEX_HTML_BASENAME = "index.html";
+/** POSIX-normalize a relative fs path for use as an ES import specifier. */
+function toImportSpecifier(from, to) {
+    let spec = relative(from, to).split(sep).join("/");
+    if (!spec.startsWith("."))
+        spec = `./${spec}`;
+    return spec;
+}
+/**
+ * Generate the minimal isolated-render harness for a React component: an entry
+ * that mounts JUST that component (placeholder/default props) inside a `<main>`
+ * landmark, plus an `index.html`. The `<main>` wrapper guarantees the same
+ * structural render floor the `ui-visual` producer asserts (`getByRole("main")`),
+ * regardless of what the component itself renders. PURE — returns file contents;
+ * the caller writes them.
+ */
+export function generateHarness(input) {
+    const { componentAbsPath, harnessDir, componentName, exportName, reactMajor } = input;
+    const importSpec = toImportSpecifier(harnessDir, componentAbsPath);
+    const importLine = exportName === undefined
+        ? `import Target from ${JSON.stringify(importSpec)};`
+        : `import { ${exportName} as Target } from ${JSON.stringify(importSpec)};`;
+    // React major picks the mount API. `import React` is inert under the automatic
+    // JSX runtime (plugin-react's default) and covers a classic-runtime consumer.
+    const mount = reactMajor >= 18
+        ? [
+            `import { createRoot } from "react-dom/client";`,
+            `const el = document.getElementById("df-preview-root");`,
+            `if (el) {`,
+            `  createRoot(el).render(`,
+            `    <main aria-label=${JSON.stringify(`df preview: ${componentName}`)}>`,
+            `      <Target />`,
+            `    </main>,`,
+            `  );`,
+            `}`,
+        ]
+        : [
+            `import { render } from "react-dom";`,
+            `const el = document.getElementById("df-preview-root");`,
+            `if (el) {`,
+            `  render(`,
+            `    <main aria-label=${JSON.stringify(`df preview: ${componentName}`)}>`,
+            `      <Target />`,
+            `    </main>,`,
+            `    el,`,
+            `  );`,
+            `}`,
+        ];
+    const entry = [
+        `// AUTO-GENERATED by \`df mode preview\` — isolated render harness for`,
+        `// ${componentName}. Ephemeral; the command removes this dir after capture.`,
+        `import React from "react";`,
+        importLine,
+        "",
+        ...mount,
+        "",
+    ].join("\n");
+    const html = [
+        `<!doctype html>`,
+        `<html lang="en">`,
+        `  <head>`,
+        `    <meta charset="utf-8" />`,
+        `    <meta name="viewport" content="width=device-width, initial-scale=1" />`,
+        `    <title>df preview: ${escapeHtml(componentName)}</title>`,
+        `  </head>`,
+        `  <body>`,
+        `    <div id="df-preview-root"></div>`,
+        `    <script type="module" src="/${ENTRY_BASENAME}"></script>`,
+        `  </body>`,
+        `</html>`,
+        "",
+    ].join("\n");
+    return [
+        { path: ENTRY_BASENAME, contents: entry },
+        { path: INDEX_HTML_BASENAME, contents: html },
+    ];
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+const COMPONENT_EXT_RE = /\.(tsx|jsx)$/;
+function parseReactMajor(deps) {
+    const raw = deps?.["react"];
+    if (!raw)
+        return null;
+    const m = raw.match(/(\d+)/);
+    return m ? Number(m[1]) : null;
+}
+/** Best-effort PascalCase component name from a filename (`user-card.tsx` →
+ *  `UserCard`, `Button.tsx` → `Button`). */
+export function componentNameFromPath(componentAbsPath) {
+    const base = basename(componentAbsPath).replace(COMPONENT_EXT_RE, "");
+    const parts = base.split(/[-_.\s]+/).filter(Boolean);
+    if (parts.length === 0)
+        return "Component";
+    return parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}
+/**
+ * Resolve which export the harness should mount. Preference order:
+ *   1. `export default` present → default import (undefined exportName).
+ *   2. a named export matching the PascalCase filename.
+ *   3. the first `export function|const <PascalCaseName>`.
+ * Returns `{ kind: "none" }` when no export is found (a blocker).
+ */
+export function resolveExport(source, componentName) {
+    if (/\bexport\s+default\b/.test(source))
+        return { kind: "default" };
+    const named = new Set();
+    const re = /\bexport\s+(?:async\s+)?(?:function|const|class)\s+([A-Za-z_$][\w$]*)/g;
+    let m;
+    while ((m = re.exec(source)) !== null)
+        named.add(m[1]);
+    // `export { Foo, Bar as Baz }`
+    const reBlock = /\bexport\s*\{([^}]*)\}/g;
+    while ((m = reBlock.exec(source)) !== null) {
+        for (const piece of m[1].split(",")) {
+            const asMatch = piece.trim().match(/(?:\bas\s+([A-Za-z_$][\w$]*))$/);
+            const name = asMatch ? asMatch[1] : piece.trim().split(/\s+/)[0];
+            if (name)
+                named.add(name);
+        }
+    }
+    if (named.has(componentName))
+        return { kind: "named", name: componentName };
+    // First PascalCase named export (React components are PascalCase by convention).
+    for (const n of named) {
+        if (/^[A-Z]/.test(n))
+            return { kind: "named", name: n };
+    }
+    return { kind: "none" };
+}
+/** Strong-signal heuristic: is this a React Server Component (unrenderable in a
+ *  client-only harness)? Conservative — only fires on unambiguous signals so an
+ *  ordinary client component is never false-blocked. */
+function looksLikeServerComponent(source) {
+    const hasUseClient = /^\s*['"]use client['"]\s*;?/m.test(source);
+    if (hasUseClient)
+        return false;
+    // Catches both `import 'server-only'` (side-effect) and `... from 'server-only'`.
+    if (/import[^;\n]*['"]server-only['"]/.test(source))
+        return true;
+    // An `async` default component only makes sense as an RSC.
+    if (/\bexport\s+default\s+async\s+function\b/.test(source))
+        return true;
+    if (/\bexport\s+async\s+function\s+[A-Z]/.test(source))
+        return true;
+    return false;
+}
+/**
+ * Decide whether the component can be rendered via the generated Vite harness,
+ * and gather advisories. PURE — no fs, no network.
+ */
+export function detectStrategy(input) {
+    const { componentAbsPath, source, packageDeps } = input;
+    const componentName = componentNameFromPath(componentAbsPath);
+    const reactMajor = parseReactMajor(packageDeps) ?? 18;
+    const storybook = !!packageDeps && Object.keys(packageDeps).some((d) => d.startsWith("@storybook/"));
+    const ladle = !!packageDeps && "@ladle/react" in packageDeps;
+    const warnings = [];
+    if (storybook || ladle) {
+        warnings.push(`${storybook ? "Storybook" : "Ladle"} detected — v1 renders via the generated ` +
+            `Vite harness; native story capture is deferred (#357 follow-up).`);
+    }
+    const base = (blocker) => ({
+        engine: blocker ? "unsupported" : "vite-harness",
+        componentName,
+        reactMajor,
+        storybook,
+        ladle,
+        warnings,
+        ...(blocker ? { blocker } : {}),
+    });
+    if (!COMPONENT_EXT_RE.test(componentAbsPath)) {
+        return base({
+            code: "not-a-component-file",
+            message: `df mode preview targets a React component file (.tsx/.jsx). "${basename(componentAbsPath)}" ` +
+                `is not one. Point at the component's .tsx/.jsx source.`,
+        });
+    }
+    const react = parseReactMajor(packageDeps);
+    if (react === null) {
+        return base({
+            code: "no-react",
+            message: "No `react` dependency found in this repo's package.json. v1 previews React " +
+                "components only (Vue/Svelte/Angular are deferred — see #357). Install react, or " +
+                "use your framework's own component sandbox.",
+        });
+    }
+    const hasVite = !!packageDeps && ("vite" in packageDeps || "@vitejs/plugin-react" in packageDeps);
+    if (!hasVite) {
+        return base({
+            code: "no-vite",
+            message: "No `vite` / `@vitejs/plugin-react` found. v1's generated harness transforms the " +
+                "component with Vite (the common React/Vite/Next-client case). Webpack/CRA transform " +
+                "is deferred (#357). Add vite + @vitejs/plugin-react as devDependencies, or add a " +
+                "Storybook/Ladle setup.",
+        });
+    }
+    if (looksLikeServerComponent(source)) {
+        return base({
+            code: "server-component",
+            message: "This looks like a React Server Component (no `\"use client\"`, and an async/server-only " +
+                "component). It cannot mount in a client-only harness. Add `\"use client\"` if it is " +
+                "actually a client component, or preview a client component it renders. RSC capture is " +
+                "deferred (#357).",
+        });
+    }
+    const exp = resolveExport(source, componentName);
+    if (exp.kind === "none") {
+        return base({
+            code: "no-export",
+            message: `No exported component found in ${basename(componentAbsPath)}. v1 mounts the default export, ` +
+                `a named export matching the filename, or the first PascalCase named export.`,
+        });
+    }
+    const result = base();
+    if (exp.kind === "named")
+        result.exportName = exp.name;
+    return result;
+}
+/** Thrown by a `CaptureDeps.capture` when the browser cannot be resolved/launched
+ *  (Playwright not installed, Chromium binary absent, missing system deps). This
+ *  is the ONLY capture failure that degrades softly (exit 2, "reached the capture
+ *  step") — a Vite transform error, a component runtime exception, missing props,
+ *  or an `fs.allow`-blocked import is a REAL failure and surfaces loudly (exit 1). */
+export class BrowserUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BrowserUnavailableError";
+    }
+}
+/** Secondary heuristic (belt-and-suspenders alongside `BrowserUnavailableError`):
+ *  recognize a genuine missing-browser / launch / install failure from its message
+ *  so a raw Playwright error is still classified as degrade-soft, while a render or
+ *  transform error is NOT. Kept deliberately narrow. */
+export function isBrowserUnavailable(err) {
+    if (err instanceof BrowserUnavailableError)
+        return true;
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (/executable doesn'?t exist/.test(msg) ||
+        /playwright install/.test(msg) ||
+        /host system is missing dependencies/.test(msg) ||
+        /missing dependencies to run browser/.test(msg) ||
+        /cannot resolve "(playwright|@playwright\/test)"/.test(msg) ||
+        /looks like playwright.* was just installed/.test(msg));
+}
+function sanitizeSlug(raw) {
+    const s = raw
+        .replace(COMPONENT_EXT_RE, "")
+        .replace(/[^a-z0-9-]+/gi, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase();
+    return s || "component";
+}
+/**
+ * A safe evidence slug is a SINGLE path segment: filesystem-safe chars only, and
+ * never `.` / `..` / anything with a separator. The slug is interpolated into the
+ * evidence path (`agent-reviews/quality-gates/ui/<sha>/<slug>/…`), so an operator
+ * `--slug ../../..` would otherwise traverse OUT of the evidence tree and clobber
+ * arbitrary files. The auto-derived slug is already safe (`sanitizeSlug`); this
+ * fail-closes an explicit `--slug`. Exported for the traversal regression test.
+ */
+export function isSafeSlug(slug) {
+    if (slug === "" || slug === "." || slug === "..")
+        return false;
+    if (slug.includes("/") || slug.includes("\\"))
+        return false;
+    return /^[A-Za-z0-9._-]+$/.test(slug);
+}
+function mergedDeps(pkg) {
+    if (!pkg)
+        return null;
+    const out = {};
+    for (const key of ["dependencies", "devDependencies", "peerDependencies"]) {
+        const block = pkg[key];
+        if (block && typeof block === "object") {
+            for (const [k, v] of Object.entries(block)) {
+                if (typeof v === "string")
+                    out[k] = v;
+            }
+        }
+    }
+    return out;
+}
+function readPackageDeps(cwd) {
+    const p = join(cwd, "package.json");
+    if (!existsSync(p))
+        return null;
+    try {
+        return mergedDeps(JSON.parse(readFileSync(p, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Render one component in isolation and write `ui-visual`-shaped evidence.
+ * Never throws for an expected failure — returns a `degraded`/`error` result
+ * with an actionable message and the right exit code.
+ */
+export async function runPreview(opts, deps) {
+    const { cwd } = opts;
+    const port = opts.port ?? 5199;
+    const componentAbsPath = isAbsolute(opts.componentPath)
+        ? opts.componentPath
+        : resolve(cwd, opts.componentPath);
+    const relForLog = relative(cwd, componentAbsPath).split(sep).join("/") || opts.componentPath;
+    const slug = opts.slug ?? sanitizeSlug(basename(componentAbsPath));
+    // Fail closed on an unsafe slug BEFORE it is interpolated into any path — an
+    // explicit `--slug ../../..` must not traverse out of the evidence tree.
+    if (!isSafeSlug(slug)) {
+        return {
+            status: "error",
+            exitCode: 1,
+            slug,
+            warnings: [],
+            message: `df mode preview: invalid --slug "${slug}". A slug must be a single path ` +
+                `segment matching [A-Za-z0-9._-] (no "/", "\\", "." or ".."). No evidence written.`,
+        };
+    }
+    if (!existsSync(componentAbsPath)) {
+        return {
+            status: "error",
+            exitCode: 1,
+            slug,
+            warnings: [],
+            message: `df mode preview: component not found: ${opts.componentPath}`,
+        };
+    }
+    const source = readFileSync(componentAbsPath, "utf8");
+    // Resolve the frontend workspace (#379): the module/config base is the
+    // workspace that actually holds react/vite/node_modules + the tsconfig path
+    // aliases — often a `web/` subdir — NOT the invocation cwd (the repo root,
+    // where the designer works and darkfactory.yaml lives). When no react is found
+    // anywhere, fall back to cwd so detectStrategy emits the existing honest
+    // no-react blocker. The invocation cwd stays the base for evidence, the SHA,
+    // and the component's display path.
+    const workspace = resolveFrontendWorkspace(cwd);
+    const workspaceDir = workspace?.workspaceDir ?? cwd;
+    // Note the shift only when it actually moved off the repo root, so the designer
+    // sees "resolved frontend workspace: web/" but a root-frontend repo stays quiet.
+    const workspaceNote = workspace && workspace.workspaceDir !== cwd
+        ? `resolved frontend workspace: ${workspace.relLabel}/ (module + config base for this preview)`
+        : undefined;
+    const detect = detectStrategy({
+        cwd: workspaceDir,
+        componentAbsPath,
+        source,
+        packageDeps: readPackageDeps(workspaceDir),
+    });
+    const baseWarnings = workspaceNote ? [workspaceNote, ...detect.warnings] : detect.warnings;
+    if (detect.blocker) {
+        return {
+            status: "degraded",
+            exitCode: 2,
+            slug,
+            warnings: baseWarnings,
+            message: `df mode preview: cannot render ${relForLog} — ${detect.blocker.message}`,
+        };
+    }
+    const sha = await resolveHeadOrWorktree(cwd);
+    // Read the workspace tsconfig `paths` → Vite alias; any unsupported-glob key is
+    // surfaced (not silently mis-resolved) via the operator notes channel.
+    const { alias, warnings: aliasWarnings } = readAliasEntries(workspaceDir);
+    const warnings = aliasWarnings.length > 0 ? [...baseWarnings, ...aliasWarnings] : baseWarnings;
+    // The harness dir lives INSIDE the resolved workspace so the entry's bare
+    // imports (`react`, `react-dom/client`) and the component's relative imports
+    // resolve up into the workspace's node_modules — identical to running from the
+    // workspace dir. Evidence still lands at the repo root (writeEvidence uses cwd).
+    const harnessDir = mkdtempSync(join(workspaceDir, ".df-preview-"));
+    let server;
+    try {
+        for (const f of generateHarness({
+            componentAbsPath,
+            harnessDir,
+            componentName: detect.componentName,
+            reactMajor: detect.reactMajor,
+            ...(detect.exportName !== undefined ? { exportName: detect.exportName } : {}),
+        })) {
+            writeFileSync(join(harnessDir, f.path), f.contents, "utf8");
+        }
+        try {
+            server = await deps.startServer({ workspaceDir, harnessDir, port, alias });
+        }
+        catch (err) {
+            return {
+                status: "degraded",
+                exitCode: 2,
+                slug,
+                warnings,
+                message: `df mode preview: reached harness build but could NOT start the isolated Vite dev ` +
+                    `server for ${relForLog} (${errMsg(err)}). Ensure \`vite\` + \`@vitejs/plugin-react\` ` +
+                    `are installed in the frontend workspace. No evidence written.`,
+            };
+        }
+        let captured;
+        try {
+            captured = await deps.capture({ url: server.url, workspaceDir });
+        }
+        catch (err) {
+            // Distinguish a genuinely-unavailable browser (soft-degrade — the render
+            // itself was fine, only the screenshot couldn't be taken HERE) from a REAL
+            // failure: a Vite transform error, a component runtime exception, missing
+            // required props, or a component import blocked by Vite `fs.allow`. The
+            // latter must surface LOUDLY (exit 1) — reporting it as "degraded
+            // gracefully" would hide a broken component behind a false soft-skip.
+            if (isBrowserUnavailable(err)) {
+                return {
+                    status: "degraded",
+                    exitCode: 2,
+                    slug,
+                    warnings,
+                    message: `df mode preview: reached the capture step for ${relForLog} but the browser is ` +
+                        `unavailable (${errMsg(err)}). Install it with \`npx playwright install chromium\` ` +
+                        `(and \`npm i -D playwright\` if absent). The isolated render succeeded; only the ` +
+                        `screenshot could not be taken here. No evidence written.`,
+                };
+            }
+            return {
+                status: "error",
+                exitCode: 1,
+                slug,
+                warnings,
+                message: `df mode preview: the isolated render of ${relForLog} FAILED (${errMsg(err)}). This is ` +
+                    `NOT a missing-browser problem — it is typically a Vite transform error, a component ` +
+                    `runtime exception, missing required props, or an import outside the repo (Vite ` +
+                    `fs.allow). Fix the component or provide props, then re-run. No evidence written.`,
+            };
+        }
+        const evidenceDir = writeEvidence({
+            cwd,
+            sha,
+            slug,
+            componentRel: relForLog,
+            componentName: detect.componentName,
+            baseURL: server.url,
+            aria: captured.aria,
+            png: captured.png,
+            // Persist the FULL merged notes (workspace-resolution + any unsupported
+            // path-alias keys), not just render advisories, so the evidence records
+            // why an alias may not have wired — not only stdout.
+            warnings,
+        });
+        return {
+            status: "captured",
+            exitCode: 0,
+            slug,
+            warnings,
+            evidenceDir,
+            message: `df mode preview: captured isolated render of ${relForLog} → ${relative(cwd, evidenceDir)}/` +
+                ` (after.png + aria.snapshot.txt + meta.json, evidenceKind=playwright).`,
+        };
+    }
+    finally {
+        if (server) {
+            try {
+                await server.close();
+            }
+            catch {
+                /* best-effort teardown */
+            }
+        }
+        rmSync(harnessDir, { recursive: true, force: true });
+    }
+}
+async function resolveHeadOrWorktree(cwd) {
+    try {
+        return await resolveCommit("HEAD", cwd);
+    }
+    catch {
+        // No commit yet (fresh repo) — evidence is still useful for the designer loop.
+        return "working-tree";
+    }
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Write the exact `ui-visual` evidence shape so the existing embed/publish path
+ *  (`discoverUiEvidence` / `buildScreenshotEmbed` / `readUiArtifacts`) consumes
+ *  it unchanged. Returns the absolute evidence dir. */
+function writeEvidence(input) {
+    const dir = join(input.cwd, "agent-reviews", "quality-gates", "ui", input.sha, input.slug);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "after.png"), input.png);
+    writeFileSync(join(dir, "aria.snapshot.txt"), `${input.aria.trim()}\n`, "utf8");
+    const meta = {
+        surface: input.slug,
+        // `path` is the embed's human title (buildScreenshotEmbed reads meta.path).
+        path: `component:${input.componentRel}`,
+        covers: input.componentRel,
+        sha: input.sha,
+        capturedAt: new Date().toISOString(),
+        baseURL: input.baseURL,
+        beforeBaseURL: null,
+        ariaSnapshotBytes: Buffer.byteLength(input.aria, "utf8"),
+        // Keep the same evidenceKind/route as the ui-visual producer so publish.ts
+        // uploads the file artifacts and the embed renders them identically.
+        evidenceKind: "playwright",
+        route: "ui-visual",
+        floor: ["aria-snapshot", "after-screenshot"],
+        beforeScreenshot: null,
+        // HONESTY marker: this is an isolated component render, not a navigated route.
+        capture: "component-isolation",
+        componentName: input.componentName,
+        engine: "vite-harness",
+        warnings: input.warnings,
+    };
+    writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+    return dir;
+}
+//# sourceMappingURL=preview.js.map