@elytracms/cli 0.0.88 → 0.0.90

package/src/doctor.js

@@ -6,14 +6,17 @@ import {
   REVALIDATE_ENV_ENDPOINT,
   REVALIDATE_ENV_SECRET,
   backendSiteUrl,
+  backendUrlOf,
   checkDeploymentReady,
   expectedDeploymentEnv,
+  parseBackendMode,
   probeAuthSigningKeys,
   probeDeliverySnapshot,
   probeDeployedFunctionsVersion,
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
-import { executeWorkspaceConfig } from './config-harness.js'
+import { aiRouteDoctorChecks, executeWorkspaceConfig, readStudioAiRoute } from './config-harness.js'
+import { appDisplay, layoutDoctorChecks } from './layout.js'
 import { convexEnvGet, defaultConvexExec } from './provision.js'
 import { gatherPreviewsArtifacts, previewsDoctorChecks } from './previews.js'
 import { loadProjectRoutes, routesDoctorChecks } from './routes-check.js'
@@ -40,17 +43,29 @@ import { loadProjectRoutes, routesDoctorChecks } from './routes-check.js'
 /**
  * Decide which deployment the doctor diagnoses from the resolved studio env.
  *
- * A configured `VITE_CONVEX_URL` is preferred over the `VITE_ELYTRA_MODE=playground`
- * run-mode flag: that flag only selects the studio's in-memory *adapter*, whereas the
- * doctor's job is to validate the real deployment you configured. So a repo that runs
+ * The mode is judged by the ONE parser the studio runs (core's `parseBackendMode`,
+ * EC-603), so a padded flag is playground here exactly as it is in the studio, and an
+ * unknown mode is the studio's own boot error — a failing `backend-url` naming the
+ * value, never silently overridden by a URL beside it.
+ *
+ * A configured `VITE_CONVEX_URL` is preferred over a VALID `VITE_ELYTRA_MODE=playground`
+ * flag: that flag only selects the studio's in-memory *adapter*, whereas the doctor's
+ * job is to validate the real deployment you configured. So a repo that runs
  * playground locally but points at a Convex deployment (e.g. the demo) is diagnosed
- * against that deployment — with a note that the studio itself runs in-memory.
+ * against that deployment — with a note that the studio itself runs in-memory. An
+ * explicit `--url` diagnoses that deployment whatever the env says.
+ *
+ * `envSource` names where the env was read, for the unconfigured detail (`studio/.env`).
  */
-export function resolveDoctorTarget(env = {}, { url } = {}) {
+export function resolveDoctorTarget(env = {}, { url, envSource = 'studio/.env' } = {}) {
   const explicit = url && url.trim() !== '' ? url.trim() : undefined
-  const envUrl = env.VITE_CONVEX_URL || env.CONVEX_URL
+  const backend = parseBackendMode(env)
+  if (!explicit && backend.kind === 'misconfigured' && backend.reason === 'unknown-mode') {
+    return { kind: 'unconfigured', detail: `${backend.detail} (in ${envSource})` }
+  }
+  const envUrl = backendUrlOf(env)
   const chosenUrl = explicit || envUrl
-  const playgroundFlag = env.VITE_ELYTRA_MODE === 'playground'
+  const playgroundFlag = backend.kind === 'playground'
 
   if (chosenUrl) {
     return {
@@ -67,7 +82,7 @@ export function resolveDoctorTarget(env = {}, { url } = {}) {
   if (playgroundFlag) return { kind: 'playground' }
   return {
     kind: 'unconfigured',
-    detail: 'No VITE_CONVEX_URL is set, and VITE_ELYTRA_MODE is not "playground", in studio/.env.',
+    detail: `No VITE_CONVEX_URL is set, and VITE_ELYTRA_MODE is not "playground", in ${envSource}.`,
   }
 }
 
@@ -345,7 +360,7 @@ export function gatherDeploymentEnvFacts({ env = {}, target, studioDir, aiRouteC
     facts.unavailableDetail =
       '--url overrides the linked deployment; env names are only read from the deployment this repo is linked to.'
   } else if (!studioDir) {
-    facts.unavailableDetail = 'No studio/ app found — deployment env names not enumerated.'
+    facts.unavailableDetail = 'No studio app found — deployment env names not enumerated.'
   } else if (!env.CONVEX_DEPLOYMENT && !env.CONVEX_DEPLOY_KEY) {
     facts.unavailableDetail =
       'No linked deployment (CONVEX_DEPLOYMENT / CONVEX_DEPLOY_KEY unset) — `npx convex env list` needs one.'
@@ -360,10 +375,10 @@ export function gatherDeploymentEnvFacts({ env = {}, target, studioDir, aiRouteC
 // --- Signed revalidate ping (EC-421) -------------------------------------------
 //
 // When the presence checks say the instant-publish pair IS set, the doctor proves the
-// chain end to end: a POST to the endpoint signed with the secret, carrying an EMPTY
-// tag list — by the receiving route's own semantics a harmless no-op answering 200
-// `{"revalidated":[]}`. Default-on (no flag): the ping is read-only in effect and the
-// silent-failure class it catches (secret mismatch — publishes rejected with 401
+// chain end to end: a POST to the endpoint signed with the secret, carrying the `probe`
+// event (EC-579), which derives no cache tags — by the receiving route's own semantics a
+// harmless no-op answering 200 `{"revalidated":[]}`. Default-on (no flag): the ping is
+// read-only in effect and the silent-failure class it catches (secret mismatch — publishes rejected with 401
 // forever, no error anywhere) is exactly what the doctor exists for.
 //
 // The ping needs the pair's VALUES — the one sanctioned value read: captured
@@ -459,6 +474,29 @@ export function formatReport(report) {
   return lines.join('\n')
 }
 
+/**
+ * The route set the doctor's route checks judge (EC-603, RESIDUE-4): the RESOLVED
+ * config's routes + collections when the harness resolved it validly — the same records
+ * the studio mounts and delivery serves, whatever file they were declared in — else the
+ * native `cms/index.ts` floor ({@link loadProjectRoutes}, or the injected `routeFacts`),
+ * with the resolved collections swapped in when there are some. `source` says which, so
+ * the report can. Never throws.
+ */
+export async function routeFactsFor({ outcome, configFacts = {}, routeFacts, root }) {
+  const project = resolvedProjectOf(outcome)
+  if (project && Array.isArray(project.routes)) {
+    return {
+      routes: project.routes,
+      routeCount: project.routes.length,
+      ...(Array.isArray(project.collections) ? { collections: project.collections } : {}),
+      source: 'config',
+    }
+  }
+  const loaded = routeFacts ?? (await loadProjectRoutes(root))
+  const enriched = configFacts.collections ? { ...loaded, collections: configFacts.collections } : loaded
+  return { ...enriched, source: 'native' }
+}
+
 // --- Command -----------------------------------------------------------------
 
 /**
@@ -502,6 +540,19 @@ export function formatReport(report) {
  * published documents whose collection the resolved config does not declare — read
  * from the public delivery snapshot ({@link gatherPublishedOrphans}). A `warn` at most,
  * so the exit code never changes; without a resolved config it is an honest `unknown`.
+ *
+ * EC-603: three more facts, all read from DECLARATIONS rather than fixed paths:
+ *  - `layout` (the CLI entry passes `inspectProject`'s resolved `package.json#elytra`
+ *    layout) → the `project-layout` row: what was resolved, declared or defaulted, and a
+ *    `fail` for an invalid section or a declared path that does not exist;
+ *  - the AI route → read from the studio's own resolved Vite config
+ *    ({@link readStudioAiRoute}) when a `root` is known — it decides the AI-key
+ *    expectation and gets its own `ai-route` row. `aiRoute` (an outcome) and
+ *    `aiRouteConfigured` (a boolean) are test seams; without either and without a root
+ *    no AI expectation is added;
+ *  - the route checks run over the RESOLVED config's routes whenever the harness
+ *    resolved it (the routes the studio and delivery actually serve); the native
+ *    `cms/index.ts` read is the fallback only when it could not, and the row says which.
  */
 export async function runDoctor({
   env = {},
@@ -510,14 +561,17 @@ export async function runDoctor({
   url,
   studioDir,
   root,
-  aiRouteConfigured = false,
+  layout,
+  aiRoute: aiRouteOutcome,
+  aiRouteConfigured,
   exec,
   previewsArtifacts,
   routeFacts,
   configOutcome,
   installedEngineVersion,
 } = {}) {
-  const target = resolveDoctorTarget(env, { url })
+  const studioLabel = appDisplay(layout, 'studio')
+  const target = resolveDoctorTarget(env, { url, envSource: `${studioLabel}/.env` })
 
   log('Elytra deployment doctor')
   if (target.kind === 'convex') {
@@ -536,8 +590,14 @@ export async function runDoctor({
   // 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 })
+
+  // EC-603: the AI route from the studio's resolved Vite config — gathered before the
+  // deployment-env facts, whose AI-key expectation it decides.
+  const aiRoute = aiRouteOutcome ?? (root !== undefined ? await readStudioAiRoute({ studioDir }) : undefined)
+  const aiExpected = aiRouteConfigured ?? aiRoute?.kind === 'mounted'
+
   if (target.kind === 'convex') {
-    facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured, exec })
+    facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured: aiExpected, exec })
     // EC-421: default-on signed no-op ping whenever the revalidate pair is present.
     const revalidateProbe = await gatherRevalidateProbe({
       envFacts: facts.deploymentEnv,
@@ -577,14 +637,24 @@ export async function runDoctor({
   const artifacts = previewsArtifacts ?? (studioDir ? gatherPreviewsArtifacts(studioDir) : undefined)
   let checks = artifacts ? [...report.checks, ...previewsDoctorChecks(artifacts)] : [...report.checks]
 
+  // EC-603: the layout and AI-route rows, in the `app` bucket (both repo facts).
+  checks = spliceBucketChecks(checks, 'app', [
+    ...layoutDoctorChecks(layout),
+    ...aiRouteDoctorChecks(aiRoute, { studioLabel }),
+  ])
+
   // EC-469: the route-conflict check, spliced into the `app` bucket it belongs to.
   // Backend-independent (routes are CODE) — it runs in playground mode too.
-  // EC-495: a resolved config supersedes the `cms/index.ts` collections re-export —
-  // the route checks judge mounts against the same collections the studio mounts.
+  // EC-603 (RESIDUE-4): when the harness resolved the config, the checks run over ITS
+  // routes and collections — what the studio and delivery serve; the native
+  // `cms/index.ts` read is the fallback for when it could not (EC-495 had swapped in the
+  // resolved collections only, so the routes still came from `cms/index.ts`).
   if (root !== undefined || routeFacts !== undefined) {
-    const loaded = routeFacts ?? (await loadProjectRoutes(root))
-    const enriched = configFacts.collections ? { ...loaded, collections: configFacts.collections } : loaded
-    checks = spliceBucketChecks(checks, 'app', routesDoctorChecks(enriched))
+    checks = spliceBucketChecks(
+      checks,
+      'app',
+      routesDoctorChecks(await routeFactsFor({ outcome, configFacts, routeFacts, root })),
+    )
   }
 
   // One rule for the exit code, the same one `checkDeploymentReady` applies: a

package/src/layout.js

@@ -0,0 +1,288 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/**
+ * The CLI layout contract (EC-603, RATIFIED 2026-10-24) — where a project's studio app,
+ * frontend app and theme stylesheet live, declared in the repo-root `package.json`:
+ *
+ *   "elytra": { "studio": "./studio", "frontend": "./frontend", "theme": "./components/theme.css" }
+ *
+ * `package.json` because it is the one file the CLI can read before ANY toolchain runs —
+ * `elytra.config.ts` (the structure) is executed through the studio app's own Vite,
+ * which needs the studio's location first (the chicken-and-egg EC-565 Round 5 settled;
+ * a plain-TS loader was measured not viable). Every key is optional and DEFAULTS TO THE
+ * SCAFFOLD LAYOUT, so a scaffolded project declares nothing and nothing changes for it.
+ *
+ * The engine supplies capability, never structure (AGENTS.md §4): with this section a
+ * project can reorganise its directories freely and still satisfy the CLI.
+ *
+ * This module is the ONE declaration of the section's shape ({@link LAYOUT_ENTRIES}) and
+ * its ONE reader ({@link resolveProjectLayout}); every CLI path that needs a location
+ * (`inspectProject`, `dev`/`build`, the config harness, `previews`, `doctor`) takes it
+ * from the resolved layout. Validation is explicit — an unknown key, a non-string value,
+ * an absolute path, a path escaping the repo, a theme that is not a file, a declared path
+ * that does not exist — each is a named issue, never a silent fall-back to the default.
+ * Its only reader is the CLI (the studio and the engine never read it), so it lives here,
+ * in plain JS with no dependency, rather than as a core schema.
+ */
+
+/** Where the section lives, as the issues name it. */
+export const LAYOUT_SECTION = 'package.json#elytra'
+
+/**
+ * The section's keys — THE declaration. `default` is the scaffold layout; `kind` is what
+ * the path must be (`app`: a directory with a `package.json`; `file`: a file).
+ */
+export const LAYOUT_ENTRIES = {
+  studio: { default: './studio', kind: 'app', label: 'studio app' },
+  frontend: { default: './frontend', kind: 'app', label: 'frontend app' },
+  theme: { default: './components/theme.css', kind: 'file', label: 'theme stylesheet' },
+}
+
+const KEYS = Object.keys(LAYOUT_ENTRIES)
+
+/** A root-relative POSIX path for display (`apps/editor`, `.` for the root itself). */
+export function displayPath(root, absolute) {
+  const rel = relative(root, absolute)
+  return rel === '' ? '.' : rel.split(sep).join('/')
+}
+
+function issue(key, code, message, fix) {
+  return { key, code, message, ...(fix ? { fix } : {}) }
+}
+
+/**
+ * PURE core: parse the root `package.json` text (or `undefined` when there is none) into
+ * the declared values and the SHAPE issues. Existence is checked separately
+ * ({@link resolveProjectLayout}) so this stays filesystem-free.
+ *
+ * Returns `{ declared: { [key]: string }, invalid: Set<key>, issues }` — a key in
+ * `invalid` has NO usable value (it is neither the declared one nor the default: an
+ * invalid declaration must never quietly turn into the scaffold path).
+ */
+export function parseLayoutSection(root, packageJsonText) {
+  const declared = {}
+  const invalid = new Set()
+  const issues = []
+  if (packageJsonText === undefined) return { declared, invalid, issues }
+
+  let pkg
+  try {
+    pkg = JSON.parse(packageJsonText)
+  } catch (error) {
+    for (const key of KEYS) invalid.add(key)
+    issues.push(
+      issue(
+        null,
+        'layout-package-json-invalid',
+        `The repo-root package.json is not valid JSON (${error.message}) — the project layout (${LAYOUT_SECTION}) cannot be read.`,
+        'Fix the JSON syntax of the repo-root package.json.',
+      ),
+    )
+    return { declared, invalid, issues }
+  }
+
+  const section = pkg?.elytra
+  if (section === undefined) return { declared, invalid, issues }
+  if (section === null || typeof section !== 'object' || Array.isArray(section)) {
+    for (const key of KEYS) invalid.add(key)
+    issues.push(
+      issue(
+        null,
+        'layout-invalid-section',
+        `${LAYOUT_SECTION} must be an object of paths ({ "studio": "./studio", … }), not ${section === null ? 'null' : Array.isArray(section) ? 'an array' : typeof section}.`,
+        `Make ${LAYOUT_SECTION} an object with any of ${KEYS.join(', ')} — or remove it to use the scaffold layout.`,
+      ),
+    )
+    return { declared, invalid, issues }
+  }
+
+  for (const key of Object.keys(section)) {
+    if (!Object.hasOwn(LAYOUT_ENTRIES, key)) {
+      issues.push(
+        issue(
+          key,
+          'layout-unknown-key',
+          `${LAYOUT_SECTION} has an unknown key "${key}" — the known keys are ${KEYS.join(', ')}.`,
+          `Rename or remove "${key}" in ${LAYOUT_SECTION}.`,
+        ),
+      )
+    }
+  }
+
+  for (const key of KEYS) {
+    if (!Object.hasOwn(section, key)) continue
+    const value = section[key]
+    const entry = LAYOUT_ENTRIES[key]
+    const fix = `Set ${LAYOUT_SECTION}.${key} to the ${entry.label}'s path relative to the repo root (default "${entry.default}"), or remove the key to use the default.`
+    if (typeof value !== 'string' || value.trim() === '') {
+      invalid.add(key)
+      issues.push(
+        issue(key, 'layout-invalid-path', `${LAYOUT_SECTION}.${key} must be a non-empty path string, not ${JSON.stringify(value)}.`, fix),
+      )
+      continue
+    }
+    if (isAbsolute(value)) {
+      invalid.add(key)
+      issues.push(
+        issue(
+          key,
+          'layout-invalid-path',
+          `${LAYOUT_SECTION}.${key} is the absolute path "${value}" — layout paths are relative to the repo root, so the project works wherever it is checked out.`,
+          fix,
+        ),
+      )
+      continue
+    }
+    const rel = relative(root, resolve(root, value))
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      invalid.add(key)
+      issues.push(
+        issue(key, 'layout-invalid-path', `${LAYOUT_SECTION}.${key} ("${value}") points outside the repo root.`, fix),
+      )
+      continue
+    }
+    if (rel === '' && entry.kind === 'app') {
+      // The root package is the one that runs `elytra` — an app there would make
+      // `elytra dev` spawn itself.
+      invalid.add(key)
+      issues.push(
+        issue(key, 'layout-invalid-path', `${LAYOUT_SECTION}.${key} ("${value}") is the repo root itself — the ${entry.label} must be its own directory.`, fix),
+      )
+      continue
+    }
+    declared[key] = value
+  }
+  return { declared, invalid, issues }
+}
+
+/** Default filesystem probes — injectable for tests. */
+const defaultFs = {
+  readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : undefined),
+  kindOf: (path) => {
+    try {
+      const stat = statSync(path)
+      return stat.isDirectory() ? 'dir' : stat.isFile() ? 'file' : 'other'
+    } catch {
+      return 'missing'
+    }
+  },
+}
+
+/**
+ * Resolve a project's layout: the declared-or-default path of every entry, whether it
+ * exists, and every issue. Never throws.
+ *
+ * Returns
+ *   {
+ *     source: 'declared' | 'defaults',   // was anything declared in package.json#elytra?
+ *     entries: { studio, frontend, theme }, each
+ *       { key, path: <absolute> | null, display: 'apps/editor' | null,
+ *         declared: boolean, found: boolean },
+ *     issues: [{ key, code, message, fix? }],
+ *   }
+ *
+ * `path` is `null` only for an INVALID declaration — the entry is then unusable, never
+ * the default. A DECLARED path that does not exist (or a theme that is not a file) is an
+ * issue; a DEFAULT path that does not exist is not (a frontend-only or studio-only repo
+ * is legitimate) — it is simply `found: false`.
+ */
+export function resolveProjectLayout(root, fs = defaultFs) {
+  const { declared, invalid, issues } = parseLayoutSection(root, fs.readFile(join(root, 'package.json')))
+  const entries = {}
+  for (const key of KEYS) {
+    const entry = LAYOUT_ENTRIES[key]
+    if (invalid.has(key)) {
+      entries[key] = { key, path: null, display: null, declared: true, found: false }
+      continue
+    }
+    const isDeclared = Object.hasOwn(declared, key)
+    const path = resolve(root, isDeclared ? declared[key] : entry.default)
+    const display = displayPath(root, path)
+    let found
+    if (entry.kind === 'app') {
+      found = fs.kindOf(join(path, 'package.json')) === 'file'
+      if (isDeclared && !found) {
+        issues.push(
+          issue(
+            key,
+            'layout-path-missing',
+            fs.kindOf(path) === 'missing'
+              ? `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} does not exist.`
+              : `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} has no package.json — it is not an app.`,
+            `Point ${LAYOUT_SECTION}.${key} at the ${entry.label}'s directory (the one with its package.json), relative to the repo root.`,
+          ),
+        )
+      }
+    } else {
+      const kind = fs.kindOf(path)
+      found = kind === 'file'
+      if (isDeclared && kind === 'missing') {
+        issues.push(
+          issue(
+            key,
+            'layout-path-missing',
+            `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} does not exist.`,
+            `Point ${LAYOUT_SECTION}.${key} at the ${entry.label} file, relative to the repo root.`,
+          ),
+        )
+      } else if (isDeclared && kind !== 'file') {
+        issues.push(
+          issue(
+            key,
+            'layout-not-a-file',
+            `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} is ${kind === 'dir' ? 'a directory' : 'not a regular file'} — the theme is one stylesheet.`,
+            `Point ${LAYOUT_SECTION}.${key} at the theme's entry stylesheet (e.g. "./components/theme.css").`,
+          ),
+        )
+      }
+    }
+    entries[key] = { key, path, display, declared: isDeclared, found }
+  }
+  const source = KEYS.some((key) => entries[key].declared) ? 'declared' : 'defaults'
+  return { source, entries, issues }
+}
+
+/**
+ * The root-relative display path of an entry for prose and fix lines (`apps/editor`,
+ * `studio`) — the resolved one, or the scaffold default's when no layout was resolved
+ * (an invalid declaration, or a hand-built project object). Display only: no command
+ * ever SPAWNS or READS from this fallback.
+ */
+export function appDisplay(layout, key) {
+  return layout?.entries?.[key]?.display ?? LAYOUT_ENTRIES[key].default.replace(/^\.\//, '')
+}
+
+// --- Doctor row (pure) ---------------------------------------------------------------
+
+/**
+ * The doctor's `project-layout` row for the `app` bucket: what the CLI resolved and where
+ * from, so "which studio did it look at?" is never a guess. `fail` on any layout issue
+ * (an invalid section or a declared path that does not exist — both deterministic in the
+ * repo, so failing the exit code is safe for CI); otherwise `ok`, listing each location
+ * and whether it was declared or defaulted.
+ */
+export function layoutDoctorChecks(layout) {
+  if (!layout) return []
+  const base = { id: 'project-layout', bucket: 'app' }
+  if (layout.issues.length > 0) {
+    return [
+      {
+        ...base,
+        status: 'fail',
+        detail: `${layout.issues.length} problem(s) with the project layout. ${layout.issues.map((i) => i.message).join(' ')}`,
+        fix: layout.issues.find((i) => i.fix)?.fix ?? `Fix ${LAYOUT_SECTION} in the repo-root package.json.`,
+      },
+    ]
+  }
+  const parts = KEYS.map((key) => {
+    const entry = layout.entries[key]
+    const where = entry.found ? entry.display : `${entry.display} (not present)`
+    return `${key} → ${where}`
+  })
+  const origin =
+    layout.source === 'declared'
+      ? `declared in ${LAYOUT_SECTION} (undeclared keys use the scaffold defaults)`
+      : `the scaffold defaults — nothing declared in ${LAYOUT_SECTION}`
+  return [{ ...base, status: 'ok', detail: `${parts.join(', ')} — ${origin}.` }]
+}

package/src/previews.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { CONFIG_FILE, pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
+import { appDisplay, resolveProjectLayout } from './layout.js'
 
 /**
  * `elytra previews` (EC-440) — build-time fixture-preview generation.
@@ -561,9 +562,10 @@ export function previewsDoctorChecks(artifacts) {
  * 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).
+ * `studioDir` is the resolved studio app (EC-603 layout).
  */
-export function resolveEngineVersion(root) {
-  const bases = [join(root, 'studio'), root]
+export function resolveEngineVersion(root, studioDir) {
+  const bases = [studioDir, root]
   for (const pkg of ['@elytracms/studio', '@elytracms/core']) {
     for (const base of bases) {
       const path = join(base, 'node_modules', ...pkg.split('/'), 'package.json')
@@ -581,16 +583,26 @@ export function resolveEngineVersion(root) {
 
 /**
  * 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).
+ * stylesheet (`<studio>/src/styles/canvas.css` — the EC-414 shape: the site
+ * theme plus any engine-required `@source` lines; the stylesheet the canvas
+ * iframe really links) when present, else the theme itself — `package.json#elytra
+ * .theme`, default `components/theme.css` (EC-603: the project's declaration, never
+ * a fixed path). `null` → no theme, the command refuses (an unstyled preview would
+ * be a lying artifact).
+ *
+ * The canvas stylesheet stays first so a conventional project's recorded render
+ * dependencies (its committed manifest) are byte-for-byte unchanged by EC-603. It is
+ * looked up relative to the RESOLVED studio app; a project without one falls back to
+ * the declared theme, so it is a preference, never a requirement.
  */
-export function themeStylesheetPath(root) {
-  for (const candidate of [
-    join(root, 'studio', 'src', 'styles', 'canvas.css'),
-    join(root, 'components', 'theme.css'),
-  ]) {
+export function themeStylesheetPath(root, layout = resolveProjectLayout(root)) {
+  const studio = layout.entries.studio
+  const theme = layout.entries.theme
+  const candidates = [
+    ...(studio.path ? [join(studio.path, 'src', 'styles', 'canvas.css')] : []),
+    ...(theme.path ? [theme.path] : []),
+  ]
+  for (const candidate of candidates) {
     if (existsSync(candidate)) return candidate
   }
   return null
@@ -652,7 +664,7 @@ function harnessPlugins({ configPath, themePath }) {
 }
 
 /** Boot the shared consumer-Vite harness with the previews page + modules. */
-async function startHarnessServer({ root, studioDir, port }) {
+async function startHarnessServer({ root, studioDir, layout, port }) {
   // Resolve vite first so a missing toolchain names vite (the same failure
   // order as before the boot moved to the shared config-harness).
   resolveFromDir(studioDir, 'vite')
@@ -660,11 +672,13 @@ async function startHarnessServer({ root, studioDir, port }) {
   const tailwind = (await import(pathToFileURL(tailwindEntry).href)).default
 
   const configPath = join(root, 'elytra.config.ts')
-  const themePath = themeStylesheetPath(root)
+  const themePath = themeStylesheetPath(root, layout)
   if (!themePath) {
+    const studio = appDisplay(layout, 'studio')
+    const theme = appDisplay(layout, 'theme')
     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.',
+      `No theme stylesheet found (looked for ${studio}/src/styles/canvas.css and ${theme} — ` +
+        'declare yours as package.json#elytra.theme) — previews must render against the consumer theme.',
     )
   }
 
@@ -708,8 +722,8 @@ const PLAYWRIGHT_INSTALL_HELP = [
 ].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]) {
+async function loadPlaywright(root, studioDir) {
+  for (const base of [studioDir, root]) {
     let resolved
     try {
       resolved = resolveFromDir(base, 'playwright')
@@ -795,8 +809,11 @@ async function captureViewport(page, cdp) {
  */
 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)
+  // EC-603: the studio app and theme where the project's layout says they are.
+  const layout = project.layout ?? resolveProjectLayout(root)
+  const studioDir = layout.entries.studio.path
+  const studioLabel = layout.entries.studio.display
+  const engine = resolveEngineVersion(root, studioDir)
   const manifestPath = join(studioDir, PREVIEWS_MANIFEST_FILE)
   const imagesDir = join(studioDir, PREVIEWS_DIR)
 
@@ -807,7 +824,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
   const chosenPort = port ? Number(port) : await pickPort()
   let harness
   try {
-    harness = await startHarnessServer({ root, studioDir, port: chosenPort })
+    harness = await startHarnessServer({ root, studioDir, layout, port: chosenPort })
   } catch (error) {
     log(`Could not start the render harness: ${error.message}`)
     return 1
@@ -863,7 +880,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
 
     const failures = []
     if (toRender.length > 0) {
-      const playwright = await loadPlaywright(root)
+      const playwright = await loadPlaywright(root, studioDir)
       if (!playwright) {
         log(PLAYWRIGHT_INSTALL_HELP)
         return 1
@@ -933,7 +950,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
     log(
       `Done: ${rendered} rendered, ${jobs.length - toRender.length} unchanged, ` +
         `${orphans.length} pruned, manifest ${manifestChanged ? 'written' : 'unchanged'} ` +
-        `(studio/${PREVIEWS_MANIFEST_FILE}).`,
+        `(${studioLabel}/${PREVIEWS_MANIFEST_FILE}).`,
     )
     if (failures.length > 0) {
       log(`✗ ${failures.length} fixture(s) failed to render — their entries were left out of the manifest.`)