shelving 1.204.0 → 1.205.0

package/package.json

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

package/ui/page/Head.js

@@ -1,34 +1,46 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect } from "react";
-import { notNullish } from "../../util/null.js";
+import { isNullish, notNullish } from "../../util/null.js";
 import { getProps } from "../../util/object.js";
-import { isDefined } from "../../util/undefined.js";
 import { requireMeta } from "../misc/Meta.js";
 import { joinTitles } from "../util/meta.js";
 /** Meta tags with a capital first letter and hyphens, e.g. `Content-Security-Policy` or `Accept`, are `http-equiv=""` tags. */
 const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
 /** Use the details from the current page data context to set the document `<title>`, meta tags, and history state. */
 export function Head() {
-    const { url, title, base, app, links, tags } = requireMeta();
+    const { url, title, base, app, links, tags, stylesheets, modules, scripts } = requireMeta();
     useEffect(() => {
         if (typeof window === "undefined")
             return;
         if (url)
             window.history.replaceState(null, "", url);
     }, [url]);
-    return (_jsxs("head", { children: [_jsx("title", { children: joinTitles(title, app) }), base && _jsx("base", { href: base.href }), tags &&
-                getProps(tags)
-                    .map(([k, x]) => {
-                    if (notNullish(x)) {
-                        const y = x === true ? "yes" : x === false ? "no" : x;
-                        if (k.startsWith("og:"))
-                            return _jsx("meta", { property: k, content: y }, k); // Tags that start with `og:` use `property=""`
-                        if (k.match(R_HTTP_EQUIV))
-                            return _jsx("meta", { httpEquiv: k, content: y }, k); // Tags that are in `Snake-Case` use `http-equiv=""`
-                        return _jsx("meta", { name: k, content: y }, k); // All other tags use `content=""`
-                    }
-                    return null;
-                })
-                    .filter(isDefined), links &&
-                getProps(links).map(([k, v]) => notNullish(v) ? (_jsx("link", { rel: k, href: v, type: v.endsWith(".png") ? "image/png" : v.endsWith(".ico") ? "image/x-icon" : undefined }, k)) : null)] }));
+    return (_jsxs("head", { children: [_jsx("title", { children: joinTitles(title, app) }), base && _jsx("base", { href: base.href }), tags && getProps(tags).map(_renderTags), links && getProps(links).map(_renderLinks), stylesheets?.map(_renderStylesheets), modules?.map(_renderModules), scripts?.map(_renderScripts)] }));
+}
+function _renderTags([k, x]) {
+    if (notNullish(x)) {
+        const y = x === true ? "yes" : x === false ? "no" : x;
+        if (k.startsWith("og:"))
+            return _jsx("meta", { property: k, content: y }, k); // Tags that start with `og:` use `property=""`
+        if (k.match(R_HTTP_EQUIV))
+            return _jsx("meta", { httpEquiv: k, content: y }, k); // Tags that are in `Snake-Case` use `http-equiv=""`
+        return _jsx("meta", { name: k, content: y }, k); // All other tags use `content=""`
+    }
+    return null;
+}
+function _renderLinks([k, v]) {
+    if (notNullish(v)) {
+        const type = k.endsWith("icon") ? "image/x-icon" : "text/css";
+        return _jsx("link", { rel: k, href: v, type: type }, k);
+    }
+    return null;
+}
+function _renderStylesheets(v) {
+    return isNullish(v) ? null : _jsx("link", { rel: "stylesheet", type: "text/css", href: v }, v);
+}
+function _renderModules(v) {
+    return isNullish(v) ? null : _jsx("script", { type: "module", src: v, defer: true }, v);
+}
+function _renderScripts(v) {
+    return isNullish(v) ? null : _jsx("script", { type: "text/javascript", src: v, defer: true }, v);
 }

package/ui/page/Head.tsx

@@ -1,16 +1,16 @@
 import { type ReactElement, useEffect } from "react";
-import { notNullish } from "../../util/null.js";
-import { getProps } from "../../util/object.js";
-import { isDefined } from "../../util/undefined.js";
+import type { ArrayItem } from "../../util/array.js";
+import { isNullish, notNullish } from "../../util/null.js";
+import { getProps, type Prop } from "../../util/object.js";
 import { requireMeta } from "../misc/Meta.js";
-import { joinTitles } from "../util/meta.js";
+import { joinTitles, type MetaAssets, type MetaLinks, type MetaTags } from "../util/meta.js";
 
 /** Meta tags with a capital first letter and hyphens, e.g. `Content-Security-Policy` or `Accept`, are `http-equiv=""` tags. */
 const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
 
 /** Use the details from the current page data context to set the document `<title>`, meta tags, and history state. */
 export function Head(): ReactElement {
-	const { url, title, base, app, links, tags } = requireMeta();
+	const { url, title, base, app, links, tags, stylesheets, modules, scripts } = requireMeta();
 
 	useEffect(() => {
 		if (typeof window === "undefined") return;
@@ -21,24 +21,41 @@ export function Head(): ReactElement {
 		<head>
 			<title>{joinTitles(title, app)}</title>
 			{base && <base href={base.href} />}
-			{tags &&
-				getProps(tags)
-					.map(([k, x]) => {
-						if (notNullish(x)) {
-							const y = x === true ? "yes" : x === false ? "no" : x;
-							if (k.startsWith("og:")) return <meta key={k} property={k} content={y} />; // Tags that start with `og:` use `property=""`
-							if (k.match(R_HTTP_EQUIV)) return <meta key={k} httpEquiv={k} content={y} />; // Tags that are in `Snake-Case` use `http-equiv=""`
-							return <meta key={k} name={k} content={y} />; // All other tags use `content=""`
-						}
-						return null;
-					})
-					.filter(isDefined)}
-			{links &&
-				getProps(links).map(([k, v]) =>
-					notNullish(v) ? (
-						<link key={k} rel={k} href={v} type={v.endsWith(".png") ? "image/png" : v.endsWith(".ico") ? "image/x-icon" : undefined} />
-					) : null,
-				)}
+			{tags && getProps(tags).map(_renderTags)}
+			{links && getProps(links).map(_renderLinks)}
+			{stylesheets?.map(_renderStylesheets)}
+			{modules?.map(_renderModules)}
+			{scripts?.map(_renderScripts)}
 		</head>
 	);
 }
+
+function _renderTags([k, x]: Prop<MetaTags>): ReactElement | null {
+	if (notNullish(x)) {
+		const y = x === true ? "yes" : x === false ? "no" : x;
+		if (k.startsWith("og:")) return <meta key={k} property={k} content={y} />; // Tags that start with `og:` use `property=""`
+		if (k.match(R_HTTP_EQUIV)) return <meta key={k} httpEquiv={k} content={y} />; // Tags that are in `Snake-Case` use `http-equiv=""`
+		return <meta key={k} name={k} content={y} />; // All other tags use `content=""`
+	}
+	return null;
+}
+
+function _renderLinks([k, v]: Prop<MetaLinks>): ReactElement | null {
+	if (notNullish(v)) {
+		const type = k.endsWith("icon") ? "image/x-icon" : "text/css";
+		return <link key={k} rel={k} href={v} type={type} />;
+	}
+	return null;
+}
+
+function _renderStylesheets(v: ArrayItem<MetaAssets>): ReactElement | null {
+	return isNullish(v) ? null : <link key={v} rel="stylesheet" type="text/css" href={v} />;
+}
+
+function _renderModules(v: ArrayItem<MetaAssets>): ReactElement | null {
+	return isNullish(v) ? null : <script key={v} type="module" src={v} defer />;
+}
+
+function _renderScripts(v: ArrayItem<MetaAssets>): ReactElement | null {
+	return isNullish(v) ? null : <script key={v} type="text/javascript" src={v} defer />;
+}

package/ui/tree/TreeApp.d.ts

@@ -1,19 +1,21 @@
 import type { ReactElement } from "react";
-import type { Elements } from "../../util/element.js";
-import { type AppProps } from "../app/App.js";
+import type { TreeElement } from "../../util/index.js";
 import type { Routes } from "../router/Routes.js";
-export interface TreeAppProps extends AppProps {
+import type { PossibleMeta } from "../util/index.js";
+export interface TreeAppProps extends PossibleMeta {
     /** The tree elements to display. */
-    elements: Elements;
+    tree: TreeElement;
     /** Additional routes (merged with the default tree route). */
     routes?: Routes | undefined;
+    /** Children is optional and defaults to `<RouterOutput />` */
+    children?: ReactElement | undefined;
 }
 /**
  * Top-level app component for a tree-based documentation site.
  * - Wraps `<App>` with routing, error catching, and a sidebar layout.
  * - The sidebar shows a `<TreeMenu>` of top-level elements.
- * - A catch-all route renders `<TreePage>` for any path.
+ * - `/` 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>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  */
-export declare function TreeApp({ elements, routes, children, ...appProps }: TreeAppProps): ReactElement;
+export declare function TreeApp({ tree, routes, children, ...appProps }: TreeAppProps): ReactElement;

package/ui/tree/TreeApp.js

@@ -2,22 +2,23 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { App } from "../app/App.js";
 import { SidebarLayout } from "../layout/SidebarLayout.js";
 import { PageCatcher } from "../misc/Catcher.js";
-import { Router } from "../router/Router.js";
+import { Router, RouterOutput } from "../router/Router.js";
 import { TreeMenu } from "./TreeMenu.js";
 import { TreePage } from "./TreePage.js";
-const TREE_ROUTE = "/{**path}";
 /**
  * Top-level app component for a tree-based documentation site.
  * - Wraps `<App>` with routing, error catching, and a sidebar layout.
  * - The sidebar shows a `<TreeMenu>` of top-level elements.
- * - A catch-all route renders `<TreePage>` for any path.
+ * - `/` 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>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  */
-export function TreeApp({ elements, routes = {}, children, ...appProps }) {
+export function TreeApp({ tree, routes = {}, children = _jsx(RouterOutput, {}), ...appProps }) {
     const allRoutes = {
         ...routes,
-        [TREE_ROUTE]: props => _jsx(TreePage, { ...props, elements: elements }),
+        "/": () => _jsx(TreePage, { tree: tree }),
+        // `**` captures the multi-segment remainder under index `"0"` (named placeholders are single-segment only).
+        "/**": ({ 0: sub }) => _jsx(TreePage, { path: `/${sub ?? ""}`, tree: tree }),
     };
-    return (_jsx(App, { ...appProps, children: _jsx(Router, { routes: allRoutes, children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: _jsx(TreeMenu, { children: elements }), children: children }) }) }) }));
+    return (_jsx(App, { ...appProps, children: _jsx(Router, { routes: allRoutes, children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: _jsx(TreeMenu, { tree: tree }), children: children }) }) }) }));
 }

package/ui/tree/TreeApp.tsx

@@ -1,42 +1,45 @@
 import type { ReactElement } from "react";
-import type { Elements } from "../../util/element.js";
+import type { TreeElement } from "../../util/index.js";
 import type { AbsolutePath } from "../../util/path.js";
-import { App, type AppProps } from "../app/App.js";
+import { App } from "../app/App.js";
 import { SidebarLayout } from "../layout/SidebarLayout.js";
 import { PageCatcher } from "../misc/Catcher.js";
-import { Router } from "../router/Router.js";
+import { Router, RouterOutput } from "../router/Router.js";
 import type { Routes } from "../router/Routes.js";
+import type { PossibleMeta } from "../util/index.js";
 import { TreeMenu } from "./TreeMenu.js";
 import { TreePage } from "./TreePage.js";
 
-export interface TreeAppProps extends AppProps {
+export interface TreeAppProps extends PossibleMeta {
 	/** The tree elements to display. */
-	elements: Elements;
+	tree: TreeElement;
 	/** Additional routes (merged with the default tree route). */
 	routes?: Routes | undefined;
+	/** Children is optional and defaults to `<RouterOutput />` */
+	children?: ReactElement | undefined;
 }
 
-const TREE_ROUTE = "/{**path}" as AbsolutePath;
-
 /**
  * Top-level app component for a tree-based documentation site.
  * - Wraps `<App>` with routing, error catching, and a sidebar layout.
  * - The sidebar shows a `<TreeMenu>` of top-level elements.
- * - A catch-all route renders `<TreePage>` for any path.
+ * - `/` 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>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  */
-export function TreeApp({ elements, routes = {}, children, ...appProps }: TreeAppProps): ReactElement {
+export function TreeApp({ tree, routes = {}, children = <RouterOutput />, ...appProps }: TreeAppProps): ReactElement {
 	const allRoutes: Routes = {
 		...routes,
-		[TREE_ROUTE]: props => <TreePage {...props} elements={elements} />,
+		"/": () => <TreePage tree={tree} />,
+		// `**` captures the multi-segment remainder under index `"0"` (named placeholders are single-segment only).
+		"/**": ({ 0: sub }) => <TreePage path={`/${sub ?? ""}` as AbsolutePath} tree={tree} />,
 	};
 
 	return (
 		<App {...appProps}>
 			<Router routes={allRoutes}>
 				<PageCatcher>
-					<SidebarLayout sidebar={<TreeMenu>{elements}</TreeMenu>}>{children}</SidebarLayout>
+					<SidebarLayout sidebar={<TreeMenu tree={tree} />}>{children}</SidebarLayout>
 				</PageCatcher>
 			</Router>
 		</App>

package/ui/tree/TreeCards.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Elements } from "../../util/element.js";
+import type { TreeElements } from "../../util/element.js";
 /**
  * Default mappings for the most common tree element types.
  * - Consumers can override individual entries via `<TreeCardMapping>`.
@@ -7,7 +7,7 @@ import type { Elements } from "../../util/element.js";
 export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeCardMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
 export interface TreeCardsProps {
     /** Elements to render as cards. */
-    children?: Elements;
+    children: TreeElements;
 }
-/** Grid of cards built from a tree of elements. */
+/** Grid of cards rendered from a flat collection of tree elements. */
 export declare function TreeCards({ children }: TreeCardsProps): ReactNode;

package/ui/tree/TreeCards.js

@@ -13,7 +13,7 @@ export const [TreeCardMapping, TreeCardMapper] = createMapper({
     "tree-file": FileCard,
     "tree-documentation": DocumentationCard,
 });
-/** Grid of cards built from a tree of elements. */
+/** Grid of cards rendered from a flat collection of tree elements. */
 export function TreeCards({ children }) {
     return (_jsx("div", { className: TREE_CARDS_CSS.grid, children: _jsx(TreeCardMapper, { children: children }) }));
 }

package/ui/tree/TreeCards.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Elements } from "../../util/element.js";
+import type { TreeElements } from "../../util/element.js";
 import { DirectoryCard } from "../docs/DirectoryCard.js";
 import { DocumentationCard } from "../docs/DocumentationCard.js";
 import { FileCard } from "../docs/FileCard.js";
@@ -18,10 +18,10 @@ export const [TreeCardMapping, TreeCardMapper] = createMapper({
 
 export interface TreeCardsProps {
 	/** Elements to render as cards. */
-	children?: Elements;
+	children: TreeElements;
 }
 
-/** Grid of cards built from a tree of elements. */
+/** Grid of cards rendered from a flat collection of tree elements. */
 export function TreeCards({ children }: TreeCardsProps): ReactNode {
 	return (
 		<div className={TREE_CARDS_CSS.grid}>

package/ui/tree/TreeMenu.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Elements } from "../../util/element.js";
+import type { TreeElement } from "../../util/element.js";
 /**
  * Default mappings for the most common tree element types.
  * - Consumers can override individual entries via `<TreeMenuMapping>`.
@@ -7,8 +7,8 @@ import type { Elements } from "../../util/element.js";
  */
 export declare const TreeMenuMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeMenuMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
 export interface TreeMenuProps {
-    /** Elements to render as navigation links. */
-    children?: Elements;
+    /** Root element whose children become the navigation links. */
+    tree: TreeElement;
 }
-/** Sidebar navigation menu built from a tree of elements. */
-export declare function TreeMenu({ children }: TreeMenuProps): ReactNode;
+/** Sidebar navigation menu built from the children of a root tree element. */
+export declare function TreeMenu({ tree }: TreeMenuProps): ReactNode;

package/ui/tree/TreeMenu.js

@@ -12,7 +12,7 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
     "tree-directory": DirectoryMenuItem,
     "tree-file": FileMenuItem,
 });
-/** Sidebar navigation menu built from a tree of elements. */
-export function TreeMenu({ children }) {
-    return (_jsx("nav", { className: TREE_MENU_CSS.menu, children: _jsx("ul", { className: TREE_MENU_CSS.list, children: _jsx(TreeMenuMapper, { children: children }) }) }));
+/** Sidebar navigation menu built from the children of a root tree element. */
+export function TreeMenu({ tree }) {
+    return (_jsx("nav", { className: TREE_MENU_CSS.menu, children: _jsx("ul", { className: TREE_MENU_CSS.list, children: _jsx(TreeMenuMapper, { children: tree.props.children }) }) }));
 }

package/ui/tree/TreeMenu.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Elements } from "../../util/element.js";
+import type { TreeElement } from "../../util/element.js";
 import { DirectoryMenuItem } from "../docs/DirectoryMenuItem.js";
 import { FileMenuItem } from "../docs/FileMenuItem.js";
 import { createMapper } from "../misc/Mapper.js";
@@ -16,16 +16,16 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
 });
 
 export interface TreeMenuProps {
-	/** Elements to render as navigation links. */
-	children?: Elements;
+	/** Root element whose children become the navigation links. */
+	tree: TreeElement;
 }
 
-/** Sidebar navigation menu built from a tree of elements. */
-export function TreeMenu({ children }: TreeMenuProps): ReactNode {
+/** Sidebar navigation menu built from the children of a root tree element. */
+export function TreeMenu({ tree }: TreeMenuProps): ReactNode {
 	return (
 		<nav className={TREE_MENU_CSS.menu}>
 			<ul className={TREE_MENU_CSS.list}>
-				<TreeMenuMapper>{children}</TreeMenuMapper>
+				<TreeMenuMapper>{tree.props.children}</TreeMenuMapper>
 			</ul>
 		</nav>
 	);

package/ui/tree/TreePage.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import { type Elements } from "../../util/element.js";
+import { type TreeElement } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 /**
  * Default mappings for the most common tree element types.
@@ -8,13 +8,13 @@ import { type AbsolutePath } from "../../util/path.js";
 export declare const TreePageMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreePageMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
 export interface TreePageProps {
     path?: AbsolutePath;
-    /** The root elements to search within. */
-    elements?: Elements;
+    tree: TreeElement;
 }
 /**
  * Resolve a URL path to a tree element and render it.
- * - Uses `resolveElement()` to walk the tree matching each path segment to an element's `key`.
+ * - Uses `resolveElementPath()` to walk the tree matching each path segment to a descendant's `key`.
+ * - `/` renders `tree` itself; deeper paths render the matching descendant.
  * - Delegates rendering to the component registered in the element mapper.
  * - Throws `NotFoundError` if no element matches at any level.
  */
-export declare function TreePage({ path, elements }: TreePageProps): ReactNode;
+export declare function TreePage({ path, tree }: TreePageProps): ReactNode;

package/ui/tree/TreePage.js

@@ -17,12 +17,13 @@ export const [TreePageMapping, TreePageMapper] = createMapper({
 });
 /**
  * Resolve a URL path to a tree element and render it.
- * - Uses `resolveElement()` to walk the tree matching each path segment to an element's `key`.
+ * - Uses `resolveElementPath()` to walk the tree matching each path segment to a descendant's `key`.
+ * - `/` renders `tree` itself; deeper paths render the matching descendant.
  * - Delegates rendering to the component registered in the element mapper.
  * - Throws `NotFoundError` if no element matches at any level.
  */
-export function TreePage({ path = "/", elements }) {
-    const element = resolveElementPath(elements, splitAbsolutePath(path));
+export function TreePage({ path = "/", tree }) {
+    const element = resolveElementPath(tree, splitAbsolutePath(path));
     if (!element)
         throw new NotFoundError("Element not found", { received: path });
     return _jsx(TreePageMapper, { children: element });

package/ui/tree/TreePage.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import { NotFoundError } from "../../error/RequestError.js";
-import { type Elements, resolveElementPath } from "../../util/element.js";
+import { resolveElementPath, type TreeElement } from "../../util/element.js";
 import { type AbsolutePath, splitAbsolutePath } from "../../util/path.js";
 import { DirectoryPage } from "../docs/DirectoryPage.js";
 import { DocumentationPage } from "../docs/DocumentationPage.js";
@@ -19,18 +19,18 @@ export const [TreePageMapping, TreePageMapper] = createMapper({
 
 export interface TreePageProps {
 	path?: AbsolutePath;
-	/** The root elements to search within. */
-	elements?: Elements;
+	tree: TreeElement;
 }
 
 /**
  * Resolve a URL path to a tree element and render it.
- * - Uses `resolveElement()` to walk the tree matching each path segment to an element's `key`.
+ * - Uses `resolveElementPath()` to walk the tree matching each path segment to a descendant's `key`.
+ * - `/` renders `tree` itself; deeper paths render the matching descendant.
  * - Delegates rendering to the component registered in the element mapper.
  * - Throws `NotFoundError` if no element matches at any level.
  */
-export function TreePage({ path = "/", elements }: TreePageProps): ReactNode {
-	const element = resolveElementPath(elements, splitAbsolutePath(path));
+export function TreePage({ path = "/", tree }: TreePageProps): ReactNode {
+	const element = resolveElementPath(tree, splitAbsolutePath(path));
 	if (!element) throw new NotFoundError("Element not found", { received: path });
 	return <TreePageMapper>{element}</TreePageMapper>;
 }

package/ui/util/meta.d.ts

@@ -34,7 +34,7 @@ export interface MetaData {
     readonly links?: MetaLinks | undefined;
     readonly modules?: MetaAssets | undefined;
     readonly scripts?: MetaAssets | undefined;
-    readonly styles?: MetaAssets | undefined;
+    readonly stylesheets?: MetaAssets | undefined;
 }
 /** Input metadata that can be parsed and converted to proper metadata. */
 export interface PossibleMeta extends Omit<MetaData, "url"> {

package/ui/util/meta.ts

@@ -37,7 +37,7 @@ export interface MetaData {
 	readonly links?: MetaLinks | undefined;
 	readonly modules?: MetaAssets | undefined;
 	readonly scripts?: MetaAssets | undefined;
-	readonly styles?: MetaAssets | undefined;
+	readonly stylesheets?: MetaAssets | undefined;
 }
 
 /** Input metadata that can be parsed and converted to proper metadata. */

package/util/element.d.ts

@@ -1,7 +1,6 @@
 import type { ImmutableArray } from "./array.js";
 import type { AbsolutePath } from "./path.js";
 import type { Query } from "./query.js";
-import type { Segments } from "./string.js";
 /** Set of valid props for an element. */
 export interface ElementProps {
     readonly [key: string]: unknown;
@@ -151,48 +150,45 @@ export declare function queryElements(elements: Elements, query: Query<Element>,
  */
 export declare function filterElements(elements: Elements, match: (element: Element) => boolean, depth?: number): Iterable<Element>;
 /**
- * Resolve an element in a tree by walking a sequence of keys.
- * - Accepts a dot-separated string (e.g. `"util.array"`) or an array of path segments (e.g. `["util", "array"]`).
- * - Matches each segment to the `key` of an immediate child element.
- * - If `keys` is empty, undefined, or an empty string, returns the first keyed element at the root level.
- * - Returns `undefined` if no element matches at any level.
+ * Resolve an element in a tree by walking a sequence of keys from `root`.
+ * - The `root` element's own key is never matched against path segments — it's the container, not a step in the path.
+ * - Each segment matches the `key` of an immediate child of the current element.
+ * - If `path` is empty, returns `root` itself.
+ * - Returns `undefined` if no descendant matches at any level.
  *
  * Splitting the path:
- * - We accept a raw `Segments` array for each element, so they can be joined later however you wish.
+ * - We accept a raw `Segments` array, so callers can join paths later however they wish.
  * - Element paths have no canonical string representation so we use `Segments` instead.
- * - To split the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(elements), splitDataPath)`
- * - To split the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(elements), splitAbsolutePath)`
+ * - To split the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(root), splitDataPath)`
+ * - To split the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(root), splitAbsolutePath)`
  *
- * @param elements The root elements to search within.
- * @param path An array of path segments.
- * - Element paths have no canonical string representation so we always us the `Segments` format.
+ * @param root The root element to walk from. Its own `key` is treated as a label, not a path segment.
+ * @param path An array of path segments naming descendants of `root`.
  *
- * @example resolveElement(elements, "util.array") // Element with key "array" inside element with key "util"
- * @example resolveElement(elements, ["util", "array"]) // Same as above
- * @example resolveElement(elements, "") // First keyed root element
+ * @example resolveElementPath(root, ["util", "array"]) // Element with key "array" inside child with key "util"
+ * @example resolveElementPath(root, []) // `root` itself
  */
-export declare function resolveElementPath(elements: Elements, path: Segments): Element | undefined;
+export declare function resolveElementPath(root: TreeElement, path: readonly string[]): Element | undefined;
 /**
- * Deeply iterate a tree of elements and yield an array of path segments for each element that has a string `key:` property.
- * - Each yielded value is an array of path segments from root to the element.
- * - Only elements with a string `key:` property are included.
- * - Elements with `undefined` or `null` key are skipped.
+ * Deeply iterate a tree from `root` and yield path segments for each reachable element.
+ * - Yields `[]` for `root` itself.
+ * - Yields `[key]` for each immediate child, `[key, key]` for grandchildren, etc.
+ * - The `root` element's own key never appears in any yielded path — it's the container.
+ * - Children with `undefined` or `null` keys are skipped (and their descendants are not yielded).
  *
  * Joining the paths:
- * - We return a `Segments` array for each element, so they can be joined later however you wish.
+ * - We return a `Segments` array for each element, so callers can join paths later however they wish.
  * - Element paths have no canonical string representation so we use `Segments` instead.
- * - To join the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(elements), joinDataPath)`
- * - To join the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(elements), joinAbsolutePath)`
+ * - To join the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(root), joinDataPath)`
+ * - To join the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(root), joinAbsolutePath)`
  *
- * @param elements The elements to get keys for.
+ * @param root The root element to walk from. Its own `key` is treated as a label, not a path segment.
  * @param depth Controls how many levels of children to recurse into (defaults to infinite depth).
- * - `depth=0` yields matching elements at the current level only (no recursion into children).
+ * - `depth=0` yields only `[]` (the root itself).
  *
- * @returns Iterable set of path segment arrays, each representing one component.
- * - Element paths have no canonical string representation so we always us the `Segments` format.
+ * @returns Iterable set of path segment arrays, each representing one descendant (or the root).
  */
-export declare function getElementPaths(elements: Elements, depth?: number): Iterable<Segments>;
-export declare function _getElementPaths(elements: Elements, depth: number, prefix?: Segments): Iterable<Segments>;
+export declare function getElementPaths(root: TreeElement, depth?: number): Iterable<readonly string[]>;
 /** Combine two `Elements`, preserving both if both are set. */
 export declare function mergeElements<T extends Elements>(a: T, b: T): T;
 export declare function mergeElements(a: Elements, b: Elements): Elements;

package/util/element.js

@@ -70,32 +70,29 @@ export function* filterElements(elements, match, depth = Infinity) {
             yield element;
 }
 /**
- * Resolve an element in a tree by walking a sequence of keys.
- * - Accepts a dot-separated string (e.g. `"util.array"`) or an array of path segments (e.g. `["util", "array"]`).
- * - Matches each segment to the `key` of an immediate child element.
- * - If `keys` is empty, undefined, or an empty string, returns the first keyed element at the root level.
- * - Returns `undefined` if no element matches at any level.
+ * Resolve an element in a tree by walking a sequence of keys from `root`.
+ * - The `root` element's own key is never matched against path segments — it's the container, not a step in the path.
+ * - Each segment matches the `key` of an immediate child of the current element.
+ * - If `path` is empty, returns `root` itself.
+ * - Returns `undefined` if no descendant matches at any level.
  *
  * Splitting the path:
- * - We accept a raw `Segments` array for each element, so they can be joined later however you wish.
+ * - We accept a raw `Segments` array, so callers can join paths later however they wish.
  * - Element paths have no canonical string representation so we use `Segments` instead.
- * - To split the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(elements), splitDataPath)`
- * - To split the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(elements), splitAbsolutePath)`
+ * - To split the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(root), splitDataPath)`
+ * - To split the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(root), splitAbsolutePath)`
  *
- * @param elements The root elements to search within.
- * @param path An array of path segments.
- * - Element paths have no canonical string representation so we always us the `Segments` format.
+ * @param root The root element to walk from. Its own `key` is treated as a label, not a path segment.
+ * @param path An array of path segments naming descendants of `root`.
  *
- * @example resolveElement(elements, "util.array") // Element with key "array" inside element with key "util"
- * @example resolveElement(elements, ["util", "array"]) // Same as above
- * @example resolveElement(elements, "") // First keyed root element
+ * @example resolveElementPath(root, ["util", "array"]) // Element with key "array" inside child with key "util"
+ * @example resolveElementPath(root, []) // `root` itself
  */
-export function resolveElementPath(elements, path) {
-    let current = elements;
-    let found;
+export function resolveElementPath(root, path) {
+    let current = root;
     for (const segment of path) {
-        found = undefined;
-        for (const el of getElements(current, 0)) {
+        let found;
+        for (const el of getElements(current.props.children, 0)) {
             if (el.key === segment) {
                 found = el;
                 break;
@@ -103,35 +100,40 @@ export function resolveElementPath(elements, path) {
         }
         if (!found)
             return undefined;
-        current = found.props.children;
+        current = found;
     }
-    return found;
+    return current;
 }
 /**
- * Deeply iterate a tree of elements and yield an array of path segments for each element that has a string `key:` property.
- * - Each yielded value is an array of path segments from root to the element.
- * - Only elements with a string `key:` property are included.
- * - Elements with `undefined` or `null` key are skipped.
+ * Deeply iterate a tree from `root` and yield path segments for each reachable element.
+ * - Yields `[]` for `root` itself.
+ * - Yields `[key]` for each immediate child, `[key, key]` for grandchildren, etc.
+ * - The `root` element's own key never appears in any yielded path — it's the container.
+ * - Children with `undefined` or `null` keys are skipped (and their descendants are not yielded).
  *
  * Joining the paths:
- * - We return a `Segments` array for each element, so they can be joined later however you wish.
+ * - We return a `Segments` array for each element, so callers can join paths later however they wish.
  * - Element paths have no canonical string representation so we use `Segments` instead.
- * - To join the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(elements), joinDataPath)`
- * - To join the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(elements), joinAbsolutePath)`
+ * - To join the keys in `a.b.c` dotted data format use `mapItems(getElementPaths(root), joinDataPath)`
+ * - To join the keys in `/a/b/c` absolute path format use `mapItems(getElementPaths(root), joinAbsolutePath)`
  *
- * @param elements The elements to get keys for.
+ * @param root The root element to walk from. Its own `key` is treated as a label, not a path segment.
  * @param depth Controls how many levels of children to recurse into (defaults to infinite depth).
- * - `depth=0` yields matching elements at the current level only (no recursion into children).
+ * - `depth=0` yields only `[]` (the root itself).
  *
- * @returns Iterable set of path segment arrays, each representing one component.
- * - Element paths have no canonical string representation so we always us the `Segments` format.
+ * @returns Iterable set of path segment arrays, each representing one descendant (or the root).
  */
-export function getElementPaths(elements, depth = Infinity) {
-    return _getElementPaths(elements, depth);
+export function getElementPaths(root, depth = Infinity) {
+    return _getElementPaths(root, depth);
+}
+function* _getElementPaths(root, depth) {
+    yield [];
+    if (depth > 0)
+        yield* _getDescendantPaths(root.props.children, depth - 1);
 }
-export function* _getElementPaths(elements, depth, prefix) {
+function* _getDescendantPaths(elements, depth, prefix) {
     for (const { key, props } of getElements(elements, 0)) {
-        // Skip `null` or `undefined` keys.
+        // Skip `null` or `undefined` keys (and their descendants).
         if (isNullish(key))
             continue;
         // Make the path and yield it.
@@ -139,7 +141,7 @@ export function* _getElementPaths(elements, depth, prefix) {
         yield keys;
         // Recurse into the children.
         if (depth > 0 && props.children)
-            yield* _getElementPaths(props.children, depth - 1, keys);
+            yield* _getDescendantPaths(props.children, depth - 1, keys);
     }
 }
 export function mergeElements(a, b) {

package/util/path.d.ts

@@ -2,7 +2,6 @@
  * Reuseable utilities for dealing with filesystem paths.
  */
 import type { AnyCaller } from "./function.js";
-import { type Segments } from "./index.js";
 import type { Nullish } from "./null.js";
 /** Absolute path string starts with `/` slash. */
 export type AbsolutePath = `/` | `/${string}`;
@@ -52,7 +51,13 @@ export declare function matchPathPrefix(target: PossiblePath, base: PossiblePath
 export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
 /** Is a target path proud (i.e. is the current path, or is a child of the current path)? */
 export declare function isPathProud(target: AbsolutePath, current: AbsolutePath): boolean;
-/** Get the "segments" in an absolute path. */
-export declare function splitAbsolutePath(path: AbsolutePath | Segments): Segments;
-/** Join a set of path segments to form an absolute path. */
-export declare function joinAbsolutePath(path: Segments | AbsolutePath): AbsolutePath;
+/**
+ * Get the "segments" in an absolute path.
+ * - `splitAbsolutePath("/")` returns `[]` — the root has no segments.
+ */
+export declare function splitAbsolutePath(path: AbsolutePath | readonly string[]): readonly string[];
+/**
+ * Join a set of path segments to form an absolute path.
+ * - `joinAbsolutePath([])` returns `"/"` — an empty segment list represents the root.
+ */
+export declare function joinAbsolutePath(path: AbsolutePath | readonly string[]): AbsolutePath;

package/util/path.js

@@ -74,11 +74,21 @@ export function isPathActive(target, current) {
 export function isPathProud(target, current) {
     return target === current || (target !== "/" && target.startsWith(`${current}/`));
 }
-/** Get the "segments" in an absolute path. */
+/**
+ * Get the "segments" in an absolute path.
+ * - `splitAbsolutePath("/")` returns `[]` — the root has no segments.
+ */
 export function splitAbsolutePath(path) {
-    return typeof path === "string" ? splitString(path.slice(1), "/", 1, undefined, splitAbsolutePath) : path;
+    if (typeof path !== "string")
+        return path;
+    if (path === "/")
+        return [];
+    return splitString(path.slice(1), "/", 1, undefined, splitAbsolutePath);
 }
-/** Join a set of path segments to form an absolute path. */
+/**
+ * Join a set of path segments to form an absolute path.
+ * - `joinAbsolutePath([])` returns `"/"` — an empty segment list represents the root.
+ */
 export function joinAbsolutePath(path) {
-    return typeof path === "string" ? path : `/${path.join("")}`;
+    return typeof path === "string" ? path : `/${path.join("/")}`;
 }