akanjs 3.1.0-rc.1 → 3.1.0-rc.3

package/base/primitiveRegistry.ts

@@ -192,7 +192,7 @@ export class Any extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Any);
 
-type NodeBuffer = Uint8Array & { toString(encoding: string): string };
+type NodeBuffer = Uint8Array<ArrayBuffer> & { toString(encoding: string): string };
 interface BufferCtor {
   from(buffer: ArrayBufferLike, byteOffset: number, length: number): NodeBuffer;
   from(text: string, encoding: string): NodeBuffer;
@@ -210,13 +210,13 @@ export class Binary extends PrimitiveScalar {
     return value instanceof Uint8Array || typeof value === "string";
   }
   static override parseValue(input: Uint8Array | string): Uint8Array {
-    return typeof input === "string" ? Binary.#fromBase64(input) : input;
+    return typeof input === "string" ? Binary.fromBase64(input) : input;
   }
   static override serializeValue(value: Uint8Array | string): string {
-    return typeof value === "string" ? value : Binary.#toBase64(value);
+    return typeof value === "string" ? value : Binary.toBase64(value);
   }
 
-  static #toBase64(bytes: Uint8Array): string {
+  static toBase64(bytes: Uint8Array): string {
     const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
     if (buffer) return buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
     let binary = "";
@@ -224,7 +224,7 @@ export class Binary extends PrimitiveScalar {
       binary += String.fromCharCode(...bytes.subarray(idx, idx + 0x8000));
     return btoa(binary);
   }
-  static #fromBase64(text: string): Uint8Array {
+  static fromBase64(text: string): Uint8Array<ArrayBuffer> {
     const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
     if (buffer) return buffer.from(text, "base64");
     const binary = atob(text);
@@ -246,6 +246,65 @@ export class Upload extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Upload);
 
+export type ImageResultMimeType = (typeof ImageResult.mimeTypes)[number];
+export interface ImageResultValue {
+  /** Standard padded base64, without a `data:` prefix. */
+  data: string;
+  mimeType: ImageResultMimeType;
+  caption?: string | null;
+}
+
+/** A picture an endpoint returns: JSON over HTTP, an image content block over MCP. Not storable. */
+export class ImageResult extends PrimitiveScalar {
+  static override refName: "ImageResult" = "ImageResult";
+  static override [SERVER_VALUE]: ImageResultValue;
+  static override [CLIENT_VALUE]: ImageResultValue;
+  static override [DEFAULT_VALUE]: ImageResultValue | null = null;
+  static override [PURIFIED_VALUE]: ImageResultValue | null = null;
+  static override [EXAMPLE_VALUE]: ImageResultValue = {
+    data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
+    mimeType: "image/png",
+    caption: "A 1x1 pixel.",
+  };
+  
+  static readonly mimeTypes = ["image/png", "image/jpeg", "image/webp", "image/gif"] as const;
+  static override jsonSchema: PrimitiveJsonSchema = {
+    type: "object",
+    properties: {
+      data: { type: "string", contentEncoding: "base64" },
+      mimeType: { type: "string", enum: [...ImageResult.mimeTypes] },
+      caption: { type: ["string", "null"] },
+    },
+    required: ["data", "mimeType"],
+    additionalProperties: false,
+  };
+  
+  static override agent: PrimitiveAgentFace<ImageResultValue> = {
+    schema: {
+      type: "object",
+      properties: { mimeType: { type: "string" }, caption: { type: "string" } },
+      required: ["mimeType"],
+    },
+    read: ({ mimeType, caption }) => (caption ? { mimeType, caption } : { mimeType }),
+  };
+
+  static override validate(value: ImageResultValue): boolean {
+    if (!value || typeof value !== "object") return false;
+    const { data, mimeType, caption } = value;
+    return (
+      typeof data === "string" &&
+      ImageResult.#isBase64(data) &&
+      (ImageResult.mimeTypes as readonly string[]).includes(mimeType) &&
+      (caption === undefined || caption === null || typeof caption === "string")
+    );
+  }
+
+  static #isBase64(data: string) {
+    return data.length > 0 && data.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(data);
+  }
+}
+PrimitiveRegistry.register(ImageResult);
+
 declare global {
   interface StringConstructor {
     refName: "String";
@@ -388,4 +447,14 @@ Object.assign(Date, {
 });
 PrimitiveRegistry.register(Date);
 
-export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Binary" | "Upload";
+export type DefaultPrimitiveName =
+  | "String"
+  | "Boolean"
+  | "Date"
+  | "Int"
+  | "Float"
+  | "ID"
+  | "Any"
+  | "Binary"
+  | "Upload"
+  | "ImageResult";

package/client/cookie.ts

@@ -1,6 +1,7 @@
 import { getEnv } from "akanjs/base";
 import {
   authTokenKey,
+  bearerTokenOf,
   decodeJwtPayload,
   isOwnAuthToken,
   Logger,
@@ -115,7 +116,7 @@ export const getAccount = <AddData = unknown>(): 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, "");
+  const jwt = getAuthToken() ?? bearerTokenOf(getHeader("authorization"));
   if (!jwt) return defaultAccount;
   const account = decodeJwtPayload<Account<AddData>>(jwt);
   if (account.appName !== getEnv().appName || account.environment !== getEnv().environment) return defaultAccount;

package/client/csrTypes.ts

@@ -3,12 +3,13 @@ import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/sr
 import type { PromiseOrObject } from "akanjs/base";
 import { type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
 import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "react-spring";
+import type { TailwindBreakpoint } from "./frameConfig";
 import type { RouteDefinition } from "./route/RouteDefinition";
 import type { RouterInstance } from "./router";
 import { sharedContext } from "./sharedContext";
+import type { TransitionType } from "./transitionTypes";
 import type { ReactFont } from "./types";
 
-export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
 export type PageSafeAreaConfig =
   | boolean
   | "top"
@@ -22,14 +23,9 @@ 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 {
+/** Px per breakpoint of `insetBreakpoints`, each from its own width up, and `base` below the first. */
+export interface ResponsiveInset extends Partial<{ [name in TailwindBreakpoint]: number }> {
   base: number;
-  sm?: number;
-  md?: number;
-  lg?: number;
-  xl?: number;
-  "2xl"?: number;
 }
 export interface PageConfig {
   transition?: TransitionType;

package/client/frameConfig.ts

@@ -1,12 +1,6 @@
 import { isRecord } from "akanjs/common";
-import type {
-  PageConfig,
-  PageSafeAreaConfig,
-  PageState,
-  ResponsiveInset,
-  SsrRenderMode,
-  TransitionType,
-} from "./csrTypes";
+import type { PageConfig, PageSafeAreaConfig, PageState, ResponsiveInset, SsrRenderMode } from "./csrTypes";
+import { transitionTypes } from "./transitionTypes";
 
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
 export type SafeAreaInsets = { top: number; bottom: number };
@@ -22,7 +16,7 @@ export interface ResolvePageStateOptions {
   width?: number;
 }
 
-/** Tailwind's default breakpoints in rem, the widths a `ResponsiveInset` keys on. */
+/** Tailwind's default breakpoints in rem, the widths a `ResponsiveInset` keys on; `ui/styles.css` repeats them. */
 export const insetBreakpoints = [
   ["sm", 40],
   ["md", 48],
@@ -30,7 +24,14 @@ export const insetBreakpoints = [
   ["xl", 80],
   ["2xl", 96],
 ] as const;
-export type InsetBreakpoint = "base" | (typeof insetBreakpoints)[number][0];
+export type TailwindBreakpoint = (typeof insetBreakpoints)[number][0];
+export type InsetBreakpoint = "base" | TailwindBreakpoint;
+
+const breakpointRem = Object.fromEntries(insetBreakpoints) as { [name in TailwindBreakpoint]: number };
+
+/** The media query Tailwind's `<name>:` variant matches, or with `below` its `max-<name>:` one. */
+export const breakpointQuery = (name: TailwindBreakpoint, { below = false }: { below?: boolean } = {}) =>
+  `(width ${below ? "<" : ">="} ${breakpointRem[name]}rem)`;
 
 const pageConfigKeys = new Set<keyof PageConfig>([
   "transition",
@@ -46,13 +47,12 @@ const pageConfigKeys = new Set<keyof PageConfig>([
 ]);
 
 const buildPageConfigKeys = new Set<keyof PageConfig>(["devOnly"]);
-const transitionTypes = new Set<TransitionType>(["none", "fade", "bottomUp", "stack", "scaleOut"]);
 const ssrRenderModes = new Set<SsrRenderMode>(["stream", "block"]);
 const DEFAULT_BOOLEAN_INSET = 48;
 
 const hasOwn = <Key extends PropertyKey>(value: object, key: Key) => Object.hasOwn(value, key);
 
-export function validatePageConfig(routeKey: string, config?: PageConfig) {
+export const validatePageConfig = (routeKey: string, config?: PageConfig) => {
   if (config === undefined) return;
   if (!isRecord(config)) throw new Error(`[route-convention] pageConfig in ${routeKey} must be an object.`);
   const pageConfig = config as PageConfig;
@@ -64,7 +64,7 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   if (pageConfig.devOnly !== undefined && typeof pageConfig.devOnly !== "boolean") {
     throw new Error(`[route-convention] pageConfig.devOnly in ${routeKey} must be a boolean.`);
   }
-  if (pageConfig.transition !== undefined && !transitionTypes.has(pageConfig.transition)) {
+  if (pageConfig.transition !== undefined && !transitionTypes.includes(pageConfig.transition)) {
     throw new Error(`[route-convention] unsupported pageConfig.transition "${pageConfig.transition}" in ${routeKey}`);
   }
   if (pageConfig.ssr !== undefined && !ssrRenderModes.has(pageConfig.ssr)) {
@@ -77,22 +77,22 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
       );
   }
   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"]> {
+const isValidInsetValue = (value: unknown): value is NonNullable<PageConfig["topInset"]> => {
   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 } {
+export const 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;
@@ -101,17 +101,17 @@ export function insetsByBreakpoint(inset: PageConfig["topInset"]): { [bp in Inse
     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 {
+export const 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) {
+const validateSafeAreaConfig = (routeKey: string, safeArea?: PageSafeAreaConfig) => {
   if (safeArea === undefined || typeof safeArea === "boolean" || safeArea === "top" || safeArea === "bottom") return;
   if (!isRecord(safeArea)) throw new Error(`[route-convention] pageConfig.safeArea in ${routeKey} is invalid.`);
   for (const key of Object.keys(safeArea)) {
@@ -131,9 +131,9 @@ function validateSafeAreaConfig(routeKey: string, safeArea?: PageSafeAreaConfig)
   ) {
     throw new Error(`[route-convention] pageConfig.safeArea.android in ${routeKey} is invalid.`);
   }
-}
+};
 
-export function mergePageConfigs(configChain: PageConfig[] = []): PageConfig {
+export const mergePageConfigs = (configChain: PageConfig[] = []): PageConfig => {
   const merged: PageConfig = {};
   for (const config of configChain) {
     for (const key of pageConfigKeys) {
@@ -147,9 +147,11 @@ export function mergePageConfigs(configChain: PageConfig[] = []): PageConfig {
     }
   }
   return merged;
-}
+};
 
-export function getExplicitPageConfigKeys(configChain: PageConfig[] = []): Partial<Record<keyof PageConfig, boolean>> {
+export const getExplicitPageConfigKeys = (
+  configChain: PageConfig[] = [],
+): Partial<Record<keyof PageConfig, boolean>> => {
   const explicitKeys: Partial<Record<keyof PageConfig, boolean>> = {};
   for (const config of configChain) {
     for (const key of pageConfigKeys) {
@@ -157,7 +159,7 @@ export function getExplicitPageConfigKeys(configChain: PageConfig[] = []): Parti
     }
   }
   return explicitKeys;
-}
+};
 
 export const defaultPageState: PageState = {
   transition: "none",
@@ -172,7 +174,7 @@ export const defaultPageState: PageState = {
   bottomSafeAreaColor: "var(--color-background, Canvas)",
 };
 
-export function resolvePageState({
+export const resolvePageState = ({
   configChain = [],
   path,
   basePath,
@@ -180,7 +182,7 @@ export function resolvePageState({
   deviceSafeArea,
   cssSafeArea,
   width,
-}: ResolvePageStateOptions): PageState {
+}: ResolvePageStateOptions): PageState => {
   const profile = getPlatformFrameProfile(platform);
   const routeRole = getRouteRoleFrameDefaults(path, platform, basePath);
   const config = mergePageConfigs([profile, routeRole, ...configChain]);
@@ -221,29 +223,29 @@ export function resolvePageState({
     topSafeAreaColor: config.topSafeAreaColor ?? defaultPageState.topSafeAreaColor,
     bottomSafeAreaColor: config.bottomSafeAreaColor ?? defaultPageState.bottomSafeAreaColor,
   };
-}
+};
 
-function resolveInset(inset: PageConfig["topInset"]): number {
+const 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 {
+const 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 {
+const getPlatformFrameProfile = (platform: DevicePlatform): PageConfig => {
   if (platform === "ios") return { safeArea: true, transition: "stack" };
   if (platform === "android") return { safeArea: { android: "auto" }, transition: "scaleOut", gesture: false };
   return { safeArea: false, transition: "none", gesture: false };
-}
+};
 
-function getRouteRoleFrameDefaults(path: string, platform: DevicePlatform, basePath?: string): PageConfig {
+const getRouteRoleFrameDefaults = (path: string, platform: DevicePlatform, basePath?: string): PageConfig => {
   const normalizedBasePath = basePath?.replace(/^\/+|\/+$/g, "");
   const depth = path
     .split("/")
@@ -255,9 +257,9 @@ function getRouteRoleFrameDefaults(path: string, platform: DevicePlatform, baseP
     transition: platform === "ios" ? "stack" : platform === "android" ? "scaleOut" : "none",
     gesture: platform === "ios",
   };
-}
+};
 
-function resolveSafeArea({
+const resolveSafeArea = ({
   safeArea,
   platform,
   deviceSafeArea,
@@ -267,7 +269,7 @@ function resolveSafeArea({
   platform: DevicePlatform;
   deviceSafeArea: SafeAreaInsets;
   cssSafeArea?: SafeAreaInsets;
-}): SafeAreaInsets {
+}): SafeAreaInsets => {
   if (safeArea === false) return { top: 0, bottom: 0 };
   const enabledAt = (side: "top" | "bottom") =>
     safeArea === true ||
@@ -296,7 +298,7 @@ function resolveSafeArea({
     top: topEnabled ? source.top : 0,
     bottom: bottomEnabled ? source.bottom : 0,
   };
-}
+};
 
 const hasInset = (insets: SafeAreaInsets) => insets.top > 0 || insets.bottom > 0;
 
@@ -305,16 +307,16 @@ const maxInsets = (a: SafeAreaInsets, b?: SafeAreaInsets): SafeAreaInsets => ({
   bottom: Math.max(a.bottom, b?.bottom ?? 0),
 });
 
-export function readCssSafeAreaInsets(): SafeAreaInsets {
+export const readCssSafeAreaInsets = (): SafeAreaInsets => {
   if (typeof window === "undefined") return { top: 0, bottom: 0 };
   const style = window.getComputedStyle?.(document.documentElement);
   return {
     top: readCssPixel(style?.getPropertyValue("--akan-native-safe-area-top")) || readCssEnvProbe("top"),
     bottom: readCssPixel(style?.getPropertyValue("--akan-native-safe-area-bottom")) || readCssEnvProbe("bottom"),
   };
-}
+};
 
-function readCssEnvProbe(side: "top" | "bottom") {
+const readCssEnvProbe = (side: "top" | "bottom") => {
   if (typeof document === "undefined") return 0;
   const probe = document.createElement("div");
   probe.style.position = "fixed";
@@ -325,10 +327,10 @@ function readCssEnvProbe(side: "top" | "bottom") {
   const value = readCssPixel(window.getComputedStyle(probe)[side]);
   probe.remove();
   return value;
-}
+};
 
-function readCssPixel(value?: string) {
+const readCssPixel = (value?: string) => {
   if (!value) return 0;
   const parsed = Number.parseFloat(value);
   return Number.isFinite(parsed) ? parsed : 0;
-}
+};

package/client/index.ts

@@ -9,12 +9,14 @@ export * from "./device";
 export * from "./frameConfig";
 export * from "./locale";
 export * from "./makePageProto";
+export * from "./mcpView";
 export * from "./resolveServerUrl";
 export * from "./route";
 export * from "./router";
 export * from "./rscNavigation";
 export * from "./sharedContext";
 export * from "./storage";
+export * from "./transitionTypes";
 export * from "./translator";
 export * from "./types";
 export * from "./useClient";

package/client/mcpView.ts

@@ -0,0 +1,2 @@
+/** Whether the page runs in a view an MCP host renders, where the host relays every call and owns the frame. */
+export const isMcpView = () => !!globalThis.__AKAN_EMBED__;

package/client/route/RouteHead.ts

@@ -14,14 +14,27 @@ export class RouteHead {
     "apple-touch-icon",
     "mask-icon",
   ]);
+  
+  static readonly #pageIdentityKeys = new Set(["link:canonical", "meta:property:og:url"]);
 
   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;
+    if (!present.some((level) => RouteHead.#snapshotOf(level))) return node;
+    const snapshotLevels: AkanHeadSnapshotNode[][] = [];
+    for (const level of present) {
+      const nodes = RouteHead.#snapshotOf(level)?.nodes ?? RouteHead.#snapshotNodesOf(RouteHead.#nodeOf(level));
+      
+      if (!nodes) return node;
+      snapshotLevels.push(nodes);
+    }
+    return { node, headSnapshot: RouteHead.#mergeSnapshots(snapshotLevels) } satisfies ResolvedHead;
+  }
+
+  /** `merge` of a page's head over its layouts': a canonical or `og:url` comes from the page or not at all. */
+  static mergePage(layouts: ResolveHeadResult, page: ResolveHeadResult): ResolveHeadResult {
+    return RouteHead.merge([RouteHead.#withoutPageIdentity(layouts), page]);
   }
 
   /** What makes two tags the same tag; `null` for one that never replaces another. */
@@ -60,11 +73,7 @@ export class RouteHead {
     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 kept = RouteHead.#keepDeepest(levels, (child) => RouteHead.#keyOfNode(child));
     
     const children = kept.map(({ item, level, idx }) =>
       isValidElement(item) ? cloneElement(item as ReactElement, { key: `head:${level}:${idx}` }) : item,
@@ -72,14 +81,59 @@ export class RouteHead {
     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 ?? {}),
+  static #keyOfNode(child: ReactNode): string | null {
+    return isValidElement(child) && typeof child.type === "string"
+      ? RouteHead.keyOf(child.type, child.props as TagProps)
+      : null;
+  }
+
+  static #withoutPageIdentity(level: ResolveHeadResult): ResolveHeadResult {
+    const isIdentity = (key: string | null) => key !== null && RouteHead.#pageIdentityKeys.has(key);
+    const node = RouteHead.#nodeOf(level);
+    const children = RouteHead.#flatten(node);
+    const kept = children.filter((child) => !isIdentity(RouteHead.#keyOfNode(child)));
+    const keptNode =
+      kept.length === children.length ? node : kept.length > 0 ? createElement(Fragment, null, ...kept) : null;
+    const snapshot = RouteHead.#snapshotOf(level);
+    if (!snapshot) return keptNode;
+    const nodes = snapshot.nodes.filter((item) => !isIdentity(RouteHead.keyOf(item.tag, item.attrs ?? {})));
+    return { node: keptNode, headSnapshot: { ...snapshot, nodes } };
+  }
+
+  static #mergeSnapshots(levels: AkanHeadSnapshotNode[][]): AkanHeadSnapshotV1 {
+    const kept = RouteHead.#keepDeepest(levels, (node: AkanHeadSnapshotNode) =>
+      RouteHead.keyOf(node.tag, node.attrs ?? {}),
     );
     return { version: 1, nodes: kept.map(({ item }) => item) };
   }
 
+  static #snapshotNodesOf(node: ReactNode): AkanHeadSnapshotNode[] | null {
+    const nodes: AkanHeadSnapshotNode[] = [];
+    for (const child of RouteHead.#flatten(node)) {
+      const snapshotNode = RouteHead.#snapshotNodeOf(child);
+      if (!snapshotNode) return null;
+      nodes.push(snapshotNode);
+    }
+    return nodes;
+  }
+
+  static #snapshotNodeOf(child: ReactNode): AkanHeadSnapshotNode | null {
+    if (!isValidElement(child)) return null;
+    const tag = child.type;
+    if (tag !== "title" && tag !== "meta" && tag !== "link") return null;
+    const { children, ...props } = child.props as TagProps;
+    if (tag === "title")
+      return typeof children === "string" || typeof children === "number" ? { tag, text: String(children) } : null;
+    if (children !== undefined && children !== null) return null;
+    const attrs: Record<string, string> = {};
+    for (const [name, value] of Object.entries(props)) {
+      if (value === undefined || value === null) continue;
+      if (typeof value !== "string" && typeof value !== "number") return null;
+      attrs[name] = String(value);
+    }
+    return { tag, attrs };
+  }
+
   static #keepDeepest<T>(levels: T[][], keyOf: (item: T) => string | null) {
     const owner = new Map<string, number>();
     levels.forEach((items, level) => {