@valbuild/tanstack 0.124.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Fredrik Ekholdt and Blank AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,380 @@
+<p align="center">
+  <p align="center">
+    <a href="https://admin.val.build">
+<svg width="100" height="100" viewBox="0 0 944 944" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="472" cy="472" r="472" fill="#1D1C28"/>
+<g filter="url(#filter0_d_14_601)">
+<path d="M181 348C181 345.791 182.791 344 185 344H320C322.209 344 324 345.791 324 348V602C324 604.209 322.209 606 320 606H185C182.791 606 181 604.209 181 602V348Z" fill="#38CD80"/>
+</g>
+<g filter="url(#filter1_i_14_601)">
+<circle cx="252" cy="550" r="24" fill="#1E1F2A"/>
+</g>
+<path d="M659.085 550.374H658.585H654.427C652.095 550.374 650.434 549.729 649.347 548.522C648.25 547.306 647.658 545.431 647.658 542.807V439.857C647.658 437.924 646.091 436.357 644.158 436.357H629.16C627.227 436.357 625.66 437.924 625.66 439.857V455.828C625.66 456.658 624.986 457.332 624.155 457.332C623.593 457.332 623.072 457.015 622.798 456.508C618.502 448.559 612.704 442.661 605.399 438.838C597.962 434.671 589.622 432.592 580.394 432.592C571.897 432.592 563.846 434.128 556.247 437.2C548.643 440.274 541.944 444.796 536.154 450.761L536.153 450.761C530.537 456.552 526.106 463.693 522.854 472.174C519.598 480.668 517.975 490.411 517.975 501.395V505.697C517.975 516.86 519.597 526.693 522.854 535.187C526.105 543.667 530.535 550.895 536.148 556.864L536.153 556.869L536.159 556.875C541.95 562.659 548.647 567.088 556.246 570.161L556.256 570.165C563.856 573.057 572.083 574.5 580.932 574.5C589.456 574.5 597.527 572.325 605.137 567.982C612.625 563.807 618.519 557.469 622.822 548.992C623.085 548.475 623.609 548.147 624.176 548.147H624.546C625.161 548.147 625.66 548.646 625.66 549.261C625.66 555.468 627.583 560.617 631.452 564.665L631.451 564.665L631.46 564.673C635.511 568.72 640.668 570.735 646.889 570.735H658.585H659.085H661.157H661.657H760C761.933 570.735 763.5 569.168 763.5 567.235V553.874C763.5 551.941 761.933 550.374 760 550.374H733.542C732.161 550.374 731.042 549.255 731.042 547.874V385C731.042 383.067 729.475 381.5 727.542 381.5H680.701C678.768 381.5 677.201 383.067 677.201 385V398.361C677.201 400.294 678.768 401.861 680.701 401.861H706.543C707.924 401.861 709.043 402.981 709.043 404.361V547.874C709.043 549.255 707.924 550.374 706.543 550.374H661.657H661.157H659.085ZM600.117 550.146L600.111 550.149C594.977 552.448 589.304 553.601 583.086 553.601C570.468 553.601 560.194 549.435 552.222 541.12C544.436 532.633 540.512 520.847 540.512 505.697V501.395C540.512 494.274 541.581 487.79 543.712 481.936L543.714 481.931C545.849 475.89 548.778 470.842 552.495 466.775C556.398 462.521 560.92 459.246 566.061 456.944C571.195 454.645 576.867 453.492 583.086 453.492C589.117 453.492 594.696 454.731 599.829 457.207L599.838 457.211L599.848 457.215C605.166 459.517 609.681 462.79 613.4 467.035L613.4 467.035L613.408 467.044C617.306 471.292 620.324 476.431 622.458 482.469L622.459 482.474C624.59 488.328 625.66 494.812 625.66 501.933V505.16C625.66 512.46 624.59 519.125 622.458 525.159C620.324 531.022 617.393 536.075 613.669 540.326C609.95 544.571 605.435 547.844 600.117 550.146ZM464.902 570.735C466.39 570.735 467.716 569.794 468.206 568.389L512.685 441.011C513.479 438.736 511.79 436.357 509.38 436.357H491.006C489.496 436.357 488.157 437.325 487.683 438.758L447.951 558.864C447.716 559.575 447.051 560.055 446.303 560.055C445.554 560.055 444.89 559.575 444.655 558.864L404.923 438.758C404.449 437.325 403.109 436.357 401.6 436.357H383.225C380.815 436.357 379.126 438.736 379.921 441.011L424.399 568.389C424.89 569.794 426.215 570.735 427.704 570.735H464.902Z" fill="white" stroke="white"/>
+<defs>
+<filter id="filter0_d_14_601" x="127.464" y="290.464" width="250.072" height="369.072" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset/>
+<feGaussianBlur stdDeviation="26.768"/>
+<feComposite in2="hardAlpha" operator="out"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0.219608 0 0 0 0 0.803922 0 0 0 0 0.501961 0 0 0 0.3 0"/>
+<feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_14_601"/>
+<feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_14_601" result="shape"/>
+</filter>
+<filter id="filter1_i_14_601" x="228" y="526" width="48" height="48" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset/>
+<feGaussianBlur stdDeviation="6"/>
+<feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0.219608 0 0 0 0 0.803922 0 0 0 0 0.501961 0 0 0 0.3 0"/>
+<feBlend mode="normal" in2="shape" result="effect1_innerShadow_14_601"/>
+</filter>
+</defs>
+</svg>
+    </a>
+    <br/>
+
+# @valbuild/tanstack
+
+Val for [TanStack Start](https://tanstack.com/start) (React).
+
+Content lives in `.val.ts` files in your repository — type-checked, refactorable,
+reviewable in a pull request — and non-developers edit it in Val Studio, which
+this package mounts at `/val`.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Wiring it up](#wiring-it-up)
+- [Reading content](#reading-content)
+- [Routes](#routes)
+- [Preview and draft mode](#preview-and-draft-mode)
+- [Images](#images)
+- [Coding agents (MCP)](#coding-agents-mcp)
+- [Differences from `@valbuild/next`](#differences-from-valbuildnext)
+- [Schema reference](#schema-reference)
+
+## Installation
+
+```sh
+npm install @valbuild/tanstack
+npm install --save-dev @valbuild/cli @valbuild/eslint-plugin
+```
+
+Requires TanStack Start ≥ 1.130 and React 19.
+
+**Tell the route generator that `*.val.ts` files are not routes.** A Val module
+for a route lives beside the route file, and the generator scans everything
+under `src/routes` — so without this it reads `posts.$postId.val.ts` as a route
+at `/posts/$postId/val` and warns on every run:
+
+```ts
+// vite.config.ts
+tanstackStart({
+  router: { routeFileIgnorePattern: "\\.val\\.[tj]sx?$" },
+});
+```
+
+```json
+// tsr.config.json — the same, for the standalone `tsr generate` CLI
+{ "routeFileIgnorePattern": "\\.val\\.[tj]sx?$" }
+```
+
+## Wiring it up
+
+### `val.config.ts`
+
+```ts
+import { initVal } from "@valbuild/tanstack";
+
+const { s, c, val, config, tanstackRouter, externalPageRouter } = initVal({
+  project: "yourorg/your-project", // omit while running locally
+});
+
+export type { t } from "@valbuild/tanstack";
+export { s, c, val, config, tanstackRouter, externalPageRouter };
+```
+
+### `val.modules.ts`
+
+```ts
+import { modules } from "@valbuild/tanstack";
+import { config } from "./val.config";
+
+export default modules(config, [
+  { def: () => import("./src/routes/index.val") },
+  { def: () => import("./src/content/authors.val") },
+]);
+```
+
+### `src/val/server.ts` — the API and the server-side readers
+
+```ts
+import { initValServer, initValContent } from "@valbuild/tanstack/server";
+import { config } from "../../val.config";
+import valModules from "../../val.modules";
+
+const { valApiHandler, draftMode } = initValServer(valModules, { ...config });
+
+export const {
+  fetchValStega: fetchVal,
+  fetchValRouteStega: fetchValRoute,
+  fetchValKeyStega: fetchValKey,
+  fetchValRouteUrl,
+} = initValContent(config, valModules, { draftMode });
+
+export { valApiHandler };
+```
+
+Build both from one `draftMode` object. The API is what turns preview on for a
+browser and the readers are what has to notice; two independently created
+defaults would each work and disagree.
+
+### `src/routes/api/val.$.ts` — mount the API
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+import { valApiHandler } from "../../val/server";
+
+export const Route = createFileRoute("/api/val/$")({
+  server: {
+    handlers: {
+      GET: ({ request }) => valApiHandler(request),
+      POST: ({ request }) => valApiHandler(request),
+      PUT: ({ request }) => valApiHandler(request),
+      PATCH: ({ request }) => valApiHandler(request),
+      DELETE: ({ request }) => valApiHandler(request),
+      HEAD: ({ request }) => valApiHandler(request),
+    },
+  },
+});
+```
+
+`/api/val/$`, not `/api/val`: every endpoint has a sub-path, so the splat is the
+whole surface.
+
+### `src/routes/val/` — Val Studio
+
+Three files, because the Studio navigates within itself (it pushes paths like
+`/val/~/...`, which have to resolve to the same page on a reload):
+
+```tsx
+// src/routes/val/route.tsx
+import { Outlet, createFileRoute } from "@tanstack/react-router";
+import { ValApp, ValModulesClient } from "@valbuild/tanstack";
+import { config } from "../../../val.config";
+import valModules from "../../../val.modules";
+
+export const Route = createFileRoute("/val")({
+  component: () => (
+    <ValApp config={config}>
+      <ValModulesClient modules={valModules} />
+      <Outlet />
+    </ValApp>
+  ),
+});
+```
+
+```tsx
+// src/routes/val/index.tsx  and  src/routes/val/$.tsx
+import { createFileRoute } from "@tanstack/react-router";
+export const Route = createFileRoute("/val/")({ component: () => null }); // and "/val/$"
+```
+
+### The site's layout — `ValProvider`
+
+Put the site's own chrome and `ValProvider` in a **pathless layout route**, not
+in `__root`. `__root` is the shell for every route including `/val`, and the
+Studio should not be rendered inside the site it is editing.
+
+```tsx
+// src/routes/_site.tsx
+import { Outlet, createFileRoute } from "@tanstack/react-router";
+import { Suspense } from "react";
+import { ValModulesClient, ValProvider } from "@valbuild/tanstack";
+import { config } from "../../val.config";
+import valModules from "../../val.modules";
+
+export const Route = createFileRoute("/_site")({
+  component: () => (
+    <ValProvider config={config} suspend>
+      <ValModulesClient modules={valModules} />
+      <Suspense fallback={null}>
+        <Outlet />
+      </Suspense>
+    </ValProvider>
+  ),
+});
+```
+
+A pathless layout adds no URL segment: `_site.index.tsx` is still `/`. Val
+modules named after those files follow the same rule, so
+`_site.posts.$postId.val.ts` holds `/posts/...` keys.
+
+**The `<Suspense>` boundary is required when you pass `suspend`.** With none
+between a suspending component and the root, React has nowhere to put a
+fallback and the tree stops updating — which looks like the Studio failing to
+load. TanStack Start provides no boundary of its own.
+
+### `src/val/client.ts` — the hooks
+
+```ts
+import { initValClient } from "@valbuild/tanstack/client";
+import { config } from "../../val.config";
+
+export const {
+  useValStega: useVal,
+  useValRouteStega: useValRoute,
+  useValRouteUrl,
+} = initValClient(config);
+```
+
+## Reading content
+
+**Prefer the hooks.** They work in both places a component runs: during SSR they
+resolve the published content, and in a browser with the Studio open they
+resolve what the editor currently holds — so an edit appears as it is typed,
+with no round trip and no loader.
+
+```tsx
+function Page() {
+  const page = useValRoute(pageVal, Route.useParams());
+  const authors = useVal(authorsVal);
+  if (page === null) throw notFound();
+  return <h1>{page.title}</h1>;
+}
+```
+
+**Read on the server when the content has to exist before the component does** —
+`head`/meta tags, a redirect decided by content, a `notFound()` that must happen
+during the request. Two things to know:
+
+1. It has to go through `createServerFn`. A route `loader` runs in the browser
+   too — that is what makes a client navigation work — so importing
+   `src/val/server.ts` straight into a loader pulls `@valbuild/server`, and
+   Node's `fs` with it, into the client bundle. `createServerFn` is compiled
+   away on the client and everything only its handler uses goes with it.
+2. Content that arrives through a loader on a first, server-rendered load is not
+   click-to-editable. The edit tags are attached as JSX is created, and Val only
+   starts attaching them once hydration has told it the Studio is open — by
+   which time the component has already rendered its loader data. A client-side
+   navigation to the same route tags it normally.
+
+```tsx
+const getDoc = createServerFn()
+  .validator((params: { slug: string }) => params)
+  .handler(async ({ data }) => ({ doc: await fetchValRoute(pageVal, data) }));
+
+export const Route = createFileRoute("/_site/docs/$slug")({
+  loader: async ({ params }) => {
+    const { doc } = await getDoc({ data: params });
+    if (!doc) throw notFound();
+    return { doc };
+  },
+  component: Doc,
+});
+```
+
+## Routes
+
+A Val module for a route **is named after the route file it sits beside**: the
+`.tsx` becomes `.val.ts`. Its keys are the URLs that route serves.
+
+| Route file                         | Val module                            | Keys look like       |
+| ---------------------------------- | ------------------------------------- | -------------------- |
+| `src/routes/index.tsx`             | `src/routes/index.val.ts`             | `/`                  |
+| `src/routes/about.tsx`             | `src/routes/about.val.ts`             | `/about`             |
+| `src/routes/posts.$postId.tsx`     | `src/routes/posts.$postId.val.ts`     | `/posts/hello-world` |
+| `src/routes/posts/$postId.tsx`     | `src/routes/posts/$postId.val.ts`     | the same route       |
+| `src/routes/docs.$.tsx` (splat)    | `src/routes/docs.$.val.ts`            | `/docs/a/b`          |
+| `src/routes/_site.posts.$id.tsx`   | `src/routes/_site.posts.$id.val.ts`   | `/posts/1`           |
+| `src/routes/(marketing)/about.tsx` | `src/routes/(marketing)/about.val.ts` | `/about`             |
+
+`.` and `/` both separate segments, `$param` is a parameter, `$` on its own is a
+splat, and `index`, `route`, `(groups)` and `_pathless` layouts contribute no
+URL segment — exactly TanStack Router's own rules.
+
+```ts
+// src/routes/posts.$postId.val.ts
+import { s, c, tanstackRouter } from "../../val.config";
+
+export default c.define(
+  "/src/routes/posts.$postId.val.ts",
+  s.router(tanstackRouter, s.object({ title: s.string() })),
+  { "/posts/hello-world": { title: "Hello world" } },
+);
+```
+
+Then, in the route's component, hand `useValRoute` the route's own params
+unchanged — including `_splat`, which is what TanStack calls a splat parameter
+and what Val expects:
+
+```tsx
+const post = useValRoute(pageVal, Route.useParams());
+```
+
+Val validates every key against the route's pattern, so a key that no URL of
+that route could produce is a content error rather than a page that silently
+never renders. Val Studio shows these modules as a sitemap under **Pages**, and
+an editor can add a page there — which creates the key.
+
+For links out of your site, `externalPageRouter` takes whole URLs instead.
+
+## Preview and draft mode
+
+Val's preview shows unpublished edits. TanStack Start has no `draftMode()` of
+its own, so this package brings a cookie (`val_draft_mode`, `valDraftMode()` in
+`@valbuild/tanstack/server`). It is a mode switch, not a credential: every draft
+read also carries Val's session cookie, which is a signed JWT the server
+verifies, so a forged draft cookie gets published content.
+
+`suspend` on `ValProvider` makes `useValStega` / `useValRouteStega` wait for
+draft data before rendering, so a page that exists **only** in an unpublished
+draft renders instead of 404ing. Visitors without the Val Enable cookie pay
+nothing for it. It needs React 19 and a `<Suspense>` boundary (see above).
+
+## Images
+
+`ValImage` is a plain `<img>` that keeps the edit tags where the Studio can see
+them, and carries the source's own `width`/`height` and its `hotspot` as
+`object-position`:
+
+```tsx
+import { ValImage } from "@valbuild/tanstack";
+
+<ValImage src={page.hero.image} style={{ maxWidth: "20rem" }} />;
+```
+
+Uploads land in `public/val` by default, which Vite serves at `/val/...`. That
+shares a prefix with the Studio route, and Vite's static handling wins, so both
+work — but if you would rather keep them apart, `s.image({ directory })` takes
+another location.
+
+## Coding agents (MCP)
+
+`initValMcp` from `@valbuild/tanstack/server` gives an MCP host Val's content
+tools — read schemas, look content up, validate it, edit it. It is the same
+implementation `@valbuild/next` uses; mount it on a server route with the MCP
+SDK of your choice. See [`@valbuild/mcp`](https://www.npmjs.com/package/@valbuild/mcp).
+
+## Differences from `@valbuild/next`
+
+| Next                                | TanStack Start                                     |
+| ----------------------------------- | -------------------------------------------------- |
+| `nextAppRouter`                     | `tanstackRouter`                                   |
+| `app/blogs/[blog]/page.val.ts`      | `src/routes/blogs.$blog.val.ts`                    |
+| `initValRsc` (`@valbuild/next/rsc`) | `initValContent` (`@valbuild/tanstack/server`)     |
+| `draftMode()` from `next/headers`   | `valDraftMode()` (a cookie this package owns)      |
+| `valNextAppRouter`                  | `valApiHandler` — a `Request` in, a `Response` out |
+| `ValImage` wraps `next/image`       | `ValImage` is an `<img>`                           |
+| `fetchVal` in a Server Component    | hooks in components; `createServerFn` for loaders  |
+
+## Schema reference
+
+The schema types — `s.string()`, `s.richtext()`, `s.image()`, `s.record()`,
+`s.union()`, `s.keyOf()`, `s.route()`, and the rest — are the same in every Val
+package and are documented in full at
+[val.build/docs](https://val.build/docs) and in
+[`@valbuild/next`'s README](https://github.com/valbuild/val/blob/main/packages/next/README.md#schema-types).

package/client/dist/valbuild-tanstack-client.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "../../dist/declarations/src/client/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsYnVpbGQtdGFuc3RhY2stY2xpZW50LmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vZGlzdC9kZWNsYXJhdGlvbnMvc3JjL2NsaWVudC9pbmRleC5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBIn0=

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

@@ -0,0 +1,288 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var routeFromVal = require('../../dist/routeFromVal-a9147ceb.cjs.dev.js');
+var core = require('@valbuild/core');
+var stega = require('@valbuild/react/stega');
+var React = require('react');
+var ValOverlayContext = require('../../dist/ValOverlayContext-d3bfacb1.cjs.dev.js');
+require('../../dist/createForOfIteratorHelper-e75681d7.cjs.dev.js');
+require('@valbuild/shared/client');
+require('@valbuild/core/patch');
+require('react/jsx-runtime');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+function useValStega(selector) {
+  var valOverlayContext = ValOverlayContext.useValOverlayContext();
+  var moduleIds = React__default["default"].useMemo(function () {
+    return stega.getModuleIds(selector);
+  }, [selector]);
+  var store = valOverlayContext.store;
+  var moduleMap = React__default["default"].useSyncExternalStore(store ? store.subscribe(moduleIds) : function () {
+    return function () {};
+  }, store ? store.getSnapshot(moduleIds) : function () {
+    return;
+  }, store ? store.getServerSnapshot(moduleIds) : function () {
+    return;
+  });
+  // Suspense gate. `suspend` is false during SSR and hydration (so the static
+  // committed source is rendered, matching the server HTML exactly) and is
+  // activated by ValProvider after hydration — inside a transition — when the
+  // `suspend` prop is set AND the Val Enable cookie is present (checked
+  // client-side; the server store is never populated). It never deactivates.
+  // The production path (no cookie) skips the call entirely. The
+  // `draftMode !== false` check is a release valve: with draft mode off the
+  // store never receives source updates, so waitForLoad could only ever
+  // resolve via its timeout — and would then re-suspend on every subsequent
+  // render since the resolved promise is evicted from the cache. draftMode is
+  // null until the first /draft/stat poll resolves; null -> true keeps
+  // suspending, -> false only unblocks, and false -> true happens only on an
+  // explicit draft-mode enable which already refreshes the route.
+  // React.use is allowed inside conditionals — it is not a hook.
+  /**
+   * Wait until draft mode is KNOWN, before anything else.
+   *
+   * `draftMode === null` means `/draft/stat` has not answered yet, and the
+   * `getModule` below treats it as off — so a render that slips through here
+   * while it is unknown resolves against committed source. For an ordinary field
+   * that is a flash of published content; for `useValRoute` on a route that
+   * exists only in an uncommitted patch it is `notFound()`, which no later
+   * answer can undo. That was the 404 on a page you had just created.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode === null && valOverlayContext.draftModeReady) {
+    React__default["default"].use(valOverlayContext.draftModeReady);
+  }
+  /**
+   * Then wait for the draft sources — but only while more might be coming.
+   *
+   * `draftSourcesSynced` is the editor saying it has sent everything it holds,
+   * and it only holds modules with patches: an unedited module has no draft, so
+   * nothing is ever sent for it. Without that signal this could not tell "not
+   * sent yet" from "nothing to send", and waited out `waitForLoad`'s ten second
+   * timeout once per unedited module the page reads — which is what left a newly
+   * created page sitting on its loading fallback.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && !valOverlayContext.draftSourcesSynced && store && !store.hasAllLoaded(moduleIds)) {
+    React__default["default"].use(store.waitForLoad(moduleIds));
+  }
+  return stega.stegaEncode(selector, {
+    disabled: !valOverlayContext.draftMode,
+    getModule: function getModule(moduleId) {
+      if (moduleMap && valOverlayContext.draftMode) {
+        return moduleMap[moduleId];
+      }
+    }
+  });
+}
+
+/**
+ * The module's source as the overlay currently sees it — i.e. WITH the editor's
+ * unpublished changes — or undefined when there is no draft view to be had
+ * (production, draft mode off, or the overlay has not pushed this module yet).
+ *
+ * This is what lets the single-entry readers show drafts. They otherwise resolve
+ * an entry through its local import thunk, which is the content that was bundled:
+ * correct in production, and stale the moment anyone edits in the Studio.
+ */
+function useDraftModuleSource(moduleFilePath) {
+  var valOverlayContext = ValOverlayContext.useValOverlayContext();
+  var store = valOverlayContext.store;
+  var moduleIds = React__default["default"].useMemo(function () {
+    return moduleFilePath ? [moduleFilePath] : [];
+  }, [moduleFilePath]);
+  var moduleMap = React__default["default"].useSyncExternalStore(store ? store.subscribe(moduleIds) : function () {
+    return function () {};
+  }, store ? store.getSnapshot(moduleIds) : function () {
+    return undefined;
+  }, store ? store.getServerSnapshot(moduleIds) : function () {
+    return undefined;
+  });
+  if (!valOverlayContext.draftMode || !moduleFilePath) {
+    return undefined;
+  }
+  return moduleMap === null || moduleMap === void 0 ? void 0 : moduleMap[moduleFilePath];
+}
+
+/**
+ * What the draft view says about one `.jsonValues()` entry.
+ *
+ * Mirrors the server-side rule in `fetchValKey`/`fetchValRoute`: a draft view
+ * that HAS an answer wins, including the answer "this entry is gone", and the
+ * bundled content is used only when there is no draft view.
+ */
+function draftJsonEntry(draftSource, key) {
+  if (draftSource === undefined || draftSource === null || routeFromVal._typeof(draftSource) !== "object" || Array.isArray(draftSource)) {
+    return {
+      status: "unavailable"
+    };
+  }
+  var entry = draftSource[key];
+  if (entry === undefined) {
+    // The module IS in the draft view and this key is not: it was deleted.
+    return {
+      status: "absent"
+    };
+  }
+  if (core.Internal.isJson(entry)) {
+    // An un-loaded marker: the Studio has not fetched this entry's content, so
+    // the draft view cannot answer. (The engine asks for entries that pending
+    // patches touch, so this resolves itself for anything actually edited.)
+    return {
+      status: "unavailable"
+    };
+  }
+  return {
+    status: "content",
+    content: entry
+  };
+}
+
+// The (loosened) content type a single `.jsonValues()` entry resolves to.
+
+// Module-level cache of in-flight/resolved entry loads, so `React.use` gets a
+// stable promise across renders (keyed by module path + entry key).
+var jsonEntryPromiseCache = new Map();
+
+/**
+ * Client counterpart to `fetchValKey`: resolves a SINGLE `.jsonValues()` entry
+ * by key, loading only that entry's backing `*.val.json` (one dynamic import).
+ * Suspends (via `React.use`) until the entry loads, so it must be rendered
+ * inside a `<Suspense>` boundary.
+ *
+ * In draft mode it renders the editor's unpublished content, taken from the
+ * overlay; in production — and whenever there is no draft view — it resolves the
+ * entry's lazy import thunk from the local module.
+ */
+function useValKeyStega(selector, key) {
+  var valOverlayContext = ValOverlayContext.useValOverlayContext();
+  var moduleFilePath = selector && core.Internal.getValPath(selector);
+  var draftSource = useDraftModuleSource(moduleFilePath || undefined);
+  var draft = draftJsonEntry(draftSource, key);
+  if (draft.status === "absent") {
+    // Deleted in the draft state. Falling back to the bundled entry here would
+    // render content the editor has just removed.
+    return undefined;
+  }
+  var content = draft.status === "content" ? draft.content : undefined;
+  if (content === undefined) {
+    content = readCommittedJsonEntry(selector, key);
+  }
+  return stega.stegaEncode(content, {
+    disabled: !valOverlayContext.draftMode,
+    root: routeFromVal.getJsonEntryStegaRoot(selector, key)
+  });
+}
+
+/**
+ * The entry's content as bundled: its lazy import thunk, resolved through
+ * `React.use` so the caller suspends until it lands.
+ *
+ * Deliberately not named `use*`: it is called conditionally, which is fine
+ * because `React.use` is not a hook, but a `use*` name would read like one.
+ */
+function readCommittedJsonEntry(selector, key) {
+  var _Internal$getValPath;
+  var source = selector && core.Internal.getSource(selector);
+  var marker = source && routeFromVal._typeof(source) === "object" ? source[key] : undefined;
+  if (!core.Internal.isJson(marker)) {
+    return undefined;
+  }
+  var thunk = core.Internal.getJsonImport(marker);
+  if (!thunk) {
+    return undefined;
+  }
+  var cacheKey = "".concat((_Internal$getValPath = core.Internal.getValPath(selector)) !== null && _Internal$getValPath !== void 0 ? _Internal$getValPath : "", " ").concat(key);
+  var promise = jsonEntryPromiseCache.get(cacheKey);
+  if (!promise) {
+    promise = thunk().then(function (mod) {
+      return mod["default"];
+    });
+    jsonEntryPromiseCache.set(cacheKey, promise);
+  }
+  return React__default["default"].use(promise);
+}
+function resolveParams(params) {
+  if (!params) {
+    return null;
+  }
+  if ("then" in params) {
+    // Defensive guard: peerDependencies declare React >=19, but if a consumer
+    // somehow ends up on React 18 with a promise params arg, surface a
+    // diagnosable error instead of a cryptic `TypeError: React.use is not a
+    // function`. Callers treat null as the error sentinel.
+    if (!("use" in React__default["default"])) {
+      console.error("Val: useValRoute received a Promise params argument but React.use is unavailable. Upgrade to React 19+ or pre-resolve the promise before passing it.");
+      return null;
+    }
+    return React__default["default"].use(params);
+  }
+  return params;
+}
+function useValRouteStega(selector, params) {
+  var valOverlayContext = ValOverlayContext.useValOverlayContext();
+  // Both called unconditionally to keep hook order stable. For a `.jsonValues()`
+  // router `val` is unused (we resolve a single entry below instead); for any
+  // other router `draftSource` is.
+  var val = useValStega(selector);
+  var draftSource = useDraftModuleSource(selector && core.Internal.getValPath(selector) || undefined);
+  var resolvedParams = resolveParams(params);
+  // Careful: null means there was an error - undefined means no params
+  if (resolvedParams === null) {
+    return null;
+  }
+  var path = selector && core.Internal.getValPath(selector);
+  var schema = selector && core.Internal.getSchema(selector);
+  // `.jsonValues()` router: map params → the entry key and load ONLY that
+  // entry's backing `*.val.json` (one dynamic import), like `useValKey`.
+  if (routeFromVal.isJsonValuesRecordSchema(schema)) {
+    var source = selector && core.Internal.getSource(selector);
+    var url = routeFromVal.getValRouteUrlFromVal(resolvedParams || {}, "useValRoute", path, schema, source);
+    if (!url) {
+      return null;
+    }
+    var draft = draftJsonEntry(draftSource, url);
+    if (draft.status === "absent") {
+      // The draft state says this route is gone — see useValKeyStega.
+      return null;
+    }
+    var content = draft.status === "content" ? draft.content : undefined;
+    if (content === undefined) {
+      content = readCommittedJsonEntry(selector, url);
+    }
+    if (content === undefined) {
+      return null;
+    }
+    return stega.stegaEncode(content, {
+      disabled: !valOverlayContext.draftMode,
+      root: routeFromVal.getJsonEntryStegaRoot(selector, url)
+    });
+  }
+  var route = routeFromVal.initValRouteFromVal(resolvedParams || {}, "useValRoute", path, schema, val);
+  return route;
+}
+function useValRouteUrl(selector, params) {
+  var val = useValStega(selector);
+  var resolvedParams = params === undefined ? undefined : resolveParams(params);
+  // Careful: null means there was an error - undefined means no params
+  if (resolvedParams === null) {
+    return null;
+  }
+  var route = routeFromVal.getValRouteUrlFromVal(resolvedParams || {}, "useValRouteUrl", selector && core.Internal.getValPath(selector), selector && core.Internal.getSchema(selector), val);
+  return route;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function initValClient(config) {
+  return {
+    useValStega: useValStega,
+    useValKeyStega: useValKeyStega,
+    useValRouteStega: useValRouteStega,
+    useValRouteUrl: useValRouteUrl
+  };
+}
+
+exports.initValClient = initValClient;