@shwfed/config 3.0.7 → 3.0.9

package/dist/runtime/components/config/utils/ai-cursor.js

@@ -0,0 +1,833 @@
+import { JSONSchema, ParseResult, Schema } from "effect";
+import { coerceFromString } from "../../../share/coerce-from-string.js";
+import { Area, findFreePlacement, normalizeLayoutSet } from "../../../share/layout.js";
+import { activeBlocks, blockRef, findBlock } from "./resolve.js";
+import { createTableAiTools } from "../../table/utils/ai-tools.js";
+import { createFormFieldTools } from "../../form/utils/ai-field-tools.js";
+import { createActionsAiTools } from "../../actions/utils/ai-button-tools.js";
+import { findColumn } from "../../table/utils/resolve.js";
+import { findField } from "../../form/utils/resolve.js";
+import { findButton } from "../../actions/utils/resolve.js";
+import { configureTableActionsScope, metadata as tableMetadata } from "../../table/schema.js";
+import { registerRowVariablesIfAbsent } from "../../table/utils/shared.js";
+import { metadata as formMetadata } from "../../form/schema.js";
+import { registerFormVariablesIfAbsent } from "../../form/utils/form-vars.js";
+import { registerLoopVariablesIfAbsent } from "../../../share/loop-item-var.js";
+import { registerNodeVariableIfAbsent } from "../../../share/tree-node-var.js";
+import { PAGE_TARGET_ID } from "../../../share/page-target.js";
+import * as alertOp from "../../operations/2026-06-09/com.shwfed.operation.alert/schema.js";
+import * as httpRequestOp from "../../operations/2026-06-11/com.shwfed.operation.http.request.json/schema.js";
+import * as navigationOp from "../../operations/2026-06-15/com.shwfed.operation.navigation/schema.js";
+import * as httpDownloadOp from "../../operations/2026-06-15/com.shwfed.operation.http.download/schema.js";
+import { getHostManual } from "./ai-host-manuals.js";
+const ENTERABLE_HOSTS = /* @__PURE__ */ new Set(["table", "form", "slot", "actions"]);
+function enterableEdge(entry) {
+  const edge = entry?.edges?.[0];
+  if (!edge) return void 0;
+  if (!ENTERABLE_HOSTS.has(edge.host)) return void 0;
+  return edge;
+}
+function isBlockDrillable(block) {
+  return enterableEdge(findBlock(block.type, block.compatibilityDate)) !== void 0;
+}
+function blockLabel(block) {
+  const entry = findBlock(block.type, block.compatibilityDate);
+  const instance = entry?.metadata.instanceName?.(block);
+  if (instance && instance.length > 0) return instance;
+  return entry?.metadata.name ?? block.type;
+}
+function recomputeTracks(placements) {
+  let cols = 0;
+  let rows = 0;
+  for (const p of Object.values(placements)) {
+    const [, [x2, y2]] = p.area;
+    if (x2 - 1 > cols) cols = x2 - 1;
+    if (y2 - 1 > rows) rows = y2 - 1;
+  }
+  return { columns: Math.max(1, cols), rows: Math.max(1, rows) };
+}
+function overlaps(a, b) {
+  return a[0][0] < b[1][0] && a[1][0] > b[0][0] && a[0][1] < b[1][1] && a[1][1] > b[0][1];
+}
+const BLOCK_HARNESS_KEYS = ["id", "type", "compatibilityDate"];
+const PlaceBlockInput = Schema.Struct({
+  id: Schema.String.pipe(Schema.minLength(1)),
+  area: Area
+});
+function decodePlace(input) {
+  const result = Schema.decodeUnknownEither(PlaceBlockInput)(coerceFromString(input, PlaceBlockInput));
+  if (result._tag === "Right") {
+    return { ok: true, value: result.right };
+  }
+  const issues = ParseResult.ArrayFormatter.formatErrorSync(result.left);
+  const report = issues.map((i) => `- ${i.path.map(String).join(".") || "(root)"}: ${i.message}`).join("\n");
+  return { ok: false, report };
+}
+function emptyLayoutSet() {
+  return { name: "\u9ED8\u8BA4", layout: { columns: 1, placements: {} } };
+}
+export function createPageSlotTools(deps) {
+  function readSlot() {
+    const page = deps.read();
+    const slot = page.slot && typeof page.slot === "object" ? page.slot : { blocks: [], layouts: [] };
+    return { page, slot };
+  }
+  return [
+    // ---- 信息获取 ----
+    {
+      name: "list_available_block_types",
+      description: "List the page block types you can insert (table, form, chart, card, tabs, \u2026). Returns each type, its name, and \u2014 when set \u2014 a one-line description of when to use it. Use this first to discover what blocks exist; for a block's field contract call describe_specific_block_type, and for its deep configuration (a table's columns, a form's fields, a container's inner blocks) insert it then enter_node into it.",
+      inputJsonSchema: { type: "object", properties: {}, additionalProperties: false },
+      execute: () => activeBlocks().map((b) => {
+        const entry = { type: b.type, name: b.metadata.name };
+        if (b.metadata.description !== void 0) entry.description = b.metadata.description;
+        return entry;
+      })
+    },
+    {
+      name: "describe_specific_block_type",
+      description: "Return the JSON Schema (without id/type/compatibilityDate \u2014 managed by the harness), the default body, and \u2014 when the type has one \u2014 a prose `guide` (when to use it, config recipe, gotchas) for one page block type. Most blocks wrap a deeper config (a table, a form, a nested slot): insert the block, then enter_node into it to configure the details discovery-first. Deprecated/unknown types are not accepted.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "A `type` value from list_available_block_types." }
+        },
+        required: ["type"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const { type } = input ?? {};
+        if (typeof type !== "string" || type.length === 0) {
+          return "describe failed: `type` must be a non-empty string.";
+        }
+        const entry = activeBlocks().find((b) => b.type === type);
+        if (!entry) {
+          return `describe failed: block type "${type}" is not available. Call list_available_block_types to see what is.`;
+        }
+        let jsonSchema;
+        try {
+          const publicSchema = entry.schema(deps.configure, blockRef(deps.configure)).pipe(Schema.omit(...BLOCK_HARNESS_KEYS));
+          jsonSchema = JSONSchema.make(publicSchema);
+        } catch {
+          jsonSchema = "(schema unavailable)";
+        }
+        const result = { schema: jsonSchema, defaults: entry.defaultBody() };
+        if (entry.prompt !== void 0) result.guide = entry.prompt;
+        return result;
+      }
+    },
+    {
+      name: "list_blocks",
+      description: "Return the current slot's blocks \u2014 each with `id`, `type`, a friendly `name`, whether it is `drillable` (can be entered to configure details), and its `placement` (grid area in the slot's first layout, or null when unplaced). Use this to discover ids before enter_node / place_block / delete_blocks.",
+      inputJsonSchema: { type: "object", properties: {}, additionalProperties: false },
+      execute: () => {
+        const { slot } = readSlot();
+        const blocks = Array.isArray(slot.blocks) ? slot.blocks : [];
+        const layout0 = Array.isArray(slot.layouts) ? slot.layouts[0]?.layout : void 0;
+        const placements = layout0?.placements ?? {};
+        return {
+          blocks: blocks.map((b) => ({
+            id: b.id,
+            type: b.type,
+            name: blockLabel(b),
+            drillable: isBlockDrillable(b),
+            placement: placements[b.id]?.area ?? null
+          })),
+          grid: layout0 ? { columns: layout0.columns ?? null } : null
+        };
+      }
+    },
+    // ---- 配置 ----
+    {
+      name: "insert_block",
+      description: "Insert one new block of the given `type` into the current slot. The harness mints the id, seeds sensible defaults, and auto-places it in the slot's first layout at a free spot sized by the block's default footprint. Do NOT pass id / compatibilityDate. Configure the block's details afterwards by enter_node-ing into it. Returns the new block id and its placement; adjust the position with place_block if needed.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "A block type from list_available_block_types." }
+        },
+        required: ["type"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const { type } = input ?? {};
+        if (typeof type !== "string" || type.length === 0) {
+          return "insert failed: `type` must be a non-empty string.";
+        }
+        const entry = activeBlocks().find((b) => b.type === type);
+        if (!entry) {
+          return `insert failed: block type "${type}" is not available. Call list_available_block_types to see what is.`;
+        }
+        const { page, slot } = readSlot();
+        const blocks = Array.isArray(slot.blocks) ? slot.blocks : [];
+        const id = deps.genUuid();
+        const block = { ...entry.defaultBody(), id, type: entry.type, compatibilityDate: entry.compatibilityDate };
+        const layouts = Array.isArray(slot.layouts) && slot.layouts.length > 0 ? slot.layouts : [emptyLayoutSet()];
+        const ls0 = layouts[0];
+        const w = entry.metadata.w.initial ?? 1;
+        const h = entry.metadata.h.initial ?? 1;
+        const existing = ls0.layout?.placements ?? {};
+        const placement = findFreePlacement(existing, w, h);
+        const placements = { ...existing, [id]: placement };
+        const tracks = recomputeTracks(placements);
+        const nextLayouts = [
+          { ...ls0, layout: { ...ls0.layout, placements, columns: tracks.columns, rows: tracks.rows } },
+          ...layouts.slice(1)
+        ];
+        deps.write({ ...page, slot: { ...slot, blocks: [...blocks, block], layouts: nextLayouts } });
+        return { id, type: entry.type, placement: placement.area };
+      }
+    },
+    {
+      name: "delete_blocks",
+      description: "Delete one or more blocks by id from the current slot. Get ids from list_blocks. Blocks are matched by id only; on any unknown id the whole call is rejected without writing. Deleting a block also removes it from every layout (its placement is stripped).",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          ids: {
+            type: "array",
+            items: { type: "string", minLength: 1 },
+            minItems: 1,
+            description: "Block ids to delete. Get them from list_blocks first."
+          }
+        },
+        required: ["ids"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const raw = input ?? {};
+        const ids = raw.ids;
+        if (!Array.isArray(ids) || ids.length === 0) {
+          return "delete failed: `ids` must be a non-empty array of block ids.";
+        }
+        for (const id of ids) {
+          if (typeof id !== "string" || id.length === 0) {
+            return "delete failed: every `ids` entry must be a non-empty string.";
+          }
+        }
+        const seen = /* @__PURE__ */ new Set();
+        for (const id of ids) {
+          if (seen.has(id)) return `delete failed: duplicate id "${id}" in input \u2014 dedupe and call again.`;
+          seen.add(id);
+        }
+        const { page, slot } = readSlot();
+        const blocks = Array.isArray(slot.blocks) ? slot.blocks : [];
+        const existing = new Set(blocks.map((b) => b.id));
+        for (const id of ids) {
+          if (!existing.has(id)) {
+            return `delete failed: block id "${id}" is not present. Call list_blocks to see current ids.`;
+          }
+        }
+        const drop = new Set(ids);
+        const nextBlocks = blocks.filter((b) => !drop.has(b.id));
+        const layouts = Array.isArray(slot.layouts) ? slot.layouts : [];
+        const nextLayouts = layouts.map((ls) => {
+          const placements = ls.layout?.placements ?? {};
+          const entries = Object.entries(placements).filter(([pid]) => !drop.has(pid));
+          if (entries.length === Object.keys(placements).length) return ls;
+          const nextLs = { ...ls, layout: { ...ls.layout, placements: Object.fromEntries(entries) } };
+          return normalizeLayoutSet(nextLs);
+        });
+        deps.write({ ...page, slot: { ...slot, blocks: nextBlocks, layouts: nextLayouts } });
+        return { deleted: ids, count: ids.length };
+      }
+    },
+    {
+      name: "place_block",
+      description: "Place a block into the current slot's first layout at grid coordinates you choose. `area` is [[x1,y1],[x2,y2]] on 1-based grid lines (top-left inclusive, bottom-right exclusive); e.g. a block spanning columns 1\u201332 on rows 1\u20138 is [[1,1],[33,9]]. The block must already exist (insert it first). The harness rejects an area overlapping another block \u2014 pick a free spot (see list_blocks) and call again. Placing an already-placed block MOVES it. The grid grows to fit your placement.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "The block id to place (from list_blocks)." },
+          area: {
+            type: "array",
+            description: "Grid area [[x1,y1],[x2,y2]], 1-based grid lines, bottom-right exclusive.",
+            items: { type: "array", items: { type: "integer", minimum: 1 }, minItems: 2, maxItems: 2 },
+            minItems: 2,
+            maxItems: 2
+          }
+        },
+        required: ["id", "area"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const verdict = decodePlace(input ?? {});
+        if (!verdict.ok) {
+          return `place failed. Fix these and call place_block again:
+${verdict.report}`;
+        }
+        const { id, area } = verdict.value;
+        const { page, slot } = readSlot();
+        const blocks = Array.isArray(slot.blocks) ? slot.blocks : [];
+        if (!blocks.some((b) => b.id === id)) {
+          return `place failed: block id "${id}" is not present. Call list_blocks to see ids.`;
+        }
+        const layouts = Array.isArray(slot.layouts) ? slot.layouts : [];
+        const ls0 = layouts[0];
+        if (!ls0 || !ls0.layout) {
+          return "place failed: the slot has no layout to place into.";
+        }
+        const placements = { ...ls0.layout.placements ?? {} };
+        for (const [pid, p] of Object.entries(placements)) {
+          if (pid === id) continue;
+          if (overlaps(area, p.area)) {
+            return `place failed: area overlaps block "${pid}" at ${JSON.stringify(p.area)}. Pick a free area (see list_blocks) and call again.`;
+          }
+        }
+        placements[id] = { area };
+        const tracks = recomputeTracks(placements);
+        const nextLayout = { ...ls0.layout, placements, columns: tracks.columns, rows: tracks.rows };
+        deps.write({ ...page, slot: { ...slot, layouts: [{ ...ls0, layout: nextLayout }, ...layouts.slice(1)] } });
+        return { id, area, columns: tracks.columns, rows: tracks.rows };
+      }
+    }
+  ];
+}
+function structKeyBridge(parent, key) {
+  return {
+    read: () => parent.read()?.[key],
+    write: (next) => {
+      const rec = parent.read() ?? {};
+      parent.write({ ...rec, [key]: next });
+    }
+  };
+}
+function arrayItemBridge(parent, arrayKey, id, subKey) {
+  return {
+    read: () => {
+      const arr = parent.read()?.[arrayKey] ?? [];
+      const item = arr.find((x) => x.id === id);
+      if (!item) return void 0;
+      return subKey ? item[subKey] : item;
+    },
+    write: (next) => {
+      const rec = parent.read() ?? {};
+      const arr = rec[arrayKey] ?? [];
+      const nextArr = arr.map((x) => x.id === id ? subKey ? { ...x, [subKey]: next } : next : x);
+      parent.write({ ...rec, [arrayKey]: nextArr });
+    }
+  };
+}
+function withLoopVars(base) {
+  return (env) => {
+    base(env);
+    registerLoopVariablesIfAbsent(env);
+  };
+}
+function withRowVars(base) {
+  return (env) => {
+    base(env);
+    registerRowVariablesIfAbsent(env);
+  };
+}
+function withFormVars(base) {
+  return (env) => {
+    base(env);
+    registerFormVariablesIfAbsent(env);
+  };
+}
+function withNodeVar(base) {
+  return (env) => {
+    base(env);
+    registerNodeVariableIfAbsent(env);
+  };
+}
+function withToolbarVars(base) {
+  return (env) => configureTableActionsScope(env, base);
+}
+function applyEdgeScope(edge, base) {
+  return edge.celScope === "loop-item" ? withLoopVars(base) : base;
+}
+function opDescriptor(o) {
+  return { id: o.type, name: o.metadata.name, compatibilityDate: o.compatibilityDate };
+}
+function pageEventTarget() {
+  return {
+    id: PAGE_TARGET_ID,
+    kind: "page",
+    name: "\u9875\u9762",
+    operations: [
+      opDescriptor(alertOp),
+      opDescriptor(httpRequestOp),
+      opDescriptor(navigationOp),
+      opDescriptor(httpDownloadOp),
+      { id: "close", name: "\u5173\u95ED\u6807\u7B7E\u9875" }
+    ]
+  };
+}
+function tableEventTargets(table) {
+  const tableId = typeof table.id === "string" ? table.id : null;
+  const tableOps = tableMetadata.operations;
+  return [{
+    id: tableId,
+    kind: "table",
+    name: typeof table.displayName === "string" && table.displayName.length > 0 ? table.displayName : tableMetadata.name,
+    operations: tableOps.map((o) => ({ id: o.id, name: o.name, ...o.compatibilityDate ? { compatibilityDate: o.compatibilityDate } : {} })),
+    ...tableId === null ? { note: "\u8BE5\u8868\u683C\u5C1A\u65E0 id\uFF0C\u6309\u94AE\u65E0\u6CD5\u53EF\u9760\u5730\u4EE5\u5B83\u4E3A\u76EE\u6807\u3002" } : {}
+  }];
+}
+export function createConfigAiCursor(deps) {
+  const pageSlotBridge = {
+    read: () => {
+      const page = deps.read();
+      return page?.slot && typeof page.slot === "object" ? page.slot : { blocks: [], layouts: [] };
+    },
+    write: (nextSlot) => {
+      const page = deps.read();
+      deps.write({ ...page, slot: nextSlot });
+    }
+  };
+  function slotFamily(bridge, configure) {
+    return createPageSlotTools({
+      read: () => ({ slot: bridge.read() ?? { blocks: [], layouts: [] } }),
+      write: (next) => bridge.write(next.slot),
+      configure,
+      genUuid: deps.genUuid
+    });
+  }
+  const pageFrame = {
+    kind: "page",
+    label: "\u9875\u9762",
+    family: slotFamily(pageSlotBridge, deps.configure),
+    slotBridge: pageSlotBridge,
+    configure: deps.configure,
+    eventTargets: () => [pageEventTarget()]
+  };
+  let frames = [pageFrame];
+  const fallbackManuals = /* @__PURE__ */ new Set();
+  const deliveredManuals = deps.manualsDelivered ?? {
+    has: (kind) => fallbackManuals.has(kind),
+    add: (kind) => {
+      fallbackManuals.add(kind);
+    }
+  };
+  const scope = () => frames.map((f) => f.label).join(" > ");
+  const current = () => frames[frames.length - 1];
+  function attachManual(result, kind) {
+    if (!deliveredManuals.has(kind)) {
+      deliveredManuals.add(kind);
+      const manual = getHostManual(kind);
+      if (manual !== void 0) result.manual = manual;
+    }
+    return result;
+  }
+  function aggregateEventTargets(ownerTargets) {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    const push = (t) => {
+      const key = t.id ?? `${t.kind}:${t.name}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      out.push(t);
+    };
+    for (const t of ownerTargets) push(t);
+    for (let i = frames.length - 1; i >= 0; i--) {
+      for (const t of frames[i].eventTargets?.() ?? []) push(t);
+    }
+    return out;
+  }
+  function enterTable(bridge, block, configure) {
+    const family = createTableAiTools({
+      read: () => bridge.read() ?? {},
+      write: (next) => bridge.write(next),
+      configure,
+      genUuid: deps.genUuid
+    });
+    const label = blockLabel(block);
+    frames.push({
+      kind: "table",
+      label,
+      node: { id: block.id, type: block.type, compatibilityDate: block.compatibilityDate },
+      family,
+      configure,
+      eventTargets: () => tableEventTargets(bridge.read() ?? {}),
+      recap: () => {
+        const t = bridge.read() ?? {};
+        return { columns: (Array.isArray(t.columns) ? t.columns : []).map((c) => ({ id: c.id, type: c.type })) };
+      },
+      // A table's row-action columns and its toolbar/bottom action bars are the
+      // enterable children (design §1.3: table → actions/bottomActions,
+      // column.actions → actions).
+      enter: (id) => {
+        const t = bridge.read() ?? {};
+        if (id === "actions" || id === "bottomActions") {
+          return enterActions(
+            structKeyBridge(bridge, id),
+            { id, type: `table.${id}`, compatibilityDate: block.compatibilityDate },
+            id === "actions" ? "\u4E0A\u65B9\u64CD\u4F5C" : "\u4E0B\u65B9\u64CD\u4F5C",
+            withToolbarVars(configure),
+            []
+          );
+        }
+        const columns2 = Array.isArray(t.columns) ? t.columns : [];
+        const col = columns2.find((c) => c.id === id);
+        if (!col) {
+          return `enter_node failed: no column or action bar with id "${id}". A table's enterable children are its row-action columns (see list_columns) plus "actions" / "bottomActions" (its toolbar / bottom action bars).`;
+        }
+        const entry = findColumn(col.type, col.compatibilityDate);
+        const edge = entry?.edges?.[0];
+        if (!edge || edge.host !== "actions") {
+          return `enter_node: column "${id}" (${col.type}) has no embedded host to drill into. Configure it with the table's column tools instead.`;
+        }
+        return enterActions(
+          arrayItemBridge(bridge, "columns", id),
+          { id, type: col.type, compatibilityDate: col.compatibilityDate },
+          "\u64CD\u4F5C\u5217",
+          withRowVars(configure),
+          []
+        );
+      }
+    });
+    const table = bridge.read() ?? {};
+    const columns = Array.isArray(table.columns) ? table.columns : [];
+    const result = {
+      scope: scope(),
+      entered: { id: block.id, node: `${block.type}@${block.compatibilityDate}`, name: label },
+      toolFamily: "table",
+      summary: {
+        columnIds: columns.map((c) => c.id),
+        dataSourceConfigured: table.dataSource !== void 0,
+        queryConfigured: table.query !== void 0
+      },
+      drillable: [],
+      hint: '\u7528 describe_general_settings / list_available_column_types / list_columns \u7B49\u6309\u9700\u4E86\u89E3\u4E0E\u914D\u7F6E\uFF1B\u641C\u7D22\u6761\u4EF6\u7528 *_field* \u5DE5\u5177\u3002\u64CD\u4F5C\u6309\u94AE\uFF1Aenter_node "actions" / "bottomActions" \u8FDB\u5165\u5DE5\u5177\u680F / \u5E95\u90E8\u64CD\u4F5C\u680F\uFF0C\u6216 enter_node \u4E00\u4E2A\u64CD\u4F5C\u5217\u8FDB\u5165\u5176\u6309\u94AE\u3002\u914D\u7F6E\u5B8C\u6210\u540E\u8C03\u7528 leave_node \u8FD4\u56DE\u3002'
+    };
+    return attachManual(result, "table");
+  }
+  function enterForm(bridge, block, configure) {
+    const family = createFormFieldTools({
+      read: () => bridge.read(),
+      write: (next) => bridge.write(next),
+      configure,
+      genUuid: deps.genUuid
+    });
+    const label = blockLabel(block);
+    frames.push({
+      kind: "form",
+      label,
+      node: { id: block.id, type: block.type, compatibilityDate: block.compatibilityDate },
+      family,
+      configure,
+      eventTargets: () => {
+        const form2 = bridge.read() ?? {};
+        if (typeof form2.id !== "string") return [];
+        const ops = formMetadata.operations;
+        return [{ id: form2.id, kind: "form", name: "\u8868\u5355", operations: ops.map((o) => ({ id: o.id, name: o.name })) }];
+      },
+      recap: () => {
+        const f = bridge.read() ?? {};
+        return { fields: (Array.isArray(f.fields) ? f.fields : []).map((x) => ({ id: x.id, type: x.type })) };
+      },
+      // A form's fields are its enterable children: a field.table (table
+      // family), a field.list/.collapsible/.tabs sub-form (form family), a
+      // field.actions (actions family). Data-driven off the field's edge.
+      enter: (id) => {
+        const f = bridge.read() ?? {};
+        const fields2 = Array.isArray(f.fields) ? f.fields : [];
+        const field = fields2.find((x) => x.id === id);
+        if (!field) {
+          return `enter_node failed: no field with id "${id}". Call list_fields to see current fields.`;
+        }
+        const entry = findField(field.type, field.compatibilityDate);
+        const edge = entry?.edges?.[0];
+        if (!edge) {
+          return `enter_node: field "${id}" (${field.type}) has no embedded host to drill into. Configure it with the form field tools instead.`;
+        }
+        const fieldConfigure = applyEdgeScope(edge, configure);
+        switch (edge.host) {
+          case "table":
+            return enterTable(arrayItemBridge(bridge, "fields", id, edge.key), { id, type: field.type, compatibilityDate: field.compatibilityDate }, fieldConfigure);
+          case "form":
+            if (edge.itemSlot) {
+              return enterTabs(bridge, "fields", id, edge, { id, type: field.type, compatibilityDate: field.compatibilityDate }, fieldConfigure);
+            }
+            return enterForm(arrayItemBridge(bridge, "fields", id, edge.key), { id, type: field.type, compatibilityDate: field.compatibilityDate }, fieldConfigure);
+          case "actions":
+            return enterActions(
+              arrayItemBridge(bridge, "fields", id),
+              { id, type: field.type, compatibilityDate: field.compatibilityDate },
+              typeof field.displayName === "string" && field.displayName || "\u64CD\u4F5C\u5B57\u6BB5",
+              withFormVars(fieldConfigure),
+              []
+            );
+          default:
+            return `enter_node: field "${id}" embeds ${edge.host}, which the cursor can't enter yet.`;
+        }
+      }
+    });
+    const form = bridge.read() ?? {};
+    const fields = Array.isArray(form.fields) ? form.fields : [];
+    const result = {
+      scope: scope(),
+      entered: { id: block.id, node: `${block.type}@${block.compatibilityDate}`, name: label },
+      toolFamily: "form",
+      summary: { fieldIds: fields.map((f) => f.id) },
+      drillable: [],
+      hint: "\u7528 list_available_field_types / describe_specific_field_type / list_fields \u7B49\u6309\u9700\u4E86\u89E3\u4E0E\u914D\u7F6E\uFF1Binsert_field \u65B0\u589E\u5B57\u6BB5\u540E\u7528 place_field \u653E\u7F6E\uFF1BCEL \u7528 describe_form_settings \u67E5\u770B\u4F5C\u7528\u57DF\u3002\u5D4C\u5957\u5B57\u6BB5\uFF08\u8868\u683C / \u5217\u8868 / \u6298\u53E0 / \u6807\u7B7E\u9875 / \u64CD\u4F5C\uFF09\u7528 enter_node \u94BB\u5165\u3002\u914D\u7F6E\u5B8C\u6210\u540E\u8C03\u7528 leave_node \u8FD4\u56DE\u3002"
+    };
+    return attachManual(result, "form");
+  }
+  function enterSlot(bridge, node, label, configure, ownerTargets = []) {
+    frames.push({
+      kind: "slot",
+      label,
+      node,
+      family: slotFamily(bridge, configure),
+      slotBridge: bridge,
+      configure,
+      ...ownerTargets.length > 0 ? { eventTargets: () => ownerTargets } : {}
+    });
+    const slot = bridge.read() ?? { blocks: [], layouts: [] };
+    const blocks = Array.isArray(slot.blocks) ? slot.blocks : [];
+    return {
+      scope: scope(),
+      entered: { id: node.id, node: `${node.type}@${node.compatibilityDate}`, name: label },
+      toolFamily: "page-slot",
+      summary: { blockIds: blocks.map((b) => b.id) },
+      drillable: [],
+      hint: "\u8FD9\u662F\u4E00\u4E2A\u9875\u9762\u69FD\uFF08page-slot\uFF09\u3002\u7528 list_available_block_types / list_blocks / insert_block / place_block \u5728\u5176\u5185\u90E8\u642D\u5757\uFF0C\u53EF\u7EE7\u7EED enter_node \u94BB\u5165\u66F4\u6DF1\u7684\u5BB9\u5668\u3002\u914D\u7F6E\u5B8C\u6210\u540E\u8C03\u7528 leave_node \u8FD4\u56DE\u3002"
+    };
+  }
+  function enterTabs(parent, arrayKey, containerId, edge, node, configure) {
+    const containerBridge = arrayKey === "__self__" ? parent : arrayItemBridge(parent, arrayKey, containerId);
+    const label = "\u6807\u7B7E\u9875";
+    const listPanes = {
+      name: "list_panes",
+      description: "Return the tabs container's panes \u2014 each with its `id` and label. Use enter_node with a pane id to drill into that pane's content.",
+      inputJsonSchema: { type: "object", properties: {}, additionalProperties: false },
+      execute: () => {
+        const c2 = containerBridge.read() ?? {};
+        const panes2 = Array.isArray(c2[edge.key]) ? c2[edge.key] : [];
+        return panes2.map((p, i) => ({ id: p.id, index: i, label: p.label ?? null }));
+      }
+    };
+    frames.push({
+      kind: "tabs",
+      label,
+      node,
+      family: [listPanes],
+      configure,
+      recap: () => {
+        const c2 = containerBridge.read() ?? {};
+        const panes2 = Array.isArray(c2[edge.key]) ? c2[edge.key] : [];
+        return { panes: panes2.map((p) => ({ id: p.id })) };
+      },
+      enter: (paneId) => {
+        const c2 = containerBridge.read() ?? {};
+        const panes2 = Array.isArray(c2[edge.key]) ? c2[edge.key] : [];
+        const idx = panes2.findIndex((p) => p.id === paneId);
+        if (idx < 0) {
+          return `enter_node failed: no pane with id "${paneId}". Call list_panes to see pane ids.`;
+        }
+        const paneBridge = {
+          read: () => {
+            const cc = containerBridge.read() ?? {};
+            const ps = cc[edge.key] ?? [];
+            return ps[idx]?.[edge.itemSlot];
+          },
+          write: (next) => {
+            const cc = containerBridge.read() ?? {};
+            const ps = (cc[edge.key] ?? []).map((p, i) => i === idx ? { ...p, [edge.itemSlot]: next } : p);
+            containerBridge.write({ ...cc, [edge.key]: ps });
+          }
+        };
+        const paneNode = { id: paneId, type: `${node.type}#pane`, compatibilityDate: node.compatibilityDate };
+        if (edge.host === "form") {
+          return enterForm(paneBridge, paneNode, configure);
+        }
+        return enterSlot(paneBridge, paneNode, "\u6807\u7B7E\u9875", configure);
+      }
+    });
+    const c = containerBridge.read() ?? {};
+    const panes = Array.isArray(c[edge.key]) ? c[edge.key] : [];
+    return {
+      scope: scope(),
+      entered: { id: node.id, node: `${node.type}@${node.compatibilityDate}`, name: label },
+      toolFamily: "tabs",
+      summary: { paneIds: panes.map((p) => p.id) },
+      drillable: [],
+      hint: "\u8FD9\u662F\u4E00\u4E2A\u591A\u6807\u7B7E\u5BB9\u5668\u3002\u7528 list_panes \u67E5\u770B\u5404\u6807\u7B7E\u9875\uFF0C\u518D enter_node \u4E00\u4E2A\u6807\u7B7E\u9875 id \u94BB\u5165\u5176\u5185\u5BB9\u914D\u7F6E\u3002\u914D\u7F6E\u5B8C\u6210\u540E\u8C03\u7528 leave_node \u8FD4\u56DE\u3002"
+    };
+  }
+  function enterActions(bridge, node, label, configure, ownerTargets) {
+    const family = createActionsAiTools({
+      read: () => bridge.read(),
+      write: (next) => bridge.write(next),
+      configure,
+      genUuid: deps.genUuid,
+      eventTargets: () => aggregateEventTargets(ownerTargets)
+    });
+    frames.push({
+      kind: "actions",
+      label,
+      node,
+      family,
+      configure,
+      ...ownerTargets.length > 0 ? { eventTargets: () => ownerTargets } : {},
+      recap: () => {
+        const c2 = bridge.read() ?? {};
+        return { items: (Array.isArray(c2.items) ? c2.items : []).map((it) => ({ id: it.id })) };
+      },
+      // A modal.layout button's inner slot is the one enterable child of an
+      // actions bar — the modal-recursion win (design §1.3).
+      enter: (id) => {
+        const c2 = bridge.read() ?? {};
+        const items2 = Array.isArray(c2.items) ? c2.items : [];
+        let found;
+        for (let i = 0; i < items2.length; i++) {
+          if (items2[i].id === id) {
+            found = { path: "top", topIdx: i, item: items2[i] };
+            break;
+          }
+          const subs = items2[i].items;
+          if (Array.isArray(subs)) {
+            const si = subs.findIndex((s) => s.id === id);
+            if (si >= 0) {
+              found = { path: "sub", topIdx: i, subIdx: si, item: subs[si] };
+              break;
+            }
+          }
+        }
+        if (!found) {
+          return `enter_node failed: no button with id "${id}". Call list_action_items to see ids.`;
+        }
+        const action = found.item.action;
+        if (!action) {
+          return `enter_node: item "${id}" has no button action to drill into.`;
+        }
+        const bEdge = findButton(action.type, action.compatibilityDate)?.edges?.[0];
+        if (!bEdge || bEdge.host !== "slot") {
+          return `enter_node: button "${id}" (${action.type}) has no inner slot to drill into. Configure it with configure_button / set_action_item.`;
+        }
+        const slotKey = bEdge.key;
+        const slotBridge = {
+          read: () => {
+            const cc = bridge.read() ?? {};
+            const its = cc.items ?? [];
+            const it = found.path === "top" ? its[found.topIdx] : its[found.topIdx]?.items?.[found.subIdx];
+            return it?.action?.[slotKey];
+          },
+          write: (next) => {
+            const cc = bridge.read() ?? {};
+            const its = (cc.items ?? []).map((it, i) => {
+              if (found.path === "top") {
+                if (i !== found.topIdx) return it;
+                return { ...it, action: { ...it.action, [slotKey]: next } };
+              }
+              if (i !== found.topIdx) return it;
+              const subs = (it.items ?? []).map((s, si) => si === found.subIdx ? { ...s, action: { ...s.action, [slotKey]: next } } : s);
+              return { ...it, items: subs };
+            });
+            bridge.write({ ...cc, items: its });
+          }
+        };
+        return enterSlot(
+          slotBridge,
+          { id, type: action.type, compatibilityDate: action.compatibilityDate ?? "" },
+          bEdge.label,
+          configure,
+          [{ id, kind: "modal", name: "\u5F39\u7A97\u6309\u94AE", operations: [{ id: "close", name: "\u5173\u95ED\u5F39\u7A97" }] }]
+        );
+      }
+    });
+    const c = bridge.read() ?? {};
+    const items = Array.isArray(c.items) ? c.items : [];
+    return attachManual({
+      scope: scope(),
+      entered: { id: node.id, node: `${node.type}@${node.compatibilityDate}`, name: label },
+      toolFamily: "actions",
+      summary: { itemIds: items.map((it) => it.id) },
+      drillable: [],
+      hint: "\u8FD9\u662F\u4E00\u7EC4\u64CD\u4F5C\u6309\u94AE\u3002\u7528 list_available_button_types / describe_specific_button_type \u9009\u578B\uFF0Cinsert_action_group / insert_button \u65B0\u589E\uFF0Cconfigure_button \u914D\u7F6E\u52A8\u4F5C\u4E0E\u89E6\u53D1\uFF08\u5148 describe_event_targets / list_operations \u67E5\u76EE\u6807\u4E0E\u64CD\u4F5C\uFF09\uFF0Cset_action_item \u914D\u6309\u94AE\u5916\u89C2\u3002\u6A21\u6001\u7A97\u53E3\u6309\u94AE\u53EF enter_node \u94BB\u5165\u5176\u5F39\u7A97\u5185\u5BB9\u3002\u914D\u7F6E\u5B8C\u6210\u540E\u8C03\u7528 leave_node \u8FD4\u56DE\u3002"
+    }, "actions");
+  }
+  const enterNode = {
+    name: "enter_node",
+    description: 'Descend the scope cursor one level into a DIRECT child so its own tool family activates. From a page/slot: a block (table / form / card / loop / tabs / actions). From a table: a row-action column, or "actions" / "bottomActions" (its action bars). From a form: a nested field (table / list / collapsible / tabs / actions). From an actions bar: a modal.layout button (its inner slot). From a tabs container: one pane (see list_panes). Pass the target\'s `id`. Reach deep targets by repeated enter_node, one level at a time. Returns a light orientation (breadcrumb, node identity, value summary, activated tool family, and \u2014 the first time you enter a host kind \u2014 its operating manual). Use leave_node to come back up.',
+    inputJsonSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The child id to enter (from list_blocks / list_columns / list_fields / list_action_items / list_panes)." }
+      },
+      required: ["id"],
+      additionalProperties: false
+    },
+    execute: (input) => {
+      const cur = current();
+      const { id } = input ?? {};
+      if (typeof id !== "string" || id.length === 0) {
+        return "enter_node failed: `id` must be a non-empty string.";
+      }
+      if (cur.slotBridge) {
+        const slot = cur.slotBridge.read();
+        const block = slot?.blocks?.find((b) => b.id === id);
+        if (!block) {
+          return `enter_node failed: no block with id "${id}". Call list_blocks to see current blocks.`;
+        }
+        const entry = findBlock(block.type, block.compatibilityDate);
+        const edge = entry?.edges?.[0];
+        if (!edge) {
+          return `enter_node: block "${id}" is a ${block.type} \u2014 a leaf block with nothing to configure by drilling in. Use describe_specific_block_type / place_block / delete_blocks from the current slot instead.`;
+        }
+        const childBase = cur.configure;
+        switch (edge.host) {
+          case "table":
+            return enterTable(arrayItemBridge(cur.slotBridge, "blocks", id, edge.key), block, childBase);
+          case "form":
+            return enterForm(arrayItemBridge(cur.slotBridge, "blocks", id, edge.key), block, childBase);
+          case "slot": {
+            const childConfigure = applyEdgeScope(edge, childBase);
+            if (edge.itemSlot) {
+              return enterTabs(cur.slotBridge, "blocks", id, edge, { id: block.id, type: block.type, compatibilityDate: block.compatibilityDate }, childConfigure);
+            }
+            return enterSlot(arrayItemBridge(cur.slotBridge, "blocks", id, edge.key), { id: block.id, type: block.type, compatibilityDate: block.compatibilityDate }, blockLabel(block), childConfigure);
+          }
+          case "actions": {
+            const ops = (entry?.metadata).operations;
+            const ownerTargets = ops && ops.length > 0 ? [{ id: block.id, kind: "host", name: blockLabel(block), operations: ops.map((o) => ({ id: o.id, name: o.name, ...o.compatibilityDate ? { compatibilityDate: o.compatibilityDate } : {} })) }] : [];
+            const childConfigure = ops && ops.length > 0 ? withNodeVar(childBase) : childBase;
+            return enterActions(arrayItemBridge(cur.slotBridge, "blocks", id, edge.key), { id: block.id, type: block.type, compatibilityDate: block.compatibilityDate }, blockLabel(block), childConfigure, ownerTargets);
+          }
+          default:
+            return `enter_node: block "${id}" embeds ${edge.host}, which the cursor can't enter yet.`;
+        }
+      }
+      if (cur.enter) return cur.enter(id);
+      return `enter_node failed: the current scope (${scope()}) has no further enterable children. Configure it with the listed tools, or call leave_node to go up.`;
+    }
+  };
+  const leaveNode = {
+    name: "leave_node",
+    description: "Ascend the scope cursor one level back to the parent scope, re-activating its tool family. Returns the parent breadcrumb and a light recap of its children.",
+    inputJsonSchema: { type: "object", properties: {}, additionalProperties: false },
+    execute: () => {
+      if (frames.length <= 1) {
+        return `leave_node: already at the top scope (${scope()}); nothing to leave.`;
+      }
+      const left = frames.pop();
+      const parent = current();
+      const recap = { scope: scope(), left: left.label, backTo: parent.label };
+      if (parent.slotBridge) {
+        const slot = parent.slotBridge.read();
+        const blocks = slot?.blocks ?? [];
+        recap.blocks = blocks.map((b) => ({ id: b.id, type: b.type, name: blockLabel(b) }));
+      } else if (parent.recap) {
+        Object.assign(recap, parent.recap());
+      }
+      return recap;
+    }
+  };
+  const genUuidTool = {
+    name: "gen_uuid",
+    description: 'Mint a fresh UUID from the harness. You almost never need this: the harness assigns every id itself (insert_block / insert_field / insert_button / \u2026 return the id, and configure_button backfills a trigger row that omits one). Call it ONLY when you must author an id you then reference in the same write \u2014 chiefly a trigger row `id` whose step output a LATER row reads via `steps["<id>"]`. Never invent an id yourself (e.g. all-zeros) \u2014 collisions there break the steps address. Returns `{ uuid }`.',
+    inputJsonSchema: { type: "object", properties: {}, additionalProperties: false },
+    execute: () => ({ uuid: deps.genUuid() })
+  };
+  function tools() {
+    return [...current().family, enterNode, leaveNode, genUuidTool];
+  }
+  function reset() {
+    frames = [pageFrame];
+  }
+  return { tools, reset, scope };
+}