@valbuild/shared 0.123.3 → 0.125.0

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # @valbuild/shared
 
+## 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.
+
+### Patch Changes
+
+- Updated dependencies [[`c390397`](https://github.com/valbuild/val/commit/c390397cb5e203eb1bedae3a6fab15726e850b90)]:
+  - @valbuild/core@0.125.0
+
+## 0.124.0
+
+### Minor Changes
+
+- [#639](https://github.com/valbuild/val/pull/639) [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055) Thanks [@freekh](https://github.com/freekh)! - Show `.jsonValues()` entries in the history pane
+
+  A `.jsonValues()` record keeps each entry's content in its own `*.val.json`
+  file; the module's own content is just markers pointing at them. The history
+  pane had no way to fetch those files for a past commit, so every entry rendered
+  as an **empty field** — which reads as "the author left this blank", about
+  content that was simply stored somewhere else.
+
+  Entries now load in the history pane the same way they load in the Studio: one
+  at a time, when you open one. A commit with a thousand support pages costs
+  nothing until you look at one of them.
+
+  An entry that cannot be read says so instead of rendering blank — including the
+  case where the key did not exist yet at that commit, which is a real answer
+  rather than an error.
+
+### Patch Changes
+
+- [#639](https://github.com/valbuild/val/pull/639) [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055) Thanks [@freekh](https://github.com/freekh)! - Require a session to read a file from history
+
+  `GET /api/val/history/files` served a file at a given commit to anyone who
+  asked. It followed the reasoning of `/api/val/files`, which is deliberately
+  open — and neither half of that reasoning applies to it:
+
+  - `/files` stands on `patch_id` being an unguessable UUID. A **commit sha is
+    published** — `git log`, the GitHub UI, every pull request — so it is no
+    substitute for a credential.
+  - `/files` also _cannot_ require auth: draft images are fetched by the app's own
+    backend during Next image optimisation, with no cookies to send. Nothing
+    fetches history files server-side; both callers are the Studio, in a browser
+    that already holds the session.
+
+  So history files now require a session. `/files` is unchanged, and the reason
+  the two differ is written down in `architecture/media.md` so it is not "fixed"
+  in either direction later.
+
+  No action needed: the Studio sends its session cookie automatically.
+
+- Updated dependencies [[`aa89fc2`](https://github.com/valbuild/val/commit/aa89fc26de7028b3c5a1666b99afc03b39e92769)]:
+  - @valbuild/core@0.124.0
+
 ## 0.123.3
 
 ### Patch Changes

package/client/dist/valbuild-shared-client.cjs.dev.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var getSitemapTree = require('../../dist/getSitemapTree-a0c9a0e3.cjs.dev.js');
+var getSitemapTree = require('../../dist/getSitemapTree-d1977d3e.cjs.dev.js');
 require('@valbuild/core');
 
 
@@ -12,9 +12,12 @@ exports.VAL_CANVAS_MESSAGE = getSitemapTree.VAL_CANVAS_MESSAGE;
 exports.VAL_CANVAS_PARAM = getSitemapTree.VAL_CANVAS_PARAM;
 exports.VAL_CONFIG_SESSION_STORAGE_KEY = getSitemapTree.VAL_CONFIG_SESSION_STORAGE_KEY;
 exports.VAL_THEME_SESSION_STORAGE_KEY = getSitemapTree.VAL_THEME_SESSION_STORAGE_KEY;
-exports.getNextAppRouterSitemapTree = getSitemapTree.getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getSitemapTree.getNextAppRouterSourceFolder;
+exports.getPageRouterSitemapTree = getSitemapTree.getPageRouterSitemapTree;
+exports.getPageRouterSourceFolder = getSitemapTree.getPageRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getSitemapTree.getPatternFromModuleFilePath;
+exports.getTanStackRouterSourceFolder = getSitemapTree.getTanStackRouterSourceFolder;
+exports.isTanStackRoutesFolder = getSitemapTree.isTanStackRoutesFolder;
 exports.isValCanvasFrame = getSitemapTree.isValCanvasFrame;
 exports.isValCanvasPageMessage = getSitemapTree.isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = getSitemapTree.isValCanvasStudioMessage;

package/client/dist/valbuild-shared-client.cjs.prod.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var getSitemapTree = require('../../dist/getSitemapTree-77b1203a.cjs.prod.js');
+var getSitemapTree = require('../../dist/getSitemapTree-b320d033.cjs.prod.js');
 require('@valbuild/core');
 
 
@@ -12,9 +12,12 @@ exports.VAL_CANVAS_MESSAGE = getSitemapTree.VAL_CANVAS_MESSAGE;
 exports.VAL_CANVAS_PARAM = getSitemapTree.VAL_CANVAS_PARAM;
 exports.VAL_CONFIG_SESSION_STORAGE_KEY = getSitemapTree.VAL_CONFIG_SESSION_STORAGE_KEY;
 exports.VAL_THEME_SESSION_STORAGE_KEY = getSitemapTree.VAL_THEME_SESSION_STORAGE_KEY;
-exports.getNextAppRouterSitemapTree = getSitemapTree.getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getSitemapTree.getNextAppRouterSourceFolder;
+exports.getPageRouterSitemapTree = getSitemapTree.getPageRouterSitemapTree;
+exports.getPageRouterSourceFolder = getSitemapTree.getPageRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getSitemapTree.getPatternFromModuleFilePath;
+exports.getTanStackRouterSourceFolder = getSitemapTree.getTanStackRouterSourceFolder;
+exports.isTanStackRoutesFolder = getSitemapTree.isTanStackRoutesFolder;
 exports.isValCanvasFrame = getSitemapTree.isValCanvasFrame;
 exports.isValCanvasPageMessage = getSitemapTree.isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = getSitemapTree.isValCanvasStudioMessage;

package/client/dist/valbuild-shared-client.esm.js

@@ -1,2 +1,2 @@
-export { b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, h as getNextAppRouterSitemapTree, g as getNextAppRouterSourceFolder, j as getPatternFromModuleFilePath, f as isValCanvasFrame, i as isValCanvasPageMessage, e as isValCanvasStudioMessage, p as parseRoutePattern, w as withValCanvasParam } from '../../dist/getSitemapTree-d3e98a2e.esm.js';
+export { b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, g as getNextAppRouterSourceFolder, l as getPageRouterSitemapTree, j as getPageRouterSourceFolder, m as getPatternFromModuleFilePath, h as getTanStackRouterSourceFolder, k as isTanStackRoutesFolder, f as isValCanvasFrame, i as isValCanvasPageMessage, e as isValCanvasStudioMessage, p as parseRoutePattern, w as withValCanvasParam } from '../../dist/getSitemapTree-a6cb37cb.esm.js';
 import '@valbuild/core';

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -1329,6 +1329,80 @@ export declare const Api: {
      * actually mounts. A file at a fixed commit cannot change, so the response is
      * immutable and the browser's own cache handles flipping between commits.
      */
+    /**
+     * One `.jsonValues()` entry's content, as it was at a commit.
+     *
+     * The history pane's counterpart to `/json`. A `.jsonValues()` record's
+     * source is only `{_type:"json"}` markers - the content is per entry, fetched
+     * on demand - so without this the commit pane rendered every entry as an
+     * empty field, which is a claim that the author left it blank.
+     *
+     * One entry per request, deliberately: the store fetches an entry when
+     * something reads inside it, so a batch would mean guessing which entries the
+     * pane is about to show. Authenticated for the same reasons as
+     * `/history/files` below.
+     */
+    "/history/json": {
+        GET: {
+            req: {
+                query: {
+                    commit_sha: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    path: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    key: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+                    key: z.ZodString;
+                    content: z.ZodUnknown;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * A binary file as it was at a commit.
+     *
+     * AUTHENTICATED, unlike `/files` below - and the difference is not an
+     * oversight in either direction. See the comment on `/files`: what makes it
+     * safe to leave open is that a `patch_id` is an unguessable UUID, and what
+     * makes leaving it open NECESSARY is that a draft image is fetched by the
+     * app's own backend during Next image optimisation, with no cookies.
+     *
+     * Neither holds here. A commit sha is published - `git log`, the GitHub UI,
+     * every PR - so it is not a secret to stand in for a credential. And nothing
+     * fetches these server-side: they are read by the Studio, in a browser that
+     * has the session cookie, for the history pane and for staging a restore.
+     * So this one asks.
+     */
     "/history/files": {
         GET: {
             req: {
@@ -1337,6 +1411,9 @@ export declare const Api: {
                     path: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
                     remote: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
                 };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
             };
             res: z.ZodUnion<readonly [z.ZodObject<{
                 status: z.ZodLiteral<401>;

package/dist/declarations/src/internal/getNextAppRouterSourceFolder.d.ts

@@ -1,2 +1,26 @@
 import { ModuleFilePath } from "@valbuild/core";
 export declare function getNextAppRouterSourceFolder(moduleFilePath: ModuleFilePath): "/app" | "/src/app" | null;
+/**
+ * The folder a TanStack Router app keeps its route files in.
+ *
+ * The same question as above for the other convention: `routes/` at the project
+ * root, or under `src/`. A Val module for a route lives beside the route file
+ * and is named the same way, so this is the prefix to strip before reading the
+ * route pattern out of the rest.
+ */
+export declare function getTanStackRouterSourceFolder(moduleFilePath: ModuleFilePath): "/routes" | "/src/routes" | null;
+/**
+ * The route folder of whichever page router this module belongs to.
+ *
+ * The two conventions have disjoint prefixes — `app/` versus `routes/` — so a
+ * module file path answers this on its own, which is what the Studio needs: it
+ * walks every schema in the project and has no framework to ask.
+ */
+export declare function getPageRouterSourceFolder(moduleFilePath: ModuleFilePath): "/app" | "/src/app" | "/routes" | "/src/routes" | null;
+/**
+ * Whether a route folder is a TanStack Router one.
+ *
+ * Exported so the pattern derivation and the source-folder detection cannot
+ * drift apart about what `/src/routes` means.
+ */
+export declare function isTanStackRoutesFolder(srcFolder: string): boolean;

package/dist/declarations/src/internal/getSitemapTree.d.ts

@@ -23,8 +23,17 @@ export type SitemapNode = {
     moduleFilePath?: ModuleFilePath;
     sourcePath?: SourcePath | ModuleFilePath;
 };
-export declare function getNextAppRouterSitemapTree(srcFolder: string, paths: {
+export declare function getPageRouterSitemapTree(srcFolder: string, paths: {
     urlPath: string;
     moduleFilePath: string;
 }[]): SitemapNode;
+/**
+ * The route pattern a page-router module serves, e.g. `/blogs/[blog]`.
+ *
+ * Written in Next's vocabulary for both routers on purpose: the pattern is read
+ * by `parseRoutePattern`, the sitemap and the Studio's key inputs, none of which
+ * should have to know which framework the project uses. The TanStack branch
+ * translates that framework's conventions into it; see
+ * `tanStackSegmentsOfRoutePath` in `@valbuild/core` for the rules.
+ */
 export declare function getPatternFromModuleFilePath(moduleFilePath: string, srcFolder: string): string;

package/dist/{getSitemapTree-d3e98a2e.esm.js → getSitemapTree-a6cb37cb.esm.js}

@@ -1,4 +1,4 @@
-import { Internal } from '@valbuild/core';
+import { Internal, tanStackSegmentsOfRoutePath } from '@valbuild/core';
 
 var VAL_CONFIG_SESSION_STORAGE_KEY = "val-config";
 var VAL_THEME_SESSION_STORAGE_KEY = "val-theme";
@@ -135,6 +135,45 @@ function getNextAppRouterSourceFolder(moduleFilePath) {
   return null;
 }
 
+/**
+ * The folder a TanStack Router app keeps its route files in.
+ *
+ * The same question as above for the other convention: `routes/` at the project
+ * root, or under `src/`. A Val module for a route lives beside the route file
+ * and is named the same way, so this is the prefix to strip before reading the
+ * route pattern out of the rest.
+ */
+function getTanStackRouterSourceFolder(moduleFilePath) {
+  if (moduleFilePath.startsWith("/routes/")) {
+    return "/routes";
+  } else if (moduleFilePath.startsWith("/src/routes/")) {
+    return "/src/routes";
+  }
+  return null;
+}
+
+/**
+ * The route folder of whichever page router this module belongs to.
+ *
+ * The two conventions have disjoint prefixes — `app/` versus `routes/` — so a
+ * module file path answers this on its own, which is what the Studio needs: it
+ * walks every schema in the project and has no framework to ask.
+ */
+function getPageRouterSourceFolder(moduleFilePath) {
+  var _getNextAppRouterSour;
+  return (_getNextAppRouterSour = getNextAppRouterSourceFolder(moduleFilePath)) !== null && _getNextAppRouterSour !== void 0 ? _getNextAppRouterSour : getTanStackRouterSourceFolder(moduleFilePath);
+}
+
+/**
+ * Whether a route folder is a TanStack Router one.
+ *
+ * Exported so the pattern derivation and the source-folder detection cannot
+ * drift apart about what `/src/routes` means.
+ */
+function isTanStackRoutesFolder(srcFolder) {
+  return srcFolder === "/routes" || srcFolder === "/src/routes";
+}
+
 function _toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -245,8 +284,14 @@ function _createForOfIteratorHelper(r, e) {
   };
 }
 
-// Strictly speaking this should be in the next package but it's shared, because we want to use it in the ui package. We want to resolve that somehow
-function getNextAppRouterSitemapTree(srcFolder, paths) {
+// Strictly speaking this should be in the framework packages but it's shared,
+// because we want to use it in the ui package. We want to resolve that somehow.
+//
+// It is one function for both page routers because the tree it builds is made
+// of URL paths, which is the same thing in either: only `srcFolder` and the
+// pattern derivation differ, and both of those are arguments (or the one call
+// below).
+function getPageRouterSitemapTree(srcFolder, paths) {
   var root = {
     type: "node",
     name: "/",
@@ -358,7 +403,24 @@ function getNextAppRouterSitemapTree(srcFolder, paths) {
   }
   return root;
 }
+
+/**
+ * The route pattern a page-router module serves, e.g. `/blogs/[blog]`.
+ *
+ * Written in Next's vocabulary for both routers on purpose: the pattern is read
+ * by `parseRoutePattern`, the sitemap and the Studio's key inputs, none of which
+ * should have to know which framework the project uses. The TanStack branch
+ * translates that framework's conventions into it; see
+ * `tanStackSegmentsOfRoutePath` in `@valbuild/core` for the rules.
+ */
 function getPatternFromModuleFilePath(moduleFilePath, srcFolder) {
+  if (isTanStackRoutesFolder(srcFolder)) {
+    var routePath = moduleFilePath.slice(srcFolder.length).replace(/\.val\.[tj]sx?$/, "");
+    var segments = tanStackSegmentsOfRoutePath(routePath);
+    // "" rather than "/" for the root, so it matches what the Next branch
+    // returns for `/app/page.val.ts` — `parseRoutePattern` reads both as [].
+    return segments.length === 0 ? "" : "/".concat(segments.join("/"));
+  }
   return moduleFilePath.replace(srcFolder, "")
   // TODO: hacky!
   // remove route groups
@@ -366,4 +428,4 @@ function getPatternFromModuleFilePath(moduleFilePath, srcFolder) {
   .replace("/page.val.ts", "").replace("/page.val.js", "");
 }
 
-export { VAL_CONFIG_SESSION_STORAGE_KEY as V, _createForOfIteratorHelper as _, VAL_THEME_SESSION_STORAGE_KEY as a, VAL_AI_SESSION_STORAGE_KEY as b, VAL_CANVAS_PARAM as c, VAL_CANVAS_MESSAGE as d, isValCanvasStudioMessage as e, isValCanvasFrame as f, getNextAppRouterSourceFolder as g, getNextAppRouterSitemapTree as h, isValCanvasPageMessage as i, getPatternFromModuleFilePath as j, _objectSpread2 as k, _arrayLikeToArray as l, _unsupportedIterableToArray as m, _defineProperty as n, _typeof as o, parseRoutePattern as p, withValCanvasParam as w };
+export { VAL_CONFIG_SESSION_STORAGE_KEY as V, _createForOfIteratorHelper as _, VAL_THEME_SESSION_STORAGE_KEY as a, VAL_AI_SESSION_STORAGE_KEY as b, VAL_CANVAS_PARAM as c, VAL_CANVAS_MESSAGE as d, isValCanvasStudioMessage as e, isValCanvasFrame as f, getNextAppRouterSourceFolder as g, getTanStackRouterSourceFolder as h, isValCanvasPageMessage as i, getPageRouterSourceFolder as j, isTanStackRoutesFolder as k, getPageRouterSitemapTree as l, getPatternFromModuleFilePath as m, _objectSpread2 as n, _arrayLikeToArray as o, parseRoutePattern as p, _unsupportedIterableToArray as q, _defineProperty as r, _typeof as s, withValCanvasParam as w };

package/dist/{getSitemapTree-77b1203a.cjs.prod.js → getSitemapTree-b320d033.cjs.prod.js}

@@ -137,6 +137,45 @@ function getNextAppRouterSourceFolder(moduleFilePath) {
   return null;
 }
 
+/**
+ * The folder a TanStack Router app keeps its route files in.
+ *
+ * The same question as above for the other convention: `routes/` at the project
+ * root, or under `src/`. A Val module for a route lives beside the route file
+ * and is named the same way, so this is the prefix to strip before reading the
+ * route pattern out of the rest.
+ */
+function getTanStackRouterSourceFolder(moduleFilePath) {
+  if (moduleFilePath.startsWith("/routes/")) {
+    return "/routes";
+  } else if (moduleFilePath.startsWith("/src/routes/")) {
+    return "/src/routes";
+  }
+  return null;
+}
+
+/**
+ * The route folder of whichever page router this module belongs to.
+ *
+ * The two conventions have disjoint prefixes — `app/` versus `routes/` — so a
+ * module file path answers this on its own, which is what the Studio needs: it
+ * walks every schema in the project and has no framework to ask.
+ */
+function getPageRouterSourceFolder(moduleFilePath) {
+  var _getNextAppRouterSour;
+  return (_getNextAppRouterSour = getNextAppRouterSourceFolder(moduleFilePath)) !== null && _getNextAppRouterSour !== void 0 ? _getNextAppRouterSour : getTanStackRouterSourceFolder(moduleFilePath);
+}
+
+/**
+ * Whether a route folder is a TanStack Router one.
+ *
+ * Exported so the pattern derivation and the source-folder detection cannot
+ * drift apart about what `/src/routes` means.
+ */
+function isTanStackRoutesFolder(srcFolder) {
+  return srcFolder === "/routes" || srcFolder === "/src/routes";
+}
+
 function _toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -247,8 +286,14 @@ function _createForOfIteratorHelper(r, e) {
   };
 }
 
-// Strictly speaking this should be in the next package but it's shared, because we want to use it in the ui package. We want to resolve that somehow
-function getNextAppRouterSitemapTree(srcFolder, paths) {
+// Strictly speaking this should be in the framework packages but it's shared,
+// because we want to use it in the ui package. We want to resolve that somehow.
+//
+// It is one function for both page routers because the tree it builds is made
+// of URL paths, which is the same thing in either: only `srcFolder` and the
+// pattern derivation differ, and both of those are arguments (or the one call
+// below).
+function getPageRouterSitemapTree(srcFolder, paths) {
   var root = {
     type: "node",
     name: "/",
@@ -360,7 +405,24 @@ function getNextAppRouterSitemapTree(srcFolder, paths) {
   }
   return root;
 }
+
+/**
+ * The route pattern a page-router module serves, e.g. `/blogs/[blog]`.
+ *
+ * Written in Next's vocabulary for both routers on purpose: the pattern is read
+ * by `parseRoutePattern`, the sitemap and the Studio's key inputs, none of which
+ * should have to know which framework the project uses. The TanStack branch
+ * translates that framework's conventions into it; see
+ * `tanStackSegmentsOfRoutePath` in `@valbuild/core` for the rules.
+ */
 function getPatternFromModuleFilePath(moduleFilePath, srcFolder) {
+  if (isTanStackRoutesFolder(srcFolder)) {
+    var routePath = moduleFilePath.slice(srcFolder.length).replace(/\.val\.[tj]sx?$/, "");
+    var segments = core.tanStackSegmentsOfRoutePath(routePath);
+    // "" rather than "/" for the root, so it matches what the Next branch
+    // returns for `/app/page.val.ts` — `parseRoutePattern` reads both as [].
+    return segments.length === 0 ? "" : "/".concat(segments.join("/"));
+  }
   return moduleFilePath.replace(srcFolder, "")
   // TODO: hacky!
   // remove route groups
@@ -379,9 +441,12 @@ exports._defineProperty = _defineProperty;
 exports._objectSpread2 = _objectSpread2;
 exports._typeof = _typeof;
 exports._unsupportedIterableToArray = _unsupportedIterableToArray;
-exports.getNextAppRouterSitemapTree = getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getNextAppRouterSourceFolder;
+exports.getPageRouterSitemapTree = getPageRouterSitemapTree;
+exports.getPageRouterSourceFolder = getPageRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getPatternFromModuleFilePath;
+exports.getTanStackRouterSourceFolder = getTanStackRouterSourceFolder;
+exports.isTanStackRoutesFolder = isTanStackRoutesFolder;
 exports.isValCanvasFrame = isValCanvasFrame;
 exports.isValCanvasPageMessage = isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = isValCanvasStudioMessage;

package/dist/{getSitemapTree-a0c9a0e3.cjs.dev.js → getSitemapTree-d1977d3e.cjs.dev.js}

@@ -137,6 +137,45 @@ function getNextAppRouterSourceFolder(moduleFilePath) {
   return null;
 }
 
+/**
+ * The folder a TanStack Router app keeps its route files in.
+ *
+ * The same question as above for the other convention: `routes/` at the project
+ * root, or under `src/`. A Val module for a route lives beside the route file
+ * and is named the same way, so this is the prefix to strip before reading the
+ * route pattern out of the rest.
+ */
+function getTanStackRouterSourceFolder(moduleFilePath) {
+  if (moduleFilePath.startsWith("/routes/")) {
+    return "/routes";
+  } else if (moduleFilePath.startsWith("/src/routes/")) {
+    return "/src/routes";
+  }
+  return null;
+}
+
+/**
+ * The route folder of whichever page router this module belongs to.
+ *
+ * The two conventions have disjoint prefixes — `app/` versus `routes/` — so a
+ * module file path answers this on its own, which is what the Studio needs: it
+ * walks every schema in the project and has no framework to ask.
+ */
+function getPageRouterSourceFolder(moduleFilePath) {
+  var _getNextAppRouterSour;
+  return (_getNextAppRouterSour = getNextAppRouterSourceFolder(moduleFilePath)) !== null && _getNextAppRouterSour !== void 0 ? _getNextAppRouterSour : getTanStackRouterSourceFolder(moduleFilePath);
+}
+
+/**
+ * Whether a route folder is a TanStack Router one.
+ *
+ * Exported so the pattern derivation and the source-folder detection cannot
+ * drift apart about what `/src/routes` means.
+ */
+function isTanStackRoutesFolder(srcFolder) {
+  return srcFolder === "/routes" || srcFolder === "/src/routes";
+}
+
 function _toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -247,8 +286,14 @@ function _createForOfIteratorHelper(r, e) {
   };
 }
 
-// Strictly speaking this should be in the next package but it's shared, because we want to use it in the ui package. We want to resolve that somehow
-function getNextAppRouterSitemapTree(srcFolder, paths) {
+// Strictly speaking this should be in the framework packages but it's shared,
+// because we want to use it in the ui package. We want to resolve that somehow.
+//
+// It is one function for both page routers because the tree it builds is made
+// of URL paths, which is the same thing in either: only `srcFolder` and the
+// pattern derivation differ, and both of those are arguments (or the one call
+// below).
+function getPageRouterSitemapTree(srcFolder, paths) {
   var root = {
     type: "node",
     name: "/",
@@ -360,7 +405,24 @@ function getNextAppRouterSitemapTree(srcFolder, paths) {
   }
   return root;
 }
+
+/**
+ * The route pattern a page-router module serves, e.g. `/blogs/[blog]`.
+ *
+ * Written in Next's vocabulary for both routers on purpose: the pattern is read
+ * by `parseRoutePattern`, the sitemap and the Studio's key inputs, none of which
+ * should have to know which framework the project uses. The TanStack branch
+ * translates that framework's conventions into it; see
+ * `tanStackSegmentsOfRoutePath` in `@valbuild/core` for the rules.
+ */
 function getPatternFromModuleFilePath(moduleFilePath, srcFolder) {
+  if (isTanStackRoutesFolder(srcFolder)) {
+    var routePath = moduleFilePath.slice(srcFolder.length).replace(/\.val\.[tj]sx?$/, "");
+    var segments = core.tanStackSegmentsOfRoutePath(routePath);
+    // "" rather than "/" for the root, so it matches what the Next branch
+    // returns for `/app/page.val.ts` — `parseRoutePattern` reads both as [].
+    return segments.length === 0 ? "" : "/".concat(segments.join("/"));
+  }
   return moduleFilePath.replace(srcFolder, "")
   // TODO: hacky!
   // remove route groups
@@ -379,9 +441,12 @@ exports._defineProperty = _defineProperty;
 exports._objectSpread2 = _objectSpread2;
 exports._typeof = _typeof;
 exports._unsupportedIterableToArray = _unsupportedIterableToArray;
-exports.getNextAppRouterSitemapTree = getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getNextAppRouterSourceFolder;
+exports.getPageRouterSitemapTree = getPageRouterSitemapTree;
+exports.getPageRouterSourceFolder = getPageRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getPatternFromModuleFilePath;
+exports.getTanStackRouterSourceFolder = getTanStackRouterSourceFolder;
+exports.isTanStackRoutesFolder = isTanStackRoutesFolder;
 exports.isValCanvasFrame = isValCanvasFrame;
 exports.isValCanvasPageMessage = isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = isValCanvasStudioMessage;

package/internal/dist/valbuild-shared-internal.cjs.dev.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var core = require('@valbuild/core');
-var getSitemapTree = require('../../dist/getSitemapTree-a0c9a0e3.cjs.dev.js');
+var getSitemapTree = require('../../dist/getSitemapTree-d1977d3e.cjs.dev.js');
 var zod = require('zod');
 var zodValidationError = require('zod-validation-error');
 var FlexSearch = require('flexsearch');
@@ -2463,6 +2463,66 @@ var Api = {
    * actually mounts. A file at a fixed commit cannot change, so the response is
    * immutable and the browser's own cache handles flipping between commits.
    */
+  /**
+   * One `.jsonValues()` entry's content, as it was at a commit.
+   *
+   * The history pane's counterpart to `/json`. A `.jsonValues()` record's
+   * source is only `{_type:"json"}` markers - the content is per entry, fetched
+   * on demand - so without this the commit pane rendered every entry as an
+   * empty field, which is a claim that the author left it blank.
+   *
+   * One entry per request, deliberately: the store fetches an entry when
+   * something reads inside it, so a batch would mean guessing which entries the
+   * pane is about to show. Authenticated for the same reasons as
+   * `/history/files` below.
+   */
+  "/history/json": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          path: onlyOneStringQueryParam,
+          key: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          path: ModuleFilePath,
+          key: zod.z.string(),
+          content: zod.z.unknown()
+        })
+      })])
+    }
+  },
+  /**
+   * A binary file as it was at a commit.
+   *
+   * AUTHENTICATED, unlike `/files` below - and the difference is not an
+   * oversight in either direction. See the comment on `/files`: what makes it
+   * safe to leave open is that a `patch_id` is an unguessable UUID, and what
+   * makes leaving it open NECESSARY is that a draft image is fetched by the
+   * app's own backend during Next image optimisation, with no cookies.
+   *
+   * Neither holds here. A commit sha is published - `git log`, the GitHub UI,
+   * every PR - so it is not a secret to stand in for a credential. And nothing
+   * fetches these server-side: they are read by the Studio, in a browser that
+   * has the session cookie, for the history pane and for staging a restore.
+   * So this one asks.
+   */
   "/history/files": {
     GET: {
       req: {
@@ -2470,6 +2530,9 @@ var Api = {
           commit_sha: onlyOneStringQueryParam,
           path: onlyOneStringQueryParam,
           remote: onlyOneStringQueryParam.optional()
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
         }
       },
       res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
@@ -5494,9 +5557,12 @@ exports.VAL_CANVAS_MESSAGE = getSitemapTree.VAL_CANVAS_MESSAGE;
 exports.VAL_CANVAS_PARAM = getSitemapTree.VAL_CANVAS_PARAM;
 exports.VAL_CONFIG_SESSION_STORAGE_KEY = getSitemapTree.VAL_CONFIG_SESSION_STORAGE_KEY;
 exports.VAL_THEME_SESSION_STORAGE_KEY = getSitemapTree.VAL_THEME_SESSION_STORAGE_KEY;
-exports.getNextAppRouterSitemapTree = getSitemapTree.getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getSitemapTree.getNextAppRouterSourceFolder;
+exports.getPageRouterSitemapTree = getSitemapTree.getPageRouterSitemapTree;
+exports.getPageRouterSourceFolder = getSitemapTree.getPageRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getSitemapTree.getPatternFromModuleFilePath;
+exports.getTanStackRouterSourceFolder = getSitemapTree.getTanStackRouterSourceFolder;
+exports.isTanStackRoutesFolder = getSitemapTree.isTanStackRoutesFolder;
 exports.isValCanvasFrame = getSitemapTree.isValCanvasFrame;
 exports.isValCanvasPageMessage = getSitemapTree.isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = getSitemapTree.isValCanvasStudioMessage;

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var core = require('@valbuild/core');
-var getSitemapTree = require('../../dist/getSitemapTree-77b1203a.cjs.prod.js');
+var getSitemapTree = require('../../dist/getSitemapTree-b320d033.cjs.prod.js');
 var zod = require('zod');
 var zodValidationError = require('zod-validation-error');
 var FlexSearch = require('flexsearch');
@@ -2463,6 +2463,66 @@ var Api = {
    * actually mounts. A file at a fixed commit cannot change, so the response is
    * immutable and the browser's own cache handles flipping between commits.
    */
+  /**
+   * One `.jsonValues()` entry's content, as it was at a commit.
+   *
+   * The history pane's counterpart to `/json`. A `.jsonValues()` record's
+   * source is only `{_type:"json"}` markers - the content is per entry, fetched
+   * on demand - so without this the commit pane rendered every entry as an
+   * empty field, which is a claim that the author left it blank.
+   *
+   * One entry per request, deliberately: the store fetches an entry when
+   * something reads inside it, so a batch would mean guessing which entries the
+   * pane is about to show. Authenticated for the same reasons as
+   * `/history/files` below.
+   */
+  "/history/json": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          path: onlyOneStringQueryParam,
+          key: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          path: ModuleFilePath,
+          key: zod.z.string(),
+          content: zod.z.unknown()
+        })
+      })])
+    }
+  },
+  /**
+   * A binary file as it was at a commit.
+   *
+   * AUTHENTICATED, unlike `/files` below - and the difference is not an
+   * oversight in either direction. See the comment on `/files`: what makes it
+   * safe to leave open is that a `patch_id` is an unguessable UUID, and what
+   * makes leaving it open NECESSARY is that a draft image is fetched by the
+   * app's own backend during Next image optimisation, with no cookies.
+   *
+   * Neither holds here. A commit sha is published - `git log`, the GitHub UI,
+   * every PR - so it is not a secret to stand in for a credential. And nothing
+   * fetches these server-side: they are read by the Studio, in a browser that
+   * has the session cookie, for the history pane and for staging a restore.
+   * So this one asks.
+   */
   "/history/files": {
     GET: {
       req: {
@@ -2470,6 +2530,9 @@ var Api = {
           commit_sha: onlyOneStringQueryParam,
           path: onlyOneStringQueryParam,
           remote: onlyOneStringQueryParam.optional()
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
         }
       },
       res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
@@ -5494,9 +5557,12 @@ exports.VAL_CANVAS_MESSAGE = getSitemapTree.VAL_CANVAS_MESSAGE;
 exports.VAL_CANVAS_PARAM = getSitemapTree.VAL_CANVAS_PARAM;
 exports.VAL_CONFIG_SESSION_STORAGE_KEY = getSitemapTree.VAL_CONFIG_SESSION_STORAGE_KEY;
 exports.VAL_THEME_SESSION_STORAGE_KEY = getSitemapTree.VAL_THEME_SESSION_STORAGE_KEY;
-exports.getNextAppRouterSitemapTree = getSitemapTree.getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getSitemapTree.getNextAppRouterSourceFolder;
+exports.getPageRouterSitemapTree = getSitemapTree.getPageRouterSitemapTree;
+exports.getPageRouterSourceFolder = getSitemapTree.getPageRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getSitemapTree.getPatternFromModuleFilePath;
+exports.getTanStackRouterSourceFolder = getSitemapTree.getTanStackRouterSourceFolder;
+exports.isTanStackRoutesFolder = getSitemapTree.isTanStackRoutesFolder;
 exports.isValCanvasFrame = getSitemapTree.isValCanvasFrame;
 exports.isValCanvasPageMessage = getSitemapTree.isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = getSitemapTree.isValCanvasStudioMessage;

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1,6 +1,6 @@
 import { Internal, CODE_LANGUAGES, DEFAULT_COLOR_FORMAT } from '@valbuild/core';
-import { _ as _createForOfIteratorHelper, k as _objectSpread2, l as _arrayLikeToArray, m as _unsupportedIterableToArray, n as _defineProperty, o as _typeof } from '../../dist/getSitemapTree-d3e98a2e.esm.js';
-export { b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, h as getNextAppRouterSitemapTree, g as getNextAppRouterSourceFolder, j as getPatternFromModuleFilePath, f as isValCanvasFrame, i as isValCanvasPageMessage, e as isValCanvasStudioMessage, p as parseRoutePattern, w as withValCanvasParam } from '../../dist/getSitemapTree-d3e98a2e.esm.js';
+import { _ as _createForOfIteratorHelper, n as _objectSpread2, o as _arrayLikeToArray, q as _unsupportedIterableToArray, r as _defineProperty, s as _typeof } from '../../dist/getSitemapTree-a6cb37cb.esm.js';
+export { b as VAL_AI_SESSION_STORAGE_KEY, d as VAL_CANVAS_MESSAGE, c as VAL_CANVAS_PARAM, V as VAL_CONFIG_SESSION_STORAGE_KEY, a as VAL_THEME_SESSION_STORAGE_KEY, g as getNextAppRouterSourceFolder, l as getPageRouterSitemapTree, j as getPageRouterSourceFolder, m as getPatternFromModuleFilePath, h as getTanStackRouterSourceFolder, k as isTanStackRoutesFolder, f as isValCanvasFrame, i as isValCanvasPageMessage, e as isValCanvasStudioMessage, p as parseRoutePattern, w as withValCanvasParam } from '../../dist/getSitemapTree-a6cb37cb.esm.js';
 import { z } from 'zod';
 import { fromError } from 'zod-validation-error';
 import FlexSearch from 'flexsearch';
@@ -2456,6 +2456,66 @@ var Api = {
    * actually mounts. A file at a fixed commit cannot change, so the response is
    * immutable and the browser's own cache handles flipping between commits.
    */
+  /**
+   * One `.jsonValues()` entry's content, as it was at a commit.
+   *
+   * The history pane's counterpart to `/json`. A `.jsonValues()` record's
+   * source is only `{_type:"json"}` markers - the content is per entry, fetched
+   * on demand - so without this the commit pane rendered every entry as an
+   * empty field, which is a claim that the author left it blank.
+   *
+   * One entry per request, deliberately: the store fetches an entry when
+   * something reads inside it, so a batch would mean guessing which entries the
+   * pane is about to show. Authenticated for the same reasons as
+   * `/history/files` below.
+   */
+  "/history/json": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          path: onlyOneStringQueryParam,
+          key: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(400),
+        json: GenericError.and(z.object({
+          kind: z.string().optional()
+        }))
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError.and(z.object({
+          kind: z.string().optional()
+        }))
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          path: ModuleFilePath,
+          key: z.string(),
+          content: z.unknown()
+        })
+      })])
+    }
+  },
+  /**
+   * A binary file as it was at a commit.
+   *
+   * AUTHENTICATED, unlike `/files` below - and the difference is not an
+   * oversight in either direction. See the comment on `/files`: what makes it
+   * safe to leave open is that a `patch_id` is an unguessable UUID, and what
+   * makes leaving it open NECESSARY is that a draft image is fetched by the
+   * app's own backend during Next image optimisation, with no cookies.
+   *
+   * Neither holds here. A commit sha is published - `git log`, the GitHub UI,
+   * every PR - so it is not a secret to stand in for a credential. And nothing
+   * fetches these server-side: they are read by the Studio, in a browser that
+   * has the session cookie, for the history pane and for staging a restore.
+   * So this one asks.
+   */
   "/history/files": {
     GET: {
       req: {
@@ -2463,6 +2523,9 @@ var Api = {
           commit_sha: onlyOneStringQueryParam,
           path: onlyOneStringQueryParam,
           remote: onlyOneStringQueryParam.optional()
+        },
+        cookies: {
+          val_session: z.string().optional()
         }
       },
       res: z.union([unauthorizedResponse, notFoundResponse, z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.123.3",
+  "version": "0.125.0",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {
@@ -37,7 +37,7 @@
     "flexsearch": "^0.8.212",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.121.0"
+    "@valbuild/core": "0.125.0"
   },
   "files": [
     "CHANGELOG.md",