@timber-js/app 0.2.0-alpha.158 → 0.2.0-alpha.159

package/src/plugins/callsite-ast.ts

@@ -0,0 +1,167 @@
+/**
+ * Shared AST helpers for callsite-ID transforms.
+ *
+ * Both timber-cache-transform (plugins/cache.ts) and timber-prebuilt
+ * (plugins/prebuilt.ts) detect calls on bindings imported from the cache
+ * module and stamp them with content-derived stable IDs. The node shapes,
+ * import-binding resolution, recursive call walk, and ID derivation are
+ * identical — only the callee shape and rewrite differ per plugin.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
+ */
+
+import { fnv1aHash } from '../cache/fast-hash.js';
+
+/** Module specifiers whose bindings the transforms track. */
+export const CACHE_MODULE_SOURCES = new Set(['@timber-js/app/cache', 'timber/cache']);
+
+export interface PositionedNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+export interface IdentifierNode extends PositionedNode {
+  type: 'Identifier';
+  name: string;
+}
+
+export interface ImportDeclarationNode extends PositionedNode {
+  type: 'ImportDeclaration';
+  source: { value: string };
+  specifiers: Array<
+    PositionedNode & {
+      type: string;
+      local: IdentifierNode;
+      imported?: IdentifierNode;
+    }
+  >;
+}
+
+export interface CallExpressionNode extends PositionedNode {
+  type: 'CallExpression';
+  callee: PositionedNode;
+  arguments: PositionedNode[];
+}
+
+export interface MemberExpressionNode extends PositionedNode {
+  type: 'MemberExpression';
+  object: PositionedNode;
+  property: PositionedNode;
+  computed: boolean;
+}
+
+export interface ProgramNode extends PositionedNode {
+  type: 'Program';
+  body: PositionedNode[];
+}
+
+export interface ImportBindings {
+  /** Local names bound to the named import (`import { cache as c }`). */
+  named: Set<string>;
+  /** Local names of namespace imports (`import * as ns`) of a tracked module. */
+  namespaces: Set<string>;
+}
+
+/**
+ * Find the local binding name(s) for `importedName` imported from one of
+ * `sources` — both named imports (including aliases) and namespace imports
+ * (TIM-1054).
+ */
+export function findImportBindings(
+  program: ProgramNode,
+  sources: ReadonlySet<string>,
+  importedName: string
+): ImportBindings {
+  const named = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    const decl = stmt as unknown as ImportDeclarationNode;
+    if (!sources.has(decl.source.value)) continue;
+    for (const spec of decl.specifiers) {
+      if (spec.type === 'ImportNamespaceSpecifier') {
+        namespaces.add(spec.local.name);
+        continue;
+      }
+      if (spec.type !== 'ImportSpecifier') continue;
+      const specImportedName = spec.imported?.name ?? spec.local.name;
+      if (specImportedName === importedName) {
+        named.add(spec.local.name);
+      }
+    }
+  }
+  return { named, namespaces };
+}
+
+/**
+ * Recursively walk AST nodes collecting call expressions accepted by
+ * `matches`. Calls are typically at module scope, but calls inside
+ * functions/blocks are handled for completeness.
+ *
+ * NOTE: matching is by binding NAME, so nested scopes that shadow a tracked
+ * import can produce false positives for consumers of this walker (see
+ * TIM-1141 for the cache transform). The prebuilt transform avoids the
+ * class entirely by not using this walker — it allowlists top-level
+ * declarator positions instead (plugins/prebuilt.ts).
+ */
+export function findCallSites(
+  node: PositionedNode,
+  matches: (call: CallExpressionNode) => boolean,
+  results: CallExpressionNode[]
+): void {
+  if (node.type === 'CallExpression') {
+    const call = node as unknown as CallExpressionNode;
+    if (matches(call)) {
+      results.push(call);
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end') continue;
+    const val = node[key];
+    if (val && typeof val === 'object') {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item && typeof item === 'object' && typeof item.type === 'string') {
+            findCallSites(item as PositionedNode, matches, results);
+          }
+        }
+      } else if (typeof (val as PositionedNode).type === 'string') {
+        findCallSites(val as PositionedNode, matches, results);
+      }
+    }
+  }
+}
+
+/**
+ * Generate a stable callsite ID from a module path, a kind discriminator
+ * ('cache' | 'component'), the source text of the enclosing top-level
+ * statement, the source text of the call expression, and an occurrence index
+ * among fully byte-identical (statement, call) pairs in the same file.
+ *
+ * The ID is deterministic and:
+ * - Stable across cold starts AND across builds/deploys for unchanged calls —
+ *   inserting, deleting, or reordering other calls does not affect it
+ * - Unique across different modules (relPath component)
+ * - Unique across distinct calls within a module (statement + span hashes),
+ *   with fully identical duplicates disambiguated by source-order occurrence
+ * - Fresh when the wrapped fn, opts, or enclosing statement change, which
+ *   intentionally invalidates the old persisted entries
+ *
+ * The enclosing-statement text is included so that byte-identical calls in
+ * different scopes — e.g. two factory helpers with identical call spans —
+ * get distinct, insertion-stable IDs. See plugins/cache.ts header for the
+ * full derivation rationale (TIM-1053).
+ */
+export function generateStableCallsiteId(
+  relativeModulePath: string,
+  kind: string,
+  statementText: string,
+  callSpanText: string,
+  occurrence: number
+): string {
+  return fnv1aHash(
+    `${relativeModulePath}:${kind}:${fnv1aHash(statementText)}:${fnv1aHash(callSpanText)}:${occurrence}`
+  );
+}

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.js';
+import type { IdentifierNode, PositionedNode, ProgramNode } from './callsite-ast.js';
+
+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/entries.ts

@@ -154,6 +154,10 @@ function generateConfigModule(ctx: PluginContext): string {
     // Per-build deployment ID for version skew detection (TIM-446).
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,
+    // Browser log forwarding threshold — used by buildClientScripts to
+    // decide whether /@vite/client is needed when clientJavascript is
+    // disabled. See TIM-1152.
+    devBrowserLogs: ctx.config.devBrowserLogs,
     // Note: project root is NOT included here — it was leaking server
     // filesystem paths to client bundles (TIM-787). Dev error pages get
     // the root through the dev server, not the runtime config.
@@ -244,8 +248,12 @@ function detectConfigFile(root: string): string | null {
  * cannot be JSON-serialized into virtual:timber-config, so it must
  * be loaded at runtime via dynamic import. See TIM-599.
  */
-function generateCacheHandlerModule(configPath: string | null, hasCacheHandler: boolean): string {
-  if (configPath && hasCacheHandler) {
+function generateCacheHandlerModule(
+  configPath: string | null,
+  hasCacheHandler: boolean,
+  hasCdnPurge: boolean
+): string {
+  if (configPath && (hasCacheHandler || hasCdnPurge)) {
     return [
       '// Auto-generated cache handler loader — do not edit.',
       '// Generated by timber-entries plugin.',
@@ -255,17 +263,27 @@ function generateCacheHandlerModule(configPath: string | null, hasCacheHandler:
       `  const config = mod.default ?? mod;`,
       `  return config.cacheHandler ?? null;`,
       `}`,
+      '',
+      `export async function loadCdnPurgeHandler() {`,
+      `  const mod = await import(${JSON.stringify(configPath)});`,
+      `  const config = mod.default ?? mod;`,
+      `  return config.cdnPurge ?? null;`,
+      `}`,
     ].join('\n');
   }
 
   return [
     '// Auto-generated cache handler loader — do not edit.',
     '// Generated by timber-entries plugin.',
-    '// No cacheHandler configured in timber.config.',
+    '// No cacheHandler or cdnPurge configured in timber.config.',
     '',
     `export default async function loadCacheHandler() {`,
     `  return null;`,
     `}`,
+    '',
+    `export async function loadCdnPurgeHandler() {`,
+    `  return null;`,
+    `}`,
   ].join('\n');
 }
 
@@ -336,7 +354,8 @@ export function timberEntries(ctx: PluginContext): Plugin {
       if (id === RESOLVED_CACHE_HANDLER_ID) {
         const configPath = detectConfigFile(ctx.root);
         const hasCacheHandler = ctx.config.cacheHandler != null;
-        return generateCacheHandlerModule(configPath, hasCacheHandler);
+        const hasCdnPurge = ctx.config.cdnPurge != null;
+        return generateCacheHandlerModule(configPath, hasCacheHandler, hasCdnPurge);
       }
       return null;
     },

package/src/plugins/fonts.ts

@@ -221,9 +221,23 @@ export function timberFonts(ctx: PluginContext): Plugin {
      *
      * Delegates to `runFontsTransform`. Errors raised through the
      * `this.error` callback are surfaced as Vite plugin errors.
+     *
+     * The `filter` option uses Vite 8's rolldown-native hook filters to
+     * skip non-JS/TS files and files that don't mention any font module
+     * before crossing into JS — replacing the hand-rolled pre-filter that
+     * was previously inside `runFontsTransform` (TIM-840, TIM-1147).
      */
-    transform(code: string, id: string) {
-      return runFontsTransform(code, id, pipeline, (msg) => this.error(msg));
+    transform: {
+      filter: {
+        id: {
+          include: /^[^?]*\.(?:js|jsx|ts|tsx|mjs|cjs|mts|cts)(?:\?|$)/,
+          exclude: /(?:^\0|(?:^|\/)node_modules\/)/,
+        },
+        code: ['@timber/fonts/', '@timber-js/app/fonts/', 'next/font/'],
+      },
+      handler(code: string, id: string) {
+        return runFontsTransform(code, id, pipeline, (msg) => this.error(msg));
+      },
     },
 
     /**