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

package/src/params/codec-registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Client-side registry for schema segment param codecs.
+ *
+ * The Link component uses codec `serialize` functions to convert typed
+ * segment param values back to URL-safe strings. Without this registry,
+ * Link falls back to `String(value)` — which works for simple types
+ * but breaks for custom codecs (e.g., Date → '2026-04-10').
+ *
+ * Populated at startup by the browser entry importing `virtual:timber-schema`.
+ * Also usable on the server (isomorphic).
+ *
+ * Design doc: design/41-global-params.md §"Link Component"
+ */
+
+import type { Codec } from '../codec.js';
+
+let _codecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the resolved schema codecs for use by Link's URL interpolation.
+ * Called once at startup from the browser entry or RSC entry.
+ * @internal
+ */
+export function setLinkCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _codecs = codecs;
+}
+
+/**
+ * Look up a codec by bracket key (e.g. '[id]', '[...slug]').
+ * Returns undefined if no schema is registered or the key has no codec.
+ */
+export function getLinkCodec(bracketKey: string): Codec<unknown> | undefined {
+  return _codecs?.[bracketKey] ?? undefined;
+}

package/src/params/define-schema.ts

@@ -0,0 +1,73 @@
+/**
+ * defineSchema — global segment param schema definition.
+ *
+ * Identity function at runtime; the type information is what matters.
+ * The Vite plugin reads the schema at build time for codegen, and
+ * the pipeline reads it at runtime for coercion.
+ *
+ * Design doc: design/41-global-params.md
+ */
+
+import type { Codec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.
+ *
+ * Used by codegen to reference schema types without hardcoding:
+ *   `InferCodecType<typeof schema.segmentParams['[year]']>`
+ */
+export type InferCodecType<V> =
+  V extends Codec<infer T>
+    ? T
+    : V extends StandardSchemaV1<infer T>
+      ? T
+      : V extends { parseServerSide: (value: string) => infer T }
+        ? T
+        : string;
+
+/** Acceptable codec value for segment params: a Codec or Standard Schema. */
+type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+
+/** Configuration object for defineSchema. */
+export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
+  segmentParams: S;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Define the global segment param schema.
+ *
+ * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,
+ * `[[...slug]]`) mapped to a codec. This makes the relationship between
+ * filesystem segments and codecs visually obvious.
+ *
+ * A dynamic segment with no key here defaults to `string` at codegen time.
+ *
+ * ```ts
+ * // app/schema.ts
+ * import { defineSchema } from '@timber-js/app/params';
+ * import { codec } from '@timber-js/app/codec';
+ * import { z } from 'zod';
+ *
+ * export default defineSchema({
+ *   segmentParams: {
+ *     '[artistSlug]': codec.string,
+ *     '[year]': codec.integer,
+ *     '[id]': z.coerce.number().int(),
+ *   },
+ * });
+ * ```
+ */
+export function defineSchema<S extends Record<string, SegmentParamCodec>>(
+  config: SchemaConfig<S>
+): SchemaConfig<S> {
+  return config;
+}

package/src/params/index.ts

@@ -0,0 +1,11 @@
+// @timber-js/app/params — Global segment param schema and typed accessors.
+//
+// This is the import path for defineSchema, InferCodecType, and
+// the future getSegmentParams/useSegmentParams with route narrowing.
+//
+// See design/41-global-params.md
+
+export { defineSchema } from './define-schema.js';
+export type { InferCodecType, SchemaConfig } from './define-schema.js';
+export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.js';
+export { setLinkCodecs, getLinkCodec } from './codec-registry.js';

package/src/params/resolve-schema.ts

@@ -0,0 +1,88 @@
+/**
+ * Schema resolution — resolves the global schema's segmentParams into
+ * a runtime-ready codec map keyed by bracket name (e.g. '[id]').
+ *
+ * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`
+ * remain distinct entries. The coercion layer reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Design doc: design/41-global-params.md §Pipeline Integration
+ */
+
+import type { Codec } from '../codec.js';
+import { isCodec, isStandardSchema, validateSync } from '../schema-bridge.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+/**
+ * Wrap a Standard Schema into a Codec for route params.
+ * Parse throws on failure (invalid param → 404). Serialize returns string.
+ */
+function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      const result = validateSync(schema, value);
+      if (!result.issues) {
+        return result.value;
+      }
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) return null;
+      if (Array.isArray(value)) return value.join('/');
+      return String(value);
+    },
+  };
+}
+
+/**
+ * Resolve a schema entry to a Codec. Accepts Codec<T> or StandardSchemaV1<T>.
+ */
+function resolveCodec(fieldName: string, value: unknown): Codec<unknown> {
+  if (isCodec(value)) return value;
+  if (isStandardSchema(value)) return fromParamSchema(fieldName, value);
+  throw new Error(`[timber] Schema field '${fieldName}' is not a valid codec or Standard Schema.`);
+}
+
+/**
+ * Reconstruct the bracket key for a segment from its type and param name.
+ * Used by the coercion layer to look up codecs in the bracket-keyed map.
+ *
+ * 'dynamic'          + 'id'   → '[id]'
+ * 'catch-all'        + 'slug' → '[...slug]'
+ * 'optional-catch-all' + 'slug' → '[[...slug]]'
+ */
+export function toBracketKey(segmentType: string, paramName: string): string {
+  switch (segmentType) {
+    case 'catch-all':
+      return `[...${paramName}]`;
+    case 'optional-catch-all':
+      return `[[...${paramName}]]`;
+    default:
+      return `[${paramName}]`;
+  }
+}
+
+/**
+ * Resolve the global schema's segmentParams into a map of bracket-keyed
+ * param name → resolved Codec.
+ *
+ * Keys are preserved exactly as written in `app/schema.ts` so that
+ * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.
+ * The coercion layer in `param-coercion.ts` reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }
+ * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }
+ */
+export function resolveSchemaCodecs(
+  segmentParams: Record<string, unknown>
+): Record<string, Codec<unknown>> {
+  const resolved: Record<string, Codec<unknown>> = Object.create(null);
+
+  for (const [bracketName, value] of Object.entries(segmentParams)) {
+    resolved[bracketName] = resolveCodec(bracketName, value);
+  }
+
+  return resolved;
+}

package/src/plugin-context.ts

@@ -0,0 +1,240 @@
+/**
+ * Plugin context — internal types and helpers for timber sub-plugins.
+ *
+ * These are NOT part of the user-facing API. They are consumed by
+ * sub-plugins (routing, entries, shims, etc.) via relative imports.
+ * The root entry point (index.ts) does not re-export them.
+ *
+ * Design doc: 18-build-system.md §"Shared Plugin Context"
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import type { RouteTree } from './routing/types';
+import type { BuildManifest } from './server/build-manifest';
+import type { StartupTimer } from './utils/startup-timer';
+import { createStartupTimer } from './utils/startup-timer';
+import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+import type { HoldingServer } from './dev-tools/holding-server.js';
+
+// Re-export for sub-plugin convenience — they import from plugin-context.ts
+export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+
+// ── Client JavaScript config ─────────────────────────────────────────────
+
+/** Fully resolved client JavaScript configuration (no optionals). */
+export interface ResolvedClientJavascript {
+  disabled: boolean;
+  enableHMRInDev: boolean;
+}
+
+/**
+ * Resolve `clientJavascript` into a fully resolved config.
+ */
+export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
+  if (config.clientJavascript !== undefined) {
+    if (typeof config.clientJavascript === 'boolean') {
+      return {
+        disabled: !config.clientJavascript,
+        enableHMRInDev: !config.clientJavascript,
+      };
+    }
+    return {
+      disabled: config.clientJavascript.disabled,
+      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
+    };
+  }
+  return { disabled: false, enableHMRInDev: false };
+}
+
+// ── Plugin Context ────────────────────────────────────────────────────────
+
+/**
+ * Shared context object passed to all sub-plugins via closure.
+ *
+ * Sub-plugins communicate through this context — not through Vite's
+ * plugin API or global state.
+ * See design/18-build-system.md §"Shared Plugin Context".
+ */
+export interface PluginContext {
+  config: TimberUserConfig;
+  /** Resolved client JavaScript configuration */
+  clientJavascript: ResolvedClientJavascript;
+  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
+  routeTree: RouteTree | null;
+  /** Absolute path to the app/ directory */
+  appDir: string;
+  /** Absolute path to the project root */
+  root: string;
+  /** Whether the dev server is running (set by timber-root-sync in configResolved) */
+  dev: boolean;
+  /** CSS build manifest (populated by adapter after client build, null in dev) */
+  buildManifest: BuildManifest | null;
+  /** Per-build deployment ID for version skew detection (null in dev) */
+  deploymentId: string | null;
+  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
+  timer: StartupTimer;
+  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */
+  holdingServer?: HoldingServer | null;
+  /**
+   * Resolved absolute path to the build output directory.
+   *
+   * Defaults to `<root>/.timber/dist`. Can be overridden via
+   * `timber.config.ts` `buildDir` or Vite's `build.outDir`.
+   * Timber config takes precedence when both are set.
+   *
+   * Used by adapter-build and cli preview.
+   */
+  buildDir: string;
+}
+
+// ── App directory resolution ──────────────────────────────────────────────
+
+/**
+ * Resolve the app directory. Checks (in order):
+ * 1. Explicit `configAppDir` from timber.config.ts
+ * 2. `<root>/app`
+ * 3. `<root>/src/app`
+ *
+ * Throws if none exist.
+ */
+export function resolveAppDir(root: string, configAppDir?: string): string {
+  if (configAppDir) {
+    const explicit = join(root, configAppDir);
+    if (!existsSync(explicit)) {
+      throw new Error(`[timber] Configured appDir "${configAppDir}" does not exist at ${explicit}`);
+    }
+    return explicit;
+  }
+
+  const rootApp = join(root, 'app');
+  if (existsSync(rootApp)) return rootApp;
+
+  const srcApp = join(root, 'src', 'app');
+  if (existsSync(srcApp)) return srcApp;
+
+  throw new Error(
+    `[timber] Could not find app directory. Expected "app/" or "src/app/" in ${root}. ` +
+      `You can set appDir in timber.config.ts to specify a custom location.`
+  );
+}
+
+// ── Plugin context factory ────────────────────────────────────────────────
+
+export function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
+  const projectRoot = root ?? process.cwd();
+  const resolvedConfig: TimberUserConfig = { ...config };
+  return {
+    config: resolvedConfig,
+    clientJavascript: resolveClientJavascript(resolvedConfig),
+    routeTree: null,
+    appDir: join(projectRoot, 'app'),
+    root: projectRoot,
+    dev: false,
+    buildManifest: null,
+    deploymentId: null,
+    timer: createStartupTimer(),
+    holdingServer: null,
+    buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+  };
+}
+
+// ── Build directory resolution ────────────────────────────────────────────
+
+/** Default build output directory (relative to root). */
+export const DEFAULT_BUILD_DIR = join('.timber', 'dist');
+
+/**
+ * Resolve the build output directory.
+ *
+ * Priority:
+ * 1. Explicit `timberBuildDir` from timber.config.ts
+ * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')
+ * 3. Default: `.timber/dist`
+ *
+ * Returns an absolute path.
+ */
+export function resolveBuildDir(
+  root: string,
+  timberBuildDir?: string,
+  viteBuildOutDir?: string
+): string {
+  if (timberBuildDir) {
+    return join(root, timberBuildDir);
+  }
+  if (viteBuildOutDir && viteBuildOutDir !== 'dist') {
+    return join(root, viteBuildOutDir);
+  }
+  return join(root, DEFAULT_BUILD_DIR);
+}
+
+// ── Config file loading ───────────────────────────────────────────────────
+
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ *
+ * Uses require() which works for ESM modules on Node 22.12+.
+ * This keeps timber() synchronous — no async config loading needed.
+ */
+export function loadTimberConfigFile(root: string): TimberUserConfig | null {
+  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  const req = createRequire(join(root, 'package.json'));
+
+  for (const name of configNames) {
+    const configPath = join(root, name);
+    if (existsSync(configPath)) {
+      const mod = req(configPath);
+      return (mod.default ?? mod) as TimberUserConfig;
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
+ * and warn the user. The `output` key is excluded because it defaults to 'server'
+ * in createPluginContext and would always appear as an inline key.
+ *
+ * Returns the list of conflicting key names (for testing).
+ */
+export function warnConfigConflicts(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): string[] {
+  const conflicts: string[] = [];
+  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {
+    if (key in inline && inline[key] !== undefined) {
+      conflicts.push(key);
+    }
+  }
+  if (conflicts.length > 0) {
+    console.warn(
+      `[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(', ')} set in both ` +
+        `vite.config.ts (inline) and timber.config.ts. ` +
+        `Move all config to timber.config.ts to avoid confusion. ` +
+        `The inline value from vite.config.ts will be used.`
+    );
+  }
+  return conflicts;
+}
+
+/**
+ * Merge file-based config into ctx.config. Inline config (already in ctx.config)
+ * takes precedence — file config only fills in missing fields.
+ */
+export function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void {
+  const inline = ctx.config;
+  warnConfigConflicts(inline, fileConfig);
+
+  ctx.config = {
+    ...fileConfig,
+    ...inline,
+    ...(fileConfig.limits && inline.limits
+      ? { limits: { ...fileConfig.limits, ...inline.limits } }
+      : {}),
+    ...(fileConfig.dev && inline.dev ? { dev: { ...fileConfig.dev, ...inline.dev } } : {}),
+    ...(fileConfig.mdx && inline.mdx ? { mdx: { ...fileConfig.mdx, ...inline.mdx } } : {}),
+  };
+}

package/src/plugins/adapter-build.ts

@@ -16,8 +16,9 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
-import type { PluginContext } from '#/index.js';
-import type { TimberPlatformAdapter, TimberConfig } from '#/adapters/types.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
+import { swallow } from '../server/logger.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -35,7 +36,7 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
         const adapter = ctx.config.adapter as TimberPlatformAdapter | undefined;
         if (!adapter || typeof adapter.buildOutput !== 'function') return;
 
-        const buildDir = join(ctx.root, 'dist');
+        const buildDir = ctx.buildDir;
 
         // Serialize the build manifest as a JS module that sets the global.
         // The adapter writes this as _timber-manifest-init.mjs and imports it
@@ -50,6 +51,12 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
             : ctx.buildManifest;
           const json = JSON.stringify(manifest);
           manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${json};\n`;
+
+          // Embed the deployment ID for version skew detection (TIM-446).
+          // The server reads this at startup via setDeploymentId().
+          if (ctx.deploymentId) {
+            manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
+          }
         }
 
         // Strip JS from the RSC plugin's assets manifest when client JS
@@ -97,7 +104,8 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
     let manifest: Record<string, unknown>;
     try {
       manifest = JSON.parse(jsonStr);
-    } catch {
+    } catch (err) {
+      swallow(err, `corrupted RSC assets manifest: ${path}`, { level: 'warn' });
       continue;
     }
 

package/src/plugins/build-manifest.ts

@@ -16,9 +16,10 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
+import { randomUUID } from 'node:crypto';
 import type { Plugin, ResolvedConfig } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { BuildManifest } from '../server/build-manifest.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.
@@ -242,6 +243,16 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     configResolved(config: ResolvedConfig) {
       resolvedBase = config.base;
       isDev = config.command === 'serve';
+
+      // Generate a per-build deployment ID early so virtual:timber-config
+      // can serialize it during the load hook (which runs before generateBundle).
+      // A random UUID is used instead of a content hash — determinism provides
+      // no real benefit here since you almost never redeploy identical code,
+      // and a random ID avoids the timing problem where the content hash was
+      // only available after generateBundle (TIM-452).
+      if (!isDev && !ctx.deploymentId) {
+        ctx.deploymentId = randomUUID().replace(/-/g, '').slice(0, 16);
+      }
     },
 
     resolveId(id: string) {

package/src/plugins/build-report.ts

@@ -15,9 +15,10 @@
 
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
+import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
 
@@ -83,33 +84,23 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
-  const routes: RouteInfo[] = [];
-
-  function walk(node: SegmentNode, chain: SegmentNode[]): void {
-    const currentChain = [...chain, node];
-    const path = node.urlPath || '/';
-
-    if (node.page) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.page.filePath });
-    }
-    if (node.route) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
-    }
-
-    // Recurse into child segments only — skip parallel slots (node.slots)
-    for (const child of node.children) walk(child, currentChain);
-  }
-
-  walk(tree.root, []);
+  const leaves = collectLeafRoutes(tree.root);
+  const routes: RouteInfo[] = leaves.map((leaf) => ({
+    path: leaf.urlPath,
+    segments: leaf.segments,
+    entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null,
+  }));
 
   // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
   // Keep the entry with the longest segment chain (most specific match).

package/src/plugins/client-chunks.ts

@@ -0,0 +1,65 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by layout boundary to balance route-scoped
+ * code splitting with HTTP request count. A constant group name would collapse
+ * all routes into one chunk (every page downloads every client component).
+ * Per-serverChunk grouping creates many sub-500B files. Layout-boundary
+ * grouping is the middle ground.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499.
+ */
+
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Groups by the first non-group route segment under appDir so that all
+ * client components belonging to the same layout boundary land in one
+ * chunk. For example:
+ *   - `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) → `"client-shared"`
+ *
+ * This balances route-scoped code splitting with HTTP request count:
+ * fewer chunks than per-serverChunk, but still avoids downloading every
+ * client component on every page.
+ */
+export function clientChunkGroup(
+  meta: { id: string; normalizedId: string; serverChunk: string },
+  appDir: string
+): string {
+  const { normalizedId, serverChunk } = meta;
+
+  // Shared chunks (not associated with a single route entry) get one group.
+  if (serverChunk.startsWith('shared:')) return 'client-shared';
+
+  // Derive the layout boundary from the file's location relative to the
+  // app directory. normalizedId is root-relative (e.g. "app/dashboard/shell.tsx"
+  // or "src/app/dashboard/shell.tsx"). We find the "app/" prefix and walk
+  // segments after it to find the first non-group directory.
+  const relPath = normalizedId.replace(/\\/g, '/');
+
+  // Find the app directory boundary in the path. The last segment of appDir
+  // is the app folder name (usually "app").
+  const appDirName = appDir.replace(/\\/g, '/').split('/').pop() || 'app';
+  const appIdx = relPath.indexOf(appDirName + '/');
+  if (appIdx === -1) return 'client-shared';
+
+  const withinApp = relPath.slice(appIdx + appDirName.length + 1);
+  const segments = withinApp.split('/');
+
+  // Find first directory segment that isn't a route group like (group-a)
+  for (const seg of segments) {
+    // Skip the filename itself
+    if (seg.includes('.')) break;
+    // Skip route groups — parenthesized segments like (group-a)
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    // Found a real route segment
+    return `client-${seg}`;
+  }
+
+  // Root-level files (layout.tsx, page.tsx directly in app/) go into the
+  // shared group since the root layout is loaded on every page.
+  return 'client-shared';
+}

package/src/plugins/content.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',