akanjs 2.4.1-rc.7 → 2.4.2-rc.0

package/CHANGELOG.md

@@ -1,5 +1,331 @@
 # akanjs
 
+## 2.4.1
+
+### Patch Changes
+
+- 473be34: fix(devkit): restart the backend for server code saved while the builder was away
+
+  Nothing watches the source tree between a builder leaving and its replacement being ready: the idle
+  suspend stops its own watcher before the wake's boot build, a recycle or crash takes the builder's
+  watcher with it, and a fresh builder primes its mtime index from whatever it finds on disk — so a save
+  that lands in that window is _baseline_ to it and produces no event anywhere. The client half of such a
+  save is rescued by the boot build reading the new file; the backend half was not. A `.service.ts` saved
+  in that window left the server running the code it replaced, with nothing on screen to say so.
+
+  The dev host now stamps `(mtime, size)` for every file in the backend import graph when the builder goes
+  away — at suspend, at a recycle request, at a crash exit — and compares them when a builder is ready
+  again, restarting the backend for anything that moved. Comparing stamps rather than waiting for events
+  also covers the watcher dropping one, which Bun's recursive `fs.watch` does.
+
+  A config change while suspended is exempt, because it replaces the backend along with the builder on its
+  own. Where the backend graph scan has never succeeded — path-role fallback rules — there is nothing to
+  stamp, and the host says so rather than staying quiet about it.
+
+- f5bfa27: perf(devkit): stop parsing every source file to find barrel imports
+
+  `rewriteBarrelImports` ran a full TypeScript parse of every file it was given, to find import
+  statements it then discarded for all but the barrel ones. It runs on every source file of every dev
+  rebuild, which made it the single most expensive thing in one.
+
+  - **63% of files import no barrel at all.** A static import cannot name a specifier without that
+    specifier appearing literally in the source, so a substring test skips them before the parser is
+    involved — 4ms for 1189 files. The bundler plugin already did this privately; it now lives in
+    `rewriteBarrelImports` so the CSS and client-entry walks get it too.
+  - **`setParentNodes: true` was paid for no reader.** Nothing reads `node.parent`; every position comes
+    from `getStart(sourceFile)`, which takes the file explicitly.
+
+  Measured across 1189 files: 299ms and 161MB of RSS become 88ms and 5MB. End to end on `apps/akan`,
+  `CssCompiler.discoverCssAndSources` drops from 262ms to 190ms and the client-entry discovery walk from
+  242ms to 176ms, retaining 107MB instead of 128MB. Verified output-identical on 1535 files: same import
+  statements from the parser, and no file the pre-filter skips would have been rewritten.
+
+  `CssCompiler` also memoises import resolution for the life of one rebuild, where a miss cost up to 13
+  sequential `exists()` calls repeated per importer (a further 216ms → 190ms).
+
+- 473be34: fix(devkit): bound the `ps` fallback that reads another process's memory
+
+  Where there is no `/proc` (macOS), the dev host reads a process's RSS by shelling out to `ps`, with no
+  timeout. An absent `ps` was already handled — it answers `null`, which callers read as "no new
+  information" — but a stuck one was not, and its only caller awaits it at the end of a 20s settle before
+  committing a builder recycle. A hang there meant the recycle silently never happened.
+
+  Now spawned directly with a 2s kill timer, which is the same treatment the dev-stability harness already
+  needed after `ps` hung under load.
+
+- 068158b: feat(devkit): bound dev-server memory and stop losing watch events
+
+  Two dev-server problems that compounded each other.
+
+  - The builder grew without bound because `Bun.build` retains native bundler arenas that
+    `Bun.gc(true)` never reclaims. It is now recycled once its RSS passes a ceiling derived
+    from the container's cgroup limit, draining in flight work first.
+  - Bun's recursive `fs.watch` reports roughly one path per coalescing window and discards
+    the rest, so concurrent saves went unbuilt. Changes are now resolved against a
+    `SourceMtimeIndex` baseline and events only decide _when_ to look.
+
+- 46a1a4a: fix(devkit): flush all builder ipc through BuilderChannel and isolate the boot build
+
+  `BuilderReply` only covered request responses, so recycle `process.exit` could still
+  drop unflushed events like `css-updated` and leave the backend on a stale bundle. The
+  boot `SsrBaseArtifactBuilder` also stayed in the long-lived watcher and retained most of
+  its idle RSS.
+
+  - Replace `BuilderReply` with `BuilderChannel` (`send` / `emit` / `drain`) so every
+    builder→host message awaits ipc flush before recycle exit.
+  - Run the boot base artifact build in the disposable `buildBatch` worker (`needs: ["base"]`)
+    and keep only the serializable artifact/fonts in the watcher.
+  - Split the idle resource-budget assertion so host+backend stays tight while the builder
+    can swing within its RSS recycle ceiling.
+
+- 90c6597: fix(devkit): answer in-flight builder requests on recycle and flush replies before exit
+
+  Builder RSS recycle (and unexpected exits) left mid-flight `build-route` /
+  `build-csr` promises hanging: the host never tracked correlation ids, and even a
+  clean drain could lose a large `build-route-res` when `process.exit` truncated an
+  unflushed ipc write past the pipe buffer.
+
+  - Track in-flight ids on the host and fail them with a reloadable error when the
+    builder recycles, crashes, or is stopped.
+  - Send replies through `BuilderReply`, which awaits the ipc flush (with a timeout)
+    so recycle drain means "answered", not "truncated".
+
+- aca901d: fix(devkit): keep builder replies matched to the backend that asked for them
+
+  `BuilderRpc` numbers its requests from 1 in each backend _process_, while the builder it
+  talks to outlives the backend. After a restart the two generations collided on id 1: the
+  builder answered the departed backend's request, the dev host relayed it, and the new
+  backend settled its own id 1 with another route's manifest delta — a page rendered against
+  client modules that were never built for it. The answer it was actually waiting for then
+  arrived to an empty pending map and was dropped, discarding the correct build too.
+
+  `BuilderRequestRouter` renumbers ids host-side, so neither the backend nor the builder
+  learns anything changed and a reply whose generation is gone is discarded rather than
+  misdelivered.
+
+- 068158b: fix(cli): make `bun run akan <cmd>` concurrency-safe
+
+  `bun run akan` rebuilds the CLI into a shared `dist/` before every command, so two
+  commands started at once could read a half-written bundle.
+
+- cb895b7: fix(devkit): find created directories on a filesystem with a coarse mtime clock
+
+  `SourceMtimeIndex` finds new files by noticing their directory's mtime moved, which Linux
+  stamps from a coarse clock: 400 back-to-back `mkdir`s left the parent's mtime unmoved 319
+  times on overlayfs and 324 times on ext4, smallest observable step 1ms. macOS APFS
+  (0.042ms) missed none, which is why this only ever showed up on Linux.
+
+  A directory mutated in the same millisecond as the recorded value — but after the walk that
+  recorded it — therefore left no trace, and because its files were never tracked, later edits
+  to them went unreported for the life of the process. Directories whose mtime was still fresh
+  when it was read are now re-walked on the next scan (`dirSettleMs`, 20ms default), and
+  `HmrWatcher` schedules one more scan while any remain unsettled.
+
+- f8a9bc5: perf(devkit): cache tailwind candidate tokens across builds
+
+  The CSS rebuild read the full text of every source file on every save. Phase 2 moved css
+  compilation into a per-generation batch worker, so an in-memory cache is discarded before
+  the next save can use it — the cache goes to disk instead, the same way font subsetting
+  does, which also survives a builder recycle and a dev-host restart.
+
+  Measured on `apps/akan` (556 sources, 26800 candidates): the candidate scan drops from
+  58-60ms to 13-19ms. Note that this is a smaller share of the rebuild than expected — the
+  full CSS rebuild is ~380ms, so the scan was never the dominant cost. Nothing is written
+  when nothing was re-read.
+
+- d973712: perf(cli): keep heavy dependencies out of the long-lived dev processes
+
+  `akan start` holds the CLI entry and the builder watcher for the whole dev session, so an
+  eagerly imported dependency is resident for the whole session too.
+
+  - The dev host reached `@inquirer/prompts` (~24MB) because `runCommands` shares a module
+    with the interactive argument fallbacks. Those now load the prompt stack on first use,
+    which for `akan start` is never.
+  - The builder watcher reached `tailwindcss` and `@tailwindcss/node` (~40MB) through the
+    `frontendBuild` barrel, which re-exports `cssCompiler` and `ssrBaseArtifactBuilder`. That
+    has been dead weight since css compilation moved into the batch worker; the watcher now
+    imports by module path.
+
+  `entryModuleGraph.test.ts` guards both by walking each built entry's chunk closure. The
+  previous check grepped the entry file alone, which cannot see a dependency reached through
+  a shared chunk and so reported both of these as absent.
+
+- 068158b: fix(devkit): pin the dev port and bound the waits that could hang forever
+
+  - `AKAN_DEV_PORT` pins the dev port. It used to derive from an app's index in the `apps/`
+    listing, so adding an app moved a running dev server's port at its next restart.
+  - `BuilderRpc` created request promises with no timeout, and nothing else answers a lost
+    request. Since the builder is recycled routinely, a page request that landed mid
+    route-build left the SSR promise pending forever with nothing to retry. Now bounded by
+    `AKAN_BUILDER_RPC_TIMEOUT_MS` (120s default) with a message naming the likely cause.
+
+- cc3dd40: feat: expose local-dev metadata endpoints for devtools visualization
+
+  Add four JSON endpoints, registered only when `AKAN_PUBLIC_ENV=local` (override with `AKAN_DEVTOOLS`),
+  that describe the running system for an external developer-tools UI:
+
+  - `GET /_akan/constant` — every model's Input/Object/Full/Light/Insight view, scalars, enums, filter
+    query/sort, and derived relation edges.
+  - `GET /_akan/signal` — declared and framework-generated endpoints, slices, internals, and a flattened
+    route table with fully resolved HTTP/WS paths.
+  - `GET /_akan/dictionary` — the merged i18n tree, module kinds, and flattened dotted keys (`?lang=` narrows it).
+  - `GET /_akan/deps` — the DI graph: services, adaptors, signals, uses, middleware, env, roles, and the
+    topological init stages.
+
+  They live in `AkanServer.#createBuiltinRoutes()` next to `/openapi.json`, so they stay off the `/api` prefix
+  and never enter the `serializedSignal` payload shipped to clients. Outside `local` the routes are not
+  registered at all and fall through to the SSR catch-all.
+
+  Supporting changes:
+
+  - `DictionaryRegistry` collects each `makeTrans` root, which was previously closure-private and unreachable
+    from the server.
+  - `DiLifecycle` gains a read-only `modules` accessor and retains disabled-module reasons that were only logged.
+  - `SignalResolver.getScheduleSkipReason` is now public so the reported schedule placement cannot drift from
+    the scheduler's own rules.
+
+  Secrets discipline: secret constant fields report name and type but no `default`/`example`, `env` carries
+  values for `AKAN_PUBLIC_*` only and every other key by name alone, and `uses` are reported as key plus class
+  name — never the instance. `env` inject keys are extracted by scanning the factory source, never by running it.
+
+- 8a2b795: perf(devkit): stop retaining source text in client-entry discovery, and expire its misses
+
+  `GraphClientEntryDiscovery` is created once per builder process, so its caches live for the
+  whole dev session in the watcher.
+
+  - It kept the full text of every file the walk had touched plus a barrel-rewritten copy of
+    each, when the walk only ever asks two things of a file — is it a client entry, and what
+    does it import — both of which were already cached separately under the same key. Those
+    three caches collapse into one holding just the derived facts: measured on `apps/akan`,
+    retention after a full walk drops from 135-142MB to 125-127MB.
+  - `invalidate()` never cleared the file-existence and resolution caches. They are keyed by
+    extension-less path and by `dir\0specifier`, neither of which maps back to a file that was
+    just created, so a negative recorded before a module existed was permanent: adding a new
+    module and importing it left the import unresolved until the next config change or builder
+    recycle. Negative answers are now dropped on any invalidate; positive ones are keyed by a
+    real path and are left alone.
+
+- 068158b: perf(devkit): cache font subsetting across dev-server boots
+
+  `FontOptimizer.optimize()` re-subset every font file on each builder boot even though it
+  already computed a config hash and wrote hashed outputs. It now skips the
+  `fonteditor-core` / `subset-font` work when the expected outputs are present, which also
+  keeps those two packages out of the common path entirely.
+
+- 473be34: fix(devkit): hold page requests during the recycle drain, not only after the builder exits
+
+  A builder asked to recycle drains first — it stays alive finishing its queued work and refuses
+  everything new — and throughout that window the dev host still reported it as `ready`. So a route or CSR
+  request that arrived during the drain was sent, refused by the departing builder, and relayed to the
+  backend as a failure: the same dev error page the request-holding fix was written to remove, in the half
+  of the window it never covered. The hold was unreachable there, because it only runs when the send
+  itself fails.
+
+  The builder host now reports `recycling` for the drain, which `send()` refuses on and which the hold
+  decision treats like a restart. `ready` — the field `onExit` reads to tell a planned exit from a builder
+  that never came up — is deliberately unchanged.
+
+- e5fde3b: fix(devkit): hold page requests while the builder restarts instead of failing them
+
+  A route or CSR request that arrived while the builder was recycling or restarting was answered
+  immediately with `builder is restarting; reload after the builder is ready`. Nothing retried, so the
+  browser tab showed an error for a builder that was seconds from being back — and the builder is recycled
+  routinely, whenever its RSS passes the ceiling.
+
+  Those requests are now held and replayed when the builder reports ready, which is what the idle-suspend
+  path already did for exactly this reason. `BuilderRpc`'s own timeout still bounds the wait, the queue is
+  capped so a builder that never returns cannot grow it, and anything still held when the builder is
+  stopped for good is failed rather than left silent.
+
+- 473be34: fix(devkit): say when a build worker was killed rather than crashed
+
+  The disposable build worker holds the largest transient in the dev tree (~548MB on a mid-size app, over
+  1GB on a large one), so on a small sandbox it is the process the kernel reaches for first. A worker the
+  OOM killer takes exits with code `null` and `SIGKILL`, and the build was reported as `build worker exited
+with code null before reporting a result` — indistinguishable from an ordinary crash, though the two have
+  opposite fixes: find the build error, or raise the memory limit.
+
+  The failure path is unchanged and still safe (that generation goes red, the last-good artifact keeps
+  serving); the message now names the signal, and calls out `SIGKILL` as most often the OOM killer.
+
+- f28466f: fix(server): stop closing the database out from under its own schema setup
+
+  `getStore()` returns a store synchronously while `ensure()` goes on creating tables and indexes, so a
+  shutdown could close the connection mid-setup. The rejection was unhandled — `void store.ensure()` —
+  and surfaced as `RangeError: Cannot use a closed database` blamed on whatever ran next, which read as a
+  flaky test rather than a race at shutdown. Reproduced at 3 failures in 8 runs of the akanjs suite, 0 in
+  10 after the fix.
+
+  All three SQL adaptors (bun:sqlite, libsql, Postgres) now track those setups and let them finish before
+  closing. Every statement `ensure()` runs is `IF NOT EXISTS`, so one cut short is simply redone next boot.
+
+- 51851fa: perf: cut idle/dev-save memory with phase-1 quick wins
+
+  Apply the phase-1 resource plan without architecture changes:
+
+  - Self-arming CSR rebuild — skip the dead CSR artifact until `/__csr` or `?csr=true` first needs it
+    (keeps mobile live-reload working once armed).
+  - Bound RSC worker reload accumulation with threshold/RSS recycle instead of retaining every pages
+    bundle generation.
+  - Split `@akanjs/devkit` into subpath exports and move route/overrides AST validation out of the
+    resident `executors` graph so `typescript` is not pulled into long-lived start processes.
+  - Lazy-load CLI command modules via a command manifest so unused command graphs stay cold.
+
+  Also await async endpoint guards (including in parallel) so `canPass` promises are honored.
+
+- 1c3436f: perf: bound builder memory with RSS recycle and disposable batch workers
+
+  Apply the phase-2 bounded-builder plan so Bun.build retention no longer grows without
+  bound across a long `akan start` session:
+
+  - Report builder RSS after each work item and recycle the builder process when it crosses
+    a ceiling (`AKAN_BUILDER_MAX_RSS_MB`, else cgroup × 0.35, else 1200 MB), only when no
+    build is in flight and the generation is green.
+  - Extract shared `memoryLimit` helpers (also used by the RSC worker) and announce recovered
+    pages/css state after a recycle-triggered boot so a live backend picks up the new
+    `base-artifact.json`.
+  - Move pages/css/csr `Bun.build` work into a disposable `buildBatch` worker that exits per
+    generation (optional `AKAN_BUILD_WORKER_REUSE_COUNT`), keeping the watcher process thin.
+
+- 128e9a3: fix(devkit): survive a container image with no `ps`
+
+  `DevStabilityHarness` shells out to `ps` to find leftover dev processes, and slim images such as
+  `oven/bun` ship without procps, so the spawn threw. It now returns the same `null` it already
+  returns for a `ps` that does not answer in time — "could not look", not "nothing is running".
+  Fixture liveness never depended on it (`process.kill(pid, 0)`), so sweeping still works.
+
+- a5d4a8a: fix: register and correctly invoke `internal(... { process })` queue workers
+
+  `process` internals accepted jobs but never ran them. Three defects:
+
+  - `buildInternal.process` was the only scheduled factory that did not default `enabled: true`, so
+    `SignalResolver.resolveSchedule` skipped it and no worker was ever registered. Placement is now governed by
+    `serverMode`/`operationMode` alone, matching the existing `serverMode: "all"` default.
+  - Registered workers were called with the `AkanJob` rather than the declared `msg` arguments. The job payload is
+    now spread onto the declared args and deserialized against their declared types, so the `exec` signature
+    `(...msgArgs, job)` holds at runtime.
+  - `BullQueue` scoped its worker to queue `<prefix>:<key>` while enqueueing onto queue `<prefix>`, so cluster mode
+    never consumed jobs. Producer and consumer now share one queue per process key.
+
+  `resolveSchedule` also logs when a `process` internal gets no worker on the current server, since the producer is
+  installed regardless of placement.
+
+- 473be34: fix(devkit): stop turning the builder's memory ceiling off on the first page load
+
+  The dev host stops enforcing the builder's RSS ceiling when recycling evidently cannot meet it. The
+  evidence it used was "two over-ceiling reports within 30s of a recycle" — but a builder reports after
+  every build, and one page load builds a route per navigation. On a container-derived ceiling (a 1.2GB
+  sandbox gives the builder ~420MB, against ~247MB per route build) the first page load after a recycle
+  switched the ceiling off for the rest of the session, leaving the builder unbounded on exactly the
+  deployment shape the ceiling exists for.
+
+  It now measures what it always claimed to: when a replacement builder becomes ready, before it has built
+  anything on demand, the host reads its RSS from the OS. That is the floor every future replacement lands
+  on, so a floor already over the ceiling means recycling cannot help — and only that stops enforcement,
+  with the message naming `AKAN_BUILDER_MAX_RSS_MB`. Otherwise the ceiling stands and the existing 30s
+  minimum interval bounds what it costs, now with a one-off warning when the builder keeps crossing back
+  inside that interval.
+
 ## 2.4.0
 
 ### Minor Changes

package/client/csrTypes.ts

@@ -50,6 +50,13 @@ export interface PageConfig {
   rscPatchHeadSafe?: boolean;
   topSafeAreaColor?: string;
   bottomSafeAreaColor?: string;
+  /**
+   * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
+   * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
+   * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
+   * the source without evaluating the module.
+   */
+  devOnly?: boolean;
 }
 
 export interface CsrState {

package/client/frameConfig.ts

@@ -24,6 +24,8 @@ const pageConfigKeys = new Set<keyof PageConfig>([
   "topSafeAreaColor",
   "bottomSafeAreaColor",
 ]);
+
+const buildPageConfigKeys = new Set<keyof PageConfig>(["devOnly"]);
 const transitionTypes = new Set<TransitionType>(["none", "fade", "bottomUp", "stack", "scaleOut"]);
 const ssrRenderModes = new Set<SsrRenderMode>(["stream", "block"]);
 const DEFAULT_BOOLEAN_INSET = 48;
@@ -38,10 +40,13 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   if (!isRecord(config)) throw new Error(`[route-convention] pageConfig in ${routeKey} must be an object.`);
   const pageConfig = config as PageConfig;
   for (const key of Object.keys(pageConfig)) {
-    if (!pageConfigKeys.has(key as keyof PageConfig)) {
+    if (!pageConfigKeys.has(key as keyof PageConfig) && !buildPageConfigKeys.has(key as keyof PageConfig)) {
       throw new Error(`[route-convention] unsupported pageConfig option "${key}" in ${routeKey}`);
     }
   }
+  if (pageConfig.devOnly !== undefined && typeof pageConfig.devOnly !== "boolean") {
+    throw new Error(`[route-convention] pageConfig.devOnly in ${routeKey} must be a boolean.`);
+  }
   if (pageConfig.transition !== undefined && !transitionTypes.has(pageConfig.transition)) {
     throw new Error(`[route-convention] unsupported pageConfig.transition "${pageConfig.transition}" in ${routeKey}`);
   }

package/client/rscNavigation.ts

@@ -1,5 +1,6 @@
 declare global {
   var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+  var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
   var __AKAN_RSC_NAVIGATE__:
     | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void>)
     | undefined;
@@ -9,11 +10,19 @@ export const clearRscNavigationCache = () => {
   globalThis.__AKAN_RSC_CLEAR_CACHE__?.();
 };
 
+/**
+ * True when the page tree currently on screen was replayed from the RSC navigation cache instead of
+ * fetched from the server. Data hydrated out of such a payload can be arbitrarily old, so anything
+ * that must show current values should refetch.
+ */
+export const isRscNavigationFromCache = () => globalThis.__AKAN_RSC_IS_FROM_CACHE__?.() ?? false;
+
 export const navigateRsc = (href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => {
   return globalThis.__AKAN_RSC_NAVIGATE__?.(href, options);
 };
 
 export const useRscNavigation = () => ({
   clearCache: clearRscNavigationCache,
+  isFromCache: isRscNavigationFromCache,
   navigate: navigateRsc,
 });

package/common/index.ts

@@ -54,3 +54,8 @@ export { sleep } from "./sleep";
 export { splitVersion } from "./splitVersion";
 export { getBasePathFromPathname, parseBasePaths } from "./subRoute";
 export type * from "./types";
+export {
+  type WebsocketAuthAckData,
+  type WebsocketAuthRequest,
+  websocketAuthContract,
+} from "./websocketAuth";

package/common/websocketAuth.ts

@@ -0,0 +1,24 @@
+export interface WebsocketAuthRequest {
+  key: string;
+  data: [string | null];
+}
+
+export interface WebsocketAuthAckData {
+  type: "auth";
+  revokedRooms: string[];
+}
+
+/**
+ * Framework-owned websocket auth contract shared by the client and the server dispatcher.
+ * The credential frame carries the raw bearer token; verifying it stays in userland middleware,
+ * so the server only swaps the credential snapshot held on the socket.
+ */
+export const websocketAuthContract = {
+  key: "__auth",
+  makeRequest: (jwt: string | null): WebsocketAuthRequest => ({ key: "__auth", data: [jwt] }),
+  makeAck: (revokedRooms: string[]): WebsocketAuthAckData => ({ type: "auth", revokedRooms }),
+  readJwt: (data: unknown): string | null => {
+    const jwt = Array.isArray(data) ? data[0] : null;
+    return typeof jwt === "string" && jwt.length > 0 ? jwt : null;
+  },
+} as const;

package/fetch/client/fetchClient.ts

@@ -197,6 +197,7 @@ export class FetchClient {
   }
   setJwt(jwt: string | null) {
     this.jwt = jwt;
+    this.ws.setJwt(jwt);
   }
   #makeAuthHeaders(option?: FetchPolicy): Record<string, string> {
     if (option?.token) return { Authorization: `Bearer ${option.token}` };

package/fetch/client/wsClient.ts

@@ -1,5 +1,6 @@
-import { Logger } from "akanjs/common";
+import { Logger, websocketAuthContract } from "akanjs/common";
 import type {
+  WebsocketAuthAck,
   WebsocketMessageData,
   WebsocketPublishData,
   WebsocketReqData,
@@ -39,6 +40,7 @@ export class WsClient {
   #roomSubscribeMap = new Map<string, SubscribeOption>();
   #listenerMap = new Map<string, Set<Listener>>();
   #destroyed = false;
+  #jwt: string | null = null;
   connected = false;
 
   constructor(
@@ -52,6 +54,21 @@ export class WsClient {
     this.ErrorCls = ErrorCls;
   }
 
+  /**
+   * The handshake only carries a same-origin cookie, so clients that hold the token in memory
+   * (native, cross-origin) authenticate with this frame instead. Signing out sends `null`, which
+   * drops the handshake cookie server-side and revokes the rooms it had authorized.
+   */
+  setJwt(jwt: string | null) {
+    if (this.#jwt === jwt) return;
+    this.#jwt = jwt;
+    if (this.#ws?.readyState === WebSocket.OPEN) this.#sendAuth();
+  }
+
+  #sendAuth() {
+    this.#ws?.send(JSON.stringify(websocketAuthContract.makeRequest(this.#jwt)));
+  }
+
   connect() {
     if (this.#ws && this.#ws.readyState !== WebSocket.CLOSED) return;
     this.logger.debug(`Connecting to ${this.url}`);
@@ -68,6 +85,8 @@ export class WsClient {
       this.#reconnectAttempts = 0;
       this.connected = true;
       this.logger.debug(`WebSocket connected`);
+
+      if (this.#jwt) this.#sendAuth();
       this.#roomSubscribeMap.forEach((option) => {
         const data: WebsocketReqData = { key: option.key, data: option.data, subscribe: true };
         this.#ws?.send(JSON.stringify(data));
@@ -97,6 +116,14 @@ export class WsClient {
             this.#handlePubsub(publishData.roomId, publishData.data);
             break;
           }
+          case "auth": {
+            const ack = parsed as WebsocketAuthAck;
+            for (const roomId of ack.revokedRooms) {
+              this.#roomSubscribeMap.delete(roomId);
+              this.logger.warn(`Websocket room ${roomId} is no longer authorized`);
+            }
+            break;
+          }
           default:
             this.logger.warn(`Unknown WebSocket message type: ${type} ${JSON.stringify(parsed)}`);
             break;

package/index.ts

@@ -163,6 +163,12 @@ export interface AppConfigResult {
   docker: DockerConfig;
   defaultDatabaseMode: DatabaseMode;
   routes?: AkanRouteConfig[];
+  /**
+   * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
+   * dependency that ships a `page` folder, an array takes exactly the libs listed, `false` (the default)
+   * syncs nothing and removes what a previous sync created.
+   */
+  syncPageLibs?: string[] | boolean;
   externalLibs: string[];
   barrelImports: string[];
   optimizeImports: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.1-rc.7",
+  "version": "2.4.2-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanServer.ts

@@ -23,6 +23,7 @@ import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
 import { ApiRouter } from "./routing/apiRouter";
+import type { AppWsData } from "./routing/appWsData";
 import type { HttpRoutes, SignalRoutes, WebsocketRoutes } from "./types";
 import type { WebRouter } from "./webRouter";
 
@@ -65,8 +66,8 @@ export interface AkanServerConsoleInfo {
 export class AkanServer {
   status: "stopped" | "initializing" | "initialized" | "starting" | "running" | "stopping" = "stopped";
 
-  #server: Bun.Server<{ createdAt: number } | HmrWsData> | null = null;
-  #wsServer: Bun.Server<{ createdAt: number } | HmrWsData> | null = null;
+  #server: Bun.Server<AppWsData | HmrWsData> | null = null;
+  #wsServer: Bun.Server<AppWsData | HmrWsData> | null = null;
   #prepared: AkanAppPrepared | null = null;
   readonly logger: Logger;
   readonly name: string;
@@ -241,7 +242,7 @@ export class AkanServer {
       }),
       
       data: {},
-    } as Bun.WebSocketHandler<{ createdAt: number } | HmrWsData>;
+    } as Bun.WebSocketHandler<AppWsData | HmrWsData>;
     
     this.#server = Bun.serve({
       idleTimeout: 0,
@@ -270,7 +271,7 @@ export class AkanServer {
           builtinRoutes,
           routeOptions,
           renderEnvRoutes,
-          upgradeAppWs: (req: Request, data: { createdAt: number }) => this.#wsServer?.upgrade(req, { data }) ?? false,
+          upgradeAppWs: (req: Request, data: AppWsData) => this.#wsServer?.upgrade(req, { data }) ?? false,
           webProxyRunner,
         }),
         websocket: websocketHandlers,

package/server/resolver/signal.resolver.ts

@@ -452,6 +452,29 @@ export class SignalResolver {
     return Boolean(req.headers.get("authorization") || req.headers.get("cookie")?.includes("jwt="));
   }
 
+  /**
+   * Re-checks the guards of every room this socket is subscribed to and drops the ones that no
+   * longer pass. Called when the socket's credential changes: a pubsub room is authorized once at
+   * subscribe time, so without this a signed-out socket would keep receiving its old rooms.
+   */
+  static async revalidateWsRooms(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry): Promise<string[]> {
+    const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws);
+    if (!roomCtxMap?.size) return [];
+    const websocket = SignalResolver.#getWebsocket(registry);
+    const revokedRooms: string[] = [];
+    for (const [roomId, roomCtx] of [...roomCtxMap]) {
+      if (await roomCtx.authorize()) continue;
+      ws.unsubscribe(roomId);
+      await Promise.all([...roomCtx.getWebSocketContext().onUnsubscribe.values()].map((handler) => handler()));
+      roomCtxMap.delete(roomId);
+      websocket.leaveRoom(ws, roomId);
+      revokedRooms.push(roomId);
+      SignalResolver.logger.verbose(`WebSocket lost access to room ${roomId}; unsubscribed`);
+    }
+    if (roomCtxMap.size === 0) SignalResolver.#liveWsPubsubRoomCtx.delete(ws);
+    return revokedRooms;
+  }
+
   static async handleWsOpen(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry) {
     await SignalResolver.#getWebsocket(registry).registerSocket(ws);
   }

package/server/routing/apiRouter.ts

@@ -1,11 +1,12 @@
 import { dayjs } from "akanjs/base";
-import type { Logger } from "akanjs/common";
+import { type Logger, websocketAuthContract } from "akanjs/common";
 import type { InjectRegistry } from "akanjs/service";
 import { Exception, type WebsocketReqData } from "akanjs/signal";
 import type { HmrWsData, HmrWsHub } from "../hmr/wsHub";
 import { copyBunRequestFields, type WebProxyRunner } from "../proxy";
 import { SignalResolver } from "../resolver";
 import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types";
+import { AppWsData } from "./appWsData";
 
 /**
  * Minimal render-state view the HMR WS hello message needs.
@@ -30,7 +31,7 @@ export interface ApiRouteInputs {
   routeOptions?: Record<string, SignalRouteOptions>;
   renderEnvRoutes: HttpRoutes;
   /** Upgrades the incoming request into an app-signal WebSocket. */
-  upgradeAppWs: (req: Request, data: { createdAt: number }) => boolean;
+  upgradeAppWs: (req: Request, data: AppWsData) => boolean;
   webProxyRunner?: WebProxyRunner | null;
 }
 
@@ -85,7 +86,7 @@ export class ApiRouter {
     const endpointPaths = new Set([...endpointEntries.map(([path]) => path), ...builtinEntries.map(([path]) => path)]);
     const routeTable = {
       [`${prefix}${websocketPrefix}` as "/api/ws"]: (req) => {
-        const upgraded = upgradeAppWs(req, { createdAt: Date.now() });
+        const upgraded = upgradeAppWs(req, AppWsData.fromRequest(req));
         if (upgraded) return;
         return new Response("Failed to upgrade to WebSocket", { status: 500 });
       },
@@ -138,6 +139,13 @@ export class ApiRouter {
           if (typeof message === "string") {
             const msg = JSON.parse(message) as WebsocketReqData;
             if (!msg.key) throw new Error("Message key is required");
+            if (msg.key === websocketAuthContract.key) {
+
+              AppWsData.applyCredential(AppWsData.of(ws), websocketAuthContract.readJwt(msg.data));
+              const revokedRooms = await SignalResolver.revalidateWsRooms(ws, registry);
+              ws.send(JSON.stringify(websocketAuthContract.makeAck(revokedRooms)));
+              return;
+            }
             const wsRoute = wsRoutes[msg.key];
             if (!wsRoute) throw new Error(`WebSocket route "${msg.key}" is not registered`);
             const eventType =

package/server/routing/appWsData.ts

@@ -0,0 +1,50 @@
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "user-agent"] as const;
+
+/**
+ * Credential snapshot taken at the websocket handshake and carried on `ws.data` for the life of the
+ * socket, so auth middleware and guards can read the caller the same way they read an HTTP request.
+ * Only the credential headers are copied — retaining the whole `Request` would pin it for as long
+ * as the socket stays open.
+ */
+export class AppWsData {
+  static fromRequest(req: Request): AppWsData {
+    const headers = new Headers();
+    for (const key of CREDENTIAL_HEADERS) {
+      const value = req.headers.get(key);
+      if (value) headers.set(key, value);
+    }
+    return new AppWsData(headers);
+  }
+  static of(ws: Bun.ServerWebSocket<unknown>): AppWsData {
+    return ws.data as AppWsData;
+  }
+  /**
+   * Swaps the credential the socket authenticates with. Callers must run this synchronously on the
+   * auth frame: frames arrive in order, so a subscribe sent right after the credential must not be
+   * able to observe the previous one.
+   */
+  static applyCredential(data: AppWsData, jwt: string | null) {
+    if (jwt) data.headers.set("authorization", `Bearer ${jwt}`);
+    else {
+      data.headers.delete("authorization");
+      data.cookies.delete("jwt");
+      const cookie = [...data.cookies].map(([name, value]) => `${name}=${value}`).join("; ");
+      if (cookie) data.headers.set("cookie", cookie);
+      else data.headers.delete("cookie");
+    }
+    data.account = undefined;
+    data.resolvedAuthorization = undefined;
+  }
+  createdAt: number;
+  headers: Headers;
+  cookies: Bun.CookieMap;
+  account?: unknown;
+  /** The `authorization` value `account` was resolved from, so each frame need not re-verify it. */
+  resolvedAuthorization?: string;
+  socketId?: string;
+  constructor(headers: Headers) {
+    this.createdAt = Date.now();
+    this.headers = headers;
+    this.cookies = new Bun.CookieMap(headers.get("cookie") ?? "");
+  }
+}

package/server/rscClient.tsx

@@ -47,6 +47,7 @@ declare global {
     | undefined;
   var __AKAN_RSC_REFRESH__: ((options?: { buildId?: number }) => Promise<void>) | undefined;
   var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+  var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
   var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
   var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
   var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
@@ -299,8 +300,11 @@ let currentRouterState: AkanRouterStateV1 | null = initialRouterState;
 let currentSegmentTree: RscSegmentCacheNode | null = createAkanSegmentCacheTree(initialNode);
 let currentFullNode: RscCacheNode = initialNode;
 let currentCommitKind: "full" | "patch" = "full";
+let currentCommitFromCache = false;
 let navigationSeq = 0;
 
+globalThis.__AKAN_RSC_IS_FROM_CACHE__ = () => currentCommitFromCache;
+
 function rememberCommittedRouteState(node: RscCacheNode): void {
   rscPatchCache.clear();
   if (!node.routerState) return;
@@ -378,6 +382,7 @@ function Root(): ReactNode {
         maxEntries: MAX_RSC_CACHE_ENTRIES,
         startTransition,
         commitThenable: (node) => {
+          currentCommitFromCache = false;
           resetAkanSegmentOutletPatches();
           setThenable(node.thenable);
         },
@@ -397,6 +402,7 @@ function Root(): ReactNode {
     const scrollToTop = options.scrollToTop ?? true;
     try {
       let nextNode = rscCache.get(target);
+      const servedFromCache = !!nextNode;
       if (!nextNode) {
         const cachedPatch = rscPatchCache.get(target);
         if (cachedPatch) {
@@ -425,6 +431,7 @@ function Root(): ReactNode {
                 bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
               })
             ) {
+              currentCommitFromCache = true;
               rememberPatchedRouteState(patchResult.tree, patchResult.patchedNode);
               rememberRscPatchCacheNode(rscPatchCache, cachedPatch, MAX_RSC_CACHE_ENTRIES);
               return;
@@ -449,6 +456,7 @@ function Root(): ReactNode {
               bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
             })
           ) {
+            currentCommitFromCache = false;
             rememberPatchedRouteState(fetched.tree, fetched.patchedNode);
             const patchCacheNode = createRscPatchNavigationCacheNode({
               href: target,
@@ -493,6 +501,7 @@ function Root(): ReactNode {
         maxEntries: MAX_RSC_CACHE_ENTRIES,
         startTransition,
         commitThenable: (node) => {
+          currentCommitFromCache = servedFromCache;
           resetAkanSegmentOutletPatches();
           setThenable(node.thenable);
         },

package/service/predefinedAdaptor/database.adaptor.ts

@@ -1586,6 +1586,41 @@ export class SqlDocumentStore {
       throw new Error(`Invalid database identifier: ${refName}`);
   }
 }
+
+/**
+ * The schema setups `getStore` starts but nobody awaits.
+ *
+ * `getStore` returns a store synchronously while `ensure()` goes on creating tables and indexes, so
+ * the connection could be closed out from under one — a server shutting down, or a test tearing its
+ * fixture down. That surfaced as an unhandled `Cannot use a closed database` blamed on whatever ran
+ * next, which made it look like a flaky test rather than a race at shutdown.
+ *
+ * Every statement `ensure()` runs is `IF NOT EXISTS`, so one cut short is simply redone on the next
+ * boot; a failure *before* the close is still a real problem and still surfaces.
+ */
+class PendingStoreEnsures {
+  readonly #pending = new Set<Promise<void>>();
+  #closed = false;
+
+  track(ensure: Promise<void>): void {
+    const tracked = ensure
+      .catch((error: unknown) => {
+        if (this.#closed) return;
+        throw error;
+      })
+      .finally(() => {
+        this.#pending.delete(tracked);
+      });
+    this.#pending.add(tracked);
+  }
+
+  /** Let them finish against a live connection. Call before closing it. */
+  async settle(): Promise<void> {
+    this.#closed = true;
+    await Promise.allSettled([...this.#pending]);
+  }
+}
+
 export class SqliteDatabase
   extends adapt("sqliteDatabase", ({ env }) => ({
     config: env((env: SqliteEnv) => {
@@ -1617,6 +1652,7 @@ export class SqliteDatabase
   #client!: BunSqliteClient;
   #stores = new Map<string, SqlDocumentStore>();
   #transaction = new AsyncLocalStorage<TransactionContext>();
+  #ensures = new PendingStoreEnsures();
 
   override async onInit() {
     await mkdir(path.dirname(this.config.filePath), { recursive: true });
@@ -1634,6 +1670,7 @@ export class SqliteDatabase
   }
 
   override async onDestroy() {
+    await this.#ensures.settle();
     this.#db?.run("PRAGMA wal_checkpoint(TRUNCATE)");
     await this.#client?.close();
   }
@@ -1647,7 +1684,7 @@ export class SqliteDatabase
     if (existing) return existing;
     const store = new SqlDocumentStore(this, constant, database, schema as DocumentSchema);
     this.#stores.set(database.refName, store);
-    void store.ensure();
+    this.#ensures.track(store.ensure());
     return store;
   }
 
@@ -1724,6 +1761,7 @@ export class LibsqlDatabase
   #client!: LibsqlAkanClient;
   #stores = new Map<string, SqlDocumentStore>();
   #transaction = new AsyncLocalStorage<TransactionContext>();
+  #ensures = new PendingStoreEnsures();
 
   override async onInit() {
     const url = this.config.url ?? "file:local.db";
@@ -1736,6 +1774,7 @@ export class LibsqlDatabase
   }
 
   override async onDestroy() {
+    await this.#ensures.settle();
     await this.#client?.close();
   }
 
@@ -1748,7 +1787,7 @@ export class LibsqlDatabase
     if (existing) return existing;
     const store = new SqlDocumentStore(this, constant, database, schema as DocumentSchema);
     this.#stores.set(database.refName, store);
-    void store.ensure();
+    this.#ensures.track(store.ensure());
     return store;
   }
 
@@ -1808,6 +1847,7 @@ export class PostgresDatabase
   #client!: PostgresAkanClient;
   #stores = new Map<string, SqlDocumentStore>();
   #transaction = new AsyncLocalStorage<TransactionContext>();
+  #ensures = new PendingStoreEnsures();
 
   override async onInit() {
     const { default: postgres } = await import("postgres");
@@ -1827,6 +1867,7 @@ export class PostgresDatabase
   }
 
   override async onDestroy() {
+    await this.#ensures.settle();
     await this.#client?.close();
   }
 
@@ -1839,7 +1880,7 @@ export class PostgresDatabase
     if (existing) return existing;
     const store = new SqlDocumentStore(this, constant, database, schema as DocumentSchema, new PostgresDialect());
     this.#stores.set(database.refName, store);
-    void store.ensure();
+    this.#ensures.track(store.ensure());
     return store;
   }
 

package/signal/signalContext.ts

@@ -125,6 +125,38 @@ export class SignalContext<
       }),
     );
   }
+  /**
+   * Re-checks this context's guards outside of a request, for a websocket room that is already
+   * subscribed. Only global middlewares run: they carry the account resolution this depends on,
+   * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+   */
+  async authorize(): Promise<boolean> {
+    try {
+      await this.#withMiddleware(async () => await this.#checkGuards(), { endpointMiddlewares: false })();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  #withMiddleware(
+    coreExec: () => Promise<unknown>,
+    { endpointMiddlewares = true }: { endpointMiddlewares?: boolean } = {},
+  ): () => Promise<unknown> {
+    const middlewares = [
+      ...this.#middleware.values(),
+      ...(endpointMiddlewares ? (this.endpointInfo.signalOption.middlewares ?? []) : []),
+    ];
+    if (middlewares.length === 0) return coreExec;
+    let next = coreExec;
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+      const MiddlewareCls = middlewares[i];
+      if (!MiddlewareCls) continue;
+      const middleware = new MiddlewareCls();
+      const currentNext = next;
+      next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
+    }
+    return next;
+  }
   async exec() {
     if (!this.trace) return await this.#exec();
     return await runWithTrace(this.trace, async () => {
@@ -137,7 +169,6 @@ export class SignalContext<
   }
   async #exec() {
     if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
-    const endpointMiddlewares = this.endpointInfo.signalOption.middlewares ?? [];
     const coreExec = async () => {
       if (!this.endpointInfo.execFn) throw new Exception.Error("Exec function is not set");
       if (this.trace) await traceSpan("guards", () => this.#checkGuards());
@@ -158,17 +189,7 @@ export class SignalContext<
         async () => await this.endpointInfo.execFn?.call(this.adaptor, ...this.args, ...this.internalArgs),
       );
     };
-    let next = coreExec;
-    if (this.#middleware.size > 0 || endpointMiddlewares.length > 0) {
-      const middlewares = [...this.#middleware.values(), ...endpointMiddlewares];
-      for (let i = middlewares.length - 1; i >= 0; i--) {
-        const MiddlewareCls = middlewares[i];
-        if (!MiddlewareCls) continue;
-        const middleware = new MiddlewareCls();
-        const currentNext = next;
-        next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
-      }
-    }
+    const next = this.#withMiddleware(coreExec);
     const result = this.trace ? await traceSpan("execChain", () => next()) : await next();
     if (this.endpointInfo.type === "pubsub") return;
     if (result instanceof Response) return result;
@@ -340,6 +361,10 @@ export class SignalContext<
     if (this.transport !== "websocket") throw new Error("Transport is not websocket");
     return this.ctx as WebSocketExecutionContext<Appended>;
   }
+  get<T = unknown>(key: string): T | null {
+    if (this.transport === "http") return this.getHttpContext<{ [key: string]: T }>().req[key] ?? null;
+    return this.getWebSocketContext<{ [key: string]: T }>().ws.data[key] ?? null;
+  }
   getRoomId(key: string) {
     if (this.transport !== "websocket") throw new Error("Transport is not websocket");
     else if (this.endpointInfo.type !== "pubsub") throw new Error("Endpoint is not pubsub");

package/signal/types.ts

@@ -140,4 +140,5 @@ export type WebsocketReqData = { key: string; data: unknown[]; subscribe?: boole
 export type WebsocketMessageData = { type: "msg"; key: string; data: object | object[] };
 export type WebsocketSubscribeAck = { type: "sub"; roomId: string; subscribe: boolean };
 export type WebsocketPublishData = { type: "pub"; roomId: string; data: object | object[] };
-export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData;
+export type WebsocketAuthAck = { type: "auth"; revokedRooms: string[] };
+export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData | WebsocketAuthAck;

package/types/client/csrTypes.d.ts

@@ -43,6 +43,13 @@ export interface PageConfig {
     rscPatchHeadSafe?: boolean;
     topSafeAreaColor?: string;
     bottomSafeAreaColor?: string;
+    /**
+     * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
+     * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
+     * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
+     * the source without evaluating the module.
+     */
+    devOnly?: boolean;
 }
 export interface CsrState {
     transition: TransitionType;

package/types/client/rscNavigation.d.ts

@@ -1,17 +1,25 @@
 declare global {
     var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+    var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
     var __AKAN_RSC_NAVIGATE__: ((href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;
     }) => Promise<void>) | undefined;
 }
 export declare const clearRscNavigationCache: () => void;
+/**
+ * True when the page tree currently on screen was replayed from the RSC navigation cache instead of
+ * fetched from the server. Data hydrated out of such a payload can be arbitrarily old, so anything
+ * that must show current values should refetch.
+ */
+export declare const isRscNavigationFromCache: () => boolean;
 export declare const navigateRsc: (href: string, options?: {
     replace?: boolean;
     scrollToTop?: boolean;
 }) => Promise<void> | undefined;
 export declare const useRscNavigation: () => {
     clearCache: () => void;
+    isFromCache: () => boolean;
     navigate: (href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;

package/types/common/index.d.ts

@@ -27,3 +27,4 @@ export { sleep } from "./sleep.d.ts";
 export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths } from "./subRoute.d.ts";
 export type * from "./types.d.ts";
+export { type WebsocketAuthAckData, type WebsocketAuthRequest, websocketAuthContract, } from "./websocketAuth.d.ts";

package/types/common/websocketAuth.d.ts

@@ -0,0 +1,19 @@
+export interface WebsocketAuthRequest {
+    key: string;
+    data: [string | null];
+}
+export interface WebsocketAuthAckData {
+    type: "auth";
+    revokedRooms: string[];
+}
+/**
+ * Framework-owned websocket auth contract shared by the client and the server dispatcher.
+ * The credential frame carries the raw bearer token; verifying it stays in userland middleware,
+ * so the server only swaps the credential snapshot held on the socket.
+ */
+export declare const websocketAuthContract: {
+    readonly key: "__auth";
+    readonly makeRequest: (jwt: string | null) => WebsocketAuthRequest;
+    readonly makeAck: (revokedRooms: string[]) => WebsocketAuthAckData;
+    readonly readJwt: (data: unknown) => string | null;
+};

package/types/fetch/client/wsClient.d.ts

@@ -15,6 +15,12 @@ export declare class WsClient {
     connected: boolean;
     constructor(url: string, ErrorCls?: ErrorConstructor | undefined);
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
+    /**
+     * The handshake only carries a same-origin cookie, so clients that hold the token in memory
+     * (native, cross-origin) authenticate with this frame instead. Signing out sends `null`, which
+     * drops the handshake cookie server-side and revokes the rooms it had authorized.
+     */
+    setJwt(jwt: string | null): void;
     connect(): void;
     destroy(): void;
     on<Data = unknown>(key: string, callback: (data: Data) => void): this;

package/types/index.d.ts

@@ -161,6 +161,12 @@ export interface AppConfigResult {
     docker: DockerConfig;
     defaultDatabaseMode: DatabaseMode;
     routes?: AkanRouteConfig[];
+    /**
+     * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
+     * dependency that ships a `page` folder, an array takes exactly the libs listed, `false` (the default)
+     * syncs nothing and removes what a previous sync created.
+     */
+    syncPageLibs?: string[] | boolean;
     externalLibs: string[];
     barrelImports: string[];
     optimizeImports: string[];

package/types/server/resolver/signal.resolver.d.ts

@@ -30,6 +30,12 @@ export declare class SignalResolver {
         live: LiveRegistry;
         middleware: Map<string, MiddlewareCls>;
     }): SignalRoutes;
+    /**
+     * Re-checks the guards of every room this socket is subscribed to and drops the ones that no
+     * longer pass. Called when the socket's credential changes: a pubsub room is authorized once at
+     * subscribe time, so without this a signed-out socket would keep receiving its old rooms.
+     */
+    static revalidateWsRooms(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry): Promise<string[]>;
     static handleWsOpen(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry): Promise<void>;
     static handleWsClose(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry): Promise<void>;
 }

package/types/server/routing/apiRouter.d.ts

@@ -1,8 +1,9 @@
-import type { Logger } from "akanjs/common";
+import { type Logger } from "akanjs/common";
 import type { InjectRegistry } from "akanjs/service";
 import type { HmrWsHub } from "../hmr/wsHub.d.ts";
 import { type WebProxyRunner } from "../proxy.d.ts";
 import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types.d.ts";
+import { AppWsData } from "./appWsData.d.ts";
 /**
  * Minimal render-state view the HMR WS hello message needs.
  * `LazyHmrController` exposes this shape via `state.buildId` / `state.cssAssets`,
@@ -27,9 +28,7 @@ export interface ApiRouteInputs {
     routeOptions?: Record<string, SignalRouteOptions>;
     renderEnvRoutes: HttpRoutes;
     /** Upgrades the incoming request into an app-signal WebSocket. */
-    upgradeAppWs: (req: Request, data: {
-        createdAt: number;
-    }) => boolean;
+    upgradeAppWs: (req: Request, data: AppWsData) => boolean;
     webProxyRunner?: WebProxyRunner | null;
 }
 export interface WebsocketHandlersInputs {

package/types/server/routing/appWsData.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Credential snapshot taken at the websocket handshake and carried on `ws.data` for the life of the
+ * socket, so auth middleware and guards can read the caller the same way they read an HTTP request.
+ * Only the credential headers are copied — retaining the whole `Request` would pin it for as long
+ * as the socket stays open.
+ */
+export declare class AppWsData {
+    static fromRequest(req: Request): AppWsData;
+    static of(ws: Bun.ServerWebSocket<unknown>): AppWsData;
+    /**
+     * Swaps the credential the socket authenticates with. Callers must run this synchronously on the
+     * auth frame: frames arrive in order, so a subscribe sent right after the credential must not be
+     * able to observe the previous one.
+     */
+    static applyCredential(data: AppWsData, jwt: string | null): void;
+    createdAt: number;
+    headers: Headers;
+    cookies: Bun.CookieMap;
+    account?: unknown;
+    /** The `authorization` value `account` was resolved from, so each frame need not re-verify it. */
+    resolvedAuthorization?: string;
+    socketId?: string;
+    constructor(headers: Headers);
+}

package/types/server/rscClient.d.ts

@@ -13,6 +13,7 @@ declare global {
         buildId?: number;
     }) => Promise<void>) | undefined;
     var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+    var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
     var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
     var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
     var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;

package/types/signal/signalContext.d.ts

@@ -32,6 +32,12 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
     getService<T>(refName: string): T;
     init(): Promise<this>;
+    /**
+     * Re-checks this context's guards outside of a request, for a websocket room that is already
+     * subscribed. Only global middlewares run: they carry the account resolution this depends on,
+     * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+     */
+    authorize(): Promise<boolean>;
     exec(): Promise<Response | undefined>;
     static try(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, fn: () => Promise<Response | undefined>): Promise<Response | undefined>;
     static resolveReturn(value: unknown, { signalContext, returnRef, arrDepth, registry, live, }: {
@@ -47,6 +53,7 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     }): Promise<unknown>;
     getHttpContext<Appended = unknown>(): HttpExecutionContext<Appended>;
     getWebSocketContext<Appended = unknown>(): WebSocketExecutionContext<Appended>;
+    get<T = unknown>(key: string): T | null;
     getRoomId(key: string): string;
     getEnv(): Env;
     getArg<T = unknown>(argName: string): T | undefined;

package/types/signal/types.d.ts

@@ -147,5 +147,9 @@ export type WebsocketPublishData = {
     roomId: string;
     data: object | object[];
 };
-export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData;
+export type WebsocketAuthAck = {
+    type: "auth";
+    revokedRooms: string[];
+};
+export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData | WebsocketAuthAck;
 export {};

package/ui/Model/EditModal.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { clsx, router, usePage } from "akanjs/client";
+import { clsx, isRscNavigationFromCache, router, usePage } from "akanjs/client";
 import { capitalize, deepObjectify, lowerlize } from "akanjs/common";
 import { ConstantRegistry, immerify } from "akanjs/constant";
 import type { ClientEdit, ServerEdit, SliceMeta } from "akanjs/fetch";
@@ -11,6 +11,8 @@ import { AiOutlinePlus, AiOutlineSave } from "react-icons/ai";
 import { Button } from "../Button";
 import { Modal } from "../Modal";
 
+const EDIT_PAYLOAD_MAX_AGE_MS = 60_000;
+
 interface EditModelProps<Full> {
   /** Rendering mode for the edit shell. */
   type?: "modal" | "form" | "empty";
@@ -148,6 +150,7 @@ export default function EditModal<Full extends { id: string }>({
       setModelModal: `set${ModelName}Modal`,
       modelLoading: `${modelName}Loading`,
       modelViewAt: `${modelName}ViewAt`,
+      editModel: `edit${ModelName}`,
       newModel: `new${ModelName}`,
       crystalizeModel: `crystalize${ModelName}`,
       modelObj: `${modelName}Obj`,
@@ -159,10 +162,19 @@ export default function EditModal<Full extends { id: string }>({
     (state: unknown) => (state as { [key: string]: { id: string | null } })[names.modelForm].id,
   );
   const modelFormLoading = storeUse[names.modelFormLoading]() as string | boolean;
+  const modalId = id ?? ((modelEdit as any)?.[names.modelObj] as Full | undefined)?.id ?? undefined;
   const isModalOpen =
     modelModal === (modal ?? "edit") &&
-    (modelFormLoading === false || modelFormLoading === id) &&
-    ((!modelFormId && !id) || id === modelFormId);
+    (modelFormLoading === false || modelFormLoading === modalId) &&
+    ((!modelFormId && !modalId) || modalId === modelFormId);
+  const isEditPayloadStale = useCallback((viewAt?: Date | null) => {
+    if (isRscNavigationFromCache()) return true;
+    return (
+      viewAt instanceof Date &&
+      !Number.isNaN(viewAt.getTime()) &&
+      Date.now() - viewAt.getTime() > EDIT_PAYLOAD_MAX_AGE_MS
+    );
+  }, []);
   useEffect(() => {
     if (!modelEdit) return;
     const refName = (modelEdit as ServerEdit<string, Full>).refName;
@@ -170,15 +182,21 @@ export default function EditModal<Full extends { id: string }>({
     const cnst = ConstantRegistry.getDatabase(modelName);
     const modelRef = cnst.full;
     if (editType === "edit") {
-      const crystal = new modelRef().set((modelEdit as any)[names.modelObj] as Full) as unknown as Full;
+      const modelObj = (modelEdit as any)[names.modelObj] as Full;
+      const viewAt = (modelEdit as any)[names.modelViewAt] as Date;
+      const crystal = new modelRef().set(modelObj) as unknown as Full;
       st.set({
         [names.model]: crystal,
         [names.modelLoading]: false,
         [names.modelForm]: immerify(modelRef, crystal),
         [names.modelFormLoading]: false,
         [names.modelModal]: modal ?? "edit",
-        [names.modelViewAt]: (modelEdit as any)[names.modelViewAt] as Date,
+        [names.modelViewAt]: viewAt,
       });
+      if (isEditPayloadStale(viewAt))
+        void storeDo[names.editModel](modelObj.id, { modal }).catch(() => {
+          st.set({ [names.modelFormLoading]: false });
+        });
     } else {
       
       const crystal = new modelRef().set(modelEdit as Full) as unknown as Full;
@@ -186,7 +204,7 @@ export default function EditModal<Full extends { id: string }>({
     }
     return () => {
     };
-  }, [modelEdit]);
+  }, [modelEdit, isEditPayloadStale]);
 
   const handleCancel = useCallback(() => {
     const modelForm = (st.get() as any)[names.modelForm] as Full;