shelving 1.222.3 → 1.224.0

package/package.json

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

package/ui/block/Card.module.css

@@ -1,3 +1,8 @@
+:root {
+	/* Opaque surface colour for content nested inside a card — slightly darker than `--color-surface`. */
+	--card-color-surface: color-mix(in srgb, var(--color-surface) 92%, black);
+}
+
 .card {
 	/* Box */
 	position: relative;
@@ -47,6 +52,12 @@
 	}
 }
 
+/* Content nested in a card uses the card's opaque surface colour, so translucent surfaces don't double up. */
+/* `:where()` keeps specificity at zero so colour/status variant classes on descendants still win. */
+:where(.card) * {
+	--color-surface: var(--card-color-surface);
+}
+
 .overlay {
 	/* Cover the entire card. */
 	position: absolute;

package/ui/docs/DirectoryPage.d.ts

@@ -1,4 +1,10 @@
 import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
+import type { AbsolutePath } from "../../util/path.js";
+interface DirectoryPageProps extends DirectoryElementProps {
+    /** Site-root-relative path of this page — threaded down so child cards build correct hrefs. */
+    readonly path: AbsolutePath;
+}
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
-export declare function DirectoryPage({ title, name, description, content, children }: DirectoryElementProps): ReactNode;
+export declare function DirectoryPage({ path, title, name, description, content, children }: DirectoryPageProps): ReactNode;
+export {};

package/ui/docs/DirectoryPage.js

@@ -2,12 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
 import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
-import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
-export function DirectoryPage({ title, name, description, content, children }) {
-    const { url } = requireMeta();
-    const path = url?.pathname ?? "/";
+export function DirectoryPage({ path, title, name, description, content, children }) {
     return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/DirectoryPage.tsx

@@ -1,16 +1,19 @@
 import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
+import type { AbsolutePath } from "../../util/path.js";
 import { Prose } from "../block/Prose.js";
 import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
-import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 
+interface DirectoryPageProps extends DirectoryElementProps {
+	/** Site-root-relative path of this page — threaded down so child cards build correct hrefs. */
+	readonly path: AbsolutePath;
+}
+
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
-export function DirectoryPage({ title, name, description, content, children }: DirectoryElementProps): ReactNode {
-	const { url } = requireMeta();
-	const path = url?.pathname ?? "/";
+export function DirectoryPage({ path, title, name, description, content, children }: DirectoryPageProps): ReactNode {
 	return (
 		<Page title={title ?? name} description={description}>
 			<Title>{title ?? name}</Title>

package/ui/docs/DocumentationPage.d.ts

@@ -1,9 +1,15 @@
 import type { ReactNode } from "react";
 import { type DocumentationElementProps } from "../../util/element.js";
+import type { AbsolutePath } from "../../util/path.js";
+interface DocumentationPageProps extends DocumentationElementProps {
+    /** Site-root-relative path of this page — threaded down so child cards build correct hrefs. */
+    readonly path: AbsolutePath;
+}
 /**
  * Page renderer for a `tree-documentation` element (also used for `tree-file` elements, whose props are a compatible subset).
  * - Renders title, signatures (one per overload), content, parameters, returns, throws, and examples.
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
  */
-export declare function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, }: DocumentationElementProps): ReactNode;
+export declare function DocumentationPage({ path, title, name, kind, description, content, signatures, params, returns, throws, examples, children, }: DocumentationPageProps): ReactNode;
+export {};

package/ui/docs/DocumentationPage.js

@@ -9,7 +9,6 @@ import { Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
-import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 import { DocumentationKind } from "./DocumentationKind.js";
@@ -30,9 +29,7 @@ const KIND_SECTIONS = [
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
  */
-export function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, }) {
-    const { url } = requireMeta();
-    const path = (url?.pathname ?? "/");
+export function DocumentationPage({ path, title, name, kind, description, content, signatures, params, returns, throws, examples, children, }) {
     return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: _jsxs(Flex, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), KIND_SECTIONS.map(([kind, label]) => {
                 // Pre-filter the children for this kind; only render the section when it has cards.
                 const group = Array.from(queryElements(children, { "props.kind": kind }));

package/ui/docs/DocumentationPage.test.tsx

@@ -11,7 +11,7 @@ function doc(name: string, kind: string): DocumentationElement {
 describe("DocumentationPage", () => {
 	test("groups child symbols into kind-based sections, in order", () => {
 		const html = renderToStaticMarkup(
-			<DocumentationPage name="array">
+			<DocumentationPage path="/array" name="array">
 				{[doc("getThing", "function"), doc("Widget", "class"), doc("getOther", "function")]}
 			</DocumentationPage>,
 		);
@@ -23,7 +23,7 @@ describe("DocumentationPage", () => {
 
 	test("renders a section only for kinds that have children", () => {
 		const html = renderToStaticMarkup(
-			<DocumentationPage name="Store" kind="class">
+			<DocumentationPage path="/Store" name="Store" kind="class">
 				{[doc("get", "method"), doc("size", "property")]}
 			</DocumentationPage>,
 		);

package/ui/docs/DocumentationPage.tsx

@@ -11,7 +11,6 @@ import { Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
-import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 import { DocumentationKind } from "./DocumentationKind.js";
@@ -29,6 +28,11 @@ const KIND_SECTIONS: ReadonlyArray<readonly [kind: string, label: string]> = [
 	["property", "Properties"],
 ];
 
+interface DocumentationPageProps extends DocumentationElementProps {
+	/** Site-root-relative path of this page — threaded down so child cards build correct hrefs. */
+	readonly path: AbsolutePath;
+}
+
 /**
  * Page renderer for a `tree-documentation` element (also used for `tree-file` elements, whose props are a compatible subset).
  * - Renders title, signatures (one per overload), content, parameters, returns, throws, and examples.
@@ -36,6 +40,7 @@ const KIND_SECTIONS: ReadonlyArray<readonly [kind: string, label: string]> = [
  * - All sections are conditional — only render when they have entries.
  */
 export function DocumentationPage({
+	path,
 	title,
 	name,
 	kind,
@@ -47,9 +52,7 @@ export function DocumentationPage({
 	throws,
 	examples,
 	children,
-}: DocumentationElementProps): ReactNode {
-	const { url } = requireMeta();
-	const path = (url?.pathname ?? "/") as AbsolutePath;
+}: DocumentationPageProps): ReactNode {
 	return (
 		<Page title={title ?? name} description={description}>
 			<Title>

package/ui/docs/FilePage.d.ts

@@ -1,4 +1,10 @@
 import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
+import type { AbsolutePath } from "../../util/path.js";
+interface FilePageProps extends FileElementProps {
+    /** Site-root-relative path of this page — threaded down so child cards build correct hrefs. */
+    readonly path: AbsolutePath;
+}
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
-export declare function FilePage({ title, name, description, content, children }: FileElementProps): ReactNode;
+export declare function FilePage({ path, title, name, description, content, children }: FilePageProps): ReactNode;
+export {};

package/ui/docs/FilePage.js

@@ -2,12 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
 import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
-import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
-export function FilePage({ title, name, description, content, children }) {
-    const { url } = requireMeta();
-    const path = url?.pathname ?? "/";
+export function FilePage({ path, title, name, description, content, children }) {
     return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/FilePage.tsx

@@ -1,16 +1,19 @@
 import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
+import type { AbsolutePath } from "../../util/path.js";
 import { Prose } from "../block/Prose.js";
 import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
-import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 
+interface FilePageProps extends FileElementProps {
+	/** Site-root-relative path of this page — threaded down so child cards build correct hrefs. */
+	readonly path: AbsolutePath;
+}
+
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
-export function FilePage({ title, name, description, content, children }: FileElementProps): ReactNode {
-	const { url } = requireMeta();
-	const path = url?.pathname ?? "/";
+export function FilePage({ path, title, name, description, content, children }: FilePageProps): ReactNode {
 	return (
 		<Page title={title ?? name} description={description}>
 			<Title>{title ?? name}</Title>

package/ui/layout/SidebarLayout.d.ts

@@ -13,7 +13,7 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
- * - Use the `--sidebar-layout-width` and `--sidebar-layout-bg` custom properties to override defaults.
+ * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  */
 export declare function SidebarLayout({ sidebar, children, right }: SidebarLayoutProps): ReactElement;
 export { SIDEBAR_LAYOUT_CSS };

package/ui/layout/SidebarLayout.js

@@ -13,7 +13,7 @@ import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
  * - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
- * - Use the `--sidebar-layout-width` and `--sidebar-layout-bg` custom properties to override defaults.
+ * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  */
 export function SidebarLayout({ sidebar, children, right = false }) {
     const [open, setOpen] = useState(false);
@@ -24,7 +24,7 @@ export function SidebarLayout({ sidebar, children, right = false }) {
             setOpen(false);
     }, [href]);
     const sidebarEl = (_jsx("nav", { className: getClass(SIDEBAR_LAYOUT_CSS.sidebar, open && SIDEBAR_LAYOUT_CSS.open), children: sidebar }, "sidebar"));
-    const contentEl = (_jsxs("div", { className: getClass(LAYOUT_CSS.layout, SIDEBAR_LAYOUT_CSS.content), children: [_jsx("div", { className: SIDEBAR_LAYOUT_CSS.toggle, children: _jsx(Button, { fit: true, cyan: !open, orange: open, plain: true, title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: SIDEBAR_LAYOUT_CSS.contentInner, children: children })] }, "content"));
+    const contentEl = (_jsxs("div", { className: getClass(LAYOUT_CSS.layout, SIDEBAR_LAYOUT_CSS.content), children: [_jsx("div", { className: SIDEBAR_LAYOUT_CSS.toggle, children: _jsx(Button, { fit: true, title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: SIDEBAR_LAYOUT_CSS.contentInner, children: children })] }, "content"));
     const overlayEl = open && (_jsx("button", { type: "button", className: SIDEBAR_LAYOUT_CSS.overlay, "aria-label": "Close menu", onClick: () => setOpen(false) }, "overlay"));
     return (_jsx("main", { className: getClass(SIDEBAR_LAYOUT_CSS.main, LAYOUT_CSS.layout), children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] }));
 }

package/ui/layout/SidebarLayout.module.css

@@ -24,7 +24,7 @@
 	overscroll-behavior: contain;
 	padding: var(--space-normal);
 	background: var(--sidebar-layout-bg, var(--color-surface));
-	border-right: 1px solid var(--color-border);
+	border-right: var(--sidebar-layout-border, 1px) solid var(--sidebar-layout-color-border, var(--color-border));
 }
 
 .content {

package/ui/layout/SidebarLayout.tsx

@@ -21,7 +21,7 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
- * - Use the `--sidebar-layout-width` and `--sidebar-layout-bg` custom properties to override defaults.
+ * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  */
 export function SidebarLayout({ sidebar, children, right = false }: SidebarLayoutProps): ReactElement {
 	const [open, setOpen] = useState(false);
@@ -40,7 +40,7 @@ export function SidebarLayout({ sidebar, children, right = false }: SidebarLayou
 	const contentEl = (
 		<div key="content" className={getClass(LAYOUT_CSS.layout, SIDEBAR_LAYOUT_CSS.content)}>
 			<div className={SIDEBAR_LAYOUT_CSS.toggle}>
-				<Button fit cyan={!open} orange={open} plain title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
+				<Button fit title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
 					{open ? <XMarkIcon /> : <Bars3Icon />}
 				</Button>
 			</div>

package/ui/menu/Menu.module.css

@@ -11,7 +11,7 @@
 	font-family: var(--menu-font, var(--font-body));
 	font-size: var(--menu-size, var(--size-normal));
 	line-height: var(--menu-leading, var(--leading-normal));
-	color: var(--menu-color-text, var(--color-quiet));
+	color: var(--menu-color-text, var(--color-text));
 }
 
 .item {
@@ -41,15 +41,17 @@
 		outline-offset: 1px;
 	}
 	&[aria-current="page"] {
-		background: var(--menu-link-color-active-bg, var(--color-surface));
+		background: var(--menu-link-color-active-bg, var(--color-white));
 		color: var(--menu-link-color-active-text, var(--color-text));
 		font-weight: var(--menu-link-active-weight, var(--weight-strong));
 	}
 }
 
-/* "Proud" item — an ancestor of the active page; emphasised in colour and reveals its nested children. */
-.proud > .link {
+/* "Proud" item — an ancestor of the active page; emphasised with a strong weight, and reveals its nested children. */
+/* The active page is excluded so its own `[aria-current]` styling wins instead of the proud styling. */
+.proud > .link:not([aria-current="page"]) {
 	color: var(--menu-link-color-proud, var(--color-text));
+	font-weight: var(--menu-link-proud-weight, var(--weight-strong));
 }
 
 /* Submenu — Blockquote-style left border to signal hierarchy. */

package/ui/misc/MetaContext.d.ts

@@ -1,3 +1,4 @@
+import type { AbsolutePath } from "../../util/path.js";
 import { type URIParams } from "../../util/uri.js";
 import { type Meta, type PossibleMeta } from "../util/meta.js";
 import type { ChildProps } from "../util/props.js";
@@ -9,3 +10,11 @@ export interface MetaProps extends PossibleMeta, ChildProps {
 export declare function requireMeta(meta?: PossibleMeta): Meta;
 /** Get all URI/route params from the current meta context's URL. */
 export declare function requireMetaParams(): URIParams;
+/**
+ * Get the current page's path relative to the site root.
+ * - Strips the meta `root` (site base) prefix from the meta `url`, leaving a site-root-relative `AbsolutePath`.
+ * - Returns `undefined` when `url` or `root` is unset, or they sit on different origins — the path is then unknowable.
+ *
+ * @returns The site-root-relative path (e.g. `/util/array`), or `undefined` if it can't be determined.
+ */
+export declare function getMetaPath(): AbsolutePath | undefined;

package/ui/misc/MetaContext.js

@@ -1,5 +1,6 @@
 import { createContext, use } from "react";
 import { getURIParams } from "../../util/uri.js";
+import { matchURLPrefix } from "../../util/url.js";
 import { mergeMeta } from "../util/meta.js";
 /** Context to store the `Config` object. */
 export const MetaContext = createContext({});
@@ -13,3 +14,14 @@ export function requireMeta(meta) {
 export function requireMetaParams() {
     return getURIParams(requireMeta().url ?? {}, requireMetaParams);
 }
+/**
+ * Get the current page's path relative to the site root.
+ * - Strips the meta `root` (site base) prefix from the meta `url`, leaving a site-root-relative `AbsolutePath`.
+ * - Returns `undefined` when `url` or `root` is unset, or they sit on different origins — the path is then unknowable.
+ *
+ * @returns The site-root-relative path (e.g. `/util/array`), or `undefined` if it can't be determined.
+ */
+export function getMetaPath() {
+    const { url, root } = requireMeta();
+    return matchURLPrefix(url, root, getMetaPath);
+}

package/ui/misc/MetaContext.test.tsx

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { createMeta } from "../util/meta.js";
+import { getMetaPath, MetaContext } from "./MetaContext.js";
+
+/** Render `getMetaPath()` from inside a component so its `use(MetaContext)` call is valid. */
+function Probe(): ReactNode {
+	return getMetaPath() ?? "none";
+}
+
+describe("getMetaPath", () => {
+	test("returns the page path relative to the site root", () => {
+		const html = renderToStaticMarkup(
+			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./util/array" })}>
+				<Probe />
+			</MetaContext>,
+		);
+		expect(html).toBe("/util/array");
+	});
+
+	test("returns `/` when url and root resolve to the same location", () => {
+		const html = renderToStaticMarkup(
+			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./" })}>
+				<Probe />
+			</MetaContext>,
+		);
+		expect(html).toBe("/");
+	});
+
+	test("returns undefined when url or root is unset", () => {
+		expect(renderToStaticMarkup(<Probe />)).toBe("none");
+	});
+
+	test("returns undefined when url and root are on different origins", () => {
+		const html = renderToStaticMarkup(
+			<MetaContext value={createMeta({ root: "http://x.com/", url: "http://y.com/foo" })}>
+				<Probe />
+			</MetaContext>,
+		);
+		expect(html).toBe("none");
+	});
+});

package/ui/misc/MetaContext.tsx

@@ -1,5 +1,7 @@
 import { createContext, use } from "react";
+import type { AbsolutePath } from "../../util/path.js";
 import { getURIParams, type URIParams } from "../../util/uri.js";
+import { matchURLPrefix } from "../../util/url.js";
 import { type Meta, mergeMeta, type PossibleMeta } from "../util/meta.js";
 import type { ChildProps } from "../util/props.js";
 
@@ -19,3 +21,15 @@ export function requireMeta(meta?: PossibleMeta): Meta {
 export function requireMetaParams(): URIParams {
 	return getURIParams(requireMeta().url ?? {}, requireMetaParams);
 }
+
+/**
+ * Get the current page's path relative to the site root.
+ * - Strips the meta `root` (site base) prefix from the meta `url`, leaving a site-root-relative `AbsolutePath`.
+ * - Returns `undefined` when `url` or `root` is unset, or they sit on different origins — the path is then unknowable.
+ *
+ * @returns The site-root-relative path (e.g. `/util/array`), or `undefined` if it can't be determined.
+ */
+export function getMetaPath(): AbsolutePath | undefined {
+	const { url, root } = requireMeta();
+	return matchURLPrefix(url, root, getMetaPath);
+}

package/ui/misc/StatusIcon.module.css

@@ -1,5 +1,5 @@
 .icon {
-	flex: 0 0 fit-content;
+	flex: none;
 	border-radius: 999px;
 	width: var(--status-icon-size, 1lh);
 	height: var(--status-icon-size, 1lh);

package/ui/tree/TreePage.d.ts

@@ -1,10 +1,13 @@
 import type { ReactNode } from "react";
 import { type TreeElement } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
+/** Extras threaded through `TreePageMapper` to the page renderer — the site-root-relative path of the page. */
+interface TreePageExtras {
+    /** Site-root-relative URL path of the page being rendered. Each page forwards it to its child cards. */
+    readonly path: AbsolutePath;
+}
 /** Mapping + Mapper pair for tree pages — wrap children in `<TreePageMapping>` to override. */
-export declare const TreePageMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<unknown>>, TreePageMapper: import("react").FunctionComponent<{
-    readonly children?: import("../../util/element.js").Elements;
-}>;
+export declare const TreePageMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreePageExtras>>, TreePageMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreePageExtras>>;
 export interface TreePageProps {
     readonly path?: AbsolutePath;
     readonly tree: TreeElement;
@@ -13,7 +16,9 @@ export interface TreePageProps {
  * Resolve a URL path to a tree element and render it as a full page.
  * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
  * - `/` renders the root itself; deeper paths render the matching descendant.
+ * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
  * - Throws `NotFoundError` if no element matches at any level.
  * - To override the renderer for a specific element type, wrap in `<TreePageMapping mapping={…}>`.
  */
 export declare function TreePage({ path, tree }: TreePageProps): ReactNode;
+export {};

package/ui/tree/TreePage.js

@@ -16,6 +16,7 @@ export const [TreePageMapping, TreePageMapper] = createMapper({
  * Resolve a URL path to a tree element and render it as a full page.
  * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
  * - `/` renders the root itself; deeper paths render the matching descendant.
+ * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
  * - Throws `NotFoundError` if no element matches at any level.
  * - To override the renderer for a specific element type, wrap in `<TreePageMapping mapping={…}>`.
  */
@@ -24,5 +25,5 @@ export function TreePage({ path = "/", tree }) {
     const element = resolveElementPath(tree, segments);
     if (!element)
         throw new NotFoundError("Element not found", { received: path });
-    return _jsx(TreePageMapper, { children: element });
+    return _jsx(TreePageMapper, { path: path, children: element });
 }

package/ui/tree/TreePage.test.tsx

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { TreeElement } from "../../util/element.js";
+import { MetaContext } from "../misc/MetaContext.js";
+import { createMeta } from "../util/meta.js";
+import { TreePage } from "./TreePage.js";
+
+/** Minimal tree: root → `util` directory → `array` file. */
+const tree: TreeElement = {
+	type: "tree-directory",
+	key: "root",
+	props: {
+		name: "shelving",
+		children: [
+			{
+				type: "tree-directory",
+				key: "util",
+				props: { name: "util", children: [{ type: "tree-file", key: "array", props: { name: "array" } }] },
+			},
+		],
+	},
+};
+
+describe("TreePage", () => {
+	// When `APP_URL` has a subfolder, the page threads its site-root-relative path to child cards so hrefs include the subfolder exactly once.
+	test("card links include an APP_URL subfolder exactly once", () => {
+		const html = renderToStaticMarkup(
+			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./util" })}>
+				<TreePage path="/util" tree={tree} />
+			</MetaContext>,
+		);
+		expect(html).toContain('href="http://x.com/sub/util/array"');
+		expect(html).not.toContain("/sub/sub/");
+	});
+
+	test("root page card links include an APP_URL subfolder exactly once", () => {
+		const html = renderToStaticMarkup(
+			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./" })}>
+				<TreePage path="/" tree={tree} />
+			</MetaContext>,
+		);
+		expect(html).toContain('href="http://x.com/sub/util"');
+		expect(html).not.toContain("/sub/sub/");
+	});
+});

package/ui/tree/TreePage.tsx

@@ -7,8 +7,14 @@ import { DocumentationPage } from "../docs/DocumentationPage.js";
 import { FilePage } from "../docs/FilePage.js";
 import { createMapper } from "../misc/Mapper.js";
 
+/** Extras threaded through `TreePageMapper` to the page renderer — the site-root-relative path of the page. */
+interface TreePageExtras {
+	/** Site-root-relative URL path of the page being rendered. Each page forwards it to its child cards. */
+	readonly path: AbsolutePath;
+}
+
 /** Mapping + Mapper pair for tree pages — wrap children in `<TreePageMapping>` to override. */
-export const [TreePageMapping, TreePageMapper] = createMapper({
+export const [TreePageMapping, TreePageMapper] = createMapper<TreePageExtras>({
 	"tree-directory": DirectoryPage,
 	"tree-file": FilePage,
 	"tree-documentation": DocumentationPage,
@@ -23,6 +29,7 @@ export interface TreePageProps {
  * Resolve a URL path to a tree element and render it as a full page.
  * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
  * - `/` renders the root itself; deeper paths render the matching descendant.
+ * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
  * - Throws `NotFoundError` if no element matches at any level.
  * - To override the renderer for a specific element type, wrap in `<TreePageMapping mapping={…}>`.
  */
@@ -30,5 +37,5 @@ export function TreePage({ path = "/", tree }: TreePageProps): ReactNode {
 	const segments = splitPath(path);
 	const element = resolveElementPath(tree, segments);
 	if (!element) throw new NotFoundError("Element not found", { received: path });
-	return <TreePageMapper>{element}</TreePageMapper>;
+	return <TreePageMapper path={path}>{element}</TreePageMapper>;
 }