@lesto/ui 0.1.0

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * @lesto/ui — the AI-native UI rendering engine's ISOMORPHIC core.
+ *
+ *   const registry = new Registry()
+ *     .define({ name: "Box", props: {}, children: true, render: (_p, kids) => <div>{kids}</div> });
+ *
+ *   const schema  = treeJsonSchema(registry);   // constrain the model's output
+ *   const catalog = componentCatalog(registry); // describe it in the prompt
+ *
+ *   const tree = { type: "Box", children: ["hello"] };   // the AI emits plain JSON
+ *
+ *   const { valid, errors } = validateTree(registry, tree);   // pure, React-free
+ *
+ * This barrel is deliberately isomorphic: NOTHING here imports `react-dom/server`,
+ * so a client bundle that pulls `@lesto/ui` (for `Registry`, `defineIsland`, the
+ * island/data tokens) never drags React's ~60 KB server renderer into the
+ * browser. The server-render surface — `renderPage`/`renderPageMarkup`/`renderTree`,
+ * the streaming renderers, and the React/Preact server dialects — lives behind the
+ * `@lesto/ui/server` subpath; the browser-only hydration runtime behind
+ * `@lesto/ui/client`. Mirrors `react-dom`'s own server/client split (ADR 0008).
+ */
+
+export { Registry } from "./registry";
+
+export { validateProps } from "./props";
+
+export { componentCatalog, treeJsonSchema } from "./schema";
+
+export { validateTree } from "./validate";
+export type { TreeError } from "./validate";
+
+// The server-render surface (`renderPage`/`renderPageMarkup`/`renderTree`, the
+// streaming renderers, the React/Preact `ServerRenderer` dialects) is NOT
+// re-exported here — it imports `react-dom/server` and so lives behind the
+// `@lesto/ui/server` subpath, keeping this barrel client-safe.
+
+export { assertClientDef, island, ISLAND_ATTR, ISLAND_MOUNT_ATTR } from "./island";
+export type { ClientComponentDef, HydrationStrategy, IslandMount } from "./island";
+
+// Self-describing islands for the `.page` path (ADR 0011) — THE CANONICAL island
+// authoring path. A component that emits its own shell + co-located mount script
+// + data primer, so islands need no page-wide manifest walk. Every `.page`/
+// `lesto()` app (estate, blog) authors islands this way; its client half is
+// `hydrateDocumentIslands` (the `@lesto/ui/client` subpath), and `@lesto/assets`
+// synthesizes the client entry from a one-`defineIsland`-per-file `app/islands/`
+// convention. The Registry/`island()`/`renderPage`/`hydrateIslands` array form
+// below is now the DEMOTED niche (ADR 0011 Increment 2): it serves the AI-/DB-
+// driven `UiNode` content tree, where a `type` is a JSON string a model emitted
+// and the page is a walked manifest — NOT a hand-authored React `.page`.
+export { defineIsland } from "./define-island";
+export type { IslandComponent, IslandDef } from "./define-island";
+
+export { islandMount } from "./mount";
+
+// Island data sources (ADR 0010): declared data, framework-owned delivery.
+// `defineDataSource` is the isomorphic token; `dataSourceHref`/`DATA_ROUTE_PREFIX`
+// + `dataPrimerScript` are the STATIC-tier server delivery seams (the client half
+// lives in `@lesto/ui/client`'s hydration runtime).
+export { DATA_ROUTE_PREFIX, dataPrimerScript, dataSourceHref, defineDataSource } from "./data";
+export type { DataSource, DataSourceScope, IslandBind } from "./data";
+
+// The render-time source resolver (ADR 0012): the DYNAMIC-tier delivery that runs
+// loaders during the render and inlines the values — feeding the canonical
+// `ssr: true` island's server markup. Server-only (it wraps the page tree in a
+// React context the `.page` renderer provides); NOT in the client barrel.
+export { createSourceResolver, IslandDataContext, IslandDataProvider } from "./data-resolve";
+export type { SourceResolver } from "./data-resolve";
+
+// Client data hooks (the first step of the reactive data layer, ADR 0027):
+// `useQuery`/`useMutation` over one shared cache giving in-flight dedupe +
+// explicit-by-key invalidation — NOT yet the schema-inferred invalidation a
+// later phase may add. Decoupled from
+// `@lesto/client` (the caller passes the fetcher/mutationFn thunk), so they stay
+// in this isomorphic core; the fetch is kicked from an effect, so SSR never fetches.
+export {
+  defaultQueryClient,
+  QueryClient,
+  serializeQueryKey,
+  useMutation,
+  useQuery,
+} from "./data-client";
+export type {
+  MutationOptions,
+  MutationResultApi,
+  MutationStatus,
+  QueryKey,
+  QueryResult,
+  QuerySnapshot,
+  QueryStatus,
+} from "./data-client";
+
+// The audited seam for inlining island JSON into a `<script>`: escapes the
+// breakout characters `JSON.stringify` leaves raw. ALL island-manifest emission
+// MUST go through this — never a bare stringify or a `String.replace` splice.
+// `serializeScriptJson` is the canonical per-island form (one mount object, used
+// by `defineIsland`'s co-located mount script); `serializeManifest` is the
+// page-wide ARRAY form, now scoped to the DEMOTED Registry/`UiNode` content path
+// (ADR 0011 Increment 2) where `renderPage` collects every island into one
+// `#lesto-islands` manifest.
+export { serializeManifest, serializeScriptJson } from "./serialize";
+
+// Resource hints + LCP/modulepreload conventions over React 19's native APIs.
+// Server-safe: the `react-dom` resource functions are isomorphic and only emit
+// markup during an SSR render.
+export {
+  lcpImage,
+  modulePreload,
+  preconnect,
+  prefetchDNS,
+  preinit,
+  preinitModule,
+  preload,
+} from "./resources";
+export type {
+  LcpImageProps,
+  PreconnectOptions,
+  PreinitModuleOptions,
+  PreinitOptions,
+  PreloadOptions,
+  ResourceRegistrar,
+} from "./resources";
+
+// Document metadata helpers + the dedup convention React's hoist-without-dedupe
+// leaves to the framework. Pure: React elements / data in, data out.
+export { dedupeMetadata, link, meta, renderMetadata, renderMetadataEntry, title } from "./metadata";
+export type {
+  CharsetMeta,
+  LinkSpec,
+  MetadataEntry,
+  MetaSpec,
+  NamedMeta,
+  PropertyMeta,
+} from "./metadata";
+
+// Soft navigation's authoring half (ADR 0024): `<Link>` is an ordinary `<a>` that
+// the client runtime upgrades to a fetch-and-swap when present, and a normal
+// navigation when not — so it is isomorphic (renders the same anchor on server and
+// client) and lives in this core barrel. It pulls only the DOM-FREE contract
+// (`./softnav-contract`: the opt-out attribute + the click/anchor shapes both
+// halves read), never the browser runtime — so a server build that imports
+// `@lesto/ui` for `<Link>` drags in no `fetch`/`DOMParser`/`document`. The RUNTIME
+// half (`enableSoftNav` + its injection seams) is browser-only and lives behind
+// `@lesto/ui/client`.
+export { Link, StrictLink } from "./link";
+export type { LinkProps, StrictLinkProps } from "./link";
+// The app-facing typed-route surface is `route` (the checked link builder), `Link` +
+// `StrictLink` (lenient / strict href), the `RegisteredRoutes` augmentation target, and
+// the `RouteHref` / `StrictRouteHref` href types. The helpers `HrefFor` / `StrictHrefFor`
+// / `PatternsOf` / `KnownPatterns` / `ParamArgs` stay exported from `./routes` for
+// `route.ts` and the type-gate (which maps `@lesto/ui` → `routes.ts` directly), but are
+// not in the public barrel — nothing an app author needs.
+export { route } from "./route";
+export type { RegisteredRoutes, RouteHref, StrictRouteHref } from "./routes";
+export { eligibleAnchor, LAYOUT_ATTR, PREFETCH_ATTR, RELOAD_ATTR } from "./softnav-contract";
+export type { PrefetchStrategy, SoftNavAnchor, SoftNavClick } from "./softnav-contract";
+
+// The hydration runtime and bfcache-safe lifecycle are browser-only (they touch
+// `document`/`window`), so they live behind the `@lesto/ui/client` subpath —
+// server-side importers of `@lesto/ui` never pull DOM code into a build without
+// the DOM lib. Mirrors react-dom's server/client split.
+
+export { LestoError, UiError } from "./errors";
+export type { UiErrorCode } from "./errors";
+
+export type { ChildrenPolicy, ComponentDef, PropSpec, PropType, UiNode } from "./types";

package/src/island.ts

@@ -0,0 +1,258 @@
+/**
+ * Islands — client-hydrated regions inside an otherwise static tree.
+ *
+ * The premise of *auth-aware static*: a page is prerendered to HTML once, but a
+ * few regions ("My Account", a cart count, a live price) must resolve on the
+ * client, per-visitor, after hydration. An island is the boundary between the
+ * two worlds.
+ *
+ * The author's experience stays uniform: an island is an ordinary `UiNode`. Its
+ * `type` names a *client* component the registry knows about, and its `props`
+ * are plain JSON that will cross the server -> client wire. The `island(...)`
+ * helper is sugar for writing that node by hand.
+ *
+ * A client component is declared with `defineClient` and differs from a server
+ * `ComponentDef` in three honest ways:
+ *   - it carries no server `render`; the only thing the server can emit is an
+ *     optional `fallback` placeholder (skeleton, last-known value, nothing);
+ *   - its real implementation is a React `component`, mounted on the client;
+ *   - the engine treats its `props` as a wire payload — they MUST be
+ *     JSON-serializable, since a function or a class instance cannot survive the
+ *     trip to the browser.
+ *
+ * Two flavors of island, distinguished by `ssr`:
+ *   - **Deferred (default, `ssr` absent/false)** — the classic auth-aware-static
+ *     island. The server CANNOT render the real component (it depends on the
+ *     signed-in user the prerender never knew), so it ships only the `fallback`,
+ *     and the client mounts the live component *fresh* (`createRoot`), swapping
+ *     the fallback for per-visitor truth. `hydrateRoot` would throw a mismatch
+ *     here, because the shell never held the component's real output.
+ *   - **SSR-able (`ssr: true`)** — the author asserts the server CAN render the
+ *     real component and that the client render will MATCH it. The server emits
+ *     the component's actual output into the shell, and the client `hydrateRoot`s
+ *     it: real hydration that reuses the server DOM and gains React 19's
+ *     hydration resilience, with no re-render and no mismatch.
+ *
+ * The default is deferred because that is the safe one: declaring `ssr` is an
+ * explicit promise that server and client agree, and a broken promise is a
+ * hydration mismatch — worse than a fresh mount. We never assume it.
+ */
+
+import type { ComponentType, ReactNode } from "react";
+
+import type { DataSource, IslandBind } from "./data";
+import { UiError } from "./errors";
+import type { PropSpec, UiNode } from "./types";
+
+/**
+ * A client component: the unit an island mounts on the browser.
+ *
+ * `props` is an optional `PropSpec` schema, validated exactly like a server
+ * component's props (required/enum/coercion all reuse the same validator).
+ * `fallback` renders the server-side placeholder; absent, the island ships an
+ * empty shell to be filled in on hydration.
+ *
+ * `ssr` opts the island into real hydration: the server renders the REAL
+ * `component` into the shell (not the fallback), and the client `hydrateRoot`s
+ * it. Only set it when the component renders identically on both sides — see the
+ * module doc. When `ssr` is true the `fallback` is unused (the real output IS the
+ * server markup) and may be omitted.
+ *
+ * `hydrate` chooses WHEN the client does the island's mount work, mirroring how
+ * `ssr` chooses WHICH shell the server ships — a per-component declaration, not a
+ * page-wide mode:
+ *   - **`"load"` (default)** — eager: the island mounts as soon as
+ *     `hydrateIslands` runs, the behavior every existing island already has.
+ *   - **`"visible"`** — lazy: the island does not mount until its region first
+ *     scrolls into view (an `IntersectionObserver`), Astro's `client:visible`
+ *     analogue. For Lesto's deferred Account island this also defers its on-mount
+ *     `/mls/api/session` fetch until the region is actually seen.
+ *
+ * Honest scope: Lesto ships ONE client bundle, so `"visible"` defers the island's
+ * MOUNT WORK (its render, effects, and fetches). Whether it also defers the
+ * island's BYTES depends on the declaration form below: an eager `component`
+ * already shipped in the main bundle, while a lazy `load` arrives as its own
+ * chunk only when the mount actually happens.
+ *
+ * A client component is declared in one of two forms, and the split is what
+ * makes per-island code-splitting real:
+ *
+ *   - **Eager (`component`)** — the component function is referenced directly,
+ *     so its code ships in the main client bundle. Required for `ssr: true`
+ *     (the server must hold the real component to render it into the shell).
+ *
+ *   - **Lazy (`load`)** — the def carries a `() => import(...)`-shaped loader
+ *     instead of the component itself. A bundler with code-splitting turns that
+ *     dynamic import into a separate chunk, so the island's BYTES stay out of
+ *     the main bundle and only arrive when the island actually mounts. Combined
+ *     with `hydrate: "visible"` this is true byte deferral: a below-the-fold
+ *     island costs nothing — no code, no work — until it scrolls into view.
+ *     A lazy island is necessarily deferred (`ssr` cannot be `true`): the server
+ *     cannot SSR a component it does not hold, only its `fallback`.
+ *
+ * The two forms are a discriminated union, not two optional fields: exactly one
+ * of `component`/`load` is present, the compiler enforces `ssr: true` only on
+ * the eager form, and `defineClient` re-checks both rules at runtime for
+ * un-typed callers.
+ */
+export type ClientComponentDef = EagerClientComponentDef | LazyClientComponentDef;
+
+/** The declaration fields shared by both forms of client component. */
+interface ClientComponentBase {
+  name: string;
+  description?: string;
+  props?: Record<string, PropSpec>;
+  fallback?: (props: Record<string, unknown>) => ReactNode;
+  hydrate?: HydrationStrategy;
+
+  /**
+   * Per-request data this island needs, as `propName → source token` (ADR
+   * 0010). The framework resolves each source and hands the value to the
+   * component as that prop — so the component is a pure function of props with
+   * no `fetch`-in-effect, and a waterfall has no author-side site to exist at.
+   * The source's implementation is bound on the server (`lesto().data(...)`);
+   * this only names the binding, so the client bundle pulls in no server code.
+   *
+   * Typed loosely here (`DataSource`, value type erased) ON PURPOSE. The
+   * type-checked binding — `DataSource<P[K]>` linked to the component's props
+   * (review F8) — lives on the `defineIsland` path (`IslandDef`), the canonical
+   * path. The Registry's `defineClient` typing is deferred to estate's `.page`
+   * convergence (ADR 0011 Increment 2): its storage is an erased
+   * `Map<string, ClientComponentDef>` and its consumers (the UiNode walk) are
+   * stringly by design, so generics here would be cosmetic until that path
+   * migrates or retires.
+   */
+  data?: Record<string, DataSource>;
+}
+
+/** An island whose component ships in the main bundle (and may be `ssr: true`). */
+export interface EagerClientComponentDef extends ClientComponentBase {
+  component: ComponentType<Record<string, unknown>>;
+  load?: never;
+  ssr?: boolean;
+}
+
+/**
+ * An island whose component arrives as its own chunk, fetched on mount.
+ *
+ * `load` resolves the component — canonically `() => import("./x").then(m => m.X)`
+ * so the bundler splits it. The island is always deferred (`ssr` is not
+ * declarable): its server shell is the `fallback`, and the client swaps it for
+ * the loaded component with a fresh mount once the chunk arrives.
+ */
+export interface LazyClientComponentDef extends ClientComponentBase {
+  load: () => Promise<ComponentType<Record<string, unknown>>>;
+  component?: never;
+  ssr?: false;
+}
+
+/**
+ * When the client mounts an island. `"load"` is eager (today's only behavior);
+ * `"visible"` defers the mount until the region first intersects the viewport.
+ * Kept as a named type because it rides both the authoring side
+ * ({@link ClientComponentDef.hydrate}) and the wire ({@link IslandMount.strategy}).
+ */
+export type HydrationStrategy = "load" | "visible";
+
+/**
+ * One hydration target: enough for ANY client runtime to find the marked DOM
+ * element and mount the right component with the right props. This is the wire
+ * contract between `renderPage` (server) and `hydrateIslands` (client).
+ *
+ * `ssr` tells the client whether the shell already holds the component's real
+ * server-rendered output (`hydrateRoot`) or only a fallback to replace
+ * (`createRoot`). It rides the wire so the client never has to guess and never
+ * risks a mismatch by hydrating a fallback-only shell.
+ *
+ * `strategy` tells the client WHEN to do that mount: `"visible"` defers it to the
+ * region's first intersection, anything else (including its absence) mounts
+ * eagerly. It is OPTIONAL and omitted for the default `"load"` so an eager
+ * island's wire entry stays byte-for-byte what it has always been — existing
+ * manifests, their serialized `<script>` payloads, and the tests that pin their
+ * exact shape all read unchanged. Only the rarer `"visible"` opt-in adds a field.
+ */
+export interface IslandMount {
+  id: string;
+  component: string;
+  props: Record<string, unknown>;
+  ssr: boolean;
+  strategy?: HydrationStrategy;
+
+  /**
+   * Per-prop data bindings the client must resolve before mounting (ADR 0010),
+   * `propName → { source, href }`. Present only on an island with a `data`
+   * declaration whose values were NOT resolved server-side; a dynamically
+   * rendered page inlines the values into `props` and omits `bind` entirely, so
+   * a data-free or server-resolved island's wire entry is byte-for-byte what it
+   * always was. The client awaits each source (the parse-time primer promise on
+   * `window.__lestoData`, else a fetch of `href`) and merges it into props.
+   */
+  bind?: Record<string, IslandBind>;
+}
+
+/** The attribute that marks an island's wrapper element for hydration. */
+export const ISLAND_ATTR = "data-lesto-island";
+
+/**
+ * The attribute marking an island's co-located mount script (ADR 0011): a
+ * `<script type="application/json" data-lesto-island-mount>` carrying one
+ * {@link IslandMount}, emitted next to its shell by `defineIsland` and scanned
+ * by `hydrateDocumentIslands`.
+ */
+export const ISLAND_MOUNT_ATTR = "data-lesto-island-mount";
+
+/**
+ * Author an island NODE by hand-free sugar: `island("Account", { plan: "pro" })`.
+ * It is exactly the `UiNode` you would have written — nothing magic, so it
+ * composes as a child anywhere a node is allowed.
+ *
+ * This is the DEMOTED Registry/`UiNode` content path's sugar (ADR 0011 Increment
+ * 2): a node in an AI-/DB-driven tree the `renderPage` walk turns into a marked
+ * shell + a page-wide manifest entry. A hand-authored `.page` does NOT use this —
+ * it drops a `defineIsland` component (`<AccountIsland />`) straight into JSX,
+ * which self-emits its shell + co-located mount script. Same `IslandMount` wire,
+ * different authoring surface.
+ */
+export function island(name: string, props: Record<string, unknown> = {}): UiNode {
+  return { type: name, props };
+}
+
+/**
+ * The runtime union rules for a {@link ClientComponentDef}, in one place so both
+ * declaration paths — the Registry (`defineClient`) and the `.page`
+ * (`defineIsland`) — refuse identical broken unions identically.
+ *
+ * The compiler already forbids these states for a typed caller (the branches
+ * would narrow `def` to `never`), but an un-typed caller can still hand over a
+ * def that violates them; a clear coded error beats a downstream
+ * undefined-component crash at hydrate time. We read the discriminant fields
+ * through a widened view because, to the compiler, they cannot be wrong.
+ *
+ *   1. neither `component` nor `load` → nothing to ever mount;
+ *   2. `ssr: true` without a `component` → the server cannot SSR a component it
+ *      does not hold (a lazy island's server shell is only its fallback).
+ *
+ * `ssr: true` WITH `data` is NO LONGER refused here — ADR 0012 makes it the
+ * canonical island: legal at define time, resolved at render. The topology check
+ * (is a render-time resolver in scope?) lives at emission, where it belongs
+ * (`UI_ISLAND_SSR_DATA_UNRESOLVED` in `define-island.tsx`).
+ */
+export function assertClientDef(def: ClientComponentDef): void {
+  const declared: { component?: unknown; load?: unknown; ssr?: unknown } = def;
+
+  if (declared.component === undefined && declared.load === undefined) {
+    throw new UiError(
+      "UI_CLIENT_COMPONENT_MISSING",
+      `client component "${def.name}" declares neither "component" nor "load" — nothing to mount`,
+      { name: def.name },
+    );
+  }
+
+  if (declared.ssr === true && declared.component === undefined) {
+    throw new UiError(
+      "UI_CLIENT_SSR_NEEDS_COMPONENT",
+      `client component "${def.name}" is ssr: true but lazy — the server cannot render a component it does not hold`,
+      { name: def.name },
+    );
+  }
+}

package/src/link.tsx

@@ -0,0 +1,103 @@
+/**
+ * `<Link>` — an ordinary anchor that soft nav upgrades.
+ *
+ * The deliberate non-magic of Lesto's client router: a `Link` renders a real
+ * `<a href>`, nothing more. It works with JS off (a normal navigation), it is
+ * crawlable, it is an anchor in every devtool — and when {@link enableSoftNav} is
+ * running, its delegated click listener turns an eligible click into a
+ * fetch-and-swap. So the component carries no navigation logic itself; it is the
+ * authoring sugar that pairs with the runtime, exactly as a server `<a>` pairs
+ * with the browser.
+ *
+ * Authored with plain `createElement` so it stays in `@lesto/ui`'s isomorphic core
+ * (no `react-dom`): it renders the same markup on the server (into the prerendered
+ * document) and on the client (inside an island), and the soft-nav runtime reads
+ * the rendered anchor, never the component.
+ *
+ *   <Link href="/listings/7">View listing</Link>
+ *   <Link href="/download.pdf" reload>Download</Link>   // opts out → full nav
+ */
+
+import { createElement } from "react";
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+
+import type { RouteHref, StrictRouteHref } from "./routes";
+import { PREFETCH_ATTR, prefetchAttrValue, RELOAD_ATTR } from "./softnav-contract";
+import type { PrefetchStrategy } from "./softnav-contract";
+
+/** A `Link`'s props: every native anchor attribute, plus `href` (required), `reload`, `prefetch`. */
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /**
+   * The destination. A same-origin path soft-navigates; anything else falls back to
+   * a full nav. Typed as {@link RouteHref}: when the app has route codegen, the
+   * known routes autocomplete; otherwise it is `string`, unchanged.
+   */
+  href: RouteHref;
+
+  /**
+   * Force a full document reload for this link, opting OUT of soft nav (renders
+   * the {@link RELOAD_ATTR} the runtime declines on). Use it for a link that must
+   * re-run the document — a logout that clears client state, a cross-app boundary.
+   */
+  reload?: boolean;
+
+  /**
+   * Opt this link INTO prefetch — warming the soft-nav fetch of its destination
+   * before the click, so the navigation feels instant. Renders the
+   * {@link PREFETCH_ATTR} the runtime reads; a server build with no soft-nav runtime
+   * (or one that declines the link, e.g. cross-origin) simply ignores it.
+   *
+   *   - `"viewport"` (or bare `prefetch` / `prefetch={true}`) — warm when the link
+   *     scrolls into view (eager, the cheaper-feeling default).
+   *   - `"hover"` — warm on pointer-enter / keyboard focus (lazy, intent-driven).
+   *   - `false`/omitted — no prefetch (the default; existing links are unchanged).
+   *
+   * Opt-in and additive: the runtime never warms a cross-origin or `route()`-escape
+   * href, so a marked external link is a harmless no-op.
+   */
+  prefetch?: boolean | PrefetchStrategy;
+
+  children?: ReactNode;
+}
+
+/**
+ * Render a soft-nav-aware anchor.
+ *
+ * `reload` and `prefetch` are lifted off the DOM props and turned into the
+ * `data-lesto-reload` / `data-lesto-prefetch` attributes the runtime reads, so
+ * neither leaks onto the `<a>` as an unknown attribute. `prefetch` renders only
+ * when it resolves to a strategy ({@link prefetchAttrValue}: `true` → `"viewport"`,
+ * `false`/omitted → nothing), so an un-prefetched link is byte-for-byte the anchor
+ * it always was. Everything else (`className`, `aria-*`, `onClick`, `rel`, a
+ * `target`) passes straight through — a `target="_blank"` link, for instance,
+ * still renders normally and the runtime declines to soft-nav it, the correct
+ * behavior with no special-casing here.
+ */
+export function Link({ href, reload, prefetch, children, ...rest }: LinkProps): ReactNode {
+  const prefetchValue = prefetchAttrValue(prefetch);
+
+  return createElement(
+    "a",
+    {
+      href,
+      ...(reload === true ? { [RELOAD_ATTR]: "" } : {}),
+      ...(prefetchValue === undefined ? {} : { [PREFETCH_ATTR]: prefetchValue }),
+      ...rest,
+    },
+    children,
+  );
+}
+
+/** The props {@link StrictLink} takes: a `Link`'s, but with a STRICT {@link StrictRouteHref}. */
+export type StrictLinkProps = Omit<LinkProps, "href"> & { href: StrictRouteHref };
+
+/**
+ * `<StrictLink>` — `<Link>` with a STRICT href: only the app's known routes, no escape,
+ * so a typo'd `href` is a `tsc` error (the "a bad link won't compile" win, BY DEFAULT —
+ * no `route()` wrapper needed). It IS `Link`, re-typed: runtime-identical, zero new code.
+ *
+ * For a FULLY-file-routed app, where the codegen registry is the complete route set. A
+ * MIXED app (with code-first `.page()` routes) keeps `<Link>` — strict here would
+ * false-positive on those (see {@link StrictRouteHref}).
+ */
+export const StrictLink: (props: StrictLinkProps) => ReactNode = Link;