@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/plugins/mdx.ts

@@ -1,34 +1,53 @@
 /**
- * timber-mdx — Vite sub-plugin for MDX page rendering.
+ * timber-mdx — Vite sub-plugin for MDX and Markdown rendering.
  *
- * Wires @mdx-js/rollup into the Vite pipeline when MDX is activated.
+ * Wires vite-plugin-satteri into the Vite pipeline when MDX is activated.
  * MDX is activated when pageExtensions includes 'mdx' or 'md', or
  * when a content/ directory exists at the project root.
  *
+ * Satteri is a Rust-based Markdown/MDX compiler with a native Vite plugin:
+ * - `.mdx` files compile to React components (ES modules with real import
+ *   statements, so @vitejs/plugin-rsc client-boundary detection works).
+ * - `.md` files compile to modules exporting a rendered HTML string.
+ * - Frontmatter (YAML/TOML) parses natively and is emitted as a
+ *   `frontmatter` named export — no remark plugins needed.
+ * - GFM (tables, footnotes, strikethrough, task lists) is on by default.
+ *
+ * Extensibility is satteri's visitor-based plugin API (defineMdastPlugin /
+ * defineHastPlugin), not unified — the AST lives on the Rust side, so
+ * remark/rehype plugins cannot run. See design/20-content-collections.md.
+ *
  * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
  */
 
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import type { PluginContext } from '../plugin-context.ts';
+import { MDX_EXTENSIONS } from '../server/utils/mdx-file.ts';
 
-const MDX_EXTENSIONS = ['mdx', 'md'];
+const MDX_EXTENSIONS_UNDOTTED = [...MDX_EXTENSIONS].map((ext) => ext.slice(1));
 
 /**
- * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root.
+ * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
+ * or in src/. Root takes precedence, matching Next.js behavior.
  * Returns the absolute path if found, otherwise undefined.
  */
-function findMdxComponents(root: string): string | undefined {
+export function findMdxComponents(root: string): string | undefined {
   const candidates = [
     'mdx-components.tsx',
     'mdx-components.ts',
     'mdx-components.jsx',
     'mdx-components.js',
   ];
-  for (const name of candidates) {
-    const p = join(root, name);
-    if (existsSync(p)) return p;
+  const dirs = [root, join(root, 'src')];
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const p = join(dir, name);
+      if (existsSync(p)) return p;
+    }
   }
   return undefined;
 }
@@ -37,8 +56,14 @@ function findMdxComponents(root: string): string | undefined {
  * Determine if MDX should be activated based on config and project structure.
  */
 function shouldActivate(ctx: PluginContext): boolean {
+  // Explicit opt-out — the escape hatch for apps that register their own
+  // MDX compiler (e.g. @mdx-js/rollup for the unified pipeline) in
+  // vite.config.ts. Without this, a content/ directory would force
+  // activation no matter what pageExtensions says.
+  if (ctx.config.mdx === false) return false;
+
   const exts = ctx.config.pageExtensions;
-  if (exts && exts.some((ext) => MDX_EXTENSIONS.includes(ext))) {
+  if (exts && exts.some((ext) => MDX_EXTENSIONS_UNDOTTED.includes(ext))) {
     return true;
   }
 
@@ -50,15 +75,47 @@ function shouldActivate(ctx: PluginContext): boolean {
 }
 
 /**
- * Try to dynamically import a module by name. Returns the default export
- * or the module itself, or undefined if the module is not installed.
+ * Try to dynamically import a module by name, resolving from the user's
+ * project root rather than from `@timber-js/app`'s own location.
+ *
+ * Why this matters: pnpm only hoists declared (peer) dependencies into a
+ * package's resolution scope. The MDX integration's optional companions
+ * — `vite-plugin-satteri` and `satteri` — are installed as direct deps of
+ * the consumer (e.g. `packages/website`), not `@timber-js/app`. A bare
+ * `import('vite-plugin-satteri')` from inside this file resolves against
+ * `packages/timber-app/node_modules` and silently fails with
+ * `ERR_MODULE_NOT_FOUND` (TIM-840).
+ *
+ * Resolving relative to `projectRoot` (via `createRequire`) makes the
+ * lookup walk the consumer's `node_modules` tree first, which is where
+ * pnpm puts the user's deps.
+ *
+ * Returns the default export, the module itself, or undefined if the
+ * module is not installed.
  */
-async function tryImport(name: string): Promise<unknown | undefined> {
+async function tryImport(name: string, projectRoot: string): Promise<unknown | undefined> {
   try {
-    const mod = await import(name);
+    // Anchor resolution at the consumer's package.json so we walk their
+    // node_modules tree, not @timber-js/app's. createRequire().resolve()
+    // returns an absolute file path that ESM dynamic import accepts when
+    // wrapped as a file:// URL.
+    const require = createRequire(join(projectRoot, 'package.json'));
+    const resolved = require.resolve(name);
+    const mod = await import(pathToFileURL(resolved).href);
     return mod.default ?? mod;
   } catch {
-    return undefined;
+    // Fall back to a bare import — covers the rare case where the package
+    // lives next to @timber-js/app (e.g. monorepo with hoisted deps).
+    try {
+      const mod = await import(name);
+      return mod.default ?? mod;
+    } catch (e) {
+      console.debug(
+        `[timber] optional MDX dependency '${name}' not available:`,
+        e instanceof Error ? e.message : e
+      );
+      return undefined;
+    }
   }
 }
 
@@ -66,9 +123,10 @@ async function tryImport(name: string): Promise<unknown | undefined> {
  * Create the timber-mdx Vite plugin.
  *
  * Uses the transform and resolveId hooks to delegate MDX compilation
- * to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+ * to vite-plugin-satteri. The inner plugin is loaded lazily on first
+ * activation.
  *
- * Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+ * Hooks: buildStart (loads vite-plugin-satteri), resolveId, load, transform
  */
 export function timberMdx(ctx: PluginContext): Plugin {
   let innerPlugin: Plugin | null = null;
@@ -76,49 +134,60 @@ export function timberMdx(ctx: PluginContext): Plugin {
   async function activate(): Promise<void> {
     if (innerPlugin !== null || !shouldActivate(ctx)) return;
 
-    const createMdxPlugin = (await tryImport('@mdx-js/rollup')) as
+    // Satteri compiles .md to an HTML string, not a component — a page.md
+    // route would make the renderer invoke a string as a component and
+    // TypeError at request time. Fail at startup instead. Imported .md
+    // files work without listing 'md' in pageExtensions.
+    if (ctx.config.pageExtensions?.includes('md')) {
+      throw new Error(
+        [
+          "[timber] pageExtensions includes 'md', but .md route pages are not supported:",
+          'Markdown files compile to HTML strings, not components.',
+          '',
+          "Use .mdx for pages (pageExtensions: ['tsx', 'ts', 'mdx']).",
+          '.md files can still be imported as HTML strings — no pageExtensions entry needed.',
+        ].join('\n')
+      );
+    }
+
+    const createSatteriPlugin = (await tryImport('vite-plugin-satteri', ctx.root)) as
       | ((options?: Record<string, unknown>) => Plugin)
       | undefined;
 
-    if (!createMdxPlugin) {
+    if (!createSatteriPlugin) {
       throw new Error(
         [
-          '[timber] MDX is enabled but @mdx-js/rollup is not installed.',
+          '[timber] MDX is enabled but vite-plugin-satteri is not installed.',
           '',
           'Install it:',
-          '  pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter',
+          '  pnpm add -D vite-plugin-satteri satteri',
           '',
           'MDX is activated because pageExtensions includes "mdx"/"md" or a content/ directory exists.',
         ].join('\n')
       );
     }
 
-    const mdxConfig = ctx.config.mdx ?? {};
-
-    // Auto-register frontmatter plugins
-    const remarkPlugins: unknown[] = [];
-    const remarkFrontmatter = await tryImport('remark-frontmatter');
-    const remarkMdxFrontmatter = await tryImport('remark-mdx-frontmatter');
-    if (remarkFrontmatter) remarkPlugins.push(remarkFrontmatter);
-    if (remarkMdxFrontmatter) remarkPlugins.push(remarkMdxFrontmatter);
-
-    if (mdxConfig.remarkPlugins) {
-      remarkPlugins.push(...mdxConfig.remarkPlugins);
-    }
+    // `|| {}` (not `??`): mdx can be `false`, though shouldActivate() has
+    // already bailed in that case.
+    const mdxConfig = ctx.config.mdx || {};
 
-    const mdxOptions: Record<string, unknown> = {
-      remarkPlugins,
-      rehypePlugins: mdxConfig.rehypePlugins ?? [],
-      recmaPlugins: mdxConfig.recmaPlugins ?? [],
-      remarkRehypeOptions: mdxConfig.remarkRehypeOptions,
-    };
+    // We pass `development` explicitly (satteri otherwise infers it from
+    // Vite's command via its own configResolved hook, which we don't
+    // delegate) and control providerImportSource — the mdx-components.tsx
+    // convention belongs to the framework, not the user config.
+    const mdxOptions: Record<string, unknown> = { development: ctx.dev };
 
     const mdxComponentsPath = findMdxComponents(ctx.root);
     if (mdxComponentsPath) {
       mdxOptions.providerImportSource = mdxComponentsPath;
     }
 
-    innerPlugin = createMdxPlugin(mdxOptions);
+    innerPlugin = createSatteriPlugin({
+      mdx: mdxOptions,
+      ...(mdxConfig.mdastPlugins ? { mdastPlugins: mdxConfig.mdastPlugins } : {}),
+      ...(mdxConfig.hastPlugins ? { hastPlugins: mdxConfig.hastPlugins } : {}),
+      ...(mdxConfig.features ? { features: mdxConfig.features } : {}),
+    });
   }
 
   return {
@@ -167,6 +236,13 @@ export function timberMdx(ctx: PluginContext): Plugin {
 
     async transform(code, id) {
       if (!innerPlugin) return null;
+      // Ids with a Vite query (?raw, ?url, ?import) are asset requests, not
+      // modules to compile. vite-plugin-satteri's id regexes match them, but
+      // by the time this transform runs the code is already the asset module
+      // (e.g. `export default "<file text>"` for ?raw) — compiling that as
+      // markdown corrupts it. @mdx-js/rollup matched by extname and skipped
+      // queried ids; preserve that behavior.
+      if (id.includes('?')) return null;
       const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
       if (envName && envName !== 'rsc') return null;
       if (typeof innerPlugin.transform === 'function') {

package/src/plugins/prebuilt-capture.ts

@@ -0,0 +1,217 @@
+/**
+ * Post-build prebuilt capture — Node-side orchestration (TIM-1119).
+ *
+ * Runs from timber-prebuilt's `buildApp` post hook, after Vite's 5-step
+ * build sequence. Imports the BUILT `rsc/index.js` (the bundle carries
+ * the react-server condition resolved at build time, so a plain dynamic
+ * import works) and calls its `__timber_capturePrebuilt` export — the
+ * capture itself must run inside the bundle's module graph, where the
+ * component registry and flight renderer live. See
+ * server/prebuilt-builder.ts and design/44-render-at-build-time.md
+ * §Build Phase.
+ *
+ * This side owns PERSISTENCE: each captured payload is written to
+ * `.timber/dist/prebuilt/<componentId>/<cacheKey>.flight` atomically
+ * (temp file + rename — a crashed build never leaves a torn artifact
+ * under its final name), and `manifest.json` is written last, only after
+ * every payload it references is fully on disk. Keeping node:fs on the
+ * plugin side keeps it out of the server bundle, which must also run on
+ * Cloudflare Workers.
+ *
+ * NOTE: importing the built entry runs the app's production startup —
+ * instrumentation.ts register() and the configured cache handler load
+ * inside the build process. That is by design (prebuilt components may
+ * call timber.cache), and it only happens when the app actually declares
+ * prebuilt components.
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { PluginContext } from '../plugin-context.ts';
+import type { CaptureOptions, CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.ts';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.ts';
+
+// ─── Artifact writer ──────────────────────────────────────────────────────
+
+/**
+ * Both patterns are framework-generated (plugins/prebuilt.ts assigns IDs,
+ * server/prebuilt/cache-key.ts hashes keys), so a mismatch is a framework
+ * bug or a tampered registry — either way it must never reach a path join.
+ */
+const COMPONENT_ID_RE = /^[a-z0-9]+_[0-9a-f]{16}$/;
+const CACHE_KEY_RE = /^[0-9a-f]{16}$/;
+
+export interface PrebuiltArtifactWriter {
+  write(entry: CapturedEntry): Promise<void>;
+  /** Write manifest.json (if any entries exist). Returns the entry count. */
+  finalize(): Promise<number>;
+}
+
+/** Write a file atomically: temp sibling + rename. */
+async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, data);
+  await rename(tmp, path);
+}
+
+/**
+ * Create the writer for `.timber/dist/prebuilt/`. Storage layout per
+ * design/44 §Storage: one directory per component ID, one `.flight` file
+ * per cache key, one manifest.json mapping componentId + key → file +
+ * metadata.
+ */
+export function createPrebuiltArtifactWriter(prebuiltDir: string): PrebuiltArtifactWriter {
+  const manifest: PrebuiltManifest = {};
+  const buildTimestamp = Date.now();
+  let count = 0;
+
+  return {
+    async write(entry: CapturedEntry): Promise<void> {
+      if (!COMPONENT_ID_RE.test(entry.componentId) || !CACHE_KEY_RE.test(entry.cacheKey)) {
+        throw new Error(
+          `[timber] prebuilt artifact writer received a malformed identity ` +
+            `(componentId: ${JSON.stringify(entry.componentId)}, cacheKey: ` +
+            `${JSON.stringify(entry.cacheKey)}) — refusing to write`
+        );
+      }
+      const relativeFile = `${entry.componentId}/${entry.cacheKey}.flight`;
+      const path = join(prebuiltDir, relativeFile);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFileAtomic(path, entry.bytes);
+
+      manifest[entry.componentId] ??= { entries: {} };
+      if (entry.paramIndependent) manifest[entry.componentId].paramIndependent = true;
+      manifest[entry.componentId].entries[entry.cacheKey] = {
+        params: entry.params,
+        file: relativeFile,
+        bytes: entry.bytes.byteLength,
+        buildTimestamp,
+        ...(entry.tags ? { tags: entry.tags } : {}),
+      };
+      count++;
+    },
+
+    async finalize(): Promise<number> {
+      if (count === 0) return 0;
+      await writeFileAtomic(
+        join(prebuiltDir, 'manifest.json'),
+        JSON.stringify(manifest, null, 2) + '\n'
+      );
+      return count;
+    },
+  };
+}
+
+/**
+ * Remove any `prebuilt/` output left by a previous build in this
+ * directory (watch mode, `emptyOutDir: false`). A stale manifest would
+ * make adapters ship payloads from an OLD build — reviving them serves
+ * outdated content with that build's chunk references instead of the
+ * intended miss → live render. Runs unconditionally at the start of the
+ * post-build hook, BEFORE the capture decision: a build whose app no
+ * longer declares any prebuilt components must also shed the artifacts
+ * (codex P2 on PR #836).
+ */
+export async function cleanPrebuiltDir(buildDir: string): Promise<void> {
+  await rm(join(buildDir, 'prebuilt'), { recursive: true, force: true });
+}
+
+// ─── Capture orchestration ────────────────────────────────────────────────
+
+/** Shape of the built RSC entry's capture export. */
+interface CaptureModule {
+  __timber_capturePrebuilt?: (options: CaptureOptions) => Promise<CaptureSummary>;
+}
+
+/**
+ * Load the built RSC entry and run the capture pass. Throws (failing the
+ * build) on infrastructure errors — missing/unloadable entry — and on
+ * dynamic-context hard errors (cookies()/headers() in a prerendered
+ * component). Per-entry data errors skip-and-report per design/44
+ * §Build-Phase Error Handling.
+ */
+export async function runPrebuiltCapture(ctx: PluginContext): Promise<CaptureSummary> {
+  const routeComponents = ctx.routePrebuiltComponents;
+  if (!routeComponents || routeComponents.size === 0) {
+    return { captured: 0, skipped: [], hardErrors: [], nestingWarnings: 0 };
+  }
+
+  const entryPath = join(ctx.buildDir, 'rsc', 'index.js');
+  if (!existsSync(entryPath)) {
+    throw new Error(
+      `[timber] prebuilt capture: built RSC entry not found at ${entryPath} — ` +
+        `the app declares cache.component({ prerender: true }) call sites but the ` +
+        `RSC build output is missing`
+    );
+  }
+
+  // The same globals the adapter entry sets before importing the handler
+  // (adapter-build.ts). The bundle's virtual:timber-build-manifest falls
+  // back to an empty manifest, but set the real values when available so
+  // capture-time behavior matches production startup.
+  const g = globalThis as Record<string, unknown>;
+  if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
+  if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
+
+  console.log('[timber] cache.component: capturing prebuilt flight payloads…');
+
+  // Tell the RSC entry to skip createRequestHandler — the capture pass
+  // only needs __timber_capturePrebuilt + the route manifest. Running the
+  // full production startup (instrumentation, cache handler, CDN purge,
+  // OTEL tracing, route matchers) is wasted work that can take 100+ seconds
+  // on large apps.
+  g.__TIMBER_CAPTURE_MODE__ = true;
+
+  let mod: CaptureModule;
+  try {
+    // Cache-busting query: in a long-lived build process (vite build
+    // --watch), a bare file URL would return the FIRST build's module from
+    // the ESM cache — stale code and a stale (already-walked) registry.
+    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+    mod = (await import(/* @vite-ignore */ entryUrl)) as CaptureModule;
+  } catch (error) {
+    throw new Error(
+      `[timber] prebuilt capture: failed to load the built RSC entry (${entryPath}). ` +
+        `The capture pass runs the production server module inside the build process — ` +
+        `its startup must succeed for prerendering to work.`,
+      { cause: error }
+    );
+  }
+  const capture = mod.__timber_capturePrebuilt;
+  if (typeof capture !== 'function') {
+    throw new Error(
+      `[timber] prebuilt capture: built RSC entry does not export __timber_capturePrebuilt — ` +
+        `the build output predates this framework version; rebuild from a clean .timber/dist`
+    );
+  }
+
+  const writer = createPrebuiltArtifactWriter(join(ctx.buildDir, 'prebuilt'));
+  const summary = await capture({
+    fileComponentMap: Object.fromEntries(routeComponents),
+    callSiteProps: ctx.prebuiltCallSiteProps
+      ? Object.fromEntries(ctx.prebuiltCallSiteProps)
+      : undefined,
+    lazyChunks: ctx.prebuiltLazyChunks ? Object.fromEntries(ctx.prebuiltLazyChunks) : undefined,
+    onEntry: (entry) => writer.write(entry),
+  });
+
+  if (summary.hardErrors.length > 0) {
+    const details = summary.hardErrors.map((issue) => `  - ${issue.message}`).join('\n');
+    throw new Error(
+      `[timber] prebuilt capture failed: ${summary.hardErrors.length} component(s) read ` +
+        `per-request context at build time:\n${details}`
+    );
+  }
+
+  await writer.finalize();
+
+  const total = summary.captured + summary.skipped.length;
+  console.log(
+    `[timber] Prebuilt ${summary.captured}/${total} entries.` +
+      (summary.skipped.length > 0 ? ` ${summary.skipped.length} skipped due to errors.` : '')
+  );
+  return summary;
+}

package/src/plugins/prebuilt-options-analysis.ts

@@ -0,0 +1,175 @@
+/**
+ * Static analysis of `cache.component(fn, options)` option literals for
+ * the timber-prebuilt transform: can this call site's options put the
+ * component in the prerender tier?
+ *
+ * Runtime-tier call sites must do NO build work — recording them would
+ * make the post-build hook import the built RSC entry (running production
+ * startup) and load route modules for routes that have nothing to
+ * prerender (codex P2 on PR #836). The analysis is conservative in one
+ * direction only: over-inclusion costs a wasted entry load (the capture
+ * pass re-checks the real options at runtime and skips), under-inclusion
+ * would silently skip prerendering.
+ */
+
+import type { CallExpressionNode, PositionedNode } from './callsite-ast.ts';
+
+const EXPRESSION_WRAPPER_TYPES = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+/** Unwrap TS expression wrappers (`as`, `satisfies`, `!`, parens). */
+export function unwrapExpression(node: PositionedNode): PositionedNode {
+  let current = node;
+  while (EXPRESSION_WRAPPER_TYPES.has(current.type) && current.expression) {
+    current = current.expression as PositionedNode;
+  }
+  return current;
+}
+
+interface ObjectPropertyNode extends PositionedNode {
+  type: 'Property';
+  computed?: boolean;
+  key: PositionedNode & { name?: string; value?: unknown };
+  value: PositionedNode & { value?: unknown };
+}
+
+/** Three-state static knowledge about a property's runtime effect. */
+type Tri = 'yes' | 'no' | 'unknown';
+
+/**
+ * Statically classify a `slots` value node against resolveSlotNames'
+ * runtime rules (server/prebuilt/slots.ts):
+ *
+ * - `yes` — certainly an ACTIVE shape: dense, non-empty array literal of
+ *   non-empty string literals.
+ * - `no` — certainly NOT active (absent/empty/malformed): registration
+ *   falls back to non-slot semantics with `prerender` preserved.
+ * - `unknown` — identifiers, spreads, holes, non-literal elements.
+ */
+function classifySlotsValue(node: PositionedNode): Tri {
+  const value = unwrapExpression(node);
+  if (value.type === 'ArrayExpression') {
+    const elements = ((value as unknown as { elements: (PositionedNode | null)[] }).elements ??
+      []) as (PositionedNode | null)[];
+    if (elements.length === 0) return 'no'; // empty → kind 'none'
+    let allValidStrings = true;
+    for (const el of elements) {
+      if (el === null) return 'no'; // hole → sparse → malformed at runtime
+      if (el.type === 'SpreadElement') return 'unknown';
+      const entry = unwrapExpression(el) as { type: string; value?: unknown };
+      if (entry.type !== 'Literal') {
+        allValidStrings = false; // could still be a valid string at runtime
+        continue;
+      }
+      if (typeof entry.value !== 'string' || entry.value.length === 0) {
+        return 'no'; // a non-string/empty literal is malformed regardless of the rest
+      }
+    }
+    return allValidStrings ? 'yes' : 'unknown';
+  }
+  if (value.type === 'Literal') return 'no'; // null / primitive → malformed → disabled
+  if (value.type === 'Identifier' && (value as { name?: string }).name === 'undefined') {
+    return 'no'; // absent
+  }
+  return 'unknown';
+}
+
+/** Statically classify whether a `ttl` value gives a runtime lifetime (`ttl !== undefined`). */
+function classifyTtlValue(node: PositionedNode): Tri {
+  const value = unwrapExpression(node);
+  if (value.type === 'Literal') return 'yes'; // any literal (number, null, …) !== undefined
+  if (value.type === 'Identifier' && (value as { name?: string }).name === 'undefined') return 'no';
+  return 'unknown';
+}
+
+/** Statically classify whether a `tags` value gives a runtime lifetime (`tags != null`). */
+function classifyTagsValue(node: PositionedNode): Tri {
+  const value = unwrapExpression(node);
+  if (value.type === 'ArrayExpression') return 'yes';
+  if (value.type === 'ArrowFunctionExpression' || value.type === 'FunctionExpression') return 'yes';
+  if (value.type === 'Literal') {
+    return (value as { value?: unknown }).value === null ? 'no' : 'yes';
+  }
+  if (value.type === 'Identifier' && (value as { name?: string }).name === 'undefined') return 'no';
+  return 'unknown';
+}
+
+/**
+ * Can this call site's options put the component in the prerender tier?
+ * The answer is static only when the options argument is an object
+ * literal:
+ *
+ *   - literal with `prerender: true`            → yes
+ *   - literal with `prerender: false`/absent    → no  (spread-free)
+ *   - literal with statically ACTIVE `slots` + certain runtime lifetime
+ *     → no — registration strips `prerender` for active slot components
+ *       (TIM-1173), so attributing the callsite would make the post-build
+ *       hook import the RSC entry and enumerate route params for entries
+ *       the capture pass then skips (codex P2 on PR #890)
+ *   - anything else (identifier, spread, non-literal values)
+ *     → conservatively yes — the capture pass re-checks at runtime
+ *
+ * Properties walk in source order with last-write-wins, mirroring
+ * object-literal evaluation: `{ prerender: false, ...opts }` may end up
+ * prerenderable (the spread can override), while `{ ...opts,
+ * prerender: false }` is statically false (codex P2 on PR #836).
+ * Computed keys are treated like spreads — they may evaluate to any of
+ * the tracked names.
+ */
+export function mayPrerender(call: CallExpressionNode): boolean {
+  if (call.arguments.length < 2) return false; // no options → no lifetime → never prerender
+  const options = unwrapExpression(call.arguments[1] as PositionedNode);
+  if (options.type !== 'ObjectExpression') return true;
+  const properties = (options as unknown as { properties: PositionedNode[] }).properties ?? [];
+
+  type Verdict = 'absent' | 'true' | 'false' | 'unknown';
+  let verdict: Verdict = 'absent';
+  let slotsActive: Tri = 'no'; // absent slots are certainly not active
+  let ttl: Tri = 'no';
+  let tags: Tri = 'no';
+
+  for (const prop of properties) {
+    if (prop.type === 'SpreadElement' || (prop as ObjectPropertyNode).computed) {
+      // A spread/computed key may write ANY of the tracked options.
+      verdict = 'unknown';
+      slotsActive = 'unknown';
+      ttl = 'unknown';
+      tags = 'unknown';
+      continue;
+    }
+    if (prop.type !== 'Property') continue;
+    const property = prop as ObjectPropertyNode;
+    const keyName =
+      property.key.type === 'Identifier'
+        ? property.key.name
+        : property.key.type === 'Literal'
+          ? String(property.key.value)
+          : undefined;
+    if (keyName === 'prerender') {
+      const value = unwrapExpression(property.value);
+      if (value.type === 'Literal') {
+        verdict = (value as { value?: unknown }).value === true ? 'true' : 'false';
+      } else {
+        verdict = 'unknown'; // `prerender: flag` — not statically known
+      }
+    } else if (keyName === 'slots') {
+      slotsActive = classifySlotsValue(property.value);
+    } else if (keyName === 'ttl') {
+      ttl = classifyTtlValue(property.value);
+    } else if (keyName === 'tags') {
+      tags = classifyTagsValue(property.value);
+    }
+  }
+
+  if (verdict !== 'true' && verdict !== 'unknown') return false;
+  // Active slots + certain runtime lifetime → registration strips
+  // prerender, so the callsite is certainly runtime-tier. Any uncertainty
+  // (slots or lifetime not statically known) keeps the conservative
+  // attribution.
+  if (slotsActive === 'yes' && (ttl === 'yes' || tags === 'yes')) return false;
+  return true;
+}