akanjs 3.0.0-beta.17 → 3.0.0-beta.19

package/base/base.ts

@@ -166,7 +166,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>;
 };
@@ -133,7 +135,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"];

package/base/databaseModes.ts

@@ -0,0 +1,76 @@
+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;
+}
+
+/** The database modes, what each runs on, and how a process settles on one. The CLI and the server share it. */
+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)];
+  }
+
+  /**
+   * The mode this process runs in, or the reason it cannot pick one. A deployment that names no mode when the build
+   * carries several fails rather than falling back: the fallback would be a SQLite file inside each container, which a
+   * cluster deployment would find out about 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

@@ -11,12 +11,8 @@ export const dayjs = dayjsLib;
 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 +38,29 @@ 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;
+}
+
+/**
+ * How an agent — an MCP client or the in-page one — sees a primitive whose stored shape is not the one a model
+ * should read or write: `schema` is what it is published as on both sides of a call, and `read` turns a stored or
+ * wire value into that shape. There is no `write`, because every argument and every input field already runs
+ * through `parseValue`; a primitive that accepts the agent's shape there has taken the write.
+ */
+export interface PrimitiveAgentFace<Value = unknown> {
+  schema: PrimitiveJsonSchema;
+  read(value: Value): unknown;
 }
 
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | object | null | undefined;
 export class PrimitiveScalar {
   static refName: string;
   static [SERVER_VALUE]: unknown;
@@ -52,6 +68,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. See `PrimitiveAgentFace`. */
+  static agent?: PrimitiveAgentFace;
 
   static validate(value: PrimitiveValue): boolean {
     return true;

package/client/csrTypes.ts

@@ -46,7 +46,7 @@ export interface PageConfig {
   ssr?: SsrRenderMode;
   /**
    * Opt in to guarded RSC page suffix commits when the page does not require
-   * head/metadata updates and the retained route chain head is invariant for
+   * head updates and the retained route chain head is invariant for
    * sibling navigations under the same layout.
    */
   rscPatchHeadSafe?: boolean;
@@ -109,7 +109,6 @@ export interface AkanHeadSnapshotV1 {
 }
 export interface ResolvedHead {
   node: Head | null | undefined;
-  hasExplicitLanguageAlternates: boolean;
   headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
@@ -163,53 +162,24 @@ 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;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
   wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
-  gaTrackingId?: string;
   Loading?: LayoutLoadingRender;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;

package/client/frameConfig.ts

@@ -165,8 +165,8 @@ export function resolvePageState({
         : (config.gesture ?? false),
     cache: config.cache ?? false,
     ssr: config.ssr ?? "stream",
-    topSafeAreaColor: config.topSafeAreaColor ?? "var(color-background, Canvas)",
-    bottomSafeAreaColor: config.bottomSafeAreaColor ?? "var(color-background, Canvas)",
+    topSafeAreaColor: config.topSafeAreaColor ?? defaultPageState.topSafeAreaColor,
+    bottomSafeAreaColor: config.bottomSafeAreaColor ?? defaultPageState.bottomSafeAreaColor,
   };
 }
 

package/client/route/RootLayoutDefinition.ts

@@ -12,7 +12,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
   #reconnect?: boolean;
   #wsConnect?: boolean;
   #layoutStyle?: "mobile" | "web";
-  #gaTrackingId?: string;
 
   fonts(fonts: ReactFont[]) {
     this.#fonts = fonts;
@@ -38,10 +37,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
     this.#layoutStyle = style;
     return this;
   }
-  gaTrackingId(id: string) {
-    this.#gaTrackingId = id;
-    return this;
-  }
 
   protected override extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
     return {
@@ -52,7 +47,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
       ...(this.#reconnect !== undefined ? { reconnect: this.#reconnect } : {}),
       ...(this.#wsConnect !== undefined ? { wsConnect: this.#wsConnect } : {}),
       ...(this.#layoutStyle ? { layoutStyle: this.#layoutStyle } : {}),
-      ...(this.#gaTrackingId ? { gaTrackingId: this.#gaTrackingId } : {}),
     };
   }
 }

package/client/route/RouteDefinition.ts

@@ -9,7 +9,7 @@ import {
 import { parseAkanI18nEnv } from "akanjs/common";
 import { deserialize } from "akanjs/constant";
 import type { ReactNode } from "react";
-import type { AkanMetadata, Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
+import type { Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
 import { AkanNotFoundError } from "../router";
 import { RouteArgError, type RouteArgInfo, type RouteArgInput, type RouteBaseArgs } from "./routeArgs";
 
@@ -19,7 +19,6 @@ export type RouteKind = "page" | "layout" | "rootLayout";
 export const routeDefinitionMarker = Symbol.for("akan.routeDefinition");
 
 type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
-type MetadataStage<Args> = AkanMetadata | ((args: Args) => PromiseOrObject<AkanMetadata | null | undefined>);
 
 interface RouteRenderProps {
   params: Record<string, string>;
@@ -46,7 +45,6 @@ export abstract class RouteDefinition<
   #config?: PageConfig;
 
   #head?: HeadStage<never>;
-  #metadata?: MetadataStage<never>;
   #loading?: (args: never) => PromiseOrObject<ReactNode>;
   #render?: (args: never) => PromiseOrObject<ReactNode>;
 
@@ -58,10 +56,6 @@ export abstract class RouteDefinition<
     this.#head = head as HeadStage<never>;
     return this;
   }
-  metadata(metadata: MetadataStage<RouteBaseArgs & Args>) {
-    this.#metadata = metadata as MetadataStage<never>;
-    return this;
-  }
   loading(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>) {
     this.#loading = render as (args: never) => PromiseOrObject<ReactNode>;
     return this;
@@ -136,7 +130,6 @@ export abstract class RouteDefinition<
     if (!render)
       throw new Error(`[route-convention] a ${this.kind}() chain ends with .render(), and this one has none`);
     const head = this.#head;
-    const metadata = this.#metadata;
     const loading = this.#loading;
     const module: PageModule & LayoutModule = {
       default: (async (props: RouteRenderProps) => await render(this.#argsOf(props) as never)) as never,
@@ -146,11 +139,6 @@ export abstract class RouteDefinition<
         : typeof head === "function"
           ? { generateHead: async (props: RouteRenderProps) => await head(this.#argsOf(props) as never) }
           : { head }),
-      ...(metadata === undefined
-        ? {}
-        : typeof metadata === "function"
-          ? { generateMetadata: async (props: RouteRenderProps) => await metadata(this.#argsOf(props) as never) }
-          : { metadata }),
       ...(loading
         ? {
             Loading: ((props: RouteRenderProps) =>

package/common/CodeTranscript.ts

@@ -179,6 +179,13 @@ export class CodeTranscript {
       case "question":
         this.#question = event.question;
         return this.#push({ kind: "question", id: event.question.questionId, question: event.question });
+      case "question_skipped":
+        return this.#push({
+          kind: "question",
+          id: event.question.questionId,
+          question: event.question,
+          rendered: `(${event.reason})`,
+        });
       case "question_resolved":
         if (this.#question?.questionId === event.questionId) this.#question = undefined;
         return this.#patch(event.questionId, (part) => {
@@ -197,8 +204,12 @@ export class CodeTranscript {
         return;
       case "compaction":
         this.#compacting = event.phase === "start";
-        if (event.phase === "end") this.#notice("info", `Compacted the conversation (${event.reason}).`);
-        return;
+        if (event.phase === "start") return;
+
+        if ((event.error || event.aborted) && event.reason === "manual") return;
+        if (event.error) return this.#notice("warning", event.error);
+        if (event.aborted) return this.#notice("info", "Compaction cancelled.");
+        return this.#notice("info", `Compacted the conversation (${event.reason}).`);
       case "retry":
         return this.#notice(
           "warning",

package/common/codeAgentProfile.ts

@@ -21,6 +21,22 @@ export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
  */
 export type CodeAgentInteractionMode = "await" | "suspend";
 
+export interface CodeAgentModelInfo {
+  id: string;
+  name: string;
+  contextWindow?: number;
+  /** Whether this is the one the session is running on, which a listing has to mark rather than repeat. */
+  current: boolean;
+}
+
+/** One provider of the model catalogue, and whether a credential for it has been configured. */
+export interface CodeAgentProviderInfo {
+  id: string;
+  name: string;
+  authorized: boolean;
+  models: CodeAgentModelInfo[];
+}
+
 export interface CodeAgentMcpServerRef {
   name: string;
   transport: "stdio" | "http";
@@ -29,8 +45,26 @@ export interface CodeAgentMcpServerRef {
   args?: string[];
   url?: string;
   env?: Record<string, string>;
+  /** Sent on every http request. A server behind a static token needs nothing else. */
+  headers?: Record<string, string>;
+  /**
+   * What to use when the server answers `401` and asks for OAuth.
+   *
+   * Everything here is optional because the spec is discoverable: the challenge names the resource metadata,
+   * that names the authorization server, and most hosted servers register a client on demand. It is for the
+   * ones that do not — a provider issuing client ids by hand, or one whose scopes cannot be guessed.
+   */
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
 }
 
+/**
+ * Where a server stands with its credential.
+ *
+ * `required` is not a failure: it is a server that answered correctly and said who may talk to it. Reporting
+ * it as unreachable would send someone to debug a server that is working exactly as designed.
+ */
+export type CodeAgentMcpAuthState = "none" | "authorized" | "required";
+
 /**
  * One declared MCP server, as the session found it.
  *
@@ -47,6 +81,8 @@ export interface CodeAgentMcpStatus {
   tools: string[];
   /** Why it published none, when it published none. */
   error?: string;
+  /** Whether a credential was needed, and whether one was held. */
+  auth?: CodeAgentMcpAuthState;
 }
 
 export interface CodeAgentSubagentBudget {

package/common/codeAgentWire.ts

@@ -190,10 +190,19 @@ export type CodeAgentEventBody =
     }
   | { type: "question"; question: CodeAgentQuestion }
   | { type: "question_resolved"; questionId: string; answer: CodeAgentAnswer; rendered: string }
+  /** A question nobody could be asked — no host attached — answered with nothing; the model continued on its own. */
+  | { type: "question_skipped"; question: CodeAgentQuestion; reason: "no-host" }
   | { type: "approval"; request: CodeAgentApprovalRequest }
   | { type: "approval_resolved"; approvalId: string; approved: boolean }
   | { type: "context"; used: number; max: number | undefined }
-  | { type: "compaction"; phase: "start" | "end"; reason: "manual" | "threshold" | "overflow" }
+  /** An `end` carrying neither `error` nor `aborted` is the only one that compacted anything. */
+  | {
+      type: "compaction";
+      phase: "start" | "end";
+      reason: "manual" | "threshold" | "overflow";
+      error?: string;
+      aborted?: boolean;
+    }
   | { type: "retry"; attempt: number; maxAttempts: number; delayMs: number; message: string }
   | { type: "queue"; steering: string[]; followUp: string[] }
   | { type: "notice"; level: "info" | "warning" | "error"; message: string }
@@ -255,6 +264,7 @@ export const codeAgentEventPersistence: { [key in CodeAgentEventType]: "live" |
   tool_end: "persist",
   question: "persist",
   question_resolved: "persist",
+  question_skipped: "persist",
   approval: "live",
   approval_resolved: "live",
   context: "live",
@@ -393,14 +403,18 @@ export const codeAgentEventLabel = (event: CodeAgentEventBody): string => {
       return `? ${event.question.prompt}`;
     case "question_resolved":
       return `= ${event.rendered}`;
+    case "question_skipped":
+      return `? ${event.question.prompt} (skipped: ${event.reason})`;
     case "approval":
       return `approve? ${event.request.summary}`;
     case "approval_resolved":
       return event.approved ? "approved" : "denied";
     case "context":
       return `context ${event.used}${event.max ? `/${event.max}` : ""}`;
-    case "compaction":
-      return `compaction ${event.phase} (${event.reason})`;
+    case "compaction": {
+      const outcome = event.error ? ` — ${event.error}` : event.aborted ? " — cancelled" : "";
+      return `compaction ${event.phase} (${event.reason})${outcome}`;
+    }
     case "retry":
       return `retry ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms — ${event.message}`;
     case "queue":

package/common/index.ts

@@ -21,10 +21,13 @@ export {
   type CodeAgentApprovalPolicy,
   type CodeAgentBuiltinTool,
   type CodeAgentInteractionMode,
+  type CodeAgentMcpAuthState,
   type CodeAgentMcpServerRef,
   type CodeAgentMcpStatus,
+  type CodeAgentModelInfo,
   type CodeAgentPresetName,
   type CodeAgentProfile,
+  type CodeAgentProviderInfo,
   type CodeAgentSubagentBudget,
   codeAgentDeniedPaths,
   codeAgentPresets,

package/common/routeConvention.ts

@@ -13,9 +13,7 @@ export const PAGE_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "default",
   "pageConfig",
   "head",
-  "metadata",
   "generateHead",
-  "generateMetadata",
   "Loading",
 ]);
 export const LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([...PAGE_ROUTE_EXPORTS, "NotFound", "Error"]);
@@ -27,7 +25,6 @@ export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "reconnect",
   "wsConnect",
   "layoutStyle",
-  "gaTrackingId",
 ]);
 /** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
 export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(

package/constant/constantRegistry.ts

@@ -238,16 +238,15 @@ export class ConstantRegistry {
       PurifiedModel<Model>
     >;
   }
-  static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false): Value {
+  static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
     if (Array.isArray(value) && Array.isArray(modelRef)) {
       const singleModelRef = modelRef.at(0);
       if (!singleModelRef) throw new Error("No model ref found");
       return value.map((v: object) => ConstantRegistry.serialize(singleModelRef as Cls, v)) as unknown as Value;
     } else if (modelRef === Map && value instanceof Map) {
+      if (!of) throw new Error("A Map needs its value type (of) to serialize");
       return Object.fromEntries(
-        [...value.entries()].map(([key, value]: [string, unknown]) => {
-          return [key, ConstantRegistry.serialize(value as Cls, value)];
-        }),
+        [...value.entries()].map(([key, entry]: [string, unknown]) => [key, ConstantRegistry.serialize(of, entry)]),
       ) as unknown as Value;
     } else if (PrimitiveRegistry.has(modelRef as Cls)) {
       return (modelRef as typeof PrimitiveScalar)._serialize(value as PrimitiveValue) as unknown as Value;
@@ -255,17 +254,15 @@ export class ConstantRegistry {
       return serialize(modelRef as ConstantCls, 0, value, "object", { nullable }) as unknown as Value;
     } else throw new Error(`No serialize function for modelRef: ${modelRef}`);
   }
-  static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false): Value {
+  static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
     if (Array.isArray(value) && Array.isArray(modelRef)) {
       const singleModelRef = modelRef.at(0);
       if (!singleModelRef) throw new Error("No model ref found");
       return value.map((v: object) => ConstantRegistry.deserialize(singleModelRef as Cls, v)) as unknown as Value;
-    } else if (modelRef === Map && value instanceof Map) {
-      return new Map(
-        Object.entries(value).map(([key, value]: [string, unknown]) => {
-          return [key, ConstantRegistry.deserialize(value as Cls, value)];
-        }),
-      ) as unknown as Value;
+    } else if (modelRef === Map && value !== null && typeof value === "object") {
+      if (!of) throw new Error("A Map needs its value type (of) to deserialize");
+      const entries: [string, unknown][] = value instanceof Map ? [...value.entries()] : Object.entries(value);
+      return new Map(entries.map(([key, entry]) => [key, ConstantRegistry.deserialize(of, entry)])) as unknown as Value;
     } else if (PrimitiveRegistry.has(modelRef as Cls)) {
       return (modelRef as typeof PrimitiveScalar)._parse(value as PrimitiveValue) as unknown as Value;
     } else if (ConstantRegistry.modelRefNameMap.has(modelRef as Cls)) {

package/constant/getDefault.ts

@@ -5,7 +5,10 @@ import type { DefaultOf } from "./types";
 export interface DefaultPlan {
   /** Fields whose default is a value that can be shared: a primitive, `null`, or the field's own literal. */
   shared: Record<string, unknown>;
-  /** Fields that have to be produced per call — a thunk, a fresh array, or a nested scalar record. */
+  /**
+   * Fields that have to be produced per call — a thunk, a fresh array, a nested scalar record, or a primitive's
+   * structured default.
+   */
   perCall: Map<string, () => unknown>;
 }
 
@@ -49,7 +52,23 @@ const buildPlan = (fieldObj: FieldObject): DefaultPlan => {
     else if (field.isClass) {
       if (field.isScalar) perCall.set(key, () => getDefault(field.modelRef[FIELD_META]));
       else shared[key] = null;
-    } else shared[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
+    } else {
+      const primitiveDefault = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
+      if (isStructured(primitiveDefault)) perCall.set(key, () => structuredClone(primitiveDefault));
+      else shared[key] = primitiveDefault;
+    }
   }
   return { shared, perCall };
 };
+
+const isStructured = (value: unknown): value is object =>
+  typeof value === "object" &&
+  value !== null &&
+  (Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+/**
+ * A primitive's value is never an identity, so a plain object or array — an empty editor document as a primitive's
+ * `DEFAULT_VALUE` — is copied for each use, for the reason an array field default is. An instance (a `Dayjs`, a
+ * `Uint8Array`) is handed back as is: its own API is how it changes, and a structured copy would drop its prototype.
+ */
+export const freshPrimitiveValue = <T>(value: T): T => (isStructured(value) ? structuredClone(value) : value);