@json-layout/core 2.8.2 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-layout/core",
-  "version": "2.8.2",
+  "version": "2.9.0",
   "description": "Compilation and state management utilities for JSON Layout.",
   "type": "module",
   "exports": {
@@ -61,6 +61,8 @@
   "scripts": {
     "test:only": "node --test --test-only test/*.spec.js",
     "test": "mkdir -p tmp && node --test test/*.spec.js",
+    "webmcp-eval:report": "node webmcp-eval/report.js",
+    "webmcp-eval:run": "node webmcp-eval/run-case.js",
     "build": "rm -rf ./types && tsc -p tsconfig.build.json",
     "watch:build": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
     "watch:test": "node --test --watch test/*.spec.js"
@@ -82,7 +84,7 @@
   },
   "homepage": "https://github.com/json-layout/json-layout#readme",
   "peerDependencies": {
-    "@json-layout/vocabulary": "^2.13.1"
+    "@json-layout/vocabulary": "^2.13.2"
   },
   "dependencies": {
     "ajv": "^8.17.1",

package/src/compile/index.js

@@ -37,7 +37,9 @@ export function compile (_schema, partialOptions = {}) {
   const schema = /** @type {import('ajv').SchemaObject} */(clone(_schema))
   schema.$id = schema.$id ?? '_jl'
   const getJSONRef = resolveLocaleRefs(schema, options.ajv, options.locale, options.defaultLocale)
-  if (options.xI18n) resolveXI18n(schema, options.locale, options.defaultLocale)
+  // always called: when xI18n is off this strips the annotations rather than applying
+  // them, so a schema carrying them stays valid instead of failing to normalize
+  resolveXI18n(schema, options.locale, options.defaultLocale, options.xI18n)
 
   /** @type {string[]} */
   const validatePointers = []

package/src/compile/skeleton-node.js

@@ -4,6 +4,30 @@ import { normalizeLayoutFragment, mergeNullableSubSchema, getSchemaFragmentType
 import { makeSkeletonTree } from './skeleton-tree.js'
 import { partialResolveRefs } from './utils/resolve-refs.js'
 
+/**
+ * Validation keywords that change what a value has to look like, as opposed to how it is
+ * rendered. A build-time compiled layout does not carry the raw schema — `serialize` emits
+ * the skeleton, the layouts and the validators, and nothing else — so a form filler working
+ * against a precompiled layout could not learn that a field is an email, or matches a
+ * pattern, or that an array holds at most five items. Ajv still enforces every one of them,
+ * which made the omission worse than useless: the rule was invisible until it was violated.
+ * Numbers are left out because min/max/step already reach the layout.
+ */
+const CONSTRAINT_KEYWORDS = ['format', 'pattern', 'minLength', 'maxLength', 'minItems', 'maxItems', 'uniqueItems']
+
+/**
+ * @param {any} schema
+ * @returns {Record<string, unknown> | undefined}
+ */
+function collectConstraints (schema) {
+  /** @type {Record<string, unknown>} */
+  const constraints = {}
+  for (const keyword of CONSTRAINT_KEYWORDS) {
+    if (schema?.[keyword] !== undefined) constraints[keyword] = schema[keyword]
+  }
+  return Object.keys(constraints).length ? constraints : undefined
+}
+
 /**
  * @param {any} rawSchema
  * @param {string} sourceSchemaId
@@ -17,10 +41,17 @@ import { partialResolveRefs } from './utils/resolve-refs.js'
  * @param {import('@json-layout/vocabulary').Expression[]} expressions
  * @param {string | number} key
  * @param {string} pointer
- * @param {boolean} required
+ * @param {boolean} required - the schema makes this node's value mandatory: omitting it is
+ * a validation error. This is what `node.required` reports and what a UI marks with an
+ * asterisk, so it must never be true for a node the schema is happy to see absent.
  * @param {string} [condition]
  * @param {boolean} [dependent]
  * @param {string} [knownType]
+ * @param {boolean} [alwaysPresent] - the node's value is materialized whether or not the
+ * schema requires it, because its parent renders it as a fixed slot. Drives default and
+ * empty-container application only. Defaults to `required`, which is the same thing for
+ * every parent that builds its children from what the schema demands; tuple entries are
+ * the exception, always present but only required up to `minItems`.
  * @returns {import('./types.js').SkeletonNode}
  */
 export function makeSkeletonNode (
@@ -39,7 +70,8 @@ export function makeSkeletonNode (
   required,
   condition,
   dependent,
-  knownType
+  knownType,
+  alwaysPresent = required
 ) {
   let schemaId = sourceSchemaId
   let schema = rawSchema
@@ -136,8 +168,8 @@ export function makeSkeletonNode (
     if (compObject.getConstData) pushExpression(expressions, compObject.getConstData)
 
     let defaultData
-    if ('default' in schema && (options.useDefault === 'data' || options.useDefault === true || required)) defaultData = schema.default
-    else if (required) {
+    if ('default' in schema && (options.useDefault === 'data' || options.useDefault === true || alwaysPresent)) defaultData = schema.default
+    else if (alwaysPresent) {
       if (nullable) defaultData = null
       else if (type === 'object' && isCompositeLayout(compObject, options.components)) defaultData = {}
       else if (type === 'array') defaultData = []
@@ -198,6 +230,9 @@ export function makeSkeletonNode (
     required: required && !nullable
   }
 
+  const constraints = collectConstraints(schema)
+  if (constraints) node.constraints = constraints
+
   if (condition) {
     if (isSwitchStruct(normalizedLayout)) throw new Error('Switch struct not allowed in conditional schema')
     node.condition = { type: 'js-eval', expr: condition, pure: true, dataAlias: 'value' }
@@ -320,7 +355,7 @@ export function makeSkeletonNode (
         const compObjects = isSwitchStruct(normalizationResult.layout) ? normalizationResult.layout.switch : [normalizationResult.layout]
         for (const compObject of compObjects) {
           let defaultData
-          if ('default' in schema && (options.useDefault === 'data' || options.useDefault === true || required)) defaultData = schema.default
+          if ('default' in schema && (options.useDefault === 'data' || options.useDefault === true || alwaysPresent)) defaultData = schema.default
           else defaultData = nullable ? null : {}
           if (compObject.defaultData === undefined) compObject.defaultData = defaultData
           if (compObject.defaultData !== undefined && !compObject.getDefaultData) compObject.getDefaultData = { type: 'js-eval', expr: 'layout.defaultData', pure: true, dataAlias: 'value' }
@@ -549,6 +584,12 @@ export function makeSkeletonNode (
             expressions,
             i,
             childPointer,
+            // a tuple entry is only mandatory while minItems still covers its position,
+            // but json-layout renders every entry, so all of them are always present
+            (schema.minItems ?? 0) > i,
+            undefined,
+            undefined,
+            undefined,
             true
           )
         }

package/src/compile/types.ts

@@ -80,4 +80,5 @@ export interface SkeletonNode {
   discriminator?: string
   required?: boolean
   nullable?: boolean
+  constraints?: Record<string, unknown> // validation keywords a form filler has to respect, kept because the raw schema does not survive serialization
 }

package/src/compile/utils/resolve-refs.js

@@ -1,5 +1,7 @@
 import { clone } from '@json-layout/vocabulary'
 
+import { resolvePointerFragment } from '../../utils/json-pointer.js'
+
 /**
  * @param {Record<string, import('ajv').SchemaObject>} schemas
  * @param {import('ajv/dist/2019.js').default} ajv
@@ -12,14 +14,9 @@ const prepareGetJSONRef = (schemas, ajv) => {
     schemas[schemaId] = schemas[schemaId] ?? (ajv.getSchema(schemaId)?.schema)
     if (!schemas[schemaId]) throw new Error(`reference not found ${schemaId}`)
     if (!pointer) return [schemas[schemaId], schemaId, fullRef]
-    const pointerParts = pointer.split('/').filter(p => !!p)
-    const { value: fragment } = pointerParts.reduce((a, pointerPart) => {
-      a.path.push(pointerPart)
-      if (!(pointerPart in a.value)) throw new Error(`reference not found ${schemaId}#${a.path.join('/')}`)
-      a.value = a.value[pointerPart]
-      return a
-    }, { path: /** @type {string[]} */([]), value: schemas[schemaId] })
-    return [fragment, schemaId, fullRef]
+    const resolved = resolvePointerFragment(schemas[schemaId], pointer)
+    if (!resolved.found) throw new Error(`reference not found ${schemaId}#${resolved.path.join('/')}`)
+    return [resolved.value, schemaId, fullRef]
   }
 }
 

package/src/compile/utils/x-i18n.js

@@ -4,21 +4,30 @@
  * @param {Record<string, any>} schema
  * @param {string} locale
  * @param {string} [defaultLocale]
+ * @param {boolean} [apply] - when false the annotations are stripped without being applied
  */
-export const resolveXI18n = (schema, locale, defaultLocale = 'en') => {
+export const resolveXI18n = (schema, locale, defaultLocale = 'en', apply = true) => {
   if (!schema || typeof schema !== 'object') return
   for (const [key, value] of Object.entries(schema)) {
     if (key.startsWith('x-i18n-')) {
-      if (typeof value !== 'object') console.error(`i18n property ${key} should be an object`)
-      const realKey = key.replace('x-i18n-', '')
-      schema[realKey] = value[locale] ?? value[defaultLocale] ?? schema[realKey]
+      // Always removed, even when not applied: these keys belong to this vocabulary, and
+      // the option says whether to translate with them, not whether they are legal. Left
+      // in place they fail the component schemas' unevaluatedProperties, normalization
+      // falls back to the default component, and a one-of-select that stops being a
+      // variant selector no longer merges its branch into the parent — the data then
+      // never stabilises and updateState throws after 100 iterations.
+      if (apply) {
+        if (typeof value !== 'object') console.error(`i18n property ${key} should be an object`)
+        const realKey = key.replace('x-i18n-', '')
+        schema[realKey] = value[locale] ?? value[defaultLocale] ?? schema[realKey]
+      }
       delete schema[key]
     } else if (Array.isArray(value)) {
       for (const child of value) {
-        resolveXI18n(child, locale, defaultLocale)
+        resolveXI18n(child, locale, defaultLocale, apply)
       }
     } else {
-      resolveXI18n(value, locale, defaultLocale)
+      resolveXI18n(value, locale, defaultLocale, apply)
     }
   }
 }

package/src/state/index.js

@@ -171,6 +171,19 @@ export class StatefulLayout {
   // @ts-ignore
   _lastCreateStateTreeContext
 
+  /**
+   * The raw validation errors of the last state update, each carrying the data pointer
+   * (instancePath) it applies to.
+   *
+   * A node only carries an error when it is hydrated, so an error below an unhydrated
+   * subtree — a list item shown in summary mode, say — has no node to attach to and
+   * collapses onto the nearest ancestor. These keep the precise location.
+   * @returns {import('ajv').ErrorObject[]}
+   */
+  get validationErrors () {
+    return this._lastCreateStateTreeContext?.allErrors ?? []
+  }
+
   /**
    * @private
    * @type {string | null}
@@ -703,7 +716,11 @@ export class StatefulLayout {
         item.value = layout.getItems?.itemValue ? this.evalNodeExpression(node, layout.getItems.itemValue, rawItem) : (layout.getItems?.returnObjects ? rawItem : rawItem.value)
         item.key = layout.getItems?.itemKey ? this.evalNodeExpression(node, layout.getItems.itemKey, rawItem) : rawItem.key
         item.title = layout.getItems?.itemTitle ? this.evalNodeExpression(node, layout.getItems.itemTitle, rawItem) : rawItem.title
-        item.value = item.value ?? item.key
+        // A legitimate null — a { const: null } branch, normalized to
+        // { key: "null", value: null } — is a value, not an absence. `??` would swallow
+        // it and keep the key, so the tool hands the agent the string "null" and the
+        // schema then rejects the very suggestion it offered.
+        if (item.value === undefined) item.value = item.key
         item.key = item.key ?? item.value + ''
         item.title = item.title ?? item.key
       }

package/src/state/state-node.js

@@ -329,8 +329,17 @@ const getCompObject = (normalizedLayout, childDefinition, options, compiledLayou
     if (childDefinition?.if && !evalExpression(compiledLayout.expressions, childDefinition.if, data, options, display, normalizedLayout, compiledLayout.validates, rootData, parentContext)) {
       return noneComp
     }
-    if (normalizedLayout.if && !evalExpression(compiledLayout.expressions, normalizedLayout.if, data, options, display, normalizedLayout, compiledLayout.validates, rootData, parentContext)) {
-      return noneComp
+    if (normalizedLayout.if) {
+      let visible
+      try {
+        visible = evalExpression(compiledLayout.expressions, normalizedLayout.if, data, options, display, normalizedLayout, compiledLayout.validates, rootData, parentContext)
+      } catch (err) {
+        // an "if" that cannot be evaluated (typically a rootData path through an empty
+        // array) hides the node, as an unresolvable getItems yields no items
+        console.warn(`json-layout: "if" expression threw, treating it as false: ${normalizedLayout.if.expr}`)
+        visible = false
+      }
+      if (!visible) return noneComp
     }
     return normalizedLayout
   }

package/src/state/utils/urls.js

@@ -3,5 +3,7 @@ const origin = typeof window === 'undefined' ? 'http://test.com' : window.locati
 export const pathURL = (/** @type {string} */url, /** @type {string} */baseURL) => {
   if (url.startsWith('http://') || url.startsWith('https://')) return new URL(url)
   if (url.startsWith('/')) return new URL(origin + url)
+  // an absolute base (a Node process pointed at a remote API) must not be glued onto the origin
+  if (baseURL.startsWith('http://') || baseURL.startsWith('https://')) return new URL(baseURL + url)
   return new URL(origin + baseURL + url)
 }

package/src/utils/json-pointer.js

@@ -0,0 +1,29 @@
+/**
+ * @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, fragment) {
+  /** @type {string[]} */
+  const path = []
+  let current = root
+  for (const segment of fragment.split('/')) {
+    if (!segment) continue
+    path.push(segment)
+    if (current === null || typeof current !== 'object' || !(segment in current)) {
+      return { found: false, path }
+    }
+    current = /** @type {any} */(current)[segment]
+  }
+  return { found: true, value: current }
+}

package/src/webmcp/README.md

@@ -0,0 +1,144 @@
+# WebMCP form tools — what they are and why they exist
+
+A page that renders a json-layout form can expose it to an agent as a set of MCP tools.
+This is the design of those tools, the choices behind them, and how far they have actually
+been validated.
+
+## Why not just hand the model the schema and let it emit JSON?
+
+This is the first question anyone asks, and for a small form it is the right instinct —
+`contact` is a 368-character schema with five fields, and a model would fill it blind.
+The suite exists because real configuration forms are not that, and four properties break
+the blind approach:
+
+**1. Half the schema does not apply until you have chosen something.** `charts` is five
+levels of nested `oneOf`: which fields are legal depends on the chart type, then on the
+data-preparation mode, then on the grouping kind. `calendar` hides a whole section behind
+`x-if: datasets.0.isRest` — the crowd-sourcing settings do not exist as valid keys until a
+REST dataset is picked. A model emitting a document in one shot has to guess which branch's
+fields are legal; the tools let it activate a branch and be told what that branch contains.
+
+**2. The accepted values are not in the schema at all.** `calendar`'s label field takes its
+options from `${rootData.datasets[0].href}/schema?calculated=false` — an HTTP request whose
+URL is built from another field's current value. No amount of schema reading yields
+`nomevenement`. `getFieldSuggestions` performs that lookup; nothing else can.
+
+**3. The values can be far larger than the answer.** A picked data-fair dataset is a 12,486-
+character object of column definitions. The agent never handles it: it applies suggestion
+index 0 and the form stores the object. Emitting that document by hand would mean
+reproducing 12 KB of column metadata verbatim.
+
+**4. The schema is bigger than the whole conversation.** `portal-page` is 285,874 characters,
+814 layout nodes. A complete `portal-page` session costs about 7.4 KB of tool output. Sending
+the schema once would cost roughly forty times the entire interaction.
+
+There is a fifth reason that matters in production: the form is *live*. Writes land in the
+state a user is looking at, validation runs on every one, and the errors come back scoped to
+what just changed. The agent is editing a form, not drafting a file.
+
+## The tools
+
+Six, and one guide. The guide is not a tool — production pages pass it to the agent as its
+prompt via `includeSubAgent`.
+
+| tool | what it is for |
+|---|---|
+| `describeState` | every field with path, type, constraints, current value, errors. The starting point and the only way to see the form. |
+| `setFieldValue` | write one field; switch a variant by writing its index. |
+| `setData` | write the whole document at once, for when the goal already contains every value. |
+| `editArray` | add or remove an item; an added item is activated and its fields returned. |
+| `getFieldSuggestions` | fetch the accepted values of a field whose list is remote. |
+| `getData` | the data itself, whole or at a path, for when the values are wanted rather than a description of them. |
+
+## Choices, and what justified them
+
+Each of these was measured, most of them after getting it wrong first.
+
+**Responses are text, never `structuredContent`.** Tools used to return both a markdown text
+and a JSON object. MCP clients substitute the JSON, so the markdown was never read — proved
+by reading the runner's own transcript, where an agent can be seen receiving
+`{"path":"/contactMethod","type":"select","getSuggestions":true}` with no values. Five
+finished pieces of work were inert. Removing the structured half took what the model receives
+for one `describeState` from 91,197 bytes to 2,212.
+
+**One representation, one home per fact.** The suggestion protocol was once stated four times
+— in two tool descriptions, a parameter, and the guide. Copies drift: a stale duplicate of
+`getData`'s description in `index.js` silently overrode the real one for weeks and cost two
+cases a call each. Tests now assert that exactly one description explains `suggestionIndex`.
+
+**One guide, no complexity classification.** There used to be small/medium/large bands, from
+counting layout nodes, feeding three different sets of advice. The threshold was
+unjustifiable, it measured the schema when the question was about data, and it was duplicated
+in two files. Four consecutive commits fixed contradictions between the branches, and across
+four baselines the small and medium advice was never taken on a real form.
+
+**No `getSchema`.** A build-time compiled layout carries no raw schema — `serialize()` emits
+the skeleton, the layouts and the validators — so the tool cannot exist where production runs.
+`calendar` and `charts` had it available in every run and never called it. What it uniquely
+offered, the validation keywords, now reaches the state tree instead: `format`, `pattern`,
+`minLength`, `maxLength`, `minItems`, `maxItems` and `uniqueItems` are carried onto the
+skeleton node, because ajv enforces them and nothing else was telling the agent.
+
+**Large values are named, never truncated.** `<object, 12486 chars — call getData with this
+path to read it>`. A truncated value read as real would be forwarded to an API as a wrong
+value with nothing looking wrong; a marker fails loudly. `getData` itself is never abbreviated
+for the same reason — what it returns is the data.
+
+**A closed list is stated, a remote one is flagged.** `describeState` prints
+`values=["top","bottom","left","right"]` when the options are already resolved, and marks
+`suggestions` when they are only reachable by request. Before this, agents spent a round trip
+per enum.
+
+**Repeated things are said once.** A recursive schema reaches the same union at every level;
+`portal-page`'s 39 branches were printed three times in a ten-call run. They are now printed
+once, then referred back to by path.
+
+**Memorised suggestions are dropped only when they go stale.** Applying an option by index
+needs the list remembered. Every write used to clear all of it, which broke a listing an
+unrelated write could not have affected. Invalidation now compares each path's
+`itemsCacheKey` — the same value the state layer uses to decide whether to re-fetch.
+
+## How far this is validated
+
+Unit tests: 463, covering tool shapes, projection rules and the compile-level changes in both
+runtime and build-time compilation.
+
+Behavioural: `core/webmcp-eval/` runs each case as a headless `claude -p` subprocess against
+a real MCP server, and a judge reads the transcript. Six cases — a hand-written control, three
+vendored from data-fair (`app-calendar`, `app-charts`, `portals` page editor), and two that
+start from a populated document and ask for a change.
+
+At the latest baseline, every case was judged satisfactory on **three model tiers**, with the
+produced document checked field by field rather than trusting `valid: true`:
+
+| | opus | sonnet | haiku |
+|---|---|---|---|
+| cases correct | 6/6 | 6/6 | 6/6 |
+| errored calls | 1 | 0 | 0 |
+| suite cost | $0.838 | $0.502 | $0.254 |
+
+Haiku 4.5 completed `portal-page` — the 39-branch recursive union — in eight calls, the floor,
+with no wasted read. The points where a smaller model was expected to slip are the ones the
+protocol leaves to inference: which of `children`/`children2` is the left column, that a
+rendered branch is the active one, that a field's options cannot be fetched before the field
+they derive from is set. None of them bit.
+
+## What is not established
+
+- **One MCP client.** Everything ran through Claude Code. The `structuredContent` episode is
+  the standing reminder that client behaviour can silently invalidate a whole line of work.
+- **The judge is not independent** — it is the same model family reading its own transcripts.
+- **n=1 per case per model**, against run-to-run variance that has reached 3× on cost for
+  identical code. Single-run comparisons are noise; only repeated, large effects are signal.
+- **`setData` with `merge: false`** has unit tests and no behavioural evidence — no agent has
+  ever called it.
+- Open findings are recorded per baseline in `core/webmcp-eval/baselines/`. All current ones
+  are clarity, not correctness: none has produced a wrong value or an invalid form.
+
+## A note on measuring
+
+Output bytes are what a tool answers with; they are not what a run costs. A `calendar` run
+consumes about 98,500 input-side tokens, 89,000 of them cache reads of the conversation
+replayed each turn, against roughly 1,300 output. One 13 KB response is about 3% of that.
+Three commits went into suppressing such a response before anyone measured it. The runner now
+records token usage and the report prints it beside the byte count.