toiljs 0.0.8 → 0.0.9

package/src/cli/configure.ts

@@ -1,5 +1,5 @@
 /**
- * `toiljs configure` — toggle a project's client styling features (CSS preprocessor + Tailwind) on
+ * `toiljs configure`, toggle a project's client styling features (CSS preprocessor + Tailwind) on
  * an existing app. Detects the current setup, prompts for the desired one, then rewrites the
  * stylesheet(s) + the `client/toil.tsx` imports, edits `package.json`, and syncs node_modules with
  * the project's package manager (so removed features are fully cleaned, not just disabled).
@@ -173,7 +173,7 @@ async function applyStyleFiles(
         const newPath = path.join(clientDir, styleEntry(to.preprocessor));
         await fs.mkdir(path.dirname(newPath), { recursive: true });
         // Rename whatever main stylesheet actually exists (preserving its content), not an assumed
-        // name — so we never blow away the user's styles when the on-disk extension differs.
+        // name, so we never blow away the user's styles when the on-disk extension differs.
         const existing = await findMainStylesheet(clientDir);
         if (existing && path.resolve(existing) !== path.resolve(newPath)) {
             await fs.rename(existing, newPath);
@@ -265,7 +265,7 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
     try {
         pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8')) as PackageJson;
     } catch {
-        cancel(`No package.json in ${pc.cyan(root)} — run this inside a toiljs project.`);
+        cancel(`No package.json in ${pc.cyan(root)}, run this inside a toiljs project.`);
         process.exit(1);
     }
 
@@ -310,7 +310,7 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
         target.preprocessor !== current.preprocessor || target.tailwind !== current.tailwind;
     const imagesChanged = targetImages !== currentImages;
     if (!styleChanged && !imagesChanged) {
-        outro('No changes — your setup is already up to date.');
+        outro('No changes, your setup is already up to date.');
         return;
     }
 
@@ -320,7 +320,7 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
     let imagesWarning = '';
     if (imagesChanged && !(await writeImagesFlag(root, targetImages))) {
         imagesWarning = pc.yellow(
-            ' Could not edit toil.config automatically — set `client.images` by hand.',
+            ' Could not edit toil.config automatically, set `client.images` by hand.',
         );
     }
     s.stop('Updated project files');
@@ -336,7 +336,7 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
                 await run(pm, ['install'], root);
                 i.stop('Dependencies synced');
             } catch {
-                i.stop(pc.yellow(`Could not run \`${pm} install\` — run it yourself to finish`));
+                i.stop(pc.yellow(`Could not run \`${pm} install\`, run it yourself to finish`));
             }
         }
     }
@@ -349,5 +349,5 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
         .filter(Boolean)
         .join('\n');
     note(summary, 'Updated');
-    outro(`Reconfigured — restart \`${accent('toiljs dev')}\` to pick up the changes.`);
+    outro(`Reconfigured, restart \`${accent('toiljs dev')}\` to pick up the changes.`);
 }

package/src/cli/create.ts

@@ -1,5 +1,5 @@
 /**
- * `toiljs create` — an interactive project scaffolder (Clack-powered) that wires a new
+ * `toiljs create`, an interactive project scaffolder (Clack-powered) that wires a new
  * app to the enforced toiljs presets (tsconfig / eslint / prettier) and file-based routing.
  * Supports a non-interactive path via flags (`--yes`, `--template`, …) for scripting/CI.
  */
@@ -161,7 +161,7 @@ function scaffold(
             JSON.stringify({ 'typescript.tsdk': 'node_modules/typescript/lib' }, null, 4) + '\n',
         'toil-env.d.ts': TOIL_ENV_DTS,
         // Stub typed-routes augmentation (RoutePath = string until the first dev/build regenerates it).
-        'toil-routes.d.ts': '// AUTO-GENERATED by toil — do not edit.\nexport {};\n',
+        'toil-routes.d.ts': '// AUTO-GENERATED by toil, do not edit.\nexport {};\n',
         'toilconfig.json':
             JSON.stringify(
                 {
@@ -312,7 +312,7 @@ export default function Layout({ children }: { children?: ReactNode }) {
 
 /**
  * Absolute path to the `app` starter client UI. There is a single source: `examples/basic/client`
- * (shipped in the package) — the runnable example IS the create template, so there's nothing to
+ * (shipped in the package), the runnable example IS the create template, so there's nothing to
  * keep in sync.
  */
 function appClientDir(): string {
@@ -331,7 +331,7 @@ function appClientDir(): string {
  * preprocessor's extension, adds the Tailwind entry, and rewrites `toil.tsx`'s style imports.
  */
 async function applyStyling(clientDir: string, features: StyleFeatures): Promise<void> {
-    // Plain CSS without Tailwind is exactly what the template ships — leave it byte-for-byte.
+    // Plain CSS without Tailwind is exactly what the template ships, leave it byte-for-byte.
     if (features.preprocessor === 'css' && !features.tailwind) return;
     const entry = styleEntry(features.preprocessor);
     if (entry !== 'styles/main.css') {
@@ -406,7 +406,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     let template: Template = opts.template ?? 'app';
     if (!opts.template && !opts.yes) {
         const templateOptions: TemplateOption[] = [
-            { value: 'app', label: 'App', hint: 'the full ToilJS starter — landing page, layout, styles, demo routes' },
+            { value: 'app', label: 'App', hint: 'the full ToilJS starter, landing page, layout, styles, demo routes' },
             { value: 'minimal', label: 'Minimal', hint: 'just a layout and a home route' },
         ];
         const choice = await select({ message: 'Which template?', options: templateOptions, initialValue: 'app' });
@@ -514,7 +514,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
             await run(pm, ['install'], targetDir);
             i.stop('Installed dependencies');
         } catch {
-            i.stop(pc.yellow(`Could not install with ${pm} — run it yourself later`));
+            i.stop(pc.yellow(`Could not install with ${pm}, run it yourself later`));
             install = false;
         }
     }
@@ -526,5 +526,5 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     steps.push(`${accent('npm run build')} ${dim('build for production')}`);
     note(steps.map((l) => dim('  ') + l).join('\n'), 'Next steps');
 
-    outro(`Created ${accent(path.basename(name))} — happy building! ${dim('· v' + version())}`);
+    outro(`Created ${accent(path.basename(name))}, happy building! ${dim('· v' + version())}`);
 }

package/src/cli/features.ts

@@ -1,5 +1,5 @@
 /**
- * Pure description of toiljs's optional client styling features — a CSS preprocessor and Tailwind —
+ * Pure description of toiljs's optional client styling features, a CSS preprocessor and Tailwind , 
  * shared by `create` (scaffold) and `configure` (toggle on existing projects). Dependency-light
  * (no node IO) so it can be unit-tested; the file writes and package-manager calls live in the
  * commands. Preprocessor and Tailwind are independent: Tailwind lives in its own `.css` entry so
@@ -128,7 +128,7 @@ export function defaultConfigSource(images: boolean): string {
 }
 
 /**
- * Sets the `client.images` flag in a `toil.config` source, returning the updated source — or `null`
+ * Sets the `client.images` flag in a `toil.config` source, returning the updated source, or `null`
  * if the file's shape isn't recognized (the caller should then fall back to a manual note). Handles
  * an existing `images:` value, an existing `client: {` block, or a bare `defineConfig({ … })`.
  */

package/src/cli/index.ts

@@ -2,7 +2,7 @@
 /**
  * toiljs CLI. Routes `create` / `dev` / `build` and wraps them in the toiljs brand banner.
  * The compiler stays presentation-free (imported via the package's own `toiljs/compiler`
- * export); the epic bits — banner, the Clack scaffolding wizard — live here.
+ * export); the epic bits, banner, the Clack scaffolding wizard, live here.
  */
 import { build, dev, start } from 'toiljs/compiler';
 

package/src/cli/ui.ts

@@ -54,7 +54,7 @@ export function success(s: string): string {
     return rgb(ACCENT, s);
 }
 
-/** Error accent (red — kept outside the brand palette since errors should read as errors). */
+/** Error accent (red, kept outside the brand palette since errors should read as errors). */
 export const danger = pc.red;
 
 function lerp(a: number, b: number, t: number): number {

package/src/cli/validate.ts

@@ -1,5 +1,5 @@
 /**
- * Pure input validation for `toiljs create` — kept dependency-light (only node:path) so it can be
+ * Pure input validation for `toiljs create`, kept dependency-light (only node:path) so it can be
  * unit-tested without pulling in the rest of the CLI.
  */
 import path from 'node:path';

package/src/client/components/Form.tsx

@@ -16,7 +16,7 @@ export interface FormProps {
     resetOnSuccess?: boolean;
     className?: string;
     /**
-     * Form contents. Pass a render function to receive live submit state — e.g. to disable the
+     * Form contents. Pass a render function to receive live submit state, e.g. to disable the
      * button while pending: `{({ pending }) => <button disabled={pending}>Save</button>}`.
      */
     children?: ReactNode | ((state: ActionState<void>) => ReactNode);
@@ -24,7 +24,7 @@ export interface FormProps {
 
 /**
  * A `<form>` that runs an {@link useAction} on submit (no page reload) and revalidates loader data
- * on success — the write half of the loader/action data loop. Tracks pending/error state, which a
+ * on success, the write half of the loader/action data loop. Tracks pending/error state, which a
  * render-function child can read.
  */
 export function Form({

package/src/client/components/Image.tsx

@@ -2,7 +2,7 @@ import { useState, type CSSProperties, type ComponentPropsWithRef, type ReactNod
 
 /**
  * Props for {@link Image}: every standard `<img>` attribute, plus toil's layout/loading controls.
- * `src` and `alt` are required (`alt` is enforced for accessibility — pass `alt=""` for decorative
+ * `src` and `alt` are required (`alt` is enforced for accessibility, pass `alt=""` for decorative
  * images). `width`/`height` (or `fill`) reserve space to prevent layout shift.
  */
 export interface ImageProps
@@ -35,7 +35,7 @@ export interface ImageProps
 /**
  * A drop-in `<img>` replacement that prevents layout shift and lazy-loads by default. It reserves
  * space from `width`/`height` (or fills its container with `fill`), decodes async, lazy-loads unless
- * `priority`, and can fade in from a `blur` placeholder. This is a client-only component — there is
+ * `priority`, and can fade in from a `blur` placeholder. This is a client-only component, there is
  * no server-side resizing; pass an already-optimized `src` (Vite hashes imported assets for you).
  */
 export function Image(props: ImageProps): ReactNode {

package/src/client/components/Script.tsx

@@ -2,9 +2,9 @@ import { useEffect, type ReactNode } from 'react';
 
 /**
  * When a {@link Script} is injected, relative to the app becoming interactive:
- * - `afterInteractive` (default) — on mount, once the app is running. Good for analytics, widgets.
- * - `lazyOnload` — deferred until the browser is idle (after `window.load`). For low-priority scripts.
- * - `beforeInteractive` — as early as possible. In a client-only SPA there is no SSR, so this still
+ * - `afterInteractive` (default), on mount, once the app is running. Good for analytics, widgets.
+ * - `lazyOnload`, deferred until the browser is idle (after `window.load`). For low-priority scripts.
+ * - `beforeInteractive`, as early as possible. In a client-only SPA there is no SSR, so this still
  *   runs after hydration, but synchronously on first mount with high fetch priority.
  */
 export type ScriptStrategy = 'beforeInteractive' | 'afterInteractive' | 'lazyOnload';

package/src/client/components/Slot.tsx

@@ -0,0 +1,21 @@
+import { useContext, type ReactNode } from 'react';
+
+import { SlotContext } from '../routing/slot-context.js';
+
+/** Props for {@link Slot}. */
+export interface SlotProps {
+    /** The parallel-slot name, the `@name` directory under `routes/` (without the `@`). */
+    name: string;
+    /** Rendered when the slot has no match for the current URL. Default `null`. */
+    fallback?: ReactNode;
+}
+
+/**
+ * Renders the parallel-route slot named `name` for the current URL. Place it in a layout or page to
+ * show an `@name` route tree alongside the main content (e.g. a persistent sidebar, or a modal that
+ * an intercepting route fills). Renders `fallback` (default nothing) when no slot route matches.
+ */
+export function Slot({ name, fallback = null }: SlotProps): ReactNode {
+    const slots = useContext(SlotContext);
+    return slots[name] ?? fallback;
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Development-only error overlay. In dev, surfaces errors that would otherwise leave a blank page or
+ * live only in the console: uncaught render errors (incl. those thrown by a loader during render),
+ * plus `window` `error` / `unhandledrejection` events. Shows the message, stack, and (for render
+ * errors) the React component stack, with Dismiss / Reload. Inert in production builds.
+ */
+import {
+    Component,
+    useSyncExternalStore,
+    type CSSProperties,
+    type ErrorInfo,
+    type ReactNode,
+} from 'react';
+
+/** A captured dev error. */
+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';
+}
+
+let current: DevError | null = null;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+    for (const listener of listeners) listener();
+}
+function setDevError(next: DevError | null): void {
+    current = next;
+    emit();
+}
+function subscribe(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+
+/** True when running under Vite's dev server (replaced at build time; falsy in production). */
+export function isDevMode(): boolean {
+    try {
+        return Boolean((import.meta as { env?: { DEV?: boolean } }).env?.DEV);
+    } catch {
+        return false;
+    }
+}
+
+let windowBound = false;
+/** Wires `window` error / unhandledrejection into the overlay (idempotent; dev only). */
+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' });
+    });
+    window.addEventListener('unhandledrejection', (event) => {
+        const reason: unknown = event.reason;
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        setDevError({ error, source: 'unhandledrejection' });
+    });
+}
+
+interface BoundaryProps {
+    readonly children: ReactNode;
+}
+interface BoundaryState {
+    readonly crashed: boolean;
+}
+
+/**
+ * Catches render errors in its subtree and reports them to the overlay. While crashed it renders
+ * nothing (the subtree threw); it recovers when the overlay is dismissed. Class component because
+ * React error boundaries have no hook equivalent.
+ */
+export class DevErrorBoundary extends Component<BoundaryProps, BoundaryState> {
+    public state: BoundaryState = { crashed: false };
+    private unsubscribe: (() => void) | undefined;
+
+    public static getDerivedStateFromError(): BoundaryState {
+        return { crashed: true };
+    }
+
+    public override componentDidCatch(error: Error, info: ErrorInfo): void {
+        setDevError({ error, componentStack: info.componentStack ?? undefined, source: 'render' });
+    }
+
+    public override componentDidMount(): void {
+        // Recover (re-render children) once the error is dismissed from the overlay.
+        this.unsubscribe = subscribe(() => {
+            if (current === null && this.state.crashed) this.setState({ crashed: false });
+        });
+    }
+
+    public override componentWillUnmount(): void {
+        this.unsubscribe?.();
+    }
+
+    public override render(): ReactNode {
+        return this.state.crashed ? null : this.props.children;
+    }
+}
+
+const overlayStyle: CSSProperties = {
+    position: 'fixed',
+    inset: 0,
+    zIndex: 2147483647,
+    background: 'rgba(8, 8, 12, 0.88)',
+    color: '#f5f6fa',
+    font: '13px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace',
+    padding: '2rem',
+    overflow: 'auto',
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'flex-start',
+};
+const panelStyle: CSSProperties = {
+    maxWidth: 900,
+    width: '100%',
+    background: '#15151c',
+    border: '1px solid #ef4444',
+    borderRadius: 10,
+    padding: '1.25rem 1.5rem',
+    boxShadow: '0 12px 48px rgba(0,0,0,0.5)',
+};
+const titleStyle: CSSProperties = {
+    margin: 0,
+    color: '#ff6b6b',
+    fontSize: '1rem',
+    fontWeight: 700,
+    wordBreak: 'break-word',
+};
+const preStyle: CSSProperties = {
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+    margin: '0.75rem 0 0',
+    color: '#c8cee0',
+};
+const buttonStyle: CSSProperties = {
+    font: 'inherit',
+    color: '#f5f6fa',
+    background: '#2a2a36',
+    border: '1px solid #3a3a48',
+    borderRadius: 6,
+    padding: '0.4em 1em',
+    cursor: 'pointer',
+    marginRight: '0.5rem',
+};
+
+const SOURCE_LABEL: Record<DevError['source'], string> = {
+    render: 'Render error',
+    window: 'Uncaught error',
+    unhandledrejection: 'Unhandled promise rejection',
+};
+
+/** Renders the overlay when a dev error is captured. Mount once at the app root (dev only). */
+export function DevErrorOverlay(): ReactNode {
+    const devError = useSyncExternalStore(
+        subscribe,
+        () => current,
+        () => null,
+    );
+    if (!devError) return null;
+    return (
+        <div
+            style={overlayStyle}
+            role="alert">
+            <div style={panelStyle}>
+                <p style={titleStyle}>
+                    {SOURCE_LABEL[devError.source]}, {devError.error.name}: {devError.error.message}
+                </p>
+                {devError.error.stack !== undefined && <pre style={preStyle}>{devError.error.stack}</pre>}
+                {devError.componentStack !== undefined && (
+                    <pre style={{ ...preStyle, color: '#8b9ab4' }}>{devError.componentStack}</pre>
+                )}
+                <div style={{ marginTop: '1.25rem' }}>
+                    <button
+                        type="button"
+                        style={buttonStyle}
+                        onClick={() => {
+                            setDevError(null);
+                        }}>
+                        Dismiss
+                    </button>
+                    <button
+                        type="button"
+                        style={buttonStyle}
+                        onClick={() => {
+                            window.location.reload();
+                        }}>
+                        Reload
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}

package/src/client/head/head.ts

@@ -4,7 +4,7 @@
  * (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 } from 'react';
+import { useEffect, useLayoutEffect } from 'react';
 
 /** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
 export interface MetaTag {
@@ -70,6 +70,9 @@ const entries = new Map<number, HeadSpec>();
 let order: number[] = [];
 let seq = 0;
 let baseTitle: string | null = null;
+// The current route's resolved metadata, the lowest-priority spec, so component `useHead`/`<Head>`
+// always compose on top of it. 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', '');
@@ -83,7 +86,8 @@ function apply(): void {
     if (typeof document === 'undefined') return;
     if (baseTitle === null) baseTitle = document.title;
 
-    const resolved = mergeHead(order.map((id) => entries.get(id)).filter((s): s is HeadSpec => !!s));
+    const specs = [routeHead, ...order.map((id) => entries.get(id))];
+    const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
 
     document.title = resolved.title ?? baseTitle;
 
@@ -116,7 +120,7 @@ function removeHead(id: number): void {
 
 /**
  * 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.
+ * 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);
@@ -138,3 +142,24 @@ 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

@@ -0,0 +1,92 @@
+/**
+ * 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 type { HeadSpec, LinkTag, 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 };
+}

package/src/client/index.ts

@@ -14,7 +14,7 @@ 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 } from './navigation/navigation.js';
+export { navigate, back, forward, refresh, setViewTransitions } from './navigation/navigation.js';
 export type { NavigateOptions } from './navigation/navigation.js';
 export {
     useParams,
@@ -52,9 +52,13 @@ 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 { Image } from './components/Image.js';
 export type { ImageProps } from './components/Image.js';
 export { Script } from './components/Script.js';
 export type { ScriptProps, ScriptStrategy } from './components/Script.js';
 export { Form } from './components/Form.js';
 export type { FormProps } from './components/Form.js';
+export { Slot } from './components/Slot.js';
+export type { SlotProps } from './components/Slot.js';

package/src/client/navigation/Link.tsx

@@ -37,7 +37,7 @@ function isExternalHref(href: string): boolean {
 
 /**
  * Client-side navigation link. Forwards all anchor attributes to the underlying `<a>`, and
- * prefetches the target route's chunk on hover/focus. Intercepts only plain same-origin clicks —
+ * prefetches the target route's chunk on hover/focus. Intercepts only plain same-origin clicks , 
  * modified clicks, `target=_blank`, `download`, in-page `#hash`, and external URLs fall through to
  * native browser behavior.
  */