shelving 1.257.1 → 1.258.0

package/package.json

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

package/ui/docs/DocumentationApp.js

@@ -9,6 +9,6 @@ import { DocumentationSearchPage } from "./DocumentationSearchPage.js";
  */
 export function DocumentationApp({ tree, routes = {
     "/search": DocumentationSearchPage,
-}, sidebar = (_jsx(TreeSidebar, { tree: tree, children: _jsx(Menu, { children: _jsx(MenuItem, { href: "/search", children: "Search" }) }) })), ...meta }) {
+}, sidebar = (_jsx(TreeSidebar, { children: _jsx(Menu, { children: _jsx(MenuItem, { href: "/search", children: "Search" }) }) })), ...meta }) {
     return _jsx(TreeApp, { tree: tree, routes: routes, sidebar: sidebar, ...meta });
 }

package/ui/docs/DocumentationApp.tsx

@@ -14,7 +14,7 @@ export function DocumentationApp({
 		"/search": DocumentationSearchPage,
 	},
 	sidebar = (
-		<TreeSidebar tree={tree}>
+		<TreeSidebar>
 			<Menu>
 				<MenuItem href="/search">Search</MenuItem>
 			</Menu>

package/ui/misc/Mapper.d.ts

@@ -4,32 +4,31 @@ import type { ChildProps } from "../util/props.js";
 /**
  * Dispatch table from a `JSX.IntrinsicElements` key to a renderer component.
  * - Each entry is optional — unmapped elements fall through and render as themselves (e.g. an unmapped `<tree-foo>` appears as a raw `<tree-foo>` HTML element).
- * - Per-entry component receives `JSX.IntrinsicElements[K] & E` — the declared props for that element type, plus any extra props `E` the mapper is configured to thread through.
+ * - Per-entry component receives `JSX.IntrinsicElements[K]` — the declared props for that element type.
  *
  * @see https://shelving.cc/ui/Mapping
  */
-export type Mapping<E = unknown> = {
-    [K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K] & E>;
+export type Mapping = {
+    [K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K]>;
 };
 /**
  * Props for the `Mapping` component returned by `createMapper()`.
  *
  * @see https://shelving.cc/ui/MappingProps
  */
-export interface MappingProps<E = unknown> extends ChildProps {
+export interface MappingProps extends ChildProps {
     /** Mapping entries that extend or override the inherited mapping inside this subtree. */
-    readonly mapping: Mapping<E>;
+    readonly mapping: Mapping;
 }
 /**
  * Props for the `Mapper` component returned by `createMapper()`.
  * - `children` holds the pre-walked elements to dispatch.
- * - All other props are spread onto every mapped child as additional props (`E`).
  *
  * @see https://shelving.cc/ui/MapperProps
  */
-export type MapperProps<E = unknown> = E & {
+export interface MapperProps {
     readonly children?: Elements;
-};
+}
 /**
  * Create a `[Mapping, Mapper]` pair of components backed by their own private React context.
  *
@@ -38,24 +37,21 @@ export type MapperProps<E = unknown> = E & {
  *
  * Each call creates its own context — independent mappers don't interfere with each other.
  *
- * @typeParam E The shape of any extra props the mapper threads through to every dispatched child. Defaults to `unknown` (no extras).
  * @param defaults The initial mapping of element types to renderer components.
  * @returns A `[Mapping, Mapper]` tuple of components sharing a private context.
  *
  * @example
- * // No extras:
  * const [TreeCardMapping, TreeCardMapper] = createMapper({
  *   "tree-element": TreeCard,
  * });
  * <TreeCardMapper>{walkElements(children)}</TreeCardMapper>
  *
  * @example
- * // With extras (`path` threaded into every dispatched child):
- * const [TreeMenuMapping, TreeMenuMapper] = createMapper<{ path?: AbsolutePath }>({
- *   "tree-element": TreeMenuItem,
- * });
- * <TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+ * // Override one entry inside a subtree:
+ * <TreeCardMapping mapping={{ "tree-element": SpecialTreeCard }}>
+ *   <TreeCardMapper>{walkElements(children)}</TreeCardMapper>
+ * </TreeCardMapping>
  *
  * @see https://shelving.cc/ui/createMapper
  */
-export declare function createMapper<E = unknown>(defaults?: Mapping<E>): [Mapping: FunctionComponent<MappingProps<E>>, Mapper: FunctionComponent<MapperProps<E>>];
+export declare function createMapper(defaults?: Mapping): [Mapping: FunctionComponent<MappingProps>, Mapper: FunctionComponent<MapperProps>];

package/ui/misc/Mapper.js

@@ -9,23 +9,20 @@ import { walkElements } from "../../util/element.js";
  *
  * Each call creates its own context — independent mappers don't interfere with each other.
  *
- * @typeParam E The shape of any extra props the mapper threads through to every dispatched child. Defaults to `unknown` (no extras).
  * @param defaults The initial mapping of element types to renderer components.
  * @returns A `[Mapping, Mapper]` tuple of components sharing a private context.
  *
  * @example
- * // No extras:
  * const [TreeCardMapping, TreeCardMapper] = createMapper({
  *   "tree-element": TreeCard,
  * });
  * <TreeCardMapper>{walkElements(children)}</TreeCardMapper>
  *
  * @example
- * // With extras (`path` threaded into every dispatched child):
- * const [TreeMenuMapping, TreeMenuMapper] = createMapper<{ path?: AbsolutePath }>({
- *   "tree-element": TreeMenuItem,
- * });
- * <TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+ * // Override one entry inside a subtree:
+ * <TreeCardMapping mapping={{ "tree-element": SpecialTreeCard }}>
+ *   <TreeCardMapper>{walkElements(children)}</TreeCardMapper>
+ * </TreeCardMapping>
  *
  * @see https://shelving.cc/ui/createMapper
  */
@@ -35,7 +32,7 @@ export function createMapper(defaults = {}) {
         const inherited = use(Context);
         return _jsx(Context, { value: { ...inherited, ...mapping }, children: children });
     }
-    function Mapper({ children, ...extras }) {
+    function Mapper({ children }) {
         const mapping = use(Context);
         const items = [];
         for (const element of walkElements(children)) {
@@ -45,7 +42,7 @@ export function createMapper(defaults = {}) {
             }
             const Component = mapping[element.type];
             if (Component) {
-                items.push(_jsx(Component, { ...extras, ...element.props }, element.key));
+                items.push(_jsx(Component, { ...element.props }, element.key));
             }
             else {
                 items.push(element);

package/ui/misc/Mapper.md

@@ -6,7 +6,6 @@ Creates a `[Mapping, Mapper]` component pair backed by a private React context.
 
 - Each call to `createMapper()` creates its own context — independent mappers don't interfere with each other.
 - Unmapped element types fall through and render as themselves (e.g. an unmapped `<tree-foo>` appears as a raw `<tree-foo>` element).
-- Any extra props passed to `Mapper` (the type parameter `E`) are spread onto every dispatched child, so you can thread shared context like a `path` into each renderer.
 
 ## Usage
 
@@ -25,12 +24,3 @@ const [TreeMapping, TreeMapper] = createMapper({
   <TreeMapper>{walkElements(children)}</TreeMapper>
 </TreeMapping>
 ```
-
-```tsx
-// With extra props threaded into every dispatched child.
-const [TreeMenuMapping, TreeMenuMapper] = createMapper<{ path?: AbsolutePath }>({
-  "tree-element": TreeMenuItem,
-});
-
-<TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
-```

package/ui/misc/Mapper.tsx

@@ -6,12 +6,12 @@ import type { ChildProps } from "../util/props.js";
 /**
  * Dispatch table from a `JSX.IntrinsicElements` key to a renderer component.
  * - Each entry is optional — unmapped elements fall through and render as themselves (e.g. an unmapped `<tree-foo>` appears as a raw `<tree-foo>` HTML element).
- * - Per-entry component receives `JSX.IntrinsicElements[K] & E` — the declared props for that element type, plus any extra props `E` the mapper is configured to thread through.
+ * - Per-entry component receives `JSX.IntrinsicElements[K]` — the declared props for that element type.
  *
  * @see https://shelving.cc/ui/Mapping
  */
-export type Mapping<E = unknown> = {
-	[K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K] & E>;
+export type Mapping = {
+	[K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K]>;
 };
 
 /**
@@ -19,21 +19,20 @@ export type Mapping<E = unknown> = {
  *
  * @see https://shelving.cc/ui/MappingProps
  */
-export interface MappingProps<E = unknown> extends ChildProps {
+export interface MappingProps extends ChildProps {
 	/** Mapping entries that extend or override the inherited mapping inside this subtree. */
-	readonly mapping: Mapping<E>;
+	readonly mapping: Mapping;
 }
 
 /**
  * Props for the `Mapper` component returned by `createMapper()`.
  * - `children` holds the pre-walked elements to dispatch.
- * - All other props are spread onto every mapped child as additional props (`E`).
  *
  * @see https://shelving.cc/ui/MapperProps
  */
-export type MapperProps<E = unknown> = E & {
+export interface MapperProps {
 	readonly children?: Elements;
-};
+}
 
 // Indexing the heterogeneous `Mapping` by an arbitrary string is unsafe by design — per-key value types diverge.
 // biome-ignore lint/suspicious/noExplicitAny: Each mapping value is a `ComponentType<P>` with its own `P`; we accept `any` for dispatch.
@@ -47,37 +46,32 @@ type AnyMapping = Record<string, ComponentType<any> | undefined>;
  *
  * Each call creates its own context — independent mappers don't interfere with each other.
  *
- * @typeParam E The shape of any extra props the mapper threads through to every dispatched child. Defaults to `unknown` (no extras).
  * @param defaults The initial mapping of element types to renderer components.
  * @returns A `[Mapping, Mapper]` tuple of components sharing a private context.
  *
  * @example
- * // No extras:
  * const [TreeCardMapping, TreeCardMapper] = createMapper({
  *   "tree-element": TreeCard,
  * });
  * <TreeCardMapper>{walkElements(children)}</TreeCardMapper>
  *
  * @example
- * // With extras (`path` threaded into every dispatched child):
- * const [TreeMenuMapping, TreeMenuMapper] = createMapper<{ path?: AbsolutePath }>({
- *   "tree-element": TreeMenuItem,
- * });
- * <TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+ * // Override one entry inside a subtree:
+ * <TreeCardMapping mapping={{ "tree-element": SpecialTreeCard }}>
+ *   <TreeCardMapper>{walkElements(children)}</TreeCardMapper>
+ * </TreeCardMapping>
  *
  * @see https://shelving.cc/ui/createMapper
  */
-export function createMapper<E = unknown>(
-	defaults: Mapping<E> = {},
-): [Mapping: FunctionComponent<MappingProps<E>>, Mapper: FunctionComponent<MapperProps<E>>] {
+export function createMapper(defaults: Mapping = {}): [Mapping: FunctionComponent<MappingProps>, Mapper: FunctionComponent<MapperProps>] {
 	const Context = createContext<AnyMapping>(defaults);
 
-	function Mapping({ mapping, children }: MappingProps<E>): ReactNode {
+	function Mapping({ mapping, children }: MappingProps): ReactNode {
 		const inherited = use(Context);
 		return <Context value={{ ...inherited, ...mapping }}>{children}</Context>;
 	}
 
-	function Mapper({ children, ...extras }: MapperProps<E>): ReactNode {
+	function Mapper({ children }: MapperProps): ReactNode {
 		const mapping = use(Context);
 		const items: ReactNode[] = [];
 		for (const element of walkElements(children)) {
@@ -87,7 +81,7 @@ export function createMapper<E = unknown>(
 			}
 			const Component = mapping[element.type];
 			if (Component) {
-				items.push(<Component key={element.key} {...extras} {...element.props} />);
+				items.push(<Component key={element.key} {...element.props} />);
 			} else {
 				items.push(element);
 			}

package/ui/tree/TreeApp.d.ts

@@ -22,6 +22,7 @@ export interface TreeAppProps extends PossibleMeta {
  * Top-level app component for a tree-based documentation site.
  *
  * - Wraps `<App>` with error catching and a sidebar layout.
+ * - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.

package/ui/tree/TreeApp.js

@@ -4,12 +4,14 @@ import { SidebarLayout } from "../layout/SidebarLayout.js";
 import { PageCatcher } from "../misc/Catcher.js";
 import { Navigation } from "../router/Navigation.js";
 import { Router } from "../router/Router.js";
+import { TreeProvider } from "./TreeContext.js";
 import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 /**
  * Top-level app component for a tree-based documentation site.
  *
  * - Wraps `<App>` with error catching and a sidebar layout.
+ * - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
@@ -20,7 +22,7 @@ import { TreeSidebar } from "./TreeSidebar.js";
  * @example <TreeApp tree={tree} title="Docs" />
  * @see https://shelving.cc/ui/TreeApp
  */
-export function TreeApp({ tree, routes, sidebar = _jsx(TreeSidebar, { tree: tree }), ...meta }) {
+export function TreeApp({ tree, routes, sidebar = _jsx(TreeSidebar, {}), ...meta }) {
     const fallback = routes && _jsx(Router, { routes: routes });
-    return (_jsx(App, { ...meta, children: _jsx(Navigation, { children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(TreeRouter, { tree: tree, fallback: fallback }) }) }) }) }));
+    return (_jsx(App, { ...meta, children: _jsx(Navigation, { children: _jsx(PageCatcher, { children: _jsx(TreeProvider, { tree: tree, children: _jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(TreeRouter, { fallback: fallback }) }) }) }) }) }));
 }

package/ui/tree/TreeApp.tsx

@@ -7,6 +7,7 @@ import { Navigation } from "../router/Navigation.js";
 import { Router } from "../router/Router.js";
 import type { Routes } from "../router/Routes.js";
 import type { PossibleMeta } from "../util/index.js";
+import { TreeProvider } from "./TreeContext.js";
 import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 
@@ -31,6 +32,7 @@ export interface TreeAppProps extends PossibleMeta {
  * Top-level app component for a tree-based documentation site.
  *
  * - Wraps `<App>` with error catching and a sidebar layout.
+ * - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
@@ -41,15 +43,17 @@ export interface TreeAppProps extends PossibleMeta {
  * @example <TreeApp tree={tree} title="Docs" />
  * @see https://shelving.cc/ui/TreeApp
  */
-export function TreeApp({ tree, routes, sidebar = <TreeSidebar tree={tree} />, ...meta }: TreeAppProps): ReactElement {
+export function TreeApp({ tree, routes, sidebar = <TreeSidebar />, ...meta }: TreeAppProps): ReactElement {
 	const fallback = routes && <Router routes={routes} />;
 	return (
 		<App {...meta}>
 			<Navigation>
 				<PageCatcher>
-					<SidebarLayout sidebar={sidebar}>
-						<TreeRouter tree={tree} fallback={fallback} />
-					</SidebarLayout>
+					<TreeProvider tree={tree}>
+						<SidebarLayout sidebar={sidebar}>
+							<TreeRouter fallback={fallback} />
+						</SidebarLayout>
+					</TreeProvider>
 				</PageCatcher>
 			</Navigation>
 		</App>

package/ui/tree/TreeCards.d.ts

@@ -5,9 +5,7 @@ import type { TreeElements } from "../../util/tree.js";
  *
  * @see https://shelving.cc/ui/TreeCardMapping
  */
-export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<unknown>>, TreeCardMapper: import("react").FunctionComponent<{
-    readonly children?: import("../../util/element.js").Elements;
-}>;
+export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeCardMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
 /**
  * Props for the `TreeCards` component — the tree elements to render as cards.
  *

package/ui/tree/TreeMenu.d.ts

@@ -1,6 +1,5 @@
 import type { ReactNode } from "react";
 import { type Element } from "../../util/element.js";
-import { type AbsolutePath } from "../../util/path.js";
 import type { TreeElement, TreeElementProps } from "../../util/tree.js";
 /**
  * Match an element that should appear in the sidebar menu.
@@ -14,52 +13,45 @@ import type { TreeElement, TreeElementProps } from "../../util/tree.js";
  * @see https://shelving.cc/ui/matchMenuElement
  */
 export declare function matchMenuElement(element: Element): boolean;
-/** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
-interface TreeMenuExtras {
-    /** URL path of the parent element. Each item appends its own `name` to compute its own path. Defaults to `/`. */
-    readonly path: AbsolutePath;
-}
 /**
  * Default menu item renderer for any `tree-*` element.
  *
- * - Computes its own URL path by appending its `name` to the parent's `path`.
+ * - Links straight to the element's own canonical `path` (stamped by `flattenTree()`), so the menu must be fed the flattened tree's elements.
  * - Passes both the label and the nested `<TreeMenuMapper>` to `<MenuItem>`; `<MenuItem>` itself decides whether to reveal the nested submenu based on the current URL.
  *
- * @param props The tree element props plus the parent's `path`.
+ * @param props The tree element props — `path` is the canonical URL to link to.
  * @returns A `<MenuItem>` for the element, with a nested `<Menu>` when it has menu-eligible children.
  * @kind component
- * @example <TreeMenuItem {...element.props} path="/" />
+ * @example <TreeMenuItem {...element.props} />
  * @see https://shelving.cc/ui/TreeMenuItem
  */
-export declare function TreeMenuItem({ path, name, title, children }: TreeElementProps & TreeMenuExtras): ReactNode;
+export declare function TreeMenuItem({ path, name, title, children }: TreeElementProps): ReactNode;
 /**
  * Mapping + Mapper pair for the menu — wrap children in `<TreeMenuMapping>` to override the per-type menu-item renderers.
  *
  * @see https://shelving.cc/ui/TreeMenuMapping
  */
-export declare const TreeMenuMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreeMenuExtras>>, TreeMenuMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreeMenuExtras>>;
+export declare const TreeMenuMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeMenuMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
 /**
  * Props for the `TreeMenu` component — the root tree element plus its URL path.
  *
  * @see https://shelving.cc/ui/TreeMenuProps
  */
 export interface TreeMenuProps {
-    /** Root element whose children become the navigation links. */
+    /** Root element whose children become the navigation links. Must be a flattened element (from `useTreeMap()`) so each child carries its canonical `path`. */
     readonly tree: TreeElement;
-    /** URL path of the root — children get `path + their.name`. Defaults to `/`. */
-    readonly path?: AbsolutePath | undefined;
 }
 /**
  * Sidebar navigation menu built from the children of a root tree element.
  *
- * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`).
+ * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`), linking to each child's stamped `path`.
+ * - Pass a flattened element (e.g. `useTreeMap().get("/")`) so its children carry their canonical `path`.
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  *
  * @kind component
  * @returns A `<Menu>` of navigation links to the root's children.
- * @example <TreeMenu tree={tree} />
+ * @example <TreeMenu tree={useTreeMap().get("/")} />
  * @see https://shelving.cc/ui/TreeMenu
  */
-export declare function TreeMenu({ path, tree }: TreeMenuProps): ReactNode;
-export {};
+export declare function TreeMenu({ tree }: TreeMenuProps): ReactNode;

package/ui/tree/TreeMenu.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { filterElements } from "../../util/element.js";
-import { joinPath } from "../../util/path.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
 import { createMapper } from "../misc/Mapper.js";
 /**
@@ -25,19 +24,18 @@ export function matchMenuElement(element) {
 /**
  * Default menu item renderer for any `tree-*` element.
  *
- * - Computes its own URL path by appending its `name` to the parent's `path`.
+ * - Links straight to the element's own canonical `path` (stamped by `flattenTree()`), so the menu must be fed the flattened tree's elements.
  * - Passes both the label and the nested `<TreeMenuMapper>` to `<MenuItem>`; `<MenuItem>` itself decides whether to reveal the nested submenu based on the current URL.
  *
- * @param props The tree element props plus the parent's `path`.
+ * @param props The tree element props — `path` is the canonical URL to link to.
  * @returns A `<MenuItem>` for the element, with a nested `<Menu>` when it has menu-eligible children.
  * @kind component
- * @example <TreeMenuItem {...element.props} path="/" />
+ * @example <TreeMenuItem {...element.props} />
  * @see https://shelving.cc/ui/TreeMenuItem
  */
-export function TreeMenuItem({ path = "/", name, title, children }) {
-    const href = joinPath(path, name);
+export function TreeMenuItem({ path, name, title, children }) {
     const submenu = Array.from(filterElements(children, matchMenuElement));
-    return (_jsxs(MenuItem, { href: href, children: [title ?? name, submenu.length ? (_jsx(Menu, { children: _jsx(TreeMenuMapper, { path: href, children: submenu }) })) : null] }));
+    return (_jsxs(MenuItem, { href: path, children: [title ?? name, submenu.length ? (_jsx(Menu, { children: _jsx(TreeMenuMapper, { children: submenu }) })) : null] }));
 }
 /**
  * Mapping + Mapper pair for the menu — wrap children in `<TreeMenuMapping>` to override the per-type menu-item renderers.
@@ -51,15 +49,16 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
 /**
  * Sidebar navigation menu built from the children of a root tree element.
  *
- * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`).
+ * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`), linking to each child's stamped `path`.
+ * - Pass a flattened element (e.g. `useTreeMap().get("/")`) so its children carry their canonical `path`.
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  *
  * @kind component
  * @returns A `<Menu>` of navigation links to the root's children.
- * @example <TreeMenu tree={tree} />
+ * @example <TreeMenu tree={useTreeMap().get("/")} />
  * @see https://shelving.cc/ui/TreeMenu
  */
-export function TreeMenu({ path = "/", tree }) {
-    return (_jsx(Menu, { children: _jsx(TreeMenuMapper, { path: path, children: filterElements(tree.props.children, matchMenuElement) }) }));
+export function TreeMenu({ tree }) {
+    return (_jsx(Menu, { children: _jsx(TreeMenuMapper, { children: filterElements(tree.props.children, matchMenuElement) }) }));
 }

package/ui/tree/TreeMenu.md

@@ -5,7 +5,7 @@ A sidebar navigation menu built from the children of a root tree element. Each c
 **Things to know:**
 
 - Only directories and files appear, plus documentation symbols of `kind: "module"` — functions, classes, methods, properties, etc. are kept off the navigation (they still get their own pages via `<TreeApp>`).
-- Each item computes its own href by appending its `name` to the parent `path` (defaulting to `/`).
+- Each item links straight to its element's own canonical `path` (stamped by `flattenTree()`), so feed it a flattened element — e.g. `useTreeMap().get("/")` — rather than a raw extracted tree.
 - It is a `[Mapping, Mapper]` pair: wrap any subtree in `<TreeMenuMapping mapping={…}>` to swap the per-type menu-item renderer without touching the rest of the site. `<TreeSidebar>` shares this same mapper.
 - Use it directly for finer layout control; otherwise `<TreeApp>` wires a `<TreeSidebar>` (a home link plus this menu) for you.
 
@@ -13,9 +13,10 @@ A sidebar navigation menu built from the children of a root tree element. Each c
 
 ```tsx
 import { TreeMenu } from "shelving/ui";
+import { useTreeMap } from "shelving/ui";
 
-// Just the navigation menu from a subtree's children.
-<TreeMenu tree={section} path="/docs" />
+// Just the navigation menu from the flattened root's children.
+<TreeMenu tree={useTreeMap().get("/")} />
 ```
 
 Override the menu-item renderer for one element type:

package/ui/tree/TreeMenu.tsx

@@ -1,6 +1,5 @@
 import type { ReactNode } from "react";
 import { type Element, filterElements } from "../../util/element.js";
-import { type AbsolutePath, joinPath } from "../../util/path.js";
 import type { TreeElement, TreeElementProps } from "../../util/tree.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
 import { createMapper } from "../misc/Mapper.js";
@@ -23,33 +22,26 @@ export function matchMenuElement(element: Element): boolean {
 	return false;
 }
 
-/** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
-interface TreeMenuExtras {
-	/** URL path of the parent element. Each item appends its own `name` to compute its own path. Defaults to `/`. */
-	readonly path: AbsolutePath;
-}
-
 /**
  * Default menu item renderer for any `tree-*` element.
  *
- * - Computes its own URL path by appending its `name` to the parent's `path`.
+ * - Links straight to the element's own canonical `path` (stamped by `flattenTree()`), so the menu must be fed the flattened tree's elements.
  * - Passes both the label and the nested `<TreeMenuMapper>` to `<MenuItem>`; `<MenuItem>` itself decides whether to reveal the nested submenu based on the current URL.
  *
- * @param props The tree element props plus the parent's `path`.
+ * @param props The tree element props — `path` is the canonical URL to link to.
  * @returns A `<MenuItem>` for the element, with a nested `<Menu>` when it has menu-eligible children.
  * @kind component
- * @example <TreeMenuItem {...element.props} path="/" />
+ * @example <TreeMenuItem {...element.props} />
  * @see https://shelving.cc/ui/TreeMenuItem
  */
-export function TreeMenuItem({ path = "/", name, title, children }: TreeElementProps & TreeMenuExtras): ReactNode {
-	const href = joinPath(path, name);
+export function TreeMenuItem({ path, name, title, children }: TreeElementProps): ReactNode {
 	const submenu = Array.from(filterElements(children, matchMenuElement));
 	return (
-		<MenuItem href={href}>
+		<MenuItem href={path}>
 			{title ?? name}
 			{submenu.length ? (
 				<Menu>
-					<TreeMenuMapper path={href}>{submenu}</TreeMenuMapper>
+					<TreeMenuMapper>{submenu}</TreeMenuMapper>
 				</Menu>
 			) : null}
 		</MenuItem>
@@ -61,7 +53,7 @@ export function TreeMenuItem({ path = "/", name, title, children }: TreeElementP
  *
  * @see https://shelving.cc/ui/TreeMenuMapping
  */
-export const [TreeMenuMapping, TreeMenuMapper] = createMapper<TreeMenuExtras>({
+export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
 	"tree-element": TreeMenuItem,
 	"tree-documentation": TreeMenuItem,
 });
@@ -72,28 +64,27 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper<TreeMenuExtras>({
  * @see https://shelving.cc/ui/TreeMenuProps
  */
 export interface TreeMenuProps {
-	/** Root element whose children become the navigation links. */
+	/** Root element whose children become the navigation links. Must be a flattened element (from `useTreeMap()`) so each child carries its canonical `path`. */
 	readonly tree: TreeElement;
-	/** URL path of the root — children get `path + their.name`. Defaults to `/`. */
-	readonly path?: AbsolutePath | undefined;
 }
 
 /**
  * Sidebar navigation menu built from the children of a root tree element.
  *
- * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`).
+ * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`), linking to each child's stamped `path`.
+ * - Pass a flattened element (e.g. `useTreeMap().get("/")`) so its children carry their canonical `path`.
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  *
  * @kind component
  * @returns A `<Menu>` of navigation links to the root's children.
- * @example <TreeMenu tree={tree} />
+ * @example <TreeMenu tree={useTreeMap().get("/")} />
  * @see https://shelving.cc/ui/TreeMenu
  */
-export function TreeMenu({ path = "/", tree }: TreeMenuProps): ReactNode {
+export function TreeMenu({ tree }: TreeMenuProps): ReactNode {
 	return (
 		<Menu>
-			<TreeMenuMapper path={path}>{filterElements(tree.props.children, matchMenuElement)}</TreeMenuMapper>
+			<TreeMenuMapper>{filterElements(tree.props.children, matchMenuElement)}</TreeMenuMapper>
 		</Menu>
 	);
 }

package/ui/tree/TreeRouter.d.ts

@@ -1,22 +1,17 @@
 import type { ReactElement, ReactNode } from "react";
-import type { TreeElement } from "../../util/tree.js";
 import type { PossibleMeta } from "../util/index.js";
 /**
  * Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override the per-type page renderers.
  *
  * @see https://shelving.cc/ui/TreeRouterMapping
  */
-export declare const TreeRouterMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<unknown>>, TreeRouterMapper: import("react").FunctionComponent<{
-    readonly children?: import("../../index.js").Elements;
-}>;
+export declare const TreeRouterMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeRouterMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
 /**
  * Props for the `TreeRouter` component — the tree to route plus an optional fallback and app meta.
  *
  * @see https://shelving.cc/ui/TreeRouterProps
  */
 export interface TreeRouterProps extends PossibleMeta {
-    /** The tree of elements to match routes for. */
-    readonly tree: TreeElement;
     /**
      * Optional fallback element.
      * - Explicit `null` means fallback to nothing (router will not throw `NotFoundError`).
@@ -26,7 +21,7 @@ export interface TreeRouterProps extends PossibleMeta {
 /**
  * Resolve a URL path to a tree element and render it as a full page.
  *
- * - Flattens the tree once (via `<TreeProvider>`) into a `path` → element map, then resolves the current URL with a single `map.get(path)`.
+ * - Reads the flattened `path` → element map from the surrounding `<TreeProvider>` (`useTreeMap()`), then resolves the current URL with a single `map.get(path)`.
  * - `/` renders the root itself; deeper paths render the matching descendant (composite module names like `/util/string` resolve for free — they're whole keys in the map).
  * - The resolved element is already stamped with its canonical `path`, so the page and its cards link straight to their own paths — nothing needs threading.
  * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
@@ -34,7 +29,7 @@ export interface TreeRouterProps extends PossibleMeta {
  * @returns The resolved element rendered as a page, or the `fallback`.
  * @throws `NotFoundError` When no element matches the URL and no `fallback` is given.
  * @kind component
- * @example <TreeRouter tree={tree} />
+ * @example <TreeProvider tree={tree}><TreeRouter /></TreeProvider>
  * @see https://shelving.cc/ui/TreeRouter
  */
-export declare function TreeRouter({ tree, fallback, ...meta }: TreeRouterProps): ReactNode;
+export declare function TreeRouter({ fallback, ...meta }: TreeRouterProps): ReactNode;

package/ui/tree/TreeRouter.js

@@ -3,7 +3,7 @@ import { NotFoundError } from "../../error/RequestError.js";
 import { DocumentationPage } from "../docs/DocumentationPage.js";
 import { createMapper } from "../misc/Mapper.js";
 import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
-import { TreeProvider, useTreeMap } from "./TreeContext.js";
+import { useTreeMap } from "./TreeContext.js";
 import { TreePage } from "./TreePage.js";
 /**
  * Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override the per-type page renderers.
@@ -17,7 +17,7 @@ export const [TreeRouterMapping, TreeRouterMapper] = createMapper({
 /**
  * Resolve a URL path to a tree element and render it as a full page.
  *
- * - Flattens the tree once (via `<TreeProvider>`) into a `path` → element map, then resolves the current URL with a single `map.get(path)`.
+ * - Reads the flattened `path` → element map from the surrounding `<TreeProvider>` (`useTreeMap()`), then resolves the current URL with a single `map.get(path)`.
  * - `/` renders the root itself; deeper paths render the matching descendant (composite module names like `/util/string` resolve for free — they're whole keys in the map).
  * - The resolved element is already stamped with its canonical `path`, so the page and its cards link straight to their own paths — nothing needs threading.
  * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
@@ -25,13 +25,12 @@ export const [TreeRouterMapping, TreeRouterMapper] = createMapper({
  * @returns The resolved element rendered as a page, or the `fallback`.
  * @throws `NotFoundError` When no element matches the URL and no `fallback` is given.
  * @kind component
- * @example <TreeRouter tree={tree} />
+ * @example <TreeProvider tree={tree}><TreeRouter /></TreeProvider>
  * @see https://shelving.cc/ui/TreeRouter
  */
-export function TreeRouter({ tree, fallback, ...meta }) {
+export function TreeRouter({ fallback, ...meta }) {
     const { path, ...combined } = requireMetaURL(meta);
-    // `<TreeProvider>` flattens the tree (memoised) and exposes it as a lookup map so descendants — the route resolver below, plus `<TreeButton>` / breadcrumbs — all resolve against the one map.
-    return (_jsx(MetaContext, { value: combined, children: _jsx(TreeProvider, { tree: tree, children: _jsx(TreeRoute, { path: path, fallback: fallback }) }) }));
+    return (_jsx(MetaContext, { value: combined, children: _jsx(TreeRoute, { path: path, fallback: fallback }) }));
 }
 /** Resolve the current URL `path` to a tree element via the flattened map and render it; otherwise fall back, or throw `NotFoundError`. */
 function TreeRoute({ path, fallback }) {

package/ui/tree/TreeRouter.test.tsx

@@ -3,6 +3,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import type { TreeElement } from "../../util/tree.js";
 import { MetaContext } from "../misc/MetaContext.js";
 import { createMeta } from "../util/meta.js";
+import { TreeProvider } from "./TreeContext.js";
 import { TreeRouter } from "./TreeRouter.js";
 
 /** Minimal tree: root → `util` directory → `array` file. */
@@ -26,7 +27,9 @@ describe("TreeRouter", () => {
 	test("card links include an APP_URL subfolder exactly once", () => {
 		const html = renderToStaticMarkup(
 			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./util" })}>
-				<TreeRouter tree={tree} />
+				<TreeProvider tree={tree}>
+					<TreeRouter />
+				</TreeProvider>
 			</MetaContext>,
 		);
 		expect(html).toContain('href="http://x.com/sub/util/array"');
@@ -36,7 +39,9 @@ describe("TreeRouter", () => {
 	test("root page card links include an APP_URL subfolder exactly once", () => {
 		const html = renderToStaticMarkup(
 			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./" })}>
-				<TreeRouter tree={tree} />
+				<TreeProvider tree={tree}>
+					<TreeRouter />
+				</TreeProvider>
 			</MetaContext>,
 		);
 		expect(html).toContain('href="http://x.com/sub/util"');

package/ui/tree/TreeRouter.tsx

@@ -1,12 +1,11 @@
 import type { ReactElement, ReactNode } from "react";
 import { NotFoundError } from "../../error/RequestError.js";
 import type { AbsolutePath } from "../../util/path.js";
-import type { TreeElement } from "../../util/tree.js";
 import { DocumentationPage } from "../docs/DocumentationPage.js";
 import { createMapper } from "../misc/Mapper.js";
 import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
 import type { PossibleMeta } from "../util/index.js";
-import { TreeProvider, useTreeMap } from "./TreeContext.js";
+import { useTreeMap } from "./TreeContext.js";
 import { TreePage } from "./TreePage.js";
 
 /**
@@ -25,9 +24,6 @@ export const [TreeRouterMapping, TreeRouterMapper] = createMapper({
  * @see https://shelving.cc/ui/TreeRouterProps
  */
 export interface TreeRouterProps extends PossibleMeta {
-	/** The tree of elements to match routes for. */
-	readonly tree: TreeElement;
-
 	/**
 	 * Optional fallback element.
 	 * - Explicit `null` means fallback to nothing (router will not throw `NotFoundError`).
@@ -38,7 +34,7 @@ export interface TreeRouterProps extends PossibleMeta {
 /**
  * Resolve a URL path to a tree element and render it as a full page.
  *
- * - Flattens the tree once (via `<TreeProvider>`) into a `path` → element map, then resolves the current URL with a single `map.get(path)`.
+ * - Reads the flattened `path` → element map from the surrounding `<TreeProvider>` (`useTreeMap()`), then resolves the current URL with a single `map.get(path)`.
  * - `/` renders the root itself; deeper paths render the matching descendant (composite module names like `/util/string` resolve for free — they're whole keys in the map).
  * - The resolved element is already stamped with its canonical `path`, so the page and its cards link straight to their own paths — nothing needs threading.
  * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
@@ -46,17 +42,14 @@ export interface TreeRouterProps extends PossibleMeta {
  * @returns The resolved element rendered as a page, or the `fallback`.
  * @throws `NotFoundError` When no element matches the URL and no `fallback` is given.
  * @kind component
- * @example <TreeRouter tree={tree} />
+ * @example <TreeProvider tree={tree}><TreeRouter /></TreeProvider>
  * @see https://shelving.cc/ui/TreeRouter
  */
-export function TreeRouter({ tree, fallback, ...meta }: TreeRouterProps): ReactNode {
+export function TreeRouter({ fallback, ...meta }: TreeRouterProps): ReactNode {
 	const { path, ...combined } = requireMetaURL(meta);
-	// `<TreeProvider>` flattens the tree (memoised) and exposes it as a lookup map so descendants — the route resolver below, plus `<TreeButton>` / breadcrumbs — all resolve against the one map.
 	return (
 		<MetaContext value={combined}>
-			<TreeProvider tree={tree}>
-				<TreeRoute path={path} fallback={fallback} />
-			</TreeProvider>
+			<TreeRoute path={path} fallback={fallback} />
 		</MetaContext>
 	);
 }

package/ui/tree/TreeSidebar.d.ts

@@ -1,29 +1,23 @@
 import { type ReactNode } from "react";
-import type { AbsolutePath } from "../../util/path.js";
-import { type TreeElement } from "../../util/tree.js";
 import type { OptionalChildProps } from "../util/index.js";
 /**
- * Props for the `TreeSidebar` component — the root tree element plus its URL path.
+ * Props for the `TreeSidebar` component.
  *
  * @see https://shelving.cc/ui/TreeSidebarProps
  */
 export interface TreeSidebarProps extends OptionalChildProps {
-    /** Root element of the tree. */
-    readonly tree: TreeElement;
-    /** URL path of the root — defaults to `/`. Children are rendered with `path + their.name`. */
-    readonly path?: AbsolutePath | undefined;
 }
 /**
- * Sidebar built from a tree element, in three sections separated by dividers.
+ * Sidebar built from the surrounding tree, in three sections separated by dividers.
  *
  * - **Middle:** a `<TextInput>` search-as-you-type filter.
  * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
  *
- * Child and result hrefs use each element's canonical `path` (or `joinPath(parent, name)` as a fallback). To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ * Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so child and result hrefs use each element's stamped canonical `path`. To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
  * @kind component
  * @returns The sectioned sidebar — home/index links, a search input, and either the tree menu or search results.
- * @example <TreeSidebar tree={tree} />
+ * @example <TreeSidebar />
  * @see https://shelving.cc/ui/TreeSidebar
  */
-export declare function TreeSidebar({ tree, path, children }: TreeSidebarProps): ReactNode;
+export declare function TreeSidebar({ children }: TreeSidebarProps): ReactNode;

package/ui/tree/TreeSidebar.js

@@ -1,29 +1,30 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useState } from "react";
+import { useState } from "react";
 import { filterElements } from "../../util/element.js";
-import { flattenTree, searchTree } from "../../util/tree.js";
+import { searchTree } from "../../util/tree.js";
 import { Divider } from "../block/Divider.js";
 import { TextInput } from "../form/TextInput.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
+import { useTreeMap } from "./TreeContext.js";
 import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
 /**
- * Sidebar built from a tree element, in three sections separated by dividers.
+ * Sidebar built from the surrounding tree, in three sections separated by dividers.
  *
  * - **Middle:** a `<TextInput>` search-as-you-type filter.
  * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
  *
- * Child and result hrefs use each element's canonical `path` (or `joinPath(parent, name)` as a fallback). To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ * Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so child and result hrefs use each element's stamped canonical `path`. To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
  * @kind component
  * @returns The sectioned sidebar — home/index links, a search input, and either the tree menu or search results.
- * @example <TreeSidebar tree={tree} />
+ * @example <TreeSidebar />
  * @see https://shelving.cc/ui/TreeSidebar
  */
-export function TreeSidebar({ tree, path = "/", children }) {
+export function TreeSidebar({ children }) {
     const [query, setQuery] = useState("");
     const trimmed = query.trim();
-    // Flatten once so search results carry a canonical `path` (and a unique `key`) for their links (the sidebar sits outside the router's `<TreeProvider>`).
-    const root = useMemo(() => flattenTree(tree).get("/") ?? tree, [tree]);
-    const results = trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
-    return (_jsxs(_Fragment, { children: [_jsx(Menu, { children: _jsx(MenuItem, { href: path, children: "Home" }) }), children, _jsx(Divider, {}), _jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(Divider, {}), _jsx(Menu, { children: results ? (results.map(el => (_jsx(MenuItem, { href: el.props.path ?? path, children: el.props.title ?? el.props.name }, el.key)))) : (_jsx(TreeMenuMapper, { path: path, children: filterElements(tree.props.children, matchMenuElement) })) })] }));
+    // The flattened root from context — its children (and descendants) already carry their canonical `path` and unique `key`.
+    const root = useTreeMap().get("/");
+    const results = root && trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
+    return (_jsxs(_Fragment, { children: [_jsx(Menu, { children: _jsx(MenuItem, { href: "/", children: "Home" }) }), children, _jsx(Divider, {}), _jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(Divider, {}), _jsx(Menu, { children: results ? (results.map(el => (_jsx(MenuItem, { href: el.props.path ?? "/", children: el.props.title ?? el.props.name }, el.key)))) : (_jsx(TreeMenuMapper, { children: filterElements(root?.props.children, matchMenuElement) })) })] }));
 }

package/ui/tree/TreeSidebar.md

@@ -4,10 +4,11 @@ The default sidebar for a tree-based site: a single "home" link for the root ele
 
 **Things to know:**
 
-- The home link uses `path` as its href (defaulting to `/`); children's hrefs are computed by appending their `name` to the root path.
+- Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so it takes no `tree` prop — mount it anywhere inside a `<TreeApp>` / `<TreeProvider>`.
+- The home link points at `/`; children's hrefs use each element's stamped canonical `path`.
 - The children render through the same mapper as `<TreeMenu>`, so customise them by wrapping in `<TreeMenuMapping mapping={…}>`.
 - Only directories, files, and `kind: "module"` symbols appear — code symbols are kept off the navigation.
-- Use it directly for finer layout control outside `<TreeApp>`.
+- Use it directly for finer layout control outside the default `<TreeApp>` sidebar.
 
 ## Usage
 
@@ -15,5 +16,5 @@ The default sidebar for a tree-based site: a single "home" link for the root ele
 import { TreeSidebar } from "shelving/ui";
 
 // A home link + children menu combined — the default sidebar.
-<TreeSidebar tree={root} />
+<TreeSidebar />
 ```

package/ui/tree/TreeSidebar.tsx

@@ -1,50 +1,45 @@
-import { type ReactNode, useMemo, useState } from "react";
+import { type ReactNode, useState } from "react";
 import { filterElements } from "../../util/element.js";
-import type { AbsolutePath } from "../../util/path.js";
-import { flattenTree, searchTree, type TreeElement } from "../../util/tree.js";
+import { searchTree } from "../../util/tree.js";
 import { Divider } from "../block/Divider.js";
 import { TextInput } from "../form/TextInput.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
 import type { OptionalChildProps } from "../util/index.js";
+import { useTreeMap } from "./TreeContext.js";
 import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
 
 /**
- * Props for the `TreeSidebar` component — the root tree element plus its URL path.
+ * Props for the `TreeSidebar` component.
  *
  * @see https://shelving.cc/ui/TreeSidebarProps
  */
-export interface TreeSidebarProps extends OptionalChildProps {
-	/** Root element of the tree. */
-	readonly tree: TreeElement;
-	/** URL path of the root — defaults to `/`. Children are rendered with `path + their.name`. */
-	readonly path?: AbsolutePath | undefined;
-}
+export interface TreeSidebarProps extends OptionalChildProps {}
 
 /**
- * Sidebar built from a tree element, in three sections separated by dividers.
+ * Sidebar built from the surrounding tree, in three sections separated by dividers.
  *
  * - **Middle:** a `<TextInput>` search-as-you-type filter.
  * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
  *
- * Child and result hrefs use each element's canonical `path` (or `joinPath(parent, name)` as a fallback). To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ * Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so child and result hrefs use each element's stamped canonical `path`. To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
  * @kind component
  * @returns The sectioned sidebar — home/index links, a search input, and either the tree menu or search results.
- * @example <TreeSidebar tree={tree} />
+ * @example <TreeSidebar />
  * @see https://shelving.cc/ui/TreeSidebar
  */
-export function TreeSidebar({ tree, path = "/", children }: TreeSidebarProps): ReactNode {
+export function TreeSidebar({ children }: TreeSidebarProps): ReactNode {
 	const [query, setQuery] = useState("");
 	const trimmed = query.trim();
 
-	// Flatten once so search results carry a canonical `path` (and a unique `key`) for their links (the sidebar sits outside the router's `<TreeProvider>`).
-	const root = useMemo(() => flattenTree(tree).get("/") ?? tree, [tree]);
-	const results = trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
+	// The flattened root from context — its children (and descendants) already carry their canonical `path` and unique `key`.
+	const root = useTreeMap().get("/");
+	const results = root && trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
 
 	return (
 		<>
 			<Menu>
-				<MenuItem href={path}>Home</MenuItem>
+				<MenuItem href="/">Home</MenuItem>
 			</Menu>
 			{children}
 			<Divider />
@@ -53,12 +48,12 @@ export function TreeSidebar({ tree, path = "/", children }: TreeSidebarProps): R
 			<Menu>
 				{results ? (
 					results.map(el => (
-						<MenuItem key={el.key} href={el.props.path ?? path}>
+						<MenuItem key={el.key} href={el.props.path ?? "/"}>
 							{el.props.title ?? el.props.name}
 						</MenuItem>
 					))
 				) : (
-					<TreeMenuMapper path={path}>{filterElements(tree.props.children, matchMenuElement)}</TreeMenuMapper>
+					<TreeMenuMapper>{filterElements(root?.props.children, matchMenuElement)}</TreeMenuMapper>
 				)}
 			</Menu>
 		</>

package/util/ansi.d.ts

@@ -92,64 +92,55 @@ export declare const ANSI_RESET: "\u001B[0m";
 /**
  * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
  *
- * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ * - Colour is only emitted when the runtime supports it, resolved once at module load into `_USES_COLOR` — `FORCE_COLOR` > `NO_COLOR` > TTY detection > default-off.
+ * - The default is *off* for non-interactive sinks (files, log aggregators, Workers), so escape codes never pollute non-TTY output unless `FORCE_COLOR` opts back in.
  *
  * @param input The string to wrap in ANSI codes.
  * @param wrappers Any number of ANSI escape codes (e.g. `ANSI_RED`, `ANSI_BOLD`) to prepend before `input`.
- * @returns The wrapped string, or `input` unchanged when the `NO_COLOR` environment variable is set.
+ * @returns The wrapped string, or `input` unchanged when colour is not supported (see precedence above).
  * @example ansiWrap("hello", ANSI_RED, ANSI_BOLD) // "\x1b[31m\x1b[1mhello\x1b[0m"
  * @see https://shelving.cc/util/ansi/ansiWrap
  */
 export declare function ansiWrap(input: string, ...wrappers: ImmutableArray<string>): string;
 /**
- * A lazily-coloured icon that re-evaluates its ANSI colouring against the live `NO_COLOR` environment variable every time it is converted to a string.
- *
- * - Used directly inside template literals (`${ANSI_SUCCESS}`), where JavaScript invokes `toString()` automatically, so the icon is coloured at use-time, not at module-load time.
- *
- * @see https://shelving.cc/util/ansi/AnsiIcon
- */
-export type AnsiIcon = {
-    toString(): string;
-};
-/**
- * Lazily blue-coloured waiting icon (`⋯`) for use in template literals.
+ * Blue-coloured waiting icon (`⋯`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_WAITING
  */
-export declare const ANSI_WAITING: AnsiIcon;
+export declare const ANSI_WAITING: string;
 /**
- * Lazily green-coloured success icon (`✓`) for use in template literals.
+ * Green-coloured success icon (`✓`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_SUCCESS
  */
-export declare const ANSI_SUCCESS: AnsiIcon;
+export declare const ANSI_SUCCESS: string;
 /**
- * Lazily red-coloured failure icon (`✗`) for use in template literals.
+ * Red-coloured failure icon (`✗`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_FAILURE
  */
-export declare const ANSI_FAILURE: AnsiIcon;
+export declare const ANSI_FAILURE: string;
 /**
- * Lazily blue-coloured up arrow icon (`↑`) for use in template literals.
+ * Blue-coloured up arrow icon (`↑`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_UP
  */
-export declare const ANSI_UP: AnsiIcon;
+export declare const ANSI_UP: string;
 /**
- * Lazily blue-coloured down arrow icon (`↓`) for use in template literals.
+ * Blue-coloured down arrow icon (`↓`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_DOWN
  */
-export declare const ANSI_DOWN: AnsiIcon;
+export declare const ANSI_DOWN: string;
 /**
- * Lazily blue-coloured right arrow icon (`→`) for use in template literals.
+ * Blue-coloured right arrow icon (`→`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_RIGHT
  */
-export declare const ANSI_RIGHT: AnsiIcon;
+export declare const ANSI_RIGHT: string;
 /**
- * Lazily blue-coloured left arrow icon (`←`) for use in template literals.
+ * Blue-coloured left arrow icon (`←`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_LEFT
  */
-export declare const ANSI_LEFT: AnsiIcon;
+export declare const ANSI_LEFT: string;

package/util/ansi.js

@@ -1,5 +1,5 @@
 import { DOWN, FAILURE, LEFT, RIGHT, SUCCESS, UP, WAITING } from "./constants.js";
-import { getEnvBoolean } from "./env.js";
+import { getEnv } from "./env.js";
 // Colors.
 /**
  * ANSI escape code that resets the foreground colour to the terminal default.
@@ -93,70 +93,90 @@ export const ANSI_INVERSE = "\x1b[7m";
  * @see https://shelving.cc/util/ansi/ANSI_RESET
  */
 export const ANSI_RESET = "\x1b[0m";
+/**
+ * Whether ANSI colour should be emitted, resolved once at module load the way the broader CLI ecosystem does.
+ *
+ * Precedence, highest first (mirrors the `supports-color` resolution order):
+ * 1. `FORCE_COLOR` — override on for any value except `0` / `false` (which forces off). An empty value counts as on.
+ * 2. `NO_COLOR` — override off for any non-empty value, per [no-color.org](https://no-color.org).
+ * 3. TTY detection — on only when `process.stdout` is an interactive TTY and `TERM` is not `dumb`.
+ * 4. Otherwise off — non-interactive sinks (files, log aggregators, serverless platforms like Cloudflare Workers) get no escape codes by default.
+ *
+ * Resolved once at import rather than on every `ansiWrap()` call: TTY detection makes the load-time value correct in every sink, and the worst case (e.g. `process.env` populated after load) simply falls back to the no-colour default.
+ */
+const _USES_COLOR = (() => {
+    // `FORCE_COLOR` overrides everything: "0"/"false" forces off, any other value (including empty) forces on.
+    const force = getEnv("FORCE_COLOR");
+    if (force !== undefined)
+        return force !== "0" && force.toLowerCase() !== "false";
+    // `NO_COLOR` with any non-empty value disables colour.
+    if (getEnv("NO_COLOR"))
+        return false;
+    // Otherwise enable colour only for an interactive TTY that isn't a dumb terminal.
+    return typeof process === "object" && !!process.stdout?.isTTY && getEnv("TERM") !== "dumb";
+})();
 /**
  * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
  *
- * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ * - Colour is only emitted when the runtime supports it, resolved once at module load into `_USES_COLOR` — `FORCE_COLOR` > `NO_COLOR` > TTY detection > default-off.
+ * - The default is *off* for non-interactive sinks (files, log aggregators, Workers), so escape codes never pollute non-TTY output unless `FORCE_COLOR` opts back in.
  *
  * @param input The string to wrap in ANSI codes.
  * @param wrappers Any number of ANSI escape codes (e.g. `ANSI_RED`, `ANSI_BOLD`) to prepend before `input`.
- * @returns The wrapped string, or `input` unchanged when the `NO_COLOR` environment variable is set.
+ * @returns The wrapped string, or `input` unchanged when colour is not supported (see precedence above).
  * @example ansiWrap("hello", ANSI_RED, ANSI_BOLD) // "\x1b[31m\x1b[1mhello\x1b[0m"
  * @see https://shelving.cc/util/ansi/ansiWrap
  */
 export function ansiWrap(input, ...wrappers) {
-    if (getEnvBoolean("NO_COLOR"))
+    if (!_USES_COLOR)
         return input;
     return `${wrappers.join("")}${input}${ANSI_RESET}`;
 }
-/** Create a lazily-coloured {@link AnsiIcon} that wraps `icon` in `wrappers` on each `toString()`. */
-function _createAnsiIcon(icon, ...wrappers) {
-    return {
-        toString() {
-            return ansiWrap(icon, ...wrappers);
-        },
-    };
-}
 // Coloured icons.
+//
+// Each icon is resolved once at module load by `ansiWrap()`, so colour support is detected at import time
+// (a TTY yields a coloured icon; a non-interactive sink like a file or Cloudflare Worker yields the bare
+// glyph). This trades the previous lazy re-evaluation — which honoured `process.env` mutated after load —
+// for plain string constants, since TTY detection means the worst case simply falls back to the no-colour default.
 /**
- * Lazily blue-coloured waiting icon (`⋯`) for use in template literals.
+ * Blue-coloured waiting icon (`⋯`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_WAITING
  */
-export const ANSI_WAITING = _createAnsiIcon(WAITING, ANSI_BLUE);
+export const ANSI_WAITING = ansiWrap(WAITING, ANSI_BLUE);
 /**
- * Lazily green-coloured success icon (`✓`) for use in template literals.
+ * Green-coloured success icon (`✓`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_SUCCESS
  */
-export const ANSI_SUCCESS = _createAnsiIcon(SUCCESS, ANSI_GREEN);
+export const ANSI_SUCCESS = ansiWrap(SUCCESS, ANSI_GREEN);
 /**
- * Lazily red-coloured failure icon (`✗`) for use in template literals.
+ * Red-coloured failure icon (`✗`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_FAILURE
  */
-export const ANSI_FAILURE = _createAnsiIcon(FAILURE, ANSI_RED);
+export const ANSI_FAILURE = ansiWrap(FAILURE, ANSI_RED);
 /**
- * Lazily blue-coloured up arrow icon (`↑`) for use in template literals.
+ * Blue-coloured up arrow icon (`↑`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_UP
  */
-export const ANSI_UP = _createAnsiIcon(UP, ANSI_BLUE);
+export const ANSI_UP = ansiWrap(UP, ANSI_BLUE);
 /**
- * Lazily blue-coloured down arrow icon (`↓`) for use in template literals.
+ * Blue-coloured down arrow icon (`↓`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_DOWN
  */
-export const ANSI_DOWN = _createAnsiIcon(DOWN, ANSI_BLUE);
+export const ANSI_DOWN = ansiWrap(DOWN, ANSI_BLUE);
 /**
- * Lazily blue-coloured right arrow icon (`→`) for use in template literals.
+ * Blue-coloured right arrow icon (`→`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_RIGHT
  */
-export const ANSI_RIGHT = _createAnsiIcon(RIGHT, ANSI_BLUE);
+export const ANSI_RIGHT = ansiWrap(RIGHT, ANSI_BLUE);
 /**
- * Lazily blue-coloured left arrow icon (`←`) for use in template literals.
+ * Blue-coloured left arrow icon (`←`) for use in template literals, resolved once at module load.
  *
  * @see https://shelving.cc/util/ansi/ANSI_LEFT
  */
-export const ANSI_LEFT = _createAnsiIcon(LEFT, ANSI_BLUE);
+export const ANSI_LEFT = ansiWrap(LEFT, ANSI_BLUE);