@json-layout/core 2.8.1 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-layout/core",
-  "version": "2.8.1",
+  "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/serialize.js

@@ -51,6 +51,8 @@ export async function serialize (compiledLayout) {
   let code = standaloneCode.default(ajv, validatesExports)
 
   code = code.replace('"use strict";', '')
+  // make the exportN validates module-local so the object below can reference them
+  code = code.replace(/export const (export\d+) =/g, 'const $1 =')
 
   // some internal imports to ajv are not translated to esm, we do it here
   // cf https://github.com/ajv-validator/ajv-formats/pull/73
@@ -76,8 +78,7 @@ export async function serialize (compiledLayout) {
     ajvI18nPath = 'ajv-i18n/localize/en/index.js'
   }
 
-  code = `import localizeErrors from "${ajvI18nPath}";
-export const exportLocalizeErrors = localizeErrors;\n` + code
+  code = `import localizeErrors from "${ajvI18nPath}";\n` + code
 
   i = 0
   const expressionsNodes = []
@@ -91,30 +92,32 @@ export const exportLocalizeErrors = localizeErrors;\n` + code
     expressionsNodes.push(builders.raw(id))
   }
 
-  const ast = parseModule(code)
+  // reference the validate functions by name, keyed by json-pointer
+  /** @type {Record<string, any>} */
+  const validatesNodes = {}
+  i = 0
+  for (const pointer of Object.keys(compiledLayout.validates)) {
+    validatesNodes[pointer] = builders.raw(`export${i++}`)
+  }
+
+  // run magicast only on the small object literal; keep the large generated `code` as
+  // a raw string prefix (parsing it was the serialization bottleneck)
+  const ast = parseModule('export const compiledLayout = {}')
   ast.exports.compiledLayout = {
     mainTree: compiledLayout.mainTree,
     skeletonTrees: clone(compiledLayout.skeletonTrees),
     skeletonNodes: clone(compiledLayout.skeletonNodes),
     normalizedLayouts: clone(compiledLayout.normalizedLayouts),
-    validates: {},
+    validates: validatesNodes,
     validationErrors: compiledLayout.validationErrors,
     expressions: expressionsNodes,
     locale: compiledLayout.locale,
     messages: compiledLayout.messages,
     components: compiledLayout.options.components,
-    localizeErrors: ast.exports.exportLocalizeErrors
-  }
-  delete ast.exports.exportLocalizeErrors
-
-  i = 0
-  for (const pointer of Object.keys(compiledLayout.validates)) {
-    const exportKey = `export${i++}`
-    ast.exports.compiledLayout.validates[pointer] = ast.exports[exportKey]
-    delete ast.exports[exportKey]
+    localizeErrors: builders.raw('localizeErrors')
   }
 
-  const generatedCode = generateCode(ast).code.replace('export const compiledLayout = {', 'const compiledLayout = {')
+  const objectCode = generateCode(ast).code.replace('export const compiledLayout = {', 'const compiledLayout = {')
 
-  return generatedCode
+  return `${code}\n${objectCode}`
 }

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' }
@@ -305,6 +340,7 @@ export function makeSkeletonNode (
       /** @type {string | undefined} */
       let discriminator
       if (schema.discriminator?.propertyName) discriminator = schema.discriminator?.propertyName
+      else discriminator = inferDiscriminator(schema.oneOf, schemaId, getJSONRef)
       const oneOfPointer = `${refPointerPrefix}/oneOf`
       if (!normalizedLayouts[oneOfPointer]) {
         const normalizationResult = normalizeLayoutFragment(
@@ -319,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' }
@@ -548,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
           )
         }
@@ -594,3 +636,27 @@ export function makeSkeletonNode (
 
   return node
 }
+
+/**
+ * infer a discriminator when the keyword was not declared:
+ * a property that has a distinct const string value in every branch of the oneOf
+ * @param {any[]} oneOf
+ * @param {string} schemaId
+ * @param {(schemaId: string, ref: string) => [any, string, string]} getJSONRef
+ * @returns {string | undefined}
+ */
+function inferDiscriminator (oneOf, schemaId, getJSONRef) {
+  const fragments = oneOf.map(branch => branch.$ref ? getJSONRef(schemaId, branch.$ref)[0] : branch)
+  const candidateKeys = Object.keys(fragments[0]?.properties ?? {})
+  for (const key of candidateKeys) {
+    /** @type {string[]} */
+    const values = []
+    const distinct = fragments.every(fragment => {
+      const value = fragment?.properties?.[key]?.const
+      if (typeof value !== 'string' || values.includes(value)) return false
+      values.push(value)
+      return true
+    })
+    if (distinct) return key
+  }
+}

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

@@ -139,6 +139,10 @@ export class StatefulLayout {
   set data (data) {
     logDataBinding('apply main data setter', data)
     this._data = data
+    // data replaced from outside is authoritative, previously activated oneOf branches
+    // are re-resolved from the new data (discriminator based or validation based)
+    this._explicitActivatedItems.clear()
+    this._reResolveActivatedItems = true
     this.updateState()
   }
 
@@ -167,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}
@@ -285,6 +302,10 @@ export class StatefulLayout {
     /** @type {CreateStateTreeContext} */
     const createStateTreeContext = {
       activatedItems: this.activatedItems,
+      explicitActivatedItems: this._explicitActivatedItems,
+      // only the first tree creation after the data setter re-resolves activated branches,
+      // the following hydration iterations preserve them so that they cannot oscillate
+      reResolveActivatedItems: this._reResolveActivatedItems,
       autoActivatedItems: {},
       autofocusTarget: this._autofocusTarget,
       currentInput: this._currentInput,
@@ -303,6 +324,8 @@ export class StatefulLayout {
     // @ts-ignore
     if (this._options._debugCache) createStateTreeContext._debugCache = this._lastCreateStateTreeContext?._debugCache ?? {}
 
+    this._reResolveActivatedItems = false
+
     this._stateTree = createStateTree(
       createStateTreeContext,
       this._options,
@@ -453,6 +476,7 @@ export class StatefulLayout {
     if (activateKey !== undefined) {
       logActivatedItems(node.fullKey, 'activated item on input', activateKey)
       this.activatedItems = produce(this.activatedItems, draft => { draft[node.fullKey] = activateKey })
+      this._explicitActivatedItems.add(node.fullKey)
       this._autofocusTarget = node.fullKey + '/' + activateKey
     }
     if (node.parentFullKey === null) {
@@ -692,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
       }
@@ -713,6 +741,21 @@ export class StatefulLayout {
    */
   activatedItems
 
+  /**
+   * keys of activatedItems that were explicitly selected by the user,
+   * as opposed to auto-activated from the data
+   * @private
+   * @type {Set<string>}
+   */
+  _explicitActivatedItems = new Set()
+
+  /**
+   * true after data was replaced from outside, consumed by the next state tree creation
+   * @private
+   * @type {boolean}
+   */
+  _reResolveActivatedItems = false
+
   /**
    * @param {StateNode} node
    * @param {number | string} key
@@ -720,6 +763,7 @@ export class StatefulLayout {
   activateItem (node, key) {
     logActivatedItems(node.fullKey, 'activate item explicitly', key)
     this.activatedItems = produce(this.activatedItems, draft => { draft[node.fullKey] = key })
+    this._explicitActivatedItems.add(node.fullKey)
     this._autofocusTarget = node.fullKey + '/' + key
     if (node.key === '$oneOf') {
       if (node.layout.emptyData && node.data && typeof node.data === 'object' && node.children?.[0]) {
@@ -764,6 +808,7 @@ export class StatefulLayout {
         if (key.startsWith(node.fullKey)) {
           logActivatedItems(node.fullKey, 'item deactivation deletes a key', key)
           delete draft[key]
+          this._explicitActivatedItems.delete(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
   }
@@ -570,13 +579,34 @@ export function createStateNode (
     // find the oneOf child that was either previously selected
     // or the one matching the specified discriminator
     // or the one that is valid with current data
-    let activeChildTreeIndex = /** @type {number} */(context.activatedItems[fullKey])
+    let activeChildTreeIndex = /** @type {number | undefined} */(context.activatedItems[fullKey])
     let validChildTreeIndex = -1
+    if (
+      activeChildTreeIndex !== undefined &&
+      skeleton.discriminator !== undefined &&
+      !context.explicitActivatedItems.has(fullKey) &&
+      data?.[skeleton.discriminator] !== undefined
+    ) {
+      // an auto-activated branch is only kept as long as the discriminator value in the data still matches it,
+      // so that data replaced from outside (main data setter) is re-resolved to the right branch
+      const activeTree = skeleton.childrenTrees[activeChildTreeIndex]
+      if (activeTree !== undefined && compiledLayout.skeletonTrees[activeTree].discriminatorValue !== data[skeleton.discriminator]) {
+        activeChildTreeIndex = undefined
+      }
+    }
     if (activeChildTreeIndex !== undefined) {
-      // already explicitly activated, just check if data validates against the active variant
+      // already activated, just check if data validates against the active variant
       const activeTree = skeleton.childrenTrees[activeChildTreeIndex]
       if (activeTree !== undefined && compiledLayout.validates[compiledLayout.skeletonTrees[activeTree].refPointer](data)) {
         validChildTreeIndex = activeChildTreeIndex
+      } else if (context.reResolveActivatedItems) {
+        // data was replaced from outside (main data setter) and does not validate against the active branch,
+        // switch to another branch that validates the new data, keep the active branch if none does
+        const reResolvedIndex = skeleton.childrenTrees.findIndex((childTree) => compiledLayout.validates[compiledLayout.skeletonTrees[childTree].refPointer](data))
+        if (reResolvedIndex !== -1) {
+          activeChildTreeIndex = reResolvedIndex
+          validChildTreeIndex = reResolvedIndex
+        }
       }
     } else {
       // try discriminator-based resolution first (cheap string comparison)
@@ -599,7 +629,8 @@ export function createStateNode (
     if (activeChildTreeIndex !== -1) {
       const activeChildTree = compiledLayout.skeletonTrees[skeleton.childrenTrees[activeChildTreeIndex]]
       const activeChildNode = compiledLayout.skeletonNodes[activeChildTree.root]
-      if (!(fullKey in context.activatedItems)) context.autoActivatedItems[fullKey] = activeChildTreeIndex
+      // record the auto-activated branch, also when it changed compared to a stale previously activated branch
+      if (context.activatedItems[fullKey] !== activeChildTreeIndex) context.autoActivatedItems[fullKey] = activeChildTreeIndex
       context.errors = context.errors?.filter(error => {
         // if an item was selected, remove the oneOf error
         if (matchLocalError(error, skeleton, dataPath, parentDataPath)) {

package/src/state/types.ts

@@ -73,6 +73,12 @@ export interface CreateStateTreeContext {
   additionalPropertiesErrors?: ErrorObject[]
   files: FileRef[]
   activatedItems: Record<string, number | string>
+  // keys of activatedItems that were explicitly selected by the user (activateItem / input with activateKey)
+  // as opposed to auto-activated from the data, they are not challenged by the discriminator value in the data
+  explicitActivatedItems: Set<string>
+  // true on the first state tree creation after data was replaced from outside (main data setter),
+  // activated oneOf branches that do not validate the new data are then re-resolved
+  reResolveActivatedItems: boolean
   autoActivatedItems: Record<string, number | number>
   autofocusTarget: string | null
   currentInput: string | null

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 }
+}