shelving 1.272.0 → 1.273.1

package/db/cache/DBCache.d.ts

@@ -3,7 +3,7 @@ import type { Identifier, Item } from "../../util/item.js";
 import type { Query } from "../../util/query.js";
 import type { Collection } from "../collection/Collection.js";
 import type { DBProvider } from "../provider/DBProvider.js";
-import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
+import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
 import type { ItemStore } from "../store/ItemStore.js";
 import type { QueryStore } from "../store/QueryStore.js";
 import { CollectionCache } from "./CollectionCache.js";

package/db/cache/DBCache.js

@@ -2,6 +2,7 @@ import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { getSource } from "../../util/source.js";
 import { CacheDBProvider } from "../provider/CacheDBProvider.js";
+import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
 import { CollectionCache } from "./CollectionCache.js";
 /**
  * Cache of `CollectionCache` objects for multiple collections.
@@ -28,8 +29,8 @@ export class DBCache {
     memory;
     constructor(provider) {
         this.provider = provider;
-        // If the provider chain contains a `CacheDBProvider`, reuse its memory so we can seed stores synchronously.
-        this.memory = getSource(CacheDBProvider, provider)?.memory;
+        // If the provider is itself in-memory (e.g. `MemoryDBProvider` or `StorageDBProvider`), or the chain contains a `CacheDBProvider`, reuse its memory so we can seed stores synchronously.
+        this.memory = provider instanceof MemoryDBProvider ? provider : getSource(CacheDBProvider, provider)?.memory;
     }
     _get(collection) {
         return this._collections.get(collection);

package/db/index.d.ts

@@ -14,6 +14,7 @@ export * from "./provider/MockDBProvider.js";
 export * from "./provider/PostgreSQLProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
+export * from "./provider/StorageDBProvider.js";
 export * from "./provider/ThroughDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";

package/db/index.js

@@ -14,6 +14,7 @@ export * from "./provider/MockDBProvider.js";
 export * from "./provider/PostgreSQLProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
+export * from "./provider/StorageDBProvider.js";
 export * from "./provider/ThroughDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";

package/db/provider/MemoryDBProvider.d.ts

@@ -16,7 +16,9 @@ import { DBProvider } from "./DBProvider.js";
  */
 export declare class MemoryDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends DBProvider<I, T> {
     /** List of tables in `{ name: MemoryTable }` format. */
-    private _tables;
+    protected _tables: {
+        [K in string]?: MemoryTable<I, T>;
+    };
     /**
      * Get (or lazily create) the `MemoryTable` backing a collection.
      *
@@ -25,6 +27,15 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      * @see https://shelving.cc/db/MemoryDBProvider/getTable
      */
     getTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
+    /**
+     * Create a new `MemoryTable` for a collection (without registering it — use `getTable()` for that).
+     * - Override point for subclasses that back collections with a specialised table, e.g. `StorageDBProvider`.
+     *
+     * @param collection Collection to create a table for.
+     * @example provider.createTable(users) // MemoryTable
+     * @see https://shelving.cc/db/MemoryDBProvider/createTable
+     */
+    createTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
@@ -46,6 +57,7 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      * @see https://shelving.cc/db/MemoryDBProvider/setItems
      */
     setItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, items: Items<II, TT>): void;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
@@ -59,7 +71,7 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
  *
  * @see https://shelving.cc/db/MemoryTable
  */
-export declare class MemoryTable<I extends Identifier, T extends Data> {
+export declare class MemoryTable<I extends Identifier, T extends Data> implements AsyncDisposable {
     /** Actual data in this table. */
     protected readonly _data: Map<I, Item<I, T>>;
     /**
@@ -203,4 +215,5 @@ export declare class MemoryTable<I extends Identifier, T extends Data> {
     deleteQuery(query: Query<Item<I, T>>): void;
     setItems(items: Items<I, T>): void;
     setItemsSequence(sequence: AsyncIterable<Items<I, T>>): AsyncIterable<Items<I, T>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/MemoryDBProvider.js

@@ -1,6 +1,7 @@
 import { StringSchema } from "../../schema/StringSchema.js";
 import { DeferredSequence } from "../../sequence/DeferredSequence.js";
 import { requireArray } from "../../util/array.js";
+import { awaitDispose } from "../../util/dispose.js";
 import { isArrayEqual } from "../../util/equal.js";
 import { getItem } from "../../util/item.js";
 import { countItems } from "../../util/iterate.js";
@@ -28,7 +29,18 @@ export class MemoryDBProvider extends DBProvider {
      * @see https://shelving.cc/db/MemoryDBProvider/getTable
      */
     getTable(collection) {
-        return (this._tables[collection.name] ||= new MemoryTable(collection));
+        return (this._tables[collection.name] ||= this.createTable(collection));
+    }
+    /**
+     * Create a new `MemoryTable` for a collection (without registering it — use `getTable()` for that).
+     * - Override point for subclasses that back collections with a specialised table, e.g. `StorageDBProvider`.
+     *
+     * @param collection Collection to create a table for.
+     * @example provider.createTable(users) // MemoryTable
+     * @see https://shelving.cc/db/MemoryDBProvider/createTable
+     */
+    createTable(collection) {
+        return new MemoryTable(collection);
     }
     async getItem(collection, id) {
         return this.getTable(collection).getItem(id);
@@ -77,6 +89,11 @@ export class MemoryDBProvider extends DBProvider {
     setItems(collection, items) {
         this.getTable(collection).setItems(items);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(...Object.values(this._tables), // Dispose all tables.
+        super[Symbol.asyncDispose]());
+    }
 }
 /**
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
@@ -214,11 +231,7 @@ export class MemoryTable {
         const oldItem = this._data.get(id);
         if (!oldItem)
             return;
-        const nextItem = updateData(oldItem, updates);
-        if (this._data.get(id) !== nextItem) {
-            this._data.set(id, nextItem);
-            this.next.resolve();
-        }
+        this.setItem(id, updateData(oldItem, updates));
     }
     /**
      * Delete an item by its id.
@@ -287,16 +300,8 @@ export class MemoryTable {
      * @see https://shelving.cc/db/MemoryTable/setQuery
      */
     setQuery(query, data) {
-        let changed = false;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            const item = getItem(id, data);
-            if (this._data.get(id) !== item) {
-                this._data.set(id, item);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            this.setItem(id, data);
     }
     /**
      * Apply partial updates to every item matching a query.
@@ -307,41 +312,16 @@ export class MemoryTable {
      * @see https://shelving.cc/db/MemoryTable/updateQuery
      */
     updateQuery(query, updates) {
-        let changed = false;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            const oldItem = this._data.get(id);
-            if (!oldItem)
-                continue;
-            const nextItem = updateData(oldItem, updates);
-            if (this._data.get(id) !== nextItem) {
-                this._data.set(id, nextItem);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            this.updateItem(id, updates);
     }
     deleteQuery(query) {
-        let changed = false;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            if (this._data.has(id)) {
-                this._data.delete(id);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            this.deleteItem(id);
     }
     setItems(items) {
-        let changed = false;
-        for (const item of items) {
-            if (this._data.get(item.id) !== item) {
-                this._data.set(item.id, item);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const item of items)
+            this.setItem(item.id, item);
     }
     async *setItemsSequence(sequence) {
         for await (const items of sequence) {
@@ -349,4 +329,10 @@ export class MemoryTable {
             yield items;
         }
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(
+        // Empty by default.
+        );
+    }
 }

package/db/provider/StorageDBProvider.d.ts

@@ -0,0 +1,79 @@
+import type { Data } from "../../util/data.js";
+import type { Identifier, Item } from "../../util/item.js";
+import type { Collection } from "../collection/Collection.js";
+import { MemoryDBProvider, MemoryTable } from "./MemoryDBProvider.js";
+/**
+ * In-memory database provider that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface.
+ *
+ * - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and act as the cache inside `CacheDBProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
+ * - The storage is a required argument (there is no default), so server code that constructs this provider must reference `localStorage` / `sessionStorage` itself — surfacing the mistake at the callsite instead of deep inside this class.
+ * - Treat the persisted data as best-effort: quota is shared across the origin (typically ~5MB) and users can clear it at any time. Data read back from storage is unvalidated — wrap this provider in `ValidationDBProvider` if it may have been written by an older version of your app.
+ * - If the storage is unusable (writes blocked by browser settings, or private browsing with zero quota), the provider degrades to memory-only operation — check the `persistent` flag to warn users their changes won't be saved.
+ *
+ * @example
+ *  const provider = new StorageDBProvider(localStorage);
+ *  if (!provider.persistent) console.warn("Changes won't be saved on this device.");
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://shelving.cc/db/StorageDBProvider
+ */
+export declare class StorageDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends MemoryDBProvider<I, T> {
+    /**
+     * Prefix for every storage key written by this provider.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/prefix
+     */
+    readonly prefix: string;
+    /**
+     * Whether this provider is actually persisting to storage.
+     * - `false` when storage exists but is unusable (e.g. blocked by browser settings, or private browsing with zero quota) — the provider still works, but data only lives in memory and is lost when the page closes.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/persistent
+     */
+    readonly persistent: boolean;
+    /** Storage being persisted to, or `undefined` when operating memory-only. */
+    private readonly _storage;
+    /**
+     * @param storage `Storage` instance to persist to, e.g. `localStorage` or `sessionStorage` (required so environments without one, e.g. the server, fail at the callsite).
+     * @param prefix Prefix for every storage key written by this provider, so it can share an origin's storage with other code (defaults to `"shelving:"`).
+     */
+    constructor(storage: Storage, prefix?: string);
+    /** Back collections with a `StorageTable`, or a plain `MemoryTable` when operating memory-only. */
+    createTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
+}
+/**
+ * `MemoryTable` that persists its items to a `Storage` instance — self-contained, so it can also be used independently of `StorageDBProvider`.
+ *
+ * - Hydrates itself from storage on construction, then persists each write *before* applying it to memory, so a failed write (e.g. `QuotaExceededError` when the origin's quota is full) throws and leaves memory and storage consistent.
+ * - Items are stored as JSON under keys formatted as `{prefix}{collection}:{id}`, so values must be JSON-serializable. The id in the key is authoritative — an `id` stored inside the JSON is overridden.
+ * - Listens for `storage` events, so changes made in other tabs/windows update memory and notify realtime sequences. Dispose the table (or its provider) to remove the listener.
+ *
+ * @see https://shelving.cc/db/StorageTable
+ */
+export declare class StorageTable<I extends Identifier, T extends Data> extends MemoryTable<I, T> {
+    /** Prefix for every storage key belonging to this table, e.g. `"shelving:users:"`. */
+    private readonly _prefix;
+    /** Storage this table persists to. */
+    private readonly _storage;
+    /** Attached `storage` event listener (so it can be detached on dispose), or `undefined` if none was attached. */
+    private readonly _listener;
+    constructor(collection: Collection<string, I, T>, storage: Storage, prefix?: string);
+    /** Load every persisted item of this table's collection into memory (directly, skipping the persist-back in `setItem()`). */
+    private _hydrate;
+    /** Storage key for an item of this table. */
+    private _key;
+    /** Identifier encoded in a storage key of this table. */
+    private _decodeKey;
+    /** Parse a stored JSON value into an item with the given id, or `undefined` if it's malformed. */
+    private _parse;
+    /**
+     * Apply a `storage` event (a change made in another tab/window) to this table.
+     * - Reuses `setItem()` / `deleteItem()` — re-persisting the value already in storage is a no-op, and same-tab writes don't fire `storage` events, so this can't loop.
+     */
+    private _syncStorage;
+    /** Persist to storage first — a failure (e.g. `QuotaExceededError`) throws before memory changes, keeping the two consistent. */
+    setItem(id: I, data: Item<I, T> | T): void;
+    /** Remove from storage first, keeping storage and memory consistent. */
+    deleteItem(id: I): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/db/provider/StorageDBProvider.js

@@ -0,0 +1,163 @@
+import { UnsupportedError } from "../../error/UnsupportedError.js";
+import { StringSchema } from "../../schema/StringSchema.js";
+import { isData } from "../../util/data.js";
+import { awaitDispose } from "../../util/dispose.js";
+import { getItem } from "../../util/item.js";
+import { MemoryDBProvider, MemoryTable } from "./MemoryDBProvider.js";
+/**
+ * In-memory database provider that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface.
+ *
+ * - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and act as the cache inside `CacheDBProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
+ * - The storage is a required argument (there is no default), so server code that constructs this provider must reference `localStorage` / `sessionStorage` itself — surfacing the mistake at the callsite instead of deep inside this class.
+ * - Treat the persisted data as best-effort: quota is shared across the origin (typically ~5MB) and users can clear it at any time. Data read back from storage is unvalidated — wrap this provider in `ValidationDBProvider` if it may have been written by an older version of your app.
+ * - If the storage is unusable (writes blocked by browser settings, or private browsing with zero quota), the provider degrades to memory-only operation — check the `persistent` flag to warn users their changes won't be saved.
+ *
+ * @example
+ *  const provider = new StorageDBProvider(localStorage);
+ *  if (!provider.persistent) console.warn("Changes won't be saved on this device.");
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://shelving.cc/db/StorageDBProvider
+ */
+export class StorageDBProvider extends MemoryDBProvider {
+    /**
+     * Prefix for every storage key written by this provider.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/prefix
+     */
+    prefix;
+    /**
+     * Whether this provider is actually persisting to storage.
+     * - `false` when storage exists but is unusable (e.g. blocked by browser settings, or private browsing with zero quota) — the provider still works, but data only lives in memory and is lost when the page closes.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/persistent
+     */
+    persistent;
+    /** Storage being persisted to, or `undefined` when operating memory-only. */
+    _storage;
+    /**
+     * @param storage `Storage` instance to persist to, e.g. `localStorage` or `sessionStorage` (required so environments without one, e.g. the server, fail at the callsite).
+     * @param prefix Prefix for every storage key written by this provider, so it can share an origin's storage with other code (defaults to `"shelving:"`).
+     */
+    constructor(storage, prefix = "shelving:") {
+        super();
+        this.prefix = prefix;
+        if (!storage)
+            throw new UnsupportedError("StorageDBProvider requires a Storage, e.g. localStorage or sessionStorage", {
+                caller: StorageDBProvider,
+            });
+        // Probe with a write+remove: private browsing can expose a `Storage` whose every write throws.
+        try {
+            const probe = `${prefix}?`;
+            storage.setItem(probe, "?");
+            storage.removeItem(probe);
+            this.persistent = true;
+            this._storage = storage;
+        }
+        catch {
+            // Unusable storage — degrade to memory-only.
+            this.persistent = false;
+            this._storage = undefined;
+        }
+    }
+    /** Back collections with a `StorageTable`, or a plain `MemoryTable` when operating memory-only. */
+    createTable(collection) {
+        return this._storage ? new StorageTable(collection, this._storage, this.prefix) : super.createTable(collection);
+    }
+}
+/**
+ * `MemoryTable` that persists its items to a `Storage` instance — self-contained, so it can also be used independently of `StorageDBProvider`.
+ *
+ * - Hydrates itself from storage on construction, then persists each write *before* applying it to memory, so a failed write (e.g. `QuotaExceededError` when the origin's quota is full) throws and leaves memory and storage consistent.
+ * - Items are stored as JSON under keys formatted as `{prefix}{collection}:{id}`, so values must be JSON-serializable. The id in the key is authoritative — an `id` stored inside the JSON is overridden.
+ * - Listens for `storage` events, so changes made in other tabs/windows update memory and notify realtime sequences. Dispose the table (or its provider) to remove the listener.
+ *
+ * @see https://shelving.cc/db/StorageTable
+ */
+export class StorageTable extends MemoryTable {
+    /** Prefix for every storage key belonging to this table, e.g. `"shelving:users:"`. */
+    _prefix;
+    /** Storage this table persists to. */
+    _storage;
+    /** Attached `storage` event listener (so it can be detached on dispose), or `undefined` if none was attached. */
+    _listener;
+    constructor(collection, storage, prefix = "shelving:") {
+        super(collection);
+        this._storage = storage;
+        this._prefix = `${prefix}${collection.name}:`;
+        this._hydrate();
+        // Changes made in other tabs/windows arrive as `storage` events on the global scope.
+        if (typeof globalThis.addEventListener === "function") {
+            this._listener = event => this._syncStorage(event);
+            globalThis.addEventListener("storage", this._listener);
+        }
+    }
+    /** Load every persisted item of this table's collection into memory (directly, skipping the persist-back in `setItem()`). */
+    _hydrate() {
+        for (let i = 0; i < this._storage.length; i++) {
+            const key = this._storage.key(i);
+            if (key?.startsWith(this._prefix)) {
+                const id = this._decodeKey(key);
+                const item = this._parse(id, this._storage.getItem(key));
+                if (item)
+                    this._data.set(id, item);
+            }
+        }
+    }
+    /** Storage key for an item of this table. */
+    _key(id) {
+        return `${this._prefix}${id}`;
+    }
+    /** Identifier encoded in a storage key of this table. */
+    _decodeKey(key) {
+        const raw = key.slice(this._prefix.length);
+        return (this.collection.id instanceof StringSchema ? raw : Number(raw)); // `as I` needed: TypeScript can't narrow I from the schema check.
+    }
+    /** Parse a stored JSON value into an item with the given id, or `undefined` if it's malformed. */
+    _parse(id, value) {
+        if (value) {
+            try {
+                const data = JSON.parse(value);
+                if (isData(data))
+                    return getItem(id, data); // `as T` needed: stored values are unvalidated — wrap the provider in `ValidationDBProvider` to validate them.
+            }
+            catch {
+                // Malformed values are skipped, not deleted — they may belong to other code sharing the prefix.
+            }
+        }
+    }
+    /**
+     * Apply a `storage` event (a change made in another tab/window) to this table.
+     * - Reuses `setItem()` / `deleteItem()` — re-persisting the value already in storage is a no-op, and same-tab writes don't fire `storage` events, so this can't loop.
+     */
+    _syncStorage({ storageArea, key, newValue }) {
+        if (storageArea !== this._storage)
+            return;
+        if (key === null) {
+            this.deleteQuery({}); // A `null` key means the other tab called `storage.clear()`.
+        }
+        else if (key.startsWith(this._prefix)) {
+            const id = this._decodeKey(key);
+            const item = newValue !== null ? this._parse(id, newValue) : undefined;
+            item ? this.setItem(id, item) : this.deleteItem(id);
+        }
+    }
+    /** Persist to storage first — a failure (e.g. `QuotaExceededError`) throws before memory changes, keeping the two consistent. */
+    setItem(id, data) {
+        const item = getItem(id, data);
+        if (this._data.get(id) !== item)
+            this._storage.setItem(this._key(id), JSON.stringify(item));
+        super.setItem(id, item);
+    }
+    /** Remove from storage first, keeping storage and memory consistent. */
+    deleteItem(id) {
+        if (this._data.has(id))
+            this._storage.removeItem(this._key(id));
+        super.deleteItem(id);
+    }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(() => this._listener && globalThis.removeEventListener("storage", this._listener), // Stop listening for `storage` events.
+        super[Symbol.asyncDispose]());
+    }
+}

package/package.json

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

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,