akanjs 3.0.0-alpha.51 → 3.0.0-alpha.53

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # akanjs
 
+## 2.4.2
+
+### Minor Changes
+
+- 11aa655: feat(constant): remove a relation's target with its owner via `cascade: "remove"`
+
+  A relation field can now take its target down with it: `image: field(File, { cascade: "remove" })`, arrays
+  included. The removal runs through the **target's service**, so the target's own `_postRemove` runs with it —
+  that is how removing a model also deletes the file's stored blob or object, with no extra wiring in the owning
+  module.
+
+  Only a relation accepts the option. A `String`, an `ID`, a scalar, and a nested array each fail while the class
+  is being built, naming the field: none of them points at a document the framework could remove.
+
+  Target services resolve lazily, at removal time, so a cascade adds no boot-order edge between two services and a
+  cascade cycle cannot fail the boot. They resolve _before_ the parent is touched, so a model cascading into a
+  module the app never mounted fails with nothing half-removed.
+
+  Two limits worth knowing. Nothing checks whether another document still references the same target, so declaring
+  `cascade` asserts that the field owns its target exclusively. And query-level removal (`deleteManyByQuery` /
+  `updateManyByQuery`) stamps `removedAt` in one atomic update that fires no hooks and therefore no cascade —
+  remove documents one at a time when they cascade.
+
+- 11aa655: feat(store): invalidate sibling slices on create and refetch them in `Load.Units`
+
+  A model with more than one parent is listed by more than one slice, and a create could only ever be spliced
+  into the slice it was issued from. Creating a `bizDoc` from `bizDocInOrg` left `bizDocListInProject` without
+  it, and an RSC navigation back to that page replayed a cached payload whose server-stamped
+  `bizDocInitAtInProject` still satisfied `Load.Units`' cache check — so the new document stayed invisible until
+  a full reload.
+
+  `create<Model>` and `create<Model>InForm` now stamp a new per-slice `<model>StaleAt<Suffix>` on every slice
+  _except_ the one named by `sliceName`. Whether the new document belongs to a sibling slice is a server-side
+  filter decision, so the siblings are marked for revalidation rather than patched optimistically. `Load.Units`
+  refetches through `refresh<Model><Suffix>` when its slice's `StaleAt` is newer than its `InitAt`, and a
+  completed refresh restamps `InitAt` past `StaleAt` to end the stale state. The refetch is skipped while the
+  list is already loading, which also dedups several `Load.Units` mounted on one slice.
+
+  `Load.Units` also takes a `staleTime` prop, in milliseconds, for age-based revalidation independent of any
+  create: `staleTime={0}` always refetches on mount, `staleTime={30_000}` refetches only when the cached data is
+  older than 30s. Omitting it leaves the component purely invalidation-driven.
+
+  Update and remove are unchanged — they already walk every slice, because a document they touch is one the
+  cached lists can be searched for by id.
+
+- 11aa655: feat(server): add subRoute hosts at runtime with `AKAN_SUB_ROUTE_HOSTS`
+
+  An app resolved a request Host to a basePath through a map fixed at build time — the domains written into
+  `akan.config.ts` plus the generated `<basePath>-<branch>.<serveDomain>`. A platform that mints its hostnames when
+  a project is created cannot write either one into the repo, so its subRoute hosts fell through to the root app.
+
+  `AKAN_SUB_ROUTE_HOSTS` adds to that map at boot, in the same spirit as `AKAN_PUBLIC_BASE_PATHS`:
+
+  ```
+  AKAN_SUB_ROUTE_HOSTS="soft=soft-abc.try.akanjs.com,soft.acme.com;office=office-abc.try.akanjs.com"
+  ```
+
+  Hosts are matched lowercased and without a port, exactly as the built-in ones are. The env mapping is a union with
+  the built one, never a replacement, so a tenant's own domains keep working and removing the env restores the
+  previous behaviour byte for byte.
+
+  A basePath the build does not serve is dropped with a warning rather than honoured — the route tree is a build
+  output, so accepting one would answer every request under it with a 404 and nothing to explain why. A malformed
+  entry is skipped the same way: the value is rendered by a deployment platform, and one bad character must not turn
+  into a boot loop across every pod.
+
+  `x-base-path` is now checked against the basePaths the build serves before it is trusted, matching the check
+  `getBasePathFromPathname` already applied to it. An unrecognised value falls through to host matching instead of
+  selecting a basePath that resolves to nothing.
+
+- 25d5b15: feat(devkit): sync lib `page` trees into apps and honor `pageConfig.devOnly`
+
+  Apps can opt in with `syncPageLibs` (`true` / lib list) so `akan sync` links each lib's routes under
+  `page/(libs)/(<lib>)` — once per basePath when the app has subRoutes. The link is generated and
+  gitignored; the lib source stays the edit target. Collision on the resolved route pattern is a
+  sync-time error.
+
+  `pageConfig.devOnly: true` (literal only) keeps a route out of `akan build` while `akan start` still
+  serves it. On a `_layout` it excludes the whole subtree. Symlink-aware file ops avoid wiping a synced
+  lib when cleaning an app link, and dangling lib links no longer break `getApps`.
+
+- 25d5b15: feat(signal): refresh websocket credentials in-session and re-check pubsub rooms
+
+  Handshake credentials now live on `AppWsData` (headers/cookies only). Clients that hold the token in
+  memory send it with `fetch.setJwt(...)`, which forwards an `__auth` frame; the server swaps the
+  snapshot synchronously and re-runs each subscribed room's guards, unsubscribing the ones that fail.
+
+  Guards should read the caller with `context.get("account")` instead of branching on HTTP vs websocket
+  transport. Slice-level guards still only wrap generated query/mutation endpoints — a pubsub endpoint
+  needs its own `guards` if the room itself must be protected.
+
+### Patch Changes
+
+- 6d58c7e: add search feature for sqlit database with fts5
+- 25d5b15: fix(ui): refresh EditModal when the hydrated edit payload is stale
+
+  RSC navigation can replay a cached page tree, and an edit shell hydrated from that payload can show
+  arbitrarily old form data. EditModal now treats a cache replay (or a `modelViewAt` older than 60s) as
+  stale and refetches via `edit<Model>` while keeping the modal open on the last known id.
+
+- 42cf7a2: Normalize unsendable relayed WebSocket close codes to 1001 so Bun's global client WebSocket.close no longer throws InvalidAccessError at the gateway's client-to-upstream relay when a peer disappears without a close frame (code 1006). The upstream-to-client relay applies the same normalization defensively.
+- 04cb46d: Allow the documented wsConnect export during source validation for root layouts, including base-path and grouped root boundaries, while continuing to reject it on nested layouts.
+
 ## 2.4.1
 
 ### Patch Changes

package/package.json

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

package/server/akanApp.ts

@@ -45,6 +45,19 @@ type GatewayUpstream = {
   ws?: Extract<AkanUpstream, { type: "tcp" }>;
 };
 
+/**
+ * Received-only close codes cannot be sent in a close frame. The gateway deliberately normalizes
+ * every unsendable code, including semantically distinct 1005 and 1006 events, to 1001 in both
+ * relay directions. In particular, Bun's global client `WebSocket.close()` throws an
+ * InvalidAccessError for these codes at the client-to-upstream relay; normalization at the
+ * upstream-to-client `Bun.ServerWebSocket.close()` relay is defensive and keeps behavior symmetric.
+ */
+const relayableCloseCode = (code: number): number => {
+  if (code >= 3000 && code <= 4999) return code;
+  if (code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006) return code;
+  return 1001;
+};
+
 /** Options for the Akan gateway that launches child server replicas and listens for traffic. */
 export interface AkanAppOptions {
   replica?: number | string;
@@ -602,9 +615,7 @@ export class AkanApp {
       if (result === 0) upstream.close();
     });
     upstream.addEventListener("close", (event) => {
-      const code = AkanApp.#sendableCloseCode(event.code);
-      if (code === undefined) ws.close();
-      else ws.close(code, event.reason);
+      ws.close(relayableCloseCode(event.code), event.reason);
     });
     upstream.addEventListener("error", () => ws.close(1011, "upstream websocket error"));
     Object.assign(ws.data, { pending });
@@ -625,15 +636,8 @@ export class AkanApp {
     else ws.data.pending?.push(payload as string | ArrayBuffer);
   }
 
-  static #sendableCloseCode(code: number): number | undefined {
-    const sendable = (code >= 1000 && code <= 1014 && (code < 1004 || code > 1006)) || (code >= 3000 && code <= 4999);
-    return sendable ? code : undefined;
-  }
-
   #handleWsClose(ws: Bun.ServerWebSocket<GatewayWsData>, code: number, reason: string) {
-    const upstreamCode = AkanApp.#sendableCloseCode(code);
-    if (upstreamCode === undefined) ws.data.upstream.close();
-    else ws.data.upstream.close(upstreamCode, reason);
+    ws.data.upstream.close(relayableCloseCode(code), reason);
     const child = this.#children.get(ws.data.childIdx);
     if (child) child.metrics.activeWebSockets = Math.max(0, (child.metrics.activeWebSockets ?? 1) - 1);
   }

package/server/routeTreeBuilder.ts

@@ -191,6 +191,7 @@ export class RouteTreeBuilder {
     parentLayouts: RouteRender[] = [],
     parentPaths: string[] = [],
     parentHead?: ResolveHead,
+    parentOverrides: RouteRender[] = [],
   ): PathRoute[] {
     const parentPath = parentPaths.filter((p) => p !== "/").join("");
     const currentPathSegment = /^\/\(.*\)$/.test(route.path) ? "" : route.path;
@@ -201,8 +202,10 @@ export class RouteTreeBuilder {
     const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
 
     const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
-    const renderRootLayouts = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderLayouts = [...parentLayouts, ...currentOverrideRenders, ...(currentLayout ? [currentLayout] : [])];
+    const overrideRenders = [...parentOverrides, ...currentOverrideRenders];
+    const rootLayoutStack = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
+    const renderRootLayouts = [...overrideRenders, ...rootLayoutStack];
+    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
     if (route.renderLayout) {
       this.#fallbackRoutes.push({
         path: routePath,
@@ -213,11 +216,10 @@ export class RouteTreeBuilder {
     }
     const routeHead = RouteTreeBuilder.#composeHeadResolvers(route.renderLayout?.resolveHead, parentHead);
     const pageRenderRootLayouts =
-      route.pageIncludesOwnLayout === false && currentRootLayout ? parentRootLayouts : renderRootLayouts;
-    const pageRenderLayouts =
-      route.pageIncludesOwnLayout === false && currentLayout
-        ? [...parentLayouts, ...currentOverrideRenders]
-        : renderLayouts;
+      route.pageIncludesOwnLayout === false && currentRootLayout
+        ? [...overrideRenders, ...parentRootLayouts]
+        : renderRootLayouts;
+    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
     const pageHead = route.pageIncludesOwnLayout === false ? parentHead : routeHead;
     return [
       ...(route.renderPage
@@ -236,7 +238,7 @@ export class RouteTreeBuilder {
         : []),
       ...(route.children.size
         ? [...route.children.values()].flatMap((child) =>
-            this.#getPathRoutes(child, renderRootLayouts, renderLayouts, pathSegments, routeHead),
+            this.#getPathRoutes(child, rootLayoutStack, renderLayouts, pathSegments, routeHead, overrideRenders),
           )
         : []),
     ];

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -48,7 +48,6 @@ export interface AgentWireTool {
   name: string;
   description?: string;
   parameters?: Record<string, unknown>;
-  effect?: string;
   needsConfirm?: boolean;
 }
 

package/store/agent/StoreSurfaceSource.ts

@@ -56,7 +56,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["path"],
         additionalProperties: false,
       },
-      effect: "state",
       
       guard: (args) =>
         typeof args.path === "string" && args.path.startsWith("/") && !args.path.startsWith("//")
@@ -83,7 +82,6 @@ export class StoreSurfaceSource implements SurfaceSource {
       description:
         "Go back to the previous page in this session's history. Use it to undo a navigation; use navigate for a path.",
       parameters: { type: "object", properties: {}, additionalProperties: false },
-      effect: "state",
       
       guard: () => (router.canGoBack() ? true : "There is no previous page in this session's history."),
       run: async () => {
@@ -112,7 +110,7 @@ export class StoreSurfaceSource implements SurfaceSource {
         },
         additionalProperties: false,
       },
-      effect: "query",
+      settle: false,
       run: (args) => {
         const root = StoreSurfaceSource.#zoneRoot(viewKey);
         const section = typeof args.section === "string" ? args.section.trim() : "";
@@ -149,7 +147,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["target"],
         additionalProperties: false,
       },
-      effect: "state",
       run: (args) => {
         const name = typeof args.target === "string" ? args.target.trim() : "";
         if (!name) throw new Error("highlight needs a target.");
@@ -182,7 +179,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["key"],
         additionalProperties: false,
       },
-      effect: "state",
       run: (args: Record<string, unknown>) => {
         this.#bridge ??= AgentBridge.of();
         return this.#bridge.read(String(args.key), viewKey);

package/store/agentic/AgentValue.ts

@@ -0,0 +1,112 @@
+import {
+  type CLIENT_VALUE,
+  type Cls,
+  type Dayjs,
+  dayjs,
+  type EnumInstance,
+  type FIELD_META,
+  type GetStateObject,
+  isEnum,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+  type UnCls,
+} from "akanjs/base";
+import { type ConstantModelRef, type MaskModel, mask, maskFieldsOf } from "akanjs/constant";
+
+type AgentSingleType = typeof PrimitiveScalar | EnumInstance<string, any> | ConstantModelRef;
+
+/** What a readable declaration names its value as. One level of array, because a published value is one JSON shape. */
+export type AgentFieldType = AgentSingleType | AgentSingleType[];
+
+/**
+ * A model class resolves to its state object rather than its instance type, so a component may hand over either
+ * the hydrated document or the plain data copied out of one — masking reads the model that was named, not the
+ * class the value still carries.
+ */
+export type AgentValueOf<T> = T extends readonly (infer F)[]
+  ? AgentValueOf<F>[]
+  : T extends { refName: "Any" }
+    ? unknown
+    : T extends EnumInstance<string, infer V>
+      ? V
+      : T extends DateConstructor
+        ? Dayjs | Date | string
+        : T extends { [FIELD_META]: unknown }
+          ? GetStateObject<UnCls<T>>
+          : T extends { [CLIENT_VALUE]: infer V }
+            ? V
+            : unknown;
+
+type ValueKind = "any" | "date" | "scalar" | "enum" | "model";
+
+/**
+ * Turns a declared type into what an agent may read of a value of that type.
+ *
+ * The type is the whole declaration: it typechecks what the component hands over, and it decides how the value is
+ * rendered — a model class masks by that model, a `Date` leaves as an ISO string, a scalar passes. `Any` is the
+ * escape hatch and passes the value untouched, so a payload nobody modeled stays publishable and the caller owns
+ * whether it is JSON and whether it is worth its tokens.
+ */
+export class AgentValue {
+  static serialize(type: AgentFieldType, value: unknown): unknown {
+    const single = Array.isArray(type) ? type[0] : type;
+    if (Array.isArray(type) && Array.isArray(value)) return value.map((item) => AgentValue.#one(single, item));
+    return AgentValue.#one(single, value);
+  }
+
+  /**
+   * Reports an unreadable type the way `st.tool` reports an undescribable argument — on the console, and the
+   * declaration goes unpublished. Throwing would cost the route its server render over an agent-tooling mistake.
+   */
+  static publishable(owner: string, type: AgentFieldType): boolean {
+    try {
+      AgentValue.#kindOf(Array.isArray(type) ? type[0] : type);
+      return true;
+    } catch (error) {
+      console.error(`${owner} is not published: its type is ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+
+  static #one(type: AgentSingleType, value: unknown): unknown {
+    if (value === null || value === undefined) return value;
+    switch (AgentValue.#kindOf(type)) {
+      case "date": {
+        const parsed = dayjs(value as string | number | Date);
+        return parsed.isValid() ? parsed.toISOString() : null;
+      }
+      case "model":
+        return mask(type as MaskModel, value);
+      default:
+        return value;
+    }
+  }
+
+  static #kindOf(type: AgentSingleType): ValueKind {
+    if (isEnum(type as Cls)) return "enum";
+    if (PrimitiveRegistry.has(type as unknown as Cls)) {
+      const refName = PrimitiveRegistry.getName(type as typeof PrimitiveScalar);
+      switch (refName) {
+        case "Any":
+          return "any";
+        case "Date":
+          return "date";
+        case "ID":
+        case "String":
+        case "Int":
+        case "Float":
+        case "Boolean":
+          return "scalar";
+        default:
+          throw new Error(`the scalar ${refName}, which an agent cannot read.`);
+      }
+    }
+    if (maskFieldsOf(type as MaskModel)) return "model";
+    throw new Error(`${AgentValue.#typeName(type)}, and a readable value is a scalar, an enum, a model, or Any.`);
+  }
+
+  static #typeName(type: AgentSingleType): string {
+    const named = type as { name?: string } | null | undefined;
+    return named?.name ? `the type ${named.name}` : `${String(type)}`;
+  }
+}

package/store/agentic/StExposeBuilder.ts

@@ -0,0 +1,47 @@
+import { useAgentResource } from "../../vendor/use-agentic";
+
+import { useRef } from "../hooks";
+import { type AgentFieldType, AgentValue, type AgentValueOf } from "./AgentValue";
+
+export interface StExposeMeta {
+  /** `false` keeps the key out of post-call diff reports — for values that change on their own every second. */
+  report?: boolean;
+}
+
+/**
+ * A read-only value past its description, waiting for the value itself. `.value()` is the one hook.
+ *
+ * The declared type is what makes the read safe: it typechecks what the component hands over and it decides how
+ * the value is rendered, so a model's `hidden` and `secret` fields are stripped by the model that was named
+ * rather than by whatever class the value still happens to carry.
+ */
+export class StExposeBuilder<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #desc: string;
+  readonly #meta: StExposeMeta;
+
+  constructor(name: string | null, type: T, desc: string, meta: StExposeMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#desc = desc;
+    this.#meta = meta;
+  }
+
+  /**
+   * A thunk is read when the agent reads, which is the difference that matters for a value assembled out of a ref
+   * the children fill in after this render — computing it here would publish whatever was there before they ran.
+   */
+  value(value: AgentValueOf<T> | (() => AgentValueOf<T>) | null | undefined): void {
+    const declared = useRef<{ name: string | null } | null>(null);
+    declared.current ??= {
+      name: this.#name && AgentValue.publishable(`st.expose("${this.#name}")`, this.#type) ? this.#name : null,
+    };
+    useAgentResource(declared.current.name, value, {
+      description: this.#desc,
+      report: this.#meta.report,
+      serialize: (current) =>
+        AgentValue.serialize(this.#type, typeof current === "function" ? (current as () => unknown)() : current),
+    });
+  }
+}

package/store/agentic/StExposeDraft.ts

@@ -0,0 +1,24 @@
+import type { AgentFieldType } from "./AgentValue";
+import { StExposeBuilder, type StExposeMeta } from "./StExposeBuilder";
+
+/**
+ * A readable value before it has said what it is: `st.expose("x", ID).desc("…")`.
+ *
+ * A falsy name declares nothing and publishes nothing, so a component whose publication is conditional keeps a
+ * constant hook count instead of branching around the chain.
+ */
+export class StExposeDraft<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #meta: StExposeMeta;
+
+  constructor(name: string | null, type: T, meta: StExposeMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#meta = meta;
+  }
+
+  desc(text: string): StExposeBuilder<T> {
+    return new StExposeBuilder(this.#name, this.#type, text, this.#meta);
+  }
+}

package/store/agentic/StStateBuilder.ts

@@ -0,0 +1,85 @@
+import { capitalize } from "akanjs/common";
+import type { ParamFieldType } from "akanjs/constant";
+import type { Dispatch, SetStateAction } from "react";
+import { type JsonSchema, useAgentState } from "../../vendor/use-agentic";
+
+import { useRef } from "../hooks";
+import { type AgentFieldType, AgentValue, type AgentValueOf } from "./AgentValue";
+import { StToolBuilder } from "./StToolBuilder";
+
+export interface StStateMeta {
+  /** `false` keeps the key out of post-call diff reports — for values that change on their own every second. */
+  report?: boolean;
+  /** Publishes a `set<Name>` tool writing the type this state declares. Read-only without it. */
+  set?: boolean;
+}
+
+interface StStateDeclaration {
+  name: string | null;
+  set: { schema: JsonSchema; type: ParamFieldType } | null;
+}
+
+/**
+ * Local state past its description, waiting for its initial value. `.init()` is the one hook and returns what
+ * `useState` returns.
+ *
+ * The declared type does both halves: it renders the read, and — with `set` — it is the schema of the setter tool
+ * an agent writes through. A type nothing can describe costs the write, not the read and not the render.
+ */
+export class StStateBuilder<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #desc: string;
+  readonly #meta: StStateMeta;
+
+  constructor(name: string | null, type: T, desc: string, meta: StStateMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#desc = desc;
+    this.#meta = meta;
+  }
+
+  init(
+    initial: AgentValueOf<T> | (() => AgentValueOf<T>),
+  ): [AgentValueOf<T>, Dispatch<SetStateAction<AgentValueOf<T>>>];
+  init(
+    initial: AgentValueOf<T> | null | (() => AgentValueOf<T> | null),
+  ): [AgentValueOf<T> | null, Dispatch<SetStateAction<AgentValueOf<T> | null>>];
+
+  init(initial: AgentValueOf<T> | null | (() => AgentValueOf<T> | null)): unknown {
+    type Value = AgentValueOf<T> | null;
+    const name = this.#name;
+    const type = this.#type;
+    const declared = useRef<StStateDeclaration | null>(null);
+    declared.current ??= {
+      name: name && AgentValue.publishable(`st.useState("${name}")`, type) ? name : null,
+      set: name && this.#meta.set ? StStateBuilder.#writable(name, type) : null,
+    };
+    const { set } = declared.current;
+    return useAgentState<Value>(declared.current.name, initial, {
+      description: this.#desc,
+      report: this.#meta.report,
+      serialize: (value) => AgentValue.serialize(type, value),
+      ...(set
+        ? {
+            set: set.schema,
+            parse: (value) =>
+              StToolBuilder.checkedValue(`set${capitalize(name ?? "")}`, "value", set.type, value) as Value,
+          }
+        : {}),
+    });
+  }
+
+  /** A `set` an agent could only call wrong leaves the key readable — the same trade `st.tool`'s `.arg` makes. */
+  static #writable(name: string, type: AgentFieldType): StStateDeclaration["set"] {
+    const scalar = type as unknown as ParamFieldType;
+    try {
+      return { schema: StToolBuilder.schemaOf(scalar), type: scalar };
+    } catch (error) {
+      console.error(
+        `st.useState("${name}") stays read-only: writing ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return null;
+    }
+  }
+}

package/store/agentic/StStateDraft.ts

@@ -0,0 +1,23 @@
+import type { AgentFieldType } from "./AgentValue";
+import { StStateBuilder, type StStateMeta } from "./StStateBuilder";
+
+/**
+ * Local state before it has said what it is: `st.useState("tab", String, { set: true }).desc("…")`.
+ *
+ * A falsy name keeps the state and publishes nothing, so a conditional surface never changes the hook count.
+ */
+export class StStateDraft<T extends AgentFieldType> {
+  readonly #name: string | null;
+  readonly #type: T;
+  readonly #meta: StStateMeta;
+
+  constructor(name: string | null, type: T, meta: StStateMeta = {}) {
+    this.#name = name;
+    this.#type = type;
+    this.#meta = meta;
+  }
+
+  desc(text: string): StStateBuilder<T> {
+    return new StStateBuilder(this.#name, this.#type, text, this.#meta);
+  }
+}