@timber-js/app 0.2.0-alpha.120 → 0.2.0-alpha.122

package/src/params/resolve-schema.ts

@@ -63,6 +63,17 @@ export function toBracketKey(segmentType: string, paramName: string): string {
   }
 }
 
+const CATCH_ALL_RE = /^\[\.\.\..+\]$/;
+const OPTIONAL_CATCH_ALL_RE = /^\[\[\.\.\..+\]\]$/;
+
+function isCatchAllKey(key: string): boolean {
+  return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
+function isOptionalCatchAllKey(key: string): boolean {
+  return OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
 /**
  * Resolve the global schema's segmentParams into a map of bracket-keyed
  * param name → resolved Codec.
@@ -81,6 +92,23 @@ export function resolveSchemaCodecs(
   const resolved: Record<string, Codec<unknown>> = Object.create(null);
 
   for (const [bracketName, value] of Object.entries(segmentParams)) {
+    if (isCatchAllKey(bracketName) && isCodec(value) && !('__catchAll' in value)) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec ` +
+          `(e.g. codec.catchAll(codec.string)). Got a scalar codec.`
+      );
+    }
+    if (
+      isOptionalCatchAllKey(bracketName) &&
+      isCodec(value) &&
+      '__catchAll' in value &&
+      !('__optional' in value)
+    ) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() ` +
+          `(e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`
+      );
+    }
     resolved[bracketName] = resolveCodec(bracketName, value);
   }
 

package/src/plugins/build-manifest.ts

@@ -16,10 +16,13 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
-import { randomUUID } from 'node:crypto';
+import { randomUUID, createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import type { Plugin, ResolvedConfig } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import type { BuildManifest } from '../server/build-manifest.js';
+import type { SegmentNode, RouteFile } from '../routing/types.js';
+import { isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.
 // We define minimal interfaces here to avoid a direct 'rollup' dependency.
@@ -84,7 +87,7 @@ export function parseViteManifest(
     modulepreload[inputPath] = collectTransitiveDeps(inputPath, viteManifest, base);
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -197,7 +200,7 @@ export function buildManifestFromBundle(
     css['_global'] = allCss;
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -228,6 +231,50 @@ function collectTransitiveBundleDeps(
   return result;
 }
 
+/**
+ * Walk the route tree and compute short content hashes for metadata route files
+ * (opengraph-image, icon, apple-icon) used for cache-busting
+ * the auto-linked URLs in <head>.
+ */
+function computeMetadataRouteHashes(node: SegmentNode<RouteFile>): Record<string, string> {
+  const hashes: Record<string, string> = {};
+
+  if (node.metadataRoutes) {
+    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
+      if (!isDynamicMetadataExtension(baseName, file.extension)) {
+        // For static files, hash the file content
+        try {
+          const content = readFileSync(file.filePath);
+          const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
+          hashes[file.filePath] = hash;
+        } catch {
+          // File unreadable — skip hash, DEV_NONCE fallback applies
+        }
+      } else {
+        // For dynamic files (.ts/.tsx), hash the source file as a reasonable
+        // approximation — the output depends on runtime data too, but the
+        // source change is the best build-time signal we have.
+        try {
+          const content = readFileSync(file.filePath);
+          const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
+          hashes[file.filePath] = hash;
+        } catch {
+          // File unreadable — skip
+        }
+      }
+    }
+  }
+
+  for (const child of node.children) {
+    Object.assign(hashes, computeMetadataRouteHashes(child));
+  }
+  for (const slot of Object.values(node.slots)) {
+    Object.assign(hashes, computeMetadataRouteHashes(slot));
+  }
+
+  return hashes;
+}
+
 /**
  * Create the timber-build-manifest Vite plugin.
  *
@@ -278,7 +325,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
           '// Auto-generated build manifest — do not edit.',
           '// Dev mode: empty manifest (Vite HMR handles CSS/JS).',
           '',
-          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
           '',
           'export default manifest;',
         ].join('\n');
@@ -292,7 +339,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
         '// Auto-generated build manifest — do not edit.',
         '// Production: reads manifest from globalThis (set by _timber-manifest-init.js).',
         '',
-        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
         '',
         'export default manifest;',
       ].join('\n');
@@ -309,6 +356,11 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
       if (envName === 'client') {
         ctx.buildManifest = buildManifestFromBundle(bundle, resolvedBase, ctx.root);
 
+        // Compute cache-busting hashes for metadata route files
+        if (ctx.routeTree) {
+          ctx.buildManifest.metadataRouteHashes = computeMetadataRouteHashes(ctx.routeTree.root);
+        }
+
         // When client JavaScript is disabled, strip JS chunks from the bundle
         // so Rollup never writes them to disk. CSS assets are preserved —
         // they're still needed for server-rendered HTML.

package/src/plugins/cloudflare-wasm.ts

@@ -0,0 +1,103 @@
+/**
+ * timber-cloudflare-wasm — Handle WASM modules for Cloudflare Workers builds.
+ *
+ * Cloudflare Workers can natively import `.wasm` files as compiled
+ * WebAssembly.Module. But Rolldown can't load `.wasm` files at build time.
+ *
+ * This plugin bridges the gap:
+ * 1. Adds the `workerd` resolve condition so libraries like @takumi-rs/wasm
+ *    resolve to their Cloudflare-native entry (bare `.wasm` import)
+ * 2. Externalizes `.wasm` imports so Rolldown skips them
+ * 3. Copies the WASM files to the build output so wrangler can find them
+ *
+ * Only active for Cloudflare adapter production builds.
+ */
+
+import { basename, resolve, dirname } from 'node:path';
+import { copyFile, mkdir } from 'node:fs/promises';
+import type { Plugin, ResolvedConfig } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+
+function isCloudflareAdapter(ctx: PluginContext): boolean {
+  const adapter = ctx.config.adapter as { name?: string } | undefined;
+  return adapter?.name === 'cloudflare';
+}
+
+export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
+  // Track resolved WASM file paths so we can copy them to the output
+  const wasmFiles = new Map<string, string>();
+
+  const plugin: Plugin = {
+    name: 'timber-cloudflare-wasm',
+
+    configResolved(resolved: ResolvedConfig) {
+      if (resolved.command !== 'build') return;
+      if (!isCloudflareAdapter(ctx)) return;
+
+      // Prepend `workerd` to resolve conditions for server environments
+      // so @takumi-rs/wasm/auto resolves to the Cloudflare-native entry
+      // (bare WASM import) instead of the Vite entry (?url + fetch).
+      // Must happen in configResolved because the RSC plugin sets its own
+      // conditions during config — merging via config() would lose them.
+      for (const envName of ['rsc', 'ssr']) {
+        const env = resolved.environments[envName];
+        if (!env) continue;
+        const conditions = env.resolve.conditions;
+        if (!conditions.includes('workerd')) {
+          conditions.unshift('workerd');
+        }
+      }
+    },
+
+    resolveId: {
+      order: 'pre',
+      async handler(source, importer) {
+        if (!source.endsWith('.wasm')) return;
+
+        let absolutePath: string;
+        if (source.startsWith('.') && importer) {
+          absolutePath = resolve(dirname(importer), source);
+        } else {
+          return;
+        }
+
+        const filename = basename(absolutePath);
+        wasmFiles.set(filename, absolutePath);
+
+        return { id: './' + filename, external: true };
+      },
+    },
+
+    async writeBundle(options, bundle) {
+      if (wasmFiles.size === 0) return;
+
+      const outDir = options.dir;
+      if (!outDir) return;
+
+      // Find which output chunks reference WASM files and copy the WASM
+      // to the same directory so the relative imports resolve correctly.
+      const targetDirs = new Set<string>();
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== 'chunk') continue;
+        for (const filename of wasmFiles.keys()) {
+          if (chunk.code.includes(filename)) {
+            targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
+          }
+        }
+      }
+
+      if (targetDirs.size === 0) return;
+
+      const copies: Promise<void>[] = [];
+      for (const dir of targetDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [filename, absolutePath] of wasmFiles) {
+          copies.push(copyFile(absolutePath, resolve(dir, filename)));
+        }
+      }
+      await Promise.all(copies);
+    },
+  };
+
+  return [plugin];
+}

package/src/plugins/dev-server.ts

@@ -31,6 +31,7 @@ import {
 } from '../dev-tools/error-page.js';
 import { addVirtualModuleContext } from '../config-validation.js';
 import { compressResponse } from '../server/compress.js';
+import { isMetadataRouteServePath } from '../server/metadata-routes.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -165,8 +166,9 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       return;
     }
 
-    // Pass through static asset requests
-    if (isAssetRequest(url)) {
+    // Pass through static asset requests — but not metadata routes like
+    // /favicon.ico that match asset extensions but are handled by timber.
+    if (isAssetRequest(url) && !isMetadataRouteServePath(url)) {
       next();
       return;
     }

package/src/plugins/routing.ts

@@ -20,11 +20,7 @@ import {
   writeSegmentTypes,
   type SegmentInfo,
 } from '../routing/segment-codegen.js';
-import {
-  collectDynamicSegments,
-  findSchemaFile,
-  parseExistingSchemaKeys,
-} from '../cli-schema-sync.js';
+import { validateSchemaAgainstRoutes } from '../routing/schema-validation.js';
 
 import {
   lintConventions,
@@ -72,7 +68,7 @@ const SEGMENT_PREFIX = '\0$segment:';
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|schema|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|schema|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
@@ -157,10 +153,10 @@ export function timberRouting(ctx: PluginContext): Plugin {
     dirToRoute = buildDirToRouteMap(ctx.routeTree, ctx.appDir);
     writeCodegen(ctx);
 
-    // Dev: warn about dynamic segments not registered in app/schema.ts.
-    // Only logs a suggestion, never auto-modifies the schema file.
+    // Validate schema keys against filesystem segments.
+    // Warns on stale keys, bracket form mismatches, and missing keys.
     // See design/41-global-params.md §Auto-Scaffolding
-    warnUnregisteredSegments(ctx);
+    warnSchemaValidation(ctx);
 
     // Lint conventions (empty app, missing methods, missing root layout)
     const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
@@ -346,34 +342,35 @@ export function timberRouting(ctx: PluginContext): Plugin {
  * When the route tree changes, any environment that has imported the manifest
  * needs to be invalidated so the next request/transform picks up the new tree.
  */
-/** Set of segments we've already warned about — avoid repeating on every rescan. */
-const _warnedSegments = new Set<string>();
+/** Set of warning keys we've already emitted — avoid repeating on every rescan. */
+const _warnedKeys = new Set<string>();
 
 /**
- * Warn about dynamic segments not registered in app/schema.ts.
- * Only fires when a schema file exists. Logs once per segment per session.
+ * Validate schema keys against the filesystem route tree.
+ * Warns on stale keys, bracket form mismatches, and missing keys.
+ * Uses the already-scanned route tree instead of re-scanning.
  */
-function warnUnregisteredSegments(ctx: PluginContext): void {
-  const schemaPath = findSchemaFile(ctx.appDir);
-  if (!schemaPath) return;
-
-  const filesystemSegments = collectDynamicSegments(ctx.appDir);
-  if (filesystemSegments.length === 0) return;
-
-  const content = readFileSync(schemaPath, 'utf-8');
-  const existingKeys = parseExistingSchemaKeys(content);
-  const missing = filesystemSegments.filter(
-    (seg) => !existingKeys.includes(seg) && !_warnedSegments.has(seg)
-  );
-
-  if (missing.length === 0) return;
-
-  for (const seg of missing) _warnedSegments.add(seg);
-
-  console.warn(
-    `[timber] New segment${missing.length > 1 ? 's' : ''} not in schema: ${missing.join(', ')}\n` +
-      `  Run: timber schema sync`
-  );
+function warnSchemaValidation(ctx: PluginContext): void {
+  if (!ctx.routeTree) return;
+  const warnings = validateSchemaAgainstRoutes(ctx.routeTree, ctx.appDir);
+
+  for (const w of warnings) {
+    const warnKey = `${w.type}:${w.key}`;
+    if (_warnedKeys.has(warnKey)) continue;
+    _warnedKeys.add(warnKey);
+
+    switch (w.type) {
+      case 'stale-key':
+        console.warn(`[timber] ${w.message}`);
+        break;
+      case 'bracket-mismatch':
+        console.warn(`[timber] ${w.message}`);
+        break;
+      case 'missing-key':
+        console.warn(`[timber] ${w.message}`);
+        break;
+    }
+  }
 }
 
 function invalidateManifest(server: ViteDevServer): void {

package/src/routing/codegen-shared.ts

@@ -82,13 +82,16 @@ export function buildCodecChainType(
 
 /**
  * Build a TypeScript type expression for a single param using the global
- * schema's InferCodecType. Falls back to `fallback` when schema doesn't
- * declare this param.
+ * schema's InferCodecType. Falls back to the param's base type when
+ * schema doesn't declare this param (schemas are opt-in per key).
  *
- * Generates: `InferCodecType<typeof schema.segmentParams['[paramName]']>`
+ * Generates a conditional that checks key existence:
+ * `[bracketName] extends keyof typeof schema.segmentParams ? InferCodecType<...> : fallback`
  */
-export function buildSchemaParamType(p: ParamEntry): string {
-  return `InferCodecType<typeof schema.segmentParams[${JSON.stringify(p.bracketName)}]>`;
+export function buildSchemaParamType(p: ParamEntry, fallback?: string): string {
+  const key = JSON.stringify(p.bracketName);
+  const fb = fallback ?? p.type;
+  return `${key} extends keyof typeof schema['segmentParams'] ? InferCodecType<typeof schema.segmentParams[${key}]> : ${fb}`;
 }
 
 /**

package/src/routing/codegen.ts

@@ -321,10 +321,40 @@ function formatDeclarationFile(
         ? './' + relative(importBase, join(appDir, 'schema')).replace(/\\/g, '/')
         : '../app/schema';
     lines.push(`import type schema from '${schemaImport}';`);
-    lines.push("import type { InferCodecType } from '@timber-js/app/params';");
+    lines.push("import type { InferCodecType, SegmentParamCodec } from '@timber-js/app/params';");
     lines.push('');
-    // Emit TimberSegmentParams, TimberRoute, AllSegmentParams, RoutesWithParams
-    lines.push(...formatSchemaTypes(routes));
+    // Collect all unique bracket keys from routes for key validation
+    const allBracketKeys = new Set<string>();
+    for (const route of routes) {
+      for (const p of route.params) {
+        allBracketKeys.add(p.bracketName);
+      }
+    }
+
+    // Augment the ValidDynamicSegmentKeysRegistry so defineSchema constrains keys
+    // to known filesystem segments. Unknown keys produce inline TS errors.
+    if (allBracketKeys.size > 0) {
+      lines.push("declare module '@timber-js/app/params' {");
+      lines.push('  interface ValidDynamicSegmentKeysRegistry {');
+      for (const key of [...allBracketKeys].sort()) {
+        lines.push(`    ${JSON.stringify(key)}: true;`);
+      }
+      lines.push('  }');
+      lines.push('}');
+      lines.push('');
+    }
+    // Type-level validation: each schema value must be a Codec or Standard Schema.
+    // Running `pnpm run typecheck` will surface errors for invalid values.
+    lines.push('type _AssertSchemaValues = {');
+    lines.push(
+      "  [K in keyof typeof schema['segmentParams']]: typeof schema['segmentParams'][K] extends SegmentParamCodec ? true : ['Error: value for', K, 'is not a valid Codec or Standard Schema'];"
+    );
+    lines.push('};');
+    // Generic constraint enforces that all values are `true` — if any value is
+    // an error tuple, TS reports a real diagnostic instead of silently computing it.
+    lines.push(
+      'type _EnforceSchemaValues<_T extends Record<string, true> = _AssertSchemaValues> = true;'
+    );
     lines.push('');
   }
 
@@ -350,6 +380,16 @@ function formatDeclarationFile(
   }
 
   lines.push('  }');
+
+  // When a global schema exists, emit segment param types inside the
+  // @timber-js/app module augmentation so that declare module blocks
+  // for @timber-js/app/server and @timber-js/app/client can reference
+  // AllSegmentParams via `import type { AllSegmentParams } from '@timber-js/app'`.
+  if (hasSchema) {
+    lines.push('');
+    lines.push(...formatSchemaTypes(routes).map((l) => `  ${l}`));
+  }
+
   lines.push('}');
   lines.push('');
 
@@ -359,13 +399,20 @@ function formatDeclarationFile(
   // Generate @timber-js/app/server augmentation — typed getSegmentParams
   if (dynamicRoutes.length > 0) {
     lines.push("declare module '@timber-js/app/server' {");
+    if (hasSchema) {
+      lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
+    }
     for (const route of dynamicRoutes) {
       const paramsType = formatParamsType(route.params, importBase, hasSchema);
       lines.push(
         `  export function getSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
       );
     }
-    lines.push('  export function getSegmentParams(): Record<string, string | string[]>');
+    lines.push(
+      hasSchema
+        ? '  export function getSegmentParams(): Partial<AllSegmentParams>'
+        : '  export function getSegmentParams(): Record<string, string | string[]>'
+    );
     lines.push('}');
     lines.push('');
   }
@@ -377,6 +424,9 @@ function formatDeclarationFile(
     lines.push(
       "  import type { SearchParamsDefinition, SetParams, QueryStatesOptions, SearchParamCodec } from '@timber-js/app/search-params'"
     );
+    if (hasSchema) {
+      lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
+    }
     lines.push('');
 
     // useSegmentParams overloads
@@ -387,7 +437,11 @@ function formatDeclarationFile(
           `  export function useSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
         );
       }
-      lines.push('  export function useSegmentParams(): Record<string, string | string[]>');
+      lines.push(
+        hasSchema
+          ? '  export function useSegmentParams(): Partial<AllSegmentParams>'
+          : '  export function useSegmentParams(): Record<string, string | string[]>'
+      );
       lines.push('');
     }
 

package/src/routing/index.ts

@@ -16,3 +16,8 @@ export { classifyUrlSegment, classifySegment } from './segment-classify.js';
 export type { UrlSegment, SegmentClassification } from './segment-classify.js';
 export { collectLeafRoutes } from './walkers.js';
 export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.js';
+export {
+  validateSchemaAgainstRoutes,
+  collectDynamicSegmentsFromTree,
+} from './schema-validation.js';
+export type { SchemaWarning } from './schema-validation.js';

package/src/routing/link-codegen.ts

@@ -83,7 +83,7 @@ export function formatLinkParamsType(
   const fields = params.map((p) => {
     const fallback = p.type === 'string' ? 'string | number' : p.type;
     const codecType = hasSchema
-      ? buildSchemaParamType(p)
+      ? buildSchemaParamType(p, fallback)
       : buildCodecChainType(p, importBase, fallback);
     return `${p.name}: ${codecType}`;
   });

package/src/routing/scanner.ts

@@ -106,6 +106,10 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
   // e.g., /[id]/items/[id] — same param name in ancestor and descendant
   validateDuplicateParamNames(tree.root);
 
+  // Validate: detect same param name used with different bracket forms
+  // e.g., [id] in one route and [...id] in another
+  validateUniqueBracketForms(tree.root);
+
   return tree;
 }
 
@@ -457,6 +461,60 @@ function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): v
   }
 }
 
+/**
+ * Validate that each param name uses a single bracket form across the entire route tree.
+ *
+ * Different bracket forms produce different types:
+ *   [id]      → string
+ *   [...id]   → string[]
+ *   [[...id]] → string[] | undefined
+ *
+ * If the same param name appears with multiple forms, the no-argument
+ * getSegmentParams() / useSegmentParams() return type becomes ambiguous.
+ *
+ * Same name + same form across different routes is fine and expected.
+ */
+function validateUniqueBracketForms(root: SegmentNode): void {
+  const forms = new Map<string, { segmentType: SegmentType; urlPath: string }>();
+  collectBracketForms(root, forms);
+}
+
+function collectBracketForms(
+  node: SegmentNode,
+  forms: Map<string, { segmentType: SegmentType; urlPath: string }>
+): void {
+  if (node.paramName && node.segmentType !== 'static' && node.segmentType !== 'group') {
+    const existing = forms.get(node.paramName);
+    if (existing && existing.segmentType !== node.segmentType) {
+      const bracketExamples: Record<string, string> = {
+        'dynamic': `[${node.paramName}]`,
+        'catch-all': `[...${node.paramName}]`,
+        'optional-catch-all': `[[...${node.paramName}]]`,
+      };
+      throw new Error(
+        `[timber] Param name '${node.paramName}' uses multiple bracket forms.\n` +
+          `  ${bracketExamples[existing.segmentType] ?? existing.segmentType} at: ${existing.urlPath}\n` +
+          `  ${bracketExamples[node.segmentType] ?? node.segmentType} at: ${node.urlPath || '/'}\n` +
+          `  Each param name must use a single bracket form across all routes.\n` +
+          `  Rename one of the segments to fix this (e.g., [${node.paramName}] → [${node.paramName}Id]).`
+      );
+    }
+    if (!existing) {
+      forms.set(node.paramName, {
+        segmentType: node.segmentType,
+        urlPath: node.urlPath || '/',
+      });
+    }
+  }
+
+  for (const child of node.children) {
+    collectBracketForms(child, forms);
+  }
+  for (const slotNode of Object.values(node.slots)) {
+    collectBracketForms(slotNode, forms);
+  }
+}
+
 /**
  * Find a fixed-extension file (proxy.ts) in a directory.
  */