@narrative.io/jsonforms-provider-protocols 3.0.0-beta.16 → 3.0.0-beta.17

package/dist/core/initFormData.js

@@ -1,3 +1,4 @@
+import { resolveRef } from "./refs.js";
 function initFormDataFromSchema(schema, seed) {
   const result = initProperty(schema, schema, seed, true);
   const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
@@ -15,30 +16,6 @@ function initFormDataFromSchema(schema, seed) {
   }
   return base;
 }
-function resolveRef(property, root, seen) {
-  if (!property || typeof property !== "object") return property;
-  const ref = property.$ref;
-  if (!ref) return property;
-  const visited = seen ?? /* @__PURE__ */ new Set();
-  if (visited.has(ref)) return property;
-  visited.add(ref);
-  const resolved = resolvePointer(root, ref);
-  if (!resolved) return property;
-  return resolveRef(resolved, root, visited);
-}
-function resolvePointer(obj, pointer) {
-  if (!pointer.startsWith("#/")) return void 0;
-  const parts = pointer.slice(2).split("/");
-  let current = obj;
-  for (const part of parts) {
-    if (current && typeof current === "object" && part in current) {
-      current = current[part];
-    } else {
-      return void 0;
-    }
-  }
-  return current;
-}
 function initProperty(property, root, seed, required) {
   if (!property || typeof property !== "object") {
     return required ? null : void 0;

package/dist/core/initFormData.js.map

@@ -1 +1 @@
-{"version":3,"file":"initFormData.js","sources":["../../src/core/initFormData.ts"],"sourcesContent":["/**\n * Initialize a form data object from a JSON Schema.\n * Resolves $ref, const, default, oneOf/discriminator, and typed empty values.\n *\n * Optional fields (not listed in the parent schema's `required` array) that\n * have no `const`, no single-value `enum`, and no `default` are omitted\n * entirely from the result. This avoids seeding values (e.g. `null` for\n * `type: \"integer\"`) that fail AJV's type check and surface spurious errors\n * on untouched fields. Required fields retain legacy typed-empty seeding\n * (`\"\"`, `null`, `false`, `[]`) so that \"is required\" surfaces cleanly.\n *\n * @param schema - The full JSON Schema (must include $defs if $refs are used)\n * @param seed   - Optional existing data to merge (seed values take priority)\n * @returns A data object with schema-defined fields initialized\n */\nexport function initFormDataFromSchema(\n  schema: Record<string, unknown>,\n  seed?: Record<string, unknown>,\n): Record<string, unknown> {\n  const result = initProperty(schema, schema, seed, true) as\n    | Record<string, unknown>\n    | undefined;\n\n  const base =\n    result && typeof result === \"object\" && !Array.isArray(result)\n      ? result\n      : {};\n\n  // Preserve seed keys not described by the schema's properties.\n  if (seed && typeof seed === \"object\") {\n    const schemaKeys = new Set(\n      Object.keys(\n        (resolveRef(schema, schema) as Record<string, unknown>)?.properties ??\n          {},\n      ),\n    );\n    for (const key of Object.keys(seed)) {\n      if (!schemaKeys.has(key) && !(key in base)) {\n        base[key] = seed[key];\n      }\n    }\n  }\n\n  return base;\n}\n\n/**\n * Resolve a $ref pointer against the root schema's $defs.\n * Supports nested $ref chains.\n */\nfunction resolveRef(\n  property: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seen?: Set<string>,\n): Record<string, unknown> {\n  if (!property || typeof property !== \"object\") return property;\n\n  const ref = property.$ref as string | undefined;\n  if (!ref) return property;\n\n  const visited = seen ?? new Set<string>();\n  if (visited.has(ref)) return property;\n  visited.add(ref);\n\n  const resolved = resolvePointer(root, ref);\n  if (!resolved) return property;\n\n  return resolveRef(resolved as Record<string, unknown>, root, visited);\n}\n\n/**\n * Resolve a JSON pointer like \"#/$defs/Price\" against an object.\n */\nfunction resolvePointer(\n  obj: Record<string, unknown>,\n  pointer: string,\n): unknown {\n  if (!pointer.startsWith(\"#/\")) return undefined;\n  const parts = pointer.slice(2).split(\"/\");\n  let current: unknown = obj;\n  for (const part of parts) {\n    if (current && typeof current === \"object\" && part in current) {\n      current = (current as Record<string, unknown>)[part];\n    } else {\n      return undefined;\n    }\n  }\n  return current;\n}\n\n/**\n * Initialize a single property value based on its schema definition.\n * Returns `undefined` when the property is optional and has nothing\n * concrete to seed — the caller then omits the key from its result.\n */\nfunction initProperty(\n  property: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: unknown,\n  required: boolean,\n): unknown {\n  if (!property || typeof property !== \"object\") {\n    return required ? null : undefined;\n  }\n\n  const resolved = resolveRef(property, root);\n  const type = resolved.type as string | undefined;\n  const isOneOf = Array.isArray(resolved.oneOf);\n\n  // Priority 1: seed wins for non-object, non-oneOf types. For oneOf we still\n  // descend so that a partial seed (e.g. `{value: 5}` missing the\n  // discriminator) picks up the variant's const/default for untouched fields.\n  if (seed !== undefined && seed !== null && type !== \"object\" && !isOneOf) {\n    return seed;\n  }\n\n  // Priority 2: const (schema-invariant — always set).\n  if (\"const\" in resolved) {\n    return resolved.const;\n  }\n\n  // Priority 3: single-value enum (same reasoning — only one valid value).\n  if (\n    Array.isArray(resolved.enum) &&\n    (resolved.enum as unknown[]).length === 1\n  ) {\n    return (resolved.enum as unknown[])[0];\n  }\n\n  // Priority 4: default (explicit author intent — always honored).\n  if (\"default\" in resolved) {\n    return resolved.default;\n  }\n\n  // Priority 5: oneOf. Recurse into the first variant, propagating the\n  // `required` flag so that the variant's own schema-declared required fields\n  // only get typed-empty seeding when the container is required. For optional\n  // containers, the variant's const / default / single-value enum still seed\n  // (author intent is unconditional) but typed-empty placeholders do not.\n  // If recursion yields nothing forced, we collapse back to undefined.\n  if (isOneOf) {\n    const value = initOneOf(resolved, root, seed, required);\n    if (\n      !required &&\n      (value === undefined ||\n        (value !== null &&\n          typeof value === \"object\" &&\n          !Array.isArray(value) &&\n          Object.keys(value as Record<string, unknown>).length === 0))\n    ) {\n      return undefined;\n    }\n    return value;\n  }\n\n  // Priority 6: objects recurse. The `required` flag propagates downward:\n  // inside an optional ancestor, nested required primitives also collapse,\n  // so an optional object with nested required fields stays absent instead\n  // of materializing a shell that AJV would flag.\n  if (type === \"object\") {\n    const obj = initObject(\n      resolved,\n      root,\n      seed as Record<string, unknown>,\n      required,\n    );\n    if (!required && Object.keys(obj).length === 0) return undefined;\n    return obj;\n  }\n\n  // Priority 7: optional primitives — omit.\n  if (!required) return undefined;\n\n  // Priority 8: required primitives — legacy typed empty.\n  switch (type) {\n    case \"array\":\n      return seed !== undefined && seed !== null ? seed : [];\n    case \"string\":\n      return \"\";\n    case \"boolean\":\n      return false;\n    case \"number\":\n    case \"integer\":\n    default:\n      return null;\n  }\n}\n\n/**\n * Initialize an object type by recursing into its properties.\n * Keys whose initialization returns `undefined` are omitted.\n *\n * `parentRequired` controls how schema.required propagates: a child is\n * treated as required only if both its parent is required AND it appears in\n * the parent's required array. Inside an optional ancestor the whole\n * subtree collapses (except for author-forced values: const, default,\n * single-value enum, or seeded values).\n */\nfunction initObject(\n  schema: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: Record<string, unknown> | undefined,\n  parentRequired: boolean,\n): Record<string, unknown> {\n  const properties = schema.properties as\n    | Record<string, Record<string, unknown>>\n    | undefined;\n  if (!properties) {\n    return seed && typeof seed === \"object\" ? { ...seed } : {};\n  }\n\n  const requiredSet = new Set<string>(\n    Array.isArray(schema.required) ? (schema.required as string[]) : [],\n  );\n\n  const result: Record<string, unknown> = {};\n\n  for (const [key, propSchema] of Object.entries(properties)) {\n    const seedValue = seed && typeof seed === \"object\" ? seed[key] : undefined;\n    const effectiveRequired = parentRequired && requiredSet.has(key);\n    const value = initProperty(propSchema, root, seedValue, effectiveRequired);\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Handle oneOf schemas — pick the first variant and initialize it.\n * `required` propagates: if the outer oneOf is required, the variant is\n * materialized with typed-empty seeding for its required fields; if optional,\n * only author-forced values (const / default / single-enum / seed) survive.\n */\nfunction initOneOf(\n  schema: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: unknown,\n  required: boolean,\n): unknown {\n  const variants = schema.oneOf as Record<string, unknown>[];\n  if (!variants || variants.length === 0) return required ? null : undefined;\n\n  const first = variants[0];\n  if (!first) return required ? null : undefined;\n\n  const firstVariant = resolveRef(first, root);\n  return initProperty(firstVariant, root, seed, required);\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"initFormData.js","sources":["../../src/core/initFormData.ts"],"sourcesContent":["/**\n * Initialize a form data object from a JSON Schema.\n * Resolves $ref, const, default, oneOf/discriminator, and typed empty values.\n *\n * Optional fields (not listed in the parent schema's `required` array) that\n * have no `const`, no single-value `enum`, and no `default` are omitted\n * entirely from the result. This avoids seeding values (e.g. `null` for\n * `type: \"integer\"`) that fail AJV's type check and surface spurious errors\n * on untouched fields. Required fields retain legacy typed-empty seeding\n * (`\"\"`, `null`, `false`, `[]`) so that \"is required\" surfaces cleanly.\n *\n * @param schema - The full JSON Schema (must include $defs if $refs are used)\n * @param seed   - Optional existing data to merge (seed values take priority)\n * @returns A data object with schema-defined fields initialized\n */\nexport function initFormDataFromSchema(\n  schema: Record<string, unknown>,\n  seed?: Record<string, unknown>,\n): Record<string, unknown> {\n  const result = initProperty(schema, schema, seed, true) as\n    | Record<string, unknown>\n    | undefined;\n\n  const base =\n    result && typeof result === \"object\" && !Array.isArray(result)\n      ? result\n      : {};\n\n  // Preserve seed keys not described by the schema's properties.\n  if (seed && typeof seed === \"object\") {\n    const schemaKeys = new Set(\n      Object.keys(\n        (resolveRef(schema, schema) as Record<string, unknown>)?.properties ??\n          {},\n      ),\n    );\n    for (const key of Object.keys(seed)) {\n      if (!schemaKeys.has(key) && !(key in base)) {\n        base[key] = seed[key];\n      }\n    }\n  }\n\n  return base;\n}\n\nimport { resolveRef } from \"./refs\";\n\n/**\n * Initialize a single property value based on its schema definition.\n * Returns `undefined` when the property is optional and has nothing\n * concrete to seed — the caller then omits the key from its result.\n */\nfunction initProperty(\n  property: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: unknown,\n  required: boolean,\n): unknown {\n  if (!property || typeof property !== \"object\") {\n    return required ? null : undefined;\n  }\n\n  const resolved = resolveRef(property, root);\n  const type = resolved.type as string | undefined;\n  const isOneOf = Array.isArray(resolved.oneOf);\n\n  // Priority 1: seed wins for non-object, non-oneOf types. For oneOf we still\n  // descend so that a partial seed (e.g. `{value: 5}` missing the\n  // discriminator) picks up the variant's const/default for untouched fields.\n  if (seed !== undefined && seed !== null && type !== \"object\" && !isOneOf) {\n    return seed;\n  }\n\n  // Priority 2: const (schema-invariant — always set).\n  if (\"const\" in resolved) {\n    return resolved.const;\n  }\n\n  // Priority 3: single-value enum (same reasoning — only one valid value).\n  if (\n    Array.isArray(resolved.enum) &&\n    (resolved.enum as unknown[]).length === 1\n  ) {\n    return (resolved.enum as unknown[])[0];\n  }\n\n  // Priority 4: default (explicit author intent — always honored).\n  if (\"default\" in resolved) {\n    return resolved.default;\n  }\n\n  // Priority 5: oneOf. Recurse into the first variant, propagating the\n  // `required` flag so that the variant's own schema-declared required fields\n  // only get typed-empty seeding when the container is required. For optional\n  // containers, the variant's const / default / single-value enum still seed\n  // (author intent is unconditional) but typed-empty placeholders do not.\n  // If recursion yields nothing forced, we collapse back to undefined.\n  if (isOneOf) {\n    const value = initOneOf(resolved, root, seed, required);\n    if (\n      !required &&\n      (value === undefined ||\n        (value !== null &&\n          typeof value === \"object\" &&\n          !Array.isArray(value) &&\n          Object.keys(value as Record<string, unknown>).length === 0))\n    ) {\n      return undefined;\n    }\n    return value;\n  }\n\n  // Priority 6: objects recurse. The `required` flag propagates downward:\n  // inside an optional ancestor, nested required primitives also collapse,\n  // so an optional object with nested required fields stays absent instead\n  // of materializing a shell that AJV would flag.\n  if (type === \"object\") {\n    const obj = initObject(\n      resolved,\n      root,\n      seed as Record<string, unknown>,\n      required,\n    );\n    if (!required && Object.keys(obj).length === 0) return undefined;\n    return obj;\n  }\n\n  // Priority 7: optional primitives — omit.\n  if (!required) return undefined;\n\n  // Priority 8: required primitives — legacy typed empty.\n  switch (type) {\n    case \"array\":\n      return seed !== undefined && seed !== null ? seed : [];\n    case \"string\":\n      return \"\";\n    case \"boolean\":\n      return false;\n    case \"number\":\n    case \"integer\":\n    default:\n      return null;\n  }\n}\n\n/**\n * Initialize an object type by recursing into its properties.\n * Keys whose initialization returns `undefined` are omitted.\n *\n * `parentRequired` controls how schema.required propagates: a child is\n * treated as required only if both its parent is required AND it appears in\n * the parent's required array. Inside an optional ancestor the whole\n * subtree collapses (except for author-forced values: const, default,\n * single-value enum, or seeded values).\n */\nfunction initObject(\n  schema: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: Record<string, unknown> | undefined,\n  parentRequired: boolean,\n): Record<string, unknown> {\n  const properties = schema.properties as\n    | Record<string, Record<string, unknown>>\n    | undefined;\n  if (!properties) {\n    return seed && typeof seed === \"object\" ? { ...seed } : {};\n  }\n\n  const requiredSet = new Set<string>(\n    Array.isArray(schema.required) ? (schema.required as string[]) : [],\n  );\n\n  const result: Record<string, unknown> = {};\n\n  for (const [key, propSchema] of Object.entries(properties)) {\n    const seedValue = seed && typeof seed === \"object\" ? seed[key] : undefined;\n    const effectiveRequired = parentRequired && requiredSet.has(key);\n    const value = initProperty(propSchema, root, seedValue, effectiveRequired);\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Handle oneOf schemas — pick the first variant and initialize it.\n * `required` propagates: if the outer oneOf is required, the variant is\n * materialized with typed-empty seeding for its required fields; if optional,\n * only author-forced values (const / default / single-enum / seed) survive.\n */\nfunction initOneOf(\n  schema: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: unknown,\n  required: boolean,\n): unknown {\n  const variants = schema.oneOf as Record<string, unknown>[];\n  if (!variants || variants.length === 0) return required ? null : undefined;\n\n  const first = variants[0];\n  if (!first) return required ? null : undefined;\n\n  const firstVariant = resolveRef(first, root);\n  return initProperty(firstVariant, root, seed, required);\n}\n"],"names":[],"mappings":"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"}

package/dist/core/projection.d.ts

@@ -27,6 +27,10 @@ export declare function setProjectedValue(data: unknown, path: string, value: un
  * Resolve the schema at the projected path.
  * Numeric segments traverse into `items` (array item schema).
  * String segments traverse into `properties[segment]`.
+ *
+ * `$ref` nodes are dereferenced transparently at every step, so projections
+ * that cross a `$ref` boundary (e.g. `items: { $ref: "#/$defs/X" }`) resolve
+ * to the target schema rather than collapsing to `{}`.
  */
 export declare function getProjectedSchema(schema: Record<string, any>, path: string): Record<string, any>;
 //# sourceMappingURL=projection.d.ts.map

package/dist/core/projection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/core/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAMrE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAGT;AAqCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAEhC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GAEX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA8BrB"}
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/core/projection.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAMrE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAGT;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAEhC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GAEX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgCrB"}

package/dist/core/projection.js

@@ -1,3 +1,4 @@
+import { deref } from "./refs.js";
 function parseProjectionPath(path) {
   if (!path) return [];
   return path.split(".").map((s) => {
@@ -46,6 +47,7 @@ function getProjectedSchema(schema, path) {
   const segments = parseProjectionPath(path);
   let current = schema;
   for (const seg of segments) {
+    current = deref(current, schema);
     if (!current) return {};
     if (typeof seg === "number") {
       const items = current.items;
@@ -63,7 +65,8 @@ function getProjectedSchema(schema, path) {
       }
     }
   }
-  return current;
+  const resolved = deref(current, schema);
+  return resolved ?? {};
 }
 export {
   getProjectedSchema,

package/dist/core/projection.js.map

@@ -1 +1 @@
-{"version":3,"file":"projection.js","sources":["../../src/core/projection.ts"],"sourcesContent":["/**\n * Projection utilities for navigating complex data structures\n * through a dot-separated path where numeric segments are array indices.\n *\n * Examples:\n *   \"0\"                → first element of an array\n *   \"include\"          → the `include` property of an object\n *   \"0.video_rate_usd\" → nested property inside the first array element\n */\n\nexport type ProjectionSegment = string | number;\n\n/**\n * Parse a projection path string into typed segments.\n * Numeric strings become numbers (array indices), others stay as strings (object keys).\n */\nexport function parseProjectionPath(path: string): ProjectionSegment[] {\n  if (!path) return [];\n  return path.split(\".\").map((s) => {\n    const n = Number(s);\n    return Number.isInteger(n) && n >= 0 ? n : s;\n  });\n}\n\n/**\n * Read a value from `data` by following the projection path.\n * Returns `undefined` if any segment along the path is missing.\n */\nexport function getProjectedValue(data: unknown, path: string): unknown {\n  const segments = parseProjectionPath(path);\n  let current: unknown = data;\n\n  for (const seg of segments) {\n    if (current === null || current === undefined) return undefined;\n\n    if (typeof seg === \"number\") {\n      if (!Array.isArray(current)) return undefined;\n      current = current[seg];\n    } else {\n      if (typeof current !== \"object\") return undefined;\n      current = (current as Record<string, unknown>)[seg];\n    }\n  }\n\n  return current;\n}\n\n/**\n * Immutably set a value at the projection path, preserving all sibling data.\n * Constructs missing intermediate structures (arrays for numeric segments, objects for string segments).\n */\nexport function setProjectedValue(\n  data: unknown,\n  path: string,\n  value: unknown,\n): unknown {\n  const segments = parseProjectionPath(path);\n  return setAtPath(data, segments, 0, value);\n}\n\nfunction setAtPath(\n  current: unknown,\n  segments: ProjectionSegment[],\n  index: number,\n  value: unknown,\n): unknown {\n  if (index === segments.length) {\n    return value;\n  }\n\n  const seg = segments[index]!;\n\n  if (typeof seg === \"number\") {\n    // Array index — ensure we have an array\n    const arr = Array.isArray(current) ? [...current] : [];\n    // Pad array if index is out of bounds\n    while (arr.length <= seg) {\n      arr.push(undefined);\n    }\n    arr[seg] = setAtPath(arr[seg], segments, index + 1, value);\n    return arr;\n  } else {\n    // Object key — ensure we have an object\n    const obj: Record<string, unknown> =\n      current !== null &&\n      current !== undefined &&\n      typeof current === \"object\" &&\n      !Array.isArray(current)\n        ? { ...(current as Record<string, unknown>) }\n        : {};\n    obj[seg] = setAtPath(obj[seg], segments, index + 1, value);\n    return obj;\n  }\n}\n\n/**\n * Resolve the schema at the projected path.\n * Numeric segments traverse into `items` (array item schema).\n * String segments traverse into `properties[segment]`.\n */\nexport function getProjectedSchema(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  schema: Record<string, any>,\n  path: string,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Record<string, any> {\n  const segments = parseProjectionPath(path);\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  let current: Record<string, any> = schema;\n\n  for (const seg of segments) {\n    if (!current) return {};\n\n    if (typeof seg === \"number\") {\n      // Array index → traverse into items schema\n      const items = current.items;\n      if (items && typeof items === \"object\") {\n        current = items as Record<string, unknown>;\n      } else {\n        return {};\n      }\n    } else {\n      // Object key → traverse into properties[key]\n      const properties = current.properties as\n        | Record<string, Record<string, unknown>>\n        | undefined;\n      if (properties && properties[seg]) {\n        current = properties[seg];\n      } else {\n        return {};\n      }\n    }\n  }\n\n  return current;\n}\n"],"names":[],"mappings":"AAgBO,SAAS,oBAAoB,MAAmC;AACrE,MAAI,CAAC,KAAM,QAAO,CAAA;AAClB,SAAO,KAAK,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM;AAChC,UAAM,IAAI,OAAO,CAAC;AAClB,WAAO,OAAO,UAAU,CAAC,KAAK,KAAK,IAAI,IAAI;AAAA,EAC7C,CAAC;AACH;AAMO,SAAS,kBAAkB,MAAe,MAAuB;AACtE,QAAM,WAAW,oBAAoB,IAAI;AACzC,MAAI,UAAmB;AAEvB,aAAW,OAAO,UAAU;AAC1B,QAAI,YAAY,QAAQ,YAAY,OAAW,QAAO;AAEtD,QAAI,OAAO,QAAQ,UAAU;AAC3B,UAAI,CAAC,MAAM,QAAQ,OAAO,EAAG,QAAO;AACpC,gBAAU,QAAQ,GAAG;AAAA,IACvB,OAAO;AACL,UAAI,OAAO,YAAY,SAAU,QAAO;AACxC,gBAAW,QAAoC,GAAG;AAAA,IACpD;AAAA,EACF;AAEA,SAAO;AACT;AAMO,SAAS,kBACd,MACA,MACA,OACS;AACT,QAAM,WAAW,oBAAoB,IAAI;AACzC,SAAO,UAAU,MAAM,UAAU,GAAG,KAAK;AAC3C;AAEA,SAAS,UACP,SACA,UACA,OACA,OACS;AACT,MAAI,UAAU,SAAS,QAAQ;AAC7B,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,SAAS,KAAK;AAE1B,MAAI,OAAO,QAAQ,UAAU;AAE3B,UAAM,MAAM,MAAM,QAAQ,OAAO,IAAI,CAAC,GAAG,OAAO,IAAI,CAAA;AAEpD,WAAO,IAAI,UAAU,KAAK;AACxB,UAAI,KAAK,MAAS;AAAA,IACpB;AACA,QAAI,GAAG,IAAI,UAAU,IAAI,GAAG,GAAG,UAAU,QAAQ,GAAG,KAAK;AACzD,WAAO;AAAA,EACT,OAAO;AAEL,UAAM,MACJ,YAAY,QACZ,YAAY,UACZ,OAAO,YAAY,YACnB,CAAC,MAAM,QAAQ,OAAO,IAClB,EAAE,GAAI,QAAA,IACN,CAAA;AACN,QAAI,GAAG,IAAI,UAAU,IAAI,GAAG,GAAG,UAAU,QAAQ,GAAG,KAAK;AACzD,WAAO;AAAA,EACT;AACF;AAOO,SAAS,mBAEd,QACA,MAEqB;AACrB,QAAM,WAAW,oBAAoB,IAAI;AAEzC,MAAI,UAA+B;AAEnC,aAAW,OAAO,UAAU;AAC1B,QAAI,CAAC,QAAS,QAAO,CAAA;AAErB,QAAI,OAAO,QAAQ,UAAU;AAE3B,YAAM,QAAQ,QAAQ;AACtB,UAAI,SAAS,OAAO,UAAU,UAAU;AACtC,kBAAU;AAAA,MACZ,OAAO;AACL,eAAO,CAAA;AAAA,MACT;AAAA,IACF,OAAO;AAEL,YAAM,aAAa,QAAQ;AAG3B,UAAI,cAAc,WAAW,GAAG,GAAG;AACjC,kBAAU,WAAW,GAAG;AAAA,MAC1B,OAAO;AACL,eAAO,CAAA;AAAA,MACT;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;"}
+{"version":3,"file":"projection.js","sources":["../../src/core/projection.ts"],"sourcesContent":["import { deref as derefSchema } from \"./refs\";\n\n/**\n * Projection utilities for navigating complex data structures\n * through a dot-separated path where numeric segments are array indices.\n *\n * Examples:\n *   \"0\"                → first element of an array\n *   \"include\"          → the `include` property of an object\n *   \"0.video_rate_usd\" → nested property inside the first array element\n */\n\nexport type ProjectionSegment = string | number;\n\n/**\n * Parse a projection path string into typed segments.\n * Numeric strings become numbers (array indices), others stay as strings (object keys).\n */\nexport function parseProjectionPath(path: string): ProjectionSegment[] {\n  if (!path) return [];\n  return path.split(\".\").map((s) => {\n    const n = Number(s);\n    return Number.isInteger(n) && n >= 0 ? n : s;\n  });\n}\n\n/**\n * Read a value from `data` by following the projection path.\n * Returns `undefined` if any segment along the path is missing.\n */\nexport function getProjectedValue(data: unknown, path: string): unknown {\n  const segments = parseProjectionPath(path);\n  let current: unknown = data;\n\n  for (const seg of segments) {\n    if (current === null || current === undefined) return undefined;\n\n    if (typeof seg === \"number\") {\n      if (!Array.isArray(current)) return undefined;\n      current = current[seg];\n    } else {\n      if (typeof current !== \"object\") return undefined;\n      current = (current as Record<string, unknown>)[seg];\n    }\n  }\n\n  return current;\n}\n\n/**\n * Immutably set a value at the projection path, preserving all sibling data.\n * Constructs missing intermediate structures (arrays for numeric segments, objects for string segments).\n */\nexport function setProjectedValue(\n  data: unknown,\n  path: string,\n  value: unknown,\n): unknown {\n  const segments = parseProjectionPath(path);\n  return setAtPath(data, segments, 0, value);\n}\n\nfunction setAtPath(\n  current: unknown,\n  segments: ProjectionSegment[],\n  index: number,\n  value: unknown,\n): unknown {\n  if (index === segments.length) {\n    return value;\n  }\n\n  const seg = segments[index]!;\n\n  if (typeof seg === \"number\") {\n    // Array index — ensure we have an array\n    const arr = Array.isArray(current) ? [...current] : [];\n    // Pad array if index is out of bounds\n    while (arr.length <= seg) {\n      arr.push(undefined);\n    }\n    arr[seg] = setAtPath(arr[seg], segments, index + 1, value);\n    return arr;\n  } else {\n    // Object key — ensure we have an object\n    const obj: Record<string, unknown> =\n      current !== null &&\n      current !== undefined &&\n      typeof current === \"object\" &&\n      !Array.isArray(current)\n        ? { ...(current as Record<string, unknown>) }\n        : {};\n    obj[seg] = setAtPath(obj[seg], segments, index + 1, value);\n    return obj;\n  }\n}\n\n/**\n * Resolve the schema at the projected path.\n * Numeric segments traverse into `items` (array item schema).\n * String segments traverse into `properties[segment]`.\n *\n * `$ref` nodes are dereferenced transparently at every step, so projections\n * that cross a `$ref` boundary (e.g. `items: { $ref: \"#/$defs/X\" }`) resolve\n * to the target schema rather than collapsing to `{}`.\n */\nexport function getProjectedSchema(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  schema: Record<string, any>,\n  path: string,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Record<string, any> {\n  const segments = parseProjectionPath(path);\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  let current: Record<string, any> | undefined = schema;\n\n  for (const seg of segments) {\n    current = derefSchema(current, schema);\n    if (!current) return {};\n\n    if (typeof seg === \"number\") {\n      // Array index → traverse into items schema\n      const items = current.items;\n      if (items && typeof items === \"object\") {\n        current = items as Record<string, unknown>;\n      } else {\n        return {};\n      }\n    } else {\n      // Object key → traverse into properties[key]\n      const properties = current.properties as\n        | Record<string, Record<string, unknown>>\n        | undefined;\n      if (properties && properties[seg]) {\n        current = properties[seg];\n      } else {\n        return {};\n      }\n    }\n  }\n\n  const resolved = derefSchema(current, schema);\n  return resolved ?? {};\n}\n"],"names":["derefSchema"],"mappings":";AAkBO,SAAS,oBAAoB,MAAmC;AACrE,MAAI,CAAC,KAAM,QAAO,CAAA;AAClB,SAAO,KAAK,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM;AAChC,UAAM,IAAI,OAAO,CAAC;AAClB,WAAO,OAAO,UAAU,CAAC,KAAK,KAAK,IAAI,IAAI;AAAA,EAC7C,CAAC;AACH;AAMO,SAAS,kBAAkB,MAAe,MAAuB;AACtE,QAAM,WAAW,oBAAoB,IAAI;AACzC,MAAI,UAAmB;AAEvB,aAAW,OAAO,UAAU;AAC1B,QAAI,YAAY,QAAQ,YAAY,OAAW,QAAO;AAEtD,QAAI,OAAO,QAAQ,UAAU;AAC3B,UAAI,CAAC,MAAM,QAAQ,OAAO,EAAG,QAAO;AACpC,gBAAU,QAAQ,GAAG;AAAA,IACvB,OAAO;AACL,UAAI,OAAO,YAAY,SAAU,QAAO;AACxC,gBAAW,QAAoC,GAAG;AAAA,IACpD;AAAA,EACF;AAEA,SAAO;AACT;AAMO,SAAS,kBACd,MACA,MACA,OACS;AACT,QAAM,WAAW,oBAAoB,IAAI;AACzC,SAAO,UAAU,MAAM,UAAU,GAAG,KAAK;AAC3C;AAEA,SAAS,UACP,SACA,UACA,OACA,OACS;AACT,MAAI,UAAU,SAAS,QAAQ;AAC7B,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,SAAS,KAAK;AAE1B,MAAI,OAAO,QAAQ,UAAU;AAE3B,UAAM,MAAM,MAAM,QAAQ,OAAO,IAAI,CAAC,GAAG,OAAO,IAAI,CAAA;AAEpD,WAAO,IAAI,UAAU,KAAK;AACxB,UAAI,KAAK,MAAS;AAAA,IACpB;AACA,QAAI,GAAG,IAAI,UAAU,IAAI,GAAG,GAAG,UAAU,QAAQ,GAAG,KAAK;AACzD,WAAO;AAAA,EACT,OAAO;AAEL,UAAM,MACJ,YAAY,QACZ,YAAY,UACZ,OAAO,YAAY,YACnB,CAAC,MAAM,QAAQ,OAAO,IAClB,EAAE,GAAI,QAAA,IACN,CAAA;AACN,QAAI,GAAG,IAAI,UAAU,IAAI,GAAG,GAAG,UAAU,QAAQ,GAAG,KAAK;AACzD,WAAO;AAAA,EACT;AACF;AAWO,SAAS,mBAEd,QACA,MAEqB;AACrB,QAAM,WAAW,oBAAoB,IAAI;AAEzC,MAAI,UAA2C;AAE/C,aAAW,OAAO,UAAU;AAC1B,cAAUA,MAAY,SAAS,MAAM;AACrC,QAAI,CAAC,QAAS,QAAO,CAAA;AAErB,QAAI,OAAO,QAAQ,UAAU;AAE3B,YAAM,QAAQ,QAAQ;AACtB,UAAI,SAAS,OAAO,UAAU,UAAU;AACtC,kBAAU;AAAA,MACZ,OAAO;AACL,eAAO,CAAA;AAAA,MACT;AAAA,IACF,OAAO;AAEL,YAAM,aAAa,QAAQ;AAG3B,UAAI,cAAc,WAAW,GAAG,GAAG;AACjC,kBAAU,WAAW,GAAG;AAAA,MAC1B,OAAO;AACL,eAAO,CAAA;AAAA,MACT;AAAA,IACF;AAAA,EACF;AAEA,QAAM,WAAWA,MAAY,SAAS,MAAM;AAC5C,SAAO,YAAY,CAAA;AACrB;"}

package/dist/core/refs.d.ts

@@ -0,0 +1,42 @@
+/**
+ * JSON Schema $ref resolution helpers.
+ *
+ * Supports the pointer grammar used across consumer schemas:
+ *   - "#/$defs/Name"
+ *   - "#/properties/foo/items"
+ *
+ * External refs (URIs, file refs) are intentionally out of scope. A ref that
+ * doesn't resolve leaves the node untouched — callers can still inspect the
+ * unresolved `$ref` for debugging.
+ */
+/**
+ * Resolve a JSON pointer (`#/a/b/c`) against an object. Returns the node at
+ * that path, or `undefined` if any segment is missing or the pointer doesn't
+ * start with `#/`.
+ */
+export declare function resolvePointer(obj: Record<string, unknown>, pointer: string): unknown;
+/**
+ * Dereference a schema node along a chain of `$ref`s. Follows `A → B → C`
+ * transitively. A cycle (same `$ref` seen twice in one chain) returns the
+ * last unresolved node rather than hanging. An unresolvable pointer returns
+ * the current node unchanged.
+ */
+export declare function resolveRef(property: Record<string, unknown>, root: Record<string, unknown>, seen?: Set<string>): Record<string, unknown>;
+/**
+ * Convenience wrapper around `resolveRef` that starts a fresh cycle-detection
+ * set. Intended for schema walkers that need to dereference at every step;
+ * each call is an independent resolution.
+ */
+export declare function deref(node: Record<string, any> | undefined, root: Record<string, any>): Record<string, any> | undefined;
+/**
+ * Recursively dereference every `$ref` in a schema subtree, producing a
+ * concrete schema with no remaining refs. Cycles along any single chain are
+ * handled by leaving the first recursion back into a seen ref as the
+ * unresolved node — matching `resolveRef`'s semantics.
+ *
+ * Intended for use at API boundaries (e.g. `resolveScopeSchema`'s return)
+ * so downstream walkers can operate on self-contained schemas without
+ * needing the original root.
+ */
+export declare function deepDeref(node: any, root: Record<string, any>, seen?: Set<string>): any;
+//# sourceMappingURL=refs.d.ts.map

package/dist/core/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/core/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,MAAM,GACd,OAAO,CAYT;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAEnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAErC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAExB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAGjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAEvB,IAAI,EAAE,GAAG,EAET,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAE5B,GAAG,CAoBL"}

package/dist/core/refs.js

@@ -0,0 +1,53 @@
+function resolvePointer(obj, pointer) {
+  if (!pointer.startsWith("#/")) return void 0;
+  const parts = pointer.slice(2).split("/");
+  let current = obj;
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in current) {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function resolveRef(property, root, seen) {
+  if (!property || typeof property !== "object") return property;
+  const ref = property.$ref;
+  if (!ref) return property;
+  const visited = seen ?? /* @__PURE__ */ new Set();
+  if (visited.has(ref)) return property;
+  visited.add(ref);
+  const resolved = resolvePointer(root, ref);
+  if (!resolved) return property;
+  return resolveRef(resolved, root, visited);
+}
+function deref(node, root) {
+  if (!node || typeof node !== "object") return node;
+  return resolveRef(node, root);
+}
+function deepDeref(node, root, seen = /* @__PURE__ */ new Set()) {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((n) => deepDeref(n, root, seen));
+  const ref = node.$ref;
+  if (typeof ref === "string") {
+    if (seen.has(ref)) return node;
+    const resolved = resolvePointer(root, ref);
+    if (!resolved || typeof resolved !== "object") return node;
+    const nextSeen = new Set(seen);
+    nextSeen.add(ref);
+    return deepDeref(resolved, root, nextSeen);
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = deepDeref(value, root, seen);
+  }
+  return result;
+}
+export {
+  deepDeref,
+  deref,
+  resolvePointer,
+  resolveRef
+};
+//# sourceMappingURL=refs.js.map

package/dist/core/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sources":["../../src/core/refs.ts"],"sourcesContent":["/**\n * JSON Schema $ref resolution helpers.\n *\n * Supports the pointer grammar used across consumer schemas:\n *   - \"#/$defs/Name\"\n *   - \"#/properties/foo/items\"\n *\n * External refs (URIs, file refs) are intentionally out of scope. A ref that\n * doesn't resolve leaves the node untouched — callers can still inspect the\n * unresolved `$ref` for debugging.\n */\n\n/**\n * Resolve a JSON pointer (`#/a/b/c`) against an object. Returns the node at\n * that path, or `undefined` if any segment is missing or the pointer doesn't\n * start with `#/`.\n */\nexport function resolvePointer(\n  obj: Record<string, unknown>,\n  pointer: string,\n): unknown {\n  if (!pointer.startsWith(\"#/\")) return undefined;\n  const parts = pointer.slice(2).split(\"/\");\n  let current: unknown = obj;\n  for (const part of parts) {\n    if (current && typeof current === \"object\" && part in current) {\n      current = (current as Record<string, unknown>)[part];\n    } else {\n      return undefined;\n    }\n  }\n  return current;\n}\n\n/**\n * Dereference a schema node along a chain of `$ref`s. Follows `A → B → C`\n * transitively. A cycle (same `$ref` seen twice in one chain) returns the\n * last unresolved node rather than hanging. An unresolvable pointer returns\n * the current node unchanged.\n */\nexport function resolveRef(\n  property: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seen?: Set<string>,\n): Record<string, unknown> {\n  if (!property || typeof property !== \"object\") return property;\n\n  const ref = property.$ref as string | undefined;\n  if (!ref) return property;\n\n  const visited = seen ?? new Set<string>();\n  if (visited.has(ref)) return property;\n  visited.add(ref);\n\n  const resolved = resolvePointer(root, ref);\n  if (!resolved) return property;\n\n  return resolveRef(resolved as Record<string, unknown>, root, visited);\n}\n\n/**\n * Convenience wrapper around `resolveRef` that starts a fresh cycle-detection\n * set. Intended for schema walkers that need to dereference at every step;\n * each call is an independent resolution.\n */\nexport function deref(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  node: Record<string, any> | undefined,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  root: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Record<string, any> | undefined {\n  if (!node || typeof node !== \"object\") return node;\n  return resolveRef(node, root) as Record<string, unknown> | undefined;\n}\n\n/**\n * Recursively dereference every `$ref` in a schema subtree, producing a\n * concrete schema with no remaining refs. Cycles along any single chain are\n * handled by leaving the first recursion back into a seen ref as the\n * unresolved node — matching `resolveRef`'s semantics.\n *\n * Intended for use at API boundaries (e.g. `resolveScopeSchema`'s return)\n * so downstream walkers can operate on self-contained schemas without\n * needing the original root.\n */\nexport function deepDeref(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  node: any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  root: Record<string, any>,\n  seen: Set<string> = new Set(),\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): any {\n  if (!node || typeof node !== \"object\") return node;\n  if (Array.isArray(node)) return node.map((n) => deepDeref(n, root, seen));\n\n  const ref = (node as Record<string, unknown>).$ref as string | undefined;\n  if (typeof ref === \"string\") {\n    if (seen.has(ref)) return node;\n    const resolved = resolvePointer(root, ref);\n    if (!resolved || typeof resolved !== \"object\") return node;\n    const nextSeen = new Set(seen);\n    nextSeen.add(ref);\n    return deepDeref(resolved, root, nextSeen);\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const result: Record<string, any> = {};\n  for (const [key, value] of Object.entries(node)) {\n    result[key] = deepDeref(value, root, seen);\n  }\n  return result;\n}\n"],"names":[],"mappings":"AAiBO,SAAS,eACd,KACA,SACS;AACT,MAAI,CAAC,QAAQ,WAAW,IAAI,EAAG,QAAO;AACtC,QAAM,QAAQ,QAAQ,MAAM,CAAC,EAAE,MAAM,GAAG;AACxC,MAAI,UAAmB;AACvB,aAAW,QAAQ,OAAO;AACxB,QAAI,WAAW,OAAO,YAAY,YAAY,QAAQ,SAAS;AAC7D,gBAAW,QAAoC,IAAI;AAAA,IACrD,OAAO;AACL,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAQO,SAAS,WACd,UACA,MACA,MACyB;AACzB,MAAI,CAAC,YAAY,OAAO,aAAa,SAAU,QAAO;AAEtD,QAAM,MAAM,SAAS;AACrB,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,UAAU,QAAQ,oBAAI,IAAA;AAC5B,MAAI,QAAQ,IAAI,GAAG,EAAG,QAAO;AAC7B,UAAQ,IAAI,GAAG;AAEf,QAAM,WAAW,eAAe,MAAM,GAAG;AACzC,MAAI,CAAC,SAAU,QAAO;AAEtB,SAAO,WAAW,UAAqC,MAAM,OAAO;AACtE;AAOO,SAAS,MAEd,MAEA,MAEiC;AACjC,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO;AAC9C,SAAO,WAAW,MAAM,IAAI;AAC9B;AAYO,SAAS,UAEd,MAEA,MACA,OAAoB,oBAAI,OAEnB;AACL,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO;AAC9C,MAAI,MAAM,QAAQ,IAAI,EAAG,QAAO,KAAK,IAAI,CAAC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;AAExE,QAAM,MAAO,KAAiC;AAC9C,MAAI,OAAO,QAAQ,UAAU;AAC3B,QAAI,KAAK,IAAI,GAAG,EAAG,QAAO;AAC1B,UAAM,WAAW,eAAe,MAAM,GAAG;AACzC,QAAI,CAAC,YAAY,OAAO,aAAa,SAAU,QAAO;AACtD,UAAM,WAAW,IAAI,IAAI,IAAI;AAC7B,aAAS,IAAI,GAAG;AAChB,WAAO,UAAU,UAAU,MAAM,QAAQ;AAAA,EAC3C;AAGA,QAAM,SAA8B,CAAA;AACpC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,WAAO,GAAG,IAAI,UAAU,OAAO,MAAM,IAAI;AAAA,EAC3C;AACA,SAAO;AACT;"}

package/dist/core/resolveScope.d.ts

@@ -6,6 +6,12 @@
  *   - "properties" segments navigate into object `.properties`
  *   - "items" segments navigate into array `.items`
  *   - all other segments index directly into the current object
+ *
+ * `$ref` nodes are dereferenced transparently at every step, so scopes that
+ * cross a `$ref` boundary (e.g. `items: { $ref: "#/$defs/X" }`) resolve to
+ * the target schema rather than returning `{}`. The returned schema is also
+ * deep-dereferenced so downstream walkers (e.g. `getProjectedSchema`) can
+ * operate on a self-contained sub-schema without needing the original root.
  */
 export declare function resolveScopeSchema(scope: string, rootSchema: Record<string, any>): Record<string, any> | undefined;
 //# sourceMappingURL=resolveScope.d.ts.map

package/dist/core/resolveScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveScope.d.ts","sourceRoot":"","sources":["../../src/core/resolveScope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EAEb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAE9B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAwBjC"}
+{"version":3,"file":"resolveScope.d.ts","sourceRoot":"","sources":["../../src/core/resolveScope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EAEb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAE9B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAyBjC"}

package/dist/core/resolveScope.js

@@ -1,10 +1,12 @@
+import { deepDeref, deref } from "./refs.js";
 function resolveScopeSchema(scope, rootSchema) {
   if (!scope || !rootSchema) return void 0;
   const path = scope.replace(/^#\/?/, "");
-  if (!path) return rootSchema;
+  if (!path) return deepDeref(rootSchema, rootSchema);
   const segments = path.split("/");
   let current = rootSchema;
   for (const segment of segments) {
+    current = deref(current, rootSchema);
     if (!current || typeof current !== "object") return void 0;
     if (segment === "properties") {
       current = current.properties;
@@ -14,7 +16,7 @@ function resolveScopeSchema(scope, rootSchema) {
       current = current[segment];
     }
   }
-  return current;
+  return deepDeref(current, rootSchema);
 }
 export {
   resolveScopeSchema

package/dist/core/resolveScope.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveScope.js","sources":["../../src/core/resolveScope.ts"],"sourcesContent":["/**\n * Resolve a JSON Forms scope path to its schema within a root schema.\n * Handles nested paths like \"#/properties/parent/properties/child\".\n *\n * Follows JSON Schema structure:\n *   - \"properties\" segments navigate into object `.properties`\n *   - \"items\" segments navigate into array `.items`\n *   - all other segments index directly into the current object\n */\nexport function resolveScopeSchema(\n  scope: string,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  rootSchema: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Record<string, any> | undefined {\n  if (!scope || !rootSchema) return undefined;\n\n  // Remove the leading \"#/\" and split into segments\n  const path = scope.replace(/^#\\/?/, \"\");\n  if (!path) return rootSchema;\n\n  const segments = path.split(\"/\");\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  let current: any = rootSchema;\n\n  for (const segment of segments) {\n    if (!current || typeof current !== \"object\") return undefined;\n\n    if (segment === \"properties\") {\n      current = current.properties;\n    } else if (segment === \"items\") {\n      current = current.items;\n    } else {\n      current = current[segment];\n    }\n  }\n\n  return current;\n}\n"],"names":[],"mappings":"AASO,SAAS,mBACd,OAEA,YAEiC;AACjC,MAAI,CAAC,SAAS,CAAC,WAAY,QAAO;AAGlC,QAAM,OAAO,MAAM,QAAQ,SAAS,EAAE;AACtC,MAAI,CAAC,KAAM,QAAO;AAElB,QAAM,WAAW,KAAK,MAAM,GAAG;AAE/B,MAAI,UAAe;AAEnB,aAAW,WAAW,UAAU;AAC9B,QAAI,CAAC,WAAW,OAAO,YAAY,SAAU,QAAO;AAEpD,QAAI,YAAY,cAAc;AAC5B,gBAAU,QAAQ;AAAA,IACpB,WAAW,YAAY,SAAS;AAC9B,gBAAU,QAAQ;AAAA,IACpB,OAAO;AACL,gBAAU,QAAQ,OAAO;AAAA,IAC3B;AAAA,EACF;AAEA,SAAO;AACT;"}
+{"version":3,"file":"resolveScope.js","sources":["../../src/core/resolveScope.ts"],"sourcesContent":["import { deepDeref, deref } from \"./refs\";\n\n/**\n * Resolve a JSON Forms scope path to its schema within a root schema.\n * Handles nested paths like \"#/properties/parent/properties/child\".\n *\n * Follows JSON Schema structure:\n *   - \"properties\" segments navigate into object `.properties`\n *   - \"items\" segments navigate into array `.items`\n *   - all other segments index directly into the current object\n *\n * `$ref` nodes are dereferenced transparently at every step, so scopes that\n * cross a `$ref` boundary (e.g. `items: { $ref: \"#/$defs/X\" }`) resolve to\n * the target schema rather than returning `{}`. The returned schema is also\n * deep-dereferenced so downstream walkers (e.g. `getProjectedSchema`) can\n * operate on a self-contained sub-schema without needing the original root.\n */\nexport function resolveScopeSchema(\n  scope: string,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  rootSchema: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Record<string, any> | undefined {\n  if (!scope || !rootSchema) return undefined;\n\n  // Remove the leading \"#/\" and split into segments\n  const path = scope.replace(/^#\\/?/, \"\");\n  if (!path) return deepDeref(rootSchema, rootSchema);\n\n  const segments = path.split(\"/\");\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  let current: any = rootSchema;\n\n  for (const segment of segments) {\n    current = deref(current, rootSchema);\n    if (!current || typeof current !== \"object\") return undefined;\n\n    if (segment === \"properties\") {\n      current = current.properties;\n    } else if (segment === \"items\") {\n      current = current.items;\n    } else {\n      current = current[segment];\n    }\n  }\n\n  return deepDeref(current, rootSchema);\n}\n"],"names":[],"mappings":";AAiBO,SAAS,mBACd,OAEA,YAEiC;AACjC,MAAI,CAAC,SAAS,CAAC,WAAY,QAAO;AAGlC,QAAM,OAAO,MAAM,QAAQ,SAAS,EAAE;AACtC,MAAI,CAAC,KAAM,QAAO,UAAU,YAAY,UAAU;AAElD,QAAM,WAAW,KAAK,MAAM,GAAG;AAE/B,MAAI,UAAe;AAEnB,aAAW,WAAW,UAAU;AAC9B,cAAU,MAAM,SAAS,UAAU;AACnC,QAAI,CAAC,WAAW,OAAO,YAAY,SAAU,QAAO;AAEpD,QAAI,YAAY,cAAc;AAC5B,gBAAU,QAAQ;AAAA,IACpB,WAAW,YAAY,SAAS;AAC9B,gBAAU,QAAQ;AAAA,IACpB,OAAO;AACL,gBAAU,QAAQ,OAAO;AAAA,IAC3B;AAAA,EACF;AAEA,SAAO,UAAU,SAAS,UAAU;AACtC;"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/jsonforms-provider-protocols",
-	"version": "3.0.0-beta.16",
+	"version": "3.0.0-beta.17",
 	"description": "Dynamic data provider capabilities for JSONForms with Vue 3 integration",
 	"type": "module",
 	"author": "Narrative I/O",

package/src/core/initFormData.ts

@@ -44,49 +44,7 @@ export function initFormDataFromSchema(
   return base;
 }
 
-/**
- * Resolve a $ref pointer against the root schema's $defs.
- * Supports nested $ref chains.
- */
-function resolveRef(
-  property: Record<string, unknown>,
-  root: Record<string, unknown>,
-  seen?: Set<string>,
-): Record<string, unknown> {
-  if (!property || typeof property !== "object") return property;
-
-  const ref = property.$ref as string | undefined;
-  if (!ref) return property;
-
-  const visited = seen ?? new Set<string>();
-  if (visited.has(ref)) return property;
-  visited.add(ref);
-
-  const resolved = resolvePointer(root, ref);
-  if (!resolved) return property;
-
-  return resolveRef(resolved as Record<string, unknown>, root, visited);
-}
-
-/**
- * Resolve a JSON pointer like "#/$defs/Price" against an object.
- */
-function resolvePointer(
-  obj: Record<string, unknown>,
-  pointer: string,
-): unknown {
-  if (!pointer.startsWith("#/")) return undefined;
-  const parts = pointer.slice(2).split("/");
-  let current: unknown = obj;
-  for (const part of parts) {
-    if (current && typeof current === "object" && part in current) {
-      current = (current as Record<string, unknown>)[part];
-    } else {
-      return undefined;
-    }
-  }
-  return current;
-}
+import { resolveRef } from "./refs";
 
 /**
  * Initialize a single property value based on its schema definition.

package/src/core/projection.ts

@@ -1,3 +1,5 @@
+import { deref as derefSchema } from "./refs";
+
 /**
  * Projection utilities for navigating complex data structures
  * through a dot-separated path where numeric segments are array indices.
@@ -97,6 +99,10 @@ function setAtPath(
  * Resolve the schema at the projected path.
  * Numeric segments traverse into `items` (array item schema).
  * String segments traverse into `properties[segment]`.
+ *
+ * `$ref` nodes are dereferenced transparently at every step, so projections
+ * that cross a `$ref` boundary (e.g. `items: { $ref: "#/$defs/X" }`) resolve
+ * to the target schema rather than collapsing to `{}`.
  */
 export function getProjectedSchema(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -106,9 +112,10 @@ export function getProjectedSchema(
 ): Record<string, any> {
   const segments = parseProjectionPath(path);
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let current: Record<string, any> = schema;
+  let current: Record<string, any> | undefined = schema;
 
   for (const seg of segments) {
+    current = derefSchema(current, schema);
     if (!current) return {};
 
     if (typeof seg === "number") {
@@ -132,5 +139,6 @@ export function getProjectedSchema(
     }
   }
 
-  return current;
+  const resolved = derefSchema(current, schema);
+  return resolved ?? {};
 }

package/src/core/refs.ts

@@ -0,0 +1,114 @@
+/**
+ * JSON Schema $ref resolution helpers.
+ *
+ * Supports the pointer grammar used across consumer schemas:
+ *   - "#/$defs/Name"
+ *   - "#/properties/foo/items"
+ *
+ * External refs (URIs, file refs) are intentionally out of scope. A ref that
+ * doesn't resolve leaves the node untouched — callers can still inspect the
+ * unresolved `$ref` for debugging.
+ */
+
+/**
+ * Resolve a JSON pointer (`#/a/b/c`) against an object. Returns the node at
+ * that path, or `undefined` if any segment is missing or the pointer doesn't
+ * start with `#/`.
+ */
+export function resolvePointer(
+  obj: Record<string, unknown>,
+  pointer: string,
+): unknown {
+  if (!pointer.startsWith("#/")) return undefined;
+  const parts = pointer.slice(2).split("/");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in current) {
+      current = (current as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Dereference a schema node along a chain of `$ref`s. Follows `A → B → C`
+ * transitively. A cycle (same `$ref` seen twice in one chain) returns the
+ * last unresolved node rather than hanging. An unresolvable pointer returns
+ * the current node unchanged.
+ */
+export function resolveRef(
+  property: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seen?: Set<string>,
+): Record<string, unknown> {
+  if (!property || typeof property !== "object") return property;
+
+  const ref = property.$ref as string | undefined;
+  if (!ref) return property;
+
+  const visited = seen ?? new Set<string>();
+  if (visited.has(ref)) return property;
+  visited.add(ref);
+
+  const resolved = resolvePointer(root, ref);
+  if (!resolved) return property;
+
+  return resolveRef(resolved as Record<string, unknown>, root, visited);
+}
+
+/**
+ * Convenience wrapper around `resolveRef` that starts a fresh cycle-detection
+ * set. Intended for schema walkers that need to dereference at every step;
+ * each call is an independent resolution.
+ */
+export function deref(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> | undefined {
+  if (!node || typeof node !== "object") return node;
+  return resolveRef(node, root) as Record<string, unknown> | undefined;
+}
+
+/**
+ * Recursively dereference every `$ref` in a schema subtree, producing a
+ * concrete schema with no remaining refs. Cycles along any single chain are
+ * handled by leaving the first recursion back into a seen ref as the
+ * unresolved node — matching `resolveRef`'s semantics.
+ *
+ * Intended for use at API boundaries (e.g. `resolveScopeSchema`'s return)
+ * so downstream walkers can operate on self-contained schemas without
+ * needing the original root.
+ */
+export function deepDeref(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  seen: Set<string> = new Set(),
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((n) => deepDeref(n, root, seen));
+
+  const ref = (node as Record<string, unknown>).$ref as string | undefined;
+  if (typeof ref === "string") {
+    if (seen.has(ref)) return node;
+    const resolved = resolvePointer(root, ref);
+    if (!resolved || typeof resolved !== "object") return node;
+    const nextSeen = new Set(seen);
+    nextSeen.add(ref);
+    return deepDeref(resolved, root, nextSeen);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = deepDeref(value, root, seen);
+  }
+  return result;
+}

package/src/core/resolveScope.ts

@@ -1,3 +1,5 @@
+import { deepDeref, deref } from "./refs";
+
 /**
  * Resolve a JSON Forms scope path to its schema within a root schema.
  * Handles nested paths like "#/properties/parent/properties/child".
@@ -6,6 +8,12 @@
  *   - "properties" segments navigate into object `.properties`
  *   - "items" segments navigate into array `.items`
  *   - all other segments index directly into the current object
+ *
+ * `$ref` nodes are dereferenced transparently at every step, so scopes that
+ * cross a `$ref` boundary (e.g. `items: { $ref: "#/$defs/X" }`) resolve to
+ * the target schema rather than returning `{}`. The returned schema is also
+ * deep-dereferenced so downstream walkers (e.g. `getProjectedSchema`) can
+ * operate on a self-contained sub-schema without needing the original root.
  */
 export function resolveScopeSchema(
   scope: string,
@@ -17,13 +25,14 @@ export function resolveScopeSchema(
 
   // Remove the leading "#/" and split into segments
   const path = scope.replace(/^#\/?/, "");
-  if (!path) return rootSchema;
+  if (!path) return deepDeref(rootSchema, rootSchema);
 
   const segments = path.split("/");
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let current: any = rootSchema;
 
   for (const segment of segments) {
+    current = deref(current, rootSchema);
     if (!current || typeof current !== "object") return undefined;
 
     if (segment === "properties") {
@@ -35,5 +44,5 @@ export function resolveScopeSchema(
     }
   }
 
-  return current;
+  return deepDeref(current, rootSchema);
 }