akanjs 3.0.0-beta.22 → 3.0.0-beta.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/client/csrTypes.ts +27 -1
  2. package/client/native.ts +3 -0
  3. package/client/route/RouteDefinition.ts +41 -1
  4. package/fetch/client/wsClient.ts +6 -1
  5. package/package.json +16 -6
  6. package/server/akanApp.ts +2 -3
  7. package/server/artifact/builderRpc.ts +5 -0
  8. package/server/artifact/ipcTypes.ts +10 -0
  9. package/server/hmr/clientScript.ts +31 -2
  10. package/server/hmr/csrDevManifest.ts +25 -0
  11. package/server/hmr/csrDevRuntime.ts +474 -0
  12. package/server/hmr/csrDevShell.ts +111 -0
  13. package/server/hmr/csrDevSourceMap.ts +142 -0
  14. package/server/hmr/devHmrController.ts +33 -16
  15. package/server/hmr/runtimeMetadataFile.ts +17 -0
  16. package/server/hmr/wsHub.ts +30 -4
  17. package/server/resolver/signal.resolver.ts +11 -5
  18. package/server/routing/apiRouter.ts +2 -0
  19. package/server/types.tsx +2 -0
  20. package/server/vendor/react-dom.ts +1 -0
  21. package/server/vendor/react-refresh-runtime.ts +13 -1
  22. package/server/vendor/react.ts +2 -0
  23. package/server/webRouter.ts +32 -2
  24. package/service/predefinedAdaptor/sql/QueryCompiler.ts +3 -3
  25. package/store/agent/ScreenTarget.ts +1 -2
  26. package/store/agent/StoreSurfaceSource.ts +3 -1
  27. package/store/liveInsert.ts +35 -13
  28. package/store/storeInstance.ts +28 -21
  29. package/types/client/csrTypes.d.ts +22 -1
  30. package/types/client/native.d.ts +1 -0
  31. package/types/client/route/RouteDefinition.d.ts +14 -0
  32. package/types/server/artifact/builderRpc.d.ts +2 -1
  33. package/types/server/artifact/ipcTypes.d.ts +11 -0
  34. package/types/server/hmr/csrDevManifest.d.ts +18 -0
  35. package/types/server/hmr/csrDevRuntime.d.ts +71 -0
  36. package/types/server/hmr/csrDevShell.d.ts +14 -0
  37. package/types/server/hmr/csrDevSourceMap.d.ts +17 -0
  38. package/types/server/hmr/devHmrController.d.ts +2 -1
  39. package/types/server/hmr/runtimeMetadataFile.d.ts +1 -0
  40. package/types/server/hmr/wsHub.d.ts +11 -0
  41. package/types/server/routing/apiRouter.d.ts +1 -0
  42. package/types/server/types.d.ts +2 -0
  43. package/types/server/vendor/react-dom.d.ts +1 -1
  44. package/types/server/vendor/react-refresh-runtime.d.ts +1 -1
  45. package/types/server/vendor/react.d.ts +1 -1
  46. package/types/store/storeInstance.d.ts +4 -3
  47. package/types/ui/System/Client.d.ts +5 -3
  48. package/types/vendor/@akanjs/native/plugins/app/src/index.d.ts +17 -0
  49. package/types/vendor/@akanjs/native/plugins/app-state/src/index.d.ts +6 -0
  50. package/types/vendor/use-agentic/AgentActivity.d.ts +11 -0
  51. package/types/vendor/use-agentic/AgentGate.d.ts +10 -0
  52. package/types/vendor/use-agentic/AgenticSurface.d.ts +15 -5
  53. package/types/vendor/use-agentic/index.d.ts +2 -0
  54. package/types/vendor/use-agentic/surfaceContext.d.ts +3 -0
  55. package/types/webkit/CsrRouteTable.d.ts +32 -0
  56. package/types/webkit/CsrStack.d.ts +45 -0
  57. package/types/webkit/RenderLayer.d.ts +2 -2
  58. package/types/webkit/bootCsr.d.ts +7 -8
  59. package/types/webkit/index.d.ts +4 -1
  60. package/types/webkit/nativeNavigation.d.ts +13 -0
  61. package/types/webkit/useCsrValues.d.ts +6 -4
  62. package/types/webkit/useFetch.d.ts +3 -1
  63. package/types/webkit/useHistory.d.ts +5 -1
  64. package/types/webkit/usePageActivity.d.ts +2 -0
  65. package/types/webkit/usePageFocusEffect.d.ts +7 -0
  66. package/types/webkit/usePageLocation.d.ts +13 -0
  67. package/ui/Data/Dashboard.tsx +2 -2
  68. package/ui/Data/ListContainer.tsx +2 -2
  69. package/ui/Layout/BottomInset.tsx +1 -1
  70. package/ui/Layout/Navbar.tsx +1 -1
  71. package/ui/Layout/TopInset.tsx +4 -3
  72. package/ui/System/CSR.tsx +40 -79
  73. package/ui/System/Client.tsx +28 -13
  74. package/vendor/@akanjs/native/native/android/src/com/akanjs/runtime/AkanNativeActivity.kt +53 -9
  75. package/vendor/@akanjs/native/native/android/src/com/akanjs/runtime/AkanNativePlugin.kt +16 -0
  76. package/vendor/@akanjs/native/plugins/app/android/AppPlugin.kt +20 -0
  77. package/vendor/@akanjs/native/plugins/app/native-plugin.json +4 -4
  78. package/vendor/@akanjs/native/plugins/app/src/desktop.ts +3 -0
  79. package/vendor/@akanjs/native/plugins/app/src/index.ts +14 -2
  80. package/vendor/@akanjs/native/plugins/app-state/android/AppStatePlugin.kt +38 -2
  81. package/vendor/@akanjs/native/plugins/app-state/ios/AppStatePlugin.swift +19 -0
  82. package/vendor/@akanjs/native/plugins/app-state/native-plugin.json +1 -1
  83. package/vendor/@akanjs/native/plugins/app-state/src/index.ts +6 -1
  84. package/vendor/use-agentic/AgentActivity.tsx +26 -0
  85. package/vendor/use-agentic/AgentGate.ts +25 -0
  86. package/vendor/use-agentic/AgenticSurface.ts +92 -34
  87. package/vendor/use-agentic/index.ts +2 -0
  88. package/vendor/use-agentic/surfaceContext.ts +3 -0
  89. package/webkit/CsrRouteTable.ts +298 -0
  90. package/webkit/CsrStack.ts +98 -0
  91. package/webkit/RenderLayer.tsx +30 -8
  92. package/webkit/bootCsr.tsx +13 -217
  93. package/webkit/index.ts +4 -1
  94. package/webkit/nativeNavigation.ts +78 -5
  95. package/webkit/useCsrValues.ts +118 -22
  96. package/webkit/useFetch.ts +9 -2
  97. package/webkit/useHistory.ts +23 -6
  98. package/webkit/useLocation.ts +6 -3
  99. package/webkit/usePageActivity.ts +6 -0
  100. package/webkit/usePageFocusEffect.ts +13 -0
  101. package/webkit/usePageLocation.ts +17 -0
@@ -6,7 +6,7 @@ import { ConstantRegistry } from "akanjs/constant";
6
6
  import type { SerializedArg } from "akanjs/signal";
7
7
  import { enableMapSet, produce } from "immer";
8
8
  import type { RefObject } from "react";
9
- import { useScopePath } from "../vendor/use-agentic";
9
+ import { type AgentGate, useAgentGate, useScopePath } from "../vendor/use-agentic";
10
10
  import { type ActionOwner, actionTagOf, tagAction } from "./actionTag";
11
11
  import { useFormTools } from "./agentic/useFormTools";
12
12
  import { DraftStore } from "./draftStore";
@@ -170,42 +170,49 @@ export class StoreInstance {
170
170
  );
171
171
  };
172
172
 
173
- retainLive = (key: string, scopeKey = "") => {
174
- const scopes = this.#liveKeys.get(key) ?? new Map<string, number>();
175
- scopes.set(scopeKey, (scopes.get(scopeKey) ?? 0) + 1);
173
+ retainLive = (key: string, scopeKey = "", gate: AgentGate | null = null) => {
174
+ const scopes = this.#liveKeys.get(key) ?? new Map<string, Map<AgentGate | null, number>>();
175
+ const gates = scopes.get(scopeKey) ?? new Map<AgentGate | null, number>();
176
+ gates.set(gate, (gates.get(gate) ?? 0) + 1);
177
+ scopes.set(scopeKey, gates);
176
178
  this.#liveKeys.set(key, scopes);
177
179
  };
178
180
 
179
- releaseLive = (key: string, scopeKey = "") => {
181
+ releaseLive = (key: string, scopeKey = "", gate: AgentGate | null = null) => {
182
+ const gates = this.#liveKeys.get(key)?.get(scopeKey);
183
+ if (!gates) return;
184
+ const count = gates.get(gate) ?? 0;
185
+ if (count <= 1) gates.delete(gate);
186
+ else gates.set(gate, count - 1);
187
+ if (gates.size) return;
180
188
  const scopes = this.#liveKeys.get(key);
181
- if (!scopes) return;
182
- const count = scopes.get(scopeKey) ?? 0;
183
- if (count <= 1) scopes.delete(scopeKey);
184
- else scopes.set(scopeKey, count - 1);
185
- if (!scopes.size) this.#liveKeys.delete(key);
189
+ scopes?.delete(scopeKey);
190
+ if (!scopes?.size) this.#liveKeys.delete(key);
186
191
  };
187
192
 
188
193
  #useLive(key: string, count = true) {
189
-
194
+
190
195
  const scopeKey = useScopePath().join(".");
196
+ const gate = useAgentGate();
191
197
  useEffect(() => {
192
198
  if (!count) return;
193
- this.retainLive(key, scopeKey);
199
+ this.retainLive(key, scopeKey, gate);
194
200
  return () => {
195
- this.releaseLive(key, scopeKey);
201
+ this.releaseLive(key, scopeKey, gate);
196
202
  };
197
- }, [key, count, scopeKey]);
203
+ }, [key, count, scopeKey, gate]);
198
204
  }
199
205
 
200
206
  #useLiveSelector(selector: (state: StoreStateRecord) => unknown) {
201
207
  const scopeKey = useScopePath().join(".");
208
+ const gate = useAgentGate();
202
209
  useEffect(() => {
203
210
  const keys = [...this.#touched(selector)];
204
- for (const key of keys) this.retainLive(key, scopeKey);
211
+ for (const key of keys) this.retainLive(key, scopeKey, gate);
205
212
  return () => {
206
- for (const key of keys) this.releaseLive(key, scopeKey);
213
+ for (const key of keys) this.releaseLive(key, scopeKey, gate);
207
214
  };
208
- }, [scopeKey]);
215
+ }, [scopeKey, gate]);
209
216
  }
210
217
 
211
218
  #touched(selector: (state: StoreStateRecord) => unknown) {
@@ -244,7 +251,7 @@ export class StoreInstance {
244
251
  readonly #sliceStateRoles = new Map<string, SliceStateRole>();
245
252
  readonly #actionArity = new Map<string, number>();
246
253
  readonly #actionOwners = new Map<string, ActionOwner>();
247
- readonly #liveKeys = new Map<string, Map<string, number>>();
254
+ readonly #liveKeys = new Map<string, Map<string, Map<AgentGate | null, number>>>();
248
255
  readonly #generatedSetters = new Set<string>();
249
256
 
250
257
  /** How many mounted components read each state key right now. */
@@ -252,14 +259,14 @@ export class StoreInstance {
252
259
  return this.liveKeysIn("");
253
260
  }
254
261
 
255
- /** Live keys retained at `viewKey`'s scope or below; `""` is the whole screen. */
262
+ /** Live keys retained at `viewKey`'s scope or below, behind no gate or an active one; `""` is the whole screen. */
256
263
  liveKeysIn(viewKey: string): ReadonlyMap<string, number> {
257
264
  const keys = new Map<string, number>();
258
265
  for (const [key, scopes] of this.#liveKeys) {
259
266
  let total = 0;
260
- for (const [scopeKey, count] of scopes) {
267
+ for (const [scopeKey, gates] of scopes) {
261
268
  if (viewKey && scopeKey !== viewKey && !scopeKey.startsWith(`${viewKey}.`)) continue;
262
- total += count;
269
+ for (const [gate, count] of gates) if (gate?.active ?? true) total += count;
263
270
  }
264
271
  if (total > 0) keys.set(key, total);
265
272
  }
@@ -100,6 +100,9 @@ export type LayoutErrorRender = (props: LayoutErrorProps) => PromiseOrObject<Rea
100
100
  export interface RouteRender {
101
101
  render: LayoutRender | PageRender;
102
102
  isAsync?: boolean;
103
+ /** CSR: a page's render reads the query; a layout's reads only the params of its own path (`paramNames`). */
104
+ kind?: "page" | "layout";
105
+ paramNames?: string[];
103
106
  Loading?: LayoutLoadingRender | PageLoadingRender;
104
107
  /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
105
108
  resolveLoading?: () => void | Promise<void>;
@@ -217,6 +220,7 @@ export interface Location {
217
220
  };
218
221
  pathRoute: PathRoute;
219
222
  hash: string;
223
+ entryId?: string;
220
224
  }
221
225
  export type CsrNavigationPhase = "idle" | "preparing" | "transitioning";
222
226
  export type CsrNavigationKind = "push" | "replace" | "back" | "popForward" | "popBack";
@@ -243,6 +247,7 @@ export interface History {
243
247
  idxMap: Map<string, number>;
244
248
  cachedLocationMap: Map<string, Location>;
245
249
  idx: number;
250
+ dormant?: Set<string>;
246
251
  }
247
252
  export interface RouterProps {
248
253
  push: (path: string) => void;
@@ -250,14 +255,23 @@ export interface RouterProps {
250
255
  refresh: () => void;
251
256
  back: () => void | Promise<void>;
252
257
  }
258
+ export type CsrPageType = "current" | "prev" | "pending" | "cached";
259
+ export interface CsrStackEntry {
260
+ key: string;
261
+ location: Location;
262
+ pageType: CsrPageType;
263
+ zIndex: number;
264
+ }
253
265
  export interface RouteState {
254
266
  clientWidth: number;
255
267
  clientHeight: number;
256
268
  location: Location;
257
269
  prevLocation: Location | null;
258
270
  pendingLocation: Location | null;
271
+ stackEntries: CsrStackEntry[];
259
272
  navigationIntent: NavigationIntent | null;
260
273
  phase: CsrNavigationPhase;
274
+ isBackgrounded: boolean;
261
275
  history: RefObject<History>;
262
276
  topSafeAreaRef: RefObject<HTMLDivElement | null>;
263
277
  bottomSafeAreaRef: RefObject<HTMLDivElement | null>;
@@ -285,7 +299,8 @@ export type CsrContextType = RouteState & UseCsrTransition;
285
299
  export declare const csrContext: import("react").Context<CsrContextType>;
286
300
  export declare const useCsr: () => CsrContextType;
287
301
  export interface PathContextType {
288
- pageType: "current" | "prev" | "cached" | "pending";
302
+ pageType: CsrPageType;
303
+ pageKey?: string;
289
304
  location: Location;
290
305
  prefix?: string;
291
306
  gestureEnabled: boolean;
@@ -294,6 +309,12 @@ export interface PathContextType {
294
309
  }
295
310
  export declare const pathContext: import("react").Context<PathContextType>;
296
311
  export declare const usePathCtx: () => PathContextType;
312
+ export type PageActivity = "current" | "prev" | "pending" | "hidden";
313
+ export interface PageActivityState {
314
+ activity: PageActivity;
315
+ focused: boolean;
316
+ }
317
+ export declare const pageActivityContext: import("react").Context<PageActivityState>;
297
318
  export interface PathRoute {
298
319
  path: string;
299
320
  pathSegments: string[];
@@ -24,5 +24,6 @@ export declare const loadIap: () => Promise<typeof import("../vendor/@akanjs/nat
24
24
  /** Inside an iOS or Android shell of the native runtime; a mobile target opened in a browser is not. */
25
25
  export declare const isNativeApp: () => boolean;
26
26
  export declare const nativePlatform: () => "ios" | "android" | null;
27
+ export declare const desktopPlatform: () => "windows" | "macos" | "linux" | null;
27
28
  /** http(s) in the in-app browser, anything else (mailto:, tel:) in the app the system picks. */
28
29
  export declare const openExternalUrl: (url: string) => Promise<void>;
@@ -6,6 +6,8 @@ export type RouteArgsShape = Record<string, unknown>;
6
6
  export type RouteKind = "page" | "layout" | "rootLayout";
7
7
  /** Interned: a definition built inside the pages bundle must be recognised by a loader bundled apart from it. */
8
8
  export declare const routeDefinitionMarker: unique symbol;
9
+ /** Interned like the marker: the declared args ride on the module's render function, read by the CSR render cache. */
10
+ export declare const routeArgsMarker: unique symbol;
9
11
  type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
10
12
  export interface RouteArgResolveOption {
11
13
  /** A prompt's arguments are strings a person typed: a list is comma-separated and a bad value is refused. */
@@ -30,5 +32,17 @@ export declare abstract class RouteDefinition<Args extends RouteArgsShape = Reco
30
32
  /** The module shape every route loader reads, so a chain and a legacy module walk one path from here on. */
31
33
  toRouteModule(): PageModule & LayoutModule;
32
34
  protected extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule;
35
+ /**
36
+ * What a route's render output depends on: a chain's declared args plus `lang`. A legacy module declares nothing,
37
+ * so it depends on the params of its own path (`paramNames`, every param when unknown) and, for a page, every
38
+ * search value — a layout reads no query.
39
+ */
40
+ static renderArgsKey(render: unknown, props: {
41
+ params: Record<string, string>;
42
+ searchParams?: Record<string, string | string[]>;
43
+ }, { isPage, paramNames }: {
44
+ isPage: boolean;
45
+ paramNames?: string[];
46
+ }): string;
33
47
  }
34
48
  export {};
@@ -1,4 +1,4 @@
1
- import type { BuildRouteClientResult, CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
1
+ import type { BuildRouteClientResult, CsrUpdatedPayload, CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
2
2
  export interface BuilderRpcEventHandlers {
3
3
  /** A watcher batch changed files: clear the route cache and broadcast a dev reload. */
4
4
  onInvalidate?: (event: {
@@ -9,6 +9,7 @@ export interface BuilderRpcEventHandlers {
9
9
  onCssUpdated?: (css: CssPayload) => void;
10
10
  /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
11
11
  onPagesUpdated?: (bundle: PagesBundlePayload) => void;
12
+ onCsrUpdated?: (update: CsrUpdatedPayload) => void;
12
13
  onBuildStatus?: (status: DevBuildStatus) => void;
13
14
  }
14
15
  /** One per backend process: subscribes to the IPC channel on construction and unsubscribes on `dispose()`. */
@@ -106,6 +106,14 @@ export interface BuilderMetrics {
106
106
  /** Work items completed since this builder spawned, so a host can require real work before recycling. */
107
107
  workCount: number;
108
108
  }
109
+ export interface CsrUpdatedPayload {
110
+ generation: number;
111
+ mode: "registry" | "artifact";
112
+ reload: boolean;
113
+ reason?: string;
114
+ patchUrl?: string;
115
+ changedIds?: string[];
116
+ }
109
117
  export type BuilderEvent = {
110
118
  type: "builder-ready";
111
119
  buildId?: string;
@@ -124,6 +132,9 @@ export type BuilderEvent = {
124
132
  } | {
125
133
  type: "pages-updated";
126
134
  data: PagesBundlePayload;
135
+ } | {
136
+ type: "csr-updated";
137
+ data: CsrUpdatedPayload;
127
138
  } | {
128
139
  type: "build-status";
129
140
  data: DevBuildStatus;
@@ -0,0 +1,18 @@
1
+ export declare const CSR_DEV_DIRNAME = "csr-dev";
2
+ export declare const CSR_DEV_ROUTE_PREFIX = "/_akan/csr-dev/";
3
+ export declare const CSR_DEV_APP_FILE = "app.js";
4
+ export declare const CSR_DEV_MANIFEST_FILE = "manifest.json";
5
+ export type DevCsrMode = "registry" | "artifact";
6
+ export interface CsrDevManifest {
7
+ version: 1;
8
+ generation: number;
9
+ vendorFile: string;
10
+ entries: Record<string, string>;
11
+ }
12
+ /** Where each module's generated code starts in a combined file (`app.js`, a patch), for its source map. */
13
+ export interface CsrDevLayout {
14
+ lineCount: number;
15
+ modules: [id: string, line: number][];
16
+ }
17
+ export declare const csrDevModuleFile: (id: string, extension: ".js" | ".js.map") => string;
18
+ export declare const resolveDevCsrMode: (env?: Record<string, string | undefined>) => DevCsrMode;
@@ -0,0 +1,71 @@
1
+ export type CsrAcceptCallback = (updated: string[]) => void;
2
+ export interface CsrHotContext {
3
+ readonly data: Record<string, unknown> | undefined;
4
+ accept(deps?: string | string[], callback?: CsrAcceptCallback): void;
5
+ dispose(callback: (data: Record<string, unknown>) => void): void;
6
+ invalidate(): void;
7
+ }
8
+ export interface CsrModuleRecord {
9
+ readonly id: string;
10
+ exports: unknown;
11
+ readonly hot: CsrHotContext;
12
+ }
13
+ export type CsrModuleFactory = (this: unknown, require: (specifier: string) => unknown, module: CsrModuleRecord, exports: unknown, $RefreshReg$: (type: unknown, localId: string) => void, $RefreshSig$: () => (type: unknown, ...rest: unknown[]) => unknown, __akanImport: (specifier: string) => Promise<unknown>) => void;
14
+ export interface CsrUpdateMessage {
15
+ generation: number;
16
+ url?: string | null;
17
+ reload?: boolean;
18
+ reason?: string;
19
+ }
20
+ export interface CsrDevRuntimeApi {
21
+ readonly generation: number;
22
+ define(id: string, factory: CsrModuleFactory): void;
23
+ defineHelpers(hash: string, factory: () => Record<string, unknown>): void;
24
+ helpers(hash: string): Record<string, unknown>;
25
+ start(options: {
26
+ generation: number;
27
+ refresh: string;
28
+ }): void;
29
+ update(generation: number, factories: Record<string, CsrModuleFactory>): void;
30
+ accept(ownerId: string, deps: string[], callback: CsrAcceptCallback): void;
31
+ hot(message: CsrUpdateMessage): void;
32
+ toESM(mod: unknown, isNodeMode?: number): unknown;
33
+ reExport(target: object, mod: unknown, secondTarget?: object): object | undefined;
34
+ inspect(): {
35
+ generation: number;
36
+ executed: string[];
37
+ modules: number;
38
+ };
39
+ }
40
+ interface CsrScriptElement {
41
+ src: string;
42
+ dataset: Record<string, string | undefined>;
43
+ onload: (() => void) | null;
44
+ onerror: (() => void) | null;
45
+ remove(): void;
46
+ }
47
+ export interface CsrDevRuntimeHost {
48
+ __akan?: CsrDevRuntimeApi;
49
+ __AKAN_CSR_LAST_UPDATE__?: {
50
+ generation: number;
51
+ executed: string[];
52
+ };
53
+ document: {
54
+ currentScript: unknown;
55
+ head: {
56
+ appendChild(node: unknown): unknown;
57
+ };
58
+ createElement(tagName: "script"): CsrScriptElement;
59
+ };
60
+ location: {
61
+ reload(): void;
62
+ };
63
+ console: {
64
+ warn(...args: unknown[]): void;
65
+ };
66
+ setTimeout(callback: () => void, ms: number): unknown;
67
+ clearTimeout(handle: unknown): void;
68
+ }
69
+ export declare const installCsrDevRuntime: (host: CsrDevRuntimeHost) => void;
70
+ export declare const CSR_DEV_RUNTIME_SCRIPT: string;
71
+ export {};
@@ -0,0 +1,14 @@
1
+ import { type CsrDevManifest } from "./csrDevManifest.d.ts";
2
+ export interface CsrDevShellRenderOptions {
3
+ basePath: string;
4
+ lang: string;
5
+ title: string;
6
+ cssHref: string | null;
7
+ }
8
+ export declare class CsrDevShell {
9
+ #private;
10
+ constructor(artifactDir: string);
11
+ readManifest(): Promise<CsrDevManifest | null>;
12
+ render({ basePath, lang, title, cssHref }: CsrDevShellRenderOptions): Promise<string | null>;
13
+ serve(req: Request): Promise<Response>;
14
+ }
@@ -0,0 +1,17 @@
1
+ export interface RawSourceMap {
2
+ version: 3;
3
+ file?: string;
4
+ sources: string[];
5
+ sourcesContent?: (string | null)[];
6
+ names: string[];
7
+ mappings: string;
8
+ }
9
+ export interface SourceMapSection {
10
+ /** The line of the combined file where the section's generated line 0 lands. */
11
+ line: number;
12
+ map: RawSourceMap;
13
+ }
14
+ export declare class CsrDevSourceMap {
15
+ #private;
16
+ static merge(file: string, sections: SourceMapSection[], lineCount: number): RawSourceMap;
17
+ }
@@ -1,8 +1,9 @@
1
1
  import { BuilderRpc, type ClientManifest, type DevBuildStatus, RouteClientCache, type RouteSeedIndex } from "../artifact.d.ts";
2
2
  import type { RscWorker } from "../rscWorkerHost.d.ts";
3
3
  import type { RenderState } from "../types.d.ts";
4
+ import { isAkanRuntimeMetadataFile } from "./runtimeMetadataFile.d.ts";
4
5
  import { type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub.d.ts";
5
- export declare function isAkanRuntimeMetadataFile(file: string): boolean;
6
+ export { isAkanRuntimeMetadataFile };
6
7
  export declare function manifestClientEntriesForFiles(files: string[], clientManifest: ClientManifest, workspaceRoot?: string): Set<string>;
7
8
  export declare function devBuildStatusToHmrMessage(status: DevBuildStatus, previous?: DevBuildStatus): Extract<HmrMessage, {
8
9
  type: "build-status";
@@ -0,0 +1 @@
1
+ export declare function isAkanRuntimeMetadataFile(file: string): boolean;
@@ -4,9 +4,11 @@ export interface ChangeBatch {
4
4
  files: string[];
5
5
  kinds: Set<Exclude<ChangeKind, "ignore">>;
6
6
  }
7
+ export type HmrClientKind = "ssr" | "csr";
7
8
  export interface HmrWsData {
8
9
  kind: "akan-hmr";
9
10
  openedAt: number;
11
+ client?: HmrClientKind;
10
12
  }
11
13
  export type HmrMessage = {
12
14
  type: "hello";
@@ -15,9 +17,17 @@ export type HmrMessage = {
15
17
  cssUrl: string;
16
18
  cssRelPath: string;
17
19
  }>;
20
+ csrGeneration?: number;
18
21
  } | {
19
22
  type: "reload";
20
23
  buildId: number;
24
+ } | {
25
+ type: "csr-update";
26
+ generation: number;
27
+ url?: string;
28
+ changedIds?: string[];
29
+ reload?: boolean;
30
+ reason?: string;
21
31
  } | {
22
32
  type: "rsc-refresh";
23
33
  buildId: number;
@@ -56,6 +66,7 @@ export type HmrMessage = {
56
66
  message: string;
57
67
  };
58
68
  export declare const HMR_WS_TOPIC = "__akan_hmr";
69
+ export declare const HMR_CSR_WS_TOPIC = "__akan_hmr_csr";
59
70
  export declare class HmrWsHub {
60
71
  #private;
61
72
  setPublisher(publish: (topic: string, payload: string) => void): void;
@@ -11,6 +11,7 @@ export interface HmrStateSource {
11
11
  cssUrl: string;
12
12
  cssRelPath: string;
13
13
  }>;
14
+ csrGeneration?: number;
14
15
  };
15
16
  }
16
17
  export type NonNullHttpRoutes = NonNullable<HttpRoutes>;
@@ -85,4 +85,6 @@ export interface RenderState {
85
85
  buildId: number;
86
86
  cssAssets: Record<string, CssAsset>;
87
87
  cssBytesByUrl: Record<string, Uint8Array>;
88
+ /** The newest CSR dev bundle generation; a CSR tab whose own generation differs has missed an update. */
89
+ csrGeneration?: number;
88
90
  }
@@ -1,3 +1,3 @@
1
1
  import * as m from "react-dom";
2
2
  export default m;
3
- export declare const __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, createPortal: typeof m.createPortal, flushSync: typeof m.flushSync, preconnect: typeof m.preconnect, prefetchDNS: typeof m.prefetchDNS, preinit: typeof m.preinit, preinitModule: typeof m.preinitModule, preload: typeof m.preload, preloadModule: typeof m.preloadModule, requestFormReset: typeof m.requestFormReset, unstable_batchedUpdates: typeof m.unstable_batchedUpdates, useFormState: typeof m.useFormState, useFormStatus: typeof m.useFormStatus, version: string;
3
+ export declare const __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, browser: any, createPortal: typeof m.createPortal, flushSync: typeof m.flushSync, preconnect: typeof m.preconnect, prefetchDNS: typeof m.prefetchDNS, preinit: typeof m.preinit, preinitModule: typeof m.preinitModule, preload: typeof m.preload, preloadModule: typeof m.preloadModule, requestFormReset: typeof m.requestFormReset, unstable_batchedUpdates: typeof m.unstable_batchedUpdates, useFormState: typeof m.useFormState, useFormStatus: typeof m.useFormStatus, version: string;
@@ -1,3 +1,3 @@
1
1
  import * as m from "react-refresh/runtime";
2
2
  export default m;
3
- export declare const injectIntoGlobalHook: any, performReactRefresh: any, register: any, createSignatureFunctionForTransform: any;
3
+ export declare const _getMountedRootCount: any, collectCustomHooksForSignature: any, createSignatureFunctionForTransform: any, getFamilyByID: any, getFamilyByType: any, hasUnrecoverableErrors: any, injectIntoGlobalHook: any, isLikelyComponentType: any, performReactRefresh: any, register: any, setSignature: any;
@@ -8,4 +8,4 @@ export declare const Activity: m.ExoticComponent<m.ActivityProps>, Children: {
8
8
  toArray(children: m.ReactNode | m.ReactNode[]): Array<Exclude<m.ReactNode, boolean | null | undefined>>;
9
9
  }, Component: typeof m.Component, Fragment: m.ExoticComponent<m.FragmentProps>, Profiler: m.ExoticComponent<m.ProfilerProps>, PureComponent: typeof m.PureComponent, StrictMode: m.ExoticComponent<{
10
10
  children?: m.ReactNode | undefined;
11
- }>, Suspense: m.ExoticComponent<m.SuspenseProps>, __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, __COMPILER_RUNTIME: any, act: typeof m.act, cache: typeof m.cache, cacheSignal: typeof m.cacheSignal, captureOwnerStack: typeof m.captureOwnerStack, cloneElement: typeof m.cloneElement, createContext: typeof m.createContext, createElement: typeof m.createElement, createRef: typeof m.createRef, forwardRef: typeof m.forwardRef, isValidElement: typeof m.isValidElement, lazy: typeof m.lazy, memo: typeof m.memo, startTransition: typeof m.startTransition, unstable_useCacheRefresh: any, use: typeof m.use, useActionState: typeof m.useActionState, useCallback: typeof m.useCallback, useContext: typeof m.useContext, useDebugValue: typeof m.useDebugValue, useDeferredValue: typeof m.useDeferredValue, useEffect: typeof m.useEffect, useEffectEvent: typeof m.useEffectEvent, useId: typeof m.useId, useImperativeHandle: typeof m.useImperativeHandle, useInsertionEffect: typeof m.useInsertionEffect, useLayoutEffect: typeof m.useLayoutEffect, useMemo: typeof m.useMemo, useOptimistic: typeof m.useOptimistic, useReducer: typeof m.useReducer, useRef: typeof m.useRef, useState: typeof m.useState, useSyncExternalStore: typeof m.useSyncExternalStore, useTransition: typeof m.useTransition, version: string;
11
+ }>, Suspense: m.ExoticComponent<m.SuspenseProps>, ViewTransition: any, __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE: any, __COMPILER_RUNTIME: any, act: typeof m.act, addTransitionType: any, cache: typeof m.cache, cacheSignal: typeof m.cacheSignal, captureOwnerStack: typeof m.captureOwnerStack, cloneElement: typeof m.cloneElement, createContext: typeof m.createContext, createElement: typeof m.createElement, createRef: typeof m.createRef, forwardRef: typeof m.forwardRef, isValidElement: typeof m.isValidElement, lazy: typeof m.lazy, memo: typeof m.memo, startTransition: typeof m.startTransition, unstable_useCacheRefresh: any, use: typeof m.use, useActionState: typeof m.useActionState, useCallback: typeof m.useCallback, useContext: typeof m.useContext, useDebugValue: typeof m.useDebugValue, useDeferredValue: typeof m.useDeferredValue, useEffect: typeof m.useEffect, useEffectEvent: typeof m.useEffectEvent, useId: typeof m.useId, useImperativeHandle: typeof m.useImperativeHandle, useInsertionEffect: typeof m.useInsertionEffect, useLayoutEffect: typeof m.useLayoutEffect, useMemo: typeof m.useMemo, useOptimistic: typeof m.useOptimistic, useReducer: typeof m.useReducer, useRef: typeof m.useRef, useState: typeof m.useState, useSyncExternalStore: typeof m.useSyncExternalStore, useTransition: typeof m.useTransition, version: string;
@@ -1,4 +1,5 @@
1
1
  import type { RefObject } from "react";
2
+ import { type AgentGate } from "../vendor/use-agentic.d.ts";
2
3
  import { type ActionOwner } from "./actionTag.d.ts";
3
4
  import type { RootStoreCls } from "./rootStore.d.ts";
4
5
  import type { SliceActionRole, SliceStateRole } from "./sliceRole.d.ts";
@@ -25,8 +26,8 @@ export declare class StoreInstance {
25
26
  }): () => void;
26
27
  };
27
28
  sel: <U>(selector: (state: StoreStateRecord) => U, equals?: (a: U, b: U) => boolean) => U;
28
- retainLive: (key: string, scopeKey?: string) => void;
29
- releaseLive: (key: string, scopeKey?: string) => void;
29
+ retainLive: (key: string, scopeKey?: string, gate?: AgentGate | null) => void;
30
+ releaseLive: (key: string, scopeKey?: string, gate?: AgentGate | null) => void;
30
31
  ref: <U>(selector: (state: StoreStateRecord) => U) => RefObject<U>;
31
32
  use: {
32
33
  [key: string]: (options?: StoreUseOptions) => unknown;
@@ -39,7 +40,7 @@ export declare class StoreInstance {
39
40
  };
40
41
  /** How many mounted components read each state key right now. */
41
42
  get liveKeys(): ReadonlyMap<string, number>;
42
- /** Live keys retained at `viewKey`'s scope or below; `""` is the whole screen. */
43
+ /** Live keys retained at `viewKey`'s scope or below, behind no gate or an active one; `""` is the whole screen. */
43
44
  liveKeysIn(viewKey: string): ReadonlyMap<string, number>;
44
45
  get actionOwners(): ReadonlyMap<string, ActionOwner>;
45
46
  /** Each method's own `length`: `do[key]` is a rest-argument wrapper whose `length` is 0. */
@@ -1,4 +1,4 @@
1
- import { type Location, type PageState, type TransitionStyle } from "akanjs/client";
1
+ import { type CsrPageType, type Location, type PageActivity, type PageState, type TransitionStyle } from "akanjs/client";
2
2
  import type { AkanTheme } from "akanjs/fetch";
3
3
  import type { SerializedSignal } from "akanjs/signal";
4
4
  import { type HTMLAttributes, type ReactNode, type RefObject } from "react";
@@ -22,7 +22,9 @@ export declare const ClientWrapper: ({ children, theme, lang, path, dictionary,
22
22
  interface ClientPathWrapperProps extends Omit<HTMLAttributes<HTMLDivElement>, "style"> {
23
23
  bind?: () => HTMLAttributes<HTMLDivElement>;
24
24
  wrapperRef?: RefObject<HTMLDivElement | null> | null;
25
- pageType?: "current" | "prev" | "cached" | "pending";
25
+ pageType?: CsrPageType;
26
+ pageKey?: string;
27
+ activity?: PageActivity;
26
28
  location?: Location;
27
29
  initialHref?: string;
28
30
  initialPath?: string;
@@ -37,7 +39,7 @@ interface ClientPathWrapperProps extends Omit<HTMLAttributes<HTMLDivElement>, "s
37
39
  children?: ReactNode;
38
40
  layoutStyle?: "web" | "mobile";
39
41
  }
40
- export declare const ClientPathWrapper: ({ className, bind, wrapperRef, pageType, location, initialHref, initialPath, initialPathname, initialParams, initialSearch, initialSearchParams, initialHash, initialPageState, style, prefix, children, layoutStyle, ...props }: ClientPathWrapperProps) => import("react/jsx-runtime").JSX.Element;
42
+ export declare const ClientPathWrapper: ({ className, bind, wrapperRef, pageType, pageKey, activity, location, initialHref, initialPath, initialPathname, initialParams, initialSearch, initialSearchParams, initialHash, initialPageState, style, prefix, children, layoutStyle, ...props }: ClientPathWrapperProps) => import("react/jsx-runtime").JSX.Element;
41
43
  interface ClientBridgeProps {
42
44
  env?: object;
43
45
  lang?: string;
@@ -25,7 +25,15 @@ export interface AppApi {
25
25
  id: number;
26
26
  allow?: boolean;
27
27
  }): Promise<void>;
28
+ /**
29
+ * Android: whether back belongs to the page right now, for a page that listens to backButton. false hands it to
30
+ * the system, which then shows its own back-to-home animation; each new listener starts at true.
31
+ */
32
+ setBackEnabled(args: {
33
+ enabled: boolean;
34
+ }): Promise<void>;
28
35
  }
36
+ export type BackProgressPhase = "started" | "progressed" | "cancelled";
29
37
  export interface AppEvents {
30
38
  /** A deep link arrived while running. URLs that arrive before anyone listens are delivered to the first listener. */
31
39
  urlOpen: {
@@ -40,6 +48,15 @@ export interface AppEvents {
40
48
  id: number;
41
49
  reason: QuitReason;
42
50
  };
51
+ /**
52
+ * Android 14+: a back swipe in progress, for a page that animates it. `progress` runs 0–1; a committed swipe then
53
+ * arrives as backButton, and one let go early as `cancelled`.
54
+ */
55
+ backProgress: {
56
+ phase: BackProgressPhase;
57
+ progress: number;
58
+ swipeEdge: "left" | "right";
59
+ };
43
60
  }
44
61
  export declare const app: import("../../../packages/core/src/plugin.ts").Plugin<AppApi, AppEvents>;
45
62
  /** Calls `handler` for every deep link while mounted. */
@@ -9,10 +9,16 @@ export interface AppStateApi {
9
9
  state: AppStateValue;
10
10
  }>;
11
11
  }
12
+ /** moderate: the system is running low; critical: it is about to end processes, likely this one. */
13
+ export type MemoryWarningLevel = "moderate" | "critical";
12
14
  export interface AppStateEvents {
13
15
  change: {
14
16
  state: AppStateValue;
15
17
  };
18
+ /** The system asked the app to give memory back: iOS's memory warning, Android's onTrimMemory and onLowMemory. */
19
+ memoryWarning: {
20
+ level: MemoryWarningLevel;
21
+ };
16
22
  }
17
23
  export declare const appState: import("../../../packages/core/src/plugin.ts").Plugin<AppStateApi, AppStateEvents>;
18
24
  /** The current app state. Re-renders on every change (SH-1). */
@@ -0,0 +1,11 @@
1
+ import { type ReactNode } from "react";
2
+ export interface AgentActivityProps {
3
+ active: boolean;
4
+ children: ReactNode;
5
+ }
6
+ /**
7
+ * Publishes what is registered below only while `active` — for a subtree kept mounted where the user cannot act on
8
+ * it, like the page under the one on screen. Registrations stay in place, so turning it back on re-publishes them
9
+ * without a remount. A registry that lives outside the surface reads the same gate through `useAgentGate()`.
10
+ */
11
+ export declare const AgentActivity: ({ active, children }: AgentActivityProps) => import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Whether what a subtree registered is published right now. A gate under another is active only while the one
3
+ * above it is, so a panel parked inside a page closes with the page.
4
+ */
5
+ export declare class AgentGate {
6
+ #private;
7
+ constructor(active: boolean, onChange: () => void, parent?: AgentGate | null);
8
+ get active(): boolean;
9
+ set(active: boolean): void;
10
+ }
@@ -1,3 +1,4 @@
1
+ import { AgentGate } from "./AgentGate.d.ts";
1
2
  import type { AgentCall, ResourceDiff, ResourceEntry, ScopeEntry, SurfaceSnapshot, SurfaceSource, SurfaceView, ToolEntry } from "./types.d.ts";
2
3
  /**
3
4
  * The live registry of what the mounted screen offers an agent: tools, readable resources, and scopes.
@@ -20,17 +21,26 @@ export declare class AgenticSurface {
20
21
  * argument rather than closing over it: every registration is then interchangeable and last-wins picks an
21
22
  * equivalent one. The description is what says so — two registrations that describe the same action to a model
22
23
  * are the same declaration twice, and fifty rows are one entry rather than fifty collisions. Two that describe
23
- * different actions under one name are a real clash whichever of them mounted last, and warn.
24
+ * different actions under one name are a real clash whichever of them mounted last, and warn. A clash needs both
25
+ * published at once, so a registration behind a parked gate, or over only parked ones, never warns.
24
26
  */
25
- registerTool(scope: string[], entry: ToolEntry): () => void;
26
- registerResource(scope: string[], entry: ResourceEntry): () => void;
27
- openScope(parent: string[], scope: ScopeEntry): () => void;
27
+ registerTool(scope: string[], entry: ToolEntry, gate?: AgentGate | null): () => void;
28
+ registerResource(scope: string[], entry: ResourceEntry, gate?: AgentGate | null): () => void;
29
+ openScope(parent: string[], scope: ScopeEntry, gate?: AgentGate | null): () => void;
28
30
  /**
29
31
  * Standing guidance for the agent while the registrant is mounted — instructions, not context data. Kept in
30
32
  * registration order rather than sorted: guides are prose, and each one must stay a coherent block.
31
33
  */
32
- registerGuide(scope: string[], text: string): () => void;
34
+ registerGuide(scope: string[], text: string, gate?: AgentGate | null): () => void;
33
35
  addSource(source: SurfaceSource): () => void;
36
+ /** A gate whose every flip re-publishes this surface. Under `parent`, it is active only while the parent is. */
37
+ gate(active: boolean, parent?: AgentGate | null): AgentGate;
38
+ /**
39
+ * This surface for a subtree behind `gate`: what registers through it is published only while the gate is active,
40
+ * and every other call reaches this surface untouched. A proxy rather than a wrapper class, so a method added to the
41
+ * surface later is forwarded instead of missing.
42
+ */
43
+ gated(gate: AgentGate): AgenticSurface;
34
44
  snapshot(view?: string[]): SurfaceSnapshot;
35
45
  /**
36
46
  * A zone session's reading half: the same registry filtered to one scope subtree. Hook entries filter by their
@@ -1,4 +1,6 @@
1
1
  export * from "./AgentAbort.d.ts";
2
+ export * from "./AgentActivity.d.ts";
3
+ export * from "./AgentGate.d.ts";
2
4
  export * from "./Agentic.d.ts";
3
5
  export * from "./AgenticSurface.d.ts";
4
6
  export * from "./AgentProgress.d.ts";