akanjs 3.0.0-alpha.57 → 3.0.0-alpha.58

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,30 @@
+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/package.json

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

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/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/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;
+    };
   };
 
   /**