akanjs 3.0.0-alpha.24 → 3.0.0-alpha.26

package/client/clientRuntime.ts

@@ -47,6 +47,8 @@ type RuntimeFetch = typeof globalThis.fetch & {
   serializedSignal: Record<string, unknown>;
   setJwt: (jwt: string | null) => void;
   slice: Record<string, SliceMeta>;
+  /** Sort keys per model refName, registered from each serialized signal's filter. */
+  sortKeyMap?: Map<string, string[]>;
   ws: RuntimeWs;
   [key: string]: unknown;
 };

package/dictionary/base.dictionary.ts

@@ -89,6 +89,11 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     removeMsg: ["Are you sure to remove?", "정말로 삭제하시겠습니까?"],
     confirmMsg: ["Are you sure to {actionType}", "진행하시겠습니까? ({actionType})"],
     perPage: ["/page", "/페이지"],
+    refresh: ["Refresh", "새로고침"],
+    cardView: ["Card view", "카드 보기"],
+    tableView: ["Table view", "표 보기"],
+    exportCsv: ["Export CSV", "CSV 내보내기"],
+    exportJson: ["Export JSON", "JSON 내보내기"],
     actions: ["Actions", "작업"],
     new: ["New", "신규"],
     edit: ["Edit", "수정"],

package/package.json

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

package/signal/serializer/fetch.serializer.ts

@@ -1,6 +1,7 @@
 import { type Cls, ENDPOINT_META, PrimitiveRegistry, type PrimitiveScalar, SLICE_META } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { ConstantRegistry, type ConstantType } from "akanjs/constant";
+import { getFilterMeta } from "akanjs/document";
 import type { LiveRegistry } from "akanjs/service";
 import type {
   ArgInfo,
@@ -90,9 +91,12 @@ export class FetchSerializer {
     for (const [key, endpointInfo] of Object.entries(endpointMeta)) {
       endpoint[key] = FetchSerializer.#serializeEndpoint(endpointInfo);
     }
+
+    const sortKeys = Object.keys(getFilterMeta(sliceCls.srv.db.filter, { allowEmpty: true })?.sort ?? {});
     return {
       ...(prefix ? { prefix } : {}),
       ...(Object.keys(slice).length ? { slice } : {}),
+      ...(sortKeys.length ? { filter: { filter: {}, sortKeys } } : {}),
       ...(sliceCls.getGuards.filter((g) => g.name !== "None").length
         ? { getGuards: sliceCls.getGuards.map((g) => g.name) }
         : {}),

package/store/agent/AgentBridge.ts

@@ -1,147 +1,67 @@
 import { DataList } from "akanjs/base";
-import { Translator } from "akanjs/client";
-import { parseAkanI18nEnv } from "akanjs/common";
 import { ConstantRegistry, type MaskModel, mask } from "akanjs/constant";
-import { FetchClient } from "akanjs/fetch";
-import type { AgentRefusal, JsonSchema, SerializedArg, SerializedSignal } from "akanjs/signal";
-
-import { JsonSchemaBuilder } from "../../signal/schema/JsonSchemaBuilder";
+import type { AgentRefusal } from "akanjs/signal";
 import type { StoreInstance } from "../storeInstance";
 import { StoreRegistry } from "../storeRegistry";
-import type { AgentVisibility } from "./AgentVisibility";
 import { StoreCatalogue } from "./StoreCatalogue";
-import type { SerializedStore, SerializedStoreAction, SerializedStoreState, StoreActionEffect } from "./types";
-
-export interface AgentTool {
-  name: string;
-  title?: string;
-  description?: string;
-  /** One flat named object, the shape MCP publishes. The bridge maps it onto the action's positional parameters. */
-  inputSchema: JsonSchema;
-  effect: StoreActionEffect;
-}
-
-/** One call the agent made, in the order it made them. */
-export interface AgentCall {
-  name: string;
-  args: Record<string, unknown>;
-  at: Date;
-  error?: string;
-}
-
-export interface AgentBridgeOptions {
-  /** Resolves a dictionary key to its text. Defaults to the seeded `Translator` in the active locale. */
-  resolveDescription?: (key: string) => string | undefined;
-}
+import type { SerializedStoreState } from "./types";
 
 /**
- * What an in-page agent may do to the app the user is looking at.
+ * What an in-page agent may read out of the store the user is looking at.
  *
- * Every call goes through `st.do`, which is the same single dispatch point a click goes through — so the agent
- * cannot reach past what the UI already lets this user do, the app re-renders from the write, and the user watches
- * the result rather than being told about it. That is why the exposure default here is the opposite of the MCP
- * catalogue's: an external agent's `tools/list` is an attack surface built out of names the operator never chose to
- * publish, while this one is the user's own session, under their own credential, with them watching.
+ * Reads only. Driving the app is a component's declaration to make: `st.tool` binds a name and a schema to the
+ * same handler the control on screen calls, so what an agent can do is what the screen offers the user and nothing
+ * else. A store method that no component declared is not a lever this screen has — publishing one made the surface
+ * the bundle rather than the screen, and gave the model levers whose effect it could not see.
  *
- * It is deliberately not an agent. There is no model, no provider, and no key here — an app wires whichever it uses
- * to `tools`, `call`, and `read`. The framework's half is the catalogue, the argument checking, the masking, and the
- * transcript; the conversation is the app's.
+ * A key is readable while a mounted component subscribes it through `st.use` / `st.sel` / `st.ref`, and its value
+ * is masked by the model that key declares. Masking is not optional even though the data mostly came from the
+ * server already masked: `<model>Form` holds what the *user* typed, credentials included, and an in-page agent
+ * ships what it reads to a remote model. The mask is by the declared model rather than by the value's class,
+ * because `immerify` copies a form into a plain object and the class is gone by the time anyone can ask.
  */
 export class AgentBridge {
   readonly refusals: AgentRefusal[];
 
   readonly #instance: StoreInstance;
-  readonly #store: SerializedStore;
-  readonly #options: AgentBridgeOptions;
-  readonly #schema = new JsonSchemaBuilder({ refPrefix: "#/$defs/" });
-  readonly #byName = new Map<string, SerializedStoreAction>();
-  readonly #calls: AgentCall[] = [];
-  readonly #visibility: AgentVisibility;
-  readonly #allTools: AgentTool[];
-  readonly #liveTools = new Map<string, { signature: string; tools: AgentTool[] }>();
+  readonly #state: { [key: string]: SerializedStoreState };
 
-  /**
-   * The bridge for the app running in this process: the one store every `st.do` goes through, and every signal any
-   * client has applied. An app needs no arguments to reach its own agent surface.
-   */
-  static of(options: AgentBridgeOptions = {}) {
-    return new AgentBridge(StoreRegistry.instance, FetchClient.sharedSerializedSignal, options);
+  /** The bridge for the app running in this process: the one store every `st.use` goes through. */
+  static of() {
+    return new AgentBridge(StoreRegistry.instance);
   }
 
-  constructor(
-    instance: StoreInstance,
-    serializedSignal: Record<string, SerializedSignal>,
-    options: AgentBridgeOptions = {},
-  ) {
+  constructor(instance: StoreInstance) {
     this.#instance = instance;
-    this.#options = options;
-    const catalogue = new StoreCatalogue(instance, serializedSignal);
-    this.#store = catalogue.store;
+    const catalogue = new StoreCatalogue(instance);
+    this.#state = catalogue.state;
     this.refusals = catalogue.refusals;
-    this.#visibility = catalogue.visibility;
-    for (const [name, action] of Object.entries(this.#store.action)) this.#byName.set(name, action);
-    this.#allTools = Object.entries(this.#store.action).map(([name, action]) => this.#tool(name, action));
-  }
-
-  /**
-   * The catalogued actions of the stores the rendered screen is reading right now — the live view, recomputed as
-   * components mount and unmount. Global exposure was the first cut's behavior and it published levers the screen
-   * does not respond to; the screen's own subscriptions are the honest boundary.
-   */
-  get tools(): AgentTool[] {
-    return this.toolsFor("");
-  }
-
-  /** The live view one zone session reads: owners counted from the keys that zone's own subtree subscribes. */
-  toolsFor(viewKey: string): AgentTool[] {
-    const live = this.#liveOwners(viewKey);
-    const signature = [...live].sort().join(",");
-    const cached = this.#liveTools.get(viewKey);
-    if (cached && cached.signature === signature) return cached.tools;
-    const tools = this.#allTools.filter((tool) => this.#ownerLive(tool.name, live));
-    this.#liveTools.set(viewKey, { signature, tools });
-    return tools;
-  }
-
-  get visibility(): AgentVisibility {
-    return this.#visibility;
-  }
-
-  #liveOwners(viewKey = "") {
-    return this.#visibility.liveOwners(this.#instance.liveKeysIn(viewKey));
-  }
-
-  #ownerLive(name: string, live: ReadonlySet<string>) {
-    const owner = this.#instance.actionOwners.get(name)?.refName;
-    return !owner || live.has(owner);
   }
 
   get state(): { [key: string]: SerializedStoreState } {
-    return this.#store.state;
-  }
-
-  get transcript(): readonly AgentCall[] {
-    return this.#calls;
+    return this.#state;
   }
 
   subscribe(listener: () => void) {
     return this.#instance.subscribe(listener);
   }
 
+  /** The keys one view may read right now: subscribed by a mounted component and catalogued. */
+  readableKeys(viewKey = ""): string[] {
+    return [...this.#instance.liveKeysIn(viewKey).keys()].filter((key) => !!this.#state[key]).sort();
+  }
+
   /**
    * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
    *
-   * Masking is not optional here even though the data mostly came from the server already masked: `<model>Form`
-   * holds what the *user* typed, credentials included, and an in-page agent ships what it reads to a remote model.
-   * The mask is by the declared model rather than by the value's class, because `immerify` copies a form into a
-   * plain object and the class is gone by the time anyone can ask.
+   * The key itself has to be one the screen reads, not merely one its store owns: a component subscribing
+   * `userList` says the screen shows a user list, and says nothing about `userForm` sitting in the same store.
    */
   read(key: string, viewKey = ""): unknown {
-    const entry = this.#store.state[key];
+    const entry = this.#state[key];
     if (!entry) throw new Error(`Unknown state key: ${key}`);
-    const owner = this.#visibility.stateOwner(key);
-    if (owner && !this.#liveOwners(viewKey).has(owner))
-      throw new Error(`State key "${key}" is not part of the current screen's surface.`);
+    if (!this.#instance.liveKeysIn(viewKey).has(key))
+      throw new Error(`State key "${key}" is not read by this screen, so it is not part of its surface.`);
     const value = AgentBridge.#unwrap(this.#instance.get()[key]);
     if (entry.refName && entry.modelType) {
       const model = ConstantRegistry.getModelRef(entry.refName, entry.modelType) as MaskModel;
@@ -153,162 +73,6 @@ export class AgentBridge {
     );
   }
 
-  /**
-   * Dispatches through `st.do`, so what happens is what happens when the user clicks.
-   *
-   * Arguments arrive named and are mapped onto the action's parameters in declared order. An omitted optional one
-   * becomes `null`, which is what the slice query builders already expect; an omitted required one is refused,
-   * because the alternative is a call that writes `undefined` into state and reports success.
-   */
-  async call(name: string, args: Record<string, unknown> = {}, viewKey = "") {
-    const action = this.#byName.get(name);
-    if (!action) throw new Error(`Unknown action: ${name}`);
-
-    const record: AgentCall = { name, args, at: new Date() };
-    this.#calls.push(record);
-    try {
-      if (!this.#ownerLive(name, this.#liveOwners(viewKey)))
-        throw new Error(`Action "${name}" is not part of the current screen's surface.`);
-      const positional = action.args.map((arg) => this.#value(name, arg, args));
-      await this.#instance.do[name]?.(...positional);
-    } catch (error) {
-      record.error = error instanceof Error ? error.message : String(error);
-      throw error;
-    }
-  }
-
-  #value(name: string, arg: SerializedArg, args: Record<string, unknown>) {
-    if (!(arg.name in args) || args[arg.name] === undefined) {
-      if (arg.nullable || arg.type === "search") return null;
-      throw new Error(`Missing argument "${arg.name}" for ${name}.`);
-    }
-    return AgentBridge.#checked(name, arg, args[arg.name]);
-  }
-
-  /**
-   * Checks a value against what the argument declared, one level of array included.
-   *
-   * `st.do` accepts anything — it is a rest wrapper — so without this a string where an `Int` belongs is written
-   * into state and rendered, and the agent is told the call succeeded. A model argument is checked only for being
-   * an object: the published schema describes its fields and the endpoint validates them server-side.
-   */
-  static #checked(name: string, arg: SerializedArg, value: unknown): unknown {
-    const depth = arg.arrDepth ?? 0;
-    if (depth) {
-      if (!Array.isArray(value)) throw new Error(`Argument "${arg.name}" of ${name} must be an array.`);
-      return value.map((item) => AgentBridge.#checked(name, { ...arg, arrDepth: depth - 1 }, item));
-    }
-    if (value === null) return null;
-    if (arg.enum) return AgentBridge.#checkedEnum(name, arg, value);
-    switch (arg.refName) {
-      case "String":
-      case "ID":
-        return AgentBridge.#assertType(name, arg, value, "string");
-      case "Int":
-        if (!Number.isInteger(value)) throw new Error(`Argument "${arg.name}" of ${name} must be a whole number.`);
-        return value;
-      case "Float":
-        if (typeof value !== "number" || !Number.isFinite(value))
-          throw new Error(`Argument "${arg.name}" of ${name} must be a finite number.`);
-        return value;
-      case "Boolean":
-        return AgentBridge.#assertType(name, arg, value, "boolean");
-      case "Date":
-        return AgentBridge.#checkedDate(name, arg, value);
-      default:
-        if (typeof value !== "object") throw new Error(`Argument "${arg.name}" of ${name} must be an object.`);
-        return value;
-    }
-  }
-
-  static #assertType(name: string, arg: SerializedArg, value: unknown, type: "string" | "boolean") {
-    if (typeof value !== type) throw new Error(`Argument "${arg.name}" of ${name} must be a ${type}.`);
-    return value;
-  }
-
-  static #checkedEnum(name: string, arg: SerializedArg, value: unknown) {
-    const values = arg.enum ? ConstantRegistry.enum.get(arg.enum)?.values : undefined;
-    if (!values) return value;
-    if (!values.includes(value as never))
-      throw new Error(`Argument "${arg.name}" of ${name} must be one of: ${[...values].join(", ")}.`);
-    return value;
-  }
-
-  /** An agent has no `Date`, so an ISO string is what it sends. Anything unparseable is refused rather than `Invalid Date`. */
-  static #checkedDate(name: string, arg: SerializedArg, value: unknown) {
-    if (value instanceof Date) return value;
-    const parsed = typeof value === "string" ? new Date(value) : null;
-    if (!parsed || Number.isNaN(parsed.getTime()))
-      throw new Error(`Argument "${arg.name}" of ${name} must be an ISO 8601 date string.`);
-    return parsed;
-  }
-
-  #tool(name: string, action: SerializedStoreAction): AgentTool {
-    const properties = Object.fromEntries(action.args.map((arg) => [arg.name, this.#argSchema(action, arg)]));
-    const required = action.args.filter((arg) => !arg.nullable && arg.type !== "search").map((arg) => arg.name);
-    const defs = this.#schema.referencedSchemas(properties);
-    return {
-      name,
-      ...this.#texts(action),
-      inputSchema: {
-        type: "object",
-        properties,
-        ...(required.length ? { required } : {}),
-        additionalProperties: false,
-        ...(Object.keys(defs).length ? { $defs: defs } : {}),
-      },
-      effect: action.effect,
-    };
-  }
-
-  /**
-   * A store action carries no argument metadata of its own, so the prose comes from wherever the argument came
-   * from: an endpoint-named action borrows `<refName>.signal.<endpoint>.arg.<name>.desc`, and a field setter's one
-   * argument is the field, described at `<refName>.<field>.desc`. A slice role's `page`/`limit`/`sort` are the
-   * framework's own and have no dictionary entry to borrow.
-   */
-  #argSchema(action: SerializedStoreAction, arg: SerializedArg) {
-    const description = this.#argText(action, arg);
-    return {
-      ...this.#schema.arg(arg),
-      ...(description ? { description } : {}),
-      ...(arg.example !== undefined ? { examples: [arg.example] } : {}),
-    };
-  }
-
-  #argText({ refName, endpoint, field }: SerializedStoreAction, arg: SerializedArg) {
-    if (!refName) return undefined;
-    if (endpoint) return this.#text(`${refName}.signal.${endpoint}.arg.${arg.name}.desc`);
-    return field && arg.name === field ? this.#text(`${refName}.${field}.desc`) : undefined;
-  }
-
-  /**
-   * The words an agent picks the action by, borrowed from what the action is named after.
-   *
-   * The endpoint comes first, and it is right rather than merely adequate: the house rule makes `st.do.X` and
-   * `fetch.X` the same verb, so an action named after an endpoint reads as that endpoint's `.desc()`. A field
-   * setter falls back to the field's own label.
-   */
-  #texts({ refName, endpoint, field }: SerializedStoreAction) {
-    const keys = refName
-      ? [...(endpoint ? [`${refName}.signal.${endpoint}`] : []), ...(field ? [`${refName}.${field}`] : [])]
-      : [];
-    for (const key of keys) {
-      const title = this.#text(key);
-      const description = this.#text(`${key}.desc`);
-      if (title || description) return { ...(title ? { title } : {}), ...(description ? { description } : {}) };
-    }
-    return {};
-  }
-
-  #text(key: string) {
-    if (this.#options.resolveDescription) return this.#options.resolveDescription(key);
-    const locale = Translator.getActiveLocale() ?? parseAkanI18nEnv().defaultLocale;
-    const text = Translator.translateByLocale(locale, key);
-    
-    return text === key ? undefined : text;
-  }
-
   static #unwrap(value: unknown) {
     return value instanceof DataList ? value.values : value;
   }

package/store/agent/AgentContext.ts

@@ -8,8 +8,8 @@ import { ensureStoreSurface } from "./storeSurface";
  * The akan default context for a turn: where the user is (route), what is on screen (scopes and their curated
  * resources), and which store keys the mounted components are reading (live keys). Live entries carry names and
  * small primitives only — anything bigger is one `readState` call away, masked — so the block cannot bloat with
- * what happens to be in the store. Base-store keys are excluded by the base store's own `agent: false`
- * declaration, and the route block carries the three of them that matter.
+ * what happens to be in the store. Base-store plumbing is kept off the surface by `st.use.x({ agent: false })`
+ * at each call site, and the route block carries the three of them that matter.
  */
 export class AgentContext {
   static of(): AgentContext {
@@ -40,10 +40,7 @@ export class AgentContext {
   }
 
   #liveBlock(viewKey: string): ContextBlock[] {
-    const live = [...this.#instance.liveKeysIn(viewKey).keys()]
-      .filter((key) => this.#bridge.visibility.visibleKey(key))
-      .sort()
-      .map((key) => this.#liveEntry(key));
+    const live = this.#bridge.readableKeys(viewKey).map((key) => this.#liveEntry(key));
     return live.length ? [{ kind: "state", live, note: "Call readState(key) to read a value." }] : [];
   }