@valbuild/next 0.125.0 → 0.127.0

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # @valbuild/next
 
+## 0.127.0
+
+### Patch Changes
+
+- [#665](https://github.com/valbuild/val/pull/665) [`7072e07`](https://github.com/valbuild/val/commit/7072e07623c953a09ac14388ae22dada0b431ce3) Thanks [@freekh](https://github.com/freekh)! - `.nullable()` no longer drops the field's `.validate(...)` functions.
+
+  `.nullable()` returns a copy of the schema, and most of the schema classes built
+  that copy with an empty list of custom validators — so a validator declared
+  before the `.nullable()` was silently thrown away:
+
+  ```ts
+  s.number()
+    .validate((n) => (n > 100 ? "Too big" : false))
+    .nullable(); // the validator never ran
+  ```
+
+  `array`, `object`, `discriminatedUnion`, `enum`, `number`, `boolean`, `literal`,
+  `keyOf`, `date`, `dateTime`, `code`, `color` and `richtext` were affected;
+  `string`, `record`, `route`, `file` and `image` already carried them over, which
+  is why the bug was easy to miss. Validators now survive `.nullable()` on every
+  schema, in either order.
+
+  A validator on a nullable schema is called with `null` when the value is unset,
+  rather than being skipped — the same thing the schemas that never dropped them
+  have always done. If yours was written before the `.nullable()`, its argument is
+  typed as non-null even though `null` can reach it, so guard for it.
+
+- Updated dependencies [[`7fa8699`](https://github.com/valbuild/val/commit/7fa869974bc895af992a7d5c18b76253636d7d65), [`600308d`](https://github.com/valbuild/val/commit/600308d0174990ad9f5c417147d160273489c65a), [`5b7fe05`](https://github.com/valbuild/val/commit/5b7fe05cec6365f9cd1de9ba31e65ed4a87edb63), [`88262ac`](https://github.com/valbuild/val/commit/88262ac8db068650a664981ef73556457d87741a), [`7072e07`](https://github.com/valbuild/val/commit/7072e07623c953a09ac14388ae22dada0b431ce3), [`29811c3`](https://github.com/valbuild/val/commit/29811c3f8c7e001a950e6f4833af6888e6a4efea), [`9983116`](https://github.com/valbuild/val/commit/99831164c5151aad7ca69de79e1d0d59878be251)]:
+  - @valbuild/core@0.127.0
+  - @valbuild/shared@0.127.0
+  - @valbuild/ui@0.127.0
+  - @valbuild/server@0.127.0
+  - @valbuild/react@0.127.0
+  - @valbuild/language-server@0.127.0
+  - @valbuild/mcp@0.127.0
+
+## 0.126.0
+
+### Patch 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.
+
+- [#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.
+
+- Updated dependencies [[`719ad6b`](https://github.com/valbuild/val/commit/719ad6b607bcf136d0dbde9e90bf4b8a843561a4), [`9830277`](https://github.com/valbuild/val/commit/9830277e9aaca8da3030f629c2656ec58da47e45), [`64bfd0a`](https://github.com/valbuild/val/commit/64bfd0a6c85832ea5169b53e47087f22e193df36), [`7782979`](https://github.com/valbuild/val/commit/7782979e9b52f2015a6e72dc981e630d4f8c78e2), [`5bfd630`](https://github.com/valbuild/val/commit/5bfd630b63dee2189e238f20fe72ecc5537160f7), [`ccbcda6`](https://github.com/valbuild/val/commit/ccbcda60b3e3c465071229ae1ba28ac735483e63), [`f2fe70d`](https://github.com/valbuild/val/commit/f2fe70dab2b65000dfaf289f09c70b4a8291467a), [`5c18c99`](https://github.com/valbuild/val/commit/5c18c99ecc84651f82123481fc042063db953833), [`755e1a3`](https://github.com/valbuild/val/commit/755e1a3953775cb8d2c2dce87d6810d3dc329640), [`c6b1ec8`](https://github.com/valbuild/val/commit/c6b1ec84f1883750a4cfe5f70470b177621e971f), [`656f680`](https://github.com/valbuild/val/commit/656f680043c640f678625a64e690389ab23a0a69), [`610a041`](https://github.com/valbuild/val/commit/610a0414b120b521f38a2eb1182b3778bf778b2b), [`171208a`](https://github.com/valbuild/val/commit/171208a20177e68ed5a8b1a6fdaabfe893a6aa5f)]:
+  - @valbuild/ui@0.126.0
+  - @valbuild/shared@0.126.0
+  - @valbuild/server@0.126.0
+  - @valbuild/core@0.126.0
+  - @valbuild/react@0.126.0
+  - @valbuild/language-server@0.126.0
+  - @valbuild/mcp@0.126.0
+
 ## 0.125.0
 
 ### Patch Changes

package/README.md

@@ -385,6 +385,16 @@ import { s } from "./val.config";
 s.string().nullable(); // <- Schema<string | null>
 ```
 
+`.nullable()` can go before or after `.validate(...)` — a validator declared on
+either side of it is kept, and runs on `null` too, so the validator decides for
+itself what an unset value means:
+
+```ts
+s.string()
+  .nullable()
+  .validate((val) => (val === null ? "Please fill this in" : false));
+```
+
 ## Read-only and hidden fields
 
 `.readonly()` renders a field disabled in the Val editor, and `.hidden()` leaves
@@ -571,7 +581,7 @@ const sectionsSchema = s.array(
 );
 ```
 
-A tagged union with no preview of its own previews as the VARIANT the value
+A discriminated union with no preview of its own previews as the VARIANT the value
 takes, so a page-builder list previews each block by its own block type.
 
 Your function is run on demand, for the rows actually on screen, so it is fine
@@ -909,20 +919,16 @@ const image = useVal(imageVal);
 return <img src={image.url} />;
 ```
 
-## Union
-
-The union schema can be used to create either "tagged unions" or a union of string literals.
+## Discriminated Union
 
-### Union Schema tagged unions
+A discriminated union is a union of objects which all have the same field (of the same type). This field determines (or "discriminates") which of the union's types a value is.
 
-A tagged union is a union of objects which all have the same field (of the same type). This field can be used to determine (or "discriminate") the exact type of one of the types of the union.
-
-It is useful when editors should be able to chose from a set of objects that are different.
+It is useful when editors should be able to choose from a set of objects that are different.
 
 Example: let us say you have a page that can be one of the following: blog (page) or product (page). In this case your schema could look like this:
 
 ```ts
-s.union(
+s.discriminatedUnion(
   "type", // the key of the "discriminator"
   s.object({
     type: s.literal("blogPage"), // <- each type must have a UNIQUE value
@@ -937,16 +943,23 @@ s.union(
 ); // <- Schema<{ type: "blogPage", author: string } | { type: "productPage", sku: number }>
 ```
 
-## Union Schema: union of string literals
+## Enum
 
-You can also use a union to create a union of string literals. This is useful if you want a type-safe way to describe a set of valid strings that can be chosen by an editor.
+Use `s.enum` for a fixed set of strings. It gives you a type-safe way to describe the valid values an editor can choose from, and it presents as a dropdown in Val Studio.
 
 ```ts
-s.union(
-  s.literal("one"),
-  s.literal("two"),
-  //...
-); // <- Schema<"one" | "two">
+s.enum("one", "two"); // <- Schema<"one" | "two">
+```
+
+### `s.union` is deprecated
+
+`s.union` did both of these jobs, deciding which one you meant from its first
+argument. It still works, and produces exactly the schemas above, but name the
+one you mean instead:
+
+```ts
+s.union(s.literal("one"), s.literal("two")); // -> s.enum("one", "two")
+s.union("type", pageA, pageB); // -> s.discriminatedUnion("type", pageA, pageB)
 ```
 
 ## KeyOf
@@ -1325,6 +1338,27 @@ s.string().validate((val) => {
 });
 ```
 
+`.validate(...)` and `.nullable()` can be written in either order: the validator
+is carried through the copy `.nullable()` makes. On a nullable schema the value
+reaching the validator can be `null`, and it is handed over rather than skipped —
+so a validator declared **before** the `.nullable()` has to guard for it, since
+its argument is still typed as non-null there:
+
+```ts
+s.string()
+  .validate((val) => (val !== null && val.length > 80 ? "Too long" : false))
+  .nullable();
+
+// Declared after, and the argument is typed `string | null`:
+s.string()
+  .nullable()
+  .validate((val) => (val !== null && val.length > 80 ? "Too long" : false));
+```
+
+Not every modifier is order-free, though: a record's `.jsonValues()` changes the
+source shape, so it must come **before** `.validate(...)` and `.preview(...)`,
+and throws with that message if it does not.
+
 ## Get in touch
 
 Join us on [discord](https://discord.gg/cZzqPvaX8k) to get help or give us feedback.

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

@@ -7,7 +7,7 @@ var routeFromVal = require('../../dist/routeFromVal-d53d5ffb.cjs.dev.js');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');
 var React = require('react');
-var ValOverlayContext = require('../../dist/ValOverlayContext-5bd7628b.cjs.dev.js');
+var ValOverlayContext = require('../../dist/ValOverlayContext-98d33d86.cjs.dev.js');
 require('../../dist/createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('../../dist/objectSpread2-58024783.cjs.dev.js');

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

@@ -7,7 +7,7 @@ var routeFromVal = require('../../dist/routeFromVal-e0995830.cjs.prod.js');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');
 var React = require('react');
-var ValOverlayContext = require('../../dist/ValOverlayContext-d690744f.cjs.prod.js');
+var ValOverlayContext = require('../../dist/ValOverlayContext-9c4ae06d.cjs.prod.js');
 require('../../dist/createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('../../dist/objectSpread2-13f847a9.cjs.prod.js');

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

@@ -3,7 +3,7 @@ import { g as getJsonEntryStegaRoot, _ as _typeof, a as isJsonValuesRecordSchema
 import { Internal } from '@valbuild/core';
 import { getModuleIds, stegaEncode } from '@valbuild/react/stega';
 import React from 'react';
-import { useValOverlayContext } from '../../dist/ValOverlayContext-e42a2e14.esm.js';
+import { useValOverlayContext } from '../../dist/ValOverlayContext-398baef3.esm.js';
 import '../../dist/createForOfIteratorHelper-5758a730.esm.js';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
 import '../../dist/objectSpread2-60d1bd93.esm.js';

package/dist/ValNextProvider-062a8dc9.cjs.dev.js

@@ -11,7 +11,7 @@ var ui = require('@valbuild/ui');
 var navigation = require('next/navigation');
 var Script = require('next/script');
 var React = require('react');
-var ValOverlayContext = require('./ValOverlayContext-5bd7628b.cjs.dev.js');
+var ValOverlayContext = require('./ValOverlayContext-98d33d86.cjs.dev.js');
 var stega = require('@valbuild/react/stega');
 var fallbackColors = require('./fallbackColors-080c1bbc.cjs.dev.js');
 var client = require('@valbuild/shared/client');

package/dist/ValNextProvider-3d2cd7e4.esm.js

@@ -7,7 +7,7 @@ import { VERSION, VAL_APP_PATH, VAL_OVERLAY_ID } from '@valbuild/ui';
 import { useRouter, usePathname } from 'next/navigation';
 import Script from 'next/script';
 import React, { useEffect } from 'react';
-import { ValExternalStore, ValOverlayProvider } from './ValOverlayContext-e42a2e14.esm.js';
+import { ValExternalStore, ValOverlayProvider } from './ValOverlayContext-398baef3.esm.js';
 import { SET_AUTO_TAG_JSX_ENABLED } from '@valbuild/react/stega';
 import { p as prefixStyles, u as useConfigStorageSave, f as floatDarkBg, d as floatLightBg, v as valPrefixedClass, c as cn } from './fallbackColors-149dfbc9.esm.js';
 import { VAL_THEME_SESSION_STORAGE_KEY, isValCanvasFrame } from '@valbuild/shared/client';

package/dist/ValNextProvider-da189afe.cjs.prod.js

@@ -11,7 +11,7 @@ var ui = require('@valbuild/ui');
 var navigation = require('next/navigation');
 var Script = require('next/script');
 var React = require('react');
-var ValOverlayContext = require('./ValOverlayContext-d690744f.cjs.prod.js');
+var ValOverlayContext = require('./ValOverlayContext-9c4ae06d.cjs.prod.js');
 var stega = require('@valbuild/react/stega');
 var fallbackColors = require('./fallbackColors-e1d73b36.cjs.prod.js');
 var client = require('@valbuild/shared/client');

package/dist/{ValOverlayContext-e42a2e14.esm.js → ValOverlayContext-398baef3.esm.js}

@@ -24,20 +24,22 @@ function _createClass(e, r, t) {
 
 var LOAD_TIMEOUT_MS = 10000;
 var ValExternalStore = /*#__PURE__*/function () {
-  // Path-keyed cache of every source seen via update(). The single source of
-  // truth: load state and snapshots are both derived from this, so data can be
-  // queried for any combination of paths even before a subscriber registers.
-
-  // Reference-stable per-subscriberId snapshot cache for useSyncExternalStore.
-  // Built lazily from loadedSources in get() and invalidated in update().
-
-  // One-shot listeners used solely by waitForLoad. Kept separate from the
-  // useSyncExternalStore listeners so waitForLoad never has to register (and
-  // leak) a subscriberId.
-
   function ValExternalStore() {
     var _this = this;
     _classCallCheck(this, ValExternalStore);
+    _defineProperty(this, "listeners", void 0);
+    _defineProperty(this, "loadPromises", void 0);
+    // Path-keyed cache of every source seen via update(). The single source of
+    // truth: load state and snapshots are both derived from this, so data can be
+    // queried for any combination of paths even before a subscriber registers.
+    _defineProperty(this, "loadedSources", void 0);
+    // Reference-stable per-subscriberId snapshot cache for useSyncExternalStore.
+    // Built lazily from loadedSources in get() and invalidated in update().
+    _defineProperty(this, "snapshots", void 0);
+    // One-shot listeners used solely by waitForLoad. Kept separate from the
+    // useSyncExternalStore listeners so waitForLoad never has to register (and
+    // leak) a subscriberId.
+    _defineProperty(this, "loadListeners", void 0);
     _defineProperty(this, "subscribe", function (paths) {
       return function (listener) {
         var subscriberId = createSubscriberId(paths);

package/dist/{ValOverlayContext-5bd7628b.cjs.dev.js → ValOverlayContext-98d33d86.cjs.dev.js}

@@ -32,20 +32,22 @@ function _createClass(e, r, t) {
 
 var LOAD_TIMEOUT_MS = 10000;
 var ValExternalStore = /*#__PURE__*/function () {
-  // Path-keyed cache of every source seen via update(). The single source of
-  // truth: load state and snapshots are both derived from this, so data can be
-  // queried for any combination of paths even before a subscriber registers.
-
-  // Reference-stable per-subscriberId snapshot cache for useSyncExternalStore.
-  // Built lazily from loadedSources in get() and invalidated in update().
-
-  // One-shot listeners used solely by waitForLoad. Kept separate from the
-  // useSyncExternalStore listeners so waitForLoad never has to register (and
-  // leak) a subscriberId.
-
   function ValExternalStore() {
     var _this = this;
     _classCallCheck(this, ValExternalStore);
+    defineProperty._defineProperty(this, "listeners", void 0);
+    defineProperty._defineProperty(this, "loadPromises", void 0);
+    // Path-keyed cache of every source seen via update(). The single source of
+    // truth: load state and snapshots are both derived from this, so data can be
+    // queried for any combination of paths even before a subscriber registers.
+    defineProperty._defineProperty(this, "loadedSources", void 0);
+    // Reference-stable per-subscriberId snapshot cache for useSyncExternalStore.
+    // Built lazily from loadedSources in get() and invalidated in update().
+    defineProperty._defineProperty(this, "snapshots", void 0);
+    // One-shot listeners used solely by waitForLoad. Kept separate from the
+    // useSyncExternalStore listeners so waitForLoad never has to register (and
+    // leak) a subscriberId.
+    defineProperty._defineProperty(this, "loadListeners", void 0);
     defineProperty._defineProperty(this, "subscribe", function (paths) {
       return function (listener) {
         var subscriberId = createSubscriberId(paths);

package/dist/ValOverlayContext-9c4ae06d.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./ValOverlayContext-9c4ae06d.cjs.prod.js");
+} else {
+  module.exports = require("./ValOverlayContext-9c4ae06d.cjs.dev.js");
+}

package/dist/{ValOverlayContext-d690744f.cjs.prod.js → ValOverlayContext-9c4ae06d.cjs.prod.js}

@@ -32,20 +32,22 @@ function _createClass(e, r, t) {
 
 var LOAD_TIMEOUT_MS = 10000;
 var ValExternalStore = /*#__PURE__*/function () {
-  // Path-keyed cache of every source seen via update(). The single source of
-  // truth: load state and snapshots are both derived from this, so data can be
-  // queried for any combination of paths even before a subscriber registers.
-
-  // Reference-stable per-subscriberId snapshot cache for useSyncExternalStore.
-  // Built lazily from loadedSources in get() and invalidated in update().
-
-  // One-shot listeners used solely by waitForLoad. Kept separate from the
-  // useSyncExternalStore listeners so waitForLoad never has to register (and
-  // leak) a subscriberId.
-
   function ValExternalStore() {
     var _this = this;
     _classCallCheck(this, ValExternalStore);
+    defineProperty._defineProperty(this, "listeners", void 0);
+    defineProperty._defineProperty(this, "loadPromises", void 0);
+    // Path-keyed cache of every source seen via update(). The single source of
+    // truth: load state and snapshots are both derived from this, so data can be
+    // queried for any combination of paths even before a subscriber registers.
+    defineProperty._defineProperty(this, "loadedSources", void 0);
+    // Reference-stable per-subscriberId snapshot cache for useSyncExternalStore.
+    // Built lazily from loadedSources in get() and invalidated in update().
+    defineProperty._defineProperty(this, "snapshots", void 0);
+    // One-shot listeners used solely by waitForLoad. Kept separate from the
+    // useSyncExternalStore listeners so waitForLoad never has to register (and
+    // leak) a subscriberId.
+    defineProperty._defineProperty(this, "loadListeners", void 0);
     defineProperty._defineProperty(this, "subscribe", function (paths) {
       return function (listener) {
         var subscriberId = createSubscriberId(paths);

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

@@ -26,6 +26,10 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
      * cache for every route it covers, for all visitors. It is NOT needed for
      * the `suspend` prop on ValProvider (which detects the cookie client-side)
      * — reserve it for advanced server-side conditionals.
+     *
+     * @example
+     * // In a Server Component, a Server Action or a Route Handler:
+     * const enabled = await isValEnabled();
      */
     isValEnabled: typeof isValEnabled;
     val: ValConstructor & {
@@ -40,10 +44,22 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
          *
          * This method is primarily intended for tooling and other advanced use cases
          * outside of the actual application.
+         *
+         * @example
+         * import pageVal from "./page.val";
+         * const page = val.unstable_getUnpatchedUnencodedVal(pageVal);
          */
         unstable_getUnpatchedUnencodedVal: typeof getUnpatchedUnencodedVal;
         /**
          * Convert any object that is encoded with Val stega encoding back to the original values
+         *
+         * Use it wherever an encoded string would break something: a `key`, a
+         * comparison, a URL, anything sent to an API.
+         *
+         * @example
+         * import pageVal from "./page.val";
+         * const page = useVal(pageVal);
+         * const slug = val.raw(page.slug);
          */
         raw: typeof raw;
         /**
@@ -52,12 +68,30 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
          * This is typically used to manually set the data-val-path attribute for visual editing on any element.
          *
          * @example
-         * const page = useVal(pageVal)
-         * <a href={page.url.href} {...val.attrs(page)}>
-         *   {page.url.label}
-         * </a>
+         * import pageVal from "./page.val";
+         * function PageLink() {
+         *   const page = useVal(pageVal);
+         *   return (
+         *     <a href={page.url.href} {...val.attrs(page)}>
+         *       {page.url.label}
+         *     </a>
+         *   );
+         * }
          */
         attrs: typeof attrs;
+        /**
+         * The Val paths encoded into a single stega encoded string, or `undefined`
+         * when there are none.
+         *
+         * `val.attrs` is what an element usually wants; this is the lower-level
+         * read, for when you need the paths themselves. Unstable: the shape of a
+         * path is not part of the public API yet.
+         *
+         * @example
+         * import pageVal from "./page.val";
+         * const page = useVal(pageVal);
+         * const paths = val.unstable_decodeValPathsOfString(page.title);
+         */
         unstable_decodeValPathsOfString: typeof decodeValPathsOfString;
     };
     /**
@@ -73,6 +107,21 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
      * });
      */
     nextAppRouter: ValRouter;
+    /**
+     * A router for pages that are NOT in this application: the keys of the record
+     * are whole URLs, not route paths of your site.
+     *
+     * It is what `s.route()` links to when the destination is somewhere else -
+     * a campaign site, a docs host, a social profile.
+     *
+     * @example
+     * const links = s.record(s.object({ title: s.string() }));
+     * export default c.define(
+     *   "/content/external.val.ts",
+     *   links.router(externalPageRouter),
+     *   { "https://val.build": { title: "Val" } },
+     * );
+     */
     externalPageRouter: ValRouter;
 };
 export {};

package/dist/valbuild-next.cjs.dev.js

@@ -12,7 +12,7 @@ var NextImage = require('next/image');
 var jsxRuntime = require('react/jsx-runtime');
 var ValApp = require('./ValApp-294e5b53.cjs.dev.js');
 var ValModulesClient = require('./ValModulesClient-4ecabf99.cjs.dev.js');
-var version = require('./version-4302babf.cjs.dev.js');
+var version = require('./version-15707a75.cjs.dev.js');
 var createForOfIteratorHelper = require('./createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('./defineProperty-f90345d7.cjs.dev.js');
 require('./unsupportedIterableToArray-c8ab77c9.cjs.dev.js');

package/dist/valbuild-next.cjs.prod.js

@@ -12,7 +12,7 @@ var NextImage = require('next/image');
 var jsxRuntime = require('react/jsx-runtime');
 var ValApp = require('./ValApp-ab8a96fd.cjs.prod.js');
 var ValModulesClient = require('./ValModulesClient-10c0721c.cjs.prod.js');
-var version = require('./version-eb9498d9.cjs.prod.js');
+var version = require('./version-9b3eb9b7.cjs.prod.js');
 var createForOfIteratorHelper = require('./createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('./defineProperty-8951f469.cjs.prod.js');
 require('./unsupportedIterableToArray-0d2087a2.cjs.prod.js');

package/dist/valbuild-next.esm.js

@@ -11,7 +11,7 @@ import NextImage from 'next/image';
 import { jsx } from 'react/jsx-runtime';
 export { ValApp } from './ValApp-3a70afe1.esm.js';
 export { ValModulesClient, useRegisterValModules } from './ValModulesClient-0dd601a1.esm.js';
-import { V as VERSION } from './version-8ab79315.esm.js';
+import { V as VERSION } from './version-dc02550b.esm.js';
 import { _ as _createForOfIteratorHelper } from './createForOfIteratorHelper-5758a730.esm.js';
 import './defineProperty-cca5affa.esm.js';
 import './unsupportedIterableToArray-5baabfdc.esm.js';

package/dist/{version-4302babf.cjs.dev.js → version-15707a75.cjs.dev.js}

@@ -14,7 +14,7 @@ var packageJson = {
 		"next",
 		"react"
 	],
-	version: "0.125.0",
+	version: "0.127.0",
 	scripts: {
 		typecheck: "tsc --noEmit",
 		test: "jest"

package/dist/{version-eb9498d9.cjs.prod.js → version-9b3eb9b7.cjs.prod.js}

@@ -14,7 +14,7 @@ var packageJson = {
 		"next",
 		"react"
 	],
-	version: "0.125.0",
+	version: "0.127.0",
 	scripts: {
 		typecheck: "tsc --noEmit",
 		test: "jest"

package/dist/{version-8ab79315.esm.js → version-dc02550b.esm.js}

@@ -12,7 +12,7 @@ var packageJson = {
 		"next",
 		"react"
 	],
-	version: "0.125.0",
+	version: "0.127.0",
 	scripts: {
 		typecheck: "tsc --noEmit",
 		test: "jest"

package/package.json

@@ -12,7 +12,7 @@
     "next",
     "react"
   ],
-  "version": "0.125.0",
+  "version": "0.127.0",
   "main": "dist/valbuild-next.cjs.js",
   "module": "dist/valbuild-next.esm.js",
   "exports": {
@@ -47,13 +47,13 @@
   "dependencies": {
     "client-only": "^0.0.1",
     "server-only": "^0.0.1",
-    "@valbuild/core": "0.125.0",
-    "@valbuild/mcp": "0.125.0",
-    "@valbuild/language-server": "0.125.0",
-    "@valbuild/react": "0.125.0",
-    "@valbuild/server": "0.125.0",
-    "@valbuild/shared": "0.125.0",
-    "@valbuild/ui": "0.125.0"
+    "@valbuild/core": "0.127.0",
+    "@valbuild/mcp": "0.127.0",
+    "@valbuild/react": "0.127.0",
+    "@valbuild/language-server": "0.127.0",
+    "@valbuild/server": "0.127.0",
+    "@valbuild/ui": "0.127.0",
+    "@valbuild/shared": "0.127.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.3",

package/rsc/dist/valbuild-next-rsc.cjs.dev.js

@@ -11,7 +11,7 @@ var stega = require('@valbuild/react/stega');
 var core = require('@valbuild/core');
 var internal = require('@valbuild/shared/internal');
 var server = require('@valbuild/server');
-var version = require('../../dist/version-4302babf.cjs.dev.js');
+var version = require('../../dist/version-15707a75.cjs.dev.js');
 require('../../dist/createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('../../dist/slicedToArray-44036a76.cjs.dev.js');

package/rsc/dist/valbuild-next-rsc.cjs.prod.js

@@ -11,7 +11,7 @@ var stega = require('@valbuild/react/stega');
 var core = require('@valbuild/core');
 var internal = require('@valbuild/shared/internal');
 var server = require('@valbuild/server');
-var version = require('../../dist/version-eb9498d9.cjs.prod.js');
+var version = require('../../dist/version-9b3eb9b7.cjs.prod.js');
 require('../../dist/createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('../../dist/slicedToArray-ce613de6.cjs.prod.js');

package/rsc/dist/valbuild-next-rsc.esm.js

@@ -7,7 +7,7 @@ import { SET_RSC, stegaEncode, SET_AUTO_TAG_JSX_ENABLED } from '@valbuild/react/
 import { Internal } from '@valbuild/core';
 import { VAL_SESSION_COOKIE } from '@valbuild/shared/internal';
 import { createValServer } from '@valbuild/server';
-import { V as VERSION } from '../../dist/version-8ab79315.esm.js';
+import { V as VERSION } from '../../dist/version-dc02550b.esm.js';
 import '../../dist/createForOfIteratorHelper-5758a730.esm.js';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
 import '../../dist/slicedToArray-aa291011.esm.js';

package/server/dist/valbuild-next-server.cjs.dev.js

@@ -9,7 +9,7 @@ var objectSpread2 = require('../../dist/objectSpread2-58024783.cjs.dev.js');
 var core = require('@valbuild/core');
 var server = require('@valbuild/server');
 var server$1 = require('next/server');
-var version = require('../../dist/version-4302babf.cjs.dev.js');
+var version = require('../../dist/version-15707a75.cjs.dev.js');
 var mcp = require('@valbuild/mcp');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('../../dist/defineProperty-f90345d7.cjs.dev.js');

package/server/dist/valbuild-next-server.cjs.prod.js

@@ -9,7 +9,7 @@ var objectSpread2 = require('../../dist/objectSpread2-13f847a9.cjs.prod.js');
 var core = require('@valbuild/core');
 var server = require('@valbuild/server');
 var server$1 = require('next/server');
-var version = require('../../dist/version-eb9498d9.cjs.prod.js');
+var version = require('../../dist/version-9b3eb9b7.cjs.prod.js');
 var mcp = require('@valbuild/mcp');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('../../dist/defineProperty-8951f469.cjs.prod.js');

package/server/dist/valbuild-next-server.esm.js

@@ -5,7 +5,7 @@ import { _ as _objectSpread2 } from '../../dist/objectSpread2-60d1bd93.esm.js';
 import { Internal } from '@valbuild/core';
 import { createValApiRouter, createValServer } from '@valbuild/server';
 import { NextResponse } from 'next/server';
-import { V as VERSION } from '../../dist/version-8ab79315.esm.js';
+import { V as VERSION } from '../../dist/version-dc02550b.esm.js';
 import { initValMcp as initValMcp$1 } from '@valbuild/mcp';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
 import '../../dist/defineProperty-cca5affa.esm.js';

package/dist/ValOverlayContext-d690744f.cjs.js

@@ -1,7 +0,0 @@
-'use strict';
-
-if (process.env.NODE_ENV === "production") {
-  module.exports = require("./ValOverlayContext-d690744f.cjs.prod.js");
-} else {
-  module.exports = require("./ValOverlayContext-d690744f.cjs.dev.js");
-}