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

package/dist/params/define-schema.d.ts

@@ -7,7 +7,7 @@
  *
  * Design doc: design/41-global-params.md
  */
-import type { Codec } from '../codec.js';
+import type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 /**
  * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.
@@ -19,7 +19,30 @@ export type InferCodecType<V> = V extends Codec<infer T> ? T : V extends Standar
     parseServerSide: (value: string) => infer T;
 } ? T : string;
 /** Acceptable codec value for segment params: a Codec or Standard Schema. */
-type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+export type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+/** Codec constraint for catch-all segment keys (`[...name]`). */
+export type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;
+/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */
+export type OptionalCatchAllParamCodec = OptionalCatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[] | undefined>;
+/**
+ * Resolves the required codec type for a given bracket key pattern.
+ * - `[...name]`    → requires a catch-all codec
+ * - `[[...name]]`  → requires an optional catch-all codec
+ * - `[name]`       → accepts any segment param codec
+ */
+export type CodecForKey<K extends string> = K extends `[[...${string}]]` ? OptionalCatchAllParamCodec : K extends `[...${string}]` ? CatchAllParamCodec : SegmentParamCodec;
+/**
+ * Registry interface augmented by codegen with known filesystem bracket keys.
+ * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.
+ */
+export interface ValidDynamicSegmentKeysRegistry {
+}
+/**
+ * Union of valid bracket keys for defineSchema.
+ * After codegen runs, this is the set of filesystem segment names.
+ * Before codegen (fresh project), accepts any string.
+ */
+export type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never ? string : keyof ValidDynamicSegmentKeysRegistry & string;
 /** Configuration object for defineSchema. */
 export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
     segmentParams: S;
@@ -48,6 +71,11 @@ export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
  * });
  * ```
  */
-export declare function defineSchema<S extends Record<string, SegmentParamCodec>>(config: SchemaConfig<S>): SchemaConfig<S>;
-export {};
+export declare function defineSchema<S extends {
+    [K in keyof S]: K extends ValidDynamicSegmentKeys ? K extends string ? CodecForKey<K> : SegmentParamCodec : never;
+}>(config: {
+    segmentParams: S;
+}): {
+    segmentParams: S;
+};
 //# sourceMappingURL=define-schema.d.ts.map

package/dist/params/define-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-schema.d.ts","sourceRoot":"","sources":["../../src/params/define-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM5D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAC1B,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACpB,CAAC,GACD,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GACjC,CAAC,GACD,CAAC,SAAS;IAAE,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;CAAE,GACvD,CAAC,GACD,MAAM,CAAC;AAEjB,6EAA6E;AAC7E,KAAK,iBAAiB,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAEpE,6CAA6C;AAC7C,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACvE,aAAa,EAAE,CAAC,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACtE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,YAAY,CAAC,CAAC,CAAC,CAEjB"}
+{"version":3,"file":"define-schema.d.ts","sourceRoot":"","sources":["../../src/params/define-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM5D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAC1B,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACpB,CAAC,GACD,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GACjC,CAAC,GACD,CAAC,SAAS;IAAE,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;CAAE,GACvD,CAAC,GACD,MAAM,CAAC;AAEjB,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAE3E,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAE/F,4EAA4E;AAC5E,MAAM,MAAM,0BAA0B,GAClC,qBAAqB,CAAC,OAAO,CAAC,GAC9B,gBAAgB,CAAC,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,QAAQ,MAAM,IAAI,GACpE,0BAA0B,GAC1B,CAAC,SAAS,OAAO,MAAM,GAAG,GACxB,kBAAkB,GAClB,iBAAiB,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,+BAA+B;CAAG;AAEnD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,+BAA+B,SAAS,KAAK,GACrF,MAAM,GACN,MAAM,+BAA+B,GAAG,MAAM,CAAC;AAEnD,6CAA6C;AAC7C,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACvE,aAAa,EAAE,CAAC,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS;KACP,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,uBAAuB,GAC7C,CAAC,SAAS,MAAM,GACd,WAAW,CAAC,CAAC,CAAC,GACd,iBAAiB,GACnB,KAAK;CACV,EACD,MAAM,EAAE;IAAE,aAAa,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,CAAC,CAAA;CAAE,CAEpD"}

package/dist/params/index.d.ts

@@ -1,5 +1,5 @@
 export { defineSchema } from './define-schema.js';
-export type { InferCodecType, SchemaConfig } from './define-schema.js';
+export type { InferCodecType, SchemaConfig, SegmentParamCodec, ValidDynamicSegmentKeys, ValidDynamicSegmentKeysRegistry, } from './define-schema.js';
 export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.js';
 export { setLinkCodecs, getLinkCodec } from './codec-registry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/params/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/params/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/params/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/params/index.js

@@ -1,5 +1,5 @@
-import { n as toBracketKey, t as resolveSchemaCodecs } from "../_chunks/resolve-schema-23Mc8aLi.js";
-import { n as setLinkCodecs, t as getLinkCodec } from "../_chunks/codec-registry-V7ARyeLN.js";
+import { n as toBracketKey, t as resolveSchemaCodecs } from "../_chunks/resolve-schema-Bf8eC6q6.js";
+import { n as setLinkCodecs, t as getLinkCodec } from "../_chunks/codec-registry-G9hD5LOq.js";
 //#region src/params/define-schema.ts
 /**
 * Define the global segment param schema.

package/dist/params/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/params/define-schema.ts"],"sourcesContent":["/**\n * defineSchema — global segment param schema definition.\n *\n * Identity function at runtime; the type information is what matters.\n * The Vite plugin reads the schema at build time for codegen, and\n * the pipeline reads it at runtime for coercion.\n *\n * Design doc: design/41-global-params.md\n */\n\nimport type { Codec } from '../codec.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.\n *\n * Used by codegen to reference schema types without hardcoding:\n *   `InferCodecType<typeof schema.segmentParams['[year]']>`\n */\nexport type InferCodecType<V> =\n  V extends Codec<infer T>\n    ? T\n    : V extends StandardSchemaV1<infer T>\n      ? T\n      : V extends { parseServerSide: (value: string) => infer T }\n        ? T\n        : string;\n\n/** Acceptable codec value for segment params: a Codec or Standard Schema. */\ntype SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;\n\n/** Configuration object for defineSchema. */\nexport interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {\n  segmentParams: S;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Define the global segment param schema.\n *\n * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,\n * `[[...slug]]`) mapped to a codec. This makes the relationship between\n * filesystem segments and codecs visually obvious.\n *\n * A dynamic segment with no key here defaults to `string` at codegen time.\n *\n * ```ts\n * // app/schema.ts\n * import { defineSchema } from '@timber-js/app/params';\n * import { codec } from '@timber-js/app/codec';\n * import { z } from 'zod';\n *\n * export default defineSchema({\n *   segmentParams: {\n *     '[artistSlug]': codec.string,\n *     '[year]': codec.integer,\n *     '[id]': z.coerce.number().int(),\n *   },\n * });\n * ```\n */\nexport function defineSchema<S extends Record<string, SegmentParamCodec>>(\n  config: SchemaConfig<S>\n): SchemaConfig<S> {\n  return config;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,SAAgB,aACd,QACiB;AACjB,QAAO"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/params/define-schema.ts"],"sourcesContent":["/**\n * defineSchema — global segment param schema definition.\n *\n * Identity function at runtime; the type information is what matters.\n * The Vite plugin reads the schema at build time for codegen, and\n * the pipeline reads it at runtime for coercion.\n *\n * Design doc: design/41-global-params.md\n */\n\nimport type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.\n *\n * Used by codegen to reference schema types without hardcoding:\n *   `InferCodecType<typeof schema.segmentParams['[year]']>`\n */\nexport type InferCodecType<V> =\n  V extends Codec<infer T>\n    ? T\n    : V extends StandardSchemaV1<infer T>\n      ? T\n      : V extends { parseServerSide: (value: string) => infer T }\n        ? T\n        : string;\n\n/** Acceptable codec value for segment params: a Codec or Standard Schema. */\nexport type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;\n\n/** Codec constraint for catch-all segment keys (`[...name]`). */\nexport type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;\n\n/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */\nexport type OptionalCatchAllParamCodec =\n  | OptionalCatchAllCodec<unknown>\n  | StandardSchemaV1<readonly unknown[] | undefined>;\n\n/**\n * Resolves the required codec type for a given bracket key pattern.\n * - `[...name]`    → requires a catch-all codec\n * - `[[...name]]`  → requires an optional catch-all codec\n * - `[name]`       → accepts any segment param codec\n */\nexport type CodecForKey<K extends string> = K extends `[[...${string}]]`\n  ? OptionalCatchAllParamCodec\n  : K extends `[...${string}]`\n    ? CatchAllParamCodec\n    : SegmentParamCodec;\n\n/**\n * Registry interface augmented by codegen with known filesystem bracket keys.\n * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.\n */\nexport interface ValidDynamicSegmentKeysRegistry {}\n\n/**\n * Union of valid bracket keys for defineSchema.\n * After codegen runs, this is the set of filesystem segment names.\n * Before codegen (fresh project), accepts any string.\n */\nexport type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never\n  ? string\n  : keyof ValidDynamicSegmentKeysRegistry & string;\n\n/** Configuration object for defineSchema. */\nexport interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {\n  segmentParams: S;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Define the global segment param schema.\n *\n * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,\n * `[[...slug]]`) mapped to a codec. This makes the relationship between\n * filesystem segments and codecs visually obvious.\n *\n * A dynamic segment with no key here defaults to `string` at codegen time.\n *\n * ```ts\n * // app/schema.ts\n * import { defineSchema } from '@timber-js/app/params';\n * import { codec } from '@timber-js/app/codec';\n * import { z } from 'zod';\n *\n * export default defineSchema({\n *   segmentParams: {\n *     '[artistSlug]': codec.string,\n *     '[year]': codec.integer,\n *     '[id]': z.coerce.number().int(),\n *   },\n * });\n * ```\n */\nexport function defineSchema<\n  S extends {\n    [K in keyof S]: K extends ValidDynamicSegmentKeys\n      ? K extends string\n        ? CodecForKey<K>\n        : SegmentParamCodec\n      : never;\n  },\n>(config: { segmentParams: S }): { segmentParams: S } {\n  return config;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA,SAAgB,aAQd,QAAoD;AACpD,QAAO"}

package/dist/params/resolve-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-schema.d.ts","sourceRoot":"","sources":["../../src/params/resolve-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAmCzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAQhC"}
+{"version":3,"file":"resolve-schema.d.ts","sourceRoot":"","sources":["../../src/params/resolve-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAmCzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS3E;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAchC"}

package/dist/plugins/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAwBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2F1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAuNxD"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAoBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2F1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAuNxD"}

package/dist/routing/index.d.ts

@@ -9,4 +9,6 @@ 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/routing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC5E,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC5E,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/routing/index.js

@@ -1,4 +1,4 @@
 import { i as INTERCEPTION_MARKERS, n as classifyUrlSegment, r as DEFAULT_PAGE_EXTENSIONS, t as classifySegment } from "../_chunks/segment-classify-CnfLLvir.js";
-import { t as scanRoutes } from "../_chunks/scanner-DmfoB7iK.js";
-import { n as collectInterceptionRewrites, r as generateRouteMap, t as collectLeafRoutes } from "../_chunks/walkers-DgOXkTts.js";
-export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectInterceptionRewrites, collectLeafRoutes, generateRouteMap, scanRoutes };
+import { p as scanRoutes } from "../_chunks/cli-schema-sync-ByZPGGmS.js";
+import { a as generateRouteMap, i as collectInterceptionRewrites, n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-DNp9tHyV.js";
+export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectDynamicSegmentsFromTree, collectInterceptionRewrites, collectLeafRoutes, generateRouteMap, scanRoutes, validateSchemaAgainstRoutes };

package/dist/routing/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/routing/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,SAAS,EAIT,aAAa,EAEd,MAAM,YAAY,CAAC;AA+CpB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CAoChF"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/routing/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,SAAS,EAIT,aAAa,EAEd,MAAM,YAAY,CAAC;AA+CpB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CAwChF"}

package/dist/routing/schema-validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Schema key/value validation against the filesystem route tree.
+ *
+ * Runs at codegen time (build + dev) to catch mismatches between
+ * app/schema.ts keys and the actual dynamic segments on disk.
+ *
+ * Design doc: design/41-global-params.md
+ */
+import type { RouteTree } from './types.js';
+export interface SchemaWarning {
+    type: 'stale-key' | 'missing-key' | 'bracket-mismatch';
+    key: string;
+    message: string;
+    filesystemKey?: string;
+}
+/**
+ * Collect all unique bracket-keyed dynamic segment names from a route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export declare function collectDynamicSegmentsFromTree(tree: RouteTree): Set<string>;
+/**
+ * Validate schema keys against the filesystem route tree.
+ *
+ * Returns warnings for:
+ * - Stale keys: schema keys that don't match any filesystem segment
+ * - Bracket form mismatches: same param name, different bracket form
+ * - Missing keys: filesystem segments not registered in schema (informational)
+ */
+export declare function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): SchemaWarning[];
+/**
+ * Core validation: compare schema keys against filesystem segments.
+ * Exported separately for testing without filesystem dependencies.
+ */
+export declare function validateKeys(schemaKeys: string[], filesystemSegments: Set<string>): SchemaWarning[];
+//# sourceMappingURL=schema-validation.d.ts.map

package/dist/routing/schema-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validation.d.ts","sourceRoot":"","sources":["../../src/routing/schema-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAIzD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,GAAG,aAAa,GAAG,kBAAkB,CAAC;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,CAI3E;AA2BD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAY5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAAE,EACpB,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC9B,aAAa,EAAE,CA+DjB"}

package/dist/search-params/index.js

@@ -1,6 +1,6 @@
-import { n as registerSearchParams, t as getSearchParamsDefinition } from "../_chunks/registry-Dp_hJL4s.js";
-import { i as isStandardSchema, n as fromSchema, r as isCodec } from "../_chunks/schema-bridge-eL5vQDSA.js";
-import { n as defineSearchParams } from "../_chunks/define-8zQ8Vm7x.js";
+import { n as registerSearchParams, t as getSearchParamsDefinition } from "../_chunks/registry-BI9cgCt7.js";
+import { i as isStandardSchema, n as fromSchema, r as isCodec } from "../_chunks/schema-bridge-o0SwFtXW.js";
+import { n as defineSearchParams } from "../_chunks/define-jeHDXZGq.js";
 //#region src/search-params/wrappers.ts
 /**
 * Wrap a nullable codec with a default value. When the inner codec returns

package/dist/segment-params/index.js

@@ -1,2 +1,2 @@
-import { r as defineSegmentParams } from "../_chunks/define-zQX6e1tN.js";
+import { r as defineSegmentParams } from "../_chunks/define-CPVQaWbx.js";
 export { defineSegmentParams };

package/dist/server/index.js

@@ -1,6 +1,6 @@
 import { a as getSpanId, d as withSpan, o as getTraceId, p as formFlashAls, t as addSpanEvent, v as isDebug, y as isDevMode } from "../_chunks/tracing-DvKLzCFa.js";
-import { t as formatSize } from "../_chunks/format-CR6v1pWE.js";
-import { D as getCookieJar, a as revalidateTag, b as getSegmentParams, c as DenySignal, f as deny, h as waitUntil, i as revalidatePath, l as RedirectSignal, m as redirectExternal, o as coerce, p as redirect, s as parseFormData, u as RedirectType, v as getHeaders } from "../_chunks/actions-Cw-7NfJJ.js";
+import { t as formatSize } from "../_chunks/format-BjN9HLu9.js";
+import { D as getCookieJar, a as revalidateTag, b as getSegmentParams, c as DenySignal, f as deny, h as waitUntil, i as revalidatePath, l as RedirectSignal, m as redirectExternal, o as coerce, p as redirect, s as parseFormData, u as RedirectType, v as getHeaders } from "../_chunks/actions-Dy8vOjFt.js";
 //#region src/server/sensitive-fields.ts
 /**
 * Sensitive field stripping — removes password/token/CVV-style fields

package/dist/server/internal.js

@@ -3,10 +3,10 @@ import { a as warnRedirectInSuspense, c as warnSuspenseWrappingChildren, i as wa
 import { n as classifyUrlSegment } from "../_chunks/segment-classify-CnfLLvir.js";
 import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-Cjmvi3rQ.js";
 import { a as logProxyError, c as logRequestReceived, d as logSwrRefetchFailed, f as logWaitUntilRejected, h as swallow, i as logMiddlewareShortCircuit, l as logRouteError, m as setLogger, n as logCacheMiss, o as logRenderError, p as logWaitUntilUnsupported, r as logMiddlewareError, s as logRequestCompleted, t as getLogger, u as logSlowRequest } from "../_chunks/logger-DDmK5skc.js";
-import { C as setMatchedSegmentPath, E as getCookie, O as getSetCookieHeaders, S as runWithRequestContext, T as setSegmentParams, _ as getHeader, b as getSegmentParams, c as DenySignal, d as RenderError, g as applyRequestHeaderOverlay, l as RedirectSignal, n as executeAction, o as coerce, r as isRscActionRequest, t as buildNoJsResponse, w as setMutableCookieContext, x as markResponseFlushed, y as getSearchParams } from "../_chunks/actions-Cw-7NfJJ.js";
+import { C as setMatchedSegmentPath, E as getCookie, O as getSetCookieHeaders, S as runWithRequestContext, T as setSegmentParams, _ as getHeader, b as getSegmentParams, c as DenySignal, d as RenderError, g as applyRequestHeaderOverlay, l as RedirectSignal, n as executeAction, o as coerce, r as isRscActionRequest, t as buildNoJsResponse, w as setMutableCookieContext, x as markResponseFlushed, y as getSearchParams } from "../_chunks/actions-Dy8vOjFt.js";
 import "../client/error-boundary.js";
-import { n as toBracketKey } from "../_chunks/resolve-schema-23Mc8aLi.js";
-import "../_chunks/segment-context-Bg0pFbLT.js";
+import { n as toBracketKey } from "../_chunks/resolve-schema-Bf8eC6q6.js";
+import "../_chunks/segment-context-EsfQpS--.js";
 import { readFile } from "node:fs/promises";
 import { createElement } from "react";
 //#region src/server/server-timing.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.120",
+  "version": "0.2.0-alpha.121",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -114,6 +114,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -157,9 +162,5 @@
   },
   "engines": {
     "node": ">=22.12.0"
-  },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/codec.ts

@@ -22,6 +22,23 @@ export interface Codec<T> {
   serialize(value: T): string | null;
 }
 
+/**
+ * Marker interface for codecs designed for catch-all segments (`[...slug]`).
+ * These codecs expect `string[]` input from the router.
+ */
+export interface CatchAllCodec<T> extends Codec<T> {
+  readonly __catchAll: true;
+}
+
+/**
+ * Marker interface for codecs designed for optional catch-all segments (`[[...slug]]`).
+ * These codecs expect `string[] | undefined` input from the router.
+ */
+export interface OptionalCatchAllCodec<T> extends Codec<T> {
+  readonly __catchAll: true;
+  readonly __optional: true;
+}
+
 /**
  * Recursive JSON-serializable type. The canonical definition for data that
  * can safely cross the RSC → client boundary.
@@ -86,6 +103,7 @@ export const codec = {
   } satisfies Codec<string>,
 
   stringArray: {
+    __catchAll: true as const,
     parse(value: string | string[] | undefined): string[] {
       if (Array.isArray(value)) return value;
       return value ? [value] : [];
@@ -93,5 +111,37 @@ export const codec = {
     serialize(value: string[]): string | null {
       return value.join('/');
     },
-  } satisfies Codec<string[]>,
+  } satisfies CatchAllCodec<string[]>,
+
+  catchAll<T>(inner: Codec<T>): CatchAllCodec<T[]> {
+    return {
+      __catchAll: true as const,
+      parse(value: string | string[] | undefined): T[] {
+        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];
+        if (arr.length === 0) {
+          throw new Error('Catch-all segment requires at least one value');
+        }
+        return arr.map((item) => inner.parse(item));
+      },
+      serialize(value: T[]): string | null {
+        return value.map((item) => inner.serialize(item)).join('/');
+      },
+    };
+  },
+
+  optionalCatchAll<T>(inner: Codec<T>): OptionalCatchAllCodec<T[] | undefined> {
+    return {
+      __catchAll: true as const,
+      __optional: true as const,
+      parse(value: string | string[] | undefined): T[] | undefined {
+        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];
+        if (arr.length === 0) return undefined;
+        return arr.map((item) => inner.parse(item));
+      },
+      serialize(value: T[] | undefined): string | null {
+        if (!value || value.length === 0) return null;
+        return value.map((item) => inner.serialize(item)).join('/');
+      },
+    };
+  },
 } as const;

package/src/params/define-schema.ts

@@ -8,7 +8,7 @@
  * Design doc: design/41-global-params.md
  */
 
-import type { Codec } from '../codec.js';
+import type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 
 // ---------------------------------------------------------------------------
@@ -31,7 +31,42 @@ export type InferCodecType<V> =
         : string;
 
 /** Acceptable codec value for segment params: a Codec or Standard Schema. */
-type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+export type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+
+/** Codec constraint for catch-all segment keys (`[...name]`). */
+export type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;
+
+/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */
+export type OptionalCatchAllParamCodec =
+  | OptionalCatchAllCodec<unknown>
+  | StandardSchemaV1<readonly unknown[] | undefined>;
+
+/**
+ * Resolves the required codec type for a given bracket key pattern.
+ * - `[...name]`    → requires a catch-all codec
+ * - `[[...name]]`  → requires an optional catch-all codec
+ * - `[name]`       → accepts any segment param codec
+ */
+export type CodecForKey<K extends string> = K extends `[[...${string}]]`
+  ? OptionalCatchAllParamCodec
+  : K extends `[...${string}]`
+    ? CatchAllParamCodec
+    : SegmentParamCodec;
+
+/**
+ * Registry interface augmented by codegen with known filesystem bracket keys.
+ * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.
+ */
+export interface ValidDynamicSegmentKeysRegistry {}
+
+/**
+ * Union of valid bracket keys for defineSchema.
+ * After codegen runs, this is the set of filesystem segment names.
+ * Before codegen (fresh project), accepts any string.
+ */
+export type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never
+  ? string
+  : keyof ValidDynamicSegmentKeysRegistry & string;
 
 /** Configuration object for defineSchema. */
 export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
@@ -66,8 +101,14 @@ export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
  * });
  * ```
  */
-export function defineSchema<S extends Record<string, SegmentParamCodec>>(
-  config: SchemaConfig<S>
-): SchemaConfig<S> {
+export function defineSchema<
+  S extends {
+    [K in keyof S]: K extends ValidDynamicSegmentKeys
+      ? K extends string
+        ? CodecForKey<K>
+        : SegmentParamCodec
+      : never;
+  },
+>(config: { segmentParams: S }): { segmentParams: S } {
   return config;
 }

package/src/params/index.ts

@@ -6,6 +6,12 @@
 // See design/41-global-params.md
 
 export { defineSchema } from './define-schema.js';
-export type { InferCodecType, SchemaConfig } from './define-schema.js';
+export type {
+  InferCodecType,
+  SchemaConfig,
+  SegmentParamCodec,
+  ValidDynamicSegmentKeys,
+  ValidDynamicSegmentKeysRegistry,
+} from './define-schema.js';
 export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.js';
 export { setLinkCodecs, getLinkCodec } from './codec-registry.js';

package/src/params/resolve-schema.ts

@@ -63,6 +63,13 @@ 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);
+}
+
 /**
  * Resolve the global schema's segmentParams into a map of bracket-keyed
  * param name → resolved Codec.
@@ -81,6 +88,12 @@ 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.`
+      );
+    }
     resolved[bracketName] = resolveCodec(bracketName, value);
   }
 

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,
@@ -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 {