@elytracms/cli 0.0.69 → 0.0.71

package/README.md

@@ -29,7 +29,26 @@ elytra doctor   Diagnose the active deployment's readiness and print each fix.
                 by NAME only — values are never read into the report or printed.
                 When the publish revalidate pair is set, also sends a signed
                 no-op ping to the endpoint to prove the publish → live chain
-                end to end. Read-only; exits non-zero if any check fails.
+                end to end. Also reports the generated-previews artifacts
+                (manifest present, image files present, no strays — warnings
+                only; previews are optional). Read-only; exits non-zero if any
+                check fails.
+
+elytra previews Render every canvas-eligible component's fixtures against your
+                theme and write committed insert-menu preview artifacts:
+                640×400 WebP images in studio/public/elytra-previews/ plus an
+                importable studio/elytra-previews.json manifest (per-entry
+                input hashes — re-running with unchanged inputs rewrites
+                nothing; removed components' images are pruned). Wire it with
+                `generatedPreviewsFromManifest` from
+                `@elytracms/studio/customization` (two lines — see the docs).
+                Rendering needs Playwright once (optional, on demand):
+                  pnpm add -D playwright && pnpm exec playwright install chromium
+                Options:
+                  --check     verify the input hashes without rendering (no
+                              Playwright needed); exits non-zero when previews
+                              are missing/stale/orphaned. Wire into CI/builds.
+                  --port <n>  harness dev-server port (default: first free 5440+)
 
 elytra help     Show help
 elytra version  Show version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.69",
+  "version": "0.0.71",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.69"
+    "@elytracms/core": "^0.0.71"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { join } from 'node:path'
 import { stdout } from 'node:process'
 import { runDoctor } from './doctor.js'
+import { runPreviews } from './previews.js'
 import { inspectProject, resolveStudioEnv } from './project.js'
 import { ensureAuthKeys } from './provision.js'
 import { runGroup, runSequential } from './run.js'
@@ -27,8 +28,18 @@ Commands:
              signing keys, expected deployment env vars — set/missing by NAME,
              values never shown — config, membership) and print each fix. When the
              instant-publish revalidate pair is set, also sends a signed no-op ping
-             to the endpoint to prove the publish → live chain end to end. Exit
-             non-zero if any check fails. Read-only. Optional: --url <convex url>.
+             to the endpoint to prove the publish → live chain end to end. Also
+             reports the generated-previews artifacts (manifest/files present;
+             hash staleness lives in \`elytra previews --check\`). Exit non-zero
+             if any check fails. Read-only. Optional: --url <convex url>.
+  previews   Render every canvas-eligible component's fixtures against YOUR theme
+             (headless Chromium via Playwright — an optional install) and write
+             committed preview images (studio/public/elytra-previews/) plus an
+             importable manifest (studio/elytra-previews.json) for the insert
+             menu. Re-running with unchanged inputs rewrites nothing.
+             Options: --check   verify freshness (input hashes) without rendering,
+                                exit non-zero when previews are missing/stale;
+                      --port <n> harness dev-server port (default: first free 5440+).
   help       Show this help
   version    Show version
 
@@ -342,6 +353,25 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
     return runInit(project, { log: emit, fetchImpl, exec })
   }
 
+  // `elytra previews [--check] [--port <n>]` (EC-440): build-time fixture-preview
+  // generation through the studio app's own Vite + on-demand Playwright.
+  if (command === 'previews') {
+    const project = inspectProject(cwd, env)
+    if (project.issues.length > 0) {
+      reportIssues(project.issues)
+      return 1
+    }
+    if (!project.apps.studio) {
+      log('No studio/ app found — `elytra previews` renders through the studio app’s Vite.')
+      return 1
+    }
+    return runPreviews(project, {
+      check: argv.includes('--check'),
+      port: flagValue(argv, '--port'),
+      log: emit,
+    })
+  }
+
   if (command !== 'dev' && command !== 'build') {
     log(`Unknown command: ${command}\n`)
     log(HELP)

package/src/doctor.js

@@ -8,6 +8,7 @@ import {
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
 import { convexEnvGet, defaultConvexExec } from './provision.js'
+import { gatherPreviewsArtifacts, previewsDoctorChecks } from './previews.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -232,6 +233,7 @@ const BUCKET_TITLE = {
   'deployment-env': 'Deployment env',
   app: 'App',
   user: 'Per-user',
+  previews: 'Previews',
 }
 
 /**
@@ -275,6 +277,13 @@ export function formatReport(report) {
  * studio dir the env checks stay honest `unknown`s. Playground stays untouched — no
  * deployment, no env bucket. When the instant-publish revalidate pair is present, a
  * signed no-op ping proves the publish → live chain end to end (EC-421, default-on).
+ *
+ * EC-440: when a studio dir is known, a `previews` bucket reports the generated
+ * fixture-preview artifacts — the cheap honest file checks a bundler-less CLI can
+ * make (manifest present + parses, every entry's image present, no strays). All
+ * findings there are warnings (previews are optional); input-hash STALENESS needs
+ * the component registry and lives in `elytra previews --check` (the ratified
+ * split). `previewsArtifacts` is injectable for tests.
  */
 export async function runDoctor({
   env = {},
@@ -284,6 +293,7 @@ export async function runDoctor({
   studioDir,
   aiRouteConfigured = false,
   exec,
+  previewsArtifacts,
 } = {}) {
   const target = resolveDoctorTarget(env, { url })
 
@@ -312,6 +322,15 @@ export async function runDoctor({
     if (revalidateProbe) facts.revalidateProbe = revalidateProbe
   }
   const report = checkDeploymentReady(facts)
-  log(formatReport(report))
+
+  // EC-440: the previews bucket (repo artifacts, backend-independent). Appended to
+  // the shared report before formatting so it wears the same glyph/fix conventions;
+  // its checks are ok/warn/unknown only, so `report.ok` (the exit code) is unchanged.
+  const artifacts = previewsArtifacts ?? (studioDir ? gatherPreviewsArtifacts(studioDir) : undefined)
+  const merged = artifacts
+    ? { ...report, checks: [...report.checks, ...previewsDoctorChecks(artifacts)] }
+    : report
+
+  log(formatReport(merged))
   return report.ok ? 0 : 1
 }

package/src/previews.js

@@ -0,0 +1,715 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { createServer as createNetServer } from 'node:net'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * `elytra previews` (EC-440) — build-time fixture-preview generation.
+ *
+ * Renders every canvas-eligible component's fixtures (each declared fixture;
+ * fixture-less components once as `Default`) against the CONSUMER theme — the
+ * same standalone Tailwind entry the canvas iframe and delivery load (EC-414)
+ * — and writes:
+ *
+ *   - images to `studio/public/elytra-previews/` (served at
+ *     `/elytra-previews/...`), deterministically named
+ *     `<componentId>__<fixture>.webp` (PNG fallback), 640×400 (16/10 — @2x of
+ *     the blocks-panel tile);
+ *   - a previews manifest to `studio/elytra-previews.json` (importable next to
+ *     `studio.config.tsx`) carrying per entry: componentId, fixture, URL, and
+ *     an input hash (manifest prop/slot shape + fixture props + engine
+ *     version) — no timestamps, so unchanged inputs re-serialize to the same
+ *     bytes.
+ *
+ * Idempotence: an entry whose input hash matches the existing manifest AND
+ * whose image file exists is skipped entirely (screenshots are not guaranteed
+ * byte-stable, so "skip unchanged" is the mechanism, not re-render-and-
+ * compare); the manifest is only written when its bytes change. A re-run with
+ * unchanged inputs therefore rewrites nothing.
+ *
+ * Harness: the CLI boots the consumer studio app's own Vite PROGRAMMATICALLY
+ * (resolved from the studio dir; a minimal inline config — the studio's
+ * `vite.config.ts`, with its app plugins/env, is deliberately NOT loaded) and
+ * serves a DATA-FREE render page that imports exactly the consumer registry
+ * (`elytra.config.ts`) and the consumer theme. Enumeration + hashing run
+ * node-side through the same Vite (`ssrLoadModule`), so `--check` needs no
+ * browser; rendering drives headless Chromium via Playwright — an ON-DEMAND
+ * dependency (dynamic import + install instructions), never a hard dep of
+ * `@elytracms/cli`.
+ *
+ * Staleness split (the ratified EC-440 design): `elytra previews --check`
+ * owns full input-hash staleness (it has the registry); `elytra doctor`'s
+ * previews bucket does the cheap honest file checks (manifest present/parses,
+ * every entry's image present, no orphans) — see {@link previewsDoctorChecks}.
+ */
+
+// --- Conventions ---------------------------------------------------------------
+
+/** Where the images live inside the studio app (served at `/elytra-previews/...`). */
+export const PREVIEWS_DIR = join('public', 'elytra-previews')
+/** The manifest file, next to `studio.config.tsx` so it imports as `./elytra-previews.json`. */
+export const PREVIEWS_MANIFEST_FILE = 'elytra-previews.json'
+/** Root-relative URL prefix the manifest entries carry. */
+export const PREVIEWS_URL_PREFIX = '/elytra-previews/'
+/** Manifest format version (mirrors `@elytracms/studio`'s PREVIEWS_MANIFEST_VERSION). */
+export const PREVIEWS_MANIFEST_VERSION = 1
+
+/** Capture geometry: 1280×800 CSS pixels (a desktop render), shot at 0.5 → 640×400 (16/10). */
+export const CAPTURE = { width: 1280, height: 800, scale: 0.5 }
+/** WebP quality — modest; typical fixture renders land well under 100 KB. */
+export const WEBP_QUALITY = 80
+/** Per-fixture budget: a render that hasn't settled in 30s fails that entry. */
+export const RENDER_TIMEOUT_MS = 30_000
+
+const HARNESS_PATH = '/__elytra-previews__/'
+const ENTRY_ID = 'virtual:elytra-previews-entry'
+const ENUMERATE_ID = 'virtual:elytra-previews-enumerate'
+
+// --- Pure helpers ----------------------------------------------------------------
+
+/**
+ * Deterministic, filename-safe slug for a component id / fixture name.
+ * Path-hostile characters become `-`; whenever the cleaned form differs from
+ * the raw name (or overflows the length cap) an 8-hex sha-256 suffix of the
+ * RAW name keeps distinct names distinct ("Startseite v2" vs "Startseite-v2").
+ */
+export function sanitizePreviewSlug(raw) {
+  const MAX = 60
+  const cleaned = String(raw).replace(/[^A-Za-z0-9._-]/g, '-')
+  if (cleaned === raw && raw.length > 0 && raw.length <= MAX) return raw
+  const suffix = createHash('sha256').update(String(raw), 'utf8').digest('hex').slice(0, 8)
+  const base = cleaned.slice(0, MAX)
+  return `${base.length > 0 ? base : 'x'}-${suffix}`
+}
+
+/** The deterministic image filename for an entry: `<componentId>__<fixture>.<ext>`. */
+export function previewFileName(componentId, fixture, ext) {
+  return `${sanitizePreviewSlug(componentId)}__${sanitizePreviewSlug(fixture)}.${ext}`
+}
+
+/** JSON.stringify with recursively sorted object keys — stable across runs. */
+export function stableStringify(value) {
+  return JSON.stringify(sortValue(value))
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue)
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const key of Object.keys(value).sort()) out[key] = sortValue(value[key])
+    return out
+  }
+  return value
+}
+
+/**
+ * The staleness input hash: sha-256 over the stable-serialized render inputs —
+ * the manifest's prop/slot shape + the fixture's own props/slotChildren (from
+ * the studio's `previewEntriesForConfig`) + the installed engine version.
+ * Implementation and theme drift are deliberately NOT hashed (the ratified
+ * split: those are caught by regeneration runs, e.g. in the consumer's build).
+ */
+export function previewEntryHash(hashInput, engineVersion) {
+  return createHash('sha256')
+    .update(stableStringify({ engine: engineVersion, input: hashInput }), 'utf8')
+    .digest('hex')
+}
+
+/** Serialize the previews manifest deterministically (sorted entry keys, LF, trailing newline). */
+export function serializePreviewsManifest({ engine, entries }) {
+  const doc = {
+    version: PREVIEWS_MANIFEST_VERSION,
+    engine,
+    entries: entries.map((e) => ({
+      componentId: e.componentId,
+      fixture: e.fixture,
+      url: e.url,
+      hash: e.hash,
+    })),
+  }
+  return `${JSON.stringify(doc, null, 2)}\n`
+}
+
+/** Parse a previews manifest; `null` when missing/unparsable/mis-shaped (tolerant). */
+export function parsePreviewsManifest(text) {
+  if (typeof text !== 'string') return null
+  try {
+    const doc = JSON.parse(text)
+    if (typeof doc !== 'object' || doc === null || !Array.isArray(doc.entries)) return null
+    return doc
+  } catch {
+    return null
+  }
+}
+
+const key = (e) => `${e.componentId}\u0000${e.fixture}`
+const fileOfUrl = (url) => (typeof url === 'string' ? url.split('/').pop() : undefined)
+
+/**
+ * Decide which entries need rendering. `specs` carry a computed `hash`;
+ * an entry is FRESH (skipped) when the existing manifest has the same hash for
+ * it and the image file it names is present. Fresh entries keep their existing
+ * URL verbatim (a prior PNG-fallback file stays a PNG until its inputs change).
+ */
+export function planPreviewRun({ specs, existing, files }) {
+  const priorByKey = new Map((existing?.entries ?? []).map((e) => [key(e), e]))
+  return specs.map((spec) => {
+    const prior = priorByKey.get(key(spec))
+    const priorFile = prior ? fileOfUrl(prior.url) : undefined
+    const fresh = Boolean(prior && prior.hash === spec.hash && priorFile && files.includes(priorFile))
+    return fresh ? { ...spec, fresh: true, url: prior.url } : { ...spec, fresh: false }
+  })
+}
+
+/**
+ * `--check` verdicts: compare the enumerated entry set (+ fresh hashes)
+ * against the committed manifest + image files. Every problem names its
+ * entry; an empty list is green.
+ */
+export function checkPreviews({ specs, manifest, files }) {
+  const problems = []
+  if (!manifest) {
+    for (const spec of specs) {
+      problems.push({ kind: 'missing', componentId: spec.componentId, fixture: spec.fixture })
+    }
+    return { ok: specs.length === 0, problems }
+  }
+  const entryByKey = new Map(manifest.entries.map((e) => [key(e), e]))
+  const specKeys = new Set(specs.map((s) => key(s)))
+
+  for (const spec of specs) {
+    const entry = entryByKey.get(key(spec))
+    if (!entry) {
+      problems.push({ kind: 'missing', componentId: spec.componentId, fixture: spec.fixture })
+      continue
+    }
+    const file = fileOfUrl(entry.url)
+    if (entry.hash !== spec.hash) {
+      problems.push({ kind: 'stale', componentId: spec.componentId, fixture: spec.fixture })
+    } else if (!file || !files.includes(file)) {
+      problems.push({ kind: 'missing-file', componentId: spec.componentId, fixture: spec.fixture, file })
+    }
+  }
+  for (const entry of manifest.entries) {
+    if (!specKeys.has(key(entry))) {
+      problems.push({ kind: 'orphan-entry', componentId: entry.componentId, fixture: entry.fixture })
+    }
+  }
+  // A file is stray when NO manifest entry references it at all.
+  for (const file of files) {
+    if (!manifest.entries.some((e) => fileOfUrl(e.url) === file)) {
+      problems.push({ kind: 'orphan-file', file })
+    }
+  }
+  return { ok: problems.length === 0, problems }
+}
+
+/** One line per problem, stable order, for `--check` output. */
+export function formatCheckProblems(problems) {
+  const label = {
+    missing: 'missing   ',
+    stale: 'stale     ',
+    'missing-file': 'file gone ',
+    'orphan-entry': 'orphaned  ',
+    'orphan-file': 'stray file',
+  }
+  return problems.map((p) =>
+    p.kind === 'orphan-file'
+      ? `  ✗ ${label[p.kind]} ${p.file}`
+      : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`,
+  )
+}
+
+// --- Doctor bucket (cheap, honest, registry-free) ---------------------------------
+
+/**
+ * Gather the previews artifacts a plain-node doctor can see: the manifest file
+ * and the images directory. No config execution, no registry — those checks
+ * live in `elytra previews --check`.
+ */
+export function gatherPreviewsArtifacts(studioDir) {
+  const manifestPath = join(studioDir, PREVIEWS_MANIFEST_FILE)
+  const imagesDir = join(studioDir, PREVIEWS_DIR)
+  const manifestExists = existsSync(manifestPath)
+  const dirExists = existsSync(imagesDir)
+  return {
+    manifestExists,
+    manifestText: manifestExists ? readFileSync(manifestPath, 'utf8') : undefined,
+    dirExists,
+    files: dirExists ? readdirSync(imagesDir).filter((f) => !f.startsWith('.')) : [],
+  }
+}
+
+/**
+ * The doctor's `previews` bucket (EC-440): the cheap honest file checks a
+ * bundler-less CLI can make. Previews are OPTIONAL — every finding here is a
+ * `warn` (named + remediated, never fails the exit code, the EC-399
+ * convention); full input-hash staleness is `elytra previews --check`'s job
+ * and is pointed to with an honest `unknown`.
+ */
+export function previewsDoctorChecks(artifacts) {
+  const { manifestExists, manifestText, dirExists, files } = artifacts
+  const rerun = 'Run `elytra previews` to (re)generate the fixture preview images.'
+
+  if (!manifestExists && !dirExists) {
+    return [
+      {
+        id: 'previews-artifacts',
+        bucket: 'previews',
+        status: 'ok',
+        detail: 'No generated previews (optional — `elytra previews` renders fixture preview images).',
+      },
+    ]
+  }
+
+  const checks = []
+  if (!manifestExists) {
+    checks.push({
+      id: 'previews-manifest',
+      bucket: 'previews',
+      status: 'warn',
+      detail: `${files.length} preview image(s) exist but studio/${PREVIEWS_MANIFEST_FILE} is missing.`,
+      fix: rerun,
+    })
+    return checks
+  }
+
+  const manifest = parsePreviewsManifest(manifestText)
+  if (!manifest) {
+    checks.push({
+      id: 'previews-manifest',
+      bucket: 'previews',
+      status: 'warn',
+      detail: `studio/${PREVIEWS_MANIFEST_FILE} exists but is not a valid previews manifest.`,
+      fix: rerun,
+    })
+    return checks
+  }
+
+  const missingFiles = manifest.entries.filter((e) => {
+    const file = fileOfUrl(e.url)
+    return !file || !files.includes(file)
+  })
+  if (missingFiles.length > 0) {
+    checks.push({
+      id: 'previews-files',
+      bucket: 'previews',
+      status: 'warn',
+      detail: `${missingFiles.length} of ${manifest.entries.length} manifest entr${manifest.entries.length === 1 ? 'y' : 'ies'} name image files that are missing (first: ${fileOfUrl(missingFiles[0].url) ?? '?'}).`,
+      fix: rerun,
+    })
+  } else {
+    checks.push({
+      id: 'previews-files',
+      bucket: 'previews',
+      status: 'ok',
+      detail: `${manifest.entries.length} generated preview(s), every image file present.`,
+    })
+  }
+
+  const referenced = new Set(manifest.entries.map((e) => fileOfUrl(e.url)))
+  const orphans = files.filter((f) => !referenced.has(f))
+  if (orphans.length > 0) {
+    checks.push({
+      id: 'previews-orphans',
+      bucket: 'previews',
+      status: 'warn',
+      detail: `${orphans.length} image file(s) are not referenced by the manifest (first: ${orphans[0]}).`,
+      fix: rerun,
+    })
+  }
+
+  checks.push({
+    id: 'previews-staleness',
+    bucket: 'previews',
+    status: 'unknown',
+    detail: 'Input-hash staleness needs the component registry — run `elytra previews --check`.',
+  })
+  return checks
+}
+
+// --- Impure plumbing ---------------------------------------------------------------
+
+/** Resolve a module specifier from a directory's own node_modules world. */
+function resolveFromDir(dir, specifier) {
+  return createRequire(join(dir, 'package.json')).resolve(specifier)
+}
+
+/**
+ * The engine version for the input hash — read from the `@elytracms/studio`
+ * (fallback `@elytracms/core`) package the CONSUMER has installed, never
+ * hardcoded. Direct node_modules paths (pnpm keeps symlinks for direct deps).
+ */
+export function resolveEngineVersion(root) {
+  const bases = [join(root, 'studio'), root]
+  for (const pkg of ['@elytracms/studio', '@elytracms/core']) {
+    for (const base of bases) {
+      const path = join(base, 'node_modules', ...pkg.split('/'), 'package.json')
+      if (!existsSync(path)) continue
+      try {
+        const version = JSON.parse(readFileSync(path, 'utf8')).version
+        if (typeof version === 'string' && version.length > 0) return version
+      } catch {
+        // fall through to the next candidate
+      }
+    }
+  }
+  return 'unknown'
+}
+
+/**
+ * The consumer theme entry the harness page imports: the studio's canvas
+ * stylesheet (`studio/src/styles/canvas.css` — the EC-414 shape: the site
+ * theme plus any engine-required `@source` lines) when present, else the
+ * shared theme entry itself (`components/theme.css`). `null` → no theme, the
+ * command refuses (an unstyled preview would be a lying artifact).
+ */
+export function themeStylesheetPath(root) {
+  for (const candidate of [
+    join(root, 'studio', 'src', 'styles', 'canvas.css'),
+    join(root, 'components', 'theme.css'),
+  ]) {
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+const HARNESS_HTML = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Elytra previews harness</title>
+  </head>
+  <body>
+    <script type="module" src="/@id/${ENTRY_ID}"></script>
+  </body>
+</html>
+`
+
+/**
+ * The inline Vite plugin serving the DATA-FREE harness: two virtual modules
+ * (the browser render entry; the node-side enumeration) that import exactly
+ * the consumer config + theme + the studio previews modules — no studio app
+ * code, no persistence, no auth, no env.
+ */
+function harnessPlugin({ configPath, themePath }) {
+  const configImport = `/@fs/${configPath}`
+  const themeImport = `/@fs/${themePath}`
+  return {
+    name: 'elytra-previews-harness',
+    resolveId(id) {
+      return id === ENTRY_ID || id === ENUMERATE_ID ? id : null
+    },
+    load(id) {
+      if (id === ENTRY_ID) {
+        return [
+          `import '${themeImport}'`,
+          `import config from '${configImport}'`,
+          `import { mountPreviewHarness } from '@elytracms/studio/previews/harness'`,
+          `mountPreviewHarness(config)`,
+        ].join('\n')
+      }
+      if (id === ENUMERATE_ID) {
+        return [
+          `import config from '${configImport}'`,
+          `import { previewEntriesForConfig } from '@elytracms/studio/previews/enumerate'`,
+          `export const entries = previewEntriesForConfig(config)`,
+        ].join('\n')
+      }
+      return null
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if (!req.url || req.url.split('?')[0] !== HARNESS_PATH) return next()
+        server
+          .transformIndexHtml(req.url, HARNESS_HTML)
+          .then((html) => {
+            res.setHeader('content-type', 'text/html')
+            res.end(html)
+          })
+          .catch(next)
+      })
+    },
+  }
+}
+
+/** First free port in [start, start+span) — never a hardcoded single port. */
+async function pickPort(start = 5440, span = 30) {
+  for (let port = start; port < start + span; port += 1) {
+    const free = await new Promise((resolve) => {
+      const probe = createNetServer()
+      probe.once('error', () => resolve(false))
+      probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)))
+    })
+    if (free) return port
+  }
+  throw new Error(`No free port in ${start}–${start + span - 1}.`)
+}
+
+/** Boot the consumer studio's Vite with the minimal inline harness config. */
+async function startHarnessServer({ root, studioDir, port }) {
+  const vite = await import(pathToFileURL(resolveFromDir(studioDir, 'vite')).href)
+  const tailwindEntry = resolveFromDir(studioDir, '@tailwindcss/vite')
+  const tailwind = (await import(pathToFileURL(tailwindEntry).href)).default
+
+  const configPath = join(root, 'elytra.config.ts')
+  const themePath = themeStylesheetPath(root)
+  if (!themePath) {
+    throw new Error(
+      'No theme stylesheet found (looked for studio/src/styles/canvas.css and components/theme.css) — ' +
+        'previews must render against the consumer theme.',
+    )
+  }
+
+  const server = await vite.createServer({
+    configFile: false,
+    root: studioDir,
+    mode: 'development',
+    appType: 'custom',
+    logLevel: 'warn',
+    plugins: [tailwind(), harnessPlugin({ configPath, themePath })],
+    server: {
+      port,
+      strictPort: true,
+      host: '127.0.0.1',
+      fs: { allow: [vite.searchForWorkspaceRoot(studioDir), root] },
+    },
+    esbuild: { jsx: 'automatic' },
+  })
+  await server.listen()
+  return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}` }
+}
+
+const PLAYWRIGHT_INSTALL_HELP = [
+  '`elytra previews` renders fixtures in a headless browser via Playwright, which is an',
+  'optional, on-demand dependency (never installed with the CLI). Install it in your repo:',
+  '',
+  '  pnpm add -D playwright',
+  '  pnpm exec playwright install chromium',
+  '',
+  'then re-run `elytra previews`.',
+].join('\n')
+
+/** Dynamic, on-demand Playwright load from the consumer repo. `null` = not installed. */
+async function loadPlaywright(root) {
+  for (const base of [join(root, 'studio'), root]) {
+    let resolved
+    try {
+      resolved = resolveFromDir(base, 'playwright')
+    } catch {
+      continue
+    }
+    const mod = await import(pathToFileURL(resolved).href)
+    return mod.default ?? mod
+  }
+  return null
+}
+
+/** Wait until the harness page reports ready (surviving dep-optimizer reloads). */
+async function waitForHarness(page) {
+  await page.waitForFunction(() => window.__ELYTRA_PREVIEWS__?.ready === true, undefined, {
+    timeout: 60_000,
+  })
+  // Vite may discover + optimize deps on first load and trigger one full
+  // reload; give it a beat, then re-confirm (the entry re-mounts on reload).
+  await page.waitForTimeout(750)
+  await page.waitForFunction(() => window.__ELYTRA_PREVIEWS__?.ready === true, undefined, {
+    timeout: 60_000,
+  })
+}
+
+/** Render one entry in-page (with the per-fixture budget) and report the outcome. */
+async function renderEntryInPage(page, spec) {
+  const attempt = () =>
+    page.evaluate(
+      ([componentId, fixture, timeout]) =>
+        Promise.race([
+          window.__ELYTRA_PREVIEWS__.render(componentId, fixture),
+          new Promise((resolve) =>
+            setTimeout(() => resolve({ ok: false, error: `render timed out after ${timeout}ms` }), timeout),
+          ),
+        ]),
+      [spec.componentId, spec.fixture, RENDER_TIMEOUT_MS],
+    )
+  try {
+    return await attempt()
+  } catch (error) {
+    // One retry after a mid-run reload (dep optimizer) destroyed the context.
+    if (String(error).includes('Execution context was destroyed')) {
+      await waitForHarness(page)
+      return attempt()
+    }
+    throw error
+  }
+}
+
+/**
+ * Screenshot the settled render: WebP via CDP (Chromium encodes natively;
+ * Playwright's own screenshot() has no WebP), PNG via Playwright as fallback.
+ */
+async function captureViewport(page, cdp) {
+  const clip = { x: 0, y: 0, width: CAPTURE.width, height: CAPTURE.height, scale: CAPTURE.scale }
+  if (cdp) {
+    try {
+      const shot = await cdp.send('Page.captureScreenshot', {
+        format: 'webp',
+        quality: WEBP_QUALITY,
+        clip,
+      })
+      return { buffer: Buffer.from(shot.data, 'base64'), ext: 'webp' }
+    } catch {
+      // fall through to PNG
+    }
+  }
+  const buffer = await page.screenshot({
+    clip: { x: 0, y: 0, width: CAPTURE.width, height: CAPTURE.height },
+    type: 'png',
+  })
+  return { buffer, ext: 'png' }
+}
+
+// --- The command -------------------------------------------------------------------
+
+/**
+ * Run `elytra previews` / `elytra previews --check` for an inspected project.
+ * Returns the process exit code. `log` is injectable; everything else uses the
+ * consumer repo's own toolchain (vite, tailwind, playwright) resolved on
+ * demand.
+ */
+export async function runPreviews(project, { check = false, port, log = (l) => console.log(l) } = {}) {
+  const root = project.root
+  const studioDir = join(root, 'studio')
+  const engine = resolveEngineVersion(root)
+  const manifestPath = join(studioDir, PREVIEWS_MANIFEST_FILE)
+  const imagesDir = join(studioDir, PREVIEWS_DIR)
+
+  log(`Elytra previews — fixture preview ${check ? 'staleness check' : 'generation'}`)
+  log(`Engine version (hash input): ${engine}`)
+
+  const chosenPort = port ? Number(port) : await pickPort()
+  let harness
+  try {
+    harness = await startHarnessServer({ root, studioDir, port: chosenPort })
+  } catch (error) {
+    log(`Could not start the render harness: ${error.message}`)
+    return 1
+  }
+
+  try {
+    // Enumerate + hash node-side through the same Vite (no browser needed).
+    const { entries } = await harness.server.ssrLoadModule(ENUMERATE_ID)
+    const specs = entries.map((entry) => ({
+      componentId: entry.componentId,
+      fixture: entry.fixture,
+      hash: previewEntryHash(entry.hashInput, engine),
+    }))
+    log(`Enumerated ${specs.length} fixture preview(s) from elytra.config.ts.`)
+
+    const artifacts = gatherPreviewsArtifacts(studioDir)
+    const existing = parsePreviewsManifest(artifacts.manifestText)
+
+    if (check) {
+      const { ok, problems } = checkPreviews({ specs, manifest: existing, files: artifacts.files })
+      if (ok) {
+        log(`✓ ${specs.length} preview(s) up to date (hashes match, all files present).`)
+        return 0
+      }
+      log(`✗ ${problems.length} problem(s):`)
+      for (const line of formatCheckProblems(problems)) log(line)
+      log('Run `elytra previews` to regenerate.')
+      return 1
+    }
+
+    const jobs = planPreviewRun({ specs, existing, files: artifacts.files })
+    const toRender = jobs.filter((j) => !j.fresh)
+    log(`${jobs.length - toRender.length} unchanged (skipped), ${toRender.length} to render.`)
+
+    const failures = []
+    if (toRender.length > 0) {
+      const playwright = await loadPlaywright(root)
+      if (!playwright) {
+        log(PLAYWRIGHT_INSTALL_HELP)
+        return 1
+      }
+      let browser
+      try {
+        browser = await playwright.chromium.launch()
+      } catch (error) {
+        log(`Could not launch Chromium: ${error.message}`)
+        log('If the browser is not installed yet: pnpm exec playwright install chromium')
+        return 1
+      }
+      try {
+        const context = await browser.newContext({
+          viewport: { width: CAPTURE.width, height: CAPTURE.height },
+          deviceScaleFactor: 1,
+          reducedMotion: 'reduce',
+        })
+        const page = await context.newPage()
+        await page.goto(harness.url)
+        await waitForHarness(page)
+        let cdp = null
+        try {
+          cdp = await context.newCDPSession(page)
+        } catch {
+          cdp = null // non-CDP browser — PNG fallback below
+        }
+
+        mkdirSync(imagesDir, { recursive: true })
+        for (const job of toRender) {
+          const result = await renderEntryInPage(page, job)
+          if (!result || result.ok !== true) {
+            failures.push({ ...job, error: result?.error ?? 'unknown render failure' })
+            log(`  ✗ ${job.componentId} · ${job.fixture} — ${result?.error ?? 'render failed'}`)
+            continue
+          }
+          const { buffer, ext } = await captureViewport(page, cdp)
+          const fileName = previewFileName(job.componentId, job.fixture, ext)
+          writeFileSync(join(imagesDir, fileName), buffer)
+          job.url = `${PREVIEWS_URL_PREFIX}${fileName}`
+          log(`  ✓ ${job.componentId} · ${job.fixture} → ${fileName} (${(buffer.length / 1024).toFixed(1)} KB)`)
+        }
+      } finally {
+        await browser.close()
+      }
+    }
+
+    // Manifest: every successful entry (fresh or rendered), enumeration order.
+    const finalEntries = jobs.filter((j) => typeof j.url === 'string')
+    const manifestText = serializePreviewsManifest({ engine, entries: finalEntries })
+    const manifestChanged = artifacts.manifestText !== manifestText
+    if (manifestChanged) {
+      mkdirSync(studioDir, { recursive: true })
+      writeFileSync(manifestPath, manifestText)
+    }
+
+    // Prune orphaned images — the directory is CLI-owned and mirrors the manifest.
+    const referenced = new Set(finalEntries.map((e) => fileOfUrl(e.url)))
+    const currentFiles = existsSync(imagesDir)
+      ? readdirSync(imagesDir).filter((f) => !f.startsWith('.'))
+      : []
+    const orphans = currentFiles.filter((f) => !referenced.has(f))
+    for (const orphan of orphans) rmSync(join(imagesDir, orphan))
+
+    const rendered = toRender.length - failures.length
+    log('')
+    log(
+      `Done: ${rendered} rendered, ${jobs.length - toRender.length} unchanged, ` +
+        `${orphans.length} pruned, manifest ${manifestChanged ? 'written' : 'unchanged'} ` +
+        `(studio/${PREVIEWS_MANIFEST_FILE}).`,
+    )
+    if (failures.length > 0) {
+      log(`✗ ${failures.length} fixture(s) failed to render — their entries were left out of the manifest.`)
+      return 1
+    }
+    return 0
+  } catch (error) {
+    log(`previews failed: ${error?.stack ?? error}`)
+    return 1
+  } finally {
+    await harness.server.close()
+  }
+}