shelving 1.273.0 → 1.274.0

package/db/provider/ChangesDBProvider.d.ts

@@ -4,6 +4,7 @@ import type { Identifier, Item } from "../../util/item.js";
 import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
+import type { DBProvider } from "./DBProvider.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Structured log entry recording a single database write performed through a `ChangesDBProvider`.
@@ -50,4 +51,6 @@ export declare class ChangesDBProvider<I extends Identifier, T extends Data> ext
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     /** Log a `"delete"` change after writing. */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    cloneWith(source: DBProvider<I, T>): this;
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
 }

package/db/provider/ChangesDBProvider.js

@@ -53,4 +53,19 @@ export class ChangesDBProvider extends ThroughDBProvider {
         await super.deleteQuery(collection, query);
         this._changes.push({ action: "delete", collection: collection.name, query });
     }
+    // Override so that transaction copies get their own log.
+    cloneWith(source) {
+        const clone = super.cloneWith(source);
+        Object.defineProperty(clone, "_changes", { value: [], enumerable: false });
+        return clone;
+    }
+    // Override to log the transaction's writes after it commits — a failed transaction logs nothing.
+    // The merge must happen after `source.transact()` resolves: backends may retry the callback or fail the commit itself, and only the committed attempt's writes belong in the log.
+    async transact(callback) {
+        let transaction;
+        const result = await this.source.transact(provider => callback((transaction = this.cloneWith(provider))));
+        if (transaction)
+            this._changes.push(...transaction.changes);
+        return result;
+    }
 }

package/db/provider/DBProvider.d.ts

@@ -167,5 +167,22 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @see https://shelving.cc/db/DBProvider/requireFirst
      */
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    /**
+     * Run a callback as a single atomic transaction — every write made through the callback's provider is committed together, or not at all.
+     *
+     * - The callback receives a transaction-scoped `DBProvider`; reads and writes made through it belong to the transaction.
+     * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
+     * - If the callback throws, nothing is committed and the error is rethrown.
+     * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
+     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
+     *
+     * @param callback Function that performs the transaction's reads and writes through the provider it receives.
+     * @returns The value returned by the callback.
+     * @throws `UnsupportedError` if this provider does not support transactions.
+     * @example await provider.transact(async db => void (await db.updateItem(users, 123, { logins: { sum: 1 } })));
+     * @see https://shelving.cc/db/DBProvider/transact
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/DBProvider.js

@@ -1,4 +1,5 @@
 import { RequiredError } from "../../error/RequiredError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { countArray, getFirst } from "../../util/array.js";
 import { awaitDispose } from "../../util/dispose.js";
 /**
@@ -81,6 +82,29 @@ export class DBProvider {
             });
         return first;
     }
+    /**
+     * Run a callback as a single atomic transaction — every write made through the callback's provider is committed together, or not at all.
+     *
+     * - The callback receives a transaction-scoped `DBProvider`; reads and writes made through it belong to the transaction.
+     * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
+     * - If the callback throws, nothing is committed and the error is rethrown.
+     * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
+     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
+     *
+     * @param callback Function that performs the transaction's reads and writes through the provider it receives.
+     * @returns The value returned by the callback.
+     * @throws `UnsupportedError` if this provider does not support transactions.
+     * @example await provider.transact(async db => void (await db.updateItem(users, 123, { logins: { sum: 1 } })));
+     * @see https://shelving.cc/db/DBProvider/transact
+     */
+    transact(callback) {
+        throw new UnsupportedError(`${this.constructor.name} does not support transactions`, {
+            provider: this,
+            received: callback,
+            caller: this.transact,
+        });
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(

package/db/provider/DebugDBProvider.d.ts

@@ -3,6 +3,7 @@ import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItem
 import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
+import type { DBProvider } from "./DBProvider.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Database provider that logs every operation it performs to the console for debugging.
@@ -29,4 +30,6 @@ export declare class DebugDBProvider<I extends Identifier, T extends Data> exten
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    /** Adds TRANSACT logging around the base behaviour, which re-wraps so operations inside the transaction are logged too. */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
 }

package/db/provider/DebugDBProvider.js

@@ -153,4 +153,17 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /** Adds TRANSACT logging around the base behaviour, which re-wraps so operations inside the transaction are logged too. */
+    async transact(callback) {
+        try {
+            console.debug(`${ANSI_RIGHT} TRANSACT`);
+            const result = await super.transact(callback);
+            console.debug(`${ANSI_SUCCESS} TRANSACT`);
+            return result;
+        }
+        catch (reason) {
+            console.error(`${ANSI_FAILURE} TRANSACT`, reason);
+            throw reason;
+        }
+    }
 }

package/db/provider/ThroughDBProvider.d.ts

@@ -36,5 +36,8 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+    /** Clone this provider with different `source`. */
+    cloneWith(source: DBProvider<I, T>): this;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/ThroughDBProvider.js

@@ -62,6 +62,14 @@ export class ThroughDBProvider {
     requireFirst(collection, query) {
         return this.source.requireFirst(collection, query);
     }
+    // Run the transaction against the wrapped `source` provider, keeping this provider's behaviour inside the transaction.
+    transact(callback) {
+        return this.source.transact(transaction => callback(this.cloneWith(transaction)));
+    }
+    /** Clone this provider with different `source`. */
+    cloneWith(source) {
+        return Object.create(this, { source: { value: source, enumerable: true } });
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(this.source);

package/db/provider/ValidationDBProvider.d.ts

@@ -10,6 +10,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
  * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
  * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ * - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
  *
  * @see https://shelving.cc/db/ValidationDBProvider
  */

package/db/provider/ValidationDBProvider.js

@@ -8,6 +8,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
  * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
  * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ * - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
  *
  * @see https://shelving.cc/db/ValidationDBProvider
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.273.0",
+	"version": "1.274.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/test/TransactionTestDBProvider.d.ts

@@ -0,0 +1,15 @@
+import type { DBProvider } from "../db/provider/DBProvider.js";
+import { MemoryDBProvider } from "../db/provider/MemoryDBProvider.js";
+import type { Data } from "../util/data.js";
+import type { Identifier } from "../util/item.js";
+/**
+ * In-memory provider for testing wrapping providers' `transact()` — runs the callback directly against itself.
+ *
+ * - No atomicity or rollback: writes apply immediately and are kept even if the callback throws.
+ * - Use it as the `source` of a wrapping provider to test how the wrapper behaves inside transactions, not to test transaction semantics themselves.
+ *
+ * @see https://shelving.cc/test/TransactionTestDBProvider
+ */
+export declare class TransactionTestDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends MemoryDBProvider<I, T> {
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+}

package/test/TransactionTestDBProvider.js

@@ -0,0 +1,14 @@
+import { MemoryDBProvider } from "../db/provider/MemoryDBProvider.js";
+/**
+ * In-memory provider for testing wrapping providers' `transact()` — runs the callback directly against itself.
+ *
+ * - No atomicity or rollback: writes apply immediately and are kept even if the callback throws.
+ * - Use it as the `source` of a wrapping provider to test how the wrapper behaves inside transactions, not to test transaction semantics themselves.
+ *
+ * @see https://shelving.cc/test/TransactionTestDBProvider
+ */
+export class TransactionTestDBProvider extends MemoryDBProvider {
+    async transact(callback) {
+        return await callback(this);
+    }
+}

package/test/index.d.ts

@@ -1,6 +1,7 @@
 import { Collection } from "../db/collection/Collection.js";
 export * from "./basics.js";
 export * from "./people.js";
+export * from "./TransactionTestDBProvider.js";
 export * from "./util.js";
 export declare const BASICS_COLLECTION: Collection<"basics", string, {
     str: string;

package/test/index.js

@@ -4,6 +4,7 @@ import { BASIC_SCHEMA } from "./basics.js";
 import { PERSON_SCHEMA } from "./people.js";
 export * from "./basics.js";
 export * from "./people.js";
+export * from "./TransactionTestDBProvider.js";
 export * from "./util.js";
 export const BASICS_COLLECTION = new Collection("basics", STRING, BASIC_SCHEMA);
 export const PEOPLE_COLLECTION = new Collection("people", STRING, PERSON_SCHEMA);

package/ui/app/App.md

@@ -46,6 +46,8 @@ export function MyApp() {
 }
 ```
 
+**Setting a `root` URL on `<App>` is strongly recommended.** `root` is the base that site-absolute links and assets (`/favicon.png`, `/base.css`) resolve against, the `<base>` tag rendered by `<HTML>`, and the prefix `<Router>` strips when matching routes. When it's unset, merging a `url` into the meta context derives `root` from that URL's origin (e.g. `https://example.com/`) — a safe fallback for apps served from the domain root, but wrong for apps deployed under a sub-path, so set it explicitly whenever your app doesn't live at `/`.
+
 `<App>` accepts all `PossibleMeta` props (`app`, `root`, `url`, `title`, `language`, `tags`, etc.) and merges them into the context it provides to children. On mount it adds the theme class to `document.body`, which activates the CSS custom property tokens defined in `App.module.css`; on unmount it removes it.
 
 For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.

package/ui/misc/MetaContext.d.ts

@@ -28,6 +28,7 @@ export declare function requireMeta(meta?: PossibleMeta): Meta;
  */
 export interface MetaURL extends Meta {
     url: ImmutableURL;
+    root: ImmutableURL;
     /** The path of `url` relative to `meta.root` (i.e. the _site-root-relative_ path). */
     path: AbsolutePath;
     /** The `?query` params of `url` extracted as a flat set of parameters. */
@@ -38,9 +39,9 @@ export interface MetaURL extends Meta {
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
  * @param caller Function to attribute thrown `RequiredError`s to (defaults to `requireMetaURL`).
- * @returns A `Meta` object with a defined `url`, plus `path` and `params` properties combined in.
- * @throws RequiredError If the current meta has no `url`.
- * @throws RequiredError If the current meta `url` does not share an origin with the meta `root`.
+ * @returns A `Meta` object with a defined `url` and `root`, plus `path` and `params` properties combined in.
+ * @throws RequiredError If the current meta has no `url` or no `root`.
+ * @throws RequiredError If the current meta `url` and `root` do not share a root (different origin, or `url` outside `root`'s path).
  * @example const { path, params } = requireMetaURL();
  * @see https://shelving.cc/ui/requireMetaURL
  */

package/ui/misc/MetaContext.js

@@ -30,9 +30,9 @@ export function requireMeta(meta) {
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
  * @param caller Function to attribute thrown `RequiredError`s to (defaults to `requireMetaURL`).
- * @returns A `Meta` object with a defined `url`, plus `path` and `params` properties combined in.
- * @throws RequiredError If the current meta has no `url`.
- * @throws RequiredError If the current meta `url` does not share an origin with the meta `root`.
+ * @returns A `Meta` object with a defined `url` and `root`, plus `path` and `params` properties combined in.
+ * @throws RequiredError If the current meta has no `url` or no `root`.
+ * @throws RequiredError If the current meta `url` and `root` do not share a root (different origin, or `url` outside `root`'s path).
  * @example const { path, params } = requireMetaURL();
  * @see https://shelving.cc/ui/requireMetaURL
  */
@@ -40,9 +40,11 @@ export function requireMetaURL(meta, caller = requireMetaURL) {
     const { url, root, ...combined } = requireMeta(meta);
     if (!url)
         throw new RequiredError("Meta URL is required", { received: url, caller });
+    if (!root)
+        throw new RequiredError("Meta root is required", { received: root, caller });
     const path = matchURLPrefix(url, root, caller);
     if (!path)
-        throw new RequiredError("Meta URL and meta root must share an origin", { url, root, caller });
+        throw new RequiredError("Meta URL and meta root must share a root", { url, root, caller });
     const params = getURIParams(url, caller);
     return { ...combined, url, root, path, params };
 }

package/ui/misc/MetaContext.test.tsx

@@ -1,8 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { RequiredError } from "shelving/error";
 import { createMeta, MetaContext, requireMetaURL } from "shelving/ui";
+import { requireURL } from "shelving/util/url";
 
 /** Render `requireMetaURL().path` from inside a component so its `use(MetaContext)` call is valid. */
 function Probe(): ReactNode {
@@ -38,8 +38,28 @@ describe("requireMetaURL", () => {
 		expect(html).toBe("/enquiry/loan");
 	});
 
+	test("defaults root to the url's origin when root is unset", () => {
+		const html = renderToStaticMarkup(
+			<MetaContext value={createMeta({ url: "http://x.com/enquiry/loan" })}>
+				<Probe />
+			</MetaContext>,
+		);
+		expect(html).toBe("/enquiry/loan");
+	});
+
 	test("throws RequiredError when url is unset", () => {
-		expect(() => renderToStaticMarkup(<Probe />)).toThrow(RequiredError);
+		expect(() => renderToStaticMarkup(<Probe />)).toThrow("Meta URL is required");
+	});
+
+	test("throws RequiredError when root is unset and was not derived", () => {
+		// Bypass `createMeta()` deliberately — merged meta always derives a root, so this backup check only fires for hand-built meta.
+		expect(() =>
+			renderToStaticMarkup(
+				<MetaContext value={{ url: requireURL("http://x.com/foo") }}>
+					<Probe />
+				</MetaContext>,
+			),
+		).toThrow("Meta root is required");
 	});
 
 	test("throws RequiredError when url and root are on different origins", () => {
@@ -49,6 +69,16 @@ describe("requireMetaURL", () => {
 					<Probe />
 				</MetaContext>,
 			),
-		).toThrow(RequiredError);
+		).toThrow("Meta URL and meta root must share a root");
+	});
+
+	test("throws RequiredError when url is outside the root's path", () => {
+		expect(() =>
+			renderToStaticMarkup(
+				<MetaContext value={createMeta({ root: "http://x.com/app/", url: "http://x.com/other" })}>
+					<Probe />
+				</MetaContext>,
+			),
+		).toThrow("Meta URL and meta root must share a root");
 	});
 });

package/ui/misc/MetaContext.tsx

@@ -37,6 +37,7 @@ export function requireMeta(meta?: PossibleMeta): Meta {
  */
 export interface MetaURL extends Meta {
 	url: ImmutableURL;
+	root: ImmutableURL;
 	/** The path of `url` relative to `meta.root` (i.e. the _site-root-relative_ path). */
 	path: AbsolutePath;
 	/** The `?query` params of `url` extracted as a flat set of parameters. */
@@ -48,17 +49,18 @@ export interface MetaURL extends Meta {
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
  * @param caller Function to attribute thrown `RequiredError`s to (defaults to `requireMetaURL`).
- * @returns A `Meta` object with a defined `url`, plus `path` and `params` properties combined in.
- * @throws RequiredError If the current meta has no `url`.
- * @throws RequiredError If the current meta `url` does not share an origin with the meta `root`.
+ * @returns A `Meta` object with a defined `url` and `root`, plus `path` and `params` properties combined in.
+ * @throws RequiredError If the current meta has no `url` or no `root`.
+ * @throws RequiredError If the current meta `url` and `root` do not share a root (different origin, or `url` outside `root`'s path).
  * @example const { path, params } = requireMetaURL();
  * @see https://shelving.cc/ui/requireMetaURL
  */
 export function requireMetaURL(meta?: PossibleMeta, caller: AnyCaller = requireMetaURL): MetaURL {
 	const { url, root, ...combined } = requireMeta(meta);
 	if (!url) throw new RequiredError("Meta URL is required", { received: url, caller });
+	if (!root) throw new RequiredError("Meta root is required", { received: root, caller });
 	const path = matchURLPrefix(url, root, caller);
-	if (!path) throw new RequiredError("Meta URL and meta root must share an origin", { url, root, caller });
+	if (!path) throw new RequiredError("Meta URL and meta root must share a root", { url, root, caller });
 	const params = getURIParams(url, caller);
 	return { ...combined, url, root, path, params };
 }

package/ui/router/Navigation.d.ts

@@ -1,5 +1,5 @@
 import { type ReactElement } from "react";
-import type { PossibleMeta } from "../util/index.js";
+import { type PossibleMeta } from "../util/index.js";
 import type { OptionalChildProps } from "../util/props.js";
 /**
  * Props for `<Navigation>` — initial `Meta` (url/base) plus optional `children`.
@@ -13,7 +13,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
  * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
  * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
  * - Listens for `popstate` to sync the store with browser back/forward.
- * - Publishes the live URL via `<Meta url={…} params={…}>` so descendant `<Router>`s re-render on navigation.
+ * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
  *
  * Exactly one `<Navigation>` per app — nested routers share this single store.
  *

package/ui/router/Navigation.js

@@ -3,6 +3,7 @@ import { useEffect } from "react";
 import { useInstance } from "../../react/useInstance.js";
 import { useStore } from "../../react/useStore.js";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
+import { mergeMeta } from "../util/index.js";
 import { NavigationContext } from "./NavigationContext.js";
 import { NavigationStore } from "./NavigationStore.js";
 /**
@@ -10,7 +11,7 @@ import { NavigationStore } from "./NavigationStore.js";
  * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
  * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
  * - Listens for `popstate` to sync the store with browser back/forward.
- * - Publishes the live URL via `<Meta url={…} params={…}>` so descendant `<Router>`s re-render on navigation.
+ * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
  *
  * Exactly one `<Navigation>` per app — nested routers share this single store.
  *
@@ -20,8 +21,8 @@ import { NavigationStore } from "./NavigationStore.js";
  * @see https://shelving.cc/ui/Navigation
  */
 export function Navigation({ children, ...meta }) {
-    const { url, root, ...merged } = requireMeta(meta);
-    const nav = useInstance(NavigationStore, url, root);
+    const current = requireMeta(meta);
+    const nav = useInstance(NavigationStore, current.url, current.root);
     useStore(nav);
     useEffect(() => {
         if (typeof document === "undefined" || typeof window === "undefined")
@@ -47,5 +48,5 @@ export function Navigation({ children, ...meta }) {
             window.removeEventListener("popstate", onPopState);
         };
     }, [nav]);
-    return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: { url: nav.value, root, ...merged }, children: children }) }));
+    return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: mergeMeta(current, { url: nav.value }, Navigation), children: children }) }));
 }

package/ui/router/Navigation.md

@@ -6,7 +6,8 @@ The top-level navigation provider for a client-side app. It owns a single `Navig
 
 - Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to an anchor to opt out.
 - It listens for `popstate` so the store stays in sync with browser back/forward.
-- It initialises the store from the surrounding `<Meta>` url/base, so set those on an ancestor `<HTML>` / `<Page>`.
+- It initialises the store from the surrounding `<Meta>` url/base, so set those on an ancestor `<App>` / `<HTML>` / `<Page>`. In the browser the store falls back to `window.location.href` when no url is set.
+- The meta it publishes always has a `root` — when none is set anywhere, `root` defaults to the live URL's origin. Setting `root` explicitly on `<App>` / `<HTML>` is still strongly recommended, especially for apps served under a sub-path.
 - `<Router>` works with no `<Navigation>` at all (SSR, static rendering, tests) — `<Navigation>` is only what makes the URL *live* on the client.
 
 ## Usage

package/ui/router/Navigation.test.tsx

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { Navigation, requireMetaURL } from "shelving/ui";
+
+/** Render `requireMetaURL().path` from inside a component so its `use(MetaContext)` call is valid. */
+function Probe(): ReactNode {
+	return requireMetaURL().path;
+}
+
+describe("Navigation", () => {
+	test("publishes merged meta with a root derived from the url", () => {
+		const html = renderToStaticMarkup(
+			<Navigation url="http://x.com/a/b">
+				<Probe />
+			</Navigation>,
+		);
+		expect(html).toBe("/a/b");
+	});
+
+	test("resolves a relative url against an explicit root", () => {
+		const html = renderToStaticMarkup(
+			<Navigation root="http://x.com/app/" url="./sub">
+				<Probe />
+			</Navigation>,
+		);
+		expect(html).toBe("/sub");
+	});
+});

package/ui/router/Navigation.tsx

@@ -2,7 +2,7 @@ import { type ReactElement, useEffect } from "react";
 import { useInstance } from "../../react/useInstance.js";
 import { useStore } from "../../react/useStore.js";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
-import type { PossibleMeta } from "../util/index.js";
+import { mergeMeta, type PossibleMeta } from "../util/index.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { NavigationContext } from "./NavigationContext.js";
 import { NavigationStore } from "./NavigationStore.js";
@@ -19,7 +19,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
  * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
  * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
  * - Listens for `popstate` to sync the store with browser back/forward.
- * - Publishes the live URL via `<Meta url={…} params={…}>` so descendant `<Router>`s re-render on navigation.
+ * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
  *
  * Exactly one `<Navigation>` per app — nested routers share this single store.
  *
@@ -29,8 +29,8 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
  * @see https://shelving.cc/ui/Navigation
  */
 export function Navigation({ children, ...meta }: NavigationProps): ReactElement {
-	const { url, root, ...merged } = requireMeta(meta);
-	const nav = useInstance(NavigationStore, url, root);
+	const current = requireMeta(meta);
+	const nav = useInstance(NavigationStore, current.url, current.root);
 	useStore(nav);
 
 	useEffect(() => {
@@ -63,7 +63,7 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
 
 	return (
 		<NavigationContext value={nav}>
-			<MetaContext value={{ url: nav.value, root, ...merged }}>{children}</MetaContext>
+			<MetaContext value={mergeMeta(current, { url: nav.value }, Navigation)}>{children}</MetaContext>
 		</NavigationContext>
 	);
 }

package/ui/util/meta.d.ts

@@ -4,7 +4,7 @@ import type { AnyCaller } from "../../util/function.js";
 import { type PossibleLink } from "../../util/link.js";
 import type { Nullish } from "../../util/null.js";
 import { type ImmutableURI, type PossibleURI, type PossibleURIParams } from "../../util/uri.js";
-import { type ImmutableURL, type PossibleURL } from "../../util/url.js";
+import { ImmutableURL, type PossibleURL } from "../../util/url.js";
 /**
  * Set of named meta `<meta />` tags in `{ name: content }` format.
  *
@@ -75,7 +75,7 @@ export interface Meta {
  * @see https://shelving.cc/ui/PossibleMeta
  */
 export interface PossibleMeta extends Omit<Meta, "root" | "url" | "links" | "scripts" | "modules" | "stylesheets"> {
-    /** Base URL for the app — accepts a string or `URL`, resolved with `requireURL()`. */
+    /** Base URL for the app — accepts a string or `URL`, resolved with `requireURL()`. Defaults to the origin of `url` when unset. */
     readonly root?: PossibleURL | undefined;
     /**
      * New URL for the page.
@@ -116,6 +116,7 @@ export declare function joinTitles(...titles: (string | undefined)[]): string;
  *
  * - `title` is merged with `joinTitles()`.
  * - `url` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
+ * - `root` defaults to the origin of the resolved `url` (e.g. `https://x.com/`) when not set explicitly, so merged meta with a `url` always has a `root`.
  * - `stylesheets` and `links` hrefs newly set in `meta2` are absolutified against the merged `url`/`root`, so they stay correct no matter where they are later rendered.
  *
  * @param meta1 The existing fully-resolved `Meta` to merge into.

package/ui/util/meta.js

@@ -1,7 +1,7 @@
 import { getDictionaryItems } from "../../util/dictionary.js";
 import { requireLink } from "../../util/link.js";
 import { withURIParams } from "../../util/uri.js";
-import { requireURL } from "../../util/url.js";
+import { ImmutableURL, requireURL } from "../../util/url.js";
 /**
  * Turn a deconstructed `MetaCSP` into a `Content-Security-Policy` string.
  *
@@ -33,6 +33,7 @@ export function joinTitles(...titles) {
  *
  * - `title` is merged with `joinTitles()`.
  * - `url` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
+ * - `root` defaults to the origin of the resolved `url` (e.g. `https://x.com/`) when not set explicitly, so merged meta with a `url` always has a `root`.
  * - `stylesheets` and `links` hrefs newly set in `meta2` are absolutified against the merged `url`/`root`, so they stay correct no matter where they are later rendered.
  *
  * @param meta1 The existing fully-resolved `Meta` to merge into.
@@ -44,8 +45,10 @@ export function joinTitles(...titles) {
  */
 export function mergeMeta(meta1, meta2, caller = mergeMeta) {
     const title = joinTitles(meta2.title, meta1.title);
-    const root = mergeMetaURL(undefined, meta1.root, meta2.root, undefined, caller);
-    const url = mergeMetaURL(root, meta1.url, meta2.url, meta2.params, caller);
+    const explicitRoot = mergeMetaURL(undefined, meta1.root, meta2.root, undefined, caller);
+    const url = mergeMetaURL(explicitRoot, meta1.url, meta2.url, meta2.params, caller);
+    // A meta with a `url` must always have a `root` — only correct for apps served from the origin's `/`, so sub-path deployments must set `root` explicitly.
+    const root = explicitRoot ?? (url ? new ImmutableURL("/", url) : undefined);
     return {
         ...meta1,
         ...meta2,

package/ui/util/meta.test.ts

@@ -60,4 +60,21 @@ describe("mergeMeta", () => {
 		expect(meta2.links?.icon?.href).toBe("http://x.com/favicon.png");
 		expect(meta2.links?.canonical?.href).toBe("http://x.com/page");
 	});
+
+	test("defaults root to the origin of the url when root is unset", () => {
+		const meta = createMeta({ url: "http://x.com/sub/page" });
+		expect(meta.url?.href).toBe("http://x.com/sub/page");
+		expect(meta.root?.href).toBe("http://x.com/");
+	});
+
+	test("keeps an explicit root instead of defaulting from the url", () => {
+		const meta = createMeta({ root: "http://x.com/app/", url: "http://x.com/app/page" });
+		expect(meta.root?.href).toBe("http://x.com/app/");
+	});
+
+	test("leaves root unset when url is also unset", () => {
+		const meta = createMeta({ title: "Title" });
+		expect(meta.root).toBeUndefined();
+		expect(meta.url).toBeUndefined();
+	});
 });

package/ui/util/meta.ts

@@ -4,7 +4,7 @@ import type { AnyCaller } from "../../util/function.js";
 import { type PossibleLink, requireLink } from "../../util/link.js";
 import type { Nullish } from "../../util/null.js";
 import { type ImmutableURI, type PossibleURI, type PossibleURIParams, withURIParams } from "../../util/uri.js";
-import { type ImmutableURL, type PossibleURL, requireURL } from "../../util/url.js";
+import { ImmutableURL, type PossibleURL, requireURL } from "../../util/url.js";
 
 /**
  * Set of named meta `<meta />` tags in `{ name: content }` format.
@@ -85,7 +85,7 @@ export interface Meta {
  * @see https://shelving.cc/ui/PossibleMeta
  */
 export interface PossibleMeta extends Omit<Meta, "root" | "url" | "links" | "scripts" | "modules" | "stylesheets"> {
-	/** Base URL for the app — accepts a string or `URL`, resolved with `requireURL()`. */
+	/** Base URL for the app — accepts a string or `URL`, resolved with `requireURL()`. Defaults to the origin of `url` when unset. */
 	readonly root?: PossibleURL | undefined;
 
 	/**
@@ -139,6 +139,7 @@ export function joinTitles(...titles: (string | undefined)[]): string {
  *
  * - `title` is merged with `joinTitles()`.
  * - `url` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
+ * - `root` defaults to the origin of the resolved `url` (e.g. `https://x.com/`) when not set explicitly, so merged meta with a `url` always has a `root`.
  * - `stylesheets` and `links` hrefs newly set in `meta2` are absolutified against the merged `url`/`root`, so they stay correct no matter where they are later rendered.
  *
  * @param meta1 The existing fully-resolved `Meta` to merge into.
@@ -151,8 +152,11 @@ export function joinTitles(...titles: (string | undefined)[]): string {
 export function mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta {
 	const title = joinTitles(meta2.title, meta1.title);
 
-	const root = mergeMetaURL(undefined, meta1.root, meta2.root, undefined, caller);
-	const url = mergeMetaURL(root, meta1.url, meta2.url, meta2.params, caller);
+	const explicitRoot = mergeMetaURL(undefined, meta1.root, meta2.root, undefined, caller);
+	const url = mergeMetaURL(explicitRoot, meta1.url, meta2.url, meta2.params, caller);
+
+	// A meta with a `url` must always have a `root` — only correct for apps served from the origin's `/`, so sub-path deployments must set `root` explicitly.
+	const root = explicitRoot ?? (url ? new ImmutableURL("/", url) : undefined);
 
 	return {
 		...meta1,