@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/plugins/callsite-jsx.ts

@@ -0,0 +1,243 @@
+/**
+ * JSX call-site props extraction for prebuilt components (TIM-1142).
+ *
+ * At build time, the timber-prebuilt transform captures the exact props
+ * from each JSX usage site of a cache.component binding so the post-build
+ * capture pass can prerender entries for each distinct prop set. Only
+ * statically analyzable props (JSON-safe literals, arrays, and plain
+ * objects) are captured; dynamic/computed props bail — those call sites
+ * fall back to live rendering per design/44 §Props Derivation.
+ *
+ * See design/44-render-at-build-time.md §Props Derivation at Build Time.
+ */
+
+import type { PluginContext } from '../plugin-context.ts';
+import type { IdentifierNode, PositionedNode, ProgramNode } from './callsite-ast.ts';
+
+interface JSXElementNode extends PositionedNode {
+  type: 'JSXElement';
+  openingElement: {
+    type: 'JSXOpeningElement';
+    name: PositionedNode;
+    attributes: PositionedNode[];
+  };
+}
+
+interface JSXAttributeNode extends PositionedNode {
+  type: 'JSXAttribute';
+  name: { type: string; name?: string };
+  value: PositionedNode | null;
+}
+
+interface JSXExpressionContainerNode extends PositionedNode {
+  type: 'JSXExpressionContainer';
+  expression: PositionedNode;
+}
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * Try to extract a static JSON-safe value from an AST expression node.
+ * Returns `undefined` (not null — null is a valid JSON value) when the
+ * expression is dynamic/computed and cannot be captured statically.
+ */
+function tryExtractStaticValue(node: PositionedNode): JsonValue | undefined {
+  if (node.type === 'Literal') {
+    const val = (node as { value?: unknown }).value;
+    if (
+      val === null ||
+      typeof val === 'string' ||
+      typeof val === 'number' ||
+      typeof val === 'boolean'
+    ) {
+      return val as JsonValue;
+    }
+    return undefined; // regex or bigint literal
+  }
+  if (node.type === 'UnaryExpression') {
+    const unary = node as unknown as { operator: string; argument: PositionedNode };
+    if (unary.operator === '-' && unary.argument.type === 'Literal') {
+      const val = (unary.argument as { value?: unknown }).value;
+      if (typeof val === 'number') return -val;
+    }
+    return undefined;
+  }
+  if (node.type === 'TemplateLiteral') {
+    const tpl = node as unknown as {
+      quasis: { value: { cooked: string } }[];
+      expressions: unknown[];
+    };
+    if (tpl.expressions.length === 0) return tpl.quasis[0]?.value.cooked ?? undefined;
+    return undefined;
+  }
+  if (node.type === 'ArrayExpression') {
+    const elements = (node as unknown as { elements: (PositionedNode | null)[] }).elements;
+    const arr: JsonValue[] = [];
+    for (const el of elements) {
+      if (el === null) return undefined; // sparse
+      const val = tryExtractStaticValue(el);
+      if (val === undefined) return undefined;
+      arr.push(val);
+    }
+    return arr;
+  }
+  if (node.type === 'ObjectExpression') {
+    const properties = (node as unknown as { properties: PositionedNode[] }).properties;
+    const obj: Record<string, JsonValue> = {};
+    for (const prop of properties) {
+      if (prop.type === 'SpreadElement') return undefined;
+      if (prop.type !== 'Property') return undefined;
+      const p = prop as unknown as {
+        computed?: boolean;
+        key: PositionedNode & { name?: string; value?: unknown };
+        value: PositionedNode;
+      };
+      if (p.computed) return undefined;
+      const keyName =
+        p.key.type === 'Identifier'
+          ? p.key.name
+          : p.key.type === 'Literal'
+            ? String(p.key.value)
+            : undefined;
+      if (keyName === undefined) return undefined;
+      const val = tryExtractStaticValue(p.value);
+      if (val === undefined) return undefined;
+      obj[keyName] = val;
+    }
+    return obj;
+  }
+  return undefined;
+}
+
+/**
+ * Extract static props from a JSX element's attributes. Returns null if
+ * any attribute is dynamic (spread, computed expression, JSX element, etc.)
+ * — the component must fall back to dynamic rendering for that call site.
+ */
+export function extractStaticJsxProps(
+  attributes: PositionedNode[]
+): Record<string, JsonValue> | null {
+  const props: Record<string, JsonValue> = {};
+  for (const attr of attributes) {
+    if (attr.type === 'JSXSpreadAttribute') return null;
+    if (attr.type !== 'JSXAttribute') return null;
+    const jsxAttr = attr as unknown as JSXAttributeNode;
+    const name = jsxAttr.name?.name;
+    if (!name) return null;
+    // React strips key and ref before passing to component props — including
+    // them would produce cache entries unaddressable at request time.
+    if (name === 'key' || name === 'ref') continue;
+    if (jsxAttr.value === null) {
+      props[name] = true;
+      continue;
+    }
+    if (jsxAttr.value.type === 'Literal') {
+      const val = tryExtractStaticValue(jsxAttr.value);
+      if (val === undefined) return null;
+      props[name] = val;
+      continue;
+    }
+    if (jsxAttr.value.type === 'JSXExpressionContainer') {
+      const container = jsxAttr.value as unknown as JSXExpressionContainerNode;
+      const val = tryExtractStaticValue(container.expression);
+      if (val === undefined) return null;
+      props[name] = val;
+      continue;
+    }
+    return null;
+  }
+  return props;
+}
+
+/**
+ * Walk an AST tree and collect JSX usages of the given binding names,
+ * returning the static props for each usage. Returns a map of
+ * bindingName → array of static prop objects (or null for dynamic props).
+ */
+export function collectJsxUsages(
+  program: ProgramNode,
+  bindingNames: Set<string>
+): Map<string, Array<Record<string, JsonValue> | null>> {
+  const result = new Map<string, Array<Record<string, JsonValue> | null>>();
+  const walk = (node: unknown) => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as PositionedNode;
+    if (n.type === 'JSXElement') {
+      const jsx = n as unknown as JSXElementNode;
+      const tagName = jsx.openingElement.name;
+      if (tagName.type === 'JSXIdentifier') {
+        const name = (tagName as IdentifierNode).name;
+        if (bindingNames.has(name)) {
+          // Children become props.children at runtime — if the element has
+          // children we can't capture the full props shape statically, so
+          // treat it as a dynamic call site (bail to null).
+          const children = (jsx as unknown as { children?: unknown[] }).children ?? [];
+          const hasChildren =
+            children.length > 0 &&
+            children.some((c: unknown) => {
+              const child = c as PositionedNode;
+              if (child.type === 'JSXText') {
+                // Whitespace-only text nodes are not passed as children
+                return (child as unknown as { value: string }).value.trim().length > 0;
+              }
+              return true;
+            });
+          const props = hasChildren ? null : extractStaticJsxProps(jsx.openingElement.attributes);
+          const usages = result.get(name) ?? [];
+          usages.push(props);
+          result.set(name, usages);
+        }
+      }
+    }
+    for (const value of Object.values(n)) {
+      if (Array.isArray(value)) {
+        for (const item of value) walk(item);
+      } else if (value && typeof value === 'object' && 'type' in value) {
+        walk(value);
+      }
+    }
+  };
+  for (const stmt of program.body) walk(stmt);
+  return result;
+}
+
+/**
+ * Deep stable JSON stringification with recursively sorted keys.
+ * `JSON.stringify` with an array replacer only includes listed keys at
+ * ALL nesting levels, so `{config:{theme:'dark'}}` and
+ * `{config:{theme:'light'}}` would both serialize as `{"config":{}}`.
+ */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  const obj = value as Record<string, unknown>;
+  const parts = Object.keys(obj)
+    .sort()
+    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]));
+  return '{' + parts.join(',') + '}';
+}
+
+/**
+ * Add a distinct props object to the call-site-props map for a component,
+ * deduplicating by deep JSON value (recursively sorted keys).
+ */
+export function recordCallSiteProps(
+  ctx: PluginContext,
+  componentId: string,
+  props: Record<string, JsonValue>
+): void {
+  ctx.prebuiltCallSiteProps ??= new Map();
+  const existing = ctx.prebuiltCallSiteProps.get(componentId) ?? [];
+  const canonical = stableStringify(props);
+  const isDuplicate = existing.some((p) => stableStringify(p) === canonical);
+  if (!isDuplicate) {
+    existing.push(props);
+    ctx.prebuiltCallSiteProps.set(componentId, existing);
+  }
+}

package/src/plugins/chunks.ts

@@ -13,10 +13,16 @@
  *   - Per-route chunks (page/layout components, only when route-specific)
  *   - rolldown-runtime (Rolldown's own output, unavoidable)
  *
+ * Additionally, this plugin builds a facade ancestry map during the RSC
+ * build so that `clientChunkGroup` can reclassify `shared:` client
+ * references that are only consumed by a single route boundary.
+ * See TIM-1107, design/27-chunking-strategy.md.
+ *
  * Design docs: 27-chunking-strategy.md
  */
 
-import type { Plugin } from 'vite';
+import type { Plugin, Rollup } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
 
 /**
  * Check if a module is part of the timber framework runtime.
@@ -36,12 +42,71 @@ export function isTimberRuntime(id: string): boolean {
   );
 }
 
+type OutputChunk = Rollup.OutputChunk;
+
+/**
+ * Build a map from absolute module IDs in non-facade RSC chunks to the
+ * absolute facade module paths that transitively import them.
+ *
+ * Used by `clientChunkGroup` to reclassify `shared:` client references
+ * that are only consumed by a single route boundary (TIM-1107).
+ */
+function buildFacadeAncestryMap(bundle: Rollup.OutputBundle): Map<string, string[]> {
+  const chunks = new Map<string, OutputChunk>();
+  for (const [file, asset] of Object.entries(bundle)) {
+    if (asset.type === 'chunk') chunks.set(file, asset);
+  }
+
+  // Reverse import graph: which chunks import this chunk file?
+  const importedBy = new Map<string, string[]>();
+  for (const [file, chunk] of chunks) {
+    for (const imp of chunk.imports) {
+      let parents = importedBy.get(imp);
+      if (!parents) {
+        parents = [];
+        importedBy.set(imp, parents);
+      }
+      parents.push(file);
+    }
+  }
+
+  // Trace upward from a chunk to find all facade modules that consume it
+  function facadeAncestors(file: string, visited: Set<string>): string[] {
+    if (visited.has(file)) return [];
+    visited.add(file);
+    const chunk = chunks.get(file);
+    if (!chunk) return [];
+    if (chunk.facadeModuleId) return [chunk.facadeModuleId];
+    const parents = importedBy.get(file) ?? [];
+    const result: string[] = [];
+    for (const p of parents) {
+      for (const f of facadeAncestors(p, visited)) result.push(f);
+    }
+    return result;
+  }
+
+  const moduleToFacades = new Map<string, string[]>();
+  for (const [file, chunk] of chunks) {
+    if (chunk.facadeModuleId) continue;
+    const facades = facadeAncestors(file, new Set());
+    if (facades.length === 0) continue;
+    // Deduplicate facades
+    const unique = [...new Set(facades)];
+    for (const modId of chunk.moduleIds) {
+      moduleToFacades.set(modId, unique);
+    }
+  }
+
+  return moduleToFacades;
+}
+
 /**
  * Create the timber-chunks Vite plugin.
  *
- * Currently a no-op — Rolldown's default splitting produces the desired
- * output (one main bundle + per-route chunks). The plugin is retained as
- * a hook point for future chunking adjustments.
+ * Rolldown's default splitting produces the desired output (one main
+ * bundle + per-route chunks). This plugin's main job is building the
+ * facade ancestry map during the RSC build so `clientChunkGroup` can
+ * reclassify shared client references to their correct route boundary.
  *
  * NOTE: Ideally we'd use Rolldown's `format: 'app'` (module registry format)
  * which guarantees single-copy module semantics like webpack/Turbopack.
@@ -51,8 +116,12 @@ export function isTimberRuntime(id: string): boolean {
  *
  * Design docs: 27-chunking-strategy.md
  */
-export function timberChunks(): Plugin {
+export function timberChunks(ctx: PluginContext): Plugin {
   return {
     name: 'timber-chunks',
+    generateBundle(_options, bundle) {
+      if (this.environment?.name !== 'rsc') return;
+      ctx.sharedModuleFacades = buildFacadeAncestryMap(bundle);
+    },
   };
 }

package/src/plugins/client-chunks.ts

@@ -0,0 +1,185 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by the **consuming route's** layout boundary
+ * (derived from `meta.serverChunk`), not by the module's own file location.
+ * This ensures components in shared directories (e.g. `components/`) land in
+ * the chunk of the route that uses them, not in a single catch-all chunk.
+ *
+ * For `shared:` modules (client references in non-facade RSC chunks), the
+ * function consults a facade ancestry map built during the RSC build. If all
+ * consuming facades belong to the same route boundary, the module is
+ * reclassified to that boundary instead of falling through to `client-shared`.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499, TIM-1104, TIM-1107.
+ */
+
+import { relative } from 'node:path';
+
+/**
+ * Check whether a root-relative path lives under the app directory,
+ * and if so return the first non-group route segment.
+ *
+ * `appPrefix` is the root-relative app directory with a trailing slash
+ * (e.g. "app/" or "src/app/"), computed once from the resolved appDir
+ * and root. Matching uses `startsWith` — no ambiguity.
+ *
+ * Returns:
+ *   { inApp: false }                       — path is not under app/
+ *   { inApp: true, segment: null }         — root of app/ (e.g. app/layout.tsx)
+ *   { inApp: true, segment: "dashboard" }  — nested route boundary
+ */
+function findAppBoundary(
+  path: string,
+  appPrefix: string
+): { inApp: false } | { inApp: true; segment: string | null } {
+  const relPath = path.replace(/\\/g, '/');
+  if (!relPath.startsWith(appPrefix)) return { inApp: false };
+
+  const withinApp = relPath.slice(appPrefix.length);
+  const segments = withinApp.split('/');
+
+  for (const seg of segments) {
+    if (seg.includes('.')) break;
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    return { inApp: true, segment: seg };
+  }
+
+  return { inApp: true, segment: null };
+}
+
+/**
+ * Check if a string is a bare import specifier (package name, not a path).
+ * Bare specifiers don't start with `.`, `/`, or contain `:/`.
+ */
+function isBareSpecifier(id: string): boolean {
+  return !id.startsWith('.') && !id.startsWith('/') && !id.includes(':/');
+}
+
+/**
+ * Look up facade ancestors for a module ID, handling bare package specifiers.
+ *
+ * The facade ancestry map is keyed by absolute resolved paths (from Rollup's
+ * moduleIds), but the RSC plugin passes bare package names (e.g. 'streamdown')
+ * as meta.id for npm package client references (TIM-1108). When a direct
+ * lookup misses and the id is a bare specifier, scan map keys for a matching
+ * node_modules path.
+ */
+function lookupFacades(
+  id: string,
+  sharedModuleFacades: Map<string, string[]>
+): string[] | undefined {
+  const direct = sharedModuleFacades.get(id);
+  if (direct) return direct;
+
+  if (!isBareSpecifier(id)) return undefined;
+
+  // Bare specifier: match against node_modules/<name>/ in map keys.
+  // Scoped packages use @scope/name, unscoped use just name.
+  // A package may have multiple module IDs in the RSC bundle (e.g. main
+  // entry + re-exported submodules), so aggregate facades from all matches.
+  const needle = `/node_modules/${id}/`;
+  let merged: string[] | undefined;
+  for (const [key, facades] of sharedModuleFacades) {
+    if (key.includes(needle)) {
+      if (!merged) merged = [...facades];
+      else merged.push(...facades);
+    }
+  }
+  return merged;
+}
+
+/**
+ * For a `shared:` client reference, check the facade ancestry map to
+ * see if all consuming facades belong to the same route boundary.
+ * Returns the boundary segment name, or null if the module is
+ * genuinely shared across multiple boundaries.
+ */
+function reclassifySharedModule(
+  meta: { id: string; normalizedId: string },
+  appPrefix: string,
+  root: string,
+  sharedModuleFacades: Map<string, string[]>
+): string | null {
+  const facades = lookupFacades(meta.id, sharedModuleFacades);
+  if (!facades || facades.length === 0) return null;
+
+  const boundaries = new Set<string>();
+  for (const facade of facades) {
+    const relFacade = relative(root, facade).replace(/\\/g, '/');
+    const result = findAppBoundary(relFacade, appPrefix);
+    if (result.inApp && result.segment) {
+      boundaries.add(result.segment);
+    } else if (result.inApp) {
+      // Root-level facade — module is used at root, keep shared
+      return null;
+    } else {
+      // Facade outside app/ (e.g. src/posts/foo.mdx) — can't derive a
+      // safe common boundary, so keep shared to avoid pulling outside-app
+      // deps into a route chunk they don't belong to.
+      return null;
+    }
+  }
+
+  if (boundaries.size === 1) return [...boundaries][0];
+  return null;
+}
+
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Always derives the group from the **consuming route** (`serverChunk`'s
+ * facade path), not from the module's own file location. This prevents
+ * components in shared directories (e.g. `app/components/`, `src/lib/`)
+ * from collapsing into a single chunk when they're only used by one route.
+ *
+ * For `shared:` modules (non-facade RSC chunks), consults the facade
+ * ancestry map to reclassify modules that are only consumed by a single
+ * route boundary. This prevents large dependencies from polluting
+ * `client-shared` when they're route-scoped (TIM-1107).
+ *
+ * Examples:
+ *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+ *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+ *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+ *   - `shared:...` (shared across chunks) → reclassified or `"client-shared"`
+ */
+export function clientChunkGroup(
+  meta: { id: string; normalizedId: string; serverChunk: string },
+  appDir: string,
+  root: string,
+  sharedModuleFacades?: Map<string, string[]>
+): string {
+  const { serverChunk } = meta;
+
+  // Compute the root-relative app directory prefix once. Both normalizedId
+  // and serverChunk paths from the RSC plugin are root-relative (via
+  // path.relative(root, absoluteId)), so this prefix matches exactly —
+  // no ambiguity with content directories that happen to share a name.
+  const appPrefix = relative(root, appDir).replace(/\\/g, '/') + '/';
+
+  if (serverChunk.startsWith('shared:')) {
+    if (sharedModuleFacades) {
+      const boundary = reclassifySharedModule(meta, appPrefix, root, sharedModuleFacades);
+      if (boundary) return `client-${boundary}`;
+    }
+    return 'client-shared';
+  }
+
+  // Derive the group from the serverChunk's facade path — the RSC entry
+  // point that references this client module. This groups by the consuming
+  // route's layout boundary, not the module's own file location (TIM-1104).
+  if (serverChunk.startsWith('facade:')) {
+    const facadePath = serverChunk.slice('facade:'.length).replace(/\\/g, '/');
+    const facadeResult = findAppBoundary(facadePath, appPrefix);
+    if (facadeResult.inApp && facadeResult.segment) return `client-${facadeResult.segment}`;
+    if (facadeResult.inApp) return 'client-shared';
+
+    // Facade is outside app/ (e.g. src/posts/foo.mdx via import.meta.glob).
+    // Derive a chunk name from the full facade path to keep these isolated.
+    const facadeName = facadePath.replace(/\.[^.]+$/, '').replace(/\//g, '-');
+    if (facadeName) return `client-${facadeName}`;
+  }
+
+  return 'client-shared';
+}

package/src/plugins/client-dep-entries.ts

@@ -0,0 +1,78 @@
+/**
+ * client-dep-entries — seed the client dep optimizer's startup scan with
+ * the app's `'use client'` modules.
+ *
+ * Vite's dev optimizer discovers bare imports by crawling from its
+ * entries before the first request. With no `optimizeDeps.entries`, the
+ * client environment crawls its build input — timber's browser entry —
+ * and nothing more: every `'use client'` module is reached only through
+ * the RSC payload at runtime, never through a static import the crawl
+ * can follow. A package imported only from client components is then
+ * found on the first browser request, re-optimized mid-load, and the
+ * page full-reloads ("optimized dependencies changed. reloading"). That
+ * reload can leave react and react-dom from two optimizer runs in the
+ * browser (duplicate React → "Invalid hook call").
+ *
+ * Listing the `'use client'` files as entries lets the startup crawl see
+ * those imports. Setting `entries` replaces the build-input default, so
+ * the browser entry is listed too. Files that gain the directive after
+ * startup still fall back to Vite's late discovery.
+ *
+ * Design docs: 21-dev-server.md §"Client Dependency Pre-Bundling".
+ */
+
+import { readFile } from 'node:fs/promises';
+import { sep } from 'node:path';
+import { detectDirective, PARSEABLE_EXTENSIONS } from '../analyze/classify.ts';
+import { normalizeSlashes, scanProjectSourceFiles } from '../analyze/scan.ts';
+
+/**
+ * Every project source file under `root` whose directive prologue holds
+ * `'use client'`. Uses the same walker as `timber graph` (node_modules,
+ * root-level dot dirs and build outputs skipped) and the same AST
+ * directive check the RSC plugin applies. Files under `excludeDir` (the
+ * build output) are skipped.
+ */
+export async function findUseClientFiles(root: string, excludeDir?: string): Promise<string[]> {
+  const files: string[] = [];
+  // An unreadable directory only means its client deps are discovered
+  // late, through Vite's normal fallback — never fatal for dev startup.
+  await scanProjectSourceFiles(root, files, () => {}, 0, PARSEABLE_EXTENSIONS);
+  const excludePrefix = excludeDir ? excludeDir + sep : undefined;
+  const candidates = excludePrefix ? files.filter((f) => !f.startsWith(excludePrefix)) : files;
+
+  const matches = await Promise.all(
+    candidates.map(async (file) => {
+      const code = await readFile(file, 'utf8').catch(() => null);
+      // Cheap text gate before parsing: a directive is a literal
+      // without escapes, so a file lacking the text cannot carry it.
+      if (code === null || !code.includes('use client')) return null;
+      return detectDirective(code, file) === 'use client' ? file : null;
+    })
+  );
+  return matches.filter((file): file is string => file !== null);
+}
+
+/**
+ * Escape a path for use as an `optimizeDeps.entries` pattern. Vite globs
+ * entries, and route directories are full of glob syntax: `(group)`,
+ * `[slug]`, `[[...catchAll]]`, `@slot`. Slashes are normalized first, so
+ * the only backslashes left are literal (POSIX) ones, which are escaped
+ * too.
+ */
+export function escapeGlobPath(path: string): string {
+  return normalizeSlashes(path).replace(/[\\()[\]{}*?|!+@]/g, '\\$&');
+}
+
+/**
+ * The client environment's `optimizeDeps.entries`: timber's browser
+ * entry plus every `'use client'` file in the project.
+ */
+export async function clientOptimizeDepsEntries(
+  root: string,
+  browserEntryFile: string,
+  buildDir: string
+): Promise<string[]> {
+  const clientFiles = await findUseClientFiles(root, buildDir);
+  return [browserEntryFile, ...clientFiles].map(escapeGlobPath);
+}