npm - akanjs - Versions diffs - 2.2.13-rc.0 → 2.3.0 - Mend

akanjs 2.2.13-rc.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (149) hide show

package/client/csrTypes.ts +37 -6
package/client/makePageProto.tsx +8 -8
package/client/router.ts +5 -2
package/fetch/requestStorage.ts +41 -11
package/package.json +1 -1
package/server/cachePolicy.ts +192 -0
package/server/metadata.tsx +114 -0
package/server/routeElementComposer.tsx +21 -1
package/server/routeTreeBuilder.ts +44 -5
package/server/rscClient.tsx +127 -50
package/server/rscHttp.ts +120 -0
package/server/rscNavigationState.ts +95 -0
package/server/rscWorker.tsx +177 -86
package/server/rscWorkerHost.ts +47 -1
package/server/rscWorkerReplay.ts +5 -0
package/server/ssrFromRscRenderer.tsx +18 -6
package/server/ssrTypes.ts +2 -1
package/server/webRouter.ts +114 -110
package/types/client/csrTypes.d.ts +37 -6
package/types/fetch/requestStorage.d.ts +16 -6
package/types/server/cachePolicy.d.ts +55 -0
package/types/server/metadata.d.ts +13 -0
package/types/server/routeElementComposer.d.ts +6 -1
package/types/server/rscHttp.d.ts +16 -0
package/types/server/rscNavigationState.d.ts +35 -0
package/types/server/rscWorkerHost.d.ts +9 -0
package/types/server/rscWorkerReplay.d.ts +6 -0
package/types/server/ssrFromRscRenderer.d.ts +2 -0
package/types/server/ssrTypes.d.ts +2 -1
package/types/server/webRouter.d.ts +22 -1
package/types/ui/Button.d.ts +1 -1
package/types/ui/ClientSide.d.ts +1 -1
package/types/ui/Constant/Doc.d.ts +6 -6
package/types/ui/Constant/Mermaid.d.ts +1 -1
package/types/ui/Constant/index.d.ts +1 -1
package/types/ui/Copy.d.ts +1 -1
package/types/ui/CsrImage.d.ts +1 -1
package/types/ui/Data/CardList.d.ts +1 -1
package/types/ui/Data/Dashboard.d.ts +1 -1
package/types/ui/Data/Insight.d.ts +1 -1
package/types/ui/Data/Item.d.ts +6 -6
package/types/ui/Data/ListContainer.d.ts +1 -1
package/types/ui/Data/Pagination.d.ts +1 -1
package/types/ui/Data/TableList.d.ts +1 -1
package/types/ui/DatePicker.d.ts +3 -3
package/types/ui/Dialog/Close.d.ts +1 -1
package/types/ui/Dialog/Content.d.ts +1 -1
package/types/ui/Dialog/Provider.d.ts +1 -1
package/types/ui/Dialog/Trigger.d.ts +1 -1
package/types/ui/Dialog/index.d.ts +3 -3
package/types/ui/DragAction.d.ts +4 -4
package/types/ui/DraggableList.d.ts +3 -3
package/types/ui/Dropdown.d.ts +1 -1
package/types/ui/Empty.d.ts +1 -1
package/types/ui/Field.d.ts +22 -22
package/types/ui/Image.d.ts +1 -1
package/types/ui/InfiniteScroll.d.ts +1 -1
package/types/ui/Input.d.ts +6 -6
package/types/ui/KeyboardAvoiding.d.ts +1 -1
package/types/ui/Layout/BottomAction.d.ts +1 -1
package/types/ui/Layout/BottomInset.d.ts +1 -1
package/types/ui/Layout/BottomTab.d.ts +1 -1
package/types/ui/Layout/Header.d.ts +1 -1
package/types/ui/Layout/LeftSider.d.ts +1 -1
package/types/ui/Layout/Navbar.d.ts +1 -1
package/types/ui/Layout/RightSider.d.ts +1 -1
package/types/ui/Layout/Sider.d.ts +1 -1
package/types/ui/Layout/Template.d.ts +1 -1
package/types/ui/Layout/TopLeftAction.d.ts +1 -1
package/types/ui/Layout/Unit.d.ts +1 -1
package/types/ui/Layout/View.d.ts +1 -1
package/types/ui/Layout/Zone.d.ts +1 -1
package/types/ui/Layout/index.d.ts +12 -12
package/types/ui/Link/Back.d.ts +1 -1
package/types/ui/Link/Close.d.ts +1 -1
package/types/ui/Link/CsrLink.d.ts +1 -1
package/types/ui/Link/Lang.d.ts +1 -1
package/types/ui/Link/SsrLink.d.ts +1 -1
package/types/ui/Link/index.d.ts +1 -1
package/types/ui/Load/Edit.d.ts +1 -1
package/types/ui/Load/Edit_Client.d.ts +1 -1
package/types/ui/Load/PageCSR.d.ts +1 -1
package/types/ui/Load/Pagination.d.ts +1 -1
package/types/ui/Load/Units.d.ts +1 -1
package/types/ui/Load/View.d.ts +1 -1
package/types/ui/Loading/Area.d.ts +1 -1
package/types/ui/Loading/Button.d.ts +1 -1
package/types/ui/Loading/Input.d.ts +1 -1
package/types/ui/Loading/ProgressBar.d.ts +1 -1
package/types/ui/Loading/Skeleton.d.ts +1 -1
package/types/ui/Loading/Spin.d.ts +1 -1
package/types/ui/Loading/index.d.ts +6 -6
package/types/ui/Menu.d.ts +1 -1
package/types/ui/Modal.d.ts +1 -1
package/types/ui/Model/AdminPanel.d.ts +1 -1
package/types/ui/Model/Edit.d.ts +1 -1
package/types/ui/Model/EditModal.d.ts +1 -1
package/types/ui/Model/EditWrapper.d.ts +1 -1
package/types/ui/Model/LoadInit.d.ts +1 -1
package/types/ui/Model/New.d.ts +1 -1
package/types/ui/Model/NewWrapper.d.ts +1 -1
package/types/ui/Model/NewWrapper_Client.d.ts +1 -1
package/types/ui/Model/Remove.d.ts +1 -1
package/types/ui/Model/RemoveWrapper.d.ts +1 -1
package/types/ui/Model/SureToRemove.d.ts +1 -1
package/types/ui/Model/View.d.ts +1 -1
package/types/ui/Model/ViewEditModal.d.ts +1 -1
package/types/ui/Model/ViewModal.d.ts +1 -1
package/types/ui/Model/ViewWrapper.d.ts +1 -1
package/types/ui/More.d.ts +1 -1
package/types/ui/ObjectId.d.ts +1 -1
package/types/ui/Popconfirm.d.ts +1 -1
package/types/ui/Radio.d.ts +2 -2
package/types/ui/RecentTime.d.ts +1 -1
package/types/ui/Refresh.d.ts +1 -1
package/types/ui/ScreenNavigator.d.ts +3 -3
package/types/ui/Select.d.ts +1 -1
package/types/ui/Signal/Arg.d.ts +13 -13
package/types/ui/Signal/Doc.d.ts +6 -6
package/types/ui/Signal/Listener.d.ts +2 -2
package/types/ui/Signal/Message.d.ts +4 -4
package/types/ui/Signal/Object.d.ts +4 -4
package/types/ui/Signal/PubSub.d.ts +4 -4
package/types/ui/Signal/Request.d.ts +2 -2
package/types/ui/Signal/Response.d.ts +3 -3
package/types/ui/Signal/RestApi.d.ts +5 -5
package/types/ui/Signal/WebSocket.d.ts +2 -2
package/types/ui/System/CSR.d.ts +5 -5
package/types/ui/System/Client.d.ts +8 -8
package/types/ui/System/Common.d.ts +2 -2
package/types/ui/System/DevModeToggle.d.ts +1 -1
package/types/ui/System/Gtag.d.ts +1 -1
package/types/ui/System/Messages.d.ts +1 -1
package/types/ui/System/Reconnect.d.ts +1 -1
package/types/ui/System/Root.d.ts +1 -1
package/types/ui/System/SSR.d.ts +4 -4
package/types/ui/System/SelectLanguage.d.ts +1 -1
package/types/ui/System/ThemeToggle.d.ts +1 -1
package/types/ui/System/index.d.ts +7 -7
package/types/ui/Tab/Menu.d.ts +1 -1
package/types/ui/Tab/Menus.d.ts +1 -1
package/types/ui/Tab/Panel.d.ts +1 -1
package/types/ui/Tab/Provider.d.ts +1 -1
package/types/ui/Tab/index.d.ts +4 -4
package/types/ui/Table.d.ts +1 -1
package/types/ui/ToggleSelect.d.ts +2 -2
package/types/ui/Unauthorized.d.ts +1 -1
package/types/webkit/useCsrValues.d.ts +1 -1
package/webkit/bootCsr.tsx +16 -2

package/client/csrTypes.ts CHANGED Viewed

@@ -7,7 +7,7 @@ import type { RouterInstance } from "./router";
 import type { ReactFont } from "./types";
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
-/** Per-page CSR configuration for transition, safe-area, gesture, and cache behavior. */
+/** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
   transition?: TransitionType;
   safeArea?: boolean | "top" | "bottom";
@@ -18,8 +18,6 @@ export interface PageConfig {
   bottomInset?: boolean | number;
   gesture?: boolean;
   cache?: boolean;
-  rscCache?: "public" | false;
-  rscCacheTtl?: number;
   topSafeAreaColor?: string;
   bottomSafeAreaColor?: string;
 }
@@ -60,7 +58,12 @@ export interface LayoutErrorProps extends LayoutNotFoundProps {
 }
 export type Head = ReactNode;
 export type GenerateHead = (props: PageProps) => PromiseOrObject<Head | null | undefined>;
-export type ResolveHead = (props: PageProps) => PromiseOrObject<Head | null | undefined>;
+export interface ResolvedHead {
+  node: Head | null | undefined;
+  hasExplicitLanguageAlternates: boolean;
+}
+export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
+export type ResolveHead = (props: PageProps) => PromiseOrObject<ResolveHeadResult>;
 export type HeadProps = PageProps;
 export type PageRender = (props: PageProps) => PromiseOrObject<ReactNode>;
 export type LayoutRender = (props: LayoutProps) => PromiseOrObject<ReactNode>;
@@ -104,17 +107,45 @@ export interface WebAppManifest {
   screenshots?: WebAppManifestIcon[];
   [key: string]: unknown;
 }
+export interface AkanMetadata {
+  title?: string;
+  description?: string;
+  robots?: string;
+  openGraph?: {
+    title?: string;
+    description?: string;
+    type?: string;
+    url?: string;
+    siteName?: string;
+    images?: string | string[];
+  };
+  twitter?: {
+    card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
+    title?: string;
+    description?: string;
+    images?: string | string[];
+  };
+  alternates?: {
+    canonical?: string;
+    languages?: Record<string, string>;
+  };
+}
+export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
   default?: PageRender;
   pageConfig?: PageConfig;
   head?: Head;
+  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
+  generateMetadata?: GenerateMetadata;
   Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
   default?: LayoutRender;
   head?: Head;
+  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
+  generateMetadata?: GenerateMetadata;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
@@ -135,7 +166,7 @@ export interface Route {
   pageIncludesOwnLayout?: boolean;
   isSpecialRoute?: boolean;
-  loader?: () => any;
+  loader?: () => unknown;
   pageState?: PageState;
   children: Map<string, Route>;
@@ -229,7 +260,7 @@ export interface RouteState {
 }
 export type UseCsrTransition = CsrTransitionStyles & {
-  pageBind: (...args: any[]) => ReactDOMAttributes;
+  pageBind: (...args: unknown[]) => ReactDOMAttributes;
   pageClassName: string;
   transDirection: "vertical" | "horizontal" | "none";
   transUnitRange: number[];

package/client/makePageProto.tsx CHANGED Viewed

@@ -1,6 +1,6 @@
 import { getEnv } from "akanjs/base";
 import { parseAkanI18nEnv } from "akanjs/common";
-import { getRequest, headers } from "akanjs/fetch";
+import { untrackedHeaders, untrackedRequest } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { Translator } from "./translator";
@@ -31,12 +31,12 @@ const getPageInfo = (): { locale: string; path: string } => {
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
     return { locale, path: hasLocalePrefix ? `/${rest.join("/")}` : window.location.pathname };
   }
-  const h = headers();
+  const h = untrackedHeaders();
   const localeHeader = h.get("x-locale");
   const pathHeader = h.get("x-path");
   if (localeHeader && pathHeader) return { locale: localeHeader, path: pathHeader };
-  const req = getRequest();
+  const req = untrackedRequest();
   if (req) {
     const urlPath = new URL(req.url).pathname;
     const [, firstSegment = "", ...rest] = urlPath.split("/");
@@ -62,11 +62,11 @@ const msg = {
   warning: () => null,
   loading: () => null,
 } as {
-  info: (key: TransMessage<any>, option?: TransMessageOption) => void;
-  success: (key: TransMessage<any>, option?: TransMessageOption) => void;
-  error: (key: TransMessage<any>, option?: TransMessageOption) => void;
-  warning: (key: TransMessage<any>, option?: TransMessageOption) => void;
-  loading: (key: TransMessage<any>, option?: TransMessageOption) => void;
+  info: (key: TransMessage<Record<string, unknown>>, option?: TransMessageOption) => void;
+  success: (key: TransMessage<Record<string, unknown>>, option?: TransMessageOption) => void;
+  error: (key: TransMessage<Record<string, unknown>>, option?: TransMessageOption) => void;
+  warning: (key: TransMessage<Record<string, unknown>>, option?: TransMessageOption) => void;
+  loading: (key: TransMessage<Record<string, unknown>>, option?: TransMessageOption) => void;
 };
 export const makePageProto = <

package/client/router.ts CHANGED Viewed

@@ -62,8 +62,11 @@ export class AkanNotFoundError extends Error {
 }
 function getServerRequestContext() {
-  const { getRequest, headers } = require("akanjs/fetch");
-  return { getRequest, headers } as { getRequest: () => Request; headers: () => Map<string, string> };
+  const { untrackedHeaders, untrackedRequest } = require("akanjs/fetch");
+  return { getRequest: untrackedRequest, headers: untrackedHeaders } as {
+    getRequest: () => Request | undefined;
+    headers: () => Map<string, string>;
+  };
 }
 const getConfiguredBasePaths = () => new Set(parseBasePaths(process.env.AKAN_PUBLIC_BASE_PATHS));

package/fetch/requestStorage.ts CHANGED Viewed

@@ -2,8 +2,6 @@ export type AkanTheme = "css" | "system" | (string & {});
 export interface AkanRequestPolicy {
   routeId?: string;
-  rscCache?: "public" | false;
-  rscCacheTtl?: number;
   cacheable?: boolean;
   revalidate?: number | false;
   tags: Set<string>;
@@ -93,10 +91,10 @@ export function getRequestTheme(): AkanTheme | undefined {
   return getRequestStore()?.theme;
 }
-export function pushRequestFallback(req: Request): () => void {
+export function pushRequestFallback(storeOrRequest: Request | AkanRequestStore): () => void {
   globalThis.__AKAN_REQUEST_FALLBACK_STACK__ ??= [];
   const stack = globalThis.__AKAN_REQUEST_FALLBACK_STACK__;
-  const store = createRequestStore(req);
+  const store = normalizeRequestStore(storeOrRequest);
   stack.push(store);
   return () => {
     const index = stack.lastIndexOf(store);
@@ -110,21 +108,43 @@ export function getRequestStore(): AkanRequestStore | undefined {
 }
 /** Returns the active server request from AsyncLocalStorage or the fallback stack. */
-export function getRequest(): Request | undefined {
-  return getRequestStore()?.request;
+export function getRequest(options: { trackDynamic?: boolean } = {}): Request | undefined {
+  const store = getRequestStore();
+  if (!store) return undefined;
+  if (options.trackDynamic !== false) {
+    store.dynamicUsage.headers = true;
+    store.dynamicUsage.cookies = true;
+  }
+  return store.request;
+}
+/** Reads the framework's active server request without marking the user route dynamic. */
+export function untrackedRequest(): Request | undefined {
+  return getRequest({ trackDynamic: false });
 }
 export function getRequestPolicy(): AkanRequestPolicy | undefined {
   return getRequestStore()?.policy;
 }
+function combineMinPolicyRevalidate(
+  current: number | false | undefined,
+  next: number | false | undefined,
+): number | false | undefined {
+  if (next === undefined) return current;
+  if (current === false || next === false) return false;
+  if (current === undefined) return next;
+  return Math.min(current, next);
+}
 export function updateRequestPolicy(
   patch: Partial<Omit<AkanRequestPolicy, "tags">> & { tags?: Iterable<string> },
 ): AkanRequestPolicy | undefined {
   const policy = getRequestPolicy();
   if (!policy) return undefined;
-  const { tags, ...rest } = patch;
+  const { tags, revalidate, ...rest } = patch;
   Object.assign(policy, rest);
+  policy.revalidate = combineMinPolicyRevalidate(policy.revalidate, revalidate);
   if (tags) for (const tag of tags) policy.tags.add(tag);
   return policy;
 }
@@ -145,17 +165,22 @@ export function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>):
 }
 /** Returns current request headers as a Map, or an empty Map outside a request. */
-export function headers(): Map<string, string> {
+export function headers(options: { trackDynamic?: boolean } = {}): Map<string, string> {
   const store = getRequestStore();
   const map = new Map<string, string>();
   if (!store) return map;
-  store.dynamicUsage.headers = true;
+  if (options.trackDynamic !== false) store.dynamicUsage.headers = true;
   store.request.headers.forEach((value, key) => {
     map.set(key, value);
   });
   return map;
 }
+/** Reads headers for framework internals without marking the user route dynamic. */
+export function untrackedHeaders(): Map<string, string> {
+  return headers({ trackDynamic: false });
+}
 export interface CookieEntry {
   name: string;
   value: string;
@@ -186,9 +211,14 @@ export function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry
 }
 /** Returns parsed cookies from the current request, or an empty Map outside a request. */
-export function cookies(): Map<string, CookieEntry> {
+export function cookies(options: { trackDynamic?: boolean } = {}): Map<string, CookieEntry> {
   const store = getRequestStore();
   if (!store) return new Map();
-  store.dynamicUsage.cookies = true;
+  if (options.trackDynamic !== false) store.dynamicUsage.cookies = true;
   return parseCookieHeader(store.request.headers.get("cookie") ?? "");
 }
+/** Reads cookies for framework internals without marking the user route dynamic. */
+export function untrackedCookies(): Map<string, CookieEntry> {
+  return cookies({ trackDynamic: false });
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.13-rc.0",
+  "version": "2.3.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/cachePolicy.ts ADDED Viewed

@@ -0,0 +1,192 @@
+import { type AkanDynamicUsage, type AkanRequestPolicy, parseCookieHeader } from "akanjs/fetch";
+export const DEFAULT_ROUTE_CACHE_TTL_SECONDS = 30;
+export interface RouteCacheKeyInput {
+  request: Request;
+  url: URL;
+  theme?: string;
+}
+export interface RouteCacheRenderState {
+  cacheable: boolean;
+  revalidate?: number | false;
+  tags?: string[];
+  dynamicUsage?: AkanDynamicUsage;
+  reason?: string;
+}
+export interface RouteCacheEntry {
+  key: string;
+  ttl: number;
+}
+export type RouteCacheRenderControlType = "redirect" | "not-found" | "error";
+export function parsePositiveInt(value: string | undefined | null): number | null {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+export function normalizeRouteCacheTtl(value: unknown, fallback = 30): number | null {
+  if (value === false || value === null) return null;
+  if (value === undefined) return fallback;
+  const ttl = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+  return Number.isFinite(ttl) && ttl > 0 ? ttl : null;
+}
+export function resolveAutoRouteCacheTtl(input: {
+  enabled?: string | null;
+  ttl?: string | null;
+  defaultTtl?: number;
+}): number | null {
+  if (input.enabled !== "1") return null;
+  return normalizeRouteCacheTtl(input.ttl, input.defaultTtl ?? DEFAULT_ROUTE_CACHE_TTL_SECONDS);
+}
+export function combineMinRevalidate(...values: Array<number | false | null | undefined>): number | false | undefined {
+  let out: number | undefined;
+  for (const value of values) {
+    if (value === undefined || value === null) continue;
+    if (value === false) return false;
+    out = out === undefined ? value : Math.min(out, value);
+  }
+  return out;
+}
+export function getClientFacingOrigin(request: Request, url = new URL(request.url)): string {
+  const forwardedProto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+  const forwardedHost = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim();
+  const host = forwardedHost ?? request.headers.get("host")?.split(",")[0]?.trim();
+  const proto = forwardedProto ?? url.protocol.slice(0, -1);
+  if (host && proto) {
+    try {
+      return new URL(`${proto}://${host}`).origin;
+    } catch {
+    }
+  }
+  return url.origin;
+}
+export function isPublicRouteCacheableRequest(request: Request): boolean {
+  if (request.method !== "GET") return false;
+  if (request.headers.has("authorization")) return false;
+  const cookie = request.headers.get("cookie");
+  if (!cookie) return true;
+  return [...parseCookieHeader(cookie).keys()].every((name) => name === "theme");
+}
+export function isRouteCachePathAllowed(
+  pathname: string,
+  options: { allow?: string | null; deny?: string | null } = {},
+): boolean {
+  const matches = (raw: string | null | undefined) => {
+    const prefixes = (raw ?? "")
+      .split(",")
+      .map((prefix) => prefix.trim())
+      .filter(Boolean);
+    if (prefixes.length === 0) return false;
+    return prefixes.some(
+      (prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`),
+    );
+  };
+  if (matches(options.deny)) return false;
+  const allow = options.allow ?? "";
+  return matches(allow);
+}
+export function createRouteCacheKey({ request, url, theme = "" }: RouteCacheKeyInput): string {
+  return [
+    getClientFacingOrigin(request, url),
+    request.headers.get("x-base-path") ?? "",
+    request.headers.get("x-locale") ?? "",
+    request.headers.get("x-path") ?? "",
+    url.pathname,
+    url.search,
+    request.headers.get("accept-language") ?? "",
+    theme,
+  ].join("\n");
+}
+export function createRouteCacheEntry(input: RouteCacheKeyInput & { ttl: number }): RouteCacheEntry {
+  return { key: createRouteCacheKey(input), ttl: input.ttl };
+}
+export function resolveRouteCacheStoreTtl(baseTtl: number, state: RouteCacheRenderState): number | null {
+  if (!state.cacheable || state.revalidate === false) return null;
+  if (typeof state.revalidate !== "number") return baseTtl;
+  if (!Number.isFinite(state.revalidate) || state.revalidate <= 0) return null;
+  return Math.min(baseTtl, state.revalidate);
+}
+export function shouldStoreRouteCache(input: {
+  policy?: AkanRequestPolicy;
+  dynamicUsage?: AkanDynamicUsage;
+  renderControlType?: RouteCacheRenderControlType;
+  lateRedirect?: boolean;
+}): RouteCacheRenderState {
+  const dynamicUsage = input.dynamicUsage ? { ...input.dynamicUsage } : undefined;
+  const tags = input.policy ? [...input.policy.tags] : undefined;
+  const revalidate = combineMinRevalidate(input.policy?.revalidate);
+  if (input.renderControlType) {
+    const reason =
+      input.renderControlType === "redirect" && input.lateRedirect
+        ? "late-redirect"
+        : `render-${input.renderControlType}`;
+    return { cacheable: false, revalidate, tags, dynamicUsage, reason };
+  }
+  if (dynamicUsage?.headers || dynamicUsage?.cookies)
+    return { cacheable: false, revalidate, tags, dynamicUsage, reason: "dynamic-request-api" };
+  return { cacheable: input.policy?.cacheable !== false, revalidate, tags, dynamicUsage };
+}
+export class LruTtlCache<T> {
+  readonly #entries = new Map<string, { value: T; expiresAt: number }>();
+  constructor(readonly maxEntries = 100) {}
+  get size(): number {
+    return this.#entries.size;
+  }
+  get(key: string): T | null {
+    const entry = this.#entries.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key);
+      return null;
+    }
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    return entry.value;
+  }
+  set(key: string, value: T, ttlSeconds: number): void {
+    this.#entries.delete(key);
+    const maxEntries = this.maxEntries > 0 ? this.maxEntries : 100;
+    while (this.#entries.size >= maxEntries) {
+      const oldest = this.#entries.keys().next().value;
+      if (!oldest) break;
+      this.#entries.delete(oldest);
+    }
+    this.#entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+  }
+  delete(key: string): boolean {
+    return this.#entries.delete(key);
+  }
+  invalidate(predicate: (key: string, value: T) => boolean): number {
+    let count = 0;
+    for (const [key, entry] of this.#entries) {
+      if (!predicate(key, entry.value)) continue;
+      this.#entries.delete(key);
+      count += 1;
+    }
+    return count;
+  }
+  clear(): void {
+    this.#entries.clear();
+  }
+}

package/server/metadata.tsx ADDED Viewed

@@ -0,0 +1,114 @@
+import type { AkanMetadata, Head, ResolvedHead, ResolveHeadResult } from "akanjs/client";
+import type { ReactNode } from "react";
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function normalizeStringArray(value: string | string[] | undefined): string[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function renderOpenGraph(metadata: AkanMetadata): ReactNode[] {
+  const openGraph = metadata.openGraph;
+  if (!openGraph) return [];
+  const nodes: ReactNode[] = [];
+  if (openGraph.title) nodes.push(<meta key="og:title" property="og:title" content={openGraph.title} />);
+  if (openGraph.description)
+    nodes.push(<meta key="og:description" property="og:description" content={openGraph.description} />);
+  if (openGraph.type) nodes.push(<meta key="og:type" property="og:type" content={openGraph.type} />);
+  if (openGraph.url) nodes.push(<meta key="og:url" property="og:url" content={openGraph.url} />);
+  if (openGraph.siteName) nodes.push(<meta key="og:site_name" property="og:site_name" content={openGraph.siteName} />);
+  for (const [index, image] of normalizeStringArray(openGraph.images).entries()) {
+    nodes.push(<meta key={`og:image:${index}`} property="og:image" content={image} />);
+  }
+  return nodes;
+}
+function renderTwitter(metadata: AkanMetadata): ReactNode[] {
+  const twitter = metadata.twitter;
+  if (!twitter) return [];
+  const nodes: ReactNode[] = [];
+  if (twitter.card) nodes.push(<meta key="twitter:card" name="twitter:card" content={twitter.card} />);
+  if (twitter.title) nodes.push(<meta key="twitter:title" name="twitter:title" content={twitter.title} />);
+  if (twitter.description)
+    nodes.push(<meta key="twitter:description" name="twitter:description" content={twitter.description} />);
+  for (const [index, image] of normalizeStringArray(twitter.images).entries()) {
+    nodes.push(<meta key={`twitter:image:${index}`} name="twitter:image" content={image} />);
+  }
+  return nodes;
+}
+function renderAlternates(metadata: AkanMetadata): ReactNode[] {
+  const alternates = metadata.alternates;
+  if (!alternates) return [];
+  const nodes: ReactNode[] = [];
+  if (alternates.canonical) nodes.push(<link key="canonical" rel="canonical" href={alternates.canonical} />);
+  if (alternates.languages) {
+    for (const [lang, href] of Object.entries(alternates.languages)) {
+      nodes.push(<link key={`metadata:alternate:${lang}`} rel="alternate" hrefLang={lang} href={href} />);
+    }
+  }
+  return nodes;
+}
+export function isAkanMetadata(value: unknown): value is AkanMetadata {
+  if (!isRecord(value)) return false;
+  return (
+    "title" in value ||
+    "description" in value ||
+    "robots" in value ||
+    "openGraph" in value ||
+    "twitter" in value ||
+    "alternates" in value
+  );
+}
+export function renderMetadata(metadata: AkanMetadata): Head {
+  return (
+    <>
+      {metadata.title ? <title>{metadata.title}</title> : null}
+      {metadata.description ? <meta name="description" content={metadata.description} /> : null}
+      {metadata.robots ? <meta name="robots" content={metadata.robots} /> : null}
+      {renderOpenGraph(metadata)}
+      {renderTwitter(metadata)}
+      {renderAlternates(metadata)}
+    </>
+  );
+}
+export function hasExplicitLanguageAlternates(metadata: AkanMetadata | null | undefined): boolean {
+  return Boolean(metadata?.alternates?.languages && Object.keys(metadata.alternates.languages).length > 0);
+}
+export function shouldRenderLocaleAlternates(options: {
+  isSpecialRoute?: boolean;
+  hasExplicitLanguageAlternates?: boolean;
+}): boolean {
+  return options.isSpecialRoute !== true && options.hasExplicitLanguageAlternates !== true;
+}
+export function isResolvedHead(value: unknown): value is ResolvedHead {
+  return isRecord(value) && "node" in value && "hasExplicitLanguageAlternates" in value;
+}
+export function resolveMetadataHead(metadata: AkanMetadata): ResolvedHead {
+  return {
+    node: renderMetadata(metadata),
+    hasExplicitLanguageAlternates: hasExplicitLanguageAlternates(metadata),
+  };
+}
+export function resolveHeadExport(value: Head | AkanMetadata | null | undefined): ResolvedHead {
+  return isAkanMetadata(value) ? resolveMetadataHead(value) : { node: value, hasExplicitLanguageAlternates: false };
+}
+export function resolveHeadResult(value: ResolveHeadResult): ResolvedHead {
+  if (isResolvedHead(value)) return value;
+  return resolveHeadExport(value as Head | AkanMetadata | null | undefined);
+}
+export function normalizeHead(value: Head | AkanMetadata | null | undefined): Head | null | undefined {
+  return isAkanMetadata(value) ? renderMetadata(value) : value;
+}

package/server/routeElementComposer.tsx CHANGED Viewed

@@ -4,9 +4,11 @@ import type {
   LayoutFallbackRoute,
   LayoutNotFoundRender,
   PathRoute,
+  ResolvedHead,
   RouteRender,
 } from "akanjs/client";
 import { Children, cloneElement, isValidElement, type ReactElement, type ReactNode, Suspense } from "react";
+import { resolveHeadResult } from "./metadata";
 export class RouteElementComposer {
   static compose({
@@ -43,7 +45,25 @@ export class RouteElementComposer {
     params: Record<string, string>;
     searchParams: Record<string, string | string[]>;
   }): Promise<Head | null | undefined> {
-    return pathRoute.resolveHead?.({ params, searchParams });
+    return (
+      await RouteElementComposer.resolveHeadWithMetadata({
+        pathRoute,
+        params,
+        searchParams,
+      })
+    ).node;
+  }
+  static async resolveHeadWithMetadata({
+    pathRoute,
+    params,
+    searchParams,
+  }: {
+    pathRoute: PathRoute;
+    params: Record<string, string>;
+    searchParams: Record<string, string[] | string>;
+  }): Promise<ResolvedHead> {
+    return resolveHeadResult(await pathRoute.resolveHead?.({ params, searchParams }));
   }
   static async composeFallback({