akanjs 3.0.2 → 3.1.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # akanjs
 
+## 3.0.2
+
+### Minor Changes
+
+- be8ed50: Endpoints take a rate limit: `rateLimit: { calls, windowMs?, by?: "ip" | "account" } | false` in the signal option, and `option.setRateLimit({ budget, endpoints, accountKey, enabled })` in an app or lib `option.ts`. An `ip` budget is counted before the request body is read, an `account` budget after the middlewares and before the guards, and a refusal answers 429 `base.error.tooManyRequests` with `{ seconds }` and `Retry-After`. Counters share the cache across instances. `AKAN_RATE_LIMIT=off|on|<calls>[/<seconds>]`; unset, budgets apply everywhere but a `local` environment. A service counts a business key with `plug(RateLimit)` and `consume(key, { calls, windowMs })`. Fetches a page makes while rendering now carry the visitor's address, and the MCP limiter keys an anonymous caller by its trusted-proxy address instead of a raw `X-Real-IP` any caller could forge.
+- af66669: The macOS dmg `build-desktop --installer true` makes opens on a drag-to-Applications window: no toolbar, sidebar or status bar, 128 pt icons of the app and the Applications link on a background with an arrow between them (1x and 2x in one multi-resolution TIFF), and the app's icon on the mounted disk (`.VolumeIcon.icns`). Its own files (`.background`, `.VolumeIcon.icns`, `.DS_Store`, `.fseventsd`) are hidden. The window is a `.DS_Store` written directly while a read-write image is mounted, never through Finder or AppleScript, so a headless CI builds the same image; the compressed image is made afterwards and is what gets signed, notarized and stapled. `native.desktop.dmg` (a target's too) replaces the background (`background`, `background2x`, or `false`) and moves the window and the icons (`window`, `iconSize`, `textSize`, `app`, `applications`, in points); the default background lines up with the default positions only.
+- be8ed50: `buttonRecipe` gains `size: "xl"` and `inputRecipe` gains `kind: "select"` for a native `<select>`. Upgrade note: an app's own `recipes.button` / `recipes.input` override slot must accept the new values to typecheck.
+- be8ed50: A slice's `get`/`cru`/`create`/`update`/`remove` guard may be `false`, which mounts no generated endpoint for that verb; `mcp: { cru: false }` only ever kept the verbs off the agent shelf. Upgrade note: a generated verb whose guards resolve to none is no longer mounted (it used to answer anyone over HTTP while the client never synthesized it). Resolving an endpoint class now warns about every endpoint that declares no guards.
+- be8ed50: Reads and query-level writes can reach soft-removed rows with `{ withRemoved: true }` (`find`/`findOne`/`findById`'s third argument, `count`/`exists`/`updateMany`'s last, `updateOne`/`updateById`'s options). Upgrade note: a query with a `removedAt` condition only a removed row can meet (`q.exists("removedAt")`, a comparison) now throws `can never match` instead of silently matching nothing; add the flag where removed rows are meant. A removed document is read-only, and `updateById(id, { removedAt: null }, { withRemoved: true })` revives one.
+
+### Patch Changes
+
+- be8ed50: An HTTP query or mutation returning `Binary` now answers base64, which the client reads back as bytes; it used to answer `{"0":1,…}`. A return declared `Any` that turns out to be an ArrayBuffer or typed array now fails with a message pointing at `Binary` instead of sending `{}`.
+- af66669: A CSR page or layout whose render fails no longer leaves a blank screen. The layer shows the error's message — "Cannot reach the server. Check your connection and try again." for `base.error.serverUnreachable`, a generic "This page could not be loaded." otherwise — and a Try again button that runs the render again. A render that redirected before it failed still shows nothing, since its page is leaving.
+- be8ed50: `enumOf` infers its literal values without `as const`, so a value outside the list fails to compile. Upgrade note: code that relied on a widened `string`/`number` enum type may need a narrower type.
+- be8ed50: `String(err)` of a dictionary `Err` appends its `data` as one line of JSON, secret-named keys masked, so a log line keeps what failed.
+- be8ed50: Arguments are parsed after the `account` guards and before the `resource` guards, so a caller an account guard refuses never reaches an argument parser. A guard or middleware that reads an argument earlier still gets it. Upgrade note: an unauthenticated call with a malformed argument now answers 401/403 instead of 400. A subscribed room's guards are re-checked on a fresh context, so a guard that memoizes per context gives a new verdict.
+- be8ed50: Changing an `immutable` field is refused with a 400 `base.error.immutableField` the client can translate, instead of a generic 500.
+- be8ed50: A server caller's `limit: 0` reads every row again, like an omitted limit, instead of 20. A client's `limit: 0` is served the 500-row page ceiling with a one-time warn.
+- af66669: A Linux desktop app's window is named after its app id (X11 `WM_CLASS`, Wayland `app_id`), so a dock or task bar finds its `<app id>.desktop` and shows that entry's name and icon instead of a generic one; the dock plugin's badge and progress name the same entry. The AppImage `build-desktop --installer true` makes carries `<app id>.desktop` with `StartupWMClass=<app id>` and `<app id>.png`, so the entry AppImageLauncher or appimaged installs under another file name still matches the window. The hidden entry that handles the app's deep links now shows the app's icon (installed as `~/.local/share/icons/hicolor/256x256/apps/<app id>.png`), and from an AppImage it starts the AppImage itself (`$APPIMAGE`) rather than the mount point it ran from, which is gone once the app quits, so a link opened after quitting the app no longer fails.
+- bd55713: `Input.Number` (and `Field.Number`) keeps the decimal point when Enter or Escape settles a typed value: 0.25 used to display as 25 while the stored value stayed 0.25.
+- be8ed50: On a server, `fetch.clone({ origin })` toward another origin no longer opens a websocket unless `connect: true`, so a server making one-off calls to another server no longer leaks an auto-reconnecting socket per clone.
+- be8ed50: `setCookie` defaults to `path=/; SameSite=Lax; Secure` instead of `SameSite=None`, matching the auth cookie the server sets, and an options object overrides only the keys it names.
+- a789952: In a signal test every `fetch.clone()` reports its own client address, so an `ip` rate limit counts each agent apart instead of every agent sharing loopback; `clone({ clientIp })` names one explicitly.
+- be8ed50: A Mongo-style `schema.index({ x: "text" })` no longer builds a B-tree over the JSON value (which could fail long inserts on Postgres); it warns at boot and points at the `text` field role, and drops the index an earlier boot built for exactly that declaration.
+
 ## 3.0.1
 
 ### Minor Changes

package/base/baseEnv.ts

@@ -30,10 +30,6 @@ export type BackendEnv = {
       cacheSize?: number;
       tempStore?: string;
     };
-    libsql?: {
-      url?: string;
-      authToken?: string;
-    };
     postgres?: {
       url?: string;
       host?: string;

package/base/primitiveRegistry.ts

@@ -281,7 +281,7 @@ declare global {
     [CLIENT_VALUE]: Dayjs;
     [DEFAULT_VALUE]: Dayjs;
     [PURIFIED_VALUE]: Dayjs;
-    [EXAMPLE_VALUE]: string;
+    [EXAMPLE_VALUE]: Dayjs;
     validate(value: Date): boolean;
     parseValue(input: Date): Dayjs;
     serializeValue(value: Dayjs | Date): Date;
@@ -371,7 +371,7 @@ Object.assign(Date, {
   ...scalarPrimitiveStatics,
   refName: "Date",
   [DEFAULT_VALUE]: dayjs(new Date(-1)),
-  [EXAMPLE_VALUE]: dayjs(new Date().toISOString()),
+  [EXAMPLE_VALUE]: dayjs("2026-01-01T00:00:00.000Z"),
   validate(value: Date | string | number) {
     const date = new Date(value);
     if (Number.isNaN(date.getTime())) return false;

package/client/cookie.ts

@@ -110,8 +110,12 @@ export const getStoredAuthToken = async (): Promise<string | undefined> => {
  * honours — the app-scoped auth cookie (a CSR client's bearer token) and `Authorization: Bearer` — so the two never
  * disagree on who is signed in. */
 export const getAccount = <AddData = unknown>(): Account<AddData> => {
-  const jwt = getAuthToken() ?? getHeader("authorization")?.replace(/^Bearer\s+/i, "");
   const defaultAccount = { appName: getEnv().appName, environment: getEnv().environment } as Account<AddData>;
+  
+  const embedded = globalThis.__AKAN_EMBED__;
+  if (embedded)
+    return embedded.account ? ({ ...defaultAccount, ...embedded.account } as Account<AddData>) : defaultAccount;
+  const jwt = getAuthToken() ?? getHeader("authorization")?.replace(/^Bearer\s+/i, "");
   if (!jwt) return defaultAccount;
   const account = decodeJwtPayload<Account<AddData>>(jwt);
   if (account.appName !== getEnv().appName || account.environment !== getEnv().environment) return defaultAccount;

package/client/csrLocation.ts

@@ -0,0 +1,122 @@
+interface CsrLocationEntry {
+  href: string;
+  state: unknown;
+}
+
+export interface CsrMemoryOwner {
+  leave: (href: string) => void;
+  reload: () => void;
+}
+
+declare global {
+  var __AKAN_CSR_LOCATION__: CsrLocation | undefined;
+  
+  var __AKAN_EMBED__: { kind: "mcp-app"; origin?: string; account?: Record<string, unknown> | null } | undefined;
+}
+
+export class CsrLocation {
+  #memory: { entries: CsrLocationEntry[]; idx: number } | null = null;
+  #owner: CsrMemoryOwner = { leave: () => undefined, reload: () => undefined };
+
+  get isMemory() {
+    return this.#memory !== null;
+  }
+
+  /** The owner takes what a document load would do, which a view cannot: it has no document to load in its place. */
+  useMemory(href: string, owner: CsrMemoryOwner) {
+    this.#memory = { entries: [{ href, state: null }], idx: 0 };
+    this.#owner = owner;
+  }
+
+  /** Path, search and hash, without the origin. */
+  get href() {
+    const entry = this.#entry();
+    if (entry) return entry.href;
+    return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+  }
+
+  get pathname() {
+    if (!this.#memory) return window.location.pathname;
+    return this.href.split(/[?#]/)[0] ?? "/";
+  }
+
+  get search() {
+    if (!this.#memory) return window.location.search;
+    const [beforeHash] = this.href.split("#");
+    const at = beforeHash?.indexOf("?") ?? -1;
+    return at >= 0 ? (beforeHash?.slice(at) ?? "") : "";
+  }
+
+  get hash() {
+    if (!this.#memory) return window.location.hash;
+    const at = this.href.indexOf("#");
+    return at >= 0 ? this.href.slice(at) : "";
+  }
+
+  get state(): unknown {
+    const entry = this.#entry();
+    return entry ? entry.state : window.history.state;
+  }
+
+  /** `href` as a route reads it: an absolute URL on this document's origin loses the origin, anything else is kept. */
+  strip(href: string) {
+    if (this.#memory) return href;
+    const origin = window.location.origin;
+    return origin !== "null" && href.startsWith(origin) ? href.slice(origin.length) : href;
+  }
+
+  push(state: unknown, href: string) {
+    const memory = this.#memory;
+    if (!memory) {
+      window.history.pushState(state, "", href);
+      return;
+    }
+    memory.entries = [...memory.entries.slice(0, memory.idx + 1), { href, state }];
+    memory.idx = memory.entries.length - 1;
+  }
+
+  replace(state: unknown, href?: string) {
+    const memory = this.#memory;
+    if (!memory) {
+      if (href === undefined) window.history.replaceState(state, "");
+      else window.history.replaceState(state, "", href);
+      return;
+    }
+    const current = memory.entries[memory.idx];
+    memory.entries[memory.idx] = { href: href ?? current?.href ?? "/", state };
+  }
+
+  back() {
+    const memory = this.#memory;
+    if (!memory) {
+      window.history.back();
+      return;
+    }
+    if (memory.idx === 0) return;
+    memory.idx -= 1;
+    const state = memory.entries[memory.idx]?.state ?? null;
+    
+    setTimeout(() => window.dispatchEvent(new PopStateEvent("popstate", { state })), 0);
+  }
+
+  assign(href: string) {
+    if (!this.#memory) {
+      window.location.assign(href);
+      return;
+    }
+    this.#owner.leave(href);
+  }
+
+  reload() {
+    if (!this.#memory) window.location.reload();
+    else this.#owner.reload();
+  }
+
+  #entry() {
+    const memory = this.#memory;
+    return memory ? memory.entries[memory.idx] : undefined;
+  }
+}
+
+globalThis.__AKAN_CSR_LOCATION__ ??= new CsrLocation();
+export const csrLocation: CsrLocation = globalThis.__AKAN_CSR_LOCATION__;

package/client/csrTypes.ts

@@ -22,13 +22,22 @@ export type PageSafeAreaConfig =
  * `"block"` buffers the whole document, so an error in slow content can still render a clean error page. */
 export type SsrRenderMode = "stream" | "block";
 
+/** Px per Tailwind breakpoint (sm 40rem, md 48rem, lg 64rem, xl 80rem, 2xl 96rem), each from its own width up. */
+export interface ResponsiveInset {
+  base: number;
+  sm?: number;
+  md?: number;
+  lg?: number;
+  xl?: number;
+  "2xl"?: number;
+}
 export interface PageConfig {
   transition?: TransitionType;
   safeArea?: PageSafeAreaConfig;
-  /** Top chrome reservation in px. Use true for the default 48px reservation. */
-  topInset?: number | boolean;
-  /** Bottom chrome reservation in px. Use true for the default 48px reservation. */
-  bottomInset?: number | boolean;
+  /** Top chrome reservation in px, or px per breakpoint. Use true for the default 48px reservation. */
+  topInset?: number | boolean | ResponsiveInset;
+  /** Bottom chrome reservation in px, or px per breakpoint. Use true for the default 48px reservation. */
+  bottomInset?: number | boolean | ResponsiveInset;
   gesture?: boolean;
   cache?: boolean;
   /** Initial full-document SSR strategy. Defaults to `"stream"`. */
@@ -48,6 +57,10 @@ export interface CsrState {
   bottomSafeArea: number;
   topInset: number;
   bottomInset: number;
+  /** The declared per-breakpoint insets; `topInset`/`bottomInset` hold their value at the width they resolved at. */
+  responsiveInset?: { top: ResponsiveInset; bottom: ResponsiveInset };
+  /** Web only: the sides whose safe area `env(safe-area-inset-*)` measures, since a browser tells script nothing. */
+  safeAreaEnv?: { top: boolean; bottom: boolean };
   gesture: boolean;
   cache: boolean;
   ssr: SsrRenderMode;
@@ -114,13 +127,27 @@ export interface RouteRender {
   resolveNotFound?: () => PromiseOrObject<LayoutNotFoundRender | undefined>;
   resolveError?: () => PromiseOrObject<LayoutErrorRender | undefined>;
   resolveHead?: ResolveHead;
+  /** Parses the declared args without rendering, so a path value the type refuses answers not-found before any byte. */
+  checkArgs?: (props: PageProps) => Promise<void>;
   getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   /** A root layout's `theme`, readable before it renders. */
   getLayoutTheme?: () => PromiseOrObject<string | undefined>;
+  /** A root layout's `viewport`, readable before it renders: the document shell writes it ahead of the body. */
+  getLayoutViewport?: () => PromiseOrObject<RouteViewport | undefined>;
+  /** A root layout's `manifest`, which the server answers at the URL its documents link. */
+  getLayoutManifest?: () => PromiseOrObject<WebAppManifest | undefined>;
   /** The `page()` chain behind a page render, when it was declared as one — what a page prompt is read off. */
   getRouteDefinition?: () => PromiseOrObject<RouteDefinition | undefined>;
 }
+export interface RouteViewport {
+  /** `viewport-fit=cover`: the page runs under the notch and home indicator, and `env(safe-area-inset-*)` measures them. */
+  fitCover?: boolean;
+  /** What the on-screen keyboard resizes; `resizes-content` shrinks the layout viewport, and `dvh` with it. */
+  interactiveWidget?: "resizes-visual" | "resizes-content" | "overlays-content";
+  /** The browser chrome's color: one for every theme, or one per theme name the app switches between. */
+  themeColor?: string | { [theme: string]: string };
+}
 export interface WebAppManifestIcon {
   src: string;
   sizes?: string;
@@ -164,6 +191,7 @@ export interface LayoutModule {
   reconnect?: boolean;
   wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
+  viewport?: RouteViewport;
   Loading?: LayoutLoadingRender;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -336,6 +364,10 @@ export const usePathCtx = () => {
   return contextValues;
 };
 
+/** Inside a layout's own markup that an MCP view hides while the page is drawn on its own: frame chrome draws nothing. */
+export const hiddenLayoutContext = sharedContext<boolean>("hiddenLayout", false);
+export const useInHiddenLayout = () => useContext(hiddenLayoutContext);
+
 export type PageActivity = "current" | "prev" | "pending" | "hidden";
 export interface PageActivityState {
   activity: PageActivity;

package/client/device.ts

@@ -1,5 +1,6 @@
 "use client";
 import type { RefObject } from "react";
+import { csrLocation } from "./csrLocation";
 import { readCssSafeAreaInsets } from "./frameConfig";
 import type { DeviceInfo } from "./native";
 
@@ -98,7 +99,7 @@ const createWebDevice = ({
   lang?: string;
   supportLanguages: string[] | readonly string[];
 }) => {
-  const pathname = typeof window === "undefined" ? "" : window.location.pathname;
+  const pathname = typeof window === "undefined" ? "" : csrLocation.pathname;
   return new Device({
     lang: lang ?? langInPath(pathname, supportLanguages) ?? getBrowserLanguage(),
     info: webDeviceInfo,

package/client/frameConfig.ts

@@ -1,5 +1,12 @@
 import { isRecord } from "akanjs/common";
-import type { PageConfig, PageSafeAreaConfig, PageState, SsrRenderMode, TransitionType } from "./csrTypes";
+import type {
+  PageConfig,
+  PageSafeAreaConfig,
+  PageState,
+  ResponsiveInset,
+  SsrRenderMode,
+  TransitionType,
+} from "./csrTypes";
 
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
 export type SafeAreaInsets = { top: number; bottom: number };
@@ -11,8 +18,20 @@ export interface ResolvePageStateOptions {
   platform: DevicePlatform;
   deviceSafeArea: SafeAreaInsets;
   cssSafeArea?: SafeAreaInsets;
+  /** The viewport width in px a responsive inset resolves at; left out, it resolves at `base`. */
+  width?: number;
 }
 
+/** Tailwind's default breakpoints in rem, the widths a `ResponsiveInset` keys on. */
+export const insetBreakpoints = [
+  ["sm", 40],
+  ["md", 48],
+  ["lg", 64],
+  ["xl", 80],
+  ["2xl", 96],
+] as const;
+export type InsetBreakpoint = "base" | (typeof insetBreakpoints)[number][0];
+
 const pageConfigKeys = new Set<keyof PageConfig>([
   "transition",
   "safeArea",
@@ -54,14 +73,42 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   for (const key of ["topInset", "bottomInset"] as const) {
     if (pageConfig[key] !== undefined && !isValidInsetValue(pageConfig[key]))
       throw new Error(
-        `[route-convention] pageConfig.${key} in ${routeKey} must be a boolean or non-negative px number.`,
+        `[route-convention] pageConfig.${key} in ${routeKey} must be a boolean, a non-negative px number, or { base, sm?, md?, lg?, xl?, "2xl"? } of them.`,
       );
   }
   validateSafeAreaConfig(routeKey, pageConfig.safeArea);
 }
 
+const isInsetPx = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0;
+const responsiveInsetKeys = new Set<string>(["base", ...insetBreakpoints.map(([name]) => name)]);
+
 function isValidInsetValue(value: unknown): value is NonNullable<PageConfig["topInset"]> {
-  return typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+  if (typeof value === "boolean" || isInsetPx(value)) return true;
+  if (!isRecord(value) || !isInsetPx(value.base)) return false;
+  return Object.entries(value).every(([key, px]) => responsiveInsetKeys.has(key) && isInsetPx(px));
+}
+
+export const isResponsiveInset = (inset: PageConfig["topInset"]): inset is ResponsiveInset => isRecord(inset);
+
+/** The inset at each breakpoint, each one the nearest declared value at or below it. */
+export function insetsByBreakpoint(inset: PageConfig["topInset"]): { [bp in InsetBreakpoint]: number } {
+  const base = isResponsiveInset(inset) ? inset.base : resolveInset(inset);
+  const values = { base } as { [bp in InsetBreakpoint]: number };
+  let current = base;
+  for (const [name] of insetBreakpoints) {
+    current = (isResponsiveInset(inset) ? inset[name] : undefined) ?? current;
+    values[name] = current;
+  }
+  return values;
+}
+
+/** The inset in force at `width` px, assuming a 16px rem. */
+export function insetAt(inset: PageConfig["topInset"], width?: number): number {
+  if (!isResponsiveInset(inset)) return resolveInset(inset);
+  if (width === undefined) return inset.base;
+  const values = insetsByBreakpoint(inset);
+  return insetBreakpoints.reduce((value, [name, rem]) => (width >= rem * 16 ? values[name] : value), values.base);
 }
 
 function validateSafeAreaConfig(routeKey: string, safeArea?: PageSafeAreaConfig) {
@@ -132,6 +179,7 @@ export function resolvePageState({
   platform,
   deviceSafeArea,
   cssSafeArea,
+  width,
 }: ResolvePageStateOptions): PageState {
   const profile = getPlatformFrameProfile(platform);
   const routeRole = getRouteRoleFrameDefaults(path, platform, basePath);
@@ -144,12 +192,25 @@ export function resolvePageState({
     cssSafeArea,
   });
   const transition = config.transition ?? "none";
+  const responsive = isResponsiveInset(config.topInset) || isResponsiveInset(config.bottomInset);
+  const safeAreaEnv = platform === "web" ? resolveSafeAreaEnv(config.safeArea) : undefined;
   return {
     transition,
     topSafeArea: safeArea.top,
     bottomSafeArea: safeArea.bottom,
-    topInset: resolveInset(config.topInset),
-    bottomInset: resolveInset(config.bottomInset),
+    topInset: insetAt(config.topInset, width),
+    bottomInset: insetAt(config.bottomInset, width),
+    ...(responsive
+      ? {
+          responsiveInset: {
+            top: isResponsiveInset(config.topInset) ? config.topInset : { base: resolveInset(config.topInset) },
+            bottom: isResponsiveInset(config.bottomInset)
+              ? config.bottomInset
+              : { base: resolveInset(config.bottomInset) },
+          },
+        }
+      : {}),
+    ...(safeAreaEnv ? { safeAreaEnv } : {}),
     gesture: explicitKeys.gesture
       ? (config.gesture ?? false)
       : transition === "none"
@@ -165,9 +226,17 @@ export function resolvePageState({
 function resolveInset(inset: PageConfig["topInset"]): number {
   if (inset === true) return DEFAULT_BOOLEAN_INSET;
   if (inset === false || inset === undefined) return 0;
+  if (isResponsiveInset(inset)) return inset.base;
   return inset;
 }
 
+function resolveSafeAreaEnv(safeArea?: PageSafeAreaConfig): { top: boolean; bottom: boolean } | undefined {
+  if (safeArea === undefined || safeArea === false) return undefined;
+  const top = safeArea === true || safeArea === "top" || (isRecord(safeArea) && safeArea.top !== false);
+  const bottom = safeArea === true || safeArea === "bottom" || (isRecord(safeArea) && safeArea.bottom !== false);
+  return top || bottom ? { top, bottom } : undefined;
+}
+
 function getPlatformFrameProfile(platform: DevicePlatform): PageConfig {
   if (platform === "ios") return { safeArea: true, transition: "stack" };
   if (platform === "android") return { safeArea: { android: "auto" }, transition: "scaleOut", gesture: false };
@@ -221,9 +290,11 @@ function resolveSafeArea({
       bottom: bottomEnabled && source ? source.bottom : 0,
     };
   }
+  
+  const source = platform === "web" && cssSafeArea ? cssSafeArea : deviceSafeArea;
   return {
-    top: topEnabled ? deviceSafeArea.top : 0,
-    bottom: bottomEnabled ? deviceSafeArea.bottom : 0,
+    top: topEnabled ? source.top : 0,
+    bottom: bottomEnabled ? source.bottom : 0,
   };
 }
 

package/client/index.ts

@@ -2,6 +2,7 @@ export * from "./clientRuntime";
 export * from "./cn";
 export * from "./cookie";
 export * from "./createFont";
+export * from "./csrLocation";
 export * from "./csrTypes";
 export * from "./decorators";
 export * from "./device";
@@ -17,3 +18,5 @@ export * from "./storage";
 export * from "./translator";
 export * from "./types";
 export * from "./useClient";
+export * from "./viewportMeta";
+export * from "./webManifest";

package/client/makePageProto.tsx

@@ -2,6 +2,7 @@ import { getEnv } from "akanjs/base";
 import { parseAkanI18nEnv } from "akanjs/common";
 import { untrackedHeaders, untrackedRequest } from "akanjs/fetch";
 import type { ReactNode } from "react";
+import { csrLocation } from "./csrLocation";
 import { Translator } from "./translator";
 
 type TransMessage<Locale extends Record<string, unknown>> = {
@@ -27,11 +28,11 @@ const getPageInfo = (): { locale: string; path: string } => {
   const activePath = Translator.getActivePath();
   if (activePath) return { locale: activeLocale ?? defaultLocale, path: activePath };
   if (getEnv().side !== "server") {
-    const [, firstSegment = "", ...rest] = window.location.pathname.split("/");
+    const [, firstSegment = "", ...rest] = csrLocation.pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
     
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
-    return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : window.location.pathname) };
+    return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : csrLocation.pathname) };
   }
   const h = untrackedHeaders();
   

package/client/native/external-view.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/external-view/src/index.ts";

package/client/route/RootLayoutDefinition.ts

@@ -1,4 +1,4 @@
-import type { LayoutModule, PageModule, WebAppManifest } from "../csrTypes";
+import type { LayoutModule, PageModule, RouteViewport, WebAppManifest } from "../csrTypes";
 import type { ReactFont } from "../types";
 import { LayoutDefinition } from "./LayoutDefinition";
 import type { RouteArgsShape, RouteKind } from "./RouteDefinition";
@@ -12,6 +12,7 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
   #reconnect?: boolean;
   #wsConnect?: boolean;
   #layoutStyle?: "mobile" | "web";
+  #viewport?: RouteViewport;
 
   fonts(fonts: ReactFont[]) {
     this.#fonts = fonts;
@@ -37,6 +38,10 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
     this.#layoutStyle = style;
     return this;
   }
+  viewport(viewport: RouteViewport) {
+    this.#viewport = viewport;
+    return this;
+  }
 
   protected override extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
     return {
@@ -47,6 +52,7 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
       ...(this.#reconnect !== undefined ? { reconnect: this.#reconnect } : {}),
       ...(this.#wsConnect !== undefined ? { wsConnect: this.#wsConnect } : {}),
       ...(this.#layoutStyle ? { layoutStyle: this.#layoutStyle } : {}),
+      ...(this.#viewport ? { viewport: this.#viewport } : {}),
     };
   }
 }

package/client/route/RouteHead.ts

@@ -0,0 +1,108 @@
+import { cloneElement, createElement, Fragment, isValidElement, type ReactElement, type ReactNode } from "react";
+import type { AkanHeadSnapshotNode, AkanHeadSnapshotV1, ResolvedHead, ResolveHeadResult } from "../csrTypes";
+
+type TagProps = Record<string, unknown>;
+
+/** Merges the `.head()` of every route level, root first: a deeper level takes over each singleton tag it writes. */
+export class RouteHead {
+  
+  static readonly #singletonLinkRels = new Set([
+    "canonical",
+    "manifest",
+    "icon",
+    "shortcut icon",
+    "apple-touch-icon",
+    "mask-icon",
+  ]);
+
+  static merge(levels: ResolveHeadResult[]): ResolveHeadResult {
+    const present = levels.filter((level) => RouteHead.#nodeOf(level) != null || RouteHead.#snapshotOf(level));
+    if (present.length <= 1) return present[0];
+    const node = RouteHead.mergeNodes(present.map((level) => RouteHead.#nodeOf(level)));
+    const snapshots = present.map((level) => RouteHead.#snapshotOf(level)).filter((snapshot) => !!snapshot);
+    if (!snapshots.length) return node;
+    return { node, headSnapshot: RouteHead.#mergeSnapshots(snapshots) } satisfies ResolvedHead;
+  }
+
+  /** What makes two tags the same tag; `null` for one that never replaces another. */
+  static keyOf(tag: string, props: TagProps): string | null {
+    if (tag === "title" || tag === "base") return tag;
+    if (tag === "meta") {
+      if (props.charSet !== undefined || props.charset !== undefined) return "meta:charset";
+      for (const attr of ["name", "property", "httpEquiv", "itemProp"]) {
+        const value = props[attr];
+        if (typeof value === "string" && value) return `meta:${attr}:${value.toLowerCase()}`;
+      }
+      return null;
+    }
+    if (tag !== "link" || typeof props.rel !== "string") return null;
+    const rel = props.rel.toLowerCase();
+    if (RouteHead.#singletonLinkRels.has(rel)) return `link:${rel}`;
+    const hrefLang = props.hrefLang ?? props.hreflang;
+    if (rel === "alternate" && typeof hrefLang === "string") return `link:alternate:${hrefLang.toLowerCase()}`;
+    return null;
+  }
+
+  static #nodeOf(level: ResolveHeadResult): ReactNode {
+    return RouteHead.#isResolved(level) ? level.node : level;
+  }
+
+  static #snapshotOf(level: ResolveHeadResult): AkanHeadSnapshotV1 | undefined {
+    return RouteHead.#isResolved(level) ? level.headSnapshot : undefined;
+  }
+
+  static #isResolved(level: ResolveHeadResult): level is ResolvedHead {
+    return typeof level === "object" && level !== null && !isValidElement(level) && "node" in level;
+  }
+
+  /** `merge` for plain JSX heads, root first. */
+  static mergeNodes(nodes: ReactNode[]): ReactNode {
+    const present = nodes.filter((node) => node !== null && node !== undefined);
+    if (present.length <= 1) return present[0];
+    const levels = present.map((node) => RouteHead.#flatten(node));
+    const kept = RouteHead.#keepDeepest(levels, (child) =>
+      isValidElement(child) && typeof child.type === "string"
+        ? RouteHead.keyOf(child.type, child.props as TagProps)
+        : null,
+    );
+    
+    const children = kept.map(({ item, level, idx }) =>
+      isValidElement(item) ? cloneElement(item as ReactElement, { key: `head:${level}:${idx}` }) : item,
+    );
+    return createElement(Fragment, null, ...children);
+  }
+
+  static #mergeSnapshots(snapshots: AkanHeadSnapshotV1[]): AkanHeadSnapshotV1 {
+    const kept = RouteHead.#keepDeepest(
+      snapshots.map((snapshot) => snapshot.nodes),
+      (node: AkanHeadSnapshotNode) => RouteHead.keyOf(node.tag, node.attrs ?? {}),
+    );
+    return { version: 1, nodes: kept.map(({ item }) => item) };
+  }
+
+  static #keepDeepest<T>(levels: T[][], keyOf: (item: T) => string | null) {
+    const owner = new Map<string, number>();
+    levels.forEach((items, level) => {
+      for (const item of items) {
+        const key = keyOf(item);
+        if (key) owner.set(key, level);
+      }
+    });
+    return levels.flatMap((items, level) =>
+      items
+        .map((item, idx) => ({ item, level, idx }))
+        .filter(({ item }) => {
+          const key = keyOf(item);
+          return !key || owner.get(key) === level;
+        }),
+    );
+  }
+
+  static #flatten(node: ReactNode): ReactNode[] {
+    if (node === null || node === undefined || typeof node === "boolean") return [];
+    if (Array.isArray(node)) return node.flatMap((child: ReactNode) => RouteHead.#flatten(child));
+    if (isValidElement(node) && node.type === Fragment)
+      return RouteHead.#flatten((node.props as { children?: ReactNode }).children);
+    return [node];
+  }
+}

package/client/route/index.ts

@@ -2,6 +2,7 @@ export * from "./LayoutDefinition";
 export * from "./PageDefinition";
 export * from "./RootLayoutDefinition";
 export * from "./RouteDefinition";
+export * from "./RouteHead";
 export * from "./resolveRouteModule";
 export * from "./routeArgs";
 export * from "./routeBuilders";