@elytracms/cli 0.0.85 → 0.0.87

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "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": ">=22.18.0"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.85"
+    "@elytracms/core": "^0.0.87"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process'
 import { join } from 'node:path'
 import { stdout } from 'node:process'
-import { runDoctor } from './doctor.js'
+import { resolveInstalledEngineVersion, runDoctor } from './doctor.js'
 import { runPreviews } from './previews.js'
 import { inspectProject, resolveStudioEnv } from './project.js'
 import { ensureAuthKeys } from './provision.js'
@@ -426,7 +426,17 @@ export async function runInit(project, { log: emit = log, fetchImpl, exec, provi
   emit('')
   emit('3. Verify —')
   const env = resolveStudioEnv(project.root)
-  const code = await runDoctor({ env, fetchImpl, log: (l) => emit(`   ${l}`) })
+  // EC-552: with the studio dir known, the verify step includes the version
+  // handshake — right after a provision is exactly when a stale-functions state
+  // should be loud. Resolution happens HERE (the entry), keeping runDoctor injected.
+  const verifyStudioDir = project.apps.studio ? join(project.root, 'studio') : undefined
+  const code = await runDoctor({
+    env,
+    fetchImpl,
+    log: (l) => emit(`   ${l}`),
+    studioDir: verifyStudioDir,
+    installedEngineVersion: resolveInstalledEngineVersion(verifyStudioDir),
+  })
 
   // 4. Ready checklist.
   emit('')
@@ -470,6 +480,7 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       return 1
     }
     const studioEnv = resolveStudioEnv(project.root, env)
+    const doctorStudioDir = project.apps.studio ? join(project.root, 'studio') : undefined
     return runDoctor({
       env: studioEnv,
       fetchImpl,
@@ -477,7 +488,10 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       url: flagValue(argv, '--url'),
       // EC-399: where `convex env list` runs (name enumeration — presence only),
       // and whether the AI provider-key expectation applies.
-      studioDir: project.apps.studio ? join(project.root, 'studio') : undefined,
+      studioDir: doctorStudioDir,
+      // EC-552: the installed engine version — resolved at the entry so runDoctor
+      // stays pure/injected; unresolvable (deps not installed) → honest `unknown`.
+      installedEngineVersion: resolveInstalledEngineVersion(doctorStudioDir),
       // EC-469: where the project's `cms/` route set is read from (code, not backend).
       root: project.root,
       aiRouteConfigured: project.hasAiRoute,

package/src/doctor.js

@@ -1,3 +1,6 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
 import {
   REVALIDATE_ENV_ENDPOINT,
   REVALIDATE_ENV_SECRET,
@@ -5,6 +8,7 @@ import {
   checkDeploymentReady,
   expectedDeploymentEnv,
   probeAuthSigningKeys,
+  probeDeployedFunctionsVersion,
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
 import { executeWorkspaceConfig } from './config-harness.js'
@@ -68,16 +72,27 @@ export function resolveDoctorTarget(env = {}, { url } = {}) {
 // --- Probes (node) -----------------------------------------------------------
 
 /**
- * Reachability probe: any HTTP response means the deployment answered; a thrown fetch
- * (DNS/connection) means it did not. (The studio uses `adapter.status()`; the CLI has
- * no convex client, so a plain GET to the deployment's client URL is the node analogue.)
+ * Deployment probe (EC-542 + EC-552): ONE call to the public query API yields BOTH the
+ * reachability fact and the version-handshake probe. The studio's probe was always a
+ * real query (`adapter.status()` → `members:mine`); the CLI previously used a bare GET
+ * and called ANY HTTP response "answered" — measured false-positive: Convex's wildcard
+ * `*.convex.cloud` 404s (empty body) for deployments that DO NOT EXIST, so every
+ * nonexistent deployment passed. Reachability now means "answered AS a Convex
+ * deployment": a Convex envelope — success, missing-function, or any other Convex
+ * error — proves a deployment; a non-Convex answer (the empty 404) or a thrown fetch
+ * (DNS/connection) fails it, each with its own honest detail so "nothing there" and
+ * "there but not deployed" stay distinguishable (the latter is reachable=true + the
+ * `functions-version`/JWKS-404 checks telling the deploy story).
  */
-export async function probeReachable(url, fetchImpl = fetch) {
-  try {
-    const res = await fetchImpl(url, { method: 'GET' })
-    return { available: true, detail: `HTTP ${res.status}` }
-  } catch (error) {
-    return { available: false, detail: error instanceof Error ? error.message : String(error) }
+export async function probeDeployment(url, fetchImpl = fetch) {
+  const versionProbe = await probeDeployedFunctionsVersion(url, fetchImpl)
+  const answered =
+    versionProbe.status === 'answered' ||
+    versionProbe.status === 'missing' ||
+    versionProbe.answeredAsConvex === true
+  return {
+    reachable: answered ? { available: true } : { available: false, detail: versionProbe.detail },
+    versionProbe,
   }
 }
 
@@ -86,24 +101,54 @@ export async function probeReachable(url, fetchImpl = fetch) {
  * user facts are intentionally omitted (no auth session) → `unknown`; the app facts
  * (config/collections) are gathered separately via the consumer-Vite harness when it
  * is available (EC-495, {@link configFactsFromOutcome}).
+ *
+ * EC-542/EC-552: reachability and the version probe are ONE network call
+ * ({@link probeDeployment}); the `functions-version` fact is emitted only when the
+ * caller supplies `installedEngineVersion` (otherwise the probe outcome still decides
+ * reachability but the handshake stays an honest `unknown`).
  */
-export async function gatherFacts(target, { fetchImpl = fetch } = {}) {
+export async function gatherFacts(target, { fetchImpl = fetch, installedEngineVersion } = {}) {
   if (target.kind === 'playground') return { backend: { kind: 'playground' } }
   if (target.kind === 'unconfigured') return { backend: { kind: 'unconfigured', detail: target.detail } }
 
-  const reachable = await probeReachable(target.url, fetchImpl)
+  const { reachable, versionProbe } = await probeDeployment(target.url, fetchImpl)
   const siteUrl = backendSiteUrl(target.url, target.siteUrl)
   const authKeys = await probeAuthSigningKeys(siteUrl, fetchImpl)
   return {
     backend: { kind: 'convex', url: target.url },
     reachable,
     authKeys,
+    ...(installedEngineVersion
+      ? { functionsVersion: { probe: versionProbe, expected: installedEngineVersion } }
+      : {}),
     // A configured URL means a deployment is wired; leave `provisioned` unset (→ ok).
     // session omitted → the user checks surface as `unknown`; config/collections are
     // merged in by the caller from the EC-495 harness outcome (or stay omitted).
   }
 }
 
+/**
+ * Resolve the engine version of the `@elytracms/studio` package INSTALLED in the
+ * consumer's studio app (EC-552) — the `expected` half of the version handshake.
+ * Deliberately resolved through the `convex/delivery` export and its adjacent
+ * `package.json`: that is the very source file the consumer's `convex deploy`
+ * bundles, so the version read here is by construction the version a redeploy
+ * would stamp. (The consumer's own `package.json` only carries a RANGE.)
+ * `undefined` when the deps aren't installed → the fact is omitted → the check
+ * reports an honest `unknown`, matching the config checks' opportunistic contract.
+ */
+export function resolveInstalledEngineVersion(studioDir) {
+  if (!studioDir) return undefined
+  try {
+    const req = createRequire(join(studioDir, 'package.json'))
+    const deliverySource = req.resolve('@elytracms/studio/convex/delivery')
+    const pkg = JSON.parse(readFileSync(join(dirname(deliverySource), '..', 'package.json'), 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
 // --- Config facts via the consumer-Vite harness (EC-495) -------------------------------
 
 /**
@@ -389,6 +434,13 @@ export function formatReport(report) {
  * works-without-node_modules contract is untouched. A resolved config also hands the
  * route checks the same collections the studio actually mounts (superseding the
  * `cms/index.ts` re-export). `configOutcome` is injectable for tests.
+ *
+ * EC-552: when the caller supplies `installedEngineVersion` (the CLI entry resolves it
+ * from the consumer's installed `@elytracms/studio` via {@link
+ * resolveInstalledEngineVersion}), the deployed functions are probed for their stamped
+ * version and the `functions-version` check gets a real answer; otherwise the fact is
+ * omitted → an honest `unknown`. Resolution stays at the entry point so this function
+ * remains pure/injected like every other gatherer here.
  */
 export async function runDoctor({
   env = {},
@@ -402,6 +454,7 @@ export async function runDoctor({
   previewsArtifacts,
   routeFacts,
   configOutcome,
+  installedEngineVersion,
 } = {}) {
   const target = resolveDoctorTarget(env, { url })
 
@@ -417,7 +470,11 @@ export async function runDoctor({
     log('No backend configured.')
   }
 
-  const facts = await gatherFacts(target, { fetchImpl })
+  // EC-552: the version handshake rides the same probe as reachability; it becomes a
+  // real check only when the caller supplied the installed engine version (the CLI
+  // entry resolves it via `resolveInstalledEngineVersion`; runDoctor itself never
+  // touches the filesystem for it, staying pure/injected like every gatherer here).
+  const facts = await gatherFacts(target, { fetchImpl, installedEngineVersion })
   if (target.kind === 'convex') {
     facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured, exec })
     // EC-421: default-on signed no-op ping whenever the revalidate pair is present.

package/src/previews.js

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
+import { CONFIG_FILE, pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
 
 /**
  * `elytra previews` (EC-440) — build-time fixture-preview generation.
@@ -18,14 +18,19 @@ import { pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } fro
  *     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) — no
- *     timestamps, so unchanged inputs re-serialize to the same bytes.
+ *     an input hash (manifest prop/slot shape + fixture props) — plus ONE
+ *     manifest-level `renderDeps` list (EC-600): a content hash per project
+ *     source file the config imports and per stylesheet in the theme's
+ *     `@import` chain. 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.
+ * Idempotence: an entry is skipped entirely when its input hash matches the
+ * existing manifest, its image file exists, AND the render dependencies are
+ * unchanged (screenshots are not guaranteed byte-stable, so "skip unchanged" is
+ * the mechanism, not re-render-and-compare). A changed render dependency
+ * re-renders every entry — nothing can say which pixels it touched. The
+ * manifest is only written when its bytes change. A re-run with unchanged
+ * inputs therefore rewrites nothing.
  *
  * Harness: the shared consumer-Vite boot (`config-harness.js`, EC-495 — one
  * mechanism for this command and `elytra doctor`'s config check) plus a
@@ -51,12 +56,17 @@ 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).
+ * Manifest format version — THE declaration (EC-514: the studio's mirror was
+ * removed; its reader is version-agnostic, and this CLI is the only writer and the
+ * only reader of the number). Bump on incompatible schema/hash changes.
  * `2` (EC-502): the entry hash no longer includes the engine version, so v1 hashes
  * are not comparable with v2 ones — a version mismatch is reported as itself
  * ("regenerate"), never as N bogus `stale` entries.
+ * `3` (EC-600): the manifest carries `renderDeps` (see {@link renderDepsOf}); a v2
+ * manifest has none, so its freshness cannot be judged — reported once as
+ * `manifest-version`, and one regeneration renders everything against the deps.
  */
-export const PREVIEWS_MANIFEST_VERSION = 2
+export const PREVIEWS_MANIFEST_VERSION = 3
 
 /** 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 }
@@ -107,11 +117,22 @@ function sortValue(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`). Implementation and theme drift are
- * deliberately NOT hashed (the ratified EC-440 split: those are caught by
- * regeneration runs, e.g. in the consumer's build).
+ * The PER-ENTRY staleness hash: sha-256 over the stable-serialized DECLARED
+ * inputs — the manifest's prop/slot shape + the fixture's own props/slotChildren
+ * (from the studio's `previewEntriesForConfig`). A change here is local to one
+ * entry: that entry re-renders and `--check` names exactly it.
+ *
+ * The component implementation and the theme are NOT in this hash — they have
+ * no per-entry identity (a config arrives evaluated; the theme is one stylesheet
+ * for everything). Until EC-600 this comment claimed regeneration caught drift
+ * there. It did not: regeneration rendered only `!fresh` jobs and `fresh` was
+ * decided by this hash alone, so a changed implementation or theme kept BOTH the
+ * check green and the images stale (measured on apps/demo 2026-10-09: an
+ * appended export in `hero.tsx` and a new `:root` rule in `theme.css` each left
+ * `--check` at exit 0; a fixture edit flipped it to `stale`). They are covered
+ * now by the manifest-level `renderDeps` ({@link renderDepsOf}): any change there
+ * re-renders everything and reports ONE `render-deps` problem — never N
+ * per-entry `stale` lines (the EC-502 lesson below).
  *
  * **EC-502 — the engine version was removed from this hash.** It made every
  * release invalidate every committed preview in every repo, so `elytra previews
@@ -133,11 +154,141 @@ export function previewEntryHash(hashInput) {
   return createHash('sha256').update(stableStringify({ input: hashInput }), 'utf8').digest('hex')
 }
 
+// --- Render dependencies (EC-600) ------------------------------------------------
+
+/**
+ * Root-relative POSIX path of an absolute file under `root` and not under a
+ * `node_modules` directory; `null` otherwise (virtual ids, installed packages,
+ * engine sources that resolve outside the project).
+ */
+function projectPath(root, file) {
+  if (typeof file !== 'string' || !isAbsolute(file)) return null
+  const rel = relative(root, file)
+  if (rel.length === 0 || rel.startsWith('..') || isAbsolute(rel)) return null
+  const posix = rel.split(sep).join('/')
+  return posix.split('/').includes('node_modules') ? null : posix
+}
+
+/**
+ * The project source files a Vite module graph loaded: every module with a real
+ * file under `root` that is not under `node_modules` — exactly what
+ * `elytra.config.ts` transitively imports, wherever the consumer keeps it
+ * (components, their helpers, imported assets, `cms/`). No directory
+ * convention is assumed (AGENTS.md §4: capability, never structure). Virtual
+ * modules have no file; installed packages sit under node_modules (in this
+ * monorepo they resolve to workspace packages outside the project) — the
+ * engine category the manifest's `engine` field and the engine-drift warning
+ * already cover. Absolute paths, sorted, unique.
+ */
+export function projectSourceFiles(moduleFiles, root) {
+  const out = new Set()
+  for (const file of moduleFiles) if (projectPath(root, file) !== null) out.add(file)
+  return [...out].sort()
+}
+
+const CSS_COMMENT = /\/\*[\s\S]*?\*\//g
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?(?:(['"])([^'"]+)\1|([^'")\s;]+))/g
+
+/**
+ * The theme entry plus every stylesheet it reaches through RELATIVE `@import`s,
+ * recursively (each file once; an extension-less `./tokens` resolves to
+ * `./tokens.css` the way postcss-import does). Bare specifiers (`tailwindcss`,
+ * a package's CSS) are installed code and are not followed; a relative target
+ * that does not exist is skipped here — the importing file, whose text names
+ * it, is hashed regardless, and the render itself fails loudly on it. Absolute
+ * paths, in import order.
+ */
+export function themeImportChain(entryPath, { readFile = readFileSync, exists = existsSync } = {}) {
+  const chain = []
+  const seen = new Set()
+  const visit = (file) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    if (!exists(file)) return
+    chain.push(file)
+    const text = String(readFile(file)).replace(CSS_COMMENT, '')
+    for (const match of text.matchAll(CSS_IMPORT)) {
+      const spec = match[2] ?? match[3]
+      if (!spec || spec.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(spec)) continue
+      const target = join(dirname(file), spec)
+      if (exists(target)) visit(target)
+      else if (spec.startsWith('.') && exists(`${target}.css`)) visit(`${target}.css`)
+    }
+  }
+  visit(entryPath)
+  return chain
+}
+
+/**
+ * Content-hash the render dependencies — the manifest's `renderDeps`:
+ * `[{ path, hash }]`, root-relative POSIX paths, sha-256 of the bytes, sorted by
+ * path, deduped. Byte-deterministic for unchanged files.
+ */
+export function renderDepsOf(root, files, { readFile = readFileSync } = {}) {
+  const byPath = new Map()
+  for (const file of files) {
+    const path = relative(root, file).split(sep).join('/')
+    if (byPath.has(path)) continue
+    byPath.set(path, createHash('sha256').update(readFile(file)).digest('hex'))
+  }
+  return [...byPath.entries()]
+    .map(([path, hash]) => ({ path, hash }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}
+
+/**
+ * The paths whose hash differs / are new / are gone between two `renderDeps`
+ * lists (each sorted). A missing list (a pre-EC-600 manifest) counts as empty,
+ * so every current dependency shows up as `added`.
+ */
+export function diffRenderDeps(prior, current) {
+  const before = new Map((prior ?? []).map((d) => [d.path, d.hash]))
+  const after = new Map((current ?? []).map((d) => [d.path, d.hash]))
+  const changed = []
+  const added = []
+  const removed = []
+  for (const [path, hash] of after) {
+    if (!before.has(path)) added.push(path)
+    else if (before.get(path) !== hash) changed.push(path)
+  }
+  for (const path of before.keys()) if (!after.has(path)) removed.push(path)
+  return { changed: changed.sort(), added: added.sort(), removed: removed.sort() }
+}
+
+/** `true` when nothing changed, was added, or was removed. */
+export function renderDepsEqual(prior, current) {
+  const { changed, added, removed } = diffRenderDeps(prior, current)
+  return changed.length + added.length + removed.length === 0
+}
+
+/** The changed/added/removed paths as one short list (`+new`, `-gone`), capped. */
+function summarizeRenderDeps(diff, cap = 6) {
+  const paths = [...diff.changed, ...diff.added.map((x) => `+${x}`), ...diff.removed.map((x) => `-${x}`)]
+  const shown = paths.slice(0, cap).join(', ') + (paths.length > cap ? `, … +${paths.length - cap} more` : '')
+  return { count: paths.length, shown }
+}
+
+/**
+ * What the render-dependency coverage IS and IS NOT — printed on every run, so
+ * "fresh" is read as exactly the claim it makes: a visible caveat, not a
+ * comment (AGENTS.md §4).
+ */
+export function describeRenderDeps({ sourceCount, themeCount, themeEntry }) {
+  return [
+    `Render dependencies: ${sourceCount} project source file(s) imported by ${CONFIG_FILE} ` +
+      `+ ${themeCount} theme stylesheet(s) (the @import chain of ${themeEntry}). ` +
+      'A change in any of them re-renders every preview.',
+    '  Not seen: modules loaded only at render time (dynamic imports), assets referenced by URL, ' +
+      'installed packages (the engine version is reported separately, as a warning).',
+  ]
+}
+
 /** Serialize the previews manifest deterministically (sorted entry keys, LF, trailing newline). */
-export function serializePreviewsManifest({ engine, entries }) {
+export function serializePreviewsManifest({ engine, entries, renderDeps = [] }) {
   const doc = {
     version: PREVIEWS_MANIFEST_VERSION,
     engine,
+    renderDeps: renderDeps.map((d) => ({ path: d.path, hash: d.hash })),
     entries: entries.map((e) => ({
       componentId: e.componentId,
       fixture: e.fixture,
@@ -165,16 +316,19 @@ const fileOfUrl = (url) => (typeof url === 'string' ? url.split('/').pop() : und
 
 /**
  * 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).
+ * an entry is FRESH (skipped) when the render dependencies are unchanged
+ * (EC-600 — `renderDeps` against the manifest's; a changed dependency makes
+ * EVERY entry stale), 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 }) {
+export function planPreviewRun({ specs, existing, files, renderDeps }) {
   const priorByKey = new Map((existing?.entries ?? []).map((e) => [key(e), e]))
+  const depsFresh = renderDepsEqual(existing?.renderDeps, renderDeps)
   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))
+    const fresh = Boolean(depsFresh && prior && prior.hash === spec.hash && priorFile && files.includes(priorFile))
     return fresh ? { ...spec, fresh: true, url: prior.url } : { ...spec, fresh: false }
   })
 }
@@ -186,9 +340,11 @@ export function planPreviewRun({ specs, existing, files }) {
  * Two channels, and the distinction is the whole point (EC-502):
  *
  *   - **problems** fail the gate (exit 1). Each one means an artifact does not
- *     match what the config declares: a fixture with no preview, a preview whose
+ *     match what the code declares: a fixture with no preview, a preview whose
  *     declared inputs changed, a manifest entry whose image is gone, an entry or
- *     file nothing enumerates any more.
+ *     file nothing enumerates any more — and, ONCE for the whole set, a render
+ *     dependency (a config-imported source file or a theme stylesheet) whose
+ *     content changed since the images were rendered (EC-600).
  *   - **warnings** are reported and do NOT fail. Today that is exactly one:
  *     `engine-drift` — these images were rendered by a different engine version.
  *     True and worth saying, but it is implementation drift, the same category
@@ -201,7 +357,7 @@ export function planPreviewRun({ specs, existing, files }) {
  * `stale` line per entry. Say the real thing once, and skip the hash comparison
  * (entry-set and file checks still run — they are version-independent).
  */
-export function checkPreviews({ specs, manifest, files, engine }) {
+export function checkPreviews({ specs, manifest, files, engine, renderDeps }) {
   const problems = []
   const warnings = []
   if (!manifest) {
@@ -215,6 +371,10 @@ export function checkPreviews({ specs, manifest, files, engine }) {
   const comparableHashes = version === PREVIEWS_MANIFEST_VERSION
   if (!comparableHashes) {
     problems.push({ kind: 'manifest-version', from: version, to: PREVIEWS_MANIFEST_VERSION })
+  } else {
+    // One problem for the whole set — which files, never N bogus per-entry `stale` rows.
+    const deps = diffRenderDeps(manifest.renderDeps, renderDeps)
+    if (!renderDepsEqual(manifest.renderDeps, renderDeps)) problems.push({ kind: 'render-deps', ...deps })
   }
   if (engine !== undefined && manifest.engine !== undefined && manifest.engine !== engine) {
     warnings.push({ kind: 'engine-drift', from: manifest.engine, to: engine })
@@ -263,6 +423,13 @@ export function formatCheckProblems(problems) {
     if (p.kind === 'manifest-version') {
       return `  ✗ manifest   written in format v${p.from}, this CLI writes v${p.to} — hashes are not comparable; regenerate`
     }
+    if (p.kind === 'render-deps') {
+      const { count, shown } = summarizeRenderDeps(p)
+      return (
+        `  ✗ render deps ${count} render dependenc${count === 1 ? 'y' : 'ies'} changed since these previews ` +
+        `were rendered (${shown}) — every preview re-renders`
+      )
+    }
     return p.kind === 'orphan-file'
       ? `  ✗ ${label[p.kind]} ${p.file}`
       : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`
@@ -507,7 +674,27 @@ async function startHarnessServer({ root, studioDir, port }) {
     port,
     plugins: [tailwind(), ...harnessPlugins({ configPath, themePath })],
   })
-  return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}` }
+  return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}`, themePath }
+}
+
+/**
+ * The render dependencies of a booted harness (EC-600): the project source files
+ * the SSR module graph loaded while enumerating (what `elytra.config.ts`
+ * imports) plus the theme's `@import` chain, content-hashed. Call AFTER
+ * `ssrLoadModule` has run, or the graph is empty.
+ */
+function collectRenderDeps(harness, root) {
+  const graph = harness.server.environments?.ssr?.moduleGraph ?? harness.server.moduleGraph
+  const sources = projectSourceFiles([...graph.idToModuleMap.values()].map((m) => m.file), root)
+  const theme = themeImportChain(harness.themePath)
+  return {
+    renderDeps: renderDepsOf(root, [...sources, ...theme]),
+    description: describeRenderDeps({
+      sourceCount: sources.length,
+      themeCount: theme.length,
+      themeEntry: relative(root, harness.themePath).split(sep).join('/'),
+    }),
+  }
 }
 
 const PLAYWRIGHT_INSTALL_HELP = [
@@ -634,7 +821,11 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
       fixture: entry.fixture,
       hash: previewEntryHash(entry.hashInput),
     }))
-    log(`Enumerated ${specs.length} fixture preview(s) from elytra.config.ts.`)
+    log(`Enumerated ${specs.length} fixture preview(s) from ${CONFIG_FILE}.`)
+    // EC-600: what the config imported while enumerating + the theme chain — and,
+    // visibly, what that does NOT cover.
+    const { renderDeps, description } = collectRenderDeps(harness, root)
+    for (const line of description) log(line)
 
     const artifacts = gatherPreviewsArtifacts(studioDir)
     const existing = parsePreviewsManifest(artifacts.manifestText)
@@ -645,12 +836,15 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
         manifest: existing,
         files: artifacts.files,
         engine,
+        renderDeps,
       })
       // Warnings print on BOTH verdicts — a green run that still has something to
       // say says it, and a red run does not swallow it.
       for (const line of formatCheckWarnings(warnings)) log(line)
       if (ok) {
-        log(`✓ ${specs.length} preview(s) up to date (hashes match, all files present).`)
+        log(
+          `✓ ${specs.length} preview(s) up to date (declared inputs and render dependencies unchanged, all files present).`,
+        )
         return 0
       }
       log(`✗ ${problems.length} problem(s):`)
@@ -659,7 +853,11 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
       return 1
     }
 
-    const jobs = planPreviewRun({ specs, existing, files: artifacts.files })
+    if (existing && !renderDepsEqual(existing.renderDeps, renderDeps)) {
+      const { shown } = summarizeRenderDeps(diffRenderDeps(existing.renderDeps, renderDeps))
+      log(`Render dependencies changed (${shown}) — every preview re-renders.`)
+    }
+    const jobs = planPreviewRun({ specs, existing, files: artifacts.files, renderDeps })
     const toRender = jobs.filter((j) => !j.fresh)
     log(`${jobs.length - toRender.length} unchanged (skipped), ${toRender.length} to render.`)
 
@@ -715,7 +913,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
 
     // 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 manifestText = serializePreviewsManifest({ engine, entries: finalEntries, renderDeps })
     const manifestChanged = artifacts.manifestText !== manifestText
     if (manifestChanged) {
       mkdirSync(studioDir, { recursive: true })