akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/README.ko.md

@@ -199,7 +199,6 @@ UI barrel import를 leaf import로 다시 써서 클라이언트 번들을 작
 특수 public surface:
 
 - `akanjs/ui/styles.css`
-- `akanjs/capacitor.base.config`
 - `akanjs/server/rsc-worker`
 - `akanjs/package.json`
 

package/README.md

@@ -197,7 +197,6 @@ frontend build to rewrite UI barrel imports into leaf imports.
 Special public surfaces:
 
 - `akanjs/ui/styles.css`
-- `akanjs/capacitor.base.config`
 - `akanjs/server/rsc-worker`
 - `akanjs/package.json`
 

package/base/base.ts

@@ -23,10 +23,10 @@ export type EnumInstance<RefName extends string = string, T = string | number> =
   }
 >;
 
-/** Returns true when a class was created by `enumOf`. */
+/** True for a `class X extends enumOf(...) {}`, not for the bare `enumOf(...)` result. */
 export const isEnum = (enumRef: Cls) => Object.getPrototypeOf(Object.getPrototypeOf(enumRef) ?? {}) === EnumPrototype;
 
-/** Creates a typed scalar enum class from a readonly list of string or number values. */
+/** `type` is `String` for string values, else `Int` when every value is an integer, else `Float`. */
 export const enumOf = <RefName extends string, T = string | number>(
   refName: RefName,
   values: readonly T[],
@@ -78,9 +78,7 @@ export const enumOf = <RefName extends string, T = string | number>(
   return Enum as unknown as EnumInstance<RefName, T>;
 };
 
-/** Id-keyed list helper used for light model collections and immutable-style list updates. */
 export class DataList<Light extends { id: string }> {
-  
   #idMap: Map<string, number>;
   length: number;
   values: Light[];
@@ -125,8 +123,7 @@ export class DataList<Light extends { id: string }> {
   }
   get(id: string) {
     const idx = this.#idMap.get(id);
-    if (idx === undefined) return undefined;
-    return this.values[idx];
+    return idx === undefined ? undefined : this.values[idx];
   }
   at(idx: number) {
     return this.values.at(idx);
@@ -143,12 +140,10 @@ export class DataList<Light extends { id: string }> {
     return this.#idMap.has(id);
   }
   find(fn: (value: Light, idx: number) => boolean) {
-    const val = this.values.find(fn);
-    return val;
+    return this.values.find(fn);
   }
   findIndex(fn: (value: Light, idx: number) => boolean) {
-    const val = this.values.findIndex(fn);
-    return val;
+    return this.values.findIndex(fn);
   }
   some(fn: (value: Light, idx: number) => boolean) {
     return this.values.some(fn);
@@ -166,7 +161,7 @@ export class DataList<Light extends { id: string }> {
     return this.values.flatMap(fn);
   }
   sort(fn: (a: Light, b: Light) => number) {
-    return new DataList(this.values.sort(fn));
+    return new DataList([...this.values].sort(fn));
   }
   filter(fn: (value: Light, idx: number) => boolean) {
     return new DataList(this.values.filter(fn));

package/base/baseEnv.ts

@@ -1,3 +1,5 @@
+import { DatabaseModes } from "./databaseModes";
+
 type ProcessEnvLike = { env?: Record<string, string | undefined> };
 
 const globalWithProcess = globalThis as unknown as { process?: ProcessEnvLike };
@@ -19,8 +21,6 @@ export type BackendEnv = {
   hostname?: string | null;
   port?: number;
   database?: {
-    mode?: DatabaseMode;
-    driver?: "sqlite" | "libsql" | "postgres";
     sqlite?: {
       filePath?: string;
       journalMode?: string;
@@ -41,6 +41,7 @@ export type BackendEnv = {
       database?: string;
       user?: string;
       password?: string;
+      insightUrl?: string;
     };
   };
   solid?: {
@@ -51,6 +52,7 @@ export type BackendEnv = {
     cleanupIntervalMs?: number;
     queuePollIntervalMs?: number;
     queueLeaseMs?: number;
+    queueFailedRetentionMs?: number;
   };
   onCleanup?: () => Promise<void>;
 };
@@ -79,7 +81,7 @@ type RoutePrefixOverride = { api?: string; ws?: string };
 
 const globalWithPrefix = globalThis as typeof globalThis & { __AKAN_PREFIX__?: RoutePrefixOverride };
 
-/** Leading slash, no trailing slash. A blank value — or a bare `/`, which would swallow every page route — is no prefix at all and falls through to the next source. */
+/** Leading slash, no trailing slash; a blank value or a bare `/` (it would swallow every page route) is no prefix. */
 export const normalizeRoutePrefix = (value: string | undefined | null): string | undefined => {
   const trimmed = value?.trim();
   if (!trimmed) return undefined;
@@ -88,12 +90,9 @@ export const normalizeRoutePrefix = (value: string | undefined | null): string |
 };
 
 /**
- * Three sources, narrowest first. The global is what a server-rendered page's bootstrap script writes, so the
- * browser follows the process that rendered it. `AKAN_API_PREFIX` is deliberately outside the `AKAN_PUBLIC_*`
- * namespace: only that namespace is inlined into client bundles at build time, so a name inside it could never
- * act as a runtime override. `AKAN_PUBLIC_API_PREFIX` is the build-time default, and the only one a prebuilt CSR
- * or mobile bundle can read. Written out rather than looked up by key — a computed `process.env[...]` is opaque
- * to the bundler's define pass, and the public value would stop being inlined.
+ * Narrowest first: the SSR bootstrap global, then `AKAN_API_PREFIX` (outside `AKAN_PUBLIC_*`, which is inlined at build
+ * time, so it can override at runtime), then the build-time default. Written out: a computed `process.env[...]` escapes
+ * the bundler's define pass.
  */
 export const getApiPrefix = (): string =>
   normalizeRoutePrefix(globalWithPrefix.__AKAN_PREFIX__?.api) ??
@@ -112,10 +111,30 @@ export const resetEnvCache = () => {
   cachedEnv = undefined;
 };
 
+const csrServerUrl = (): URL | null => {
+  const value = process.env.AKAN_PUBLIC_SERVER_URL;
+  if (!value) return null;
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:")
+    throw new Error(`AKAN_PUBLIC_SERVER_URL must be an http(s) URL, got "${value}".`);
+  return url;
+};
+
+const nativeDevGatewayOrigin = (): string | null =>
+  (globalThis as { __AKAN_NATIVE_DEV__?: { gateway?: string } }).__AKAN_NATIVE_DEV__?.gateway
+    ? `${window.location.protocol}//${window.location.host}`
+    : null;
+
+const nativeDevServerUrl = (operationMode: BaseEnv["operationMode"]): URL | null => {
+  const platform = (globalThis as { __AKAN_NATIVE__?: { platform?: string } }).__AKAN_NATIVE__?.platform;
+  if (operationMode !== "local" || !platform || platform === "web") return null;
+  return new URL(`http://localhost:${process.env.AKAN_PUBLIC_SERVER_PORT ?? "8282"}`);
+};
+
 const missingPublicEnv = (key: string) =>
   `getEnv() cannot run at build time: akan build does not inject ${key}. Call it from a runtime function instead of at module scope (e.g. env(() => getEnv()) in adapt(), a method body, or a default thunk).`;
 
-/** Reads and caches Akan runtime environment values from process/browser environment settings. */
+/** Cached after the first call. */
 export const getEnv = (): ClientEnv => {
   if (cachedEnv) return cachedEnv;
   const appName = process.env.AKAN_PUBLIC_APP_NAME ?? "unknown";
@@ -133,7 +152,14 @@ export const getEnv = (): ClientEnv => {
     appName,
     environment,
     operationMode,
-    databaseMode: process.env.AKAN_DATABASE_MODE as DatabaseMode | undefined,
+    databaseMode:
+      typeof window === "undefined"
+        ? DatabaseModes.settle({
+            requested: process.env.AKAN_DATABASE_MODE,
+            declared: process.env.AKAN_DATABASE_MODES,
+            local: environment === "local" || operationMode === "local",
+          })
+        : undefined,
   } as const;
   const side = typeof window === "undefined" ? "server" : "client";
   const renderMode = (process.env.AKAN_PUBLIC_RENDER_ENV ?? "csr") as ClientEnv["renderMode"];
@@ -152,7 +178,14 @@ export const getEnv = (): ClientEnv => {
         ? "http:"
         : "https:";
   const clientHttpUri = `${clientHttpProtocol}//${clientHost}${clientPort === 443 ? "" : `:${clientPort}`}`;
+  const csrClient = side === "client" && renderMode === "csr";
+  const pageOrigin = csrClient && !process.env.AKAN_PUBLIC_SERVER_URL ? nativeDevGatewayOrigin() : null;
+  const serverUrl = csrClient && !pageOrigin ? (csrServerUrl() ?? nativeDevServerUrl(operationMode)) : null;
+  
+  const hostFromPage =
+    side === "client" && !serverUrl && (!!pageOrigin || operationMode === "local" || renderMode !== "csr");
   const serverHost =
+    (pageOrigin ? window.location.hostname : serverUrl?.hostname) ??
     process.env.SERVER_HOST ??
     (operationMode === "local"
       ? typeof window === "undefined"
@@ -168,9 +201,14 @@ export const getEnv = (): ClientEnv => {
   const serverPort =
     side === "server"
       ? parseInt(process.env.AKAN_PUBLIC_SERVER_PORT ?? selfServerPort ?? "8282")
-      : parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"));
+      : serverUrl
+        ? parseInt(serverUrl.port || (serverUrl.protocol === "https:" ? "443" : "80"))
+        : hostFromPage
+          ? parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"))
+          : 443;
 
   const serverHttpProtocol: "http:" | "https:" =
+    ((pageOrigin ? window.location.protocol : serverUrl?.protocol) as "http:" | "https:" | undefined) ??
     (process.env.SERVER_HTTP_PROTOCOL as "http:" | "https:" | undefined) ??
     (operationMode === "local"
       ? side === "client"
@@ -183,9 +221,14 @@ export const getEnv = (): ClientEnv => {
           : ("http:" as const));
   const apiPrefix = getApiPrefix();
   const wsPrefix = getWsPrefix();
-  const serverHttpUri = `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}${apiPrefix}`;
+  
+  const serverHttpUri = pageOrigin
+    ? `${pageOrigin}${apiPrefix}`
+    : `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}${apiPrefix}`;
   const serverWsProtocol = serverHttpProtocol === "http:" ? "ws:" : "wss:";
-  const serverWsUri = `${serverWsProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}`;
+  const serverWsUri = pageOrigin
+    ? pageOrigin.replace(/^http/, "ws")
+    : `${serverWsProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}`;
 
   const env: ClientEnv = {
     ...baseEnv,

package/base/databaseModes.ts

@@ -0,0 +1,75 @@
+import type { DatabaseMode } from "./baseEnv";
+
+export interface DatabaseModeRequest {
+  /** `AKAN_DATABASE_MODE`: the mode a deployment names. */
+  requested: string | undefined;
+  /** `AKAN_DATABASE_MODES`: what the build carries drivers for, first one the default. Unset allows any. */
+  declared: string | undefined;
+  /** A developer machine, which may leave the mode unnamed when the build carries several. */
+  local: boolean;
+}
+
+/** Shared by the CLI and the server. */
+export class DatabaseModes {
+  static readonly all = ["single", "multiple", "cluster"] as const satisfies readonly DatabaseMode[];
+  /** Packages a mode imports at runtime. A build carries them for every mode the app declares. */
+  static readonly drivers: { [mode in DatabaseMode]: readonly string[] } = {
+    single: [],
+    multiple: ["bullmq", "ioredis"],
+    cluster: ["bullmq", "ioredis", "postgres"],
+  };
+  static readonly #stores: { [mode in DatabaseMode]: string } = {
+    single: "sqlite · solid",
+    multiple: "sqlite · redis",
+    cluster: "postgres · redis",
+  };
+
+  static describe(mode: DatabaseMode) {
+    return `${mode} (${DatabaseModes.#stores[mode]})`;
+  }
+
+  static parse(value: string, source: string): DatabaseMode {
+    const mode = value.trim();
+    if ((DatabaseModes.all as readonly string[]).includes(mode)) return mode as DatabaseMode;
+    throw new Error(`${source} must be one of ${DatabaseModes.all.join(", ")}, not "${value}"`);
+  }
+
+  static parseList(value: string, source: string): DatabaseMode[] {
+    const modes = value
+      .split(",")
+      .filter((mode) => mode.trim())
+      .map((mode) => DatabaseModes.parse(mode, source));
+    if (!modes.length) throw new Error(`${source} names no database mode`);
+    return [...new Set(modes)];
+  }
+
+  /**
+   * Throws when a build carrying several modes names none: the fallback would be a SQLite file in each container,
+   * which a cluster deployment would discover only once its instances disagreed.
+   */
+  static resolve({ requested, declared, local }: DatabaseModeRequest): DatabaseMode {
+    const modes = declared?.trim() ? DatabaseModes.parseList(declared, "AKAN_DATABASE_MODES") : null;
+    if (requested?.trim()) {
+      const mode = DatabaseModes.parse(requested, "AKAN_DATABASE_MODE");
+      if (modes && !modes.includes(mode))
+        throw new Error(
+          `AKAN_DATABASE_MODE is ${mode}, but this build carries only ${modes.join(", ")}. Add "${mode}" to database.modes in akan.config.ts and rebuild.`,
+        );
+      return mode;
+    }
+    if (!modes) return "single";
+    if (modes.length === 1 || local) return modes[0] as DatabaseMode;
+    throw new Error(
+      `This build runs in ${modes.join(" or ")} mode, and AKAN_DATABASE_MODE names neither. Set it to say which this deployment is.`,
+    );
+  }
+
+  /** `resolve` for readers that cannot fail a boot; the boot itself resolves again and reports the reason. */
+  static settle(request: DatabaseModeRequest): DatabaseMode | undefined {
+    try {
+      return DatabaseModes.resolve(request);
+    } catch {
+      return undefined;
+    }
+  }
+}

package/base/index.ts

@@ -1,5 +1,6 @@
 export * from "./base";
 export * from "./baseEnv";
+export * from "./databaseModes";
 export * from "./primitiveRegistry";
 export * from "./symbols";
 export * from "./types";

package/base/primitiveRegistry.ts

@@ -4,19 +4,13 @@ import type { Cls } from "./types";
 
 export type { Dayjs };
 
-/** Shared dayjs factory re-export used by Akan documents, services, stores, and UI. */
 export const dayjs = dayjsLib;
 
-/** Registry that maps Akan primitive scalar names to their runtime scalar classes. */
 export class PrimitiveRegistry {
   static readonly #namePrimitiveMap = new Map<string, typeof PrimitiveScalar>();
   static readonly #primitiveNameMap = new Map<typeof PrimitiveScalar, string>();
-  static register(scalar: typeof PrimitiveScalar, { overwrite = false } = {}) {
-    if (
-      !overwrite &&
-      (PrimitiveRegistry.#namePrimitiveMap.has(scalar.refName) || PrimitiveRegistry.#primitiveNameMap.has(scalar))
-    )
-      throw new Error(`Scalar ${scalar.refName} already registered`);
+
+  static register(scalar: typeof PrimitiveScalar) {
     PrimitiveRegistry.#namePrimitiveMap.set(scalar.refName, scalar);
     PrimitiveRegistry.#primitiveNameMap.set(scalar, scalar.refName);
   }
@@ -42,9 +36,27 @@ export class PrimitiveRegistry {
   static getAll(): (typeof PrimitiveScalar)[] {
     return [...PrimitiveRegistry.#namePrimitiveMap.values()];
   }
+  /** The agent face `modelRef` declares, or null for anything that is not a registered primitive declaring one. */
+  static agentOf(modelRef: unknown): PrimitiveAgentFace | null {
+    if (!PrimitiveRegistry.#primitiveNameMap.has(modelRef as typeof PrimitiveScalar)) return null;
+    return (modelRef as typeof PrimitiveScalar).agent ?? null;
+  }
+}
+
+export interface PrimitiveJsonSchema {
+  [key: string]: unknown;
 }
 
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
+/**
+ * How an agent sees a primitive whose stored shape is not the one a model should read: `schema` is its published shape
+ * and `read` maps a stored or wire value into it. No `write`: every input already runs through `parseValue`.
+ */
+export interface PrimitiveAgentFace<Value = unknown> {
+  schema: PrimitiveJsonSchema;
+  read(value: Value): unknown;
+}
+
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | object | null | undefined;
 export class PrimitiveScalar {
   static refName: string;
   static [SERVER_VALUE]: unknown;
@@ -52,6 +64,10 @@ export class PrimitiveScalar {
   static [DEFAULT_VALUE]: unknown = null;
   static [PURIFIED_VALUE]: unknown = null;
   static [EXAMPLE_VALUE]: unknown = null;
+  /** The wire shape, for a primitive the built-in schema table cannot know. Absent, it is published as a string. */
+  static jsonSchema?: PrimitiveJsonSchema;
+  /** Absent, an agent sees the wire shape. */
+  static agent?: PrimitiveAgentFace;
 
   static validate(value: PrimitiveValue): boolean {
     return true;
@@ -99,7 +115,7 @@ export class PrimitiveScalar {
   }
 }
 
-/** Integer primitive scalar. Accepts safe integer numbers after parsing. */
+/** Safe integers only. */
 export class Int extends PrimitiveScalar {
   static override refName: "Int" = "Int";
   static override [SERVER_VALUE]: number;
@@ -120,7 +136,7 @@ export class Int extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Int);
 
-/** Floating point primitive scalar. Accepts finite numbers after parsing. */
+/** Finite numbers only. */
 export class Float extends PrimitiveScalar {
   static override refName: "Float" = "Float";
   static override [SERVER_VALUE]: number;
@@ -141,7 +157,7 @@ export class Float extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Float);
 
-/** 24-character hexadecimal id primitive used by Akan document and signal models. */
+/** 24 hexadecimal characters. */
 export class ID extends PrimitiveScalar {
   static override refName: "ID" = "ID";
   static override [SERVER_VALUE]: string;
@@ -168,7 +184,7 @@ export class ID extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(ID);
 
-/** Open object primitive for intentionally flexible payloads or metadata blobs. */
+/** An intentionally open payload. */
 export class Any extends PrimitiveScalar {
   static override refName: "Any" = "Any";
   static override [DEFAULT_VALUE]: object | null = null;
@@ -275,34 +291,20 @@ declare global {
   }
 }
 
+const isBlankOrInvalid = (refName: string, value: PrimitiveValue) =>
+  value === "" ||
+  (refName === "Date" && typeof value === "string" && Number.isNaN(new Date(value).getTime())) ||
+  (refName === "Date" && value instanceof Date && Number.isNaN(value.getTime())) ||
+  (!!value && typeof value === "object" && "isValid" in value && !(value as { isValid: () => boolean }).isValid());
+
 const scalarPrimitiveStatics = {
-  _parse(
-    this: typeof PrimitiveScalar,
-    input: PrimitiveValue,
-    { optional = false }: { optional?: boolean } = {},
-  ): PrimitiveValue {
-    if (optional && (input === null || input === undefined)) return undefined;
-    const value = this.parseValue(input);
-    this._checkValue(value, { optional });
-    return value;
-  },
+  _parse: PrimitiveScalar._parse,
   _serialize(
     this: typeof PrimitiveScalar,
     value: PrimitiveValue,
     { optional = false }: { optional?: boolean } = {},
   ): PrimitiveValue {
-    if (optional && value === "") return undefined;
-    if (this.refName === "Date" && optional && typeof value === "string" && Number.isNaN(new Date(value).getTime()))
-      return undefined;
-    if (this.refName === "Date" && optional && value instanceof Date && Number.isNaN(value.getTime())) return undefined;
-    if (
-      optional &&
-      value &&
-      typeof value === "object" &&
-      "isValid" in value &&
-      !(value as { isValid: () => boolean }).isValid()
-    )
-      return undefined;
+    if (optional && isBlankOrInvalid(this.refName, value)) return undefined;
     this._checkValue(value, { optional });
     if (value === null || value === undefined) return undefined;
     return this.serializeValue(value);
@@ -316,18 +318,7 @@ const scalarPrimitiveStatics = {
       if (optional) return;
       else throw new Error(`Required ${this.refName} value: ${value}`);
     }
-    if (optional && value === "") return;
-    if (this.refName === "Date" && optional && typeof value === "string" && Number.isNaN(new Date(value).getTime()))
-      return;
-    if (this.refName === "Date" && optional && value instanceof Date && Number.isNaN(value.getTime())) return;
-    if (
-      optional &&
-      value &&
-      typeof value === "object" &&
-      "isValid" in value &&
-      !(value as { isValid: () => boolean }).isValid()
-    )
-      return;
+    if (optional && isBlankOrInvalid(this.refName, value)) return;
     if (!this.validate(value)) throw new Error(`Invalid ${this.refName} value: ${value}`);
   },
 };

package/base/symbols.ts

@@ -13,7 +13,7 @@ export const STATE_META = Symbol.for("akan.state");
 export const STATE_INIT_META = Symbol.for("akan.state.init");
 export const STATE_DERIVED_META = Symbol.for("akan.state.derived");
 export const ACTION_META = Symbol.for("akan.action");
-/** Which module declared each action. See `ActionOwner`. */
+/** Which module declared each action. */
 export const ACTION_OWNER_META = Symbol.for("akan.action.owner");
 /** What a dispatcher does, carried on the function so a component handed one can annotate the DOM with it. */
 export const ACTION_TAG = Symbol.for("akan.action.tag");

package/base/types.ts

@@ -116,7 +116,7 @@ export type MergeAllDoubleKeyOfObjects<
     : MergeAllDoubleKeyOfObjects<Rest, Key, SubKey, Acc>
   : Acc;
 
-export type Primitive = string | number | boolean | null | undefined; 
+export type Primitive = string | number | boolean | null | undefined;
 
 export type NestedKeysWithAllowed<T, Allowed = Primitive> = T extends Primitive
   ? never

package/base/utils.ts

@@ -21,10 +21,7 @@ export const applyFnToArrayObjects = <Input, Fn extends (arg: never) => unknown>
   arraiedData: Input,
   fn: Fn,
 ): ApplyFnToArrayObjectsResult<Input, ReturnType<Fn>> => {
-  if (Array.isArray(arraiedData))
-    return arraiedData.map((data) => applyFnToArrayObjects(data, fn)) as ApplyFnToArrayObjectsResult<
-      Input,
-      ReturnType<Fn>
-    >;
-  return fn(arraiedData as never) as ApplyFnToArrayObjectsResult<Input, ReturnType<Fn>>;
+  type Result = ApplyFnToArrayObjectsResult<Input, ReturnType<Fn>>;
+  if (Array.isArray(arraiedData)) return arraiedData.map((data) => applyFnToArrayObjects(data, fn)) as Result;
+  return fn(arraiedData as never) as Result;
 };

package/client/cn.ts

@@ -1,11 +1,6 @@
 import { type ClassNameValue, extendTailwindMerge } from "tailwind-merge";
 
-/**
- * Akan's semantic color tokens beyond tailwind-merge's built-in Tailwind palette.
- * Registering them under `theme.color` teaches tailwind-merge that `bg-*`/`text-*`/
- * `border-*`/… built from these names belong to the same conflict group, so
- * `cn("bg-primary", "bg-open")` correctly resolves to `"bg-open"` instead of keeping both.
- */
+/** Registered with tailwind-merge so `cn("bg-primary", "bg-open")` resolves to `"bg-open"` instead of keeping both. */
 export const colorTokens = [
   "background",
   "foreground",
@@ -38,10 +33,7 @@ export const colorTokens = [
   "ring",
 ];
 
-/**
- * Akan's semantic radius tokens (`--radius-box` / `--radius-field` in ui/styles.css). Without them
- * `cn("rounded-field", "rounded-full")` keeps both classes and stylesheet order decides the winner.
- */
+/** `--radius-box` / `--radius-field`; unregistered, `cn("rounded-field", "rounded-full")` would keep both. */
 export const radiusTokens = ["box", "field"];
 
 const twMerge = extendTailwindMerge({
@@ -53,7 +45,5 @@ const twMerge = extendTailwindMerge({
   },
 });
 
-/** The one class-combining function: joins strings/arrays/conditional parts (`cond && "x"`) and
- *  resolves Tailwind conflicts with a shared tailwind-merge instance that knows Akan's semantic
- *  color tokens. clsx-style object syntax (`{ x: cond }`) is not supported — write `cond && "x"`. */
+/** Joins class parts and resolves Tailwind conflicts; object syntax (`{ x: cond }`) is unsupported — write `cond && "x"`. */
 export const cn = (...inputs: ClassNameValue[]) => twMerge(...inputs);