npm - toiljs - Versions diffs - 0.0.14 → 0.0.16 - Mend

toiljs 0.0.14 → 0.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (225) hide show

package/.babelrc +13 -13
package/.gitattributes +2 -2
package/.github/ISSUE_TEMPLATE/bug_report.md +38 -38
package/.github/ISSUE_TEMPLATE/bug_report.yml +90 -90
package/.github/ISSUE_TEMPLATE/config.yml +8 -8
package/.github/ISSUE_TEMPLATE/feature_request.md +20 -20
package/.github/PULL_REQUEST_TEMPLATE.md +43 -43
package/.github/changelog-config.json +45 -45
package/.github/dependabot.yml +27 -27
package/.github/workflows/ci.yml +191 -191
package/.prettierrc.json +11 -11
package/.vscode/settings.json +9 -9
package/CHANGELOG.md +5 -5
package/LICENSE +187 -187
package/README.md +339 -315
package/as-pect.asconfig.json +34 -34
package/as-pect.config.js +65 -65
package/assets/logo.svg +36 -36
package/build/backend/.tsbuildinfo +1 -1
package/build/cli/.tsbuildinfo +1 -1
package/build/cli/index.js +2926 -191
package/build/client/.tsbuildinfo +1 -1
package/build/client/dev/devtools.d.ts +6 -0
package/build/client/dev/devtools.js +442 -0
package/build/client/dev/error-overlay.d.ts +9 -0
package/build/client/dev/error-overlay.js +19 -4
package/build/client/head/metadata.d.ts +3 -1
package/build/client/head/metadata.js +8 -0
package/build/client/index.d.ts +4 -4
package/build/client/index.js +2 -2
package/build/client/navigation/navigation.d.ts +2 -0
package/build/client/navigation/navigation.js +9 -1
package/build/client/navigation/prefetch.d.ts +1 -0
package/build/client/navigation/prefetch.js +35 -0
package/build/client/routing/Router.js +1 -1
package/build/client/routing/hooks.js +6 -2
package/build/client/routing/loader.d.ts +25 -0
package/build/client/routing/loader.js +53 -7
package/build/client/routing/mount.js +4 -3
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/config.d.ts +18 -0
package/build/compiler/config.js +8 -0
package/build/compiler/docs.js +16 -16
package/build/compiler/generate.js +3 -0
package/build/compiler/index.d.ts +2 -2
package/build/compiler/index.js +3 -1
package/build/compiler/plugin.js +156 -0
package/build/compiler/prerender.d.ts +1 -0
package/build/compiler/prerender.js +2 -1
package/build/compiler/seo.d.ts +2 -2
package/build/compiler/seo.js +8 -6
package/build/compiler/ssg.d.ts +5 -0
package/build/compiler/ssg.js +121 -0
package/build/io/.tsbuildinfo +1 -1
package/build/logger/.tsbuildinfo +1 -1
package/build/shared/.tsbuildinfo +1 -1
package/eslint.config.js +48 -48
package/examples/basic/client/404.tsx +11 -11
package/examples/basic/client/components/.gitkeep +1 -1
package/examples/basic/client/global-error.tsx +13 -13
package/examples/basic/client/layout.tsx +25 -25
package/examples/basic/client/public/images/.gitkeep +1 -1
package/examples/basic/client/public/images/logo.svg +36 -36
package/examples/basic/client/public/robots.txt +2 -2
package/examples/basic/client/routes/docs/[...slug].tsx +12 -12
package/examples/basic/client/routes/features/error/error.tsx +16 -16
package/examples/basic/client/routes/features/template/b.tsx +14 -14
package/examples/basic/client/routes/files/[[...slug]].tsx +21 -21
package/examples/basic/client/routes/gallery/layout.tsx +13 -13
package/examples/basic/client/routes/io.tsx +24 -24
package/examples/basic/client/routes/loader-demo/loading.tsx +13 -13
package/examples/basic/client/routes/search.tsx +61 -61
package/examples/basic/client/toil.tsx +5 -5
package/package.json +155 -147
package/presets/eslint.js +88 -88
package/presets/no-uint8array-tostring.js +200 -200
package/presets/prettier.json +18 -18
package/presets/tsconfig.json +37 -37
package/src/backend/index.ts +160 -160
package/src/cli/proc.ts +50 -50
package/src/cli/updates.ts +69 -69
package/src/cli/validate.ts +31 -31
package/src/client/channel/channel.ts +146 -146
package/src/client/components/Form.tsx +65 -65
package/src/client/components/Script.tsx +113 -113
package/src/client/components/Slot.tsx +21 -21
package/src/client/dev/devtools.tsx +973 -0
package/src/client/dev/error-overlay.tsx +30 -4
package/src/client/head/head.ts +167 -167
package/src/client/head/metadata.ts +19 -1
package/src/client/index.ts +19 -9
package/src/client/navigation/NavLink.tsx +86 -86
package/src/client/navigation/navigation.ts +25 -5
package/src/client/navigation/prefetch.ts +169 -130
package/src/client/navigation/scroll.ts +53 -53
package/src/client/routing/Router.tsx +8 -2
package/src/client/routing/action.ts +122 -122
package/src/client/routing/error-boundary.tsx +43 -43
package/src/client/routing/hooks.ts +21 -6
package/src/client/routing/loader.ts +325 -225
package/src/client/routing/match.ts +47 -47
package/src/client/routing/mount.tsx +54 -52
package/src/client/routing/params-context.ts +10 -10
package/src/client/routing/slot-context.ts +7 -7
package/src/client/search/search.ts +189 -189
package/src/client/search/use-page-search.ts +73 -73
package/src/client/types.ts +73 -73
package/src/compiler/config.ts +47 -1
package/src/compiler/docs.ts +228 -228
package/src/compiler/generate.ts +394 -391
package/src/compiler/index.ts +64 -54
package/src/compiler/pages.ts +70 -70
package/src/compiler/plugin.ts +170 -2
package/src/compiler/prerender.ts +5 -1
package/src/compiler/seo.ts +23 -7
package/src/compiler/ssg.ts +162 -0
package/src/io/BinaryReader.ts +340 -340
package/src/io/BinaryWriter.ts +385 -385
package/src/io/FastMap.ts +127 -127
package/src/io/index.ts +11 -11
package/src/io/lengths.ts +14 -14
package/src/io/types.ts +18 -18
package/src/logger/index.ts +22 -22
package/src/server/index.ts +10 -10
package/src/server/main.ts +13 -13
package/src/server/tsconfig.json +4 -4
package/src/shared/index.ts +10 -10
package/std/client/index.d.ts +15 -15
package/std/client/package.json +3 -3
package/test/assembly/example.spec.ts +7 -7
package/test/channel.test.ts +21 -21
package/test/dom/Link.test.tsx +47 -47
package/test/dom/NavLink.test.tsx +37 -37
package/test/dom/error-overlay.test.tsx +44 -44
package/test/dom/loader.test.tsx +121 -121
package/test/dom/navigation.test.ts +59 -59
package/test/dom/revalidate.test.tsx +38 -38
package/test/dom/route-head.test.tsx +78 -78
package/test/dom/router-loading.test.tsx +44 -44
package/test/dom/scroll.test.ts +56 -56
package/test/dom/use-metadata.test.tsx +58 -0
package/test/io.test.ts +93 -93
package/test/navlink.test.ts +28 -28
package/test/placeholder.test.ts +9 -9
package/test/routes.test.ts +76 -76
package/test/seo.test.ts +175 -164
package/test/slot-layouts.test.ts +69 -69
package/test/ssg.test.ts +36 -0
package/test/update.test.ts +44 -44
package/test/validate.test.ts +42 -42
package/toil-routes.d.ts +7 -0
package/toilconfig.json +30 -30
package/tsconfig.backend.json +13 -13
package/tsconfig.base.json +35 -35
package/tsconfig.cli.json +13 -13
package/tsconfig.client.json +14 -14
package/tsconfig.compiler.json +13 -13
package/tsconfig.io.json +12 -12
package/tsconfig.json +22 -22
package/tsconfig.logger.json +12 -12
package/tsconfig.server.json +10 -10
package/tsconfig.shared.json +12 -12
package/vitest.config.ts +26 -26
package/.idea/codeStyles/Project.xml +0 -54
package/.idea/codeStyles/codeStyleConfig.xml +0 -5
package/.idea/inspectionProfiles/Project_Default.xml +0 -6
package/.idea/modules.xml +0 -8
package/.idea/prettier.xml +0 -7
package/.idea/toiljs.iml +0 -8
package/.idea/vcs.xml +0 -6
package/.toil/entry.tsx +0 -9
package/.toil/index.html +0 -12
package/.toil/routes.ts +0 -9
package/build/cli/configure.d.ts +0 -16
package/build/cli/configure.js +0 -272
package/build/cli/create.d.ts +0 -16
package/build/cli/create.js +0 -420
package/build/cli/diagnostics.d.ts +0 -55
package/build/cli/diagnostics.js +0 -333
package/build/cli/doctor.d.ts +0 -6
package/build/cli/doctor.js +0 -249
package/build/cli/features.d.ts +0 -25
package/build/cli/features.js +0 -107
package/build/cli/index.d.ts +0 -2
package/build/cli/proc.d.ts +0 -6
package/build/cli/proc.js +0 -31
package/build/cli/ui.d.ts +0 -9
package/build/cli/ui.js +0 -75
package/build/cli/update.d.ts +0 -7
package/build/cli/update.js +0 -117
package/build/cli/updates.d.ts +0 -10
package/build/cli/updates.js +0 -45
package/build/cli/validate.d.ts +0 -4
package/build/cli/validate.js +0 -19
package/build/client/Link.d.ts +0 -8
package/build/client/Link.js +0 -44
package/build/client/NavLink.d.ts +0 -14
package/build/client/NavLink.js +0 -37
package/build/client/Router.d.ts +0 -7
package/build/client/Router.js +0 -55
package/build/client/channel.d.ts +0 -23
package/build/client/channel.js +0 -94
package/build/client/error-boundary.d.ts +0 -16
package/build/client/error-boundary.js +0 -19
package/build/client/head.d.ts +0 -26
package/build/client/head.js +0 -87
package/build/client/hooks.d.ts +0 -17
package/build/client/hooks.js +0 -48
package/build/client/lazy.d.ts +0 -16
package/build/client/lazy.js +0 -53
package/build/client/match.d.ts +0 -2
package/build/client/match.js +0 -32
package/build/client/mount.d.ts +0 -2
package/build/client/mount.js +0 -13
package/build/client/navigation.d.ts +0 -13
package/build/client/navigation.js +0 -97
package/build/client/params-context.d.ts +0 -2
package/build/client/params-context.js +0 -2
package/build/client/prefetch.d.ts +0 -11
package/build/client/prefetch.js +0 -100
package/build/client/runtime.d.ts +0 -31
package/build/client/runtime.js +0 -112
package/build/client/scroll.d.ts +0 -8
package/build/client/scroll.js +0 -36
package/toil-env.d.ts +0 -16

package/src/client/dev/error-overlay.tsx CHANGED Viewed

@@ -7,21 +7,33 @@
 import { Component, type CSSProperties, type ErrorInfo, type ReactNode, useSyncExternalStore, } from 'react';
 /** A captured dev error. */
-interface DevError {
+export interface DevError {
     readonly error: Error;
     readonly componentStack?: string;
     /** Where it came from, a render boundary, a window `error`, or an unhandled rejection. */
     readonly source: 'render' | 'window' | 'unhandledrejection';
+    /** Capture time (ms epoch). */
+    readonly time: number;
 }
 let current: DevError | null = null;
 const listeners = new Set<() => void>();
+/**
+ * Bounded history of captured errors, for the dev toolbar's Errors tab. Reassigned to a new array
+ * on each change (never mutated in place) so `getErrorLog` is a stable useSyncExternalStore snapshot:
+ * the reference changes only when the log changes, so React re-renders on new errors but not in a loop.
+ */
+let errorLog: readonly DevError[] = [];
+const MAX_LOG = 50;
 function emit(): void {
     for (const listener of listeners) listener();
 }
 function setDevError(next: DevError | null): void {
     current = next;
+    if (next) {
+        errorLog = [...errorLog, next].slice(-MAX_LOG);
+    }
     emit();
 }
 function subscribe(listener: () => void): () => void {
@@ -31,6 +43,13 @@ function subscribe(listener: () => void): () => void {
     };
 }
+/** The captured-error history (most recent last). Subscribe via {@link subscribeErrors}. */
+export function getErrorLog(): readonly DevError[] {
+    return errorLog;
+}
+/** Subscribes to error captures (fires whenever a new error is recorded or dismissed). */
+export const subscribeErrors = subscribe;
 /** True when running under Vite's dev server (replaced at build time; falsy in production). */
 export function isDevMode(): boolean {
     try {
@@ -46,12 +65,14 @@ export function initDevErrorOverlay(): void {
     if (windowBound || typeof window === 'undefined') return;
     windowBound = true;
     window.addEventListener('error', (event) => {
-        if (event.error instanceof Error) setDevError({ error: event.error, source: 'window' });
+        if (event.error instanceof Error) {
+            setDevError({ error: event.error, source: 'window', time: Date.now() });
+        }
     });
     window.addEventListener('unhandledrejection', (event) => {
         const reason: unknown = event.reason;
         const error = reason instanceof Error ? reason : new Error(String(reason));
-        setDevError({ error, source: 'unhandledrejection' });
+        setDevError({ error, source: 'unhandledrejection', time: Date.now() });
     });
 }
@@ -76,7 +97,12 @@ export class DevErrorBoundary extends Component<BoundaryProps, BoundaryState> {
     }
     public override componentDidCatch(error: Error, info: ErrorInfo): void {
-        setDevError({ error, componentStack: info.componentStack ?? undefined, source: 'render' });
+        setDevError({
+            error,
+            componentStack: info.componentStack ?? undefined,
+            source: 'render',
+            time: Date.now(),
+        });
     }
     public override componentDidMount(): void {

package/src/client/head/head.ts CHANGED Viewed

@@ -1,167 +1,167 @@
-/**
- * Client-side document `<head>` management. `useHead` / `useTitle` / `<Head>` let any component
- * (layout or page) set the title and `<meta>` / `<link>` tags; entries compose across the tree
- * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
- * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
- */
-import { useEffect, useLayoutEffect } from 'react';
-/** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
-export interface MetaTag {
-    readonly name?: string;
-    readonly property?: string;
-    readonly content: string;
-    readonly [attr: string]: string | undefined;
-}
-/** A `<link>` tag (deduped by `rel` + `href`); extra attrs pass through. */
-export interface LinkTag {
-    readonly rel: string;
-    readonly href: string;
-    readonly [attr: string]: string | undefined;
-}
-/** A head contribution from one component. */
-export interface HeadSpec {
-    /** Document title. */
-    readonly title?: string;
-    /** Template applied to a child's title, `%s` = the title (e.g. `'%s · toiljs'`). */
-    readonly titleTemplate?: string;
-    readonly meta?: readonly MetaTag[];
-    readonly link?: readonly LinkTag[];
-}
-/** The resolved head after merging all active specs. */
-export interface ResolvedHead {
-    readonly title?: string;
-    readonly meta: MetaTag[];
-    readonly link: LinkTag[];
-}
-function metaKey(m: MetaTag): string {
-    if (m.name !== undefined) return `name:${m.name}`;
-    if (m.property !== undefined) return `property:${m.property}`;
-    return `meta:${JSON.stringify(m)}`;
-}
-/**
- * Merges head specs in order: the last `title`/`titleTemplate` wins, `meta` dedupes by name/property
- * and `link` by rel+href (last wins). A `titleTemplate` formats the resolved title via `%s`.
- */
-export function mergeHead(specs: readonly HeadSpec[]): ResolvedHead {
-    let title: string | undefined;
-    let titleTemplate: string | undefined;
-    const meta = new Map<string, MetaTag>();
-    const link = new Map<string, LinkTag>();
-    for (const spec of specs) {
-        if (spec.title !== undefined) title = spec.title;
-        if (spec.titleTemplate !== undefined) titleTemplate = spec.titleTemplate;
-        for (const m of spec.meta ?? []) meta.set(metaKey(m), m);
-        for (const l of spec.link ?? []) link.set(`${l.rel}:${l.href}`, l);
-    }
-    const resolvedTitle =
-        title !== undefined && titleTemplate !== undefined
-            ? titleTemplate.replace('%s', title)
-            : title;
-    return { title: resolvedTitle, meta: [...meta.values()], link: [...link.values()] };
-}
-const entries = new Map<number, HeadSpec>();
-let order: number[] = [];
-let seq = 0;
-let baseTitle: string | null = null;
-// The current route's resolved `metadata` export. Merged LAST (highest priority), so a route's
-// metadata wins over a layout's `useHead`/`<Head>` defaults (e.g. a site-wide title/titleTemplate) for
-// the keys it sets, while the layout still fills everything the route leaves unset. Set by the router
-// via `setRouteHead` on each navigation.
-let routeHead: HeadSpec | null = null;
-function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
-    el.setAttribute('data-toil-head', '');
-    for (const [key, value] of Object.entries(attrs)) {
-        if (value !== undefined) el.setAttribute(key, value);
-    }
-}
-/** Reconciles `document.head` with the merged active specs. */
-function apply(): void {
-    if (typeof document === 'undefined') return;
-    if (baseTitle === null) baseTitle = document.title;
-    const specs = [...order.map((id) => entries.get(id)), routeHead];
-    const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
-    document.title = resolved.title ?? baseTitle;
-    for (const stale of document.head.querySelectorAll('[data-toil-head]')) stale.remove();
-    for (const m of resolved.meta) {
-        const el = document.createElement('meta');
-        setAttrs(el, m);
-        document.head.appendChild(el);
-    }
-    for (const l of resolved.link) {
-        const el = document.createElement('link');
-        setAttrs(el, l);
-        document.head.appendChild(el);
-    }
-}
-function addHead(spec: HeadSpec): number {
-    const id = ++seq;
-    entries.set(id, spec);
-    order.push(id);
-    apply();
-    return id;
-}
-function removeHead(id: number): void {
-    entries.delete(id);
-    order = order.filter((x) => x !== id);
-    apply();
-}
-/**
- * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
- * Reverts on unmount. Compose freely, a root layout can set defaults a page overrides.
- */
-export function useHead(spec: HeadSpec): void {
-    const json = JSON.stringify(spec);
-    useEffect(() => {
-        const id = addHead(JSON.parse(json) as HeadSpec);
-        return () => {
-            removeHead(id);
-        };
-    }, [json]);
-}
-/** Sets `document.title` for the calling component's lifetime. */
-export function useTitle(title: string): void {
-    useHead({ title });
-}
-/** Declarative form of {@link useHead}: `<Head title="…" meta={[…]} />`. Renders nothing. */
-export function Head(props: HeadSpec): null {
-    useHead(props);
-    return null;
-}
-/** Sets the current route's baseline head (lowest priority). Pass `null` to clear it. */
-export function setRouteHead(spec: HeadSpec | null): void {
-    routeHead = spec;
-    apply();
-}
-/**
- * Applies a route's resolved `metadata` as the baseline head for the calling route's lifetime, and
- * clears it on unmount. Used internally by the router; a layout-effect so the title updates before
- * paint (no flicker).
- */
-export function useRouteHead(spec: HeadSpec | undefined): void {
-    const json = spec ? JSON.stringify(spec) : '';
-    useLayoutEffect(() => {
-        setRouteHead(json ? (JSON.parse(json) as HeadSpec) : null);
-        return () => {
-            setRouteHead(null);
-        };
-    }, [json]);
-}
+/**
+ * Client-side document `<head>` management. `useHead` / `useTitle` / `<Head>` let any component
+ * (layout or page) set the title and `<meta>` / `<link>` tags; entries compose across the tree
+ * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
+ * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
+ */
+import { useEffect, useLayoutEffect } from 'react';
+/** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
+export interface MetaTag {
+    readonly name?: string;
+    readonly property?: string;
+    readonly content: string;
+    readonly [attr: string]: string | undefined;
+}
+/** A `<link>` tag (deduped by `rel` + `href`); extra attrs pass through. */
+export interface LinkTag {
+    readonly rel: string;
+    readonly href: string;
+    readonly [attr: string]: string | undefined;
+}
+/** A head contribution from one component. */
+export interface HeadSpec {
+    /** Document title. */
+    readonly title?: string;
+    /** Template applied to a child's title, `%s` = the title (e.g. `'%s · toiljs'`). */
+    readonly titleTemplate?: string;
+    readonly meta?: readonly MetaTag[];
+    readonly link?: readonly LinkTag[];
+}
+/** The resolved head after merging all active specs. */
+export interface ResolvedHead {
+    readonly title?: string;
+    readonly meta: MetaTag[];
+    readonly link: LinkTag[];
+}
+function metaKey(m: MetaTag): string {
+    if (m.name !== undefined) return `name:${m.name}`;
+    if (m.property !== undefined) return `property:${m.property}`;
+    return `meta:${JSON.stringify(m)}`;
+}
+/**
+ * Merges head specs in order: the last `title`/`titleTemplate` wins, `meta` dedupes by name/property
+ * and `link` by rel+href (last wins). A `titleTemplate` formats the resolved title via `%s`.
+ */
+export function mergeHead(specs: readonly HeadSpec[]): ResolvedHead {
+    let title: string | undefined;
+    let titleTemplate: string | undefined;
+    const meta = new Map<string, MetaTag>();
+    const link = new Map<string, LinkTag>();
+    for (const spec of specs) {
+        if (spec.title !== undefined) title = spec.title;
+        if (spec.titleTemplate !== undefined) titleTemplate = spec.titleTemplate;
+        for (const m of spec.meta ?? []) meta.set(metaKey(m), m);
+        for (const l of spec.link ?? []) link.set(`${l.rel}:${l.href}`, l);
+    }
+    const resolvedTitle =
+        title !== undefined && titleTemplate !== undefined
+            ? titleTemplate.replace('%s', title)
+            : title;
+    return { title: resolvedTitle, meta: [...meta.values()], link: [...link.values()] };
+}
+const entries = new Map<number, HeadSpec>();
+let order: number[] = [];
+let seq = 0;
+let baseTitle: string | null = null;
+// The current route's resolved `metadata` export. Merged LAST (highest priority), so a route's
+// metadata wins over a layout's `useHead`/`<Head>` defaults (e.g. a site-wide title/titleTemplate) for
+// the keys it sets, while the layout still fills everything the route leaves unset. Set by the router
+// via `setRouteHead` on each navigation.
+let routeHead: HeadSpec | null = null;
+function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
+    el.setAttribute('data-toil-head', '');
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value !== undefined) el.setAttribute(key, value);
+    }
+}
+/** Reconciles `document.head` with the merged active specs. */
+function apply(): void {
+    if (typeof document === 'undefined') return;
+    if (baseTitle === null) baseTitle = document.title;
+    const specs = [...order.map((id) => entries.get(id)), routeHead];
+    const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
+    document.title = resolved.title ?? baseTitle;
+    for (const stale of document.head.querySelectorAll('[data-toil-head]')) stale.remove();
+    for (const m of resolved.meta) {
+        const el = document.createElement('meta');
+        setAttrs(el, m);
+        document.head.appendChild(el);
+    }
+    for (const l of resolved.link) {
+        const el = document.createElement('link');
+        setAttrs(el, l);
+        document.head.appendChild(el);
+    }
+}
+function addHead(spec: HeadSpec): number {
+    const id = ++seq;
+    entries.set(id, spec);
+    order.push(id);
+    apply();
+    return id;
+}
+function removeHead(id: number): void {
+    entries.delete(id);
+    order = order.filter((x) => x !== id);
+    apply();
+}
+/**
+ * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
+ * Reverts on unmount. Compose freely, a root layout can set defaults a page overrides.
+ */
+export function useHead(spec: HeadSpec): void {
+    const json = JSON.stringify(spec);
+    useEffect(() => {
+        const id = addHead(JSON.parse(json) as HeadSpec);
+        return () => {
+            removeHead(id);
+        };
+    }, [json]);
+}
+/** Sets `document.title` for the calling component's lifetime. */
+export function useTitle(title: string): void {
+    useHead({ title });
+}
+/** Declarative form of {@link useHead}: `<Head title="…" meta={[…]} />`. Renders nothing. */
+export function Head(props: HeadSpec): null {
+    useHead(props);
+    return null;
+}
+/** Sets the current route's baseline head (lowest priority). Pass `null` to clear it. */
+export function setRouteHead(spec: HeadSpec | null): void {
+    routeHead = spec;
+    apply();
+}
+/**
+ * Applies a route's resolved `metadata` as the baseline head for the calling route's lifetime, and
+ * clears it on unmount. Used internally by the router; a layout-effect so the title updates before
+ * paint (no flicker).
+ */
+export function useRouteHead(spec: HeadSpec | undefined): void {
+    const json = spec ? JSON.stringify(spec) : '';
+    useLayoutEffect(() => {
+        setRouteHead(json ? (JSON.parse(json) as HeadSpec) : null);
+        return () => {
+            setRouteHead(null);
+        };
+    }, [json]);
+}

package/src/client/head/metadata.ts CHANGED Viewed

@@ -4,7 +4,7 @@
  * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
  * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
  */
-import type { HeadSpec, LinkTag, MetaTag } from './head.js';
+import { useHead, type HeadSpec, type LinkTag, type MetaTag } from './head.js';
 import type { RouteParams } from '../routing/match.js';
 /** OpenGraph fields, expanded to `og:*` meta tags. */
@@ -92,3 +92,21 @@ export function resolveMetadata(metadata: Metadata): HeadSpec {
     return { title: metadata.title, titleTemplate: metadata.titleTemplate, meta, link };
 }
+/**
+ * Applies a route-style {@link Metadata} object from inside any component for that component's
+ * lifetime, reverting on unmount. The runtime counterpart of a route's `metadata` export, for
+ * content that isn't itself a route file (a rendered article, a widget, ...). Composes through the
+ * head manager like {@link useHead}; a route's own `metadata` (applied last) still wins for keys it
+ * sets, so this fills in for routes that declare none. Resolved fresh each render, the head manager
+ * dedupes by value, so passing a computed object is fine.
+ */
+export function useMetadata(metadata: Metadata): void {
+    useHead(resolveMetadata(metadata));
+}
+/** Declarative form of {@link useMetadata}: `<Metadata title="…" openGraph={…} />`. Renders nothing. */
+export function Metadata(props: Metadata): null {
+    useMetadata(props);
+    return null;
+}

package/src/client/index.ts CHANGED Viewed

@@ -14,7 +14,15 @@ export { Link } from './navigation/Link.js';
 export type { LinkProps } from './navigation/Link.js';
 export { NavLink, matchActive } from './navigation/NavLink.js';
 export type { NavLinkProps, NavLinkState } from './navigation/NavLink.js';
-export { navigate, back, forward, refresh, setViewTransitions } from './navigation/navigation.js';
+export {
+    navigate,
+    back,
+    forward,
+    refresh,
+    setViewTransitions,
+    setTransitions,
+    href,
+} from './navigation/navigation.js';
 export type { NavigateOptions } from './navigation/navigation.js';
 export {
     useParams,
@@ -27,7 +35,14 @@ export {
 } from './routing/hooks.js';
 export type { RouterInstance } from './routing/hooks.js';
 export { useLoaderData, revalidate, invalidateLoaderData } from './routing/loader.js';
-export type { LoaderArgs, LoaderFunction, LoaderData, Revalidate } from './routing/loader.js';
+export type {
+    LoaderArgs,
+    LoaderFunction,
+    LoaderData,
+    Revalidate,
+    StaticParams,
+    GenerateStaticParams,
+} from './routing/loader.js';
 export { useAction } from './routing/action.js';
 export type {
     UseActionOptions,
@@ -52,13 +67,8 @@ export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel
 export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
 export { useHead, useTitle, Head, mergeHead } from './head/head.js';
 export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
-export { resolveMetadata } from './head/metadata.js';
-export type {
-    Metadata,
-    GenerateMetadata,
-    GenerateMetadataArgs,
-    OpenGraph,
-} from './head/metadata.js';
+export { resolveMetadata, useMetadata, Metadata } from './head/metadata.js';
+export type { GenerateMetadata, GenerateMetadataArgs, OpenGraph } from './head/metadata.js';
 export { searchPages, registerPages, getPages, pagePath } from './search/search.js';
 export type {
     PageMeta,

package/src/client/navigation/NavLink.tsx CHANGED Viewed

@@ -1,86 +1,86 @@
-import type { CSSProperties, ReactNode } from 'react';
-import { useLocation } from '../routing/hooks.js';
-import { Link, type LinkProps } from './Link.js';
-/** State passed to `NavLink`'s function-form `className` / `style` / `children`. */
-export interface NavLinkState {
-    readonly isActive: boolean;
-}
-/**
- * Props for {@link NavLink}: all {@link LinkProps}, but `className` / `style` / `children` may also
- * be functions of the active state.
- */
-export interface NavLinkProps extends Omit<LinkProps, 'className' | 'style' | 'children'> {
-    className?: string | ((state: NavLinkState) => string | undefined);
-    style?: CSSProperties | ((state: NavLinkState) => CSSProperties | undefined);
-    children?: ReactNode | ((state: NavLinkState) => ReactNode);
-    /** Match `href` exactly; without it, sub-paths are also active. Default `false`. */
-    end?: boolean;
-    /** Class added when active (used with a string `className`). Default `"active"`. */
-    activeClassName?: string;
-}
-function normalizePath(p: string): string {
-    return p.length > 1 ? p.replace(/\/+$/, '') : p;
-}
-/**
- * Whether a link to `linkPath` is active for `currentPath`. Exact when `end`; otherwise a parent
- * path is active for its sub-paths (and `/` is active everywhere, matching React Router).
- */
-export function matchActive(linkPath: string, currentPath: string, end: boolean): boolean {
-    const link = normalizePath(linkPath);
-    const current = normalizePath(currentPath);
-    if (current === link) return true;
-    if (end) return false;
-    if (link === '/') return true;
-    return current.startsWith(link + '/');
-}
-/**
- * A {@link Link} that knows whether it points at the current location. Applies an active class
- * (default `"active"`) and `aria-current="page"` when active; `className` / `style` / `children`
- * may be functions of `{ isActive }`. Inherits Link's full anchor API and prefetching.
- */
-export function NavLink(props: NavLinkProps): ReactNode {
-    const {
-        href,
-        className,
-        style,
-        children,
-        end = false,
-        activeClassName = 'active',
-        ...rest
-    } = props;
-    const pathname = useLocation();
-    let linkPath = href;
-    try {
-        linkPath = new URL(href, window.location.href).pathname;
-    } catch {
-        linkPath = href;
-    }
-    const isActive = matchActive(linkPath, pathname, end);
-    const state: NavLinkState = { isActive };
-    const resolvedClassName =
-        typeof className === 'function'
-            ? className(state)
-            : [className, isActive ? activeClassName : undefined].filter(Boolean).join(' ') ||
-              undefined;
-    const resolvedStyle = typeof style === 'function' ? style(state) : style;
-    const resolvedChildren = typeof children === 'function' ? children(state) : children;
-    return (
-        <Link
-            {...rest}
-            href={href}
-            className={resolvedClassName}
-            style={resolvedStyle}
-            aria-current={isActive ? 'page' : undefined}>
-            {resolvedChildren}
-        </Link>
-    );
-}
+import type { CSSProperties, ReactNode } from 'react';
+import { useLocation } from '../routing/hooks.js';
+import { Link, type LinkProps } from './Link.js';
+/** State passed to `NavLink`'s function-form `className` / `style` / `children`. */
+export interface NavLinkState {
+    readonly isActive: boolean;
+}
+/**
+ * Props for {@link NavLink}: all {@link LinkProps}, but `className` / `style` / `children` may also
+ * be functions of the active state.
+ */
+export interface NavLinkProps extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+    className?: string | ((state: NavLinkState) => string | undefined);
+    style?: CSSProperties | ((state: NavLinkState) => CSSProperties | undefined);
+    children?: ReactNode | ((state: NavLinkState) => ReactNode);
+    /** Match `href` exactly; without it, sub-paths are also active. Default `false`. */
+    end?: boolean;
+    /** Class added when active (used with a string `className`). Default `"active"`. */
+    activeClassName?: string;
+}
+function normalizePath(p: string): string {
+    return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
+/**
+ * Whether a link to `linkPath` is active for `currentPath`. Exact when `end`; otherwise a parent
+ * path is active for its sub-paths (and `/` is active everywhere, matching React Router).
+ */
+export function matchActive(linkPath: string, currentPath: string, end: boolean): boolean {
+    const link = normalizePath(linkPath);
+    const current = normalizePath(currentPath);
+    if (current === link) return true;
+    if (end) return false;
+    if (link === '/') return true;
+    return current.startsWith(link + '/');
+}
+/**
+ * A {@link Link} that knows whether it points at the current location. Applies an active class
+ * (default `"active"`) and `aria-current="page"` when active; `className` / `style` / `children`
+ * may be functions of `{ isActive }`. Inherits Link's full anchor API and prefetching.
+ */
+export function NavLink(props: NavLinkProps): ReactNode {
+    const {
+        href,
+        className,
+        style,
+        children,
+        end = false,
+        activeClassName = 'active',
+        ...rest
+    } = props;
+    const pathname = useLocation();
+    let linkPath = href;
+    try {
+        linkPath = new URL(href, window.location.href).pathname;
+    } catch {
+        linkPath = href;
+    }
+    const isActive = matchActive(linkPath, pathname, end);
+    const state: NavLinkState = { isActive };
+    const resolvedClassName =
+        typeof className === 'function'
+            ? className(state)
+            : [className, isActive ? activeClassName : undefined].filter(Boolean).join(' ') ||
+              undefined;
+    const resolvedStyle = typeof style === 'function' ? style(state) : style;
+    const resolvedChildren = typeof children === 'function' ? children(state) : children;
+    return (
+        <Link
+            {...rest}
+            href={href}
+            className={resolvedClassName}
+            style={resolvedStyle}
+            aria-current={isActive ? 'page' : undefined}>
+            {resolvedChildren}
+        </Link>
+    );
+}