@valbuild/core 0.124.0 → 0.126.0

package/CHANGELOG.md

@@ -1,5 +1,201 @@
 # @valbuild/core
 
+## 0.126.0
+
+### Minor Changes
+
+- [#652](https://github.com/valbuild/val/pull/652) [`f2fe70d`](https://github.com/valbuild/val/commit/f2fe70dab2b65000dfaf289f09c70b4a8291467a) Thanks [@freekh](https://github.com/freekh)! - `s.union` is now `s.discriminatedUnion` and `s.enum`.
+
+  `s.union` did two unrelated jobs and worked out which one you meant from its
+  first argument: a string key meant a tagged union of objects, literal schemas
+  meant a set of allowed strings. Those are now two schemas with two names.
+
+  ```ts
+  // A fixed set of strings — presents as a dropdown
+  s.enum("primary", "secondary", "ghost"); // Schema<"primary" | "secondary" | "ghost">
+
+  // One of several object shapes, told apart by a tag field
+  s.discriminatedUnion(
+    "type",
+    s.object({ type: s.literal("hero"), heading: s.string() }),
+    s.object({ type: s.literal("quote"), text: s.string() }),
+  );
+  ```
+
+  `s.enum` takes the strings directly, so the `s.literal(...)` wrapper is gone.
+
+  **`s.union` still works** — it is deprecated, and it builds exactly the schema
+  above, so nothing has to change today:
+
+  ```ts
+  s.union(s.literal("one"), s.literal("two")); // → s.enum("one", "two")
+  s.union("type", pageA, pageB); // → s.discriminatedUnion("type", pageA, pageB)
+  ```
+
+  The two are different kinds of node, and that is the reason for the split. A
+  discriminated union is a container: the selected variant's fields are the fields
+  being edited, and everything that walks a schema descends through it. An enum is
+  a leaf — a string with a closed domain — so nothing recurses into it. Told apart
+  only by the shape of `key`, every consumer had to re-derive which one it was
+  holding; each now has its own serialized type (`"discriminated-union"` and
+  `"enum"`) and Val Studio has a field per kind rather than one field that
+  branches.
+
+  Two behaviour changes fall out of the split, both of them fixes:
+
+  - A value that is not a string at all now fails an enum's validation with a
+    type error. `s.union` of literals only ever checked the value against its
+    literals when the value WAS a string, so a number or an object where an enum
+    was declared validated clean.
+  - An enum field now shows its validation errors in Val Studio where the field
+    is opened on its own — the module editor and the canvas's fields column — and
+    gets the compact error layout inside an inline list row. It is a leaf now, so
+    it goes through the same error rendering as every other leaf field; the string
+    union bypassed it and showed nothing in those places.
+
+  Several latent crashes in the old `s.union` are fixed on the way past, all of
+  them cases where it threw a `TypeError` instead of reporting:
+
+  - A required discriminated union holding `null` now reports a type error rather
+    than throwing, and resolving a path underneath a nullable one that is `null`
+    gives the error the API promises instead of a crash.
+  - `s.literal("")` is a legal discriminator tag, and `s.enum("")` a legal value.
+    Both used to be treated as absent by a truthiness check — in path resolution,
+    in stega encoding, and in the message that lists a union's valid tags. The
+    editor's dropdowns handle them too: an empty value is reserved by the select
+    component and had to be mapped around.
+  - A variant that omits the discriminator entirely is now reported as the schema
+    error it is, instead of throwing while the check looked for it.
+  - An enum's value is now indexed for search, like every other string leaf. The
+    old string union was never indexed at all, so searching for one of its values
+    could not find the field.
+  - A nullable discriminated union set to `null` no longer renders a spinner that
+    never resolves.
+
+  `s.discriminatedUnion` also requires at least one variant, as `s.enum` requires
+  at least one value: a union with nothing to select is not a thing to write, and
+  everything downstream reads the first variant where it needs any.
+
+  If you read serialized schemas yourself, that is the breaking part: `type` is no
+  longer `"union"`, an enum carries `values: string[]` instead of a `key` plus
+  `items` of literal schemas, and `UnionSchema` is no longer a class.
+  `SerializedUnionSchema`, `SerializedStringUnionSchema`,
+  `SerializedObjectUnionSchema` and `UnionSchema` remain as deprecated type
+  aliases.
+
+### Patch Changes
+
+- [#661](https://github.com/valbuild/val/pull/661) [`171208a`](https://github.com/valbuild/val/commit/171208a20177e68ed5a8b1a6fdaabfe893a6aa5f) Thanks [@freekh](https://github.com/freekh)! - Every schema method now has a worked `@example` in its JSDoc, so hovering it in
+  your editor shows what to write.
+
+  That covers the whole builder surface — `.describe()`, `.validate()`,
+  `.nullable()`, `.readonly()`, `.hidden()`, `.preview()`, `.render()`, and the
+  per-type methods such as `.minLength()`, `.regexp()`, `.raw()`, `.multiline()`,
+  `.from()` / `.to()`, `.remote()`, `.jsonValues()` and `.external()` — as well as
+  `c.define()`, `c.json()`, `c.external()` and the `val` helpers (`val.attrs`,
+  `val.raw`, `val.unstable_getPath` and friends).
+
+  One of the examples corrected a real trap: a custom validator returns
+  `false | string`, so the natural-looking
+
+  ```ts
+  s.string().validate((val) => val.trim() === val || "No surrounding spaces");
+  ```
+
+  does not type check — `||` yields `true`, and `true` is not one of the two
+  answers. Write it as a ternary instead:
+
+  ```ts
+  s.string().validate((val) =>
+    val.trim() === val ? false : "No surrounding spaces",
+  );
+  ```
+
+  The examples are checked in CI, not just written: one test asks the TypeScript
+  checker for the doc each method actually resolves to and fails if it has no
+  `@example`, and another compiles every example it finds.
+
+## 0.125.0
+
+### Minor Changes
+
+- [#638](https://github.com/valbuild/val/pull/638) [`c390397`](https://github.com/valbuild/val/commit/c390397cb5e203eb1bedae3a6fab15726e850b90) Thanks [@freekh](https://github.com/freekh)! - Val now runs on TanStack Start.
+
+  `@valbuild/tanstack` is a new package with everything `@valbuild/next` has: Val
+  Studio at `/val`, the on-page overlay and canvas, draft mode, the client hooks,
+  server-side content reads, images, and the MCP tools.
+
+  ```sh
+  npm install @valbuild/tanstack
+  ```
+
+  ```ts
+  // val.config.ts
+  import { initVal } from "@valbuild/tanstack";
+  const { s, c, config, tanstackRouter } = initVal({ project: "org/project" });
+  ```
+
+  **Routes are first class.** A Val module for a route is named after the route
+  file it sits beside — `src/routes/posts.$postId.tsx` is served content by
+  `src/routes/posts.$postId.val.ts` — and its keys are the URLs that route serves:
+
+  ```ts
+  export default c.define(
+    "/src/routes/posts.$postId.val.ts",
+    s.router(tanstackRouter, s.object({ title: s.string() })),
+    { "/posts/hello-world": { title: "Hello world" } },
+  );
+  ```
+
+  `.` and `/` both separate segments, `$param` is a parameter, `$` is a splat, and
+  `index`, `route`, `(groups)` and `_pathless` layouts add no URL segment — the
+  same rules TanStack Router uses for the route file itself. Val validates every
+  key against that pattern, and Val Studio shows these modules as a sitemap under
+  **Pages**, where an editor can add a page.
+
+  Point the route generator away from your content files, in `vite.config.ts` and
+  `tsr.config.json`:
+
+  ```ts
+  tanstackStart({ router: { routeFileIgnorePattern: "\\.val\\.[tj]sx?$" } });
+  ```
+
+  See the [README](https://github.com/valbuild/val/blob/main/packages/tanstack/README.md)
+  for the full wiring, and `examples/tanstack` for a working app.
+
+  **Also fixed, for everyone:** `Internal.VERSION.core` was `null` in any ESM
+  bundle — it was read with `require("../package.json")` inside a `try`, so the
+  failure was silent. That version goes into every remote file ref and proxy mode
+  refuses to start without it. Every package now reads its version through a
+  static JSON import, which is inlined at build time.
+
+  Two smaller fixes that came out of running the whole toolchain against a
+  TanStack project:
+
+  - `val versions` reports `@valbuild/tanstack`, and `val debug` writes a snapshot
+    that names whichever framework package the captured project actually has.
+  - `@valbuild/eslint-plugin` reads a `tsconfig.json` that has comments in it. A
+    tsconfig is JSONC, and `JSON.parse` is not — so on any project whose tsconfig
+    carries a comment (the TanStack starter's does) the
+    `module-in-val-modules` rule threw `Expected double-quoted property name in
+JSON` on the first file and took the whole lint run with it.
+
+  Three fixes found by driving the Studio against a real TanStack app:
+
+  - **A draft image now loads on the page.** The source the Studio pushes to the
+    host page carries `patch_id` for any file whose bytes are still in a patch, so
+    the page asks `/api/val/files/...?patch_id=` rather than a `/public` path that
+    nothing has written yet. This was silent — the image just did not appear — and
+    it affects any page that reads media through the hooks rather than on the
+    server, `@valbuild/next` included.
+  - **A splat route no longer logs an error on every render.** TanStack returns
+    both `_splat` and `*` for the same parameter; Val reported the second as a
+    parameter it could not place in the path.
+  - The TanStack example and starter render a 404 page instead of throwing
+    `notFound()` from a component, which escaped to the error boundary and logged
+    `Error in renderToReadableStream` (and, with no not-found component
+    configured, aborted the response) on every miss.
+
 ## 0.124.0
 
 ### Minor Changes

package/dist/declarations/src/getSourcePathFromRoute.d.ts

@@ -2,14 +2,23 @@ import type { ModuleFilePath, SourcePath } from "./val/index.js";
 import type { SerializedSchema } from "./schema/index.js";
 /**
  * Given a URL pathname (e.g. "/blogs/blog-1") and all serialized module schemas,
- * finds the matching next-app-router module and returns the module file path
- * and the source path for that route's content.
+ * finds the page-router module that serves that route and returns the module
+ * file path and the source path for that route's content.
  *
  * External routers (e.g. external-url-router) are intentionally skipped.
- * Returns null if no next-app-router module matches the pathname.
+ * Returns null if no page-router module matches the pathname.
  */
 export declare function getSourcePathFromRoute(pathname: string, schemas: Record<ModuleFilePath, SerializedSchema>): {
     moduleFilePath: ModuleFilePath;
     sourcePath: SourcePath;
     route: string;
 } | null;
+/**
+ * Whether a router id is one whose keys are routes of this site.
+ *
+ * The same question `getSourcePathFromRoute` asks, exported because the Studio
+ * asks it too — a page router gets the sitemap and the "Pages" menu, an
+ * external one gets a flat list of URLs — and the two must not disagree about
+ * which is which.
+ */
+export declare function isPageRouter(routerId: string): boolean;

package/dist/declarations/src/index.d.ts

@@ -63,20 +63,23 @@ export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetim
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
 export { type SerializedRouteSchema, RouteSchema } from "./schema/route.js";
 export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtext.js";
-export { type SerializedUnionSchema, UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
+export { type SerializedDiscriminatedUnionSchema, type DiscriminatedUnionSourceOf, DiscriminatedUnionSchema, } from "./schema/discriminatedUnion.js";
+export { type SerializedEnumSchema, EnumSchema } from "./schema/enum.js";
+export { type SerializedUnionSchema, type UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
 export { type SerializedLiteralSchema, LiteralSchema } from "./schema/literal.js";
 export { deserializeSchema } from "./schema/deserialize.js";
 export { type PreviewItem, type ItemPreviewInput, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";
 export { type InlineRender, type FieldRender, isInlineRender } from "./render.js";
 export type { ValRouter, RouteValidationError } from "./router.js";
-export { getSourcePathFromRoute } from "./getSourcePathFromRoute.js";
+export { parseNextJsRoutePattern, parseTanStackRoutePattern, tanStackSegmentsOfRoutePath, validateUrlAgainstPattern, } from "./router.js";
+export { getSourcePathFromRoute, isPageRouter } from "./getSourcePathFromRoute.js";
 export declare const FATAL_ERROR_TYPES: readonly ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];
 export type FatalErrorType = (typeof FATAL_ERROR_TYPES)[number];
 export declare const DEFAULT_CONTENT_HOST = "https://content.val.build";
 export declare const DEFAULT_APP_HOST = "https://admin.val.build";
 declare const Internal: {
     VERSION: {
-        core: string | null;
+        core: string;
     };
     mediaUrl: typeof mediaUrl;
     resolveMedia: typeof resolveMedia;
@@ -93,6 +96,7 @@ declare const Internal: {
     splitModuleFilePathAndModulePath: typeof splitModuleFilePathAndModulePath;
     joinModuleFilePathAndModulePath: typeof joinModuleFilePathAndModulePath;
     nextAppRouter: import("./router.js").ValRouter;
+    tanstackRouter: import("./router.js").ValRouter;
     externalPageRouter: import("./router.js").ValRouter;
     color: {
         parseColor: typeof parseColor;

package/dist/declarations/src/initSchema.d.ts

@@ -4,6 +4,8 @@ import { object } from "./schema/object.js";
 import { string } from "./schema/string.js";
 import { boolean } from "./schema/boolean.js";
 import { union } from "./schema/union.js";
+import { discriminatedUnion } from "./schema/discriminatedUnion.js";
+import { enumSchema } from "./schema/enum.js";
 import { richtext } from "./schema/richtext.js";
 import { image } from "./schema/image.js";
 import { literal } from "./schema/literal.js";
@@ -67,32 +69,58 @@ export type InitSchema = {
      */
     readonly number: typeof number;
     /**
-     * Define a union.
+     * Define one of several object shapes, told apart by a tag field.
      *
-     * @example // union of string literals
-     * const schema = s.union(s.literal("test"), s.literal("test2"));
-     * export default c.define("/example.val.ts", schema, "test");
+     * The first argument names the field that carries the tag; every object must
+     * set it to a distinct `s.literal(...)`. The editor shows a dropdown of the
+     * tags and the fields of whichever one is selected.
      *
-     * @example // union of string literals
-     * const schema = s.union("type", s.object({
-     *   type: s.literal("test"),
-     *   value: s.string()
-     * }), s.object({
-     *   type: s.literal("test2"),
-     *   value: s.string()
-     * }));
+     * @example
+     * const schema = s.discriminatedUnion("type",
+     *   s.object({ type: s.literal("text"), value: s.string() }),
+     *   s.object({ type: s.literal("image"), value: s.image() }),
+     * );
      * export default c.define("/example.val.ts", schema, {
-     *   type: "test",
+     *   type: "text",
      *   value: "test"
      * });
      *
      */
+    readonly discriminatedUnion: typeof discriminatedUnion;
+    /**
+     * Define a string that must be one of a fixed set of values.
+     *
+     * The editor shows a dropdown of the values, in the order they are given.
+     *
+     * @example
+     * const schema = s.enum("primary", "secondary", "ghost");
+     * export default c.define("/example.val.ts", schema, "primary");
+     *
+     */
+    readonly enum: typeof enumSchema;
+    /**
+     * Define a union.
+     *
+     * @deprecated Use `s.discriminatedUnion` for a tagged union of objects, or
+     * `s.enum` for one of a fixed set of strings.
+     *
+     * @example // was: a union of string literals
+     * const schema = s.enum("test", "test2");
+     *
+     * @example // was: a tagged union of objects
+     * const schema = s.discriminatedUnion("type",
+     *   s.object({ type: s.literal("test"), value: s.string() }),
+     *   s.object({ type: s.literal("test2"), value: s.string() }),
+     * );
+     *
+     */
     readonly union: typeof union;
     /**
      * Define a rich text.
      *
      * @example
-     * const schema = s.richtext();
+     * // Every tag and style is off until the options ask for it.
+     * const schema = s.richtext({ h1: true, bold: true });
      * export default c.define("/example.val.ts", schema, [
      *   { tag: "h1", children: ["Title 1"] },
      * ]);
@@ -119,6 +147,7 @@ export type InitSchema = {
      *
      * @example
      * // Backed by a gallery: width, height and mimeType live there.
+     * import galleryVal from "./gallery.val"; // an s.images() module
      * const schema = s.image(galleryVal);
      * export default c.define("/example.val.ts", schema, {
      *   path: "/public/val/example.png",
@@ -346,7 +375,9 @@ export declare function initSchema(): {
         max?: number;
         min?: number;
     }) => import("./index.js").NumberSchema<number>;
-    union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./index.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
+    discriminatedUnion: <Key extends string, T extends import("./schema/discriminatedUnion.js").DiscriminatedUnionItems<Key>>(key: Key, ...objects: T) => import("./index.js").DiscriminatedUnionSchema<Key, T, import("./index.js").DiscriminatedUnionSourceOf<Key, T>>;
+    enum: <T extends string>(values_0: T, ...values: T[]) => import("./index.js").EnumSchema<T>;
+    union: typeof union;
     richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./index.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
     image: typeof image;
     literal: <T extends string>(value: T) => import("./index.js").LiteralSchema<T>;

package/dist/declarations/src/initVal.d.ts

@@ -4,11 +4,71 @@ import { getValPath as getPath } from "./val/index.js";
 import { json } from "./source/json.js";
 import { external } from "./source/external.js";
 export type ContentConstructor = {
+    /**
+     * Define a content module: a schema, and source that matches it.
+     *
+     * The first argument is the module's own file path, starting at the root of
+     * the project. It has to match the file the call is written in - that is how
+     * the Studio, validation and patching find the module again - so a
+     * `c.define` is always the default export of one `*.val.ts` file.
+     *
+     * @example
+     * const schema = s.object({ title: s.string() });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     * });
+     */
     define: typeof define;
+    /**
+     * Put one entry of a `.jsonValues()` record in its own `*.val.json` file,
+     * loaded lazily.
+     *
+     * What is written in the module is the `import()` thunk, not the content: the
+     * `.val.ts` stays small, and the runtime, the Studio and validation each work
+     * an entry at a time. That is what lets a record or a router hold many
+     * thousands of entries.
+     *
+     * Only for the entries of a record that said `.jsonValues()`.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
+     */
     json: typeof json;
+    /**
+     * The source of a record whose entries live behind an adapter - a database,
+     * an HTTP API, a bucket - instead of in the module.
+     *
+     * It takes no arguments, and there is nothing to fill in: it says only that
+     * the entries are somewhere else. WHICH adapter is the schema's business
+     * (`.external("posts")`), and the binding is registered where the app is set
+     * up.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     */
     external: typeof external;
 };
 export type ValConstructor = {
+    /**
+     * The source path of a value inside a module, or `undefined` for something
+     * that did not come from Val.
+     *
+     * A path is what every Val API addresses content by, so this is the way from
+     * a value you are holding back to the thing the Studio, a patch or a
+     * validation error names. Unstable: the shape of a path is not part of the
+     * public API yet.
+     *
+     * @example
+     * import pageVal from "./page.val";
+     * const path = val.unstable_getPath(pageVal); // "/page.val.ts"
+     */
     unstable_getPath: typeof getPath;
 };
 export type ConfigDirectory = `/public` | `/public/${string}`;
@@ -39,9 +99,57 @@ export type ValConfig = {
     };
 };
 export type InitVal = {
+    /**
+     * The content constructor: `c.define` for a module, `c.json` and
+     * `c.external` for entries that live outside it.
+     *
+     * @example
+     * const schema = s.object({ title: s.string() });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     * });
+     */
     c: ContentConstructor;
+    /**
+     * Helpers for working with content your app is already holding, rather than
+     * for declaring it.
+     *
+     * `@valbuild/next` and `@valbuild/tanstack` add to this: `val.attrs` for
+     * visual editing, `val.raw` to strip the stega encoding off a string.
+     *
+     * @example
+     * import pageVal from "./page.val";
+     * const path = val.unstable_getPath(pageVal);
+     */
     val: ValConstructor;
+    /**
+     * The schema constructor: one method per type of content Val can hold.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string().describe("Shown in the browser tab"),
+     *   image: s.image().nullable(),
+     * });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     *   image: null,
+     * });
+     */
     s: InitSchema;
+    /**
+     * The config this `initVal` was called with, as the rest of Val reads it.
+     *
+     * Exported from `val.config.ts` so that the Val API route and the Studio get
+     * the same object the content modules were built with.
+     *
+     * @example
+     * import { initVal } from "@valbuild/core";
+     * const { s, c, val, config } = initVal({
+     *   project: "myorg/myproject",
+     *   files: { directory: "/public/val" },
+     * });
+     * export { s, c, val, config };
+     */
     config: ValConfig;
 };
 export declare const initVal: (config?: ValConfig) => InitVal;

package/dist/declarations/src/render.d.ts

@@ -59,10 +59,11 @@ export type FieldRender = InlineRender;
  * question, and a disagreement between them is a row you can edit in place but
  * that "add" navigates away from.
  *
- * A tagged union counts as inline when the union itself declares it OR when
- * ANY of its variants does. A page-builder list is `s.array(s.union("type",
- * block, block, ...))` and the natural place to write the render is on the
- * blocks, one per block type — the union is a dispatch, not something the
+ * A discriminated union counts as inline when the union itself declares it OR
+ * when ANY of its variants does. A page-builder list is
+ * `s.array(s.discriminatedUnion("type", block, block, ...))` and the natural
+ * place to write the render is on the blocks, one per block type — the union
+ * is a dispatch, not something the
  * author thinks of as the field. `some` rather than `every` because the row
  * draws the union's own editor (the tag selector plus the matched variant's
  * fields), which handles every variant either way: with `every`, adding one

package/dist/declarations/src/router.d.ts

@@ -23,6 +23,51 @@ export declare const nextAppRouter: ValRouter;
  * - /app/(..)(dashboard)/feed/page.val.ts -> ["feed"] (interception route)
  */
 export declare function parseNextJsRoutePattern(moduleFilePath: string): string[];
+/**
+ * Parse a TanStack Router route pattern out of a Val module file path.
+ *
+ * TanStack Router's file conventions are not Next's, so this is a different
+ * parser rather than a flag on the one above. A Val module for a route lives
+ * beside the route file and is named the same way — `routes/posts.$postId.tsx`
+ * is served content by `routes/posts.$postId.val.ts` — so the pattern is the
+ * file path with the conventions applied:
+ *
+ * - `.` and `/` both separate segments (`posts.$postId.val.ts` and
+ *   `posts/$postId.val.ts` are the same route)
+ * - `$param` is a dynamic segment, `$` on its own is a splat
+ * - `index` is the directory's own route and contributes no segment
+ * - `route` is a layout for the directory, likewise
+ * - `(group)` folders and `_pathless` layout segments are not in the URL
+ * - a trailing `_` on a segment opts out of nesting and is not in the URL
+ *
+ * The result is expressed in the SAME vocabulary the Next parser uses
+ * (`[param]`, `[...param]`), because everything downstream — validation, the
+ * sitemap, the key inputs in the Studio — is written against that vocabulary
+ * and there is no reason for two.
+ *
+ * - /src/routes/posts.$postId.val.ts -> ["posts", "[postId]"]
+ * - /routes/posts/$postId.val.ts     -> ["posts", "[postId]"]
+ * - /src/routes/index.val.ts         -> []
+ * - /src/routes/files.$.val.ts       -> ["files", "[..._splat]"]
+ * - /src/routes/(app)/_layout.about.val.ts -> ["about"]
+ */
+export declare function parseTanStackRoutePattern(moduleFilePath: string): string[];
+/**
+ * The URL segments of a TanStack route path, given relative to `routes/`.
+ *
+ * Exported because the Studio derives the same pattern from the same file path
+ * and must not disagree with validation about what a route is.
+ */
+export declare function tanStackSegmentsOfRoutePath(routePath: string): string[];
+/**
+ * The router for a TanStack Router (and TanStack Start) app.
+ *
+ * Like `nextAppRouter` this does not belong in core — it is here for the same
+ * reason that one is: the serialized schema carries only a router id, so the
+ * thing that turns an id back into a validator has to be somewhere every
+ * consumer can reach.
+ */
+export declare const tanstackRouter: ValRouter;
 export interface ValRouter {
     getRouterId(): string;
     validate(moduleFilePath: ModuleFilePath, urlPaths: string[]): RouteValidationError[];

package/dist/declarations/src/schema/array.d.ts

@@ -38,7 +38,47 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     private readonly previewInput;
     private readonly renderInput;
     constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s
+     *   .array(s.string())
+     *   .describe("Bullet points shown under the heading");
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+     */
     describe(description: string | null): ArraySchema<T, Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The function is given the whole array. To validate one item, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the item's own row.
+     *
+     * @example
+     * const schema = s.array(s.string()).validate((val) =>
+     *   val.length <= 3 ? false : "At most 3 items",
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+     */
     validate(validationFunction: (src: Src) => false | string): ArraySchema<T, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -55,6 +95,25 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
      * is the item of another container, in search, in references. What its rows
      * show is the ITEM schema's `preview`, not this. Never how the field is
      * edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * // The preview of the ARRAY, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const tags = s.array(s.string()).preview(({ val }) => ({
+     *   title: `${val.length} tags`,
+     * }));
+     * export default c.define("/example.val.ts", s.record(tags), {
+     *   "a-post": ["news", "release"],
+     * });
+     *
+     * @example
+     * // Rows of an array come from the ITEM's preview, not the array's:
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): ArraySchema<T, Src>;
     /**
@@ -63,6 +122,12 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.record(s.array(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, {
+     *   "a-post": ["news", "release"],
+     * });
      */
     render(input: FieldRender): ArraySchema<T, Src>;
 }