@json-layout/core 2.8.2 → 2.9.1

package/types/state/state-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-node.d.ts","sourceRoot":"","sources":["../../src/state/state-node.js"],"names":[],"mappings":"AAkRA;;;;;;;;;;;GAWG;AACH,4CAXW,OAAO,aAAa,EAAE,kBAAkB,EAAE,cAC1C,OAAO,yBAAyB,EAAE,UAAU,QAC5C,GAAG,WACH,OAAO,YAAY,EAAE,gBAAgB,WACrC,OAAO,oBAAoB,EAAE,OAAO,UACpC,OAAO,yBAAyB,EAAE,cAAc,aAChD,MAAM,CAAC,MAAM,EAAE,OAAO,KAAK,EAAE,gBAAgB,CAAC,YAC9C,OAAO,iBACP,OAAO,qBAAqB,EAAE,uBAAuB,GAAG,IAAI,GAC1D,GAAG,CAsBf;AAiCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yCAlBW,OAAO,YAAY,EAAE,sBAAsB,iBAC3C,OAAO,YAAY,EAAE,gBAAgB,kBACrC,OAAO,aAAa,EAAE,cAAc,OACpC,MAAM,GAAG,MAAM,WACf,MAAM,iBACN,MAAM,GAAG,IAAI,YACb,MAAM,kBACN,MAAM,GAAG,IAAI,YACb,OAAO,aAAa,EAAE,YAAY,mBAClC,OAAO,yBAAyB,EAAE,KAAK,GAAG,IAAI,iBAC9C,OAAO,oBAAoB,EAAE,OAAO,QACpC,GAAG,iBACH,OAAO,qBAAqB,EAAE,uBAAuB,GAAG,IAAI,mBAC5D,OAAO,YAAY,EAAE,eAAe,cACpC,MAAM,eACN,OAAO,YAAY,EAAE,SAAS,GAC5B,OAAO,YAAY,EAAE,SAAS,CAipB1C;AAx9BM,qCALI,OAAO,UACP,OAAO,yBAAyB,EAAE,cAAc,WAChD,OAAO,YAAY,EAAE,gBAAgB,GACnC,OAAO,CAMnB;AAs9BD,uFAAuF;AACvF,iCADW,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,KAAK,GAAG,CAgBjF;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAFU,CAAC,YAAY,EAAE,GAAG,EAAE,EAAE,aAAa,EAAE,OAAO,yBAAyB,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,yBAAyB,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,KAAK,GAAG,CAkC5M"}
+{"version":3,"file":"state-node.d.ts","sourceRoot":"","sources":["../../src/state/state-node.js"],"names":[],"mappings":"AAkRA;;;;;;;;;;;GAWG;AACH,4CAXW,OAAO,aAAa,EAAE,kBAAkB,EAAE,cAC1C,OAAO,yBAAyB,EAAE,UAAU,QAC5C,GAAG,WACH,OAAO,YAAY,EAAE,gBAAgB,WACrC,OAAO,oBAAoB,EAAE,OAAO,UACpC,OAAO,yBAAyB,EAAE,cAAc,aAChD,MAAM,CAAC,MAAM,EAAE,OAAO,KAAK,EAAE,gBAAgB,CAAC,YAC9C,OAAO,iBACP,OAAO,qBAAqB,EAAE,uBAAuB,GAAG,IAAI,GAC1D,GAAG,CAsBf;AA0CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yCAlBW,OAAO,YAAY,EAAE,sBAAsB,iBAC3C,OAAO,YAAY,EAAE,gBAAgB,kBACrC,OAAO,aAAa,EAAE,cAAc,OACpC,MAAM,GAAG,MAAM,WACf,MAAM,iBACN,MAAM,GAAG,IAAI,YACb,MAAM,kBACN,MAAM,GAAG,IAAI,YACb,OAAO,aAAa,EAAE,YAAY,mBAClC,OAAO,yBAAyB,EAAE,KAAK,GAAG,IAAI,iBAC9C,OAAO,oBAAoB,EAAE,OAAO,QACpC,GAAG,iBACH,OAAO,qBAAqB,EAAE,uBAAuB,GAAG,IAAI,mBAC5D,OAAO,YAAY,EAAE,eAAe,cACpC,MAAM,eACN,OAAO,YAAY,EAAE,SAAS,GAC5B,OAAO,YAAY,EAAE,SAAS,CAipB1C;AAj+BM,qCALI,OAAO,UACP,OAAO,yBAAyB,EAAE,cAAc,WAChD,OAAO,YAAY,EAAE,gBAAgB,GACnC,OAAO,CAMnB;AA+9BD,uFAAuF;AACvF,iCADW,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,KAAK,GAAG,CAgBjF;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAFU,CAAC,YAAY,EAAE,GAAG,EAAE,EAAE,aAAa,EAAE,OAAO,yBAAyB,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,yBAAyB,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,KAAK,GAAG,CAkC5M"}

package/types/state/utils/urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../../src/state/utils/urls.js"],"names":[],"mappings":"AAEO,6BAA4B,MAAM,WAAoB,MAAM,OAIlE"}
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../../src/state/utils/urls.js"],"names":[],"mappings":"AAEO,6BAA4B,MAAM,WAAoB,MAAM,OAMlE"}

package/types/utils/json-pointer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file JSON pointer traversal, shared by the compilation step and the webmcp tools
+ * @description Pointers are produced by concatenation in the compilation step
+ * (`${refPointerPrefix}/properties/${propertyKey}` and similar), their segments are
+ * therefore consumed raw: they are deliberately not unescaped as RFC 6901 would
+ * prescribe, so that resolution stays symmetric with the way pointers are built.
+ */
+/**
+ * Resolve the fragment part of a JSON pointer (what follows the '#') in a schema or any object.
+ * @param {unknown} root
+ * @param {string} fragment - e.g. '/properties/address/items', leading and empty segments are ignored
+ * @returns {{found: true, value: unknown} | {found: false, path: string[]}} - the resolved value, or
+ * the segments consumed up to and including the missing one, to report where the resolution failed
+ */
+export function resolvePointerFragment(root: unknown, fragment: string): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+    path: string[];
+};
+//# sourceMappingURL=json-pointer.d.ts.map

package/types/utils/json-pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-pointer.d.ts","sourceRoot":"","sources":["../../src/utils/json-pointer.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,6CALW,OAAO,YACP,MAAM,GACJ;IAAC,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAC,GAAG;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAC,CAgB1E"}

package/types/webmcp/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @typedef {object} WebMCPOptions
+ * @property {string} [prefixName] - Prefix for all tool names
+ * @property {string} [dataTitle] - Title used in descriptions (default: 'form')
+ * @property {boolean} [includeFillFormSkill] - Include the fillFormSkill tool (default: false)
+ * @property {boolean} [includeSubAgent] - Include a subagent_ tool wrapping all form tools (default: false)
+ */
 /**
  * WebMCP class that provides MCP tool descriptors for a StatefulLayout instance
  */
@@ -22,16 +29,6 @@ export class WebMCP {
      * @type {string}
      */
     readonly _dataTitle: string;
-    /**
-     * @readonly
-     * @type {"small"|"medium"|"large"}
-     */
-    readonly _complexity: "small" | "medium" | "large";
-    /**
-     * @readonly
-     * @type {object | null}
-     */
-    readonly _schema: object | null;
     /**
      * @readonly
      * @type {boolean}
@@ -46,6 +43,19 @@ export class WebMCP {
      * @type {string[]}
      */
     _registeredTools: string[];
+    /**
+     * memory of the last suggestions per node path, used by setFieldValue's suggestionIndex
+     * @readonly
+     * @type {SuggestionsStore}
+     */
+    readonly _suggestionsStore: SuggestionsStore;
+    /**
+     * Variant lists already sent to the agent. Never cleared on a write: a schema's branches
+     * are a constant, so unlike memorized suggestions nothing about the data can invalidate
+     * them.
+     * @type {VariantsMemo}
+     */
+    _variantsMemo: VariantsMemo;
     /**
      * @param {string} name
      * @returns {string}
@@ -64,6 +74,7 @@ export class WebMCP {
      */
     unregisterTools(): Promise<void>;
 }
+export type ToolDescriptor = import("@mcp-b/webmcp-types").ToolDescriptor;
 export type WebMCPOptions = {
     /**
      * - Prefix for all tool names
@@ -73,10 +84,6 @@ export type WebMCPOptions = {
      * - Title used in descriptions (default: 'form')
      */
     dataTitle?: string | undefined;
-    /**
-     * - The original JSON schema
-     */
-    schema?: object | undefined;
     /**
      * - Include the fillFormSkill tool (default: false)
      */
@@ -86,5 +93,6 @@ export type WebMCPOptions = {
      */
     includeSubAgent?: boolean | undefined;
 };
-export type ToolDescriptor = import("@mcp-b/webmcp-types").ToolDescriptor;
+import { SuggestionsStore } from './suggestions-store.js';
+import { VariantsMemo } from './variants-memo.js';
 //# sourceMappingURL=index.d.ts.map

package/types/webmcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webmcp/index.js"],"names":[],"mappings":"AA4DA;;GAEG;AACH;IAgDE;;;OAGG;IACH,4BAHW,OAAO,mBAAmB,EAAE,cAAc,YAC1C,aAAa,EAUvB;IA3DD;;;OAGG;IACH,0BAFU,OAAO,mBAAmB,EAAE,cAAc,CAErC;IAEf;;;OAGG;IACH,sBAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,qBAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,sBAFU,OAAO,GAAC,QAAQ,GAAC,OAAO,CAEvB;IAEX;;;OAGG;IACH,kBAFU,MAAM,GAAG,IAAI,CAET;IAEd;;;OAGG;IACH,gCAFU,OAAO,CAEY;IAE7B;;;OAGG;IACH,2BAFU,OAAO,CAEO;IAExB;;OAEG;IACH,kBAFU,MAAM,EAAE,CAEG;IAgBrB;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,YAFa,cAAc,EAAE,CA0O5B;IAED;;OAEG;IACH,iBAFa,OAAO,CAAC,IAAI,CAAC,CAczB;IAED;;OAEG;IACH,mBAFa,OAAO,CAAC,IAAI,CAAC,CAYzB;CACF;;;;;;;;;;;;;;;;;;;;;;;6BAjYa,OAAO,qBAAqB,EAAE,cAAc"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webmcp/index.js"],"names":[],"mappings":"AA2CA;;;;;;GAMG;AAEH;;GAEG;AACH;IAmDE;;;OAGG;IACH,4BAHW,OAAO,mBAAmB,EAAE,cAAc,YAC1C,aAAa,EAQvB;IA5DD;;;OAGG;IACH,0BAFU,OAAO,mBAAmB,EAAE,cAAc,CAErC;IAEf;;;OAGG;IACH,sBAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,qBAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,gCAFU,OAAO,CAEY;IAE7B;;;OAGG;IACH,2BAFU,OAAO,CAEO;IAExB;;OAEG;IACH,kBAFU,MAAM,EAAE,CAEG;IAErB;;;;OAIG;IACH,4BAFU,gBAAgB,CAEgB;IAE1C;;;;;OAKG;IACH,eAFU,YAAY,CAEY;IAclC;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,YAFa,cAAc,EAAE,CAwP5B;IAED;;OAEG;IACH,iBAFa,OAAO,CAAC,IAAI,CAAC,CAczB;IAED;;OAEG;IACH,mBAFa,OAAO,CAAC,IAAI,CAAC,CAYzB;CACF;6BApYa,OAAO,qBAAqB,EAAE,cAAc;;;;;;;;;;;;;;;;;;;iCAHzB,wBAAwB;6BAC5B,oBAAoB"}

package/types/webmcp/project.d.ts

@@ -1,28 +1,91 @@
 /**
- * @typedef {{
- *   path: string,
- *   type: string,
- *   data: unknown,
- *   title?: string,
- *   label?: string,
- *   help?: string,
- *   error?: string,
- *   required?: boolean,
- *   readOnly?: boolean,
- *   modified?: boolean,
- *   constraints?: Record<string, unknown>,
- *   variants?: Array<{index: number, title: string}>,
- *   selectedVariant?: number,
- *   children?: Array<ProjectedNode>,
- *   getSuggestions?: boolean
- * }} ProjectedNode
+ * Help is authored as HTML for a browser. An agent reads text, so the markup is pure cost —
+ * `&#39;` is not merely wasted, it is harder to read than the apostrophe it stands for —
+ * and the newlines between block tags break the one-line-per-node markdown the state tree
+ * is made of.
+ * @param {string} html
+ * @returns {string}
  */
+export function helpToText(html: string): string;
 /**
+ * Which nodes are currently rendered, by path. A node hidden by a layout `if` stays in
+ * the tree as comp "none", so what a write changes there is visibility rather than the
+ * set of paths — comparing paths alone would report nothing. A node governed by a schema
+ * if/then is the other way round: it is absent until the condition holds, so the set of
+ * paths is all there is to compare. Recording both facts lets one diff serve both.
  * @param {import('../state/types.js').StateNode} node
- * @param {import('../state/index.js').StatefulLayout} statefulLayout
- * @returns {ProjectedNode}
+ * @param {Map<string, {comp: string, owns: boolean}>} [into]
+ * @returns {Map<string, {comp: string, owns: boolean}>}
+ */
+export function visibilitySnapshot(node: import("../state/types.js").StateNode, into?: Map<string, {
+    comp: string;
+    owns: boolean;
+}>): Map<string, {
+    comp: string;
+    owns: boolean;
+}>;
+/**
+ * What a write turned visible or invisible.
+ *
+ * A field can arrive two ways: a layout `if` toggles a node that already exists between
+ * comp "none" and its real component, while a schema-level if/then has no node at all
+ * until the condition holds and then creates one. Both are the same event to an agent —
+ * something it must now fill that it could not before — so both count.
+ *
+ * `activated` is the variant selector a write just switched, if any. Activating a variant
+ * replaces a whole branch, and setFieldValue already lists the branch it activated;
+ * counting those nodes here too would print the same subtree twice.
+ * @param {Map<string, {comp: string, owns: boolean}>} before
+ * @param {Map<string, {comp: string, owns: boolean}>} after
+ * @param {string} [activated] - fullKey of a variant selector whose subtree is reported elsewhere
+ * @returns {{ revealed: string[], hidden: string[] }}
+ */
+export function diffVisibility(before: Map<string, {
+    comp: string;
+    owns: boolean;
+}>, after: Map<string, {
+    comp: string;
+    owns: boolean;
+}>, activated?: string): {
+    revealed: string[];
+    hidden: string[];
+};
+/**
+ * @param {{ revealed: string[], hidden: string[] }} diff
+ * @returns {string}
+ */
+export function formatVisibilityDiff(diff: {
+    revealed: string[];
+    hidden: string[];
+}): string;
+/**
+ * Render a value for the agent: in full when it is small enough to be worth reading,
+ * otherwise named with its kind and size so the agent knows what is there without paying
+ * for it. It can always read a node's own subtree with describeState.
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+export function abbreviateValue(value: unknown): string | undefined;
+/**
+ * Whether this field's options cannot be fetched yet because the request that would
+ * produce them cannot be built.
+ *
+ * The state layer resolves a remote list's URL up front and stores it as `itemsCacheKey`;
+ * when the expression THROWS — because it reads a field nobody has filled in — the key is
+ * null. That is a different situation from "your query matched nothing" and from "this
+ * field has no list", and all three used to arrive as the same four words. The review that
+ * prompted this put 45% of the option lists across thirty real applications in this state
+ * until some other field is written first, so it is the common case, not an edge.
+ * @param {import('../state/types.js').StateNode} node
+ * @returns {boolean}
  */
-export function projectNode(node: import("../state/types.js").StateNode, statefulLayout: import("../state/index.js").StatefulLayout): ProjectedNode;
+export function suggestionsBlocked(node: import("../state/types.js").StateNode): boolean;
+/**
+ * The expression a blocked list is waiting on, so the answer can say what to go and set.
+ * @param {import('../state/types.js').StateNode} node
+ * @returns {string|undefined}
+ */
+export function suggestionsSource(node: import("../state/types.js").StateNode): string | undefined;
 /**
  * Project a single field result for slim mutation responses
  * @param {import('../state/types.js').StateNode} node
@@ -35,77 +98,135 @@ export function projectFieldResult(node: import("../state/types.js").StateNode,
     data: unknown;
     error?: string;
 };
-/**
- * @param {import('../state/types.js').StateTree} stateTree
- * @param {import('../state/index.js').StatefulLayout} statefulLayout
- * @returns {{ root: ProjectedNode, valid: boolean }}
- */
-export function projectStateTree(stateTree: import("../state/types.js").StateTree, statefulLayout: import("../state/index.js").StatefulLayout): {
-    root: ProjectedNode;
-    valid: boolean;
-};
 /**
  * Format a projected node as a markdown line for LLM-readable output.
  * @param {import('../state/types.js').StateNode} node
  * @param {import('../state/index.js').StatefulLayout} statefulLayout
  * @param {number} [depth]
+ * @param {Record<string, string>} [errorsByPath] - computed on the root node when not given
+ * @param {import('./variants-memo.js').VariantsMemo} [variantsMemo] - when given, a variant
+ * list already printed for the same schema node is replaced by a pointer back to it
  * @returns {string}
  */
-export function projectNodeToMarkdown(node: import("../state/types.js").StateNode, statefulLayout: import("../state/index.js").StatefulLayout, depth?: number): string;
+export function projectNodeToMarkdown(node: import("../state/types.js").StateNode, statefulLayout: import("../state/index.js").StatefulLayout, depth?: number, errorsByPath?: Record<string, string>, variantsMemo?: import("./variants-memo.js").VariantsMemo): string;
 /**
  * Format a state tree as markdown for LLM-readable output.
  * @param {import('../state/types.js').StateTree} stateTree
  * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @param {import('./variants-memo.js').VariantsMemo} [variantsMemo]
  * @returns {string}
  */
-export function projectStateTreeToMarkdown(stateTree: import("../state/types.js").StateTree, statefulLayout: import("../state/index.js").StatefulLayout): string;
+export function projectStateTreeToMarkdown(stateTree: import("../state/types.js").StateTree, statefulLayout: import("../state/index.js").StatefulLayout, variantsMemo?: import("./variants-memo.js").VariantsMemo): string;
 /**
  * Format a mutation result as concise text for LLM-readable output.
  * @param {boolean} valid
- * @param {Array<{path: string, message: string}>} errors
+ * @param {Array<{path: string, message: string}>} errors - errors of the mutated subtree
  * @param {string} [prefix] - optional prefix line (e.g. field info)
+ * @param {number} [otherErrors] - number of errors of the form outside of the mutated subtree
  * @returns {string}
  */
 export function formatMutationResult(valid: boolean, errors: Array<{
     path: string;
     message: string;
-}>, prefix?: string): string;
+}>, prefix?: string, otherErrors?: number): string;
 /**
- * Format field suggestions as markdown for LLM-readable output.
+ * @typedef {{index: number, title: string, key?: string, value?: unknown, valueOmitted?: boolean, valueLength?: number}} ProjectedSuggestion
+ */
+/**
+ * Project suggestions for the tools output: anything but a short scalar is identified by
+ * its title and key alone, and referred to by index instead of copied around.
  * @param {Array<{value: unknown, title: string, key?: string}>} items
- * @returns {string}
+ * @param {number} [baseIndex] - index of the first item, as the store assigned it
+ * @returns {ProjectedSuggestion[]}
  */
-export function formatSuggestions(items: Array<{
+export function projectSuggestions(items: Array<{
     value: unknown;
     title: string;
     key?: string;
-}>): string;
+}>, baseIndex?: number): ProjectedSuggestion[];
 /**
- * @param {import('../state/types.js').StateNode} node
+ * Format field suggestions as markdown for LLM-readable output.
+ * @param {ProjectedSuggestion[]} suggestions
+ * @param {string} [blockedOn] - the expression the list is waiting on, when it has one
+ * @returns {string}
+ */
+export function formatSuggestions(suggestions: ProjectedSuggestion[], blockedOn?: string): string;
+/**
+ * Errors of the whole form, each named by the location it actually applies to.
+ *
+ * A node only carries an error while it is hydrated. A list shows its items in summary
+ * mode, so nothing below an unedited item exists as a node, and every error under it
+ * collapses onto the list — one message, on a path that is not the faulty one. An agent
+ * told "/sections must be integer" knows it is wrong and not where, and retries blind.
+ *
+ * So a node error that is standing in for deeper errors nobody names is replaced by
+ * those errors, addressed by data pointer. Errors a hydrated node does name keep their
+ * form path, which is what the mutation tools expect.
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
  * @returns {Array<{path: string, message: string}>}
  */
-export function collectErrors(node: import("../state/types.js").StateNode): Array<{
+export function collectErrors(statefulLayout: import("../state/index.js").StatefulLayout): Array<{
     path: string;
     message: string;
 }>;
-export type ProjectedNode = {
-    path: string;
-    type: string;
-    data: unknown;
-    title?: string;
-    label?: string;
-    help?: string;
-    error?: string;
-    required?: boolean;
-    readOnly?: boolean;
-    modified?: boolean;
-    constraints?: Record<string, unknown>;
-    variants?: Array<{
-        index: number;
-        title: string;
+/**
+ * Errors of the subtree of a node, and count of the errors of the rest of the form.
+ * @param {import('../state/index.js').StatefulLayout} statefulLayout
+ * @param {import('../state/types.js').StateNode} node
+ * @returns {{ errors: Array<{path: string, message: string}>, otherErrors: number }}
+ */
+export function collectScopedErrors(statefulLayout: import("../state/index.js").StatefulLayout, node: import("../state/types.js").StateNode): {
+    errors: Array<{
+        path: string;
+        message: string;
     }>;
-    selectedVariant?: number;
-    children?: Array<ProjectedNode>;
-    getSuggestions?: boolean;
+    otherErrors: number;
+};
+/**
+ * Suggestion values can be arbitrarily large objects (a whole dataset definition for example),
+ * they are kept out of the tools output and retrieved by index with setFieldValue.
+ */
+/**
+ * Longest value inlined in a suggestion listing. Only scalars are ever inlined: a picker
+ * shows a person titles, not the objects behind them, and an agent picks a row the same
+ * way, by index. Printing a slice of each object cost 61-77% of every suggestion response
+ * measured, for bytes the tool's own description tells the agent never to copy.
+ */
+export const SUGGESTION_VALUE_MAX_LENGTH: 100;
+/**
+ * Longest value rendered in full anywhere the agent reads state. Beyond it a value is
+ * named rather than printed: a picked data-fair dataset is 4-13 KB of column schema, and
+ * echoing it on the write, again in the state tree and a third time from getData was the
+ * single largest cost in the eval — for content the agent applied by index and never had
+ * to handle.
+ */
+export const DISPLAYED_VALUE_MAX_LENGTH: 1000;
+/** Most revealed or hidden paths named before the list is summarised instead. */
+export const REVEALED_PATHS_MAX: 10;
+/**
+ * Longest rendered list of options inlined into a state line instead of being flagged as
+ * something to go and fetch. A closed enum is already in hand — the state layer resolves it
+ * into itemsCacheKey without a request — so flagging it sent the agent on a round trip for
+ * a list nobody had to look up: charts spent two of sixteen calls reading four-const enums,
+ * and sortBy, sortOrder, color and strValue would each have cost another.
+ */
+export const INLINE_ITEMS_MAX_LENGTH: 200;
+/**
+ * Longest help inlined on a node the agent did not ask about. Help is written for someone
+ * looking at a form, where it sits behind a "?" icon and is read on demand; inlined into
+ * every state read it is pushed instead, and portal-page spends 782 characters of SEO
+ * advice on a field no agent in the eval has ever filled. Past this length it is named and
+ * left to be fetched, the same bargain oversized values get. Short help stays inline
+ * whatever the node — it is the kind that changes what an agent writes, such as a negative
+ * height meaning automatic sizing.
+ */
+export const HELP_MAX_LENGTH: 300;
+export type ProjectedSuggestion = {
+    index: number;
+    title: string;
+    key?: string;
+    value?: unknown;
+    valueOmitted?: boolean;
+    valueLength?: number;
 };
 //# sourceMappingURL=project.d.ts.map

package/types/webmcp/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/webmcp/project.js"],"names":[],"mappings":"AA+CA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,kCAJW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,GACxC,aAAa,CAiDzB;AAED;;;;;GAKG;AACH,yCAJW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAWzE;AAED;;;;GAIG;AACH,4CAJW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,GACxC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAOnD;AAED;;;;;;GAMG;AACH,4CALW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,UAC1C,MAAM,GACJ,MAAM,CAoElB;AAED;;;;;GAKG;AACH,sDAJW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,GACxC,MAAM,CAsBlB;AAED;;;;;;GAMG;AACH,4CALW,OAAO,UACP,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,WACtC,MAAM,GACJ,MAAM,CAmBlB;AAED;;;;GAIG;AACH,yCAHW,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,GAClD,MAAM,CAclB;AAED;;;GAGG;AACH,oCAHW,OAAO,mBAAmB,EAAE,SAAS,GACnC,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CAOlD;4BAnQY;IACR,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/webmcp/project.js"],"names":[],"mappings":"AA6EA;;;;;;;GAOG;AACH,iCAHW,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;;;;;GASG;AACH,yCAJW,OAAO,mBAAmB,EAAE,SAAS,SACrC,GAAG,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,CAAC,GACxC,GAAG,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,CAAC,CAStD;AAED;;;;;;;;;;;;;;;GAeG;AACH,uCALW,GAAG,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,CAAC,SAC1C,GAAG,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,CAAC,cAC1C,MAAM,GACJ;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAyBpD;AAED;;;GAGG;AACH,2CAHW;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACtC,MAAM,CAelB;AAED;;;;;;GAMG;AACH,uCAHW,OAAO,GACL,MAAM,GAAG,SAAS,CAQ9B;AAmHD;;;;;;;;;;;;GAYG;AACH,yCAHW,OAAO,mBAAmB,EAAE,SAAS,GACnC,OAAO,CAInB;AAED;;;;GAIG;AACH,wCAHW,OAAO,mBAAmB,EAAE,SAAS,GACnC,MAAM,GAAC,SAAS,CAM5B;AA8BD;;;;;GAKG;AACH,yCAJW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAYzE;AAED;;;;;;;;;GASG;AACH,4CARW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,UAC1C,MAAM,iBACN,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,iBACtB,OAAO,oBAAoB,EAAE,YAAY,GAEvC,MAAM,CAwHlB;AAED;;;;;;GAMG;AACH,sDALW,OAAO,mBAAmB,EAAE,SAAS,kBACrC,OAAO,mBAAmB,EAAE,cAAc,iBAC1C,OAAO,oBAAoB,EAAE,YAAY,GACvC,MAAM,CAsBlB;AAED;;;;;;;GAOG;AACH,4CANW,OAAO,UACP,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,WACtC,MAAM,gBACN,MAAM,GACJ,MAAM,CAsClB;AAED;;GAEG;AAEH;;;;;;GAMG;AACH,0CAJW,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,cACpD,MAAM,GACJ,mBAAmB,EAAE,CAqBjC;AAED;;;;;GAKG;AACH,+CAJW,mBAAmB,EAAE,cACrB,MAAM,GACJ,MAAM,CAiBlB;AAgDD;;;;;;;;;;;;;GAaG;AACH,8CAHW,OAAO,mBAAmB,EAAE,cAAc,GACxC,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CAiClD;AAED;;;;;GAKG;AACH,oDAJW,OAAO,mBAAmB,EAAE,cAAc,QAC1C,OAAO,mBAAmB,EAAE,SAAS,GACnC;IAAE,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAmBnF;AAxuBD;;;GAGG;AACH;;;;;GAKG;AACH,0CAA2C,GAAG,CAAA;AAE9C;;;;;;GAMG;AACH,yCAA0C,IAAI,CAAA;AAE9C,iFAAiF;AACjF,iCAAkC,EAAE,CAAA;AAEpC;;;;;;GAMG;AACH,sCAAuC,GAAG,CAAA;AAuB1C;;;;;;;;GAQG;AACH,8BAA+B,GAAG,CAAA;kCA+frB;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAC"}

package/types/webmcp/resolve.d.ts

@@ -1,6 +1,3 @@
-/**
- * @file Node resolution for webmcp tools
- */
 /**
  * Navigate from a root StateNode to a descendant node by path.
  * @param {import('../state/types.js').StateNode} root
@@ -8,4 +5,11 @@
  * @returns {import('../state/types.js').StateNode|undefined}
  */
 export function resolveNode(root: import("../state/types.js").StateNode, path: string): import("../state/types.js").StateNode | undefined;
+/**
+ * Children of a node as they should be presented to an agent: hidden nodes are removed
+ * and the duplicated activated list item is deduplicated.
+ * @param {import('../state/types.js').StateNode} node
+ * @returns {import('../state/types.js').StateNode[]}
+ */
+export function visibleChildren(node: import("../state/types.js").StateNode): import("../state/types.js").StateNode[];
 //# sourceMappingURL=resolve.d.ts.map

package/types/webmcp/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/webmcp/resolve.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,kCAJW,OAAO,mBAAmB,EAAE,SAAS,QACrC,MAAM,GACJ,OAAO,mBAAmB,EAAE,SAAS,GAAC,SAAS,CAgB3D"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/webmcp/resolve.js"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,kCAJW,OAAO,mBAAmB,EAAE,SAAS,QACrC,MAAM,GACJ,OAAO,mBAAmB,EAAE,SAAS,GAAC,SAAS,CAgB3D;AAED;;;;;GAKG;AACH,sCAHW,OAAO,mBAAmB,EAAE,SAAS,GACnC,OAAO,mBAAmB,EAAE,SAAS,EAAE,CAgBnD"}

package/types/webmcp/schema.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Deep clone a schema fragment while removing the keys added by the compilation step.
+ * @param {unknown} fragment
+ * @returns {unknown}
+ */
+export function cleanSchemaFragment(fragment: unknown): unknown;
+/**
+ * Resolve a schema fragment from a skeleton pointer (ex: "_jl#/properties/filters/items").
+ * @param {object} schema - a JSON schema, its $id should match the pointer prefix
+ * @param {string} pointer
+ * @returns {object|undefined}
+ */
+export function resolveSchemaPointer(schema: object, pointer: string): object | undefined;
+/**
+ * Resolve the sub-schema that governs a node of the form.
+ * The schema given to the WebMCP instance is preferred (it is pristine),
+ * the compiled one is used as a fallback (it is cleaned up before being returned).
+ * @param {StateNode} node
+ * @param {StatefulLayout} statefulLayout
+ * @param {object|null} [originalSchema]
+ * @returns {object|undefined}
+ */
+export function resolveNodeSchema(node: StateNode, statefulLayout: StatefulLayout, originalSchema?: object | null): object | undefined;
+/**
+ * List the fields declared by the skeleton of a node, even when the state tree
+ * did not hydrate them yet (a collapsed list item for example).
+ * @param {StateNode} node
+ * @param {StatefulLayout} statefulLayout
+ * @param {object|null} [originalSchema]
+ * @returns {DeclaredField[]}
+ */
+export function projectDeclaredFields(node: StateNode, statefulLayout: StatefulLayout, originalSchema?: object | null): DeclaredField[];
+export type StateNode = import("../state/types.js").StateNode;
+export type StatefulLayout = import("../state/index.js").StatefulLayout;
+export type DeclaredField = {
+    key: string | number;
+    path: string;
+    type?: string;
+    title?: string;
+    required?: boolean;
+    enum?: unknown[];
+    declared: true;
+};
+//# sourceMappingURL=schema.d.ts.map

package/types/webmcp/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/webmcp/schema.js"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,8CAHW,OAAO,GACL,OAAO,CAcnB;AAeD;;;;;GAKG;AACH,6CAJW,MAAM,WACN,MAAM,GACJ,MAAM,GAAC,SAAS,CAgB5B;AAED;;;;;;;;GAQG;AACH,wCALW,SAAS,kBACT,cAAc,mBACd,MAAM,GAAC,IAAI,GACT,MAAM,GAAC,SAAS,CAkB5B;AAqBD;;;;;;;GAOG;AACH,4CALW,SAAS,kBACT,cAAc,mBACd,MAAM,GAAC,IAAI,GACT,aAAa,EAAE,CAsC3B;wBAhKa,OAAO,mBAAmB,EAAE,SAAS;6BACrC,OAAO,mBAAmB,EAAE,cAAc;4BAQ3C;IAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE"}

package/types/webmcp/suggestions-store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file Memory of the last suggestions returned for each node path
+ * @description Suggestion values can be large objects, they are not returned in full
+ * to the agent. They are memorized here so that setFieldValue can reuse the original
+ * value from its index.
+ *
+ * Searches on the same path accumulate rather than replace one another, and indices are
+ * absolute across them. Replacing meant a second search silently rebound every index the
+ * first had handed out, so an agent applying an index it had been given a moment earlier
+ * would set a different value with no error — the worst kind of failure this protocol can
+ * produce, since nothing in the transcript looks wrong. A write can change another
+ * field's options, so writes drop what they invalidate — see `retainFresh`.
+ */
+/** @typedef {{value: unknown, title: string, key?: string}} SuggestionItem */
+/**
+ * Per WebMCP instance memory of the suggestions, keyed by node path.
+ */
+export class SuggestionsStore {
+    /**
+     * @private
+     * @type {Map<string, SuggestionItem[]>}
+     */
+    private _byPath;
+    /**
+     * What the node's items depended on when each path was memorized, so a write can tell
+     * whether it invalidated them. See `retainFresh`.
+     * @private
+     * @type {Map<string, unknown>}
+     */
+    private _cacheKeys;
+    /**
+     * Paths that HAD memorized suggestions until a write dropped them. Kept so that the
+     * failure can say which of the two things happened: an agent told to "call
+     * getFieldSuggestions first" when it did exactly that, one call ago, cannot tell that
+     * the list went stale, and the eval shows it stops trusting suggestionIndex entirely.
+     * @private
+     * @type {Set<string>}
+     */
+    private _invalidated;
+    /**
+     * Memorize a search's items and return the index its first item was given. Indices are
+     * absolute per path, so an index handed out earlier keeps meaning what the agent saw.
+     * @param {string} path
+     * @param {SuggestionItem[]} items
+     * @param {unknown} [cacheKey] - the node's itemsCacheKey, what its options depend on
+     * @returns {number} the index of the first of these items
+     */
+    add(path: string, items: SuggestionItem[], cacheKey?: unknown): number;
+    /**
+     * Drop only the paths a write actually invalidated.
+     *
+     * Clearing everything on every write was correct but far broader than the hazard it
+     * guarded: writing one field cannot change the options of a field whose list does not
+     * depend on it, and the eval caught the cost twice on the same case — once recovered in
+     * one call, once in three. `isFresh` is given the key recorded at `add` time so the
+     * caller can compare it with the node's current `itemsCacheKey`, which is what the state
+     * layer itself uses to decide whether to re-fetch: a resolved URL for a remote picker, so
+     * the comparison is exact where it matters, and a value that simply differs for an
+     * expression-based list, which over-invalidates in the safe direction.
+     * @param {(path: string, cacheKey: unknown) => boolean} isFresh
+     */
+    retainFresh(isFresh: (path: string, cacheKey: unknown) => boolean): void;
+    /**
+     * @param {string} path
+     * @returns {SuggestionItem[]|undefined}
+     */
+    get(path: string): SuggestionItem[] | undefined;
+    /**
+     * Get the full original value memorized for a path at a given index.
+     * @param {string} path
+     * @param {number} index
+     * @returns {unknown}
+     */
+    getValue(path: string, index: number): unknown;
+    clear(): void;
+}
+export type SuggestionItem = {
+    value: unknown;
+    title: string;
+    key?: string;
+};
+//# sourceMappingURL=suggestions-store.d.ts.map

package/types/webmcp/suggestions-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions-store.d.ts","sourceRoot":"","sources":["../../src/webmcp/suggestions-store.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8EAA8E;AAE9E;;GAEG;AACH;IACE;;;OAGG;IACH,gBAAmB;IAEnB;;;;;OAKG;IACH,mBAAsB;IAEtB;;;;;;;OAOG;IACH,qBAAwB;IAExB;;;;;;;OAOG;IACH,UALW,MAAM,SACN,cAAc,EAAE,aAChB,OAAO,GACL,MAAM,CAalB;IAED;;;;;;;;;;;;OAYG;IACH,qBAFW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,QAStD;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,cAAc,EAAE,GAAC,SAAS,CAItC;IAED;;;;;OAKG;IACH,eAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAcnB;IAED,cAIC;CACF;6BA1Ga;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAC"}