akanjs 3.0.0-alpha.50 → 3.0.0-alpha.51

package/constant/fieldInfo.ts

@@ -106,6 +106,13 @@ export interface ConstantFieldProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
+  /**
+   * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
+   * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
+   * placeholder still ships to `<Image>`. Unlike `hidden`/`secret` this is about cost, not secrecy: a field
+   * nothing can answer a question with is pure spend on every turn it rides.
+   */
+  visual?: boolean;
   meta?: Metadata;
 }
 export const fieldPresets = ["email", "password", "url"] as const;
@@ -197,6 +204,7 @@ interface ConstantFieldBuildProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
+  visual: boolean;
   modelRef: ConstantModelRef;
   arrDepth: number;
   optArrDepth: number;
@@ -321,6 +329,7 @@ export class ConstantField<
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: TextFieldRole;
   readonly cascade?: CascadeAction;
+  readonly visual: boolean;
   readonly modelRef: ConstantModelRef;
   readonly arrDepth: number;
   readonly optArrDepth: number;
@@ -353,6 +362,7 @@ export class ConstantField<
     this.validate = props.validate;
     this.text = props.text;
     this.cascade = props.cascade;
+    this.visual = props.visual;
     this.modelRef = props.modelRef;
     this.arrDepth = props.arrDepth;
     this.optArrDepth = props.optArrDepth;
@@ -432,6 +442,7 @@ export class ConstantField<
       validate: option.validate,
       text: option.text,
       cascade: option.cascade,
+      visual: option.visual ?? false,
       modelRef,
       arrDepth: arrDepth,
       optArrDepth: optArrDepth,
@@ -478,6 +489,7 @@ export class ConstantField<
       validate: this.validate,
       text: this.text,
       cascade: this.cascade,
+      visual: this.visual,
       modelRef: this.modelRef,
       arrDepth: this.arrDepth,
       optArrDepth: this.optArrDepth,
@@ -530,6 +542,26 @@ export const field = <
     fieldType: "property",
   });
 
+/**
+ * A stored property the page renders and an agent never sees — `field(value, { visual: true })`, spelled short
+ * because the reason to reach for it is always the same one. A blur placeholder, a rendered HTML body, a
+ * serialized geometry: real data the screen needs, and hundreds of tokens per record that no question is answered
+ * from. It stays a plain `property` everywhere else, so persistence, search, forms and the page response are
+ * untouched.
+ */
+field.visual = <
+  ExplicitType,
+  Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
+  MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
+>(
+  value: Value,
+  option: FieldOption<Value, MapValue> = {},
+) =>
+  new FieldInfo<"property", Value, ExplicitType, MapValue>(value, {
+    ...option,
+    fieldType: "property",
+    visual: true,
+  });
 field.hidden = <
   ExplicitType,
   Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,

package/constant/mask.ts

@@ -15,6 +15,7 @@ interface MaskField {
   fieldType?: string;
   isClass?: boolean;
   modelRef?: MaskModel;
+  visual?: boolean;
 }
 
 export const maskFieldsOf = (model: MaskModel): Record<string, MaskField> | null => {
@@ -22,7 +23,12 @@ export const maskFieldsOf = (model: MaskModel): Record<string, MaskField> | null
   return fields && typeof fields === "object" ? (fields as Record<string, MaskField>) : null;
 };
 
-/** The `hidden` and `secret` field names of `model` that `value` still carries populated. */
+/**
+ * The `hidden` and `secret` field names of `model` that `value` still carries populated.
+ *
+ * `visual` is deliberately not among them. A refusal here means a value must not be published at all, and a blur
+ * placeholder is not a secret — it is merely not worth its tokens, which masking answers by dropping it.
+ */
 export const leakingFieldsOf = (model: MaskModel, value: Record<string, unknown>): string[] => {
   const fields = maskFieldsOf(model);
   if (!fields) return [];
@@ -32,8 +38,9 @@ export const leakingFieldsOf = (model: MaskModel, value: Record<string, unknown>
 };
 
 /**
- * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the value
- * happens to still carry.
+ * Strips what a model marks `hidden`, `secret`, or `visual`, by the model the caller names rather than by the one
+ * the value happens to still carry. The first two are secrecy and the third is cost, but the answer is the same
+ * one — leave the field out — and this is the only place every AI-facing read already passes through.
  *
  * That distinction is the whole point. A check that reads the class off the value can only mask what arrives as an
  * instance, so a `{ ...doc }` spread, a `toJSON()`, an `immerify()`, or a round-trip through `JSON.stringify` reaches
@@ -53,7 +60,7 @@ export const mask = (model: MaskModel, value: unknown): unknown => {
   const source = value as Record<string, unknown>;
   const masked: Record<string, unknown> = {};
   for (const [key, field] of Object.entries(fields)) {
-    if (field.fieldType === "hidden" || field.fieldType === "secret" || !(key in source)) continue;
+    if (field.fieldType === "hidden" || field.fieldType === "secret" || field.visual || !(key in source)) continue;
     masked[key] = field.isClass && field.modelRef ? mask(field.modelRef, source[key]) : source[key];
   }
   return masked;

package/package.json

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

package/server/akanServer.ts

@@ -80,6 +80,13 @@ export interface McpServerOption {
    * the document is built once at boot and cached by clients, and it is read by a model rather than by a person.
    */
   language?: string;
+  /**
+   * Whether a structured result also ships as serialized JSON in the text block, `true` by default because that
+   * is what the spec asks of a server for clients that predate `structuredContent`. It is also a flat doubling:
+   * every model-returning tool sends its whole payload twice, so a deployment whose clients read the structured
+   * half turns this off and halves what each of those calls costs the model. `AKAN_MCP_LEGACY_TEXT=false`.
+   */
+  legacyTextBlock?: boolean;
   /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
   auth?: McpAuthOption;
 }
@@ -622,6 +629,11 @@ export class AkanServer {
     return !names.some((name) => process.env[name] === "false" || process.env[name] === "0");
   }
 
+  /** Named rather than defaulted: an absent env must leave the option unset so a value written in code still wins. */
+  static #isEnvOff(...names: string[]) {
+    return names.some((name) => process.env[name] === "false" || process.env[name] === "0");
+  }
+
   /** Both differ per environment, so they belong in env rather than in the app's source alongside the switch. */
   static #mcpAuthFromEnv(): McpAuthOption {
     const authorizationServers = AkanServer.#envList("AKAN_MCP_AUTH_SERVERS");
@@ -657,6 +669,7 @@ export class AkanServer {
       ...(allowedOrigins?.length ? { allowedOrigins } : {}),
       ...(Number.isInteger(pageSize) && pageSize > 0 ? { pageSize } : {}),
       ...(process.env.AKAN_MCP_LANGUAGE ? { language: process.env.AKAN_MCP_LANGUAGE } : {}),
+      ...(AkanServer.#isEnvOff("AKAN_MCP_LEGACY_TEXT") ? { legacyTextBlock: false } : {}),
     };
   }
 

package/server/mcp/McpDispatcher.ts

@@ -1,5 +1,6 @@
 import { type BackendEnv, ENDPOINT_META } from "akanjs/base";
 import { Logger } from "akanjs/common";
+import { ConstantRegistry, mask } from "akanjs/constant";
 import { DictionaryLookup } from "akanjs/dictionary";
 import { NoDocumentError } from "akanjs/document";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
@@ -42,12 +43,20 @@ interface McpDispatcherProps {
   middleware: Map<string, MiddlewareCls>;
   /** The one language error text is resolved in, matching the catalogue the client was handed. */
   language?: string;
+  /**
+   * Whether a structured result also ships as serialized JSON in the text block. `true` by default, which is what
+   * the spec asks for; `false` halves what every model-returning tool costs.
+   */
+  legacyTextBlock?: boolean;
 }
 
 /** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
 export class McpDispatcher {
   static readonly logger = new Logger("McpDispatcher");
 
+  /** What the text block says when the serialized duplicate is off. Read by a model, so English. */
+  static readonly structuredNote = "The result is in this call's structuredContent.";
+
   readonly #props: McpDispatcherProps;
   #endpoints: Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }> | null = null;
   /**
@@ -68,10 +77,10 @@ export class McpDispatcher {
     const found = this.#index().get(exposed.key);
     if (!found) return McpDispatcher.#failure(`Tool "${exposed.key}" is declared but not mounted on this server.`);
     try {
-      const value = await this.#exec(exposed.key, found, args, req);
+      const value = McpDispatcher.#readable(exposed, await this.#exec(exposed.key, found, args, req));
       const structuredContent = McpDocument.structuredContent(exposed.endpoint, value);
       return {
-        content: [{ type: "text", text: McpDispatcher.#text(structuredContent, value) }],
+        content: this.#content(structuredContent, value),
         ...(structuredContent === undefined ? {} : { structuredContent }),
         isError: false,
       };
@@ -223,6 +232,19 @@ export class McpDispatcher {
     return status && status < 500 ? McpErrorCode.invalidParams : McpErrorCode.internal;
   }
 
+  /**
+   * A structured result rides twice by default: once as `structuredContent`, once as the same JSON here, which is
+   * what the spec asks of a server for clients that predate the structured field. Every model return therefore
+   * costs the model twice what it carries, and `legacyTextBlock: false` is the deployment that has decided its
+   * clients read the structured half — the pointer keeps `content` non-empty, since a client that renders
+   * `content[0].text` and finds nothing shows an empty answer rather than a missing one.
+   */
+  #content(structuredContent: unknown, value: unknown): McpToolResult["content"] {
+    if (structuredContent !== undefined && this.#props.legacyTextBlock === false)
+      return [{ type: "text", text: McpDispatcher.structuredNote }];
+    return [{ type: "text", text: McpDispatcher.#text(structuredContent, value) }];
+  }
+
   /**
    * The text block every result carries, whether or not a structured one goes with it.
    *
@@ -239,6 +261,24 @@ export class McpDispatcher {
     return JSON.stringify(structuredContent ?? value) ?? "null";
   }
 
+  /**
+   * Strips what the return model marks `visual` — a field the page renders and no question is answered from.
+   *
+   * Done here rather than in `resolveReturn`, which every ordinary HTTP response also passes through: the point of
+   * a `visual` field is that a browser still receives it. MCP results reach an agent and nothing else, so this is
+   * where the model's own declaration is honoured, and it is the same `mask` the in-page agent's reads use.
+   */
+  static #readable(exposed: McpExposedEndpoint, value: unknown): unknown {
+    const { refName, modelType } = exposed.endpoint.returns;
+    if (!modelType) return value;
+    try {
+      return mask(ConstantRegistry.getModelRef(refName, modelType), value);
+    } catch {
+
+      return value;
+    }
+  }
+
   static #failure(message: string): McpToolResult {
     return { content: [{ type: "text", text: message }], isError: true };
   }

package/server/mcp/McpRouter.ts

@@ -45,6 +45,8 @@ export interface McpRouterProps {
    * rarely sees. Defaults to `en`, falling back to the first registered language when the app has no `en`.
    */
   language?: string;
+  /** Whether a structured result also ships as serialized JSON in the text block. Default `true`. */
+  legacyTextBlock?: boolean;
   auth?: McpAuthOption;
 }
 

package/signal/schema/JsonSchemaBuilder.ts

@@ -14,11 +14,15 @@ export interface JsonSchemaBuilderOptions {
 
 export interface JsonSchemaModelOptions {
   /**
-   * Drops `hidden` and `secret` fields. `SignalContext.resolveReturn` strips both from every response, so naming
-   * them describes a value the caller can never read — and on a model like `user` the names are themselves the
-   * leak: `password`, `accountId`, `phone` published as readable properties of the model. This is the one place a
-   * field the framework blocks on every value path is still visible, so it is scoped to schemas that describe a
-   * *response*. A request body is a different shape and legitimately carries both.
+   * Drops `hidden`, `secret`, and `visual` fields. `SignalContext.resolveReturn` strips the first two from every
+   * response, so naming them describes a value the caller can never read — and on a model like `user` the names
+   * are themselves the leak: `password`, `accountId`, `phone` published as readable properties of the model. This
+   * is the one place a field the framework blocks on every value path is still visible, so it is scoped to schemas
+   * that describe a *response*. A request body is a different shape and legitimately carries all three.
+   *
+   * `visual` is dropped here because it is dropped from the payload an AI caller receives, and a schema that
+   * promises a field the value omits is worse than one that never named it: a non-optional visual field would be
+   * listed `required` and a validating client would refuse the whole result.
    */
   readable?: boolean;
 }
@@ -56,7 +60,7 @@ export class JsonSchemaBuilder {
     const required: string[] = [];
     for (const [key, field] of Object.entries(fields)) {
       const props = field.getProps();
-      if (readable && (props.fieldType === "hidden" || props.fieldType === "secret")) continue;
+      if (readable && (props.fieldType === "hidden" || props.fieldType === "secret" || props.visual)) continue;
       properties[key] = this.#field(field);
       if (!props.nullable) required.push(key);
     }

package/store/agent/ScreenReader.ts

@@ -51,6 +51,11 @@ const blockTags = new Set([
  * agent's own UI is marked `data-agent-ui` and skipped, so a turn never re-reads its own transcript, and a
  * password value is never read — the screen shows dots, so the DOM holds more than the user sees.
  *
+ * A region the app marks `data-agent-skip` — what `Agent.Skip` renders — costs a `[skipped: <name>]` line instead
+ * of its text. It stands in the output rather than vanishing because a deleted region reads as an absent one, and
+ * an agent asked about a footer it never saw answers that the page has none. Naming the region as `section` reads
+ * it: the marker is what the default read leaves out, not a wall.
+ *
  * A heading carries `(#anchor)` whenever it opens a container that has an id or a scope path, because that is the
  * name `readScreen({ section })` and `highlight` take: printing the text without the name leaves an agent
  * guessing at a slug. For the same reason a truncated read ends with the headings below the cut instead of only
@@ -64,7 +69,7 @@ export class ScreenReader {
     const reader = new ScreenReader();
     const title = document.title.trim();
     if (title) reader.#lines.push(`Page: ${title}`);
-    reader.#walk(root ?? document.body);
+    reader.#walk(root ?? document.body, true);
     reader.#flush();
     return reader.#text() || "The page is rendering nothing readable.";
   }
@@ -78,10 +83,10 @@ export class ScreenReader {
     if (typeof document === "undefined") return "No rendered document is available.";
     const reader = new ScreenReader();
     const container = ScreenReader.#sectionOf(heading, root);
-    if (container) reader.#walk(container);
+    if (container) reader.#walk(container, true);
     else {
       const level = headingLevels[heading.tagName.toUpperCase() as keyof typeof headingLevels] ?? 1;
-      reader.#walk(heading);
+      reader.#walk(heading, true);
       let next = heading.nextElementSibling;
       while (next && !ScreenReader.#stops(next, level)) {
         reader.#walk(next);
@@ -123,6 +128,17 @@ export class ScreenReader {
     return "";
   }
 
+  /**
+   * `checkVisibility()` reports whether the element has a layout box, and a `display: contents` wrapper has none
+   * while its children do — so Chrome answers false for a wrapper the user is looking straight at, and skipping it
+   * would drop that whole subtree (happy-dom answers true, so no DOM test sees the difference). Reading through it
+   * is safe only because the walk is top-down: a `display: none` ancestor bails on its own computed display first.
+   */
+  static #rendered(el: HTMLElement) {
+    if (typeof el.checkVisibility !== "function" || el.checkVisibility()) return true;
+    return getComputedStyle(el).display === "contents";
+  }
+
   static #stops(el: Element, level: number) {
     const found = headingLevels[el.tagName.toUpperCase() as keyof typeof headingLevels];
     return !!found && found <= level;
@@ -141,7 +157,7 @@ export class ScreenReader {
     if (node.nodeType !== Node.ELEMENT_NODE) return;
     const el = node as HTMLElement;
     const tag = el.tagName.toUpperCase();
-    if (skipTags.has(tag) || el.hasAttribute("data-agent-ui")) return;
+    if (skipTags.has(tag) || el.hasAttribute("data-agent-ui") || el.hasAttribute("data-agent-skip")) return;
     const level = headingLevels[tag as keyof typeof headingLevels];
     if (level) {
       const anchor = ScreenReader.anchorOf(el);
@@ -163,7 +179,15 @@ export class ScreenReader {
       : `${kept}${note}`;
   }
 
-  #walk(node: Node): void {
+  /** What stands where a skipped region was: its own name, and the anchor `section` takes to read it on request. */
+  #mark(el: HTMLElement, label: string) {
+    const anchor = el.getAttribute("data-agent-scope") ?? el.getAttribute("data-agent-zone") ?? el.id;
+    this.#flush();
+    this.#buffer = `[skipped: ${label || el.tagName.toLowerCase()}${anchor ? ` (#${anchor})` : ""}]`;
+    this.#flush();
+  }
+
+  #walk(node: Node, isRoot = false): void {
     if (this.#length > ScreenReader.limit * 2) {
       this.#outline(node);
       return;
@@ -179,7 +203,13 @@ export class ScreenReader {
     if (skipTags.has(tag)) return;
     if (el.hasAttribute("data-agent-ui") || el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true")
       return;
-    if (typeof el.checkVisibility === "function" && !el.checkVisibility()) return;
+    if (!ScreenReader.#rendered(el)) return;
+    
+    const skipped = isRoot ? null : el.getAttribute("data-agent-skip");
+    if (skipped !== null) {
+      this.#mark(el, skipped);
+      return;
+    }
     if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") {
       this.#control(el, tag);
       return;

package/store/agent/ScreenTarget.ts

@@ -1,6 +1,6 @@
 import { ScreenReader } from "./ScreenReader";
 
-const containerAttrs = ["data-agent-zone", "data-agent-scope"] as const;
+const containerAttrs = ["data-agent-zone", "data-agent-scope", "data-agent-skip"] as const;
 const controlAttrs = ["data-akan-action", "data-akan-state"] as const;
 const headingSelector = "h1, h2, h3, h4, h5, h6";
 const nameCap = 40;
@@ -9,9 +9,9 @@ const nameCap = 40;
  * Resolves a name the agent read on screen to the element it names.
  *
  * Four vocabularies, every one of them something already on the screen rather than a selector the model invented:
- * the `data-akan-action` / `data-akan-state` annotation a control carries and `readScreen` prints beside it, an
- * `Agent.Zone` or `useScreenScope` container, a plain element id — what a docs slide is addressed by — and, last, a
- * **heading by its own text**.
+ * the `data-akan-action` / `data-akan-state` annotation a control carries and `readScreen` prints beside it, a
+ * container — an `Agent.Zone`, a `useScreenScope` scope, or an `Agent.Skip` region named by the marker left in its
+ * place — a plain element id, what a docs slide is addressed by, and, last, a **heading by its own text**.
  *
  * A heading is matched on letters and digits alone, so the slug an agent naturally writes for a heading it read
  * ("images-and-public-env") finds "Images And Public Env". That tolerance is for headings only: a heading is a
@@ -20,7 +20,8 @@ const nameCap = 40;
  *
  * Nothing hidden ever resolves, by the same rule `readScreen` skips it. A collapsed panel or an off-variant
  * duplicate is not what the user is looking at, and scrolling to one flashes a ring nobody can see — which reads
- * as the tool being broken rather than as a miss.
+ * as the tool being broken rather than as a miss. A `display: contents` wrapper does not resolve either, even
+ * though the reader now reads through it: it has no box, so `scrollIntoView` has nothing to scroll to.
  */
 export class ScreenTarget {
   static container(name: string, root?: HTMLElement | null): HTMLElement | null {
@@ -28,8 +29,13 @@ export class ScreenTarget {
     if (!scope || !name) return null;
     if (ScreenTarget.#named(scope, containerAttrs, name)) return scope;
     const escaped = CSS.escape(name);
-    const selector = [...containerAttrs.map((attr) => `[${attr}="${escaped}"]`), `#${escaped}`].join(", ");
-    return ScreenTarget.#first(scope, selector);
+    const selector = containerAttrs.map((attr) => `[${attr}="${escaped}"]`).join(", ");
+
+    return (
+      ScreenTarget.#first(scope, selector) ??
+      [...scope.querySelectorAll<HTMLElement>("[id]")].find((el) => el.id === name && ScreenTarget.#visible(el)) ??
+      null
+    );
   }
 
   static control(name: string, root?: HTMLElement | null): HTMLElement | null {

package/store/agent/StoreSurfaceSource.ts

@@ -107,7 +107,7 @@ export class StoreSurfaceSource implements SurfaceSource {
           section: {
             type: "string",
             description:
-              "One region of the screen: a heading's anchor as readScreen prints it, the heading's own text, or a scope path from the screen context. Omit to read all of it.",
+              "One region of the screen: a heading's anchor as readScreen prints it, the heading's own text, a scope path from the screen context, or the name in a `[skipped: name]` marker. Omit to read all of it.",
           },
         },
         additionalProperties: false,

package/types/constant/fieldInfo.d.ts

@@ -47,6 +47,13 @@ export interface ConstantFieldProps<FieldType extends ConstantFieldKind = Consta
     validate?: (value: FieldValue, model: any) => boolean;
     text?: TextFieldRole;
     cascade?: CascadeAction;
+    /**
+     * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
+     * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
+     * placeholder still ships to `<Image>`. Unlike `hidden`/`secret` this is about cost, not secrecy: a field
+     * nothing can answer a question with is pure spend on every turn it rides.
+     */
+    visual?: boolean;
     meta?: Metadata;
 }
 export declare const fieldPresets: readonly ["email", "password", "url"];
@@ -94,6 +101,7 @@ interface ConstantFieldBuildProps<FieldType extends ConstantFieldKind = any, Fie
     validate?: (value: FieldValue, model: any) => boolean;
     text?: TextFieldRole;
     cascade?: CascadeAction;
+    visual: boolean;
     modelRef: ConstantModelRef;
     arrDepth: number;
     optArrDepth: number;
@@ -139,6 +147,7 @@ export declare class ConstantField<FieldType extends ConstantFieldKind = Constan
     readonly validate?: (value: FieldValue, model: any) => boolean;
     readonly text?: TextFieldRole;
     readonly cascade?: CascadeAction;
+    readonly visual: boolean;
     readonly modelRef: ConstantModelRef;
     readonly arrDepth: number;
     readonly optArrDepth: number;
@@ -172,6 +181,7 @@ export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ..
 /** Builds a stored property field with optional validation, default, ref, text, and metadata options. */
 export declare const field: {
     <ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: FieldOption<Value, MapValue>): FieldInfo<"property", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, false>;
+    visual<ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: FieldOption<Value, MapValue>): FieldInfo<"property", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, false>;
     hidden<ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: FieldOption<Value, MapValue>): FieldInfo<"hidden", Value, ExplicitType, MapValue, FieldKindSource<Value>, UnCls<FieldKindSource<Value>> extends BaseObject ? true : false, FieldKindSource<Value> extends infer T ? T extends FieldKindSource<Value> ? T extends EnumInstance<string, any> ? true : false : never : never, FieldKindSource<Value> extends infer T_1 ? T_1 extends FieldKindSource<Value> ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, FieldKindSource<Value> extends infer T_2 ? T_2 extends FieldKindSource<Value> ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<FieldKindSource<Value>> extends BaseObject ? true : false) ? T_3 extends true ? false : (FieldKindSource<Value> extends infer T_4 ? T_4 extends FieldKindSource<Value> ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (FieldKindSource<Value> extends infer T_12 ? T_12 extends FieldKindSource<Value> ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (FieldKindSource<Value> extends infer T_6 ? T_6 extends FieldKindSource<Value> ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (FieldKindSource<Value> extends infer T_11 ? T_11 extends FieldKindSource<Value> ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (FieldKindSource<Value> extends infer T_8 ? T_8 extends FieldKindSource<Value> ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (FieldKindSource<Value> extends infer T_10 ? T_10 extends FieldKindSource<Value> ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, true, false>;
     secret<ExplicitType, Value extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never>(value: Value, option?: FieldOption<Value, MapValue>): FieldInfo<"secret", Value | null, ExplicitType | null, MapValue, SingleValue<Value> & {}, UnCls<SingleValue<Value> & {}> extends BaseObject ? true : false, SingleValue<Value> & {} extends infer T ? T extends SingleValue<Value> & {} ? T extends EnumInstance<string, any> ? true : false : never : never, SingleValue<Value> & {} extends infer T_1 ? T_1 extends SingleValue<Value> & {} ? T_1 extends typeof PrimitiveScalar ? true : false : never : never, SingleValue<Value> & {} extends infer T_2 ? T_2 extends SingleValue<Value> & {} ? T_2 extends MapConstructor ? true : false : never : never, (UnCls<SingleValue<Value> & {}> extends BaseObject ? true : false) extends infer T_3 ? T_3 extends (UnCls<SingleValue<Value> & {}> extends BaseObject ? true : false) ? T_3 extends true ? false : (SingleValue<Value> & {} extends infer T_4 ? T_4 extends SingleValue<Value> & {} ? T_4 extends EnumInstance<string, any> ? true : false : never : never) extends infer T_5 ? T_5 extends (SingleValue<Value> & {} extends infer T_12 ? T_12 extends SingleValue<Value> & {} ? T_12 extends EnumInstance<string, any> ? true : false : never : never) ? T_5 extends true ? false : (SingleValue<Value> & {} extends infer T_6 ? T_6 extends SingleValue<Value> & {} ? T_6 extends typeof PrimitiveScalar ? true : false : never : never) extends infer T_7 ? T_7 extends (SingleValue<Value> & {} extends infer T_11 ? T_11 extends SingleValue<Value> & {} ? T_11 extends typeof PrimitiveScalar ? true : false : never : never) ? T_7 extends true ? false : (SingleValue<Value> & {} extends infer T_8 ? T_8 extends SingleValue<Value> & {} ? T_8 extends MapConstructor ? true : false : never : never) extends infer T_9 ? T_9 extends (SingleValue<Value> & {} extends infer T_10 ? T_10 extends SingleValue<Value> & {} ? T_10 extends MapConstructor ? true : false : never : never) ? T_9 extends true ? false : true : never : never : never : never : never : never : never : never, false, true>;
 };

package/types/constant/mask.d.ts

@@ -12,13 +12,20 @@ interface MaskField {
     fieldType?: string;
     isClass?: boolean;
     modelRef?: MaskModel;
+    visual?: boolean;
 }
 export declare const maskFieldsOf: (model: MaskModel) => Record<string, MaskField> | null;
-/** The `hidden` and `secret` field names of `model` that `value` still carries populated. */
+/**
+ * The `hidden` and `secret` field names of `model` that `value` still carries populated.
+ *
+ * `visual` is deliberately not among them. A refusal here means a value must not be published at all, and a blur
+ * placeholder is not a secret — it is merely not worth its tokens, which masking answers by dropping it.
+ */
 export declare const leakingFieldsOf: (model: MaskModel, value: Record<string, unknown>) => string[];
 /**
- * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the value
- * happens to still carry.
+ * Strips what a model marks `hidden`, `secret`, or `visual`, by the model the caller names rather than by the one
+ * the value happens to still carry. The first two are secrecy and the third is cost, but the answer is the same
+ * one — leave the field out — and this is the only place every AI-facing read already passes through.
  *
  * That distinction is the whole point. A check that reads the class off the value can only mask what arrives as an
  * instance, so a `{ ...doc }` spread, a `toJSON()`, an `immerify()`, or a round-trip through `JSON.stringify` reaches

package/types/server/akanServer.d.ts

@@ -52,6 +52,13 @@ export interface McpServerOption {
      * the document is built once at boot and cached by clients, and it is read by a model rather than by a person.
      */
     language?: string;
+    /**
+     * Whether a structured result also ships as serialized JSON in the text block, `true` by default because that
+     * is what the spec asks of a server for clients that predate `structuredContent`. It is also a flat doubling:
+     * every model-returning tool sends its whole payload twice, so a deployment whose clients read the structured
+     * half turns this off and halves what each of those calls costs the model. `AKAN_MCP_LEGACY_TEXT=false`.
+     */
+    legacyTextBlock?: boolean;
     /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
     auth?: McpAuthOption;
 }

package/types/server/mcp/McpDispatcher.d.ts

@@ -24,11 +24,18 @@ interface McpDispatcherProps {
     middleware: Map<string, MiddlewareCls>;
     /** The one language error text is resolved in, matching the catalogue the client was handed. */
     language?: string;
+    /**
+     * Whether a structured result also ships as serialized JSON in the text block. `true` by default, which is what
+     * the spec asks for; `false` halves what every model-returning tool costs.
+     */
+    legacyTextBlock?: boolean;
 }
 /** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
 export declare class McpDispatcher {
     #private;
     static readonly logger: Logger;
+    /** What the text block says when the serialized duplicate is off. Read by a model, so English. */
+    static readonly structuredNote = "The result is in this call's structuredContent.";
     constructor(props: McpDispatcherProps);
     call(exposed: McpExposedEndpoint, args: Record<string, unknown>, req: Request): Promise<McpToolResult>;
     /**

package/types/server/mcp/McpRouter.d.ts

@@ -26,6 +26,8 @@ export interface McpRouterProps {
      * rarely sees. Defaults to `en`, falling back to the first registered language when the app has no `en`.
      */
     language?: string;
+    /** Whether a structured result also ships as serialized JSON in the text block. Default `true`. */
+    legacyTextBlock?: boolean;
     auth?: McpAuthOption;
 }
 /**

package/types/signal/schema/JsonSchemaBuilder.d.ts

@@ -10,11 +10,15 @@ export interface JsonSchemaBuilderOptions {
 }
 export interface JsonSchemaModelOptions {
     /**
-     * Drops `hidden` and `secret` fields. `SignalContext.resolveReturn` strips both from every response, so naming
-     * them describes a value the caller can never read — and on a model like `user` the names are themselves the
-     * leak: `password`, `accountId`, `phone` published as readable properties of the model. This is the one place a
-     * field the framework blocks on every value path is still visible, so it is scoped to schemas that describe a
-     * *response*. A request body is a different shape and legitimately carries both.
+     * Drops `hidden`, `secret`, and `visual` fields. `SignalContext.resolveReturn` strips the first two from every
+     * response, so naming them describes a value the caller can never read — and on a model like `user` the names
+     * are themselves the leak: `password`, `accountId`, `phone` published as readable properties of the model. This
+     * is the one place a field the framework blocks on every value path is still visible, so it is scoped to schemas
+     * that describe a *response*. A request body is a different shape and legitimately carries all three.
+     *
+     * `visual` is dropped here because it is dropped from the payload an AI caller receives, and a schema that
+     * promises a field the value omits is worse than one that never named it: a non-optional visual field would be
+     * listed `required` and a validating client would refuse the whole result.
      */
     readable?: boolean;
 }

package/types/store/agent/ScreenReader.d.ts

@@ -4,6 +4,11 @@
  * agent's own UI is marked `data-agent-ui` and skipped, so a turn never re-reads its own transcript, and a
  * password value is never read — the screen shows dots, so the DOM holds more than the user sees.
  *
+ * A region the app marks `data-agent-skip` — what `Agent.Skip` renders — costs a `[skipped: <name>]` line instead
+ * of its text. It stands in the output rather than vanishing because a deleted region reads as an absent one, and
+ * an agent asked about a footer it never saw answers that the page has none. Naming the region as `section` reads
+ * it: the marker is what the default read leaves out, not a wall.
+ *
  * A heading carries `(#anchor)` whenever it opens a container that has an id or a scope path, because that is the
  * name `readScreen({ section })` and `highlight` take: printing the text without the name leaves an agent
  * guessing at a slug. For the same reason a truncated read ends with the headings below the cut instead of only

package/types/store/agent/ScreenTarget.d.ts

@@ -2,9 +2,9 @@
  * Resolves a name the agent read on screen to the element it names.
  *
  * Four vocabularies, every one of them something already on the screen rather than a selector the model invented:
- * the `data-akan-action` / `data-akan-state` annotation a control carries and `readScreen` prints beside it, an
- * `Agent.Zone` or `useScreenScope` container, a plain element id — what a docs slide is addressed by — and, last, a
- * **heading by its own text**.
+ * the `data-akan-action` / `data-akan-state` annotation a control carries and `readScreen` prints beside it, a
+ * container — an `Agent.Zone`, a `useScreenScope` scope, or an `Agent.Skip` region named by the marker left in its
+ * place — a plain element id, what a docs slide is addressed by, and, last, a **heading by its own text**.
  *
  * A heading is matched on letters and digits alone, so the slug an agent naturally writes for a heading it read
  * ("images-and-public-env") finds "Images And Public Env". That tolerance is for headings only: a heading is a
@@ -13,7 +13,8 @@
  *
  * Nothing hidden ever resolves, by the same rule `readScreen` skips it. A collapsed panel or an off-variant
  * duplicate is not what the user is looking at, and scrolling to one flashes a ring nobody can see — which reads
- * as the tool being broken rather than as a miss.
+ * as the tool being broken rather than as a miss. A `display: contents` wrapper does not resolve either, even
+ * though the reader now reads through it: it has no box, so `scrollIntoView` has nothing to scroll to.
  */
 export declare class ScreenTarget {
     #private;