akanjs 3.0.0-alpha.50 → 3.0.0-alpha.52

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/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.52",
   "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/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,