@moku-labs/web 2.0.1 → 2.1.0

package/README.md

@@ -125,6 +125,51 @@ const app = createApp({
 await app.start();   // spa mounts islands onto the SSR'd DOM and intercepts navigation
 ```
 
+### Per-route transitions, scroll, and programmatic nav
+
+The *behaviour* of a navigation is declared on the **route** (a typed framework directive, not free-form `.meta()`), with an app-wide default on the `spa` plugin. Both `.transition()` and `.scroll()` override the default for navigations **to** that route:
+
+```ts
+spa: { islands, viewTransitions: "crossfade", scrollRestoration: "top" } // app defaults
+
+route("/board/{id}").transition("slide")                 // board↔board slides
+route("/board/{id}/issue/{issueId}")
+  .transition("morph")                                   // the card morphs into the panel
+  .scroll("preserve")                                    // overlay: don't move the board behind it
+```
+
+- **`viewTransitions`** accepts `boolean` (`true` → `"crossfade"`, `false` → `"none"`) **or** a named `TransitionMode` (`"none" | "crossfade" | "slide" | "morph"`). A named transition tags the swap so your CSS can target it two ways — `:root[data-view-transition~="slide"]` (every View-Transitions engine) and the standards-track `:active-view-transition-type(slide)` — and a shared `view-transition-name` left across the swap morphs one element into another. Reduced-motion and unsupported browsers fall back to an instant swap.
+- **`scrollRestoration`** is `"top"` (reset, the default) or `"preserve"` (keep the current scroll — e.g. opening an overlay route over content that must stay still). Back/forward always restores its saved position.
+- **`ctx.navigate(path, options?)`** — every island can navigate programmatically with no `app` handle (an always-present context member, like `ctx.set`/`ctx.url`). `app.spa.navigate` takes the same optional `{ scroll }`.
+
+```ts
+createIsland("issue", {
+  // `null` renders nothing but stays mountable (Preact unmount, not innerHTML="") —
+  // the correct "empty" for a persistent overlay panel, so it re-opens cleanly:
+  render: (s) => (s.open ? h(IssuePanel, { issue: s.issue }) : null),
+  events: { "click [data-close]": (ctx) => ctx.navigate(ctx.url("board", { id: ctx.params.id })) },
+});
+```
+
+### Live realtime channels
+
+`createChannel` is a self-healing client WebSocket primitive for islands that consume a server push stream (e.g. a Durable Object). It owns reconnect-with-backoff, an optional keepalive, a pre-seed buffer that closes the connect→load race, refcounted `subscribe` (first in connects, last out disconnects), and an optimistic `deliverLocal` echo — browser-only and tree-shaken away unless used:
+
+```ts
+import { createChannel } from "@moku-labs/web/browser";
+
+const board = createChannel<BoardPatch>({
+  url: (id) => `${location.origin.replace(/^http/, "ws")}/ws/board/${id}`,
+  keepAlive: { send: "ping", ignore: "pong" },
+  bufferUntilSeed: true,
+});
+// island onMount:
+const off = board.subscribe(boardId, (patch) => applyPatch(ctx, patch));
+ctx.cleanup(off);
+const snapshot = await getBoard(boardId);
+board.seed(boardId);   // flush anything that arrived during the load
+```
+
 ## How it works
 
 ### Three layers, one `createApp`

package/dist/browser.d.mts

@@ -278,7 +278,7 @@ interface PathMatcher {
   } | null;
 }
 declare namespace types_d_exports$3 {
-  export { Api$2 as Api, ClientRoute, CompileInput, CompiledRoute, Config$2 as Config, ExtractApi$1 as ExtractApi, ExtractRouteParams, ExtractSegmentParameter, GenerateContext, HeadConfig$1 as HeadConfig, LayoutContext, LoadContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteRequire, RouteState, RouterApi, RouterConfig, RouterState, State$2 as State, TypedRoute, Urls };
+  export { Api$2 as Api, ClientRoute, CompileInput, CompiledRoute, Config$2 as Config, ExtractApi$1 as ExtractApi, ExtractRouteParams, ExtractSegmentParameter, GenerateContext, HeadConfig$1 as HeadConfig, LayoutContext, LoadContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteRequire, RouteState, RouterApi, RouterConfig, RouterState, ScrollMode, State$2 as State, TransitionMode, TypedRoute, Urls };
 }
 /**
  * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
@@ -426,6 +426,27 @@ interface HeadConfig$1 {
   /** Arbitrary extra head fields. */
   readonly [key: string]: unknown;
 }
+/**
+ * Named view-transition behaviour for a navigation TO a route — a closed, typed
+ * vocabulary the SPA kernel interprets (NOT free-form app data, so it earns a
+ * first-class `.transition()` method instead of a `.meta()` key):
+ * - `"none"` — swap with no View Transition (instant);
+ * - `"crossfade"` — the default root crossfade (`startViewTransition(swap)`);
+ * - `"slide"` / `"morph"` — a named transition; the kernel tags the transition with
+ *   `types: ["slide"|"morph"]` so consumer CSS can target `:active-view-transition-type(slide)`
+ *   (and shared `view-transition-name`s morph one element into another).
+ *
+ * A route's `.transition()` OVERRIDES the app-wide default (`spa.viewTransitions`).
+ */
+type TransitionMode = "none" | "crossfade" | "slide" | "morph";
+/**
+ * Scroll behaviour for a navigation TO a route — a closed, typed vocabulary the SPA
+ * kernel interprets (a first-class `.scroll()` method, not a `.meta()` key):
+ * - `"top"` — reset to the top of the page on the swap (the default for forward navs);
+ * - `"preserve"` — keep the current scroll position (e.g. opening an overlay/issue route
+ *   over a board that must stay still). A route's `.scroll()` OVERRIDES `spa.scrollRestoration`.
+ */
+type ScrollMode = "top" | "preserve";
 /**
  * Fluent route builder. Each chain method returns the same builder with a
  * (possibly widened) state generic. Only `.load()` widens the data type `D`.
@@ -458,6 +479,24 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
    * projected verbatim into `clientManifest()` and shipped to the browser.
    */
   meta(meta: Record<string, unknown>): RouteBuilder<S>;
+  /**
+   * Declare the view-transition behaviour for navigations TO this route — a typed
+   * framework directive (the SPA kernel reads it), overriding the app-wide
+   * `spa.viewTransitions` default. See {@link TransitionMode}.
+   *
+   * @example
+   * route("/board/{id}/issue/{issueId}").transition("morph"); // card → panel
+   */
+  transition(mode: TransitionMode): RouteBuilder<S>;
+  /**
+   * Declare the scroll behaviour for navigations TO this route — a typed framework
+   * directive (the SPA kernel reads it), overriding the app-wide
+   * `spa.scrollRestoration` default. See {@link ScrollMode}.
+   *
+   * @example
+   * route("/board/{id}/issue/{issueId}").scroll("preserve"); // overlay: don't move the board
+   */
+  scroll(mode: ScrollMode): RouteBuilder<S>;
   /** Attach a JSON serializer for the route's data. */
   toJson(handler: (ctx: RouteContext<S>) => unknown): RouteBuilder<S>;
   /** Override the output file-path producer. */
@@ -490,6 +529,10 @@ interface RouteDefinition {
   readonly pattern: string;
   /** Metadata bag accumulated from `.meta()` (named `_meta` to avoid clashing with the `.meta()` builder method). */
   readonly _meta: Record<string, unknown>;
+  /** Named view-transition behaviour from `.transition()` (read by the SPA kernel); undefined → app default. */
+  readonly _transition?: TransitionMode;
+  /** Scroll behaviour from `.scroll()` (read by the SPA kernel); undefined → app default. */
+  readonly _scroll?: ScrollMode;
   /** Build-time handler bag (load/render/head/generate/toJson/toFile). */
   readonly _handlers: RouteHandlers;
 }
@@ -871,7 +914,12 @@ type Api$1 = {
   composeTitle(head: HeadConfig | undefined): string;
 };
 declare namespace types_d_exports$4 {
-  export { AnyVNode, ExtractApi, ISLAND_HOOK_NAMES, IslandContext, IslandDef, IslandEventHandler, IslandEvents, IslandHooks, IslandInstance, IslandRender, IslandRouteSlice, IslandSpec, IslandSpecExtras, IslandStateFactory, PageData, RenderResult, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
+  export { AnyVNode, ExtractApi, ISLAND_HOOK_NAMES, IslandContext, IslandDef, IslandEventHandler, IslandEvents, IslandHooks, IslandInstance, IslandRender, IslandRouteSlice, IslandSpec, IslandSpecExtras, IslandStateFactory, NavigateOptions, PageData, RenderResult, ResolvedSpaConfig, ScrollMode, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState, TransitionMode };
+}
+/** Per-navigation options for the programmatic navigators (`ctx.navigate` / `app.spa.navigate`). */
+interface NavigateOptions {
+  /** Override the scroll behaviour for this single navigation (else the route/app default). */
+  scroll?: ScrollMode;
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {
@@ -946,10 +994,21 @@ type SpaConfig = {
    */
   swapSelector?: string;
   /**
-   * Use the View Transitions API for cross-fade swaps when available.
-   * Falls back to an instant swap when unsupported. Defaults to `false`.
+   * The app-wide default View-Transition behaviour for navigations. Accepts a
+   * boolean (legacy: `true` → `"crossfade"`, `false` → `"none"`) OR a named
+   * {@link TransitionMode} (`"none" | "crossfade" | "slide" | "morph"`). A route's
+   * `.transition()` overrides this per-route. Falls back to an instant swap when the
+   * View Transitions API is unsupported or under `prefers-reduced-motion`. Defaults
+   * to `false` (`"none"`).
+   */
+  viewTransitions?: boolean | TransitionMode;
+  /**
+   * The app-wide default scroll behaviour for forward navigations: `"top"` (reset to
+   * the top, the default) or `"preserve"` (keep the current scroll). A route's
+   * `.scroll()` overrides this per-route. Traverse (back/forward) always restores its
+   * saved position regardless. Defaults to `"top"`.
    */
-  viewTransitions?: boolean;
+  scrollRestoration?: ScrollMode;
   /**
    * Show the in-house top progress bar during navigation. Defaults to `true`.
    */
@@ -964,8 +1023,12 @@ type SpaConfig = {
 interface ResolvedSpaConfig {
   /** CSS selector for the swapped page region. */
   swapSelector: string;
-  /** Whether View Transitions are enabled. */
+  /** Whether View Transitions are enabled at all (false ⇒ always instant swap). */
   viewTransitions: boolean;
+  /** The app-wide default transition mode applied when a route declares none. */
+  defaultTransition: TransitionMode;
+  /** The app-wide default scroll behaviour applied when a route declares none. */
+  scrollRestoration: ScrollMode;
   /** Whether the progress bar is enabled. */
   progressBar: boolean;
   /** Pre-registered islands. */
@@ -976,9 +1039,14 @@ interface ResolvedSpaConfig {
  * - a Preact `VNode` — committed into the host through the lazy Preact gate (`commitVNode`);
  * - a `Node` — replaces the host's children;
  * - a `string` — set as the host's `innerHTML`;
+ * - `null` — render NOTHING but stay mountable: the host's Preact tree is unmounted via
+ *   `render(null, host)` (NOT `innerHTML = ""`), so a later non-empty render re-commits
+ *   cleanly. This is the correct "empty" for a persistent render-island (e.g. a closed
+ *   overlay panel) — returning `""` instead corrupts Preact's retained vdom and the panel
+ *   never re-opens;
  * - `void`/`undefined` — the render mutated the DOM itself (DOM-only islands → no Preact loaded).
  */
-type RenderResult = AnyVNode | Node | string | void;
+type RenderResult = AnyVNode | Node | string | null | void;
 /**
  * A Preact `VNode` of ANY props shape. A render returns `h(Component, props)`, i.e. a
  * `VNode<SomeProps>`; the props generic is invariant under `exactOptionalPropertyTypes`,
@@ -1064,6 +1132,21 @@ interface IslandContext<S = undefined> {
   readonly locale: string;
   /** Build a link to a named route by pattern substitution (same output as `app.router.toUrl`). */
   readonly url: (name: string, params?: Record<string, string>) => string;
+  /**
+   * Programmatically navigate the SPA to an internal path (same swap pipeline as a
+   * link click; no-op without a DOM). Build `path` from the route map's `urls`/`ctx.url`,
+   * never a literal. Pass `{ scroll: "preserve" }` to keep the current scroll for this nav.
+   *
+   * An ALWAYS-PRESENT member (like `set`/`flush`/`cleanup`) so every island can navigate
+   * without an `app` handle — no synthesized anchor click.
+   *
+   * @param path - The internal destination path (e.g. `ctx.url("board", { id })`).
+   * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+   * @returns void
+   * @example
+   * ctx.navigate(ctx.url("issue", { id, issueId }));
+   */
+  readonly navigate: (path: string, options?: NavigateOptions) => void;
   /** The live per-instance state (the object returned by `spec.state`). `undefined` for legacy hooks-only islands. */
   readonly state: S;
   /**
@@ -1306,11 +1389,12 @@ interface SpaKernel {
    * Process a navigation to `path`: fetch then swap then head-sync then emit.
    *
    * @param path - The target path to navigate to.
+   * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
    * @returns void
    * @example
    * kernel.processNav("/about");
    */
-  processNav(path: string): void;
+  processNav(path: string, options?: NavigateOptions): void;
   /**
    * Query the swap region and mount islands for matching elements.
    *
@@ -1342,6 +1426,12 @@ interface SpaState {
   destroyRouter: (() => void) | null;
   /** Whether the browser runtime has been booted. */
   started: boolean;
+  /**
+   * The kernel's programmatic navigator, bound at init (null until then). The island
+   * context's `ctx.navigate` reads through this — the same decoupled seam `islandApis`
+   * uses — so `islands.ts` never imports the kernel.
+   */
+  navigate: ((path: string, options?: NavigateOptions) => void) | null;
   /** The single shared SPA kernel instance (null until onInit builds it). */
   kernel: SpaKernel | null;
 }
@@ -1360,11 +1450,12 @@ type SpaApi = {
    * Programmatically navigate to a path (client runtime; no-op without a DOM).
    *
    * @param path - Target path (pathname, optionally with search/hash).
+   * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
    * @returns void
    * @example
    * app.spa.navigate("/about");
    */
-  navigate(path: string): void;
+  navigate(path: string, options?: NavigateOptions): void;
   /**
    * Read the current resolved URL.
    *
@@ -1600,6 +1691,112 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
   buildArticleHead: typeof buildArticleHead;
 };
 //#endregion
+//#region src/plugins/spa/channel.d.ts
+/**
+ * @file spa plugin — `createChannel`, a client realtime WebSocket primitive.
+ *
+ * A live, self-healing message channel for islands that consume a server push stream
+ * (e.g. a Durable Object broadcasting board patches). It owns the parts every real-time
+ * app otherwise hand-rolls: a single active socket bound to one channel `id`, refcounted
+ * `subscribe` (first subscriber connects, last disconnects — so cross-island mount order
+ * stops being load-bearing), exponential-backoff auto-reconnect, an optional keepalive
+ * ping, a pre-seed buffer (frames that arrive before the island's snapshot loads are
+ * queued and flushed on `seed`, so the connect→load race drops nothing), and an
+ * optimistic `deliverLocal` echo.
+ *
+ * Browser-only (uses `WebSocket`); reached ONLY through an explicit `createChannel(...)`
+ * call, so an app that never opens a channel never pulls this module into its graph.
+ * @see {@link createChannel} for the usage example.
+ */
+/** Keepalive configuration: a frame sent on an interval, and the reply to ignore. */
+interface ChannelKeepAlive {
+  /** The keepalive frame to send (e.g. `"ping"`). */
+  send: string;
+  /** A reply frame to ignore rather than parse (e.g. `"pong"`). */
+  ignore?: string;
+  /** Interval between keepalive sends, in ms. Defaults to `30000`. */
+  everyMs?: number;
+}
+/** Auto-reconnect backoff configuration (exponential, capped). */
+interface ChannelReconnect {
+  /** First retry delay in ms (doubles each attempt). Defaults to `500`. */
+  baseMs?: number;
+  /** Maximum retry delay in ms (the backoff ceiling). Defaults to `8000`. */
+  maxMs?: number;
+}
+/** Options for {@link createChannel}. */
+interface ChannelOptions<T> {
+  /** Build the `ws(s)://` URL for a channel `id`. */
+  url: (id: string) => string;
+  /**
+   * Parse a raw text frame into a message, or return `undefined` to drop it (malformed
+   * frame / keepalive reply). Defaults to `JSON.parse` (dropping frames that fail to parse).
+   */
+  parse?: (raw: string) => T | undefined;
+  /** Keepalive ping configuration (off when omitted). */
+  keepAlive?: ChannelKeepAlive;
+  /** Auto-reconnect backoff (defaults applied when omitted; pass `false` to disable). */
+  reconnect?: ChannelReconnect | false;
+  /**
+   * Buffer frames that arrive before {@link Channel.seed} and flush them (in arrival
+   * order) on seed, closing the connect→load race. Defaults to `false` (deliver live).
+   */
+  bufferUntilSeed?: boolean;
+}
+/** A live realtime channel (the surface returned by {@link createChannel}). */
+interface Channel<T> {
+  /**
+   * Subscribe to messages for channel `id`, connecting (or switching) the single
+   * active socket to it. Refcounted: the first subscriber connects, the last to
+   * unsubscribe disconnects. Returns an unsubscribe function.
+   *
+   * @param id - The channel id to subscribe to.
+   * @param handler - Called with each delivered message.
+   * @returns A function that removes this handler (and disconnects when it was the last).
+   */
+  subscribe(id: string, handler: (message: T) => void): () => void;
+  /**
+   * Mark the channel seeded and flush the pre-seed buffer (no-op unless
+   * `bufferUntilSeed` and `id` is the active channel). Idempotent.
+   *
+   * @param id - The channel id whose buffer to flush (must be the active id).
+   */
+  seed(id: string): void;
+  /**
+   * Deliver a message to the local handlers immediately (the optimistic-update path —
+   * the acting client reflects its own mutation without waiting for the server echo).
+   *
+   * @param id - The channel id (must be the active id; ignored otherwise).
+   * @param message - The message to deliver locally now.
+   */
+  deliverLocal(id: string, message: T): void;
+  /**
+   * Send a raw text frame over the live socket (no-op when not open).
+   *
+   * @param raw - The frame to send.
+   */
+  send(raw: string): void;
+  /**
+   * The currently-subscribed channel id, or `undefined` when disconnected.
+   *
+   * @returns The active id, or undefined.
+   */
+  current(): string | undefined;
+  /** Close the socket, cancel reconnect, and clear all handlers. */
+  disconnect(): void;
+}
+/**
+ * Create a live realtime channel — a single self-healing WebSocket bound to one channel
+ * `id` at a time, with refcounted subscription, auto-reconnect, an optional keepalive, a
+ * pre-seed buffer, and an optimistic local-echo path. See the file header for the model.
+ *
+ * @param options - The channel configuration (see {@link ChannelOptions}).
+ * @returns The {@link Channel} control surface.
+ * @example
+ * const board = createChannel<BoardPatch>({ url: (id) => `wss://host/ws/board/${id}` });
+ */
+declare function createChannel<T>(options: ChannelOptions<T>): Channel<T>;
+//#endregion
 //#region src/plugins/spa/islands.d.ts
 /**
  * Create a validated island definition. Accepts either the legacy hooks-only form
@@ -2417,4 +2614,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>>;
 //#endregion
-export { types_d_exports as Content, types_d_exports$1 as Data, type Env, types_d_exports$2 as Head, type Log, types_d_exports$3 as Router, types_d_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports as Content, types_d_exports$1 as Data, type Env, types_d_exports$2 as Head, type Log, types_d_exports$3 as Router, types_d_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };