@scalar/json-magic 0.13.5 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @scalar/json-magic
 
+## 0.15.0
+
+### Minor Changes
+
+- [#10206](https://github.com/scalar/scalar/pull/10206): Preserve authored references between embedded schema resources when the containing document has no declared identity. This keeps references valid across `$id` scopes and when exporting the bundle to a different retrieval URL.
+- [#10274](https://github.com/scalar/scalar/pull/10274): Add a standard-agnostic `join` utility with configurable merge strategies and conflict reporting to `@scalar/json-magic/join`. Use it in the OpenAPI parser while retaining OpenAPI upgrades, component prefixes, and OpenAPI conflict reports in the parser.
+- [#10206](https://github.com/scalar/scalar/pull/10206): Add generic document identity hooks for bundling and an explicit root URI option for reference proxies. Honor OpenAPI 3.2 `$self` through an OpenAPI plugin in workspace-store, including external documents and partial bundles, and enable it in OpenAPI bundling callers.
+
+  URI resolution now honors root-relative and protocol-relative URLs, query/fragment references, and trailing-slash directory bases for all bundler consumers. Absolute non-HTTP identifiers remain unchanged instead of becoming filesystem paths; loader support is unchanged. Relative HTTP references retain query strings and fragments and are emitted only when they round-trip to the original URL.
+
+  Preserve authored reference spellings through serialized partial bundles and editable exports, while keeping older OpenAPI resolution and configured loader restrictions unchanged.
+
+  Keep references matching authored root schema identifiers intact so schema labels and anchors retain their existing behavior.
+
+## 0.14.0
+
+### Minor Changes
+
+- [#10241](https://github.com/scalar/scalar/pull/10241): Expose helpers for indexing locally embedded `$id` and `$anchor` resources and resolving a reference to its local path.
+
+### Patch Changes
+
+- [#10257](https://github.com/scalar/scalar/pull/10257): Resolve a relative reference reached through a local pointer during a partial bundle against the document origin; it was resolved against an empty base and failed.
+
 ## 0.13.5
 
 ### Patch Changes

package/README.md

@@ -37,6 +37,7 @@ There is no root export. Every module is imported from its own entry point, so y
 | `@scalar/json-magic/bundle/plugins/node` | `fetchUrls`, `parseJson`, `parseYaml`, `readFiles` |
 | `@scalar/json-magic/bundle/value-generator` | `getHash`, `generateUniqueValue`, `uniqueValueGeneratorFactory` |
 | `@scalar/json-magic/dereference` | `dereference` |
+| `@scalar/json-magic/join` | `join`, plus the `JoinOptions`, `JoinStrategy`, `JoinContext`, `JoinConflict` and `JoinResult` types |
 | `@scalar/json-magic/diff` | `diff`, `merge`, `apply`, the `Difference` type |
 | `@scalar/json-magic/magic-proxy` | `createMagicProxy`, `getRaw` |
 | `@scalar/json-magic/helpers/*` | Small standalone helpers, see [Helpers](#helpers) |
@@ -50,10 +51,71 @@ There is no root export. Every module is imported from its own entry point, so y
 | Resolve every `$ref`, internal and external, in one call | [`dereference`](#dereference) |
 | Compare two documents and merge concurrent edits | [`diff`](#diff) |
 
+## join
+
+`join` combines JSON objects without assuming a document standard. It merges objects recursively and replaces arrays and scalar values with those from later inputs. It does not mutate inputs, upgrade document versions, resolve references, or rename definitions. Literal keys such as `__proto__`, `constructor`, and `prototype` are preserved as own data properties without changing object prototypes.
+
+```ts
+import { join } from '@scalar/json-magic/join'
+
+const result = join(
+  [
+    { title: 'First', catalog: { apple: { price: 2 } }, labels: [{ name: 'fruit' }] },
+    { title: 'Second', catalog: { pear: { price: 3 } }, labels: [{ name: 'fruit' }] },
+  ],
+  {
+    strategy: ({ path }) => {
+      if (path[0] === 'catalog' && path.length === 2) {
+        return 'conflict'
+      }
+      if (path[0] === 'labels') {
+        return { uniqueBy: 'name' }
+      }
+      return 'merge'
+    },
+  },
+)
+
+if (result.ok) {
+  console.log(result.document) // Both catalog entries, title "Second", one fruit label
+} else {
+  console.log(result.conflicts) // Example: [{ path: ['catalog', 'apple'] }]
+}
+```
+
+The optional `strategy` callback receives `{ path, current, incoming }` for each visited field. Paths are arrays of literal keys, so a key containing `/` remains one segment. The root always merges; returning `replace` or `conflict` for an object treats that object as a whole and does not visit its children.
+
+| Strategy | Behavior |
+| --- | --- |
+| `merge` (default) | Recursively merge objects; replace other values using the later input. |
+| `merge-by-index` | Recursively merge objects and arrays, combining array entries at matching indexes and retaining trailing entries. |
+| `skip` | Ignore this incoming field, leaving any existing value unchanged. |
+| `replace` | Replace the entire value, including objects. |
+| `conflict` | Report a duplicate key, even if both values are equal or the earlier value is null. |
+| `{ uniqueBy: 'name' }` | Combine arrays, retaining the first item for each identity property value. Items without that property remain distinct. Use scalar identity values. Non-array incoming values replace the existing value. |
+
+An empty input list returns `{ ok: true, document: {} }`. Conflicts return `{ ok: false, conflicts }` without a partial document. Inputs must be acyclic JSON objects.
+
+For OpenAPI, use `join` from `@scalar/openapi-parser`, which supplies OpenAPI rules, version upgrades, and optional component prefixes. Other formats can supply their own rules; this module does not include an AsyncAPI adapter.
+
 ## bundle
 
 `bundle` walks a JSON object, resolves every external `$ref` (URLs, local files, or anything a custom loader plugin can handle) and embeds the result into the document itself. The original `$ref` values are rewritten to point at the embedded copies, so the output is a single self-contained document.
 
+Document formats can supply a `resolveDocument` lifecycle hook returning `{ baseUri, metadata }`. The bundler resolves relative references against that base URI and retains the supplied root metadata when tree shaking. The hook also applies to cached and previously bundled documents. Without a hook, the retrieval URI remains the document base. JSON Schema `$id` values resolve against their enclosing base.
+
+When reading qualified root references with `createMagicProxy`, pass the canonical URI as `documentUri`. Interpretation of format-specific identity fields belongs in the caller or a plugin.
+
+URI resolution applies to every bundling path, including descriptions without `$self`:
+
+- Absolute scheme-bearing references (`https:`, `file:`, `urn:`, `mailto:`, or custom schemes) retain their identity. This does not enable fetching those schemes; loader plugins still decide what they support.
+- Hierarchical URI bases use URL resolution. Root-relative references replace the pathname; protocol-relative references replace the host. A new document path drops the base query and fragment, while query-only or fragment-only references keep the applicable parts of the base.
+- A base ending in `/` denotes a directory. Without the slash, the final segment is a document name. Scheme-less paths continue to use filesystem resolution, including Windows drive paths.
+- Opaque identities such as URNs support absolute and fragment references, but cannot provide a directory for a relative document path. Such a resolution throws rather than inventing a local path.
+- Relativization preserves query strings, fragments, and directory slashes. HTTP references become relative only when resolving them again reproduces the original URL. Non-HTTP URIs remain absolute: the generic helper has no document registry, so limiting this rule to known `$self` values would corrupt other identifiers.
+
+These are intentional URI compatibility changes, rather than behavior limited to OpenAPI `$self`.
+
 External documents are stored under the `x-ext` key, and the mapping between the generated keys and their original URLs is stored under `x-ext-urls`. Both keys are configurable, see [Options](#options).
 
 ### Quick start

package/dist/bundle/bundle.d.ts

@@ -1,4 +1,5 @@
 import type { UnknownObject } from '../types.js';
+import { type DocumentResolver } from './document-references.js';
 /**
  * Checks if a string is a local reference (starts with #)
  * @param value - The reference string to check
@@ -93,7 +94,7 @@ export declare function prefixInternalRefRecursive(input: unknown, prefix: strin
  * // Result: target will contain the User schema with resolved references
  * ```
  */
-export declare const resolveAndCopyReferences: (targetDocument: unknown, sourceDocument: unknown, referencePath: string, externalRefsKey: string, documentKey: string, bundleLocalRefs?: boolean, processedNodes?: Set<unknown>) => void;
+export declare const resolveAndCopyReferences: (targetDocument: unknown, sourceDocument: unknown, referencePath: string, externalRefsKey: string, documentKey: string, bundleLocalRefs?: boolean, processedNodes?: Set<unknown>, documentMetadata?: Record<string, unknown>) => void;
 /**
  * A loader plugin for resolving external references during bundling.
  * Loader plugins are responsible for handling specific types of external references,
@@ -235,6 +236,11 @@ type Config = {
      * Allows tracking the progress and status of reference resolution.
      */
     hooks?: Partial<{
+        /** Called once a complete document is available, including cached and saved documents.
+         * The first resolver returning an identity supplies its base URI and retained metadata.
+         * This hook is synchronous because identities are indexed before following references.
+         */
+        resolveDocument: DocumentResolver;
         /**
          * Optional hook called when the bundler starts resolving a $ref.
          * Useful for tracking or logging the beginning of a reference resolution.

package/dist/bundle/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle/bundle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle/bundle.ts"],"names":[],"mappings":"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"}

package/dist/bundle/bundle.js

@@ -1,6 +1,5 @@
 import { isObject } from '@scalar/helpers/object/is-object';
-import { convertToLocalRef } from '../helpers/convert-to-local-ref.js';
-import { getId, getSchemas } from '../helpers/get-schemas.js';
+import { getId } from '../helpers/get-schemas.js';
 import { getValueByPath } from '../helpers/get-value-by-path.js';
 import { isFilePath } from '../helpers/is-file-path.js';
 import { isHttpUrl } from '../helpers/is-http-url.js';
@@ -9,6 +8,7 @@ import { setValueAtPath } from '../helpers/set-value-at-path.js';
 import { toRelativePath } from '../helpers/to-relative-path.js';
 import { escapeJsonPointer } from '../helpers/escape-json-pointer.js';
 import { getSegmentsFromPath } from '../helpers/get-segments-from-path.js';
+import { documentReferences } from './document-references.js';
 import { getHash, uniqueValueGeneratorFactory } from './value-generator.js';
 /** Type guard to check if a value is an object with a $ref property */
 const hasRef = (value) => isObject(value) && '$ref' in value && typeof value['$ref'] === 'string';
@@ -144,13 +144,35 @@ export function prefixInternalRefRecursive(input, prefix) {
  * // Result: target will contain the User schema with resolved references
  * ```
  */
-export const resolveAndCopyReferences = (targetDocument, sourceDocument, referencePath, externalRefsKey, documentKey, bundleLocalRefs = false, processedNodes = new Set()) => {
+export const resolveAndCopyReferences = (targetDocument, sourceDocument, referencePath, externalRefsKey, documentKey, bundleLocalRefs = false, processedNodes = new Set(), documentMetadata = {}) => {
     const referencedValue = getValueByPath(sourceDocument, getSegmentsFromPath(referencePath)).value;
     if (processedNodes.has(referencedValue)) {
         return;
     }
     processedNodes.add(referencedValue);
-    setValueAtPath(targetDocument, referencePath, referencedValue);
+    // Only relocated copies need canonical metadata; keep the authored source unchanged.
+    const segments = getSegmentsFromPath(referencePath);
+    const copiedValue = segments.length === 2 && isObject(referencedValue) && Object.keys(documentMetadata).length > 0
+        ? { ...referencedValue, ...documentMetadata }
+        : referencedValue;
+    setValueAtPath(targetDocument, referencePath, copiedValue);
+    // Keep every enclosing base when copying a subtree, so later partial bundles
+    // resolve against the same document and schema resources as the original.
+    for (let length = 2; length < segments.length; length++) {
+        const ancestorPath = segments.slice(0, length);
+        const ancestor = getValueByPath(sourceDocument, ancestorPath).value;
+        if (!isObject(ancestor)) {
+            continue;
+        }
+        if (length === 2) {
+            for (const [key, value] of Object.entries(documentMetadata)) {
+                setValueAtPath(targetDocument, `/${[...ancestorPath, key].map(escapeJsonPointer).join('/')}`, value);
+            }
+        }
+        if (typeof ancestor.$id === 'string') {
+            setValueAtPath(targetDocument, `/${[...ancestorPath, '$id'].map(escapeJsonPointer).join('/')}`, ancestor.$id);
+        }
+    }
     // Do the same for each local ref
     const traverse = (node) => {
         if (!node || typeof node !== 'object') {
@@ -162,11 +184,11 @@ export const resolveAndCopyReferences = (targetDocument, sourceDocument, referen
             // 2. The source document only contains the current document's content
             // This prevents undefined behavior and maintains proper document boundaries
             if (node['$ref'].startsWith(`#/${externalRefsKey}/${escapeJsonPointer(documentKey)}`)) {
-                resolveAndCopyReferences(targetDocument, sourceDocument, node['$ref'].substring(1), externalRefsKey, documentKey, bundleLocalRefs, processedNodes);
+                resolveAndCopyReferences(targetDocument, sourceDocument, node['$ref'].substring(1), externalRefsKey, documentKey, bundleLocalRefs, processedNodes, documentMetadata);
             }
             // Bundle the local refs as well
             else if (bundleLocalRefs) {
-                resolveAndCopyReferences(targetDocument, sourceDocument, node['$ref'].substring(1), externalRefsKey, documentKey, bundleLocalRefs, processedNodes);
+                resolveAndCopyReferences(targetDocument, sourceDocument, node['$ref'].substring(1), externalRefsKey, documentKey, bundleLocalRefs, processedNodes, documentMetadata);
             }
         }
         for (const value of Object.values(node)) {
@@ -288,8 +310,6 @@ export async function bundle(input, config) {
     // Document root used to write all external documents
     // We need this when we want to do a partial bundle of a document
     const documentRoot = config.root ?? rawSpecification;
-    // Extract all $id and $anchor values from the document to identify local schemas
-    const schemas = getSchemas(documentRoot);
     // Determines if the bundling operation is partial.
     // Partial bundling occurs when:
     // - A root document is provided that is different from the raw specification being bundled, or
@@ -302,11 +322,6 @@ export async function bundle(input, config) {
     // For string inputs that are URLs or file paths, uses the input as the origin.
     // For non-string inputs or other string types, returns an '/' as a root path.
     const getDefaultOrigin = () => {
-        // Id field is the first priority
-        const id = getId(documentRoot);
-        if (id) {
-            return id;
-        }
         if (config.origin) {
             return config.origin;
         }
@@ -318,12 +333,48 @@ export async function bundle(input, config) {
         }
         return '/';
     };
-    const defaultOrigin = getDefaultOrigin();
+    const references = documentReferences(config.externalDocumentsKey, (document, retrievalUri) => {
+        for (const resolver of [
+            config.hooks?.resolveDocument,
+            ...lifecyclePlugin.map((plugin) => plugin.resolveDocument),
+        ]) {
+            const identity = resolver?.(document, retrievalUri);
+            if (identity !== undefined) {
+                return identity;
+            }
+        }
+        return undefined;
+    });
+    references.register(documentRoot, getDefaultOrigin());
+    const defaultOrigin = references.origin(documentRoot) ?? getDefaultOrigin();
+    const hasRootIdentity = references.identity(documentRoot) !== undefined || getId(documentRoot) !== undefined;
+    const referenceToRoot = (pointer, sourceOrigin) => {
+        return hasRootIdentity && references.isSchemaResource(sourceOrigin) && sourceOrigin !== defaultOrigin
+            ? `${defaultOrigin}${pointer}`
+            : pointer;
+    };
     // Create the cache to store the compressed values to their map values
     if (documentRoot[config.externalDocumentsMappingsKey] === undefined) {
         documentRoot[config.externalDocumentsMappingsKey] = {};
     }
     const { generate } = uniqueValueGeneratorFactory(config.compress ?? getHash, documentRoot[config.externalDocumentsMappingsKey]);
+    // Index supplied and previously bundled documents before resolving canonical identities.
+    const storedDocuments = documentRoot[config.externalDocumentsKey];
+    if (isObject(storedDocuments)) {
+        for (const [key, document] of Object.entries(storedDocuments)) {
+            const retrievalUri = resolveReferencePath(defaultOrigin, documentRoot[config.externalDocumentsMappingsKey][key] ?? key);
+            references.register(document, retrievalUri, [config.externalDocumentsKey, key]);
+        }
+    }
+    for (const [uri, pending] of cache) {
+        const result = await pending;
+        if (result.ok) {
+            const retrievalUri = resolveReferencePath(defaultOrigin, uri);
+            const relativeUri = toRelativePath(retrievalUri, defaultOrigin);
+            const key = await generate(relativeUri);
+            references.register(result.data, retrievalUri, [config.externalDocumentsKey, key]);
+        }
+    }
     /**
      * Executes lifecycle hooks defined both in the bundler configuration and any extended lifecycle plugins.
      * This utility function ensures that all relevant hooks for a given event type are called in order:
@@ -367,6 +418,7 @@ export async function bundle(input, config) {
         // A node with its own `$id` establishes a new base for resolving relative references within it.
         // Fall back to the origin inherited from the parent document otherwise.
         const id = getId(root);
+        const nodeOrigin = references.origin(root) ?? (id ? resolveReferencePath(origin, id) : origin);
         const context = {
             path: currentPath,
             referencedFromPath,
@@ -374,7 +426,7 @@ export async function bundle(input, config) {
             parentNode: parent,
             rootNode: documentRoot,
             loaders: loaderPlugins,
-            origin: id ?? origin,
+            origin: nodeOrigin,
         };
         await executeHooks('onBeforeNodeProcess', root, context);
         if (hasRef(root)) {
@@ -387,17 +439,48 @@ export async function bundle(input, config) {
             // In case of partial bundling, we still need to ensure that all dependencies
             // of the local reference are bundled to create a complete and self-contained partial bundle
             // This is important to maintain the integrity of the partial bundle
-            const localRef = convertToLocalRef(ref, id ?? origin, schemas);
+            const local = references.resolve(ref, nodeOrigin);
+            const localRef = local?.path;
             if (localRef !== undefined) {
+                // A fragment under an embedded $id resolves within that schema, not the document.
+                // Without a declared root identity, retain references to root resources rather
+                // than baking a retrieval location into an otherwise portable bundle.
+                const preserveRootResourceReference = !hasRootIdentity &&
+                    local.document === documentRoot &&
+                    references.isSchemaResource(nodeOrigin) &&
+                    nodeOrigin !== defaultOrigin;
+                if (!local.preserveReference && !preserveRootResourceReference) {
+                    root.$ref = referenceToRoot(localRef ? `#/${localRef}` : '#', nodeOrigin);
+                }
                 if (isPartialBundling) {
                     const segments = getSegmentsFromPath(`/${localRef}`);
                     const parent = segments.length > 0 ? getValueByPath(documentRoot, segments.slice(0, -1)).value : undefined;
-                    const targetValue = getValueByPath(documentRoot, segments);
+                    const targetValue = {
+                        value: local.value,
+                        context: isObject(local.value) ? references.origin(local.value) : nodeOrigin,
+                    };
                     // When doing partial bundling, we need to recursively bundle all dependencies
                     // referenced by this local reference to ensure the partial bundle is complete.
                     // This includes not just the direct reference but also all its dependencies,
                     // creating a complete and self-contained partial bundle.
-                    await bundler(targetValue.value, targetValue.context, isChunkParent, depth + 1, segments, parent, referencedFromPath);
+                    //
+                    // The pointer addresses the root document, so the target's base is the nearest `$id` on
+                    // the way to it, else the document origin. `getValueByPath` reports no `$id` as an empty
+                    // string, and handing that on as the origin left a relative reference under the target
+                    // (a chunk reference written relative to the document) with nothing to resolve against.
+                    await bundler(targetValue.value, targetValue.context || defaultOrigin, isChunkParent, depth + 1, segments, parent, referencedFromPath);
+                }
+                if (local.documentPath.length > 0) {
+                    const origin = isObject(local.document) || Array.isArray(local.document) ? references.origin(local.document) : nodeOrigin;
+                    await bundler(local.document, origin, isChunkParent, depth + 1, local.documentPath);
+                    if (config.treeShake) {
+                        const [key, documentKey] = local.documentPath;
+                        resolveAndCopyReferences(documentRoot, { [key]: { [documentKey]: local.document } }, `/${localRef}`, key, documentKey, false, new Set(), references.identity(local.document)?.metadata);
+                    }
+                    else {
+                        const metadata = references.identity(local.document)?.metadata;
+                        setValueAtPath(documentRoot, `/${local.documentPath.map(escapeJsonPointer).join('/')}`, isObject(local.document) && metadata ? { ...local.document, ...metadata } : local.document);
+                    }
                 }
                 await executeHooks('onAfterNodeProcess', root, context);
                 return;
@@ -405,7 +488,7 @@ export async function bundle(input, config) {
             const [prefix, path = ''] = ref.split('#', 2);
             // Combine the current origin with the new path to resolve relative references
             // correctly within the context of the external file being processed
-            const resolvedPath = resolveReferencePath(id ?? origin, prefix);
+            const resolvedPath = resolveReferencePath(nodeOrigin, prefix);
             const relativePath = toRelativePath(resolvedPath, defaultOrigin);
             // Generate a unique compressed path for the external document
             // This is used as a key to store and reference the bundled external document
@@ -422,19 +505,10 @@ export async function bundle(input, config) {
                 // Process the result only once to avoid duplicate processing and prevent multiple prefixing
                 // of internal references, which would corrupt the reference paths
                 if (!seen) {
-                    // Skip prefixing for chunks since they are meant to be self-contained and their
-                    // internal references should remain relative to their original location. Chunks
-                    // are typically used for modular components that need to maintain their own
-                    // reference context without being affected by the main document's structure.
+                    // Index the whole external document before following references within it.
+                    // Chunks retain the referring context because they are already self-contained.
                     if (!isChunk) {
-                        // Update internal references in the resolved document to use the correct base path.
-                        // When we embed external documents, their internal references need to be updated to
-                        // maintain the correct path context relative to the main document. This is crucial
-                        // because internal references in the external document are relative to its original
-                        // location, but when embedded, they need to be relative to their new location in
-                        // the main document's x-ext section. Without this update, internal references
-                        // would point to incorrect locations and break the document structure.
-                        prefixInternalRefRecursive(result.data, [extensions.externalDocuments, compressedPath]);
+                        references.register(result.data, resolvedPath, [config.externalDocumentsKey, compressedPath]);
                     }
                     // Recursively process the resolved content
                     // to handle any nested references it may contain. We pass the resolvedPath as the new origin
@@ -451,7 +525,7 @@ export async function bundle(input, config) {
                     // Store only the subtree that is actually used
                     // This optimizes the bundle size by only including the parts of the external document
                     // that are referenced, rather than the entire document
-                    resolveAndCopyReferences(documentRoot, { [config.externalDocumentsKey]: { [compressedPath]: result.data } }, prefixInternalRef(`#${path}`, [config.externalDocumentsKey, compressedPath]).substring(1), config.externalDocumentsKey, compressedPath);
+                    resolveAndCopyReferences(documentRoot, { [config.externalDocumentsKey]: { [compressedPath]: result.data } }, prefixInternalRef(`#${path}`, [config.externalDocumentsKey, compressedPath]).substring(1), config.externalDocumentsKey, compressedPath, false, new Set(), references.identity(result.data)?.metadata);
                 }
                 else if (!seen) {
                     // Store the external document in the main document's x-ext key
@@ -459,12 +533,13 @@ export async function bundle(input, config) {
                     // This preserves all content and is faster since we don't need to analyze and copy
                     // specific parts. This approach is ideal when storing the result in memory
                     // as it avoids the overhead of tree shaking operations
-                    setValueAtPath(documentRoot, `/${config.externalDocumentsKey}/${compressedPath}`, result.data);
+                    const metadata = references.identity(result.data)?.metadata;
+                    setValueAtPath(documentRoot, `/${config.externalDocumentsKey}/${compressedPath}`, isObject(result.data) && metadata ? { ...result.data, ...metadata } : result.data);
                 }
                 // Update the $ref to point to the embedded document in x-ext
                 // This is necessary because we need to maintain the correct path context
                 // for the embedded document while preserving its internal structure
-                root.$ref = prefixInternalRef(`#${path}`, [config.externalDocumentsKey, compressedPath]);
+                root.$ref = referenceToRoot(prefixInternalRef(`#${path}`, [config.externalDocumentsKey, compressedPath]), nodeOrigin);
                 await executeHooks('onResolveSuccess', root);
                 await executeHooks('onAfterNodeProcess', root, context);
                 return;
@@ -480,7 +555,7 @@ export async function bundle(input, config) {
             if (key === config.externalDocumentsKey || key === config.externalDocumentsMappingsKey) {
                 continue;
             }
-            await bundler(root[key], id ?? origin, isChunkParent, depth + 1, [...currentPath, key], root, referencedFromPath);
+            await bundler(root[key], nodeOrigin, isChunkParent, depth + 1, [...currentPath, key], root, referencedFromPath);
         }
         await executeHooks('onAfterNodeProcess', root, context);
     };

package/dist/bundle/document-references.d.ts

@@ -0,0 +1,30 @@
+/** Format-specific document identity, supplied by the caller. */
+export type DocumentIdentity = {
+    /** Declared base URI, resolved relative to the retrieval URI when necessary. */
+    baseUri: string;
+    /** Root properties retained on copies embedded in the bundle; never applied to the source document. */
+    metadata?: Record<string, unknown>;
+};
+/** Reads document identity without imposing a document format on the bundler. */
+export type DocumentResolver = (document: unknown, retrievalUri: string) => DocumentIdentity | undefined;
+/** Resolution metadata survives moving documents into the bundle. */
+type DocumentReferences = {
+    identity: (document: unknown) => DocumentIdentity | undefined;
+    register: (document: unknown, retrievalUri: string, path?: string[]) => void;
+    isSchemaResource: (uri: string) => boolean;
+    origin: (node: object) => string | undefined;
+    resolve: (ref: string, base: string) => {
+        path: string;
+        value: unknown;
+        preserveReference: boolean;
+        document: unknown;
+        documentPath: string[];
+    } | undefined;
+};
+/**
+ * Indexes complete documents before following their references. A declared identity
+ * can point to content already in memory even when that URI cannot be fetched.
+ */
+export declare const documentReferences: (externalDocumentsKey: string, resolveDocument?: DocumentResolver) => DocumentReferences;
+export {};
+//# sourceMappingURL=document-references.d.ts.map

package/dist/bundle/document-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-references.d.ts","sourceRoot":"","sources":["../../src/bundle/document-references.ts"],"names":[],"mappings":"AAQA,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAA;IACf,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAA;AAaxG,qEAAqE;AACrE,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,gBAAgB,GAAG,SAAS,CAAA;IAC7D,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IAC5E,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC1C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IAC5C,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KAEV;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,GACvG,SAAS,CAAA;CACd,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,sBAAsB,MAAM,EAC5B,kBAAkB,gBAAgB,KACjC,kBAoGF,CAAA"}

package/dist/bundle/document-references.js

@@ -0,0 +1,104 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { escapeJsonPointer } from '../helpers/escape-json-pointer.js';
+import { getId } from '../helpers/get-schemas.js';
+import { getSegmentsFromPath } from '../helpers/get-segments-from-path.js';
+import { getValueByPath } from '../helpers/get-value-by-path.js';
+import { resolveReferencePath } from '../helpers/resolve-reference-path.js';
+/**
+ * Indexes complete documents before following their references. A declared identity
+ * can point to content already in memory even when that URI cannot be fetched.
+ */
+export const documentReferences = (externalDocumentsKey, resolveDocument) => {
+    const identities = new Map();
+    const resources = new Map();
+    const origins = new WeakMap();
+    const bundledResources = new Map();
+    const register = (document, retrievalUri, path = []) => {
+        const identity = resolveDocument?.(document, retrievalUri);
+        const base = identity === undefined ? retrievalUri : resolveReferencePath(retrievalUri, identity.baseUri);
+        if (identity !== undefined) {
+            identities.set(document, { ...identity, baseUri: base });
+        }
+        const resource = { value: document, path, schema: false, embedded: path.length > 0, document, documentPath: path };
+        // Retrieval aliases retain compatibility with callers that supply local copies.
+        resources.set(retrievalUri, resource);
+        resources.set(base, resource);
+        if (path.length > 1) {
+            bundledResources.set(path[1], resource);
+        }
+        // Shared nodes use the first traversal path and base, including for $id and $anchor
+        // registration. This also prevents cycles from being indexed repeatedly.
+        const visited = new WeakSet();
+        const visit = (value, origin, location, inheritedIdentifier = '') => {
+            if (value === null || typeof value !== 'object' || visited.has(value)) {
+                return;
+            }
+            visited.add(value);
+            const id = getId(value);
+            const identifier = id ?? inheritedIdentifier;
+            const current = id === undefined ? origin : resolveReferencePath(origin, id);
+            origins.set(value, current);
+            const anchor = isObject(value) && typeof value.$anchor === 'string' ? value.$anchor : undefined;
+            if (id !== undefined || anchor !== undefined) {
+                const schemaResource = {
+                    value,
+                    path: location,
+                    schema: true,
+                    identifier,
+                    embedded: path.length > 0,
+                    document,
+                    documentPath: path,
+                };
+                if (id !== undefined) {
+                    resources.set(current, schemaResource);
+                }
+                if (anchor !== undefined) {
+                    resources.set(`${current}#${anchor}`, schemaResource);
+                }
+            }
+            for (const [key, child] of Object.entries(value)) {
+                if (key !== externalDocumentsKey) {
+                    visit(child, current, [...location, key], identifier);
+                }
+            }
+        };
+        visit(document, base, path);
+    };
+    return {
+        identity: (document) => identities.get(document),
+        register,
+        isSchemaResource: (uri) => resources.get(uri)?.schema === true,
+        origin: (node) => origins.get(node),
+        resolve: (ref, base) => {
+            const [prefix, fragment = ''] = ref.split('#', 2);
+            const uri = prefix ? resolveReferencePath(base, prefix) : base;
+            const pointer = fragment.startsWith('/') ? getSegmentsFromPath(fragment) : [];
+            const bundled = (!prefix || resources.get(uri)?.path.length === 0) && pointer[0] === externalDocumentsKey
+                ? bundledResources.get(pointer[1])
+                : undefined;
+            const resource = bundled ?? resources.get(fragment && !fragment.startsWith('/') ? `${uri}#${fragment}` : uri);
+            if (!resource) {
+                return undefined;
+            }
+            const segments = bundled ? pointer.slice(2) : pointer;
+            const location = [...resource.path, ...segments];
+            const value = getValueByPath(resource.value, segments).value;
+            // Missing targets must stay unresolved instead of becoming pointers to absent values.
+            const isUnresolved = value === undefined;
+            // Fragment-only schema references are relative to their own resource, even when embedded.
+            const isLocalSchemaReference = resource.schema && !prefix;
+            // References matching an authored root schema identifier remain usable by downstream consumers.
+            // Preserve relative identifiers too: rewriting them changes schema names shown by renderers.
+            const isDeclaredRootSchemaReference = !resource.embedded && resource.schema && Boolean(prefix) && prefix === resource.identifier;
+            // Fragment-only document references already address the root without relocation.
+            const isLocalRootDocumentReference = !resource.embedded && !resource.schema && !prefix;
+            return {
+                path: location.map(escapeJsonPointer).join('/'),
+                value,
+                document: resource.document,
+                documentPath: resource.documentPath,
+                preserveReference: isUnresolved || isLocalSchemaReference || isDeclaredRootSchemaReference || isLocalRootDocumentReference,
+            };
+        },
+    };
+};

package/dist/bundle/index.d.ts

@@ -1,4 +1,5 @@
 export { resolveReferencePath } from '../helpers/resolve-reference-path.js';
 export type { LifecyclePlugin, LoaderPlugin, Plugin, ResolveResult } from './bundle.js';
 export { bundle, extensions, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, resolveAndCopyReferences, } from './bundle.js';
+export type { DocumentIdentity, DocumentResolver } from './document-references.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/bundle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAEvE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EACL,MAAM,EACN,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAEvE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EACL,MAAM,EACN,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/helpers/convert-to-local-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert-to-local-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/convert-to-local-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAC5B,KAAK,MAAM,EACX,gBAAgB,MAAM,EACtB,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3B,MAAM,GAAG,SA8BX,CAAA"}
+{"version":3,"file":"convert-to-local-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/convert-to-local-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAC5B,KAAK,MAAM,EACX,gBAAgB,MAAM,EACtB,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3B,MAAM,GAAG,SA+BX,CAAA"}

package/dist/helpers/convert-to-local-ref.js

@@ -18,7 +18,8 @@ export const convertToLocalRef = (ref, currentContext, schemas) => {
         }
         // If the pathOrAnchor is a JSON pointer, we need to append it to the baseUrl
         if (pathOrAnchor.startsWith('/')) {
-            return `${schemas.get(baseUrl)}${pathOrAnchor}`;
+            const rootPath = schemas.get(baseUrl);
+            return rootPath ? `${rootPath}${pathOrAnchor}` : pathOrAnchor.slice(1);
         }
         // If the pathOrAnchor is an anchor, we need to return the anchor
         return schemas.get(`${baseUrl}#${pathOrAnchor}`);

package/dist/helpers/resolve-reference-path.d.ts

@@ -1,6 +1,9 @@
 /**
  * Resolves a reference path by combining a base path with a relative path.
- * Handles both remote URLs and local file paths.
+ * Scheme-bearing references keep their identity, including non-fetchable URNs.
+ * Hierarchical URI bases use URL resolution (query, fragment, and directory semantics);
+ * an opaque base such as a URN cannot resolve a relative path and throws.
+ * Scheme-less inputs retain filesystem resolution, including Windows drive paths.
  *
  * @param base - The base path (can be a URL or local file path)
  * @param relativePath - The relative path to resolve against the base

package/dist/helpers/resolve-reference-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-reference-path.d.ts","sourceRoot":"","sources":["../../src/helpers/resolve-reference-path.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,cAAc,MAAM,WAYtE,CAAA"}
+{"version":3,"file":"resolve-reference-path.d.ts","sourceRoot":"","sources":["../../src/helpers/resolve-reference-path.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,cAAc,MAAM,KAAG,MAgBzE,CAAA"}

package/dist/helpers/resolve-reference-path.js

@@ -1,8 +1,11 @@
 import path from 'pathe';
-import { isHttpUrl } from '../helpers/is-http-url.js';
+const hasScheme = (value) => /^[a-z][a-z0-9+.-]*:/i.test(value) && !/^[a-z]:[\\/]/i.test(value);
 /**
  * Resolves a reference path by combining a base path with a relative path.
- * Handles both remote URLs and local file paths.
+ * Scheme-bearing references keep their identity, including non-fetchable URNs.
+ * Hierarchical URI bases use URL resolution (query, fragment, and directory semantics);
+ * an opaque base such as a URN cannot resolve a relative path and throws.
+ * Scheme-less inputs retain filesystem resolution, including Windows drive paths.
  *
  * @param base - The base path (can be a URL or local file path)
  * @param relativePath - The relative path to resolve against the base
@@ -17,13 +20,16 @@ import { isHttpUrl } from '../helpers/is-http-url.js';
  * // Returns: '/path/to/user.json'
  */
 export const resolveReferencePath = (base, relativePath) => {
-    if (isHttpUrl(relativePath)) {
+    if (hasScheme(relativePath)) {
         return relativePath;
     }
-    if (isHttpUrl(base)) {
-        const baseUrl = new URL(base);
-        baseUrl.pathname = path.posix.resolve('/', path.dirname(baseUrl.pathname), relativePath);
-        return baseUrl.toString();
+    if (hasScheme(base)) {
+        return new URL(relativePath, base).href;
     }
-    return path.resolve(path.dirname(base), relativePath);
+    if (!relativePath) {
+        return base;
+    }
+    const directory = /[\\/]$/.test(base) ? base : path.dirname(base);
+    const resolved = path.resolve(directory, relativePath);
+    return /[\\/]$/.test(relativePath) && !resolved.endsWith('/') ? `${resolved}/` : resolved;
 };

package/dist/helpers/to-relative-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-relative-path.d.ts","sourceRoot":"","sources":["../../src/helpers/to-relative-path.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,WAmCzD,CAAA"}
+{"version":3,"file":"to-relative-path.d.ts","sourceRoot":"","sources":["../../src/helpers/to-relative-path.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,MA6C5D,CAAA"}

package/dist/helpers/to-relative-path.js

@@ -9,6 +9,12 @@ import { isHttpUrl } from '../helpers/is-http-url.js';
  * - Otherwise, computes the relative path between two local paths.
  */
 export const toRelativePath = (input, base) => {
+    // This format-agnostic helper has no document-identity registry. Preserve every
+    // non-HTTP URI, not only known $self values: file:, urn:, and custom schemes must
+    // not become filesystem paths. Loader plugins decide whether a URI is fetchable.
+    if (URL.canParse(input) && !isHttpUrl(input) && !/^[a-z]:[\\/]/i.test(input)) {
+        return input;
+    }
     // Both input and base are remote URLs
     if (isHttpUrl(input) && isHttpUrl(base)) {
         const inputUrl = new URL(input);
@@ -18,10 +24,14 @@ export const toRelativePath = (input, base) => {
             return input;
         }
         // Get the directory of the base URL pathname (not the file itself)
-        const baseDir = path.dirname(path.posix.resolve('/', baseUrl.pathname));
+        const baseDir = baseUrl.pathname.endsWith('/') ? baseUrl.pathname : path.dirname(baseUrl.pathname);
         const inputPath = path.posix.resolve('/', inputUrl.pathname);
         // Return the relative path from baseDir to inputPath
-        return path.posix.relative(baseDir, inputPath);
+        const relativePath = path.posix.relative(baseDir, inputPath);
+        const suffix = relativePath && inputUrl.pathname.endsWith('/') ? '/' : '';
+        const relativeUri = `${relativePath}${suffix}${inputUrl.search}${inputUrl.hash}`;
+        // Keep the absolute URI when path normalization would change its identity.
+        return new URL(relativeUri, base).href === inputUrl.href ? relativeUri : input;
     }
     // Base is a remote URL, input is a local path
     if (isHttpUrl(base)) {
@@ -36,7 +46,7 @@ export const toRelativePath = (input, base) => {
         return input;
     }
     // Both input and base are local paths; return the relative path
-    const baseDir = path.dirname(path.resolve(base));
+    const baseDir = base.endsWith('/') ? path.resolve(base) : path.dirname(path.resolve(base));
     const inputPath = path.resolve(input);
     return path.relative(baseDir, inputPath);
 };

package/dist/join/index.d.ts

@@ -0,0 +1,3 @@
+export type { JoinConflict, JoinContext, JoinOptions, JoinResult, JoinStrategy } from './join.js';
+export { join } from './join.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/join/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/join/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAC9F,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA"}

package/dist/join/index.js

@@ -0,0 +1 @@
+export { join } from './join.js';

package/dist/join/join.d.ts

@@ -0,0 +1,36 @@
+import type { UnknownObject } from '../types.js';
+/** Controls how a value is combined with the value from earlier inputs. */
+export type JoinStrategy = 'merge' | 'merge-by-index' | 'replace' | 'conflict' | 'skip' | {
+    uniqueBy: string;
+};
+/** Context for choosing a strategy. Paths are segments, so keys containing slashes stay intact. */
+export type JoinContext = {
+    path: readonly string[];
+    current: unknown;
+    incoming: unknown;
+};
+/** Customize merging without coupling it to a document format. */
+export type JoinOptions = {
+    strategy?: (context: JoinContext) => JoinStrategy;
+};
+/** A duplicate value at a location marked as a conflict by the caller. */
+export type JoinConflict = {
+    path: string[];
+};
+/** Conflicts prevent returning a partially joined document. */
+export type JoinResult = {
+    ok: true;
+    document: UnknownObject;
+} | {
+    ok: false;
+    conflicts: JoinConflict[];
+};
+/**
+ * Join JSON objects without interpreting any document standard or resolving references.
+ * Objects merge recursively; arrays and other values are replaced by later inputs.
+ * A strategy can instead replace an entire object, reject duplicate keys (even equal
+ * values), or combine arrays by a property, retaining the first occurrence.
+ * Inputs must be acyclic JSON objects and are never mutated or shared with the result.
+ */
+export declare const join: (inputs: readonly UnknownObject[], options?: JoinOptions) => JoinResult;
+//# sourceMappingURL=join.d.ts.map

package/dist/join/join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/join/join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9G,mGAAmG;AACnG,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,CAAA;CAClD,CAAA;AAED,0EAA0E;AAC1E,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAE7C,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,YAAY,EAAE,CAAA;CAAE,CAAA;AAazG;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,QAAQ,SAAS,aAAa,EAAE,EAAE,UAAS,WAAgB,KAAG,UAmElF,CAAA"}

package/dist/join/join.js

@@ -0,0 +1,76 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+/** Copy literal JSON keys as own data properties, without invoking prototype setters. */
+const copy = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(copy);
+    }
+    if (isObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, copy(child)]));
+    }
+    return value;
+};
+/**
+ * Join JSON objects without interpreting any document standard or resolving references.
+ * Objects merge recursively; arrays and other values are replaced by later inputs.
+ * A strategy can instead replace an entire object, reject duplicate keys (even equal
+ * values), or combine arrays by a property, retaining the first occurrence.
+ * Inputs must be acyclic JSON objects and are never mutated or shared with the result.
+ */
+export const join = (inputs, options = {}) => {
+    const conflicts = [];
+    const skipped = Symbol('skipped');
+    const mergeFields = (target, source, path) => {
+        for (const [key, value] of Object.entries(source)) {
+            const hasKey = Object.hasOwn(target, key);
+            const merged = combine(hasKey ? Reflect.get(target, key) : undefined, value, [...path, key], hasKey);
+            if (merged !== skipped) {
+                // Defining an own property preserves literal __proto__ keys without changing the prototype.
+                Object.defineProperty(target, key, { value: merged, enumerable: true, configurable: true, writable: true });
+            }
+        }
+    };
+    const combine = (current, incoming, path, exists) => {
+        const strategy = options.strategy?.({ path, current, incoming }) ?? 'merge';
+        if (strategy === 'skip') {
+            return skipped;
+        }
+        if (strategy === 'conflict' && exists) {
+            conflicts.push({ path });
+            return current;
+        }
+        if (typeof strategy === 'object' && Array.isArray(incoming)) {
+            const seen = new Set();
+            return [...(Array.isArray(current) ? current : []), ...incoming]
+                .filter((item) => {
+                const key = isObject(item) && Object.hasOwn(item, strategy.uniqueBy) ? item[strategy.uniqueBy] : undefined;
+                // Items without the identity property remain distinct.
+                if (key === undefined) {
+                    return true;
+                }
+                if (seen.has(key)) {
+                    return false;
+                }
+                seen.add(key);
+                return true;
+            })
+                .map(copy);
+        }
+        if (strategy === 'merge-by-index' && Array.isArray(incoming)) {
+            const result = Array.isArray(current) ? current : [];
+            mergeFields(result, incoming, path);
+            return result;
+        }
+        if ((strategy === 'merge' || strategy === 'merge-by-index') && isObject(incoming)) {
+            const result = isObject(current) ? current : {};
+            mergeFields(result, incoming, path);
+            return result;
+        }
+        return copy(incoming);
+    };
+    // The root always merges; strategies apply to fields within each document.
+    const document = {};
+    for (const input of inputs) {
+        mergeFields(document, input, []);
+    }
+    return conflicts.length ? { ok: false, conflicts } : { ok: true, document };
+};

package/dist/magic-proxy/proxy.d.ts

@@ -39,6 +39,8 @@ import type { UnknownObject } from '../types.js';
  */
 export declare const createMagicProxy: <T extends Record<keyof T & symbol, unknown>, S extends UnknownObject>(target: T, options?: Partial<{
     showInternal: boolean;
+    /** Canonical URI identifying the root document for qualified references. */
+    documentUri: string;
 }>, args?: {
     /**
      * The root object for resolving local JSON references.

package/dist/magic-proxy/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/magic-proxy/proxy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAQ5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,aAAa,EACnG,QAAQ,CAAC,EACT,UAAU,OAAO,CAAC;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC,EAC5C,OAAM;IACJ;;OAEG;IACH,IAAI,EAAE,CAAC,GAAG,CAAC,CAAA;IACX;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAC9B;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3B;;OAEG;IACH,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;CAOvB,KACA,CAkNF,CAAA;AAMD;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAUnC"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/magic-proxy/proxy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAQ5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,aAAa,EACnG,QAAQ,CAAC,EACT,UAAU,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAA;IACrB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAA;CACpB,CAAC,EACF,OAAM;IACJ;;OAEG;IACH,IAAI,EAAE,CAAC,GAAG,CAAC,CAAA;IACX;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAC9B;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3B;;OAEG;IACH,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;CAOvB,KACA,CAkNF,CAAA;AAMD;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAUnC"}

package/dist/magic-proxy/proxy.js

@@ -50,7 +50,7 @@ export const createMagicProxy = (target, options, args = {
     root: target,
     proxyCache: new WeakMap(),
     cache: new Map(),
-    schemas: getSchemas(target),
+    schemas: getSchemas(target, '', [], new Map(options?.documentUri ? [[options.documentUri, '']] : [])),
     currentContext: '',
 }) => {
     if (!isObject(target) && !Array.isArray(target)) {

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.13.5",
+  "version": "0.15.0",
   "engines": {
     "node": ">=22"
   },
@@ -51,6 +51,16 @@
       "types": "./dist/helpers/escape-json-pointer.d.ts",
       "default": "./dist/helpers/escape-json-pointer.js"
     },
+    "./helpers/convert-to-local-ref": {
+      "import": "./dist/helpers/convert-to-local-ref.js",
+      "types": "./dist/helpers/convert-to-local-ref.d.ts",
+      "default": "./dist/helpers/convert-to-local-ref.js"
+    },
+    "./helpers/get-schemas": {
+      "import": "./dist/helpers/get-schemas.js",
+      "types": "./dist/helpers/get-schemas.d.ts",
+      "default": "./dist/helpers/get-schemas.js"
+    },
     "./helpers/get-segments-from-path": {
       "import": "./dist/helpers/get-segments-from-path.js",
       "types": "./dist/helpers/get-segments-from-path.d.ts",
@@ -96,6 +106,11 @@
       "types": "./dist/helpers/unescape-json-pointer.d.ts",
       "default": "./dist/helpers/unescape-json-pointer.js"
     },
+    "./join": {
+      "import": "./dist/join/index.js",
+      "types": "./dist/join/index.d.ts",
+      "default": "./dist/join/index.js"
+    },
     "./magic-proxy": {
       "import": "./dist/magic-proxy/index.js",
       "types": "./dist/magic-proxy/index.d.ts",
@@ -107,10 +122,10 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@scalar/helpers": "0.13.0",
     "pathe": "^2.0.3",
     "undici": "7.24.4",
-    "yaml": "^2.9.0",
-    "@scalar/helpers": "0.12.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "fastify": "^5.11.2",