@connextar/house 0.1.1 → 0.2.0

package/dist/release/changelog.js

@@ -0,0 +1,92 @@
+import { isReleaseVersion, releaseKind } from "./version.js";
+export const CHANGE_TYPES = ["new", "improved", "changed", "fixed"];
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Everything wrong with a release history, as sentences — an empty list means
+ * it is sound. An app's guard test is one assertion:
+ *
+ * ```ts
+ * expect(releaseHistoryProblems(CHANGELOG, { pkg, lock })).toEqual([]);
+ * ```
+ *
+ * A version lives in three places — package.json, its lockfile and the newest
+ * changelog release — and a bump that touches one and forgets another is the
+ * drift this exists to catch. Returning problems rather than throwing on the
+ * first means a broken history is reported whole.
+ */
+export function releaseHistoryProblems(changelog, manifest) {
+    const problems = [];
+    const newest = changelog[0];
+    if (!newest)
+        return ["the changelog has no releases"];
+    if (manifest) {
+        const declared = manifest.pkg.version;
+        if (declared !== newest.version) {
+            problems.push(`package.json declares ${declared ?? "no version"} but the newest release is ${newest.version}`);
+        }
+        if (manifest.lock) {
+            if (manifest.lock.version !== declared) {
+                problems.push(`package-lock.json declares ${manifest.lock.version ?? "no version"}, package.json ${declared}`);
+            }
+            const root = manifest.lock.packages?.[""]?.version;
+            if (manifest.lock.packages && root !== declared) {
+                problems.push(`package-lock.json's root package declares ${root ?? "no version"}, package.json ${declared}`);
+            }
+        }
+    }
+    changelog.forEach((release, i) => {
+        const label = release.version || `release #${i + 1}`;
+        if (!isReleaseVersion(release.version)) {
+            problems.push(`${label} is not MAJOR.MINOR.PATCH`);
+        }
+        if (!ISO_DATE.test(release.date) || Number.isNaN(new Date(`${release.date}T00:00:00Z`).getTime())) {
+            problems.push(`${label} has date "${release.date}", not YYYY-MM-DD`);
+        }
+        const older = changelog[i + 1];
+        if (older && isReleaseVersion(release.version) && isReleaseVersion(older.version)) {
+            if (releaseKind(older.version, release.version) === null) {
+                problems.push(`${older.version} → ${release.version} is not one step (newest first, no skipped numbers)`);
+            }
+            if (ISO_DATE.test(release.date) && ISO_DATE.test(older.date) && release.date < older.date) {
+                problems.push(`${release.version} is dated ${release.date}, before ${older.version} (${older.date})`);
+            }
+        }
+        if (!release.title.trim())
+            problems.push(`${label} has no title`);
+        if (!release.summary.trim())
+            problems.push(`${label} has no summary`);
+        if (release.sections.length === 0)
+            problems.push(`${label} has no sections`);
+        const headings = release.sections.map((section) => section.heading);
+        if (new Set(headings).size !== headings.length)
+            problems.push(`${label} repeats a section heading`);
+        for (const section of release.sections) {
+            if (!section.heading.trim())
+                problems.push(`${label} has a section with no heading`);
+            if (section.changes.length === 0)
+                problems.push(`${label} · ${section.heading} has no changes`);
+            for (const change of section.changes) {
+                if (!CHANGE_TYPES.includes(change.type)) {
+                    problems.push(`${label} · ${section.heading} has a change of unknown type "${String(change.type)}"`);
+                }
+                if (!change.title.trim())
+                    problems.push(`${label} · ${section.heading} has a change with no title`);
+                if (!change.text.trim())
+                    problems.push(`${label} · ${section.heading} · "${change.title}" has no text`);
+            }
+        }
+    });
+    return problems;
+}
+/** A fragment id without dots, so it never needs escaping as a selector: `v0-25-0`. */
+export function releaseAnchor(version) {
+    return `v${version.replaceAll(".", "-")}`;
+}
+/** Format an ISO date as "29 August 2026" (or the locale's equivalent), in UTC so it never shifts a day. */
+export function formatReleaseDate(iso, locale = "en-GB") {
+    return new Intl.DateTimeFormat(locale, { day: "numeric", month: "long", year: "numeric", timeZone: "UTC" }).format(new Date(`${iso}T00:00:00Z`));
+}
+export function countChanges(release) {
+    return release.sections.reduce((n, section) => n + section.changes.length, 0);
+}
+//# sourceMappingURL=changelog.js.map

package/dist/release/changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/release/changelog.ts"],"names":[],"mappings":"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"}

package/dist/release/index.d.ts

@@ -0,0 +1,3 @@
+export { compareVersions, isReleaseVersion, nextVersion, parseVersion, releaseKind, type ReleaseKind, type Version, } from "./version.js";
+export { CHANGE_TYPES, countChanges, formatReleaseDate, releaseAnchor, releaseHistoryProblems, type ChangeType, type ChangelogChange, type ChangelogRelease, type ChangelogSection, type ReleaseManifest, } from "./changelog.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/release/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/release/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,OAAO,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC"}

package/dist/release/index.js

@@ -0,0 +1,3 @@
+export { compareVersions, isReleaseVersion, nextVersion, parseVersion, releaseKind, } from "./version.js";
+export { CHANGE_TYPES, countChanges, formatReleaseDate, releaseAnchor, releaseHistoryProblems, } from "./changelog.js";
+//# sourceMappingURL=index.js.map

package/dist/release/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/release/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,WAAW,GAGZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,sBAAsB,GAMvB,MAAM,gBAAgB,CAAC"}

package/dist/release/version.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Semantic versions for an app's releases.
+ *
+ * The rules for choosing a version live in docs/ReleaseProcess.md; this file
+ * only knows the arithmetic, so a changelog page and a release guard test read
+ * versions the same way.
+ */
+export type ReleaseKind = "major" | "minor" | "patch";
+export interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare function parseVersion(value: string): Version;
+export declare function isReleaseVersion(value: string): boolean;
+/** Negative when `a` is older than `b`, positive when newer, 0 when equal. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * What kind of release `next` is after `previous` — or null when it is not
+ * exactly one step on (a skipped number, a reset that isn't to zero, or going
+ * backwards). One step at a time is what makes every version findable.
+ */
+export declare function releaseKind(previous: string, next: string): ReleaseKind | null;
+/**
+ * The version after `current` for a change of the given class.
+ *
+ * Before 1.0.0 a MAJOR-class change bumps MINOR — semver treats 0.x as a period
+ * when anything may change, and leaving it is the owner's call, never a side
+ * effect of a change set. The release must then carry a `changed` entry saying
+ * what people need to do.
+ */
+export declare function nextVersion(current: string, change: ReleaseKind): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/release/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/release/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAInD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAO9E;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAKxE"}

package/dist/release/version.js

@@ -0,0 +1,57 @@
+/**
+ * Semantic versions for an app's releases.
+ *
+ * The rules for choosing a version live in docs/ReleaseProcess.md; this file
+ * only knows the arithmetic, so a changelog page and a release guard test read
+ * versions the same way.
+ */
+/** MAJOR.MINOR.PATCH with no leading zeros, no "v" and no pre-release suffix. */
+const RELEASE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+export function parseVersion(value) {
+    const match = RELEASE_VERSION.exec(value);
+    if (!match)
+        throw new Error(`Not a release version (MAJOR.MINOR.PATCH): "${value}"`);
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+export function isReleaseVersion(value) {
+    return RELEASE_VERSION.test(value);
+}
+/** Negative when `a` is older than `b`, positive when newer, 0 when equal. */
+export function compareVersions(a, b) {
+    const x = parseVersion(a);
+    const y = parseVersion(b);
+    return x.major - y.major || x.minor - y.minor || x.patch - y.patch;
+}
+/**
+ * What kind of release `next` is after `previous` — or null when it is not
+ * exactly one step on (a skipped number, a reset that isn't to zero, or going
+ * backwards). One step at a time is what makes every version findable.
+ */
+export function releaseKind(previous, next) {
+    const p = parseVersion(previous);
+    const n = parseVersion(next);
+    if (n.major === p.major + 1 && n.minor === 0 && n.patch === 0)
+        return "major";
+    if (n.major === p.major && n.minor === p.minor + 1 && n.patch === 0)
+        return "minor";
+    if (n.major === p.major && n.minor === p.minor && n.patch === p.patch + 1)
+        return "patch";
+    return null;
+}
+/**
+ * The version after `current` for a change of the given class.
+ *
+ * Before 1.0.0 a MAJOR-class change bumps MINOR — semver treats 0.x as a period
+ * when anything may change, and leaving it is the owner's call, never a side
+ * effect of a change set. The release must then carry a `changed` entry saying
+ * what people need to do.
+ */
+export function nextVersion(current, change) {
+    const { major, minor, patch } = parseVersion(current);
+    if (change === "patch")
+        return `${major}.${minor}.${patch + 1}`;
+    if (change === "minor" || major === 0)
+        return `${major}.${minor + 1}.0`;
+    return `${major + 1}.0.0`;
+}
+//# sourceMappingURL=version.js.map

package/dist/release/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/release/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,iFAAiF;AACjF,MAAM,eAAe,GAAG,4CAA4C,CAAC;AAErE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,KAAK,GAAG,CAAC,CAAC;IACrF,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,IAAY;IACxD,MAAM,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC9E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACpF,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,MAAmB;IAC9D,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;IAChE,IAAI,MAAM,KAAK,OAAO,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC;IACxE,OAAO,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC;AAC5B,CAAC"}

package/dist/trail/index.d.ts

@@ -0,0 +1,3 @@
+export { codeFor, isCrumb, nextTrail, TRAIL_LIMIT, type Crumb } from "./rules.js";
+export { carryTrail, ScrollToHash, TrailBar, TrailHere, TrailProvider, TrailRail, UnlessTrail, useActiveTrail, useTrail, } from "./trail.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/trail/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trail/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EACL,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/dist/trail/index.js

@@ -0,0 +1,3 @@
+export { codeFor, isCrumb, nextTrail, TRAIL_LIMIT } from "./rules.js";
+export { carryTrail, ScrollToHash, TrailBar, TrailHere, TrailProvider, TrailRail, UnlessTrail, useActiveTrail, useTrail, } from "./trail.js";
+//# sourceMappingURL=index.js.map

package/dist/trail/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trail/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAClF,OAAO,EACL,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/dist/trail/rules.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The navigation trail: the path someone took to where they are, kept so they
+ * can step back to any point of it in one click.
+ *
+ * Every page that sits in a hierarchy says where it is — its own chain, root
+ * first (Home › Amara › Progress). Most of the time that chain *is* the trail.
+ * The exception is following a reference: from a note, `@Amara` opens Amara's
+ * page, and the way back to the note must survive the jump even though the note
+ * is nowhere in Amara's hierarchy. So a reference link "carries" the trail
+ * across, and the destination's chain is added to the end of it.
+ *
+ * Pure, so the rules are tested without a browser; `./trail.tsx` keeps the
+ * state and draws it.
+ */
+export interface Crumb {
+    /** Identity across pages: "note:abc", "learner:xyz", "section:progress". */
+    key: string;
+    label: string;
+    href: string;
+    /** A short code for the pill's chip — "NO", "LE" — derived when absent. */
+    code?: string;
+}
+/** The most crumbs kept: past this, the oldest fall off the front. */
+export declare const TRAIL_LIMIT = 8;
+/**
+ * The next trail, from the one before, the page's own chain, and whether the
+ * page was reached by following a reference.
+ *
+ * - **Carried** (a reference was followed): the page's chain is appended to the
+ *   trail — minus anything already in it. Following a reference back to
+ *   something already on the trail returns to that point instead of looping.
+ * - **Not carried**: the page's chain *is* the trail — unless the page is
+ *   already on the trail (a pill was clicked, or Back pressed), in which case
+ *   the trail is cut back to it.
+ */
+export declare function nextTrail(previous: readonly Crumb[], chain: readonly Crumb[], carried: boolean): Crumb[];
+/** "Maths — Schedule" → "MS"; "Notes" → "NO"; always two characters or fewer, upper-case. */
+export declare function codeFor(crumb: Crumb): string;
+/**
+ * Only a same-origin path is a crumb. The trail is kept in `sessionStorage`,
+ * which is ours — but it is still input, and a crumb is a link.
+ */
+export declare function isCrumb(value: unknown): value is Crumb;
+//# sourceMappingURL=rules.d.ts.map

package/dist/trail/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/trail/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,KAAK;IACpB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sEAAsE;AACtE,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,KAAK,EAAE,CAcxG;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAU5C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAYtD"}

package/dist/trail/rules.js

@@ -0,0 +1,74 @@
+/**
+ * The navigation trail: the path someone took to where they are, kept so they
+ * can step back to any point of it in one click.
+ *
+ * Every page that sits in a hierarchy says where it is — its own chain, root
+ * first (Home › Amara › Progress). Most of the time that chain *is* the trail.
+ * The exception is following a reference: from a note, `@Amara` opens Amara's
+ * page, and the way back to the note must survive the jump even though the note
+ * is nowhere in Amara's hierarchy. So a reference link "carries" the trail
+ * across, and the destination's chain is added to the end of it.
+ *
+ * Pure, so the rules are tested without a browser; `./trail.tsx` keeps the
+ * state and draws it.
+ */
+/** The most crumbs kept: past this, the oldest fall off the front. */
+export const TRAIL_LIMIT = 8;
+/**
+ * The next trail, from the one before, the page's own chain, and whether the
+ * page was reached by following a reference.
+ *
+ * - **Carried** (a reference was followed): the page's chain is appended to the
+ *   trail — minus anything already in it. Following a reference back to
+ *   something already on the trail returns to that point instead of looping.
+ * - **Not carried**: the page's chain *is* the trail — unless the page is
+ *   already on the trail (a pill was clicked, or Back pressed), in which case
+ *   the trail is cut back to it.
+ */
+export function nextTrail(previous, chain, carried) {
+    const here = chain.at(-1);
+    if (!here)
+        return [];
+    const at = previous.findIndex((crumb) => crumb.key === here.key);
+    if (at !== -1) {
+        // Back to a point already on the trail: keep what led there, refresh the
+        // crumb itself (its label may have changed — a renamed note).
+        return [...previous.slice(0, at), here].slice(-TRAIL_LIMIT);
+    }
+    if (!carried)
+        return chain.slice(-TRAIL_LIMIT);
+    const seen = new Set(previous.map((crumb) => crumb.key));
+    return [...previous, ...chain.filter((crumb) => !seen.has(crumb.key))].slice(-TRAIL_LIMIT);
+}
+/** "Maths — Schedule" → "MS"; "Notes" → "NO"; always two characters or fewer, upper-case. */
+export function codeFor(crumb) {
+    if (crumb.code)
+        return crumb.code.slice(0, 3).toUpperCase();
+    const words = crumb.label
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .split(/\s+/)
+        .filter(Boolean);
+    const [first, second] = words;
+    if (!first)
+        return "·";
+    if (!second)
+        return first.slice(0, 2).toUpperCase();
+    return ((first[0] ?? "") + (second[0] ?? "")).toUpperCase();
+}
+/**
+ * Only a same-origin path is a crumb. The trail is kept in `sessionStorage`,
+ * which is ours — but it is still input, and a crumb is a link.
+ */
+export function isCrumb(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const { key, label, href, code } = value;
+    return (typeof key === "string" &&
+        typeof label === "string" &&
+        typeof href === "string" &&
+        href.startsWith("/") &&
+        !href.startsWith("//") &&
+        !href.startsWith("/\\") &&
+        (code === undefined || typeof code === "string"));
+}
+//# sourceMappingURL=rules.js.map

package/dist/trail/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/trail/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,QAA0B,EAAE,KAAuB,EAAE,OAAgB;IAC7F,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjE,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACd,yEAAyE;QACzE,8DAA8D;QAC9D,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC;IAE/C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,QAAQ,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC;AAC7F,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,OAAO,CAAC,KAAY;IAClC,IAAI,KAAK,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK;SACtB,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC;SACjC,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,GAAG,CAAC;IACvB,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACpD,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,KAAgC,CAAC;IACpE,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QACtB,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QACvB,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CACjD,CAAC;AACJ,CAAC"}

package/dist/trail/trail.d.ts

@@ -0,0 +1,49 @@
+import { type ReactNode } from "react";
+import { type Crumb } from "./rules.js";
+/**
+ * `scope` is what the trail is made in — typically `${user.id}:${view}`.
+ * Mount it once in the layout that frames the pages which register crumbs.
+ */
+export declare function TrailProvider({ scope, children }: {
+    scope?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Say where this page sits: its chain, root first, ending with itself. Pass null
+ * while the page doesn't know yet (nothing selected). Re-registers when the
+ * chain's keys, labels or links change — not on every render.
+ */
+export declare function useTrail(chain: Crumb[] | null): void;
+/** For a server page: say where it sits in the trail. Renders nothing. */
+export declare function TrailHere({ chain }: {
+    chain: Crumb[];
+}): null;
+/** Before following a reference: the next page keeps the trail that led to it. */
+export declare function carryTrail(): void;
+/** The trail for the page on screen, or null when there is nothing to go back to. */
+export declare function useActiveTrail(): Crumb[] | null;
+/**
+ * Renders its children only while no trail is showing. A page's static
+ * breadcrumb and the trail answer the same question — how do I get back? — so
+ * when the trail is up, it answers alone.
+ */
+export declare function UnlessTrail({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/** Stacked vertical pills pinned to the left of the page (wide screens). */
+export declare function TrailRail({ className, top }: {
+    className?: string;
+    top?: string;
+}): import("react").JSX.Element | null;
+/** The same trail as a pinned bar across the top, with Back (narrow screens). */
+export declare function TrailBar({ className, top }: {
+    className?: string;
+    top?: string;
+}): import("react").JSX.Element | null;
+/**
+ * Scroll to the element the URL's `#hash` names, once it exists. The router
+ * tries on arrival, but a streamed page can arrive before the element does — a
+ * crumb pointing at `/home#item-…` otherwise lands at the top of the page.
+ */
+export declare function ScrollToHash(): null;
+//# sourceMappingURL=trail.d.ts.map

package/dist/trail/trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.d.ts","sourceRoot":"","sources":["../../src/trail/trail.tsx"],"names":[],"mappings":"AAKA,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAA+B,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAyDrE;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAU,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAwC9F;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,GAAG,IAAI,CAapD;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,KAAK,EAAE,CAAA;CAAE,QAGtD;AAED,kFAAkF;AAClF,wBAAgB,UAAU,IAAI,IAAI,CAMjC;AAED,qFAAqF;AACrF,wBAAgB,cAAc,IAAI,KAAK,EAAE,GAAG,IAAI,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,sCAEhE;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,EAAE,SAAS,EAAE,GAAY,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,sCAoE1F;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAY,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,sCA2DzF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,SAW3B"}

package/dist/trail/trail.js

@@ -0,0 +1,188 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeft } from "lucide-react";
+import { Link } from "../internal/next-link.js";
+import { usePathname } from "next/navigation.js";
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "../internal/cx.js";
+import { codeFor, isCrumb, nextTrail } from "./rules.js";
+/**
+ * The navigation trail on screen — see `./rules.ts` for the rules.
+ *
+ * Pages say where they are with `useTrail(chain)` (or `<TrailHere>` from a
+ * server page); the provider works out the trail and keeps it in
+ * `sessionStorage`, so it belongs to one tab and survives a reload but not a
+ * new window. A reference link calls `carryTrail()` before navigating — or
+ * carries `data-trail-carry` — which is what lets the destination keep the way
+ * back to the page it came from.
+ *
+ * Two renderings of the same crumbs: stacked vertical pills pinned to the left
+ * of the page on wide screens, and a pinned bar with Back across the top on
+ * narrow ones. Both appear only when there is somewhere to go back to — two
+ * crumbs or more — and only on the page that registered them.
+ *
+ * A trail belongs to one scope. Switching who is signed in, or which view of
+ * the product they are in, starts a new one: the old crumbs may lead to pages
+ * the new scope cannot see, so the stored trail carries the `scope` it was made
+ * in, and one from another scope is dropped.
+ *
+ * Storage keys need no per-app prefix: sessionStorage is already per origin.
+ */
+const STORE = "house:trail";
+const CARRY = "house:trail:carry";
+/** A carry older than this was a navigation that never landed on a trail page. */
+const CARRY_MS = 15_000;
+// Two contexts: the trail itself, which changes, and the function that sets it,
+// which changes only with the scope. Pages depend only on the second —
+// depending on a context that changes whenever they register would register
+// again, forever.
+const TrailStateContext = createContext(null);
+const TrailRegisterContext = createContext(null);
+function readStored(scope) {
+    try {
+        const parsed = JSON.parse(sessionStorage.getItem(STORE) ?? "null");
+        const stored = typeof parsed === "object" && parsed !== null ? parsed : {};
+        const previous = stored.scope === scope && Array.isArray(stored.crumbs) ? stored.crumbs.filter(isCrumb) : [];
+        const stamp = Number(sessionStorage.getItem(CARRY) ?? 0);
+        return { previous, carried: stamp > 0 && Date.now() - stamp < CARRY_MS };
+    }
+    catch {
+        return { previous: [], carried: false };
+    }
+}
+/**
+ * `scope` is what the trail is made in — typically `${user.id}:${view}`.
+ * Mount it once in the layout that frames the pages which register crumbs.
+ */
+export function TrailProvider({ scope = "", children }) {
+    const [state, setState] = useState(null);
+    const [shownScope, setShownScope] = useState(scope);
+    // Switched scope on this page: the trail on screen goes with the old one.
+    if (shownScope !== scope) {
+        setShownScope(scope);
+        setState(null);
+    }
+    const register = useCallback((path, chain) => {
+        const { previous, carried } = readStored(scope);
+        const crumbs = nextTrail(previous, chain, carried);
+        try {
+            sessionStorage.setItem(STORE, JSON.stringify({ scope, crumbs }));
+            sessionStorage.removeItem(CARRY);
+        }
+        catch {
+            // Storage can be unavailable (private windows); the trail just won't persist.
+        }
+        setState({ path, crumbs });
+    }, [scope]);
+    // A link marked `data-trail-carry` — a reference in read-only text — carries
+    // the trail, as the editor's references do.
+    useEffect(() => {
+        const onClick = (event) => {
+            if (event.target instanceof Element && event.target.closest("a[data-trail-carry]"))
+                carryTrail();
+        };
+        document.addEventListener("click", onClick, true);
+        return () => document.removeEventListener("click", onClick, true);
+    }, []);
+    return (_jsx(TrailRegisterContext.Provider, { value: register, children: _jsx(TrailStateContext.Provider, { value: state, children: children }) }));
+}
+/**
+ * Say where this page sits: its chain, root first, ending with itself. Pass null
+ * while the page doesn't know yet (nothing selected). Re-registers when the
+ * chain's keys, labels or links change — not on every render.
+ */
+export function useTrail(chain) {
+    const register = useContext(TrailRegisterContext);
+    const pathname = usePathname();
+    const signature = chain ? JSON.stringify(chain.map((c) => [c.key, c.label, c.href])) : "";
+    const latest = useRef(chain);
+    useLayoutEffect(() => {
+        latest.current = chain;
+    });
+    useEffect(() => {
+        const current = latest.current;
+        if (register && current && current.length > 0)
+            register(pathname, current);
+    }, [register, pathname, signature]);
+}
+/** For a server page: say where it sits in the trail. Renders nothing. */
+export function TrailHere({ chain }) {
+    useTrail(chain);
+    return null;
+}
+/** Before following a reference: the next page keeps the trail that led to it. */
+export function carryTrail() {
+    try {
+        sessionStorage.setItem(CARRY, String(Date.now()));
+    }
+    catch {
+        // No storage, no trail — the link still works.
+    }
+}
+/** The trail for the page on screen, or null when there is nothing to go back to. */
+export function useActiveTrail() {
+    const state = useContext(TrailStateContext);
+    const pathname = usePathname();
+    if (!state || state.path !== pathname || state.crumbs.length < 2)
+        return null;
+    return state.crumbs;
+}
+/**
+ * Renders its children only while no trail is showing. A page's static
+ * breadcrumb and the trail answer the same question — how do I get back? — so
+ * when the trail is up, it answers alone.
+ */
+export function UnlessTrail({ children }) {
+    return useActiveTrail() ? null : _jsx(_Fragment, { children: children });
+}
+/** Stacked vertical pills pinned to the left of the page (wide screens). */
+export function TrailRail({ className, top = "4rem" }) {
+    const crumbs = useActiveTrail();
+    if (!crumbs)
+        return null;
+    const last = crumbs.length - 1;
+    return (_jsx("nav", { "aria-label": "Where you've been", className: cx("house-trail-rail sticky hidden shrink-0 self-start border-r border-border lg:flex print:hidden", className), style: { top, height: `calc(100dvh - ${top})` }, children: _jsx("ol", { className: "flex", children: crumbs.map((crumb, index) => {
+                const current = index === last;
+                const body = (_jsxs(_Fragment, { children: [_jsx("span", { className: cx("rounded px-1 py-0.5 font-mono text-[9px] leading-none font-bold", current ? "bg-primary text-primary-foreground" : "bg-muted-foreground/70 text-background"), "aria-hidden": true, children: codeFor(crumb) }), _jsx("span", { className: cx("max-h-[calc(100dvh-10rem)] overflow-hidden text-[12.5px] font-semibold text-ellipsis whitespace-nowrap [writing-mode:vertical-rl] [transform:rotate(180deg)]", current ? "text-foreground" : "text-muted-foreground"), children: crumb.label })] }));
+                const shared = "house-trail-pill flex h-full w-11 flex-col items-center gap-2.5 border-r border-border py-3.5";
+                // Each step deeper is a shade further from the card; the stylesheet
+                // turns the step into a tint, so HSL-triplet themes can map the colours.
+                const style = { "--house-trail-step": Math.min(index, 5) };
+                return (_jsx("li", { className: "flex", children: current ? (_jsx("span", { "aria-current": "page", title: crumb.label, className: shared, style: style, "data-current": "", children: body })) : (_jsx(Link, { href: crumb.href, title: `Back to ${crumb.label}`, className: cx(shared, "transition-colors hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none focus-visible:ring-inset"), style: style, children: body })) }, crumb.key));
+            }) }) }));
+}
+/** The same trail as a pinned bar across the top, with Back (narrow screens). */
+export function TrailBar({ className, top = "4rem" }) {
+    const crumbs = useActiveTrail();
+    const listRef = useRef(null);
+    // The end of the trail is where you are; keep it in view on a narrow bar.
+    useEffect(() => {
+        const list = listRef.current;
+        if (list)
+            list.scrollLeft = list.scrollWidth;
+    }, [crumbs]);
+    const previous = crumbs?.at(-2);
+    if (!crumbs || !previous)
+        return null;
+    const last = crumbs.length - 1;
+    return (_jsxs("nav", { "aria-label": "Where you've been", "data-trail-bar": "", className: cx("sticky z-20 -mx-4 -mt-6 mb-4 flex items-center gap-1 border-b border-border bg-background/95 px-2 py-1.5 backdrop-blur sm:-mx-6 lg:hidden print:hidden", className), style: { top }, children: [_jsxs(Link, { href: previous.href, className: "flex min-h-8 shrink-0 items-center gap-0.5 rounded-md px-1.5 text-sm font-medium text-primary hover:bg-accent", "aria-label": `Back to ${previous.label}`, children: [_jsx(ChevronLeft, { className: "size-4", "aria-hidden": true }), "Back"] }), _jsx("ol", { ref: listRef, className: "flex min-w-0 flex-1 items-center overflow-x-auto text-sm whitespace-nowrap", children: crumbs.map((crumb, index) => (_jsxs("li", { className: "flex items-center", children: [index > 0 ? (_jsx("span", { className: "px-1 text-muted-foreground/60", "aria-hidden": true, children: "/" })) : null, index === last ? (_jsx("span", { "aria-current": "page", className: "max-w-[12rem] truncate font-medium", children: crumb.label })) : (_jsx(Link, { href: crumb.href, className: "inline-flex min-h-8 max-w-[9rem] items-center truncate rounded px-1 text-muted-foreground hover:text-foreground", children: crumb.label }))] }, crumb.key))) })] }));
+}
+/**
+ * Scroll to the element the URL's `#hash` names, once it exists. The router
+ * tries on arrival, but a streamed page can arrive before the element does — a
+ * crumb pointing at `/home#item-…` otherwise lands at the top of the page.
+ */
+export function ScrollToHash() {
+    useEffect(() => {
+        const go = () => {
+            const id = decodeURIComponent(window.location.hash.slice(1));
+            if (id)
+                document.getElementById(id)?.scrollIntoView({ block: "start" });
+        };
+        go();
+        window.addEventListener("hashchange", go);
+        return () => window.removeEventListener("hashchange", go);
+    }, []);
+    return null;
+}
+//# sourceMappingURL=trail.js.map

package/dist/trail/trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.js","sourceRoot":"","sources":["../../src/trail/trail.tsx"],"names":[],"mappings":"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"}