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

toiljs 0.0.15 → 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 (217) 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 +0 -0
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/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 +23 -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 +16 -0
package/build/compiler/config.js +7 -0
package/build/compiler/docs.js +16 -16
package/build/compiler/index.d.ts +2 -2
package/build/compiler/index.js +1 -1
package/build/compiler/plugin.js +156 -0
package/build/compiler/prerender.d.ts +1 -0
package/build/compiler/prerender.js +1 -1
package/build/compiler/seo.d.ts +1 -1
package/build/compiler/seo.js +5 -4
package/build/compiler/ssg.js +32 -1
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 -148
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 +112 -112
package/src/client/index.ts +89 -89
package/src/client/navigation/NavLink.tsx +86 -86
package/src/client/navigation/navigation.ts +235 -235
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 -235
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 +219 -182
package/src/compiler/docs.ts +228 -228
package/src/compiler/generate.ts +394 -394
package/src/compiler/index.ts +64 -57
package/src/compiler/pages.ts +70 -70
package/src/compiler/plugin.ts +170 -2
package/src/compiler/prerender.ts +156 -156
package/src/compiler/seo.ts +397 -390
package/src/compiler/ssg.ts +162 -126
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 -58
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 -36
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

@@ -1,112 +1,112 @@
-/**
- * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
- * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
- * 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 { useHead, type HeadSpec, type LinkTag, type MetaTag } from './head.js';
-import type { RouteParams } from '../routing/match.js';
-/** OpenGraph fields, expanded to `og:*` meta tags. */
-export interface OpenGraph {
-    readonly title?: string;
-    readonly description?: string;
-    readonly type?: string;
-    readonly url?: string;
-    readonly image?: string;
-    readonly siteName?: string;
-}
-/** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
-export interface Metadata {
-    /** Document title. */
-    readonly title?: string;
-    /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
-    readonly titleTemplate?: string;
-    /** `<meta name="description">`. */
-    readonly description?: string;
-    /** `<meta name="keywords">`, joined with `, ` if an array. */
-    readonly keywords?: string | readonly string[];
-    /** `<link rel="canonical">`. */
-    readonly canonical?: string;
-    /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
-    readonly robots?: string;
-    /** `<meta name="theme-color">`. */
-    readonly themeColor?: string;
-    /** OpenGraph (`og:*`) tags. */
-    readonly openGraph?: OpenGraph;
-    /** Escape hatch: extra raw `<meta>` tags. */
-    readonly meta?: readonly MetaTag[];
-    /** Escape hatch: extra raw `<link>` tags. */
-    readonly link?: readonly LinkTag[];
-}
-/** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
-export interface GenerateMetadataArgs<T = unknown> {
-    readonly params: RouteParams;
-    readonly searchParams: URLSearchParams;
-    readonly data: T;
-}
-/** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
-export type GenerateMetadata<T = unknown> = (
-    args: GenerateMetadataArgs<T>,
-) => Metadata | Promise<Metadata>;
-/** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
-export function resolveMetadata(metadata: Metadata): HeadSpec {
-    const meta: MetaTag[] = [];
-    if (metadata.description !== undefined) {
-        meta.push({ name: 'description', content: metadata.description });
-    }
-    if (metadata.keywords !== undefined) {
-        const content =
-            typeof metadata.keywords === 'string'
-                ? metadata.keywords
-                : metadata.keywords.join(', ');
-        meta.push({ name: 'keywords', content });
-    }
-    if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
-    if (metadata.themeColor !== undefined) {
-        meta.push({ name: 'theme-color', content: metadata.themeColor });
-    }
-    const og = metadata.openGraph;
-    if (og) {
-        const pairs: readonly [string, string | undefined][] = [
-            ['og:title', og.title],
-            ['og:description', og.description],
-            ['og:type', og.type],
-            ['og:url', og.url],
-            ['og:image', og.image],
-            ['og:site_name', og.siteName],
-        ];
-        for (const [property, content] of pairs) {
-            if (content !== undefined) meta.push({ property, content });
-        }
-    }
-    if (metadata.meta) meta.push(...metadata.meta);
-    const link: LinkTag[] = [];
-    if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
-    if (metadata.link) link.push(...metadata.link);
-    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;
-}
+/**
+ * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
+ * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
+ * 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 { useHead, type HeadSpec, type LinkTag, type MetaTag } from './head.js';
+import type { RouteParams } from '../routing/match.js';
+/** OpenGraph fields, expanded to `og:*` meta tags. */
+export interface OpenGraph {
+    readonly title?: string;
+    readonly description?: string;
+    readonly type?: string;
+    readonly url?: string;
+    readonly image?: string;
+    readonly siteName?: string;
+}
+/** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
+export interface Metadata {
+    /** Document title. */
+    readonly title?: string;
+    /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
+    readonly titleTemplate?: string;
+    /** `<meta name="description">`. */
+    readonly description?: string;
+    /** `<meta name="keywords">`, joined with `, ` if an array. */
+    readonly keywords?: string | readonly string[];
+    /** `<link rel="canonical">`. */
+    readonly canonical?: string;
+    /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
+    readonly robots?: string;
+    /** `<meta name="theme-color">`. */
+    readonly themeColor?: string;
+    /** OpenGraph (`og:*`) tags. */
+    readonly openGraph?: OpenGraph;
+    /** Escape hatch: extra raw `<meta>` tags. */
+    readonly meta?: readonly MetaTag[];
+    /** Escape hatch: extra raw `<link>` tags. */
+    readonly link?: readonly LinkTag[];
+}
+/** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
+export interface GenerateMetadataArgs<T = unknown> {
+    readonly params: RouteParams;
+    readonly searchParams: URLSearchParams;
+    readonly data: T;
+}
+/** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
+export type GenerateMetadata<T = unknown> = (
+    args: GenerateMetadataArgs<T>,
+) => Metadata | Promise<Metadata>;
+/** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
+export function resolveMetadata(metadata: Metadata): HeadSpec {
+    const meta: MetaTag[] = [];
+    if (metadata.description !== undefined) {
+        meta.push({ name: 'description', content: metadata.description });
+    }
+    if (metadata.keywords !== undefined) {
+        const content =
+            typeof metadata.keywords === 'string'
+                ? metadata.keywords
+                : metadata.keywords.join(', ');
+        meta.push({ name: 'keywords', content });
+    }
+    if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
+    if (metadata.themeColor !== undefined) {
+        meta.push({ name: 'theme-color', content: metadata.themeColor });
+    }
+    const og = metadata.openGraph;
+    if (og) {
+        const pairs: readonly [string, string | undefined][] = [
+            ['og:title', og.title],
+            ['og:description', og.description],
+            ['og:type', og.type],
+            ['og:url', og.url],
+            ['og:image', og.image],
+            ['og:site_name', og.siteName],
+        ];
+        for (const [property, content] of pairs) {
+            if (content !== undefined) meta.push({ property, content });
+        }
+    }
+    if (metadata.meta) meta.push(...metadata.meta);
+    const link: LinkTag[] = [];
+    if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
+    if (metadata.link) link.push(...metadata.link);
+    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;
+}