akanjs 3.0.0-alpha.57 → 3.0.0-alpha.59

package/client/csrTypes.ts

@@ -1,9 +1,10 @@
 "use client";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 import type { PromiseOrObject } from "akanjs/base";
-import { createContext, type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
+import { type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
 import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "react-spring";
 import type { RouterInstance } from "./router";
+import { sharedContext } from "./sharedContext";
 import type { ReactFont } from "./types";
 
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
@@ -349,7 +350,7 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = createContext<CsrContextType>({} as unknown as CsrContextType);
+export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;
@@ -363,7 +364,7 @@ export interface PathContextType {
   setGestureEnabled: (enabled: boolean) => void;
   registerFrameSlot: (slot: FrameSlotRegistration) => () => void;
 }
-export const pathContext = createContext<PathContextType>({} as unknown as PathContextType);
+export const pathContext = sharedContext<PathContextType>("path", {} as unknown as PathContextType);
 export const usePathCtx = () => {
   const contextValues = useContext(pathContext);
   return contextValues;

package/client/index.ts

@@ -11,6 +11,7 @@ export * from "./locale";
 export * from "./makePageProto";
 export * from "./router";
 export * from "./rscNavigation";
+export * from "./sharedContext";
 export * from "./storage";
 export * from "./translator";
 export * from "./types";

package/client/locale.ts

@@ -1,4 +1,4 @@
 "use client";
-import { createContext } from "react";
+import { sharedContext } from "./sharedContext";
 
-export const dictionaryContext = createContext<{ [key: string]: { [key: string]: string } }>({});
+export const dictionaryContext = sharedContext<{ [key: string]: { [key: string]: string } }>("dictionary", {});

package/client/sharedContext.ts

@@ -0,0 +1,31 @@
+"use client";
+import { type Context, createContext } from "react";
+
+/**
+ * A React context interned on `globalThis`, which is how every context this framework owns must be made.
+ *
+ * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
+ * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
+ * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
+ * consumer silently reads the context's default instead.
+ *
+ * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
+ * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
+ * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
+ * a bug in the app's own component. The same shape cost a zone every tool it declared.
+ *
+ * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
+ * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
+ *
+ * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
+ * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
+ */
+export const sharedContext = <T>(name: string, initial: T): Context<T> => {
+  const key = Symbol.for(`akanjs.context.${name}`);
+  const holder = globalThis as typeof globalThis & { [slot: symbol]: Context<T> | undefined };
+  const existing = holder[key];
+  if (existing) return existing;
+  const created = createContext(initial);
+  holder[key] = created;
+  return created;
+};

package/client/translator.ts

@@ -1,4 +1,4 @@
-import { pathGet } from "akanjs/common";
+import { pathGetLoose } from "akanjs/common";
 
 export interface Dictionary {
   [key: string]: {
@@ -63,7 +63,7 @@ export class Translator {
   static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string {
     const dictionary = getTranslatorState().langDictionaryMap.get(lang);
     if (!dictionary) return key;
-    const msg = (pathGet(key, dictionary, ".", { t: key }) as { t: string }).t;
+    const msg = (pathGetLoose(key, dictionary, ".", { t: key }) as { t: string }).t;
     return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
   }
 

package/common/index.ts

@@ -39,6 +39,7 @@ export {
 export { mergeVersion } from "./mergeVersion";
 export { objectify } from "./objectify";
 export { pathGet } from "./pathGet";
+export { pathGetLoose } from "./pathGetLoose";
 export { pathSet } from "./pathSet";
 export { randomPick } from "./randomPick";
 export { randomPicks } from "./randomPicks";

package/common/pathGetLoose.ts

@@ -0,0 +1,31 @@
+type Indexable = Record<string, unknown>;
+
+const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
+
+/**
+ * Reads a dotted path whose segments may themselves contain the separator.
+ *
+ * Dictionary keys are built as `<refName>.<value>` and an enum value is a real-world identifier — `gpt-5.6-terra`,
+ * `v1.2` — so the key is not a clean dotted path and `pathGet` splits it into segments that were never nodes.
+ * The tree stores such a key literally, so resolution has to try joined prefixes too.
+ */
+export const pathGetLoose = (
+  path: string | readonly string[],
+  obj: unknown,
+  separator = ".",
+  fallback: unknown = null,
+): unknown => {
+  const walk = (node: unknown, rest: readonly string[]): unknown => {
+    if (!rest.length) return node;
+    if (!isIndexable(node)) return undefined;
+    
+    for (let take = 1; take <= rest.length; take += 1) {
+      const child = node[rest.slice(0, take).join(separator)];
+      if (child === undefined) continue;
+      const found = walk(child, rest.slice(take));
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return walk(obj, Array.isArray(path) ? [...path] : (path as string).split(separator)) ?? fallback;
+};

package/dictionary/DictionaryLookup.ts

@@ -1,4 +1,4 @@
-import { pathGet } from "akanjs/common";
+import { pathGetLoose } from "akanjs/common";
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictionaryNode } from "./trans";
 
@@ -23,7 +23,7 @@ export class DictionaryLookup {
     const [refName, ...rest] = key.split(".");
     if (!refName) return undefined;
     const model = this.#models[refName];
-    const node = (rest.length ? pathGet(rest.join("."), model) : model) as { t?: unknown } | null;
+    const node = (rest.length ? pathGetLoose(rest, model) : model) as { t?: unknown } | null;
     const text = node?.t;
     return typeof text === "string" && text.length ? text : undefined;
   }

package/dictionary/trans.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
-import { pathGet } from "akanjs/common";
+import { pathGetLoose } from "akanjs/common";
 
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
@@ -177,7 +177,7 @@ export const makeTrans = <
     const msgKey = msgKeys.join(".");
     const langDict = rootDictionary[lang] ?? {};
     const model = langDict[modelName as string] ?? {};
-    const message = pathGet(msgKey as string, model, ".", { t: key }) as { t: string };
+    const message = pathGetLoose(msgKey as string, model, ".", { t: key }) as { t: string };
     return message.t;
   };
   const getDictionary = (lang: Language) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.57",
+  "version": "3.0.0-alpha.59",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/predefinedAdaptor/database.adaptor.ts

@@ -981,6 +981,7 @@ export class SqlDocumentStore {
   #insertStmt: AkanSqlStatement | null = null;
   #readStmtCache = new Map<string, AkanSqlStatement>();
   #docPrototype: object | null = null;
+  #immutableKeys: string[] | null = null;
 
   constructor(
     private readonly owner: DocumentDatabaseOwner,
@@ -1483,7 +1484,9 @@ export class SqlDocumentStore {
     originalData: DocumentRecord,
     { runSaveHooks = true, crudType = "update" }: WriteHookOptions = {},
   ) {
-    const doc = this.hydrate(this.prepareDocument({ ...data, id, updatedAt: dayjs() }), originalData);
+    const prepared = this.prepareDocument({ ...data, id, updatedAt: dayjs() });
+    this.#assertImmutableUnchanged(prepared, originalData);
+    const doc = this.hydrate(prepared, originalData);
     if (runSaveHooks) await this.runHooks("save", crudType, doc, "pre");
     await this.runHooks(crudType, crudType, doc, "pre");
     const row = this.toRow(doc);
@@ -1498,6 +1501,19 @@ export class SqlDocumentStore {
     return doc;
   }
 
+  #assertImmutableUnchanged(prepared: DocumentRecord, originalData: DocumentRecord) {
+    this.#immutableKeys ??= Object.entries(this.database.doc[FIELD_META] as unknown as FieldMap)
+      .filter(([, fieldMeta]) => fieldMeta.getProps().immutable)
+      .map(([key]) => key);
+    if (!this.#immutableKeys.length) return;
+    const changed = this.#immutableKeys.filter((key) => jsonStr(prepared[key]) !== jsonStr(originalData[key]));
+    if (!changed.length) return;
+    
+    throw new Error(
+      `Cannot modify immutable field${changed.length > 1 ? "s" : ""} on ${this.table} (${String(prepared.id)}): ${changed.join(", ")}`,
+    );
+  }
+
   private parseProjectedValue(value: unknown) {
     if (typeof value !== "string") return value;
     const trimmed = value.trim();

package/types/client/index.d.ts

@@ -11,6 +11,7 @@ export * from "./locale.d.ts";
 export * from "./makePageProto.d.ts";
 export * from "./router.d.ts";
 export * from "./rscNavigation.d.ts";
+export * from "./sharedContext.d.ts";
 export * from "./storage.d.ts";
 export * from "./translator.d.ts";
 export * from "./types.d.ts";

package/types/client/sharedContext.d.ts

@@ -0,0 +1,21 @@
+import { type Context } from "react";
+/**
+ * A React context interned on `globalThis`, which is how every context this framework owns must be made.
+ *
+ * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
+ * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
+ * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
+ * consumer silently reads the context's default instead.
+ *
+ * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
+ * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
+ * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
+ * a bug in the app's own component. The same shape cost a zone every tool it declared.
+ *
+ * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
+ * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
+ *
+ * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
+ * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
+ */
+export declare const sharedContext: <T>(name: string, initial: T) => Context<T>;

package/types/common/index.d.ts

@@ -21,6 +21,7 @@ export { isMcpDescribableArg, type McpExposureEndpoint, type McpExposureOption,
 export { mergeVersion } from "./mergeVersion.d.ts";
 export { objectify } from "./objectify.d.ts";
 export { pathGet } from "./pathGet.d.ts";
+export { pathGetLoose } from "./pathGetLoose.d.ts";
 export { pathSet } from "./pathSet.d.ts";
 export { randomPick } from "./randomPick.d.ts";
 export { randomPicks } from "./randomPicks.d.ts";

package/types/common/pathGetLoose.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reads a dotted path whose segments may themselves contain the separator.
+ *
+ * Dictionary keys are built as `<refName>.<value>` and an enum value is a real-world identifier — `gpt-5.6-terra`,
+ * `v1.2` — so the key is not a clean dotted path and `pathGet` splits it into segments that were never nodes.
+ * The tree stores such a key literally, so resolution has to try joined prefixes too.
+ */
+export declare const pathGetLoose: (path: string | readonly string[], obj: unknown, separator?: string, fallback?: unknown) => unknown;

package/types/ui/Agent/History.d.ts

@@ -16,5 +16,11 @@ export interface HistoryProps {
  *
  * Restoring follows the session's one rule: it lands only while nothing has happened to the conversation yet, so
  * mounting with the zone restores and mounting later saves from there on.
+ *
+ * The store is attached for exactly as long as this is mounted. A zone's own session dies with it, so that is the
+ * whole story there — but a session the app handed in (`Agent.Zone`'s `session` prop) outlives this, and its
+ * saving stops on unmount: nothing is claiming to persist it any more, and a component that is gone should not
+ * still be writing. A host that wants the store to outlive the view calls `session.setHistory` itself, which also
+ * takes the slot, so a later unmount here leaves it alone.
  */
 export declare const History: ({ load, save, clear, onCompact }: HistoryProps) => null;

package/types/ui/Dialog/context.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 export interface DialogContextType {
     open: boolean;
     setOpen: (open: boolean) => void;

package/types/ui/Tab/context.d.ts

@@ -1,4 +1,4 @@
-import { type RefObject } from "react";
+import type { RefObject } from "react";
 interface TabContextType {
     defaultMenu: string | null;
     menu: string | null;

package/types/ui/UiOverride/context.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentType } from "react";
+import type { ComponentType } from "react";
 import type { ClassNameValue as ClassValue } from "tailwind-merge";
 import type { ApprovalProps as AgentApprovalProps } from "../Agent/Approval.d.ts";
 import type { BubbleProps as AgentBubbleProps } from "../Agent/Bubble.d.ts";

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -134,10 +134,12 @@ export declare class AgentSession {
      * Restoring follows the rule an async `load` already follows: it lands only while nothing has happened to this
      * session yet. Attach before the first turn and it restores; attach after and it saves from there on, with the
      * store never asked for a transcript that would be discarded. One rule rather than a mount-order surprise.
+     *
+     * Returns the detach, which clears the slot only while this call's store is still the one in it.
      */
-    setHistory: (history: SessionHistory | null) => void;
+    setHistory: (history: SessionHistory | null) => () => void;
     /** The compaction hook as a setter, for the same reason `setHistory` is one: a host attaches it after the fact. */
-    setOnCompact: (onCompact: AgentSessionOptions["onCompact"] | null) => void;
+    setOnCompact: (onCompact: AgentSessionOptions["onCompact"] | null) => () => void;
     /**
      * Re-runs the last user message, dropping what the previous attempt produced. Turns fail for reasons that have
      * nothing to do with what was asked — a refused relay, a model that is unavailable — and retyping is otherwise the

package/ui/Agent/History.tsx

@@ -20,6 +20,12 @@ export interface HistoryProps {
  *
  * Restoring follows the session's one rule: it lands only while nothing has happened to the conversation yet, so
  * mounting with the zone restores and mounting later saves from there on.
+ *
+ * The store is attached for exactly as long as this is mounted. A zone's own session dies with it, so that is the
+ * whole story there — but a session the app handed in (`Agent.Zone`'s `session` prop) outlives this, and its
+ * saving stops on unmount: nothing is claiming to persist it any more, and a component that is gone should not
+ * still be writing. A host that wants the store to outlive the view calls `session.setHistory` itself, which also
+ * takes the slot, so a later unmount here leaves it alone.
  */
 export const History = ({ load, save, clear, onCompact }: HistoryProps) => {
   const session = useContext(SessionContext);
@@ -28,16 +34,15 @@ export const History = ({ load, save, clear, onCompact }: HistoryProps) => {
   const latest = useRef({ load, save, clear, onCompact });
   latest.current = { load, save, clear, onCompact };
   useEffect(() => {
-    session.setHistory({
+    const detachHistory = session.setHistory({
       load: () => latest.current.load(),
       save: (messages) => latest.current.save(messages),
       clear: () => latest.current.clear(),
     });
-    session.setOnCompact((replaced, summary) => latest.current.onCompact?.(replaced, summary));
+    const detachCompact = session.setOnCompact((replaced, summary) => latest.current.onCompact?.(replaced, summary));
     return () => {
-      
-      session.setHistory(null);
-      session.setOnCompact(null);
+      detachHistory();
+      detachCompact();
     };
   }, [session]);
   return null;

package/ui/Dialog/context.ts

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, type ReactNode } from "react";
+import type { ReactNode } from "react";
+import { sharedContext } from "../../client/sharedContext";
 
 export interface DialogContextType {
   open: boolean;
@@ -18,7 +19,7 @@ export interface DialogContextType {
   setAction: (action: ReactNode) => void;
 }
 
-export const DialogContext = createContext<DialogContextType>({
+export const DialogContext = sharedContext<DialogContextType>("dialog", {
   open: false,
   setOpen: (open: boolean) => null,
   openDialog: () => null,

package/ui/DragAction.tsx

@@ -3,8 +3,9 @@ import { useGesture } from "@use-gesture/react";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 import { cn } from "akanjs/client";
 import { animated } from "akanjs/ui";
-import { createContext, type ReactNode, useContext, useRef } from "react";
+import { type ReactNode, useContext, useRef } from "react";
 import { SpringValue, useSpring } from "react-spring";
+import { sharedContext } from "../client/sharedContext";
 
 interface DragActionContextType {
   bind: () => ReactDOMAttributes;
@@ -17,7 +18,7 @@ interface DragActionContextType {
   onClick?: () => void;
 }
 
-const DragActionContext = createContext<DragActionContextType>({
+const DragActionContext = sharedContext<DragActionContextType>("dragAction", {
   bind: () => ({}),
   x: new SpringValue(0),
   y: new SpringValue(0),

package/ui/DraggableList.tsx

@@ -4,9 +4,10 @@ import { useGesture } from "@use-gesture/react";
 import { cn } from "akanjs/client";
 import { useFieldTool } from "akanjs/store";
 import { animated } from "akanjs/ui";
-import { createContext, type ReactElement, type ReactNode, useContext, useRef } from "react";
+import { type ReactElement, type ReactNode, useContext, useRef } from "react";
 import { BiTrash } from "react-icons/bi";
 import { MdDragIndicator } from "react-icons/md";
+import { sharedContext } from "../client/sharedContext";
 import { agentAttrs } from "./agentAttrs";
 import { buttonRecipe } from "./Button";
 import { useUiRecipe } from "./UiOverride";
@@ -24,7 +25,7 @@ interface DragListContextType<V> {
   bind: (...args: any[]) => any;
   onRemove: (value: V) => void;
 }
-const dragListContext = createContext<DragListContextType<any>>({} as unknown as DragListContextType<any>);
+const dragListContext = sharedContext<DragListContextType<any>>("dragList", {} as unknown as DragListContextType<any>);
 const useDragList = () => useContext(dragListContext);
 
 interface DragListProps<V> {

package/ui/ScreenNavigator.tsx

@@ -4,8 +4,9 @@ import { cn } from "akanjs/client";
 import { capitalize } from "akanjs/common";
 import { st } from "akanjs/store";
 import { animated } from "akanjs/ui";
-import { createContext, type ReactNode, useContext, useEffect, useRef, useState } from "react";
+import { type ReactNode, useContext, useEffect, useRef, useState } from "react";
 import { SpringValue, useSpringValue } from "react-spring";
+import { sharedContext } from "../client/sharedContext";
 
 interface ScreenNavigatorContextType {
   bind: (...args: any[]) => any;
@@ -16,7 +17,7 @@ interface ScreenNavigatorContextType {
   onClickMenu: (menu: string) => void;
 }
 
-const ScreenNavigatorContext = createContext<ScreenNavigatorContextType>({
+const ScreenNavigatorContext = sharedContext<ScreenNavigatorContextType>("screenNavigator", {
   bind: () => ({}),
   xValue: new SpringValue(0),
   setMenu: null as unknown as (menu: string) => void,

package/ui/Signal/Object.tsx

@@ -90,7 +90,7 @@ const ObjectDetail = ({ className, objRef }: ObjectDetailProps) => {
                       <ObjectType objRef={modelRef} arrDepth={arrDepth} nullable={nullable} />
                     ) : (
                       <span className={docPill("muted", "font-mono")}>
-                        {typeLabel(ConstantRegistry.getModelName(modelRef), arrDepth, nullable)}
+                        {typeLabel(isMap ? "Map" : ConstantRegistry.getModelName(modelRef), arrDepth, nullable)}
                       </span>
                     )}
                     {isMap ? (

package/ui/Signal/makeExample.ts

@@ -8,10 +8,15 @@ import {
   PrimitiveRegistry,
   type PrimitiveScalar,
 } from "akanjs/base";
-import { type ConstantCls, ConstantRegistry } from "akanjs/constant";
+import { type ConstantCls, type ConstantField, ConstantRegistry } from "akanjs/constant";
 
 import type { SerializedArg, SerializedEndpoint, SignalType } from "akanjs/signal";
 
+const getMapExample = (field: ConstantField, getValueExample: (modelRef: Cls) => unknown) => {
+  const [valueRef, valueArrDepth] = getNonArrayModel(field.of as Cls);
+  return { key: arraiedModel(getValueExample(valueRef as Cls), valueArrDepth) };
+};
+
 const getResponseExample = (ref: Cls | Cls[]) => {
   const [modelRef, arrDepth] = getNonArrayModel(ref);
   const isPrimitive = PrimitiveRegistry.has(modelRef);
@@ -21,6 +26,7 @@ const getResponseExample = (ref: Cls | Cls[]) => {
   Object.entries((modelRef as ConstantCls)[FIELD_META]).forEach(([key, field]) => {
     if (field.example) example[key] = field.example as unknown;
     else if (field.enum) example[key] = arraiedModel<string>(field.enum.values[0] as string, field.arrDepth);
+    else if (field.isMap) example[key] = getMapExample(field, getResponseExample);
     else example[key] = getResponseExample(field.modelRef);
   });
   const result = arraiedModel(example, arrDepth);
@@ -33,7 +39,8 @@ const getRequestExample = (modelRef: Cls) => {
   if (isPrimitive) return (modelRef as typeof PrimitiveScalar)[EXAMPLE_VALUE];
   else {
     Object.entries((modelRef as ConstantCls)[FIELD_META]).forEach(([key, field]) => {
-      if (!field.isScalar && field.isClass) example[key] = "ObjectID";
+      if (field.isMap) example[key] = getMapExample(field, getRequestExample);
+      else if (!field.isScalar && field.isClass) example[key] = "ObjectID";
       else
         example[key] = (
           (field.example ?? field.enum)

package/ui/Tab/context.ts

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, type RefObject } from "react";
+import type { RefObject } from "react";
+import { sharedContext } from "../../client/sharedContext";
 
 interface TabContextType {
   defaultMenu: string | null;
@@ -10,7 +11,7 @@ interface TabContextType {
   switchTab: (menu: string) => void;
 }
 
-export const TabContext = createContext<TabContextType>({
+export const TabContext = sharedContext<TabContextType>("tab", {
   defaultMenu: null,
   menu: null,
   setMenu: (value: string | null) => null,

package/ui/UiOverride/context.ts

@@ -1,6 +1,7 @@
 "use client";
-import { type ComponentType, createContext } from "react";
+import type { ComponentType } from "react";
 import type { ClassNameValue as ClassValue } from "tailwind-merge";
+import { sharedContext } from "../../client/sharedContext";
 import type { ApprovalProps as AgentApprovalProps } from "../Agent/Approval";
 import type { BubbleProps as AgentBubbleProps } from "../Agent/Bubble";
 import type { ChatProps as AgentChatProps } from "../Agent/Chat";
@@ -130,4 +131,4 @@ export type AkanUiOverrideManifest = Partial<AkanUiOverrides> & { recipes?: Part
  * merged (child wins) by each nested `UiOverrideProvider`, mirroring how nested
  * `_layout.tsx` / `_overrides.tsx` stack down the route tree.
  */
-export const UiOverrideContext = createContext<AkanUiOverrideManifest>({});
+export const UiOverrideContext = sharedContext<AkanUiOverrideManifest>("uiOverride", {});

package/ui/overlayLayer.ts

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, useContext } from "react";
+import { useContext } from "react";
+import { sharedContext } from "../client/sharedContext";
 
 /**
  * Overlay surfaces render through `createPortal(document.body)`, so they leave the DOM subtree of the
@@ -22,7 +23,7 @@ export const OVERLAY_LAYER_ATTR = "data-akan-overlay";
 export const overlayZ = { select: 90, dropdown: 100, popconfirmScrim: 105, popconfirm: 110 } as const;
 
 /** Scope that rendered the surrounding content — empty at page level. */
-const OverlayOwnerContext = createContext("");
+const OverlayOwnerContext = sharedContext("overlayOwner", "");
 
 /** Wrap the content a dismissable container owns, with the scope from {@link useOverlayScope}. */
 export const OverlayOwnerProvider = OverlayOwnerContext.Provider;

package/vendor/use-agentic/AgentSession.ts

@@ -313,22 +313,30 @@ export class AgentSession {
    * Restoring follows the rule an async `load` already follows: it lands only while nothing has happened to this
    * session yet. Attach before the first turn and it restores; attach after and it saves from there on, with the
    * store never asked for a transcript that would be discarded. One rule rather than a mount-order surprise.
+   *
+   * Returns the detach, which clears the slot only while this call's store is still the one in it.
    */
   setHistory = (history: SessionHistory | null) => {
     this.#history = history ?? undefined;
-    if (!history || this.#version !== 0) return;
-    const restored = AgentSession.#restored(history);
-    if (!(restored instanceof Promise)) {
-      this.#restore(restored);
-      return;
+    if (history && this.#version === 0) {
+      const restored = AgentSession.#restored(history);
+      if (restored instanceof Promise) {
+        this.#restoring = true;
+        void this.#hydrate(restored);
+      } else this.#restore(restored);
     }
-    this.#restoring = true;
-    void this.#hydrate(restored);
+
+    return () => {
+      if (history && this.#history === history) this.#history = undefined;
+    };
   };
 
   /** The compaction hook as a setter, for the same reason `setHistory` is one: a host attaches it after the fact. */
   setOnCompact = (onCompact: AgentSessionOptions["onCompact"] | null) => {
     this.#onCompact = onCompact ?? undefined;
+    return () => {
+      if (onCompact && this.#onCompact === onCompact) this.#onCompact = undefined;
+    };
   };
 
   /**