akanjs 3.1.1 → 3.1.2-rc.0

package/README.ko.md

@@ -46,6 +46,28 @@ akan start <app-name> --open
 워크스페이스 이름과 앱 이름을 물은 뒤 `akan` CLI와 워크스페이스 의존성을 설치하고 샘플 앱을 만들어 줍니다. 앱은
 `http://localhost:8282`에서 열립니다.
 
+### 기존 저장소 안에서 시작하기
+
+앱이 놓일 폴더와 실행 방식이 정해진 작업이라면, 예를 들어 다른 저장소의 하위 폴더, Node와 npm만 있는 호스트, 스펙이 정한
+URL이라면, 코딩 에이전트는 묻지 않고 아래대로 진행하면 됩니다.
+
+- **그 폴더에 바로 만들기:** `bunx create-akan-workspace@latest . --app <app> --dir <folder> --sample false`.
+  `<folder>` 자체에 쓰고, 이미 있는 파일은 덮어쓰지 않고 멈추며, 샘플 모듈과 페이지는 만들지 않습니다. 함께 생기는
+  `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.agents/`, `.cursor/`, `.mcp.json`은 지우지 마세요. 에이전트가 따를 규칙과
+  도구가 들어 있습니다.
+- **`<folder>`에서 작업하기.** `akan`은 워크스페이스 루트에서만 실행되고, 그곳에서 연 에이전트 세션이 워크스페이스의
+  규칙과 MCP 서버를 불러옵니다.
+- **변경마다 `akan verify <app>`로 확인하기.** sync, lint, 타입체크, 빌드, SSR 검사를 한 번에 하고 실패한 것만
+  출력합니다. `akan preview <app> --changed`는 변경이 닿는 페이지를 열어 봅니다.
+- **정해진 URL:** 페이지는 기본적으로 `/<locale>/…` 아래에 있습니다. 기본 로케일을 프리픽스 없는 경로
+  (`/pokemon/deoxys`)로 내보내려면 `akan.config.ts`에 `i18n: { defaultLocale: "en", locales: ["en"], localePrefix:
+  "as-needed" }`를 두세요. `<Link>`도 따라갑니다.
+- **Node와 npm만 있는 호스트:** `npm install -g bun`으로 생성기를 실행할 런타임을 받으세요. 호스트에도 설치되도록
+  워크스페이스의 `dependencies`에 `bun`을 두고, package script에서는 `devDependencies`의 `@akanjs/cli`로 `akan`을
+  부르세요. 전역 설치 뒤 `akan`을 찾지 못하면 `bun pm bin -g`가 출력하는 폴더를 `PATH`에 더하세요.
+- **Docker 없이 프로덕션 빌드 실행:** `akan build <app>` 뒤 `cd dist/apps/<app> && PORT=3000 bun main.js`. 빌드에
+  필요한 env가 함께 들어 있습니다.
+
 ## 이 모든 게 한 줄입니다
 
 ```ts

package/README.md

@@ -45,6 +45,28 @@ akan start <app-name> --open
 The creator asks for a workspace name and an app name, installs the `akan` CLI and the workspace's dependencies, and
 generates a sample app. The app opens on `http://localhost:8282`.
 
+### Inside an existing repository
+
+When a task fixes where the app lives and how it runs, for example a folder in another repository, a host with only
+Node and npm, or URLs given by a spec, a coding agent needs these, and nothing has to ask:
+
+- **Create the workspace in that folder:** `bunx create-akan-workspace@latest . --app <app> --dir <folder> --sample false`.
+  It writes into `<folder>` itself, refuses to overwrite a file already there, and leaves out the sample module and
+  pages. Keep the `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.agents/`, `.cursor/` and `.mcp.json` it writes: they carry
+  the rules and tools an agent works through.
+- **Work from `<folder>`.** `akan` runs only from the workspace root, and an agent session opened there loads the
+  workspace's rules and MCP server.
+- **Check each change with `akan verify <app>`.** It syncs, lints, typechecks, builds and checks SSR, and prints only
+  what failed. `akan preview <app> --changed` opens the pages a change reaches.
+- **Exact URLs:** pages live under `/<locale>/…`. To serve the default locale at the bare path (`/pokemon/deoxys`),
+  set `i18n: { defaultLocale: "en", locales: ["en"], localePrefix: "as-needed" }` in `akan.config.ts`; `<Link>`
+  follows.
+- **A host with only Node and npm:** `npm install -g bun` gives the creator its runtime. Put `bun` in the workspace's
+  `dependencies` so the host installs it too, and let the package scripts call `akan` from the `@akanjs/cli` in
+  `devDependencies`. If `akan` is not found after a global install, add the folder `bun pm bin -g` prints to `PATH`.
+- **Run the production build without Docker:** `akan build <app>`, then `cd dist/apps/<app> && PORT=3000 bun main.js`.
+  The build carries the env it needs.
+
 ## All Of It Is One Line
 
 ```ts

package/client/cookie.ts

@@ -14,7 +14,7 @@ import {
   SessionCookies,
 } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
-import { cookieJar as serverCookieJar, headers as serverHeaders } from "akanjs/fetch";
+import { SessionCookie, cookieJar as serverCookieJar, headers as serverHeaders } from "akanjs/fetch";
 import { secretStorage } from "./storage";
 import { fetch } from "./useClient";
 
@@ -114,10 +114,19 @@ const sentAuthToken = (): string | undefined => {
   }
 };
 
+/** The session's claims from its readable cookie: a JWT without its signature, so never a credential. */
+export const getSessionClaims = (): string | undefined =>
+  isCsrClient() ? undefined : cookieJar().read(SessionCookie.claimsKey()).value || undefined;
+
+const serverHoldsSession = () => getEnv().side !== "server" && !!getSessionClaims();
+
 /** The auth token this app holds: on a CSR client the one `fetch` sends first, since a native shell's page keeps no
- * session cookie; then the app-scoped cookie, unless it is held more than once. */
+ * session cookie; then the app-scoped cookie, unless it is held more than once; then, while the server holds the
+ * session where no script reads it, the token this page was handed at sign-in, if any. */
 export const getAuthToken = (): string | undefined =>
-  (isCsrClient() ? sentAuthToken() : undefined) ?? readSessionToken(cookieJar()).token;
+  (isCsrClient() ? sentAuthToken() : undefined) ??
+  readSessionToken(cookieJar()).token ??
+  (serverHoldsSession() ? sentAuthToken() : undefined);
 
 /** The auth token this app holds in client storage — the OS credential store in a native app, localStorage elsewhere. */
 export const getStoredAuthToken = async (): Promise<string | undefined> =>
@@ -134,7 +143,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() ?? bearerTokenOf(getHeader("authorization"));
+  const jwt = getAuthToken() ?? bearerTokenOf(getHeader("authorization")) ?? getSessionClaims();
   if (!jwt) return defaultAccount;
   const account = decodeJwtPayload<Account<AddData>>(jwt);
   if (account.appName !== getEnv().appName || account.environment !== getEnv().environment) return defaultAccount;
@@ -149,12 +158,17 @@ interface SetAuthOption {
 const announceAuth = () => {
   if (typeof window !== "undefined") window.dispatchEvent(new Event("akan:auth"));
 };
-/** Sets the active auth token on fetch, the cookie jar (except on a CSR client), and client storage. */
+/** Sets the active auth token on fetch, then keeps it where the next launch finds it: client storage on a CSR client,
+ * the session cookie elsewhere unless the server already holds it there (`SessionCookie.issue`). */
 export const setAuth = ({ jwt }: SetAuthOption) => {
   fetch.setJwt(jwt);
   
-  if (!isCsrClient()) setCookie(authTokenKey(), jwt);
-  void secretStorage.setItem(storedAuthTokenKey(), jwt);
+  if (isCsrClient()) void secretStorage.setItem(storedAuthTokenKey(), jwt);
+  else {
+    
+    void secretStorage.removeItem(storedAuthTokenKey());
+    if (!serverHoldsSession()) setCookie(authTokenKey(), jwt);
+  }
   
   for (const key of retiredAuthTokenKeys()) removeCookie(key);
   void secretStorage.removeItem(legacyAuthTokenKey);
@@ -209,9 +223,11 @@ export const initAuth = ({ jwt }: InitAuthOption = {}) => {
   Logger.verbose(`JWT ${token ? "restored" : "not found"}`);
 };
 
+/** Signs this page out; an HttpOnly session the server holds ends only with `SessionCookie.expire`. */
 export const resetAuth = () => {
   fetch.setJwt(null);
   removeCookie(authTokenKey());
+  removeCookie(SessionCookie.claimsKey());
   for (const key of retiredAuthTokenKeys()) removeCookie(key);
   void secretStorage.removeItem(storedAuthTokenKey());
   void secretStorage.removeItem(legacyAuthTokenKey);

package/client/csrTypes.ts

@@ -1,8 +1,8 @@
 "use client";
+import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "@react-spring/web";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 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";

package/client/makePageProto.tsx

@@ -21,6 +21,15 @@ interface ErrPayload extends ErrRestoreOption {
   data?: Record<string, unknown>;
 }
 
+const htmlEntities: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+const escapeRichParams = (param: { [key: string]: string | number } | undefined) =>
+  Object.fromEntries(
+    Object.entries(param ?? {}).map(([key, value]) => [
+      key,
+      String(value).replace(/[&<>"']/g, (char) => htmlEntities[char] ?? char),
+    ]),
+  );
+
 const getPageInfo = (): { locale: string; path: string } => {
   const { defaultLocale, locales } = parseAkanI18nEnv();
   const localeSet = new Set(locales);
@@ -159,7 +168,7 @@ export const makePageProto = <
             
             dangerouslySetInnerHTML={{
               __html: translator.translate(lang, key, {
-                ...param,
+                ...escapeRichParams(param),
                 br: `<br />`,
               }),
             }}

package/client/router.ts

@@ -1,6 +1,8 @@
 import { getEnv } from "akanjs/base";
 import {
+  type AkanLocalePrefix,
   getBasePathFromPathname,
+  LocalePath,
   Logger,
   originFromRequest,
   parseAkanI18nEnv,
@@ -108,11 +110,6 @@ const getConfiguredBasePaths = () => new Set(parseBasePaths(process.env.AKAN_PUB
 const shouldExposeBasePath = () => getEnv().operationMode === "local";
 const CSR_RUNTIME_SEARCH_PARAMS = ["csr", "akanMobileTarget", "akanMobileBasePath", "akanMobileIndexPath"] as const;
 
-const getLocaleFromPathname = (pathname: string) => {
-  const [firstSegment] = pathname.split("/").filter(Boolean);
-  return parseAkanI18nEnv().locales.find((locale) => locale === firstSegment);
-};
-
 const normalizeRoutePath = (path: string | undefined) => {
   const normalized = path?.trim();
   if (!normalized) return undefined;
@@ -163,7 +160,17 @@ declare global {
   var __AKAN_ROUTER__: Router | undefined;
 }
 
-export const getPathInfo = (requestUrl: string, lang: string, prefix: string) => {
+const withoutNetworkPath = (pathname: string) => {
+  
+  const path = pathname.replace(/[\t\n\r]/g, "").replace(/^[\u0000-\u0020/\\]+/, "");
+  return `/${path}`;
+};
+export const getPathInfo = (
+  requestUrl: string,
+  lang: string,
+  prefix: string,
+  localePrefix: AkanLocalePrefix | undefined = parseAkanI18nEnv().localePrefix,
+) => {
   const [urlWithoutHash, hash = ""] = requestUrl.split("#");
   const [url, search = ""] = urlWithoutHash.split("?");
   const langLength = lang.length + 1;
@@ -177,13 +184,20 @@ export const getPathInfo = (requestUrl: string, lang: string, prefix: string) =>
         ? pathWithSubRoute.slice(prefixLength)
         : pathWithSubRoute;
   const subRoute = prefix ? `/${prefix}` : "";
-  
-  const pathname = Href.hasWebScheme(path) ? path : path === "/" ? `/${lang}${subRoute}` : `/${lang}${subRoute}${path}`;
+  const langSegment = LocalePath.segmentOf(lang, { defaultLocale: parseAkanI18nEnv().defaultLocale, localePrefix });
+  const appPathname = `${langSegment}${subRoute}${path === "/" ? "" : path}`;
+
+  const pathname = Href.hasWebScheme(path)
+    ? path
+    : langSegment || subRoute
+      ? appPathname
+      : withoutNetworkPath(appPathname);
   const href = `${pathname}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
   return { path, pathname, hash, search, href };
 };
 class Router {
   isInitialized: boolean = false;
+  #isCsr: boolean = false;
   #prefix = "";
   #lang = parseAkanI18nEnv().defaultLocale;
   #routePaths = new Set<string>();
@@ -201,6 +215,7 @@ class Router {
   #expectedPops: { idx: number; isAllowed: boolean; onLand?: () => void }[] = [];
   
   #beforeInit: (() => void)[] = [];
+  #frameParentOrigins: string[] | "*" = [];
   #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
@@ -218,6 +233,7 @@ class Router {
     },
   };
   init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption) {
+    this.#isCsr = options.type === "csr";
     this.#prefix = options.prefix ?? "";
     this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
     this.#routePaths = new Set(
@@ -395,8 +411,17 @@ class Router {
     csrLocation.replace(nextState);
   }
 
+  #localePrefix(): AkanLocalePrefix {
+    return this.#isCsr ? "always" : (parseAkanI18nEnv().localePrefix ?? "always");
+  }
+  #langSegment(lang = this.#lang) {
+    return LocalePath.segmentOf(lang, {
+      defaultLocale: parseAkanI18nEnv().defaultLocale,
+      localePrefix: this.#localePrefix(),
+    });
+  }
   #getPathInfo(href: string, prefix = this.#prefix) {
-    return getPathInfo(href, this.#lang, prefix);
+    return getPathInfo(href, this.#lang, prefix, this.#localePrefix());
   }
   #getNavigationPathInfo(href: string) {
     return this.#getPathInfo(href, shouldExposeBasePath() ? this.#prefix : "");
@@ -417,12 +442,16 @@ class Router {
     return `${pathname}${query ? `?${query}` : ""}${hash ? `#${hash}` : ""}`;
   }
   #getVisiblePathInfo(href: string, lang = this.#lang) {
-    return getPathInfo(href, lang, shouldExposeBasePath() ? this.#prefix : "");
+    return getPathInfo(href, lang, shouldExposeBasePath() ? this.#prefix : "", this.#localePrefix());
   }
   
   #postPathAfterBack() {
     if (this.canGoBack()) this.#backsAwaitingPopstate += 1;
   }
+  /** Origins besides the page's own that hear `pathChange` when they frame it in production; `"*"` is any parent. */
+  setFrameParentOrigins(origins: string[] | "*") {
+    this.#frameParentOrigins = origins;
+  }
   /** Tells the frame embedding this page where it went: a new path, or a page of a paginated list. */
   postPathChange(change: { path: string; pathname: string; hash: string } | { page: number }) {
     const message =
@@ -431,8 +460,13 @@ class Router {
         : { type: "pathChange", path: change.path, pathname: change.pathname, hash: change.hash };
     if (!("page" in change)) Logger.info(`pathChange-start:${change.path}${change.hash ? `#${change.hash}` : ""}`);
     
-    if (isMcpView()) return;
-    window.parent.postMessage(message, "*");
+    if (isMcpView() || window.parent === window) return;
+    
+    const targets =
+      getEnv().operationMode === "local" || this.#frameParentOrigins === "*"
+        ? ["*"]
+        : [window.location.origin, ...this.#frameParentOrigins];
+    for (const target of targets) window.parent.postMessage(message, target);
   }
   #postDevSyncNavigation(kind: "push" | "replace", href: string) {
     if (globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__) return;
@@ -639,7 +673,12 @@ class Router {
       const langFromPath = reqPathname.split("/").find(Boolean);
       const lang = (h.get("x-locale") ?? langFromPath ?? this.#lang) as string;
       const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
-      const { pathname, href: fullHref } = getPathInfo(href, lang, shouldExposeBasePath() ? basePath : "");
+      const { pathname, href: fullHref } = getPathInfo(
+        href,
+        lang,
+        shouldExposeBasePath() ? basePath : "",
+        this.#localePrefix(),
+      );
       Logger.info(`redirect to:${pathname}`);
       throw new AkanRedirectError(fullHref, method, status);
     } else {
@@ -663,7 +702,8 @@ class Router {
   setLang(lang: string) {
     if (getEnv().side === "server") throw new Error("setLang is only available in client side");
     this.#checkInitialized();
-    const currentLang = getLocaleFromPathname(csrLocation.pathname) ?? this.#lang;
+    const i18n = { ...parseAkanI18nEnv(), localePrefix: this.#localePrefix() };
+    const currentLang = LocalePath.split(csrLocation.pathname, i18n).locale ?? this.#lang;
     const { path, search, hash } = this.#getVisiblePathInfo(csrLocation.href, currentLang);
     this.#lang = lang;
     this.#instance.replace(`${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`);
@@ -679,13 +719,14 @@ class Router {
   }
   getFullPath(withLang = true) {
     if (getEnv().side === "server") throw new Error("getPath is only available in client side");
-    return `${withLang ? `/${this.#lang}/` : ""}${this.#prefix}${this.getPath()}`;
+    const path = `${this.#prefix}${this.getPath()}`;
+    return withLang ? `${this.#langSegment()}/${path}`.replace(/^\/+/, "/") : path;
   }
   getPrefix() {
     return this.#prefix;
   }
   getPrefixedPath(path: string) {
-    return this.#prefix ? `${this.#lang ? `/${this.#lang}` : ""}/${this.#prefix}${path}` : path;
+    return this.#prefix ? `${this.#lang ? this.#langSegment() : ""}/${this.#prefix}${path}` : path;
   }
 }
 const browserRouter = () => {

package/common/IpLiteral.ts

@@ -4,9 +4,11 @@ export class IpLiteral {
   
   static parse(entry: string): string | null {
     const trimmed = entry.trim();
-    const bracketed = /^\[([^\]]*:[^\]]*)\](?::\d{1,5})?$/.exec(trimmed);
+    
+    const bracketed = /^\[([^\]]*)\](?::\d{1,5})?$/.exec(trimmed)?.[1];
+    const v6InBrackets = bracketed?.includes(":") ? bracketed : undefined;
     const v4WithPort = /^(\d{1,3}(?:\.\d{1,3}){3}):\d{1,5}$/.exec(trimmed);
-    const [address = "", zone, ...rest] = (bracketed?.[1] ?? v4WithPort?.[1] ?? trimmed).split("%");
+    const [address = "", zone, ...rest] = (v6InBrackets ?? v4WithPort?.[1] ?? trimmed).split("%");
     if (rest.length) return null;
     if (zone !== undefined && !(address.includes(":") && /^[A-Za-z0-9_.-]{1,64}$/.test(zone))) return null;
     const bytes = IpBytes.of(IpBytes.normalize(address));

package/common/TrustedProxy.ts

@@ -27,6 +27,7 @@ export class TrustedProxy {
   static readonly #verdicts = new Map<string, boolean>();
   static readonly #verdictLimit = 1024;
   static #warnedIgnoredPeer = false;
+  static #warnedUnlistedChain = false;
 
   static configure(list: string | null | undefined) {
     TrustedProxy.reset();
@@ -37,6 +38,7 @@ export class TrustedProxy {
     TrustedProxy.#policy = null;
     TrustedProxy.#verdicts.clear();
     TrustedProxy.#warnedIgnoredPeer = false;
+    TrustedProxy.#warnedUnlistedChain = false;
   }
 
   static #load(): TrustPolicy {
@@ -104,6 +106,7 @@ export class TrustedProxy {
 
       const judge = TrustedProxy.#load().strict ? (address: string) => TrustedProxy.isTrusted(address) : undefined;
       const recorded = clientAddressFromHeaders(headers, judge);
+      if (peerAddress) TrustedProxy.#noteUnlistedChain(headers, peerAddress);
       if (recorded) return { address: recorded, forwarded: true };
     } else if (peerAddress) TrustedProxy.#noteIgnoredPeer(headers, peerAddress);
     return {
@@ -123,16 +126,56 @@ export class TrustedProxy {
     );
   }
 
+  static #noteUnlistedChain(headers: Headers, peerAddress: string) {
+    if (TrustedProxy.#warnedUnlistedChain) return;
+    const policy = TrustedProxy.#load();
+    if (policy.strict || policy.trustAll) return;
+    const hops = (headers.get("x-forwarded-for") ?? "")
+      .split(",")
+      .map((hop) => hop.trim())
+      .filter((hop) => hop);
+    const realIp = headers.get("x-real-ip")?.trim();
+    const last = hops.at(-1);
+    const disagrees = realIp ? !!last && IpLiteral.parse(last) !== IpLiteral.parse(realIp) : hops.length > 1;
+    if (!disagrees) return;
+    const bytes = IpBytes.of(normalizeIpAddress(peerAddress));
+    if (!bytes || TrustedProxy.#isLoopback(bytes)) return;
+    TrustedProxy.#warnedUnlistedChain = true;
+    new Logger("TrustedProxy").warn(
+      `AKAN_TRUSTED_PROXIES is unset, so the client address comes from the x-real-ip or leftmost x-forwarded-for that ${normalizeIpAddress(peerAddress)} sent. If that proxy appends to those headers instead of overwriting them, list it in AKAN_TRUSTED_PROXIES so the chain is read from the nearest hop.`,
+    );
+  }
+
   /** For refusing an outbound fetch to a caller-chosen name: judges the address alone, never the proxy list. */
   static isPrivateAddress(address: string): boolean {
     const bytes = IpBytes.of(normalizeIpAddress(address));
-    if (!bytes) return true;
+    return !bytes || TrustedProxy.#isNonPublic(bytes);
+  }
+
+  static #isNonPublic(bytes: Uint8Array): boolean {
     if (TrustedProxy.#isLoopback(bytes) || TrustedProxy.#isPrivateRange(bytes)) return true;
     if (bytes.length === 4) {
       const [a = 0, b = 0] = bytes;
       return a === 0 || (a === 100 && b >= 64 && b <= 127) || a >= 224;
     }
-    return bytes.every((byte) => byte === 0) || bytes[0] === 0xff;
+    const embedded = TrustedProxy.#embeddedIpv4(bytes);
+    if (embedded) return TrustedProxy.#isNonPublic(embedded);
+    const [first = 0, second = 0, third = 0, fourth = 0, fifth = 0, sixth = 0] = bytes;
+    const localNat64 =
+      first === 0 && second === 0x64 && third === 0xff && fourth === 0x9b && fifth === 0 && sixth === 1;
+    return localNat64 || first === 0xff;
+  }
+
+  static #embeddedIpv4(bytes: Uint8Array): Uint8Array | null {
+    const zero = (from: number, to: number) => bytes.subarray(from, to).every((byte) => byte === 0);
+    const groupAt = (idx: number) => ((bytes[idx] ?? 0) << 8) | (bytes[idx + 1] ?? 0);
+    const tail = bytes.slice(12);
+    if (zero(0, 10) && (groupAt(10) === 0xffff || groupAt(10) === 0)) return tail;
+    if (zero(0, 8) && groupAt(8) === 0xffff && groupAt(10) === 0) return tail;
+    if (groupAt(0) === 0x64 && groupAt(2) === 0xff9b && zero(4, 12)) return tail;
+    if (groupAt(0) === 0x2002) return bytes.slice(2, 6);
+    if (groupAt(0) === 0x2001 && groupAt(2) === 0) return tail.map((byte) => byte ^ 0xff);
+    return null;
   }
 
   static #isLoopback(bytes: Uint8Array): boolean {

package/common/akanNames.ts

@@ -0,0 +1,169 @@
+import { capitalize, lowerlize } from "./capitalize";
+
+export const sliceNames = (refName: string, suffix = "") => {
+  const [Model, Suffix] = [capitalize(refName), capitalize(suffix)];
+  const live = `${refName}Live${Suffix}`;
+  return {
+    slice: `${refName}${Suffix}`,
+    state: {
+      defaultModel: `default${Model}${Suffix}`,
+      modelInitList: `${refName}InitList${Suffix}`,
+      modelInsight: `${refName}Insight${Suffix}`,
+      modelList: `${refName}List${Suffix}`,
+      modelListLoading: `${refName}ListLoading${Suffix}`,
+      modelInitAt: `${refName}InitAt${Suffix}`,
+      modelStaleAt: `${refName}StaleAt${Suffix}`,
+      lastPageOfModel: `lastPageOf${Model}${Suffix}`,
+      pageOfModel: `pageOf${Model}${Suffix}`,
+      limitOfModel: `limitOf${Model}${Suffix}`,
+      hasMoreOfModel: `hasMoreOf${Model}${Suffix}`,
+      isCumulativeOfModel: `isCumulativeOf${Model}${Suffix}`,
+      hasInsightOfModel: `hasInsightOf${Model}${Suffix}`,
+      queryArgsOfModel: `queryArgsOf${Model}${Suffix}`,
+      sortOfModel: `sortOf${Model}${Suffix}`,
+      modelSelection: `${refName}Selection${Suffix}`,
+    },
+    action: {
+      initModel: `init${Model}${Suffix}`,
+      refreshModel: `refresh${Model}${Suffix}`,
+      selectModel: `select${Model}${Suffix}`,
+      setPageOfModel: `setPageOf${Model}${Suffix}`,
+      loadMoreOfModel: `loadMoreOf${Model}${Suffix}`,
+      setLimitOfModel: `setLimitOf${Model}${Suffix}`,
+      setQueryArgsOfModel: `setQueryArgsOf${Model}${Suffix}`,
+      setSortOfModel: `setSortOf${Model}${Suffix}`,
+      applyLiveModel: `applyLive${Model}${Suffix}`,
+      watchLiveModel: `watchLive${Model}${Suffix}`,
+    },
+    endpoint: {
+      list: `${refName}List${Suffix}`,
+      insight: `${refName}Insight${Suffix}`,
+      live,
+      subscribeLive: endpointNames(live).subscribe,
+      init: `init${Model}${Suffix}`,
+      getInit: `get${Model}Init${Suffix}`,
+      initResult: `${refName}Init${Suffix}`,
+    },
+  };
+};
+
+export const queryNames = (queryKey: string) => {
+  const Key = capitalize(queryKey);
+  return {
+    list: `list${Key}`,
+    listIds: `listIds${Key}`,
+    find: `find${Key}`,
+    findId: `findId${Key}`,
+    pick: `pick${Key}`,
+    pickId: `pickId${Key}`,
+    exists: `exists${Key}`,
+    count: `count${Key}`,
+    insight: `insight${Key}`,
+    query: `query${Key}`,
+    remove: `remove${Key}`,
+    removeOne: `removeOne${Key}`,
+    purge: `purge${Key}`,
+    update: `update${Key}`,
+    updateOne: `updateOne${Key}`,
+  };
+};
+
+export const databaseStateNames = (refName: string) => {
+  const className = capitalize(refName);
+  return {
+    model: refName,
+    modelLoading: `${refName}Loading`,
+    modelForm: `${refName}Form`,
+    modelFormLoading: `${refName}FormLoading`,
+    modelFormUploading: `${refName}FormUploading`,
+    modelSubmit: `${refName}Submit`,
+    modelViewAt: `${refName}ViewAt`,
+    modelModal: `${refName}Modal`,
+    modelDraft: `${refName}FormDraft`,
+    modelOperation: `${refName}Operation`,
+    defaultModel: `default${className}`,
+  };
+};
+
+export const modelNames = (refName: string) => {
+  const Model = capitalize(refName);
+  return {
+    ...databaseStateNames(refName),
+    getModel: `get${Model}`,
+    loadModel: `load${Model}`,
+    loadModelMany: `load${Model}Many`,
+    createModel: `create${Model}`,
+    createModelMany: `create${Model}Many`,
+    updateModel: `update${Model}`,
+    removeModel: `remove${Model}`,
+    modelModel: `${refName}Model`,
+    modelLoader: `${refName}Loader`,
+    modelCache: `${refName}Cache`,
+    modelId: `${refName}Id`,
+    lightModel: `light${Model}`,
+    viewModel: `view${Model}`,
+    getModelView: `get${Model}View`,
+    modelView: `${refName}View`,
+    editModel: `edit${Model}`,
+    getModelEdit: `get${Model}Edit`,
+    modelEdit: `${refName}Edit`,
+    modelObj: `${refName}Obj`,
+    modelObjList: `${refName}ObjList`,
+    modelObjInsight: `${refName}ObjInsight`,
+    addModelFiles: `add${Model}Files`,
+    mergeModel: `merge${Model}`,
+    createModelInForm: `create${Model}InForm`,
+    updateModelInForm: `update${Model}InForm`,
+    checkModelSubmitable: `check${Model}Submitable`,
+    submitModel: `submit${Model}`,
+    newModel: `new${Model}`,
+    setModel: `set${Model}`,
+    resetModel: `reset${Model}`,
+    invalidateModel: `invalidate${Model}`,
+    loadModelFormDraft: `load${Model}FormDraft`,
+    restoreModelFormDraft: `restore${Model}FormDraft`,
+    discardModelFormDraft: `discard${Model}FormDraft`,
+    writeOnModel: `writeOn${Model}`,
+    setViewOfModel: `setViewOf${Model}`,
+    exportCsvOfModel: `exportCsvOf${Model}`,
+    exportJsonOfModel: `exportJsonOf${Model}`,
+  };
+};
+
+export const moduleNames = (refName: string) => {
+  const Model = capitalize(refName);
+  return {
+    service: `${refName}Service`,
+    ServiceClass: `${Model}Service`,
+    SliceClass: `${Model}Slice`,
+    ModelClass: `${Model}Model`,
+    FilterClass: `${Model}Filter`,
+    SignalClass: `${Model}Signal`,
+    InternalClass: `${Model}Internal`,
+    EndpointClass: `${Model}Endpoint`,
+  };
+};
+
+export const formSetterNames = (className: string, key: string) => {
+  const classKeyName = capitalize(key);
+  return {
+    field: lowerlize(key),
+    Field: classKeyName,
+    setFieldOnModel: `set${classKeyName}On${className}`,
+    addFieldOnModel: `add${classKeyName}On${className}`,
+    subFieldOnModel: `sub${classKeyName}On${className}`,
+    addOrSubFieldOnModel: `addOrSub${classKeyName}On${className}`,
+    
+    moveFieldOnModel: `move${classKeyName}On${className}`,
+    uploadFieldOnModel: `upload${classKeyName}On${className}`,
+    
+    postSetField: `_postSet${classKeyName}`,
+  };
+};
+
+export const stateSetterName = (key: string) => `set${capitalize(key)}`;
+
+export const endpointNames = (key: string) => {
+  const Key = capitalize(key);
+  return { subscribe: `subscribe${Key}`, listen: `listen${Key}` };
+};