@dojo-ng/history 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @dojo-ng/history
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Navigation history for single-page apps: real paths with `pushState`, Back and Forward that skip
+pages the user only skimmed, and hooks for tracking. It publishes the location on a
+[`@dojo-ng/pubsub`](https://www.npmjs.com/package/@dojo-ng/pubsub) bus. Your app decides what to show.
+
+Part of the [Dojo NG framework](https://foss.heptapod.net/dojo-ng/framework) packages: plain ESM
+and no Lit. BSD-3-Clause.
+
+## Install
+
+```bash
+npm install @dojo-ng/history @dojo-ng/pubsub
+```
+
+## Usage
+
+```js
+import { createPubSub } from "@dojo-ng/pubsub";
+import { installHistory, match } from "@dojo-ng/history";
+
+const bus = createPubSub();
+const history = installHistory(bus);
+
+// Follow the location. The current one arrives at once, so this also covers a reload.
+history.subscribe((location) => {
+  const order = match("/orders/:id", location.path);
+  if (order) showOrder(order.id);
+});
+
+history.go("/orders/7");   // pushes /orders/7 and publishes the new location
+history.back();
+```
+
+Call `installHistory` once, at startup. A second call logs a warning and returns the first
+instance, because there is one history stack.
+
+## Real paths need a server fallback
+
+Every navigation is a real URL. A reload, a pasted link, or a bookmark asks the server for that
+path, so the server must answer every route your app uses with the app itself. Without that, a
+reload on `/orders/7` is a 404. The app must also be able to render a view from the path alone.
+The [playground](playground/server.mjs) has a ten-line example.
+
+## The bus
+
+| Topic | Payload | Meaning |
+|---|---|---|
+| `nav:go` | `{ path, state?, trail?, replace? }` | Navigate. Anything can publish this. `history.go(path, state)` is a shortcut. |
+| `nav:location` | `{ path, state, index, committed, source, trail? }` | The location changed. |
+
+- `path` is the app path: no `base`, but it keeps any `?query` and `#hash` you gave to `go`.
+- `source` is `"go"` (a `nav:go`), `"pop"` (Back or Forward), or `"load"` (the page opened).
+- `index` is the entry's position in the stack. The entry the app landed on is 0.
+- `committed` is `false` while the entry is provisional (see Dwell). When it commits,
+  `nav:location` is published again with `committed: true`.
+- The bus keeps the last value, so a view that subscribes late still gets the current location.
+
+Only a `nav:go` writes to the browser's history. A `popstate` publishes `nav:location` and does
+nothing else, so Back never adds an entry.
+
+## The history object
+
+`installHistory(bus, options)` returns:
+
+- `go(path, state?, { replace?, trail? }?)`, `back()`, `forward()`
+- `subscribe(fn)` returns an unsubscribe function
+- `current`: the latest `nav:location` payload, or `undefined` before the first one
+- `canGoBack`, `canGoForward`: properties. The browser does not say whether Back or Forward has
+  somewhere to go, so each entry carries a private `{ id, index }` in `history.state`, and the
+  highest index is kept in `sessionStorage`. Without `sessionStorage`, `canGoForward` is `false`.
+- `href(path)`: `base` plus `path`, for a link's `href`
+- `annotate({ state?, trail? })`: replace those fields on the current entry (with `replaceState`)
+  and publish the location again. It sets whichever of the two you pass; it does not merge inside `state`.
+- `commit()`: commit the current entry now
+- `destroy()`: remove the listeners and unregister. For tests.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `base` | `""` | A path prefix such as `/acme`. Added to every URL written and stripped from every path read. |
+| `dwellMs` | `3000` | Visible milliseconds before an entry commits. `0` gives plain browser behavior. |
+| `onCommit` | none | Called once for each entry that commits. See Hooks. |
+| `resolve` | none | Rebuilds the state of a landing entry that has none. See Hooks. |
+| `window` | `globalThis.window` | For tests: any object shaped like the parts of `window` this uses. |
+
+## Dwell: skimmed pages stay off the stack
+
+A browser cannot remove an entry from history, but it can replace the current one. So a new entry
+is provisional until the user has stayed on it for `dwellMs`. If `go` runs while the current entry
+is provisional, the new path replaces it instead of pushing. Open A, read it, then click through B, C
+and D quickly and settle on E: the stack holds A and E, and Back from E goes to A.
+
+- The entry the app lands on is committed at once.
+- An entry reached by Back or Forward is committed. It already earned its place.
+- `commit()` commits early, for when the user clearly engaged (typing in a form, for example).
+- Only visible time counts. The timer pauses while the tab is hidden and resumes with the time that was left.
+- `go(path, state, { replace: true })` on a provisional entry replaces it and restarts the timer. On
+  an entry that has already committed, the replacement commits too and keeps its place.
+- `dwellMs: 0` pushes every entry, as a browser does.
+
+## Hooks
+
+`onCommit({ path, state, trail? })` runs once per entry that commits. It never runs for a skimmed
+entry or for the landing entry. This is the place to send a location to a server. This package
+ships no server code.
+
+`resolve(path)` is async. When the page opens on an entry with no state of ours (a new tab, a
+pasted link, a bookmark), it is awaited before the first `nav:location` (`source: "load"`), and its
+result becomes the entry's state. If it rejects, the error is logged and the bare path is
+published. A reload in the same tab keeps its state, so `resolve` is not called. If the app
+navigates before `resolve` settles, the late result is dropped.
+
+## match
+
+```js
+import { match } from "@dojo-ng/history";
+
+match("/orders/:id", "/orders/42");          // { id: "42" }
+match("/files/*", "/files/a/b");             // { "*": "a/b" }
+match("/orders/:id", "/orders");             // null
+```
+
+Static segments, `:name` params (decoded with `decodeURIComponent`), and a trailing `*` that takes
+the rest, zero or more segments. A trailing slash on either side is ignored. Pass a pathname: a
+`?query` or `#hash` is not stripped. Navigation never calls `match`; mapping a path to a view is the app's job.
+
+## For components: the handle subpath
+
+```js
+import { getHistory, whenHistory } from "@dojo-ng/history/handle";
+```
+
+`getHistory()` returns the installed instance or `undefined`. `whenHistory()` returns a promise
+that resolves at install. The subpath also exports the types and imports nothing, so a component
+that only reads the location does not pull in the rest of the package. The instance is stored on
+`globalThis[Symbol.for("dojo-ng.history")]`, so two copies of the package in one bundle share one.
+
+## The dj-navigate event
+
+A component that has a path does not need the instance. It dispatches a bubbling, composed
+`dj-navigate` event, and `installHistory` listens for it on `document`:
+
+```js
+this.dispatchEvent(new CustomEvent("dj-navigate", {
+  detail: { path: "/orders/7", state: undefined, trail: [{ path: "/orders", label: "Orders" }, { path: "/orders/7", label: "Order 7" }], replace: false },
+  bubbles: true,
+  composed: true,
+}));
+```
+
+It becomes a `nav:go`. `trail` is stored in the entry's state, so it comes back on Back, Forward,
+and a same-tab reload. Other keys in `detail` (such as `label`) are ignored here.
+
+## Another router on the page
+
+If something else seems to be writing history, one `console.warn` per kind of signal is logged and
+the layer carries on: `history.pushState` or `replaceState` is not native; Back or Forward lands
+on an entry this layer did not create; or the location changed without a `nav:go`. This package
+never patches `pushState`.
+
+## Playground
+
+```bash
+cd packages/history
+npm run build
+npm run playground     # http://localhost:8902/
+```

package/dist/handle.d.ts

@@ -0,0 +1,75 @@
+/** One step of the path from the root to a node, carried in navigation state. */
+export interface TrailEntry {
+    path: string;
+    label: string;
+}
+/** Where a `NavLocation` came from: a `nav:go`, a Back/Forward (`pop`), or the install itself. */
+export type NavSource = "go" | "pop" | "load";
+/** The payload of every `nav:location` publish. `path` never includes the `base` option. */
+export interface NavLocation {
+    path: string;
+    /** The state passed to `go`, or the result of `resolve`. `undefined` when there is none. */
+    state: unknown;
+    /** Position of this entry in the stack, 0 for the entry the app landed on. */
+    index: number;
+    /** False while the entry is provisional (see `dwellMs`). */
+    committed: boolean;
+    source: NavSource;
+    /** Root-to-node trail, when whoever navigated supplied one. */
+    trail?: TrailEntry[];
+}
+/** What `annotate` can change on the current entry. */
+export interface NavAnnotation {
+    state?: unknown;
+    trail?: TrailEntry[];
+}
+/** The payload of `nav:go`, and of the `dj-navigate` event detail (which may carry extra keys). */
+export interface NavGo {
+    path: string;
+    state?: unknown;
+    trail?: TrailEntry[];
+    replace?: boolean;
+}
+/** The `detail` of the `dj-navigate` event a component dispatches. `label` is for whoever listens; history ignores it. */
+export interface NavigateDetail extends NavGo {
+    label?: string;
+}
+export interface GoOptions {
+    /** Replace the current entry instead of pushing a new one. */
+    replace?: boolean;
+    trail?: TrailEntry[];
+}
+/** What is passed to `onCommit` when an entry commits. */
+export interface CommitEntry {
+    path: string;
+    state: unknown;
+    trail?: TrailEntry[];
+}
+export interface HistoryInstance {
+    /** Publish `nav:go`. The only way anything here writes to the browser's history. */
+    go(path: string, state?: unknown, options?: GoOptions): void;
+    back(): void;
+    forward(): void;
+    /** Commit the current entry now, without waiting out the dwell time. */
+    commit(): void;
+    /** Follow the location. The current one is delivered at once. Returns an unsubscribe function. */
+    subscribe(fn: (location: NavLocation) => void): () => void;
+    /** The current location, or `undefined` until the first one is published. */
+    readonly current: NavLocation | undefined;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+    /** The URL for an app path: `base` plus `path`. */
+    href(path: string): string;
+    /** Merge `state` and/or `trail` into the current entry, then publish the location again. */
+    annotate(partial: NavAnnotation): void;
+    /** Remove listeners and unregister. For tests. */
+    destroy(): void;
+}
+/** The installed instance, or `undefined` when `installHistory` has not run. */
+export declare function getHistory(): HistoryInstance | undefined;
+/** Resolves with the instance: at once if installed, otherwise when `installHistory` runs. */
+export declare function whenHistory(): Promise<HistoryInstance>;
+/** @internal Called by `installHistory`. Not part of the public API. */
+export declare function registerHistory(instance: HistoryInstance): void;
+/** @internal Called by `destroy()`. Only removes the registration if it is still `instance`. */
+export declare function unregisterHistory(instance: HistoryInstance): void;

package/dist/handle.js

@@ -0,0 +1,44 @@
+// The subpath components import: `@dojo-ng/history/handle`. It holds the types, the lookup of the
+// installed instance, and the promise that resolves at install. It imports nothing (no pub/sub, no
+// install code), so a component that only reads the location pulls in a few lines, not the package.
+//
+// The instance lives on `globalThis[Symbol.for("dojo-ng.history")]` (that is `window` in a
+// browser), so two copies of the package in one bundle agree on one instance (decision D3). The
+// callbacks waiting for an install live under a second well-known symbol for the same reason.
+const INSTANCE_KEY = Symbol.for("dojo-ng.history");
+const WAITERS_KEY = Symbol.for("dojo-ng.history.waiters");
+function slot() {
+    return globalThis;
+}
+/** The installed instance, or `undefined` when `installHistory` has not run. */
+export function getHistory() {
+    return slot()[INSTANCE_KEY];
+}
+/** Resolves with the instance: at once if installed, otherwise when `installHistory` runs. */
+export function whenHistory() {
+    const installed = getHistory();
+    if (installed)
+        return Promise.resolve(installed);
+    return new Promise((resolve) => {
+        const s = slot();
+        const waiters = s[WAITERS_KEY] ?? [];
+        waiters.push(resolve);
+        s[WAITERS_KEY] = waiters;
+    });
+}
+/** @internal Called by `installHistory`. Not part of the public API. */
+export function registerHistory(instance) {
+    const s = slot();
+    s[INSTANCE_KEY] = instance;
+    const waiters = s[WAITERS_KEY];
+    s[WAITERS_KEY] = undefined;
+    if (waiters)
+        for (const resolve of waiters)
+            resolve(instance);
+}
+/** @internal Called by `destroy()`. Only removes the registration if it is still `instance`. */
+export function unregisterHistory(instance) {
+    const s = slot();
+    if (s[INSTANCE_KEY] === instance)
+        s[INSTANCE_KEY] = undefined;
+}

package/dist/history.d.ts

@@ -0,0 +1,45 @@
+import type { PubSub } from "@dojo-ng/pubsub";
+import { type CommitEntry, type HistoryInstance } from "./handle.js";
+/** The parts of `window` that `installHistory` uses. Tests pass a fake with this shape. */
+export interface HistoryWindow {
+    history: {
+        pushState(state: unknown, title: string, url?: string | null): void;
+        replaceState(state: unknown, title: string, url?: string | null): void;
+        back(): void;
+        forward(): void;
+        readonly state: unknown;
+    };
+    location: {
+        readonly pathname: string;
+        readonly search: string;
+        readonly hash: string;
+        readonly href: string;
+    };
+    addEventListener(type: string, listener: (event: never) => void): void;
+    removeEventListener(type: string, listener: (event: never) => void): void;
+    document: {
+        readonly visibilityState?: string;
+        addEventListener(type: string, listener: (event: never) => void): void;
+        removeEventListener(type: string, listener: (event: never) => void): void;
+    };
+    readonly sessionStorage?: {
+        getItem(key: string): string | null;
+        setItem(key: string, value: string): void;
+    };
+}
+export interface InstallOptions {
+    /** A path prefix such as `/acme`. Added to every URL written, stripped from every path read. */
+    base?: string;
+    /** Default `globalThis.window`. Exists so tests can inject a fake. */
+    window?: HistoryWindow;
+    /** How long (visible) milliseconds an entry must stay current before it is committed. Default 3000. 0 turns skimming off. */
+    dwellMs?: number;
+    /** Called once per entry when it commits. Never for a skimmed entry, never for the landing entry. */
+    onCommit?: (entry: CommitEntry) => void;
+    /**
+     * Called at install when the landing entry carries no state of ours (a new tab, a pasted link, a
+     * bookmark). Its result becomes the entry's state before `nav:location` is published as `load`.
+     */
+    resolve?: (path: string) => Promise<unknown>;
+}
+export declare function installHistory(bus: PubSub, options?: InstallOptions): HistoryInstance;

package/dist/history.js

@@ -0,0 +1,371 @@
+import { getHistory, registerHistory, unregisterHistory, } from "./handle.js";
+const DEFAULT_DWELL_MS = 3000;
+const MAX_INDEX_KEY = "dojo-ng.history.max";
+const DUPLICATE_INSTALL_WARNED = new WeakSet();
+let idCounter = 0;
+function newId() {
+    return `${Date.now().toString(36)}-${(++idCounter).toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function readStamp(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const stamp = raw.__djnav;
+    if (!isRecord(stamp) || typeof stamp.id !== "string" || typeof stamp.index !== "number")
+        return undefined;
+    return { id: stamp.id, index: stamp.index };
+}
+function isNative(fn) {
+    try {
+        return Function.prototype.toString.call(fn).includes("[native code]");
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeBase(base) {
+    if (!base)
+        return "";
+    const trimmed = base.replace(/\/+$/, "");
+    return trimmed === "" || trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+export function installHistory(bus, options = {}) {
+    const existing = getHistory();
+    if (existing) {
+        if (!DUPLICATE_INSTALL_WARNED.has(existing)) {
+            DUPLICATE_INSTALL_WARNED.add(existing);
+            console.warn("[@dojo-ng/history] installHistory was called more than once. There is one history stack; returning the first instance.");
+        }
+        return existing;
+    }
+    const win = options.window ?? globalThis.window;
+    if (!win)
+        throw new Error("[@dojo-ng/history] installHistory needs a window. Pass options.window outside a browser.");
+    const base = normalizeBase(options.base);
+    const dwellMs = options.dwellMs ?? DEFAULT_DWELL_MS;
+    const warned = new Set();
+    const provisionalIds = new Set();
+    let cur;
+    let last;
+    let expectedPlace = "";
+    let destroyed = false;
+    let timer;
+    let remaining = dwellMs;
+    let startedAt = 0;
+    // --- helpers -------------------------------------------------------------------------------
+    function warnOnce(signal, message) {
+        if (warned.has(signal))
+            return;
+        warned.add(signal);
+        console.warn(`[@dojo-ng/history] ${message} (${signal}). Dojo NG routing stays in charge; this is the only warning of this kind.`);
+    }
+    function currentPath() {
+        const full = win.location.pathname + win.location.search + win.location.hash;
+        if (base && (full === base || full.startsWith(`${base}/`) || full.startsWith(`${base}?`) || full.startsWith(`${base}#`))) {
+            const rest = full.slice(base.length);
+            return rest.startsWith("/") ? rest : `/${rest}`;
+        }
+        return full;
+    }
+    function place() {
+        return win.location.pathname + win.location.search;
+    }
+    function stateFor(entry) {
+        return { __djnav: { id: entry.id, index: entry.index }, state: entry.state, trail: entry.trail };
+    }
+    /** The one place that writes to the browser's history. Called from `onGo`, install, and annotate; never from `onPop`. */
+    function writeEntry(mode, entry, url) {
+        if (mode === "push")
+            win.history.pushState(stateFor(entry), "", url);
+        else
+            win.history.replaceState(stateFor(entry), "", url);
+    }
+    function entryFromState(raw, stamp) {
+        const record = raw;
+        return {
+            id: stamp.id,
+            index: stamp.index,
+            path: currentPath(),
+            state: record.state,
+            trail: Array.isArray(record.trail) ? record.trail : undefined,
+            committed: !provisionalIds.has(stamp.id),
+            source: "pop",
+        };
+    }
+    function readMax() {
+        try {
+            const value = win.sessionStorage?.getItem(MAX_INDEX_KEY);
+            if (value === null || value === undefined)
+                return undefined;
+            const n = Number(value);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function writeMax(n) {
+        try {
+            win.sessionStorage?.setItem(MAX_INDEX_KEY, String(n));
+        }
+        catch {
+            // Storage can be blocked. canGoForward is then false, which is harmless.
+        }
+    }
+    function publish() {
+        const location = {
+            path: cur.path,
+            state: cur.state,
+            index: cur.index,
+            committed: cur.committed,
+            source: cur.source,
+            ...(cur.trail ? { trail: cur.trail } : {}),
+        };
+        last = location;
+        bus.publish("nav:location", location);
+    }
+    function fireCommit(entry) {
+        if (!options.onCommit)
+            return;
+        try {
+            options.onCommit({ path: entry.path, state: entry.state, ...(entry.trail ? { trail: entry.trail } : {}) });
+        }
+        catch (err) {
+            console.error("[@dojo-ng/history] onCommit threw:", err);
+        }
+    }
+    // --- dwell ---------------------------------------------------------------------------------
+    function isVisible() {
+        return win.document.visibilityState !== "hidden";
+    }
+    function stopTimer() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function runTimer() {
+        startedAt = Date.now();
+        timer = setTimeout(() => {
+            timer = undefined;
+            commitCurrent();
+        }, remaining);
+    }
+    /** Start counting dwell time for a provisional entry. Counts visible time only. */
+    function startDwell() {
+        stopTimer();
+        remaining = dwellMs;
+        if (isVisible())
+            runTimer();
+    }
+    function onVisibility() {
+        if (destroyed)
+            return;
+        if (!isVisible()) {
+            if (timer !== undefined) {
+                stopTimer();
+                remaining = Math.max(0, remaining - (Date.now() - startedAt));
+            }
+        }
+        else if (!cur.committed && timer === undefined) {
+            runTimer();
+        }
+    }
+    function commitCurrent() {
+        if (destroyed || cur.committed)
+            return;
+        stopTimer();
+        cur.committed = true;
+        provisionalIds.delete(cur.id);
+        publish();
+        fireCommit(cur);
+    }
+    // --- the coexistence checks (D6) -----------------------------------------------------------
+    function checkForeignLocation() {
+        if (place() !== expectedPlace) {
+            warnOnce("foreign-location", "The location changed without a nav:go, so another router or script may be pushing history");
+        }
+    }
+    // --- inputs --------------------------------------------------------------------------------
+    function onGo(request) {
+        if (destroyed || !request || typeof request.path !== "string")
+            return;
+        checkForeignLocation();
+        const previous = cur;
+        const replace = request.replace === true || !previous.committed;
+        const entry = {
+            id: newId(),
+            index: replace ? previous.index : previous.index + 1,
+            path: request.path,
+            state: request.state,
+            trail: request.trail,
+            committed: false,
+            source: "go",
+        };
+        provisionalIds.delete(previous.id);
+        stopTimer();
+        writeEntry(replace ? "replace" : "push", entry, base + request.path);
+        if (!replace)
+            writeMax(entry.index);
+        expectedPlace = place();
+        cur = entry;
+        // A replace of an entry that had already committed keeps its place on the stack, so the
+        // replacement commits too. Otherwise the entry is provisional until it has been read.
+        const commitNow = dwellMs <= 0 || (replace && previous.committed);
+        if (commitNow) {
+            entry.committed = true;
+            publish();
+            fireCommit(entry);
+        }
+        else {
+            provisionalIds.add(entry.id);
+            publish();
+            startDwell();
+        }
+    }
+    function onPop() {
+        if (destroyed)
+            return;
+        stopTimer();
+        const raw = win.history.state;
+        const stamp = readStamp(raw);
+        let entry;
+        let newlyCommitted = false;
+        if (!stamp) {
+            warnOnce("foreign-entry", "Back or Forward landed on a history entry this layer did not create, so another router or script may be pushing history");
+            // Keeps the id of the entry we were on, so a later Back onto a stamped entry that is
+            // already "current" still reads as history changing without a nav:go.
+            entry = {
+                id: cur.id,
+                index: cur.index,
+                path: currentPath(),
+                state: undefined,
+                committed: true,
+                source: "pop",
+            };
+        }
+        else {
+            if (stamp.id === cur.id) {
+                warnOnce("foreign-location", "Back landed on the entry already current, so history changed without a nav:go");
+            }
+            entry = entryFromState(raw, stamp);
+            if (!entry.committed) {
+                entry.committed = true;
+                provisionalIds.delete(entry.id);
+                newlyCommitted = true;
+            }
+        }
+        entry.source = "pop";
+        cur = entry;
+        expectedPlace = place();
+        publish();
+        if (newlyCommitted)
+            fireCommit(entry);
+    }
+    function onNavigate(event) {
+        const detail = event.detail;
+        if (!detail || typeof detail.path !== "string")
+            return;
+        bus.publish("nav:go", {
+            path: detail.path,
+            state: detail.state,
+            trail: detail.trail,
+            replace: detail.replace === true,
+        });
+    }
+    // --- the instance --------------------------------------------------------------------------
+    const instance = {
+        go(path, state, goOptions) {
+            bus.publish("nav:go", { path, state, trail: goOptions?.trail, replace: goOptions?.replace === true });
+        },
+        back() {
+            win.history.back();
+        },
+        forward() {
+            win.history.forward();
+        },
+        commit: commitCurrent,
+        subscribe(fn) {
+            return bus.subscribe("nav:location", (location) => fn(location));
+        },
+        get current() {
+            return last;
+        },
+        get canGoBack() {
+            return cur.index > 0;
+        },
+        get canGoForward() {
+            const max = readMax();
+            return max !== undefined && cur.index < max;
+        },
+        href(path) {
+            return base + path;
+        },
+        annotate(partial) {
+            if (destroyed)
+                return;
+            if ("state" in partial)
+                cur.state = partial.state;
+            if ("trail" in partial)
+                cur.trail = partial.trail;
+            writeEntry("replace", cur);
+            publish();
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            stopTimer();
+            unsubscribeGo();
+            win.removeEventListener("popstate", onPop);
+            win.document.removeEventListener("visibilitychange", onVisibility);
+            win.document.removeEventListener("dj-navigate", onNavigate);
+            unregisterHistory(instance);
+        },
+    };
+    // --- install -------------------------------------------------------------------------------
+    if (!isNative(win.history.pushState) || !isNative(win.history.replaceState)) {
+        warnOnce("patched-pushstate", "history.pushState or replaceState is not the browser's own, so another router may be patching them");
+    }
+    const raw = win.history.state;
+    const stamp = readStamp(raw);
+    let fresh = false;
+    if (stamp) {
+        cur = { ...entryFromState(raw, stamp), committed: true, source: "load" };
+    }
+    else {
+        // A fresh tab, pasted link, or bookmark. Stamp the entry so none ever has null state (app3 lesson 5).
+        fresh = true;
+        cur = { id: newId(), index: 0, path: currentPath(), state: undefined, committed: true, source: "load" };
+        writeEntry("replace", cur);
+        writeMax(0);
+    }
+    expectedPlace = place();
+    const unsubscribeGo = bus.subscribe("nav:go", onGo, { replay: false });
+    win.addEventListener("popstate", onPop);
+    win.document.addEventListener("visibilitychange", onVisibility);
+    win.document.addEventListener("dj-navigate", onNavigate);
+    registerHistory(instance);
+    if (fresh && options.resolve) {
+        const landing = cur;
+        new Promise((resolve) => resolve(options.resolve(landing.path))).then((result) => {
+            if (destroyed || cur !== landing)
+                return;
+            if (result !== undefined) {
+                landing.state = result;
+                writeEntry("replace", landing);
+            }
+            publish();
+        }, (err) => {
+            console.error("[@dojo-ng/history] resolve rejected; publishing the bare path:", err);
+            if (destroyed || cur !== landing)
+                return;
+            publish();
+        });
+    }
+    else {
+        publish();
+    }
+    return instance;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { installHistory } from "./history.js";
+export type { InstallOptions, HistoryWindow } from "./history.js";
+export { match } from "./match.js";
+export { getHistory, whenHistory } from "./handle.js";
+export type { CommitEntry, GoOptions, HistoryInstance, NavAnnotation, NavGo, NavigateDetail, NavLocation, NavSource, TrailEntry, } from "./handle.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { installHistory } from "./history.js";
+export { match } from "./match.js";
+export { getHistory, whenHistory } from "./handle.js";

package/dist/match.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Match a path against a pattern of static segments, `:name` params, and an optional trailing `*`.
+ * Returns the params, or `null` when the path does not match. Params are decoded with
+ * `decodeURIComponent`; a malformed escape is a non-match. A trailing slash on either side is
+ * ignored. `*` takes the rest of the path, zero or more segments, under the key `"*"`.
+ *
+ * Pass a pathname. A `?query` or `#hash` is not stripped.
+ */
+export declare function match(pattern: string, path: string): Record<string, string> | null;

package/dist/match.js

@@ -0,0 +1,58 @@
+// Path matching. A separate export that navigation never calls (decision D10): mapping a path to a
+// view stays the app's job, and this is only a helper for doing it.
+function segments(path) {
+    const parts = path.split("/");
+    if (parts[0] === "")
+        parts.shift();
+    if (parts.length > 0 && parts[parts.length - 1] === "")
+        parts.pop();
+    return parts;
+}
+function decode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Match a path against a pattern of static segments, `:name` params, and an optional trailing `*`.
+ * Returns the params, or `null` when the path does not match. Params are decoded with
+ * `decodeURIComponent`; a malformed escape is a non-match. A trailing slash on either side is
+ * ignored. `*` takes the rest of the path, zero or more segments, under the key `"*"`.
+ *
+ * Pass a pathname. A `?query` or `#hash` is not stripped.
+ */
+export function match(pattern, path) {
+    const want = segments(pattern);
+    const have = segments(path);
+    const rest = want[want.length - 1] === "*";
+    const fixed = rest ? want.slice(0, -1) : want;
+    if (rest ? have.length < fixed.length : have.length !== fixed.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < fixed.length; i++) {
+        const piece = fixed[i];
+        if (piece.length > 1 && piece[0] === ":") {
+            const value = decode(have[i]);
+            if (value === null)
+                return null;
+            params[piece.slice(1)] = value;
+        }
+        else if (piece !== have[i]) {
+            return null;
+        }
+    }
+    if (rest) {
+        const decoded = [];
+        for (const part of have.slice(fixed.length)) {
+            const value = decode(part);
+            if (value === null)
+                return null;
+            decoded.push(value);
+        }
+        params["*"] = decoded.join("/");
+    }
+    return params;
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@dojo-ng/history",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Dojo NG navigation history: real paths with pushState, Back and Forward that skip skimmed pages, and hooks for tracking",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./handle": {
+      "types": "./dist/handle.d.ts",
+      "default": "./dist/handle.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "dojo",
+    "history",
+    "navigation",
+    "pushstate",
+    "spa",
+    "esm"
+  ],
+  "repository": {
+    "type": "hg",
+    "url": "https://foss.heptapod.net/dojo-ng/framework"
+  },
+  "dependencies": {
+    "@dojo-ng/pubsub": "^0.1.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:browser": "npm run build && web-test-runner",
+    "playground": "node playground/server.mjs",
+    "prepublishOnly": "npm run build"
+  }
+}