@scalar/workspace-store 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/workspace-store
 
+## 0.63.0
+
+### Minor Changes
+
+- [#10261](https://github.com/scalar/scalar/pull/10261): Add `getDocumentRevision(document)`, a counter the store bumps on every write to a document. A consumer caching a derivation of a schema node can validate the entry against it in constant time, instead of walking the subtree to see whether anything moved. It reads the same from any view of the document, including one with the reactive and detect-changes proxies stripped for reads, and returns 0 for a document no store tracks.
+- [#10261](https://github.com/scalar/scalar/pull/10261): Type the result of `resolve.schema` as read-only. A resolved schema is the document's own node or a shallow merge over it, so writing to it writes into the document behind the store's back; every change belongs in a store mutation, and a caller that needs a modified shape copies what it needs first. No in-repo consumer had to change.
+
+### Patch Changes
+
+- [#10261](https://github.com/scalar/scalar/pull/10261): Make rendering from the store cheaper: the detect-changes proxy no longer allocates a path on every property read, `getResolvedRefDeep` stops deep-unpacking every node it visits, `resolve.schema` builds its composed typebox schema once, and `getExampleFromSchema` builds its options cache key once per call instead of once per node.
+- [#10261](https://github.com/scalar/scalar/pull/10261): Follow chains of references when resolving. A reference can point at a second reference — `resolve()` on a static or SSR workspace leaves the component behind as a `{ $ref: '#/x-ext/<hash>', $global: true }` stub with the content under `x-ext` — so `getResolvedRef` and `getResolvedRefDeep` now hop through references that carry nothing but a `$ref` until they reach the node itself, instead of handing back the stub. A reference that carries keywords of its own stays its own hop, since it is a schema in its own right.
+
 ## 0.62.0
 
 ### Minor Changes

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -18,6 +18,7 @@ import { createAuthStore } from './entities/auth/index.js';
 import { createHistoryStore } from './entities/history/index.js';
 import { deepClone } from './helpers/deep-clone.js';
 import { createDetectChangesProxy } from './helpers/detect-changes-proxy.js';
+import { bumpDocumentRevision } from './helpers/document-revision.js';
 import { safeAssign } from './helpers/general.js';
 import { getFetch } from './helpers/get-fetch.js';
 import { mergeObjects } from './helpers/merge-object.js';
@@ -219,6 +220,9 @@ export const createWorkspaceStore = (workspaceProps) => {
                         info: { title: '', version: '' },
                         'x-scalar-original-document-hash': '',
                     };
+                    // Every write through the store passes here, which is what makes the revision a
+                    // complete record of the document changing.
+                    bumpDocumentRevision(document);
                     const event = {
                         type: 'documents',
                         documentName,
@@ -244,6 +248,7 @@ export const createWorkspaceStore = (workspaceProps) => {
                         info: { title: '', version: '' },
                         'x-scalar-original-document-hash': '',
                     };
+                    bumpDocumentRevision(document);
                     // Active document changed
                     const event = {
                         type: 'documents',

package/dist/helpers/detect-changes-proxy.d.ts

@@ -1,5 +1,11 @@
 type OnBeforeChangeHook = (path: string[], value?: unknown) => void;
 type OnAfterChangeHook = (path: string[], value?: unknown) => void;
+type Options = {
+    hooks: Partial<{
+        onBeforeChange: OnBeforeChangeHook;
+        onAfterChange: OnAfterChangeHook;
+    }>;
+};
 /**
  * createDetectChangesProxy - Creates a proxy for an object or array that detects and triggers hooks on changes.
  *
@@ -23,12 +29,7 @@ type OnAfterChangeHook = (path: string[], value?: unknown) => void;
  * @param args Internal: proxy cache and current property path (used for recursion)
  * @returns The proxied object/array with change detection capabilities
  */
-export declare const createDetectChangesProxy: <T>(target: T, options?: {
-    hooks: Partial<{
-        onBeforeChange: OnBeforeChangeHook;
-        onAfterChange: OnAfterChangeHook;
-    }>;
-}, args?: {
+export declare const createDetectChangesProxy: <T>(target: T, options?: Options, args?: {
     /** Cache for storing proxies */
     proxyCache: WeakMap<object, unknown>;
     /** Path for the target */

package/dist/helpers/detect-changes-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect-changes-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/detect-changes-proxy.ts"],"names":[],"mappings":"AAKA,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AACnE,KAAK,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EACxC,QAAQ,CAAC,EACT,UAAU;IACR,KAAK,EAAE,OAAO,CAAC;QACb,cAAc,EAAE,kBAAkB,CAAA;QAClC,aAAa,EAAE,iBAAiB,CAAA;KACjC,CAAC,CAAA;CACH,EACD,OAAM;IACJ,gCAAgC;IAChC,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAA;CAIf,KACA,CAoDF,CAAA;AAED,eAAO,MAAM,0BAA0B,GAAI,KAAK,OAAO,KAAG,OAMzD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAE,KAAK,CAAC,KAAG,CAWpD,CAAA"}
+{"version":3,"file":"detect-changes-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/detect-changes-proxy.ts"],"names":[],"mappings":"AAKA,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AACnE,KAAK,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AAElE,KAAK,OAAO,GAAG;IACb,KAAK,EAAE,OAAO,CAAC;QACb,cAAc,EAAE,kBAAkB,CAAA;QAClC,aAAa,EAAE,iBAAiB,CAAA;KACjC,CAAC,CAAA;CACH,CAAA;AA+HD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EACxC,QAAQ,CAAC,EACT,UAAU,OAAO,EACjB,OAAM;IACJ,gCAAgC;IAChC,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAA;CAIf,KACA,CAAyE,CAAA;AAE5E,eAAO,MAAM,0BAA0B,GAAI,KAAK,OAAO,KAAG,OAMzD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAE,KAAK,CAAC,KAAG,CAWpD,CAAA"}

package/dist/helpers/detect-changes-proxy.js

@@ -1,40 +1,36 @@
 import { isObject } from '@scalar/helpers/object/is-object';
 const isDetectChangesProxy = Symbol('isDetectChangesProxy');
 const detectChangesProxyTarget = Symbol('detectChangesProxyTarget');
-/**
- * createDetectChangesProxy - Creates a proxy for an object or array that detects and triggers hooks on changes.
- *
- * This proxy enables detection of set operations, triggering optional hooks (onBeforeChange, onAfterChange) with the path and value changed.
- * The proxy can be applied recursively to all nested objects/arrays, and caches proxies to prevent creating multiple proxies for the same object.
- *
- * Example usage:
- *
- * const obj = { foo: 1, bar: { baz: 2 } };
- * const proxy = createDetectChangesProxy(obj, {
- *   hooks: {
- *     onBeforeChange: (path, value) => console.log('Before', path, value),
- *     onAfterChange: (path, value) => console.log('After', path, value),
- *   }
- * });
- * proxy.foo = 42; // Console: Before ['foo'] '42', After ['foo'] '42'
- * proxy.bar.baz = 99; // Console: Before ['bar', 'baz'] '99', After ['bar', 'baz'] '99'
- *
- * @param target The target object or array to wrap in a proxy
- * @param options Optional: hooks for change detection
- * @param args Internal: proxy cache and current property path (used for recursion)
- * @returns The proxied object/array with change detection capabilities
- */
-export const createDetectChangesProxy = (target, options, args = {
-    proxyCache: new WeakMap(),
-    path: [],
-}) => {
+/** Build the `string[]` a hook expects, from the chain of links above the property being written. */
+const materializePath = (parent, prop) => {
+    let depth = 1;
+    for (let link = parent; link !== undefined; link = link.parent) {
+        depth++;
+    }
+    const path = new Array(depth);
+    path[--depth] = prop;
+    for (let link = parent; link !== undefined; link = link.parent) {
+        path[--depth] = link.key;
+    }
+    return path;
+};
+/** Turn the caller-supplied starting path into the link chain the proxies carry. */
+const toPathLink = (path) => {
+    let link = undefined;
+    for (const key of path) {
+        link = { parent: link, key };
+    }
+    return link;
+};
+const createProxy = (target, options, proxyCache, pathLink) => {
     // Only wrap objects or arrays
     if (!isObject(target) && !Array.isArray(target)) {
         return target;
     }
     // Return cached proxy if already created for this target
-    if (args.proxyCache.has(target)) {
-        return args.proxyCache.get(target);
+    const cached = proxyCache.get(target);
+    if (cached !== undefined) {
+        return cached;
     }
     const proxy = new Proxy(target, {
         get(target, prop, receiver) {
@@ -46,34 +42,83 @@ export const createDetectChangesProxy = (target, options, args = {
             if (prop === detectChangesProxyTarget) {
                 return target;
             }
-            // Recursively wrap property values in the detect changes proxy
             const value = Reflect.get(target, prop, receiver);
+            // Primitives and functions are handed back untouched, which is the common case on a read.
+            if (value === null || typeof value !== 'object') {
+                return value;
+            }
+            // A value wrapped earlier keeps its proxy, so nothing below this point runs for a repeat read.
+            const cachedChild = proxyCache.get(value);
+            if (cachedChild !== undefined) {
+                return cachedChild;
+            }
             if (isDetectChangesProxyObject(value)) {
                 return value;
             }
-            return createDetectChangesProxy(value, options, { ...args, path: [...args.path, String(prop)] });
+            // Recursively wrap property values in the detect changes proxy
+            return createProxy(value, options, proxyCache, { parent: pathLink, key: String(prop) });
         },
         set(target, prop, value, receiver) {
-            const path = [...args.path, String(prop)];
+            const onBeforeChange = options?.hooks?.onBeforeChange;
+            const onAfterChange = options?.hooks?.onAfterChange;
+            // Both hooks receive the same array, because `client.ts` mutates it in `onAfterChange`.
+            const path = onBeforeChange || onAfterChange ? materializePath(pathLink, String(prop)) : undefined;
             // Call before-change hook if provided
-            options?.hooks?.onBeforeChange?.(path, value);
+            if (path) {
+                onBeforeChange?.(path, value);
+            }
             const result = Reflect.set(target, prop, value, receiver);
             // Call after-change hook if provided
-            options?.hooks?.onAfterChange?.(path, value);
+            if (path) {
+                onAfterChange?.(path, value);
+            }
             return result;
         },
         deleteProperty(target, prop) {
-            const path = [...args.path, String(prop)];
-            options?.hooks?.onBeforeChange?.(path);
+            const onBeforeChange = options?.hooks?.onBeforeChange;
+            const onAfterChange = options?.hooks?.onAfterChange;
+            const path = onBeforeChange || onAfterChange ? materializePath(pathLink, String(prop)) : undefined;
+            if (path) {
+                onBeforeChange?.(path);
+            }
             const result = Reflect.deleteProperty(target, prop);
-            options?.hooks?.onAfterChange?.(path);
+            if (path) {
+                onAfterChange?.(path);
+            }
             return result;
         },
     });
     // Cache the proxy for this target
-    args.proxyCache.set(target, proxy);
+    proxyCache.set(target, proxy);
     return proxy;
 };
+/**
+ * createDetectChangesProxy - Creates a proxy for an object or array that detects and triggers hooks on changes.
+ *
+ * This proxy enables detection of set operations, triggering optional hooks (onBeforeChange, onAfterChange) with the path and value changed.
+ * The proxy can be applied recursively to all nested objects/arrays, and caches proxies to prevent creating multiple proxies for the same object.
+ *
+ * Example usage:
+ *
+ * const obj = { foo: 1, bar: { baz: 2 } };
+ * const proxy = createDetectChangesProxy(obj, {
+ *   hooks: {
+ *     onBeforeChange: (path, value) => console.log('Before', path, value),
+ *     onAfterChange: (path, value) => console.log('After', path, value),
+ *   }
+ * });
+ * proxy.foo = 42; // Console: Before ['foo'] '42', After ['foo'] '42'
+ * proxy.bar.baz = 99; // Console: Before ['bar', 'baz'] '99', After ['bar', 'baz'] '99'
+ *
+ * @param target The target object or array to wrap in a proxy
+ * @param options Optional: hooks for change detection
+ * @param args Internal: proxy cache and current property path (used for recursion)
+ * @returns The proxied object/array with change detection capabilities
+ */
+export const createDetectChangesProxy = (target, options, args = {
+    proxyCache: new WeakMap(),
+    path: [],
+}) => createProxy(target, options, args.proxyCache, toPathLink(args.path));
 export const isDetectChangesProxyObject = (obj) => {
     return (typeof obj === 'object' &&
         obj !== null &&

package/dist/helpers/document-revision.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Records a write against a document.
+ *
+ * Called from the store's change hooks, which see every mutation made through the store.
+ */
+export declare const bumpDocumentRevision: (document: unknown) => void;
+/**
+ * How many writes the store has recorded against a document, for a consumer caching derivations of its
+ * nodes: the number changes whenever anything in the document does, so a cache entry taken at one
+ * revision is known to be stale at the next, in constant time and without walking the document.
+ *
+ * Returns 0 for a document no store tracks — a plain or magic-proxied document on the server, say —
+ * which is also what an untouched document reads, so a cache validating against it simply never sees a
+ * change. Documents that are mutated outside the store are the caller's problem either way: nothing
+ * observes those writes.
+ *
+ * The number is meaningful only against itself. It counts writes, not versions, and a single edit can
+ * move it by more than one.
+ *
+ * It is a plain number, not a reactive source: reading it inside a Vue `computed` or `effect` tracks
+ * nothing, so that computed will not re-run when the number moves. Use it to validate a cache entry at
+ * the point of use — alongside whatever already makes the surrounding computed re-run — rather than as
+ * the thing a computed depends on.
+ */
+export declare const getDocumentRevision: (document: unknown) => number;
+//# sourceMappingURL=document-revision.d.ts.map

package/dist/helpers/document-revision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-revision.d.ts","sourceRoot":"","sources":["../../src/helpers/document-revision.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,OAAO,KAAG,IAOxD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,KAAG,MAOvD,CAAA"}

package/dist/helpers/document-revision.js

@@ -0,0 +1,47 @@
+import { unpackProxyShallow } from '../helpers/unpack-proxy.js';
+/**
+ * How many writes the store has recorded against each document, keyed by the raw document object.
+ *
+ * Keyed on the raw object rather than on a proxy, because the writer and the reader hold different
+ * views of the same document: the store writes through `reactive(detectChanges(overrides(magic(raw))))`,
+ * while a reader may hold any inner layer — the API reference strips the outer two for schema reads.
+ * `unpackProxyShallow` lands on the same object from any of them.
+ */
+const revisions = new WeakMap();
+/**
+ * Records a write against a document.
+ *
+ * Called from the store's change hooks, which see every mutation made through the store.
+ */
+export const bumpDocumentRevision = (document) => {
+    const raw = unpackProxyShallow(document);
+    if (typeof raw !== 'object' || raw === null) {
+        return;
+    }
+    revisions.set(raw, (revisions.get(raw) ?? 0) + 1);
+};
+/**
+ * How many writes the store has recorded against a document, for a consumer caching derivations of its
+ * nodes: the number changes whenever anything in the document does, so a cache entry taken at one
+ * revision is known to be stale at the next, in constant time and without walking the document.
+ *
+ * Returns 0 for a document no store tracks — a plain or magic-proxied document on the server, say —
+ * which is also what an untouched document reads, so a cache validating against it simply never sees a
+ * change. Documents that are mutated outside the store are the caller's problem either way: nothing
+ * observes those writes.
+ *
+ * The number is meaningful only against itself. It counts writes, not versions, and a single edit can
+ * move it by more than one.
+ *
+ * It is a plain number, not a reactive source: reading it inside a Vue `computed` or `effect` tracks
+ * nothing, so that computed will not re-run when the number moves. Use it to validate a cache entry at
+ * the point of use — alongside whatever already makes the surrounding computed re-run — rather than as
+ * the thing a computed depends on.
+ */
+export const getDocumentRevision = (document) => {
+    const raw = unpackProxyShallow(document);
+    if (typeof raw !== 'object' || raw === null) {
+        return 0;
+    }
+    return revisions.get(raw) ?? 0;
+};

package/dist/helpers/get-resolved-ref-deep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-resolved-ref-deep.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-ref-deep.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,kDAAkD,CAAA;AAMnG,KAAK,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AAC1F,KAAK,SAAS,CAAC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE3C;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,GAC9C,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC5B,eAAe,CAAC,CAAC,CAAC,EAAE,GACpB,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAC5G,CAAC,GACL,WAAW,CAAC,CAAC,CAAC,SAAS,MAAM,GAC3B;KACG,CAAC,IAAI,MAAM,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,GAAG,CAAC,GAC/D,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,GACjD,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACvC,GACD,WAAW,CAAC,CAAC,CAAC,CAAA;AAEpB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,KAAG,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CA6D/F,CAAA"}
+{"version":3,"file":"get-resolved-ref-deep.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-ref-deep.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,kDAAkD,CAAA;AAMnG,KAAK,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AAC1F,KAAK,SAAS,CAAC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE3C;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,GAC9C,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC5B,eAAe,CAAC,CAAC,CAAC,EAAE,GACpB,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAC5G,CAAC,GACL,WAAW,CAAC,CAAC,CAAC,SAAS,MAAM,GAC3B;KACG,CAAC,IAAI,MAAM,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,GAAG,CAAC,GAC/D,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,GACjD,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACvC,GACD,WAAW,CAAC,CAAC,CAAC,CAAA;AAEpB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,KAAG,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAyE/F,CAAA"}

package/dist/helpers/get-resolved-ref-deep.js

@@ -1,6 +1,6 @@
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { unpackProxyObject } from '@scalar/workspace-store/helpers/unpack-proxy';
+import { unpackProxyShallow } from '@scalar/workspace-store/helpers/unpack-proxy';
 /**
  * Recursively resolves all $ref objects in a data structure to their actual values.
  * Traverses through objects, arrays, and nested structures to find and resolve
@@ -17,7 +17,9 @@ export const getResolvedRefDeep = (node) => {
         if (!isObject(current) && !Array.isArray(current)) {
             return current;
         }
-        const rawValue = unpackProxyObject(current, { depth: 1 });
+        // Identity only: the raw object keys the caches below and is never read from or returned, so the
+        // outermost proxies come off and the node's own properties are left alone.
+        const rawValue = unpackProxyShallow(current);
         // We don't have to recurse into the same object again
         // This helps us having to manually remove the tracked node after we recurse into the tree
         if (cachedResults.has(rawValue)) {
@@ -30,31 +32,41 @@ export const getResolvedRefDeep = (node) => {
         // Track visited nodes
         visited.add(rawValue);
         if ('$ref' in current) {
+            // `getResolvedRef` follows a chain of pure pass-through references, so a component that resolve()
+            // left behind as a `$global` stub reaches the node the stub points at rather than the stub.
             const resolved = getResolvedRef(current);
             const result = resolveNode(resolved);
             // Preserve keywords declared alongside the `$ref`. A `$ref` may carry siblings that specialize the
             // target — most notably the `$defs`/`$dynamicAnchor` binding used to express a generic schema like
             // `Paginated<Planet>`. Per OpenAPI 3.1, siblings of a `$ref` override the resolved value, so we merge
             // them on top. Without this the dynamic-ref binding is dropped and `$dynamicRef` cannot resolve.
-            const siblings = Object.entries(current).filter(([key]) => key !== '$ref' && key !== '$ref-value');
-            if (siblings.length > 0 && isObject(result)) {
-                const merged = { ...result };
-                for (const [key, value] of siblings) {
-                    merged[key] = resolveNode(value);
+            let merged = undefined;
+            if (isObject(result)) {
+                for (const key of Object.keys(current)) {
+                    if (key === '$ref' || key === '$ref-value') {
+                        continue;
+                    }
+                    merged ??= { ...result };
+                    merged[key] = resolveNode(current[key]);
                 }
-                cachedResults.set(rawValue, merged);
-                return merged;
             }
-            cachedResults.set(rawValue, result);
-            return result;
+            const value = merged ?? result;
+            cachedResults.set(rawValue, value);
+            return value;
         }
         // For arrays
         if (Array.isArray(current)) {
-            const result = current.map(resolveNode);
+            const result = new Array(current.length);
+            for (let index = 0; index < current.length; index++) {
+                result[index] = resolveNode(current[index]);
+            }
             cachedResults.set(rawValue, result);
             return result;
         }
-        const result = Object.fromEntries(Object.entries(current).map(([key, value]) => [key, resolveNode(value)]));
+        const result = {};
+        for (const key of Object.keys(current)) {
+            result[key] = resolveNode(current[key]);
+        }
         cachedResults.set(rawValue, result);
         return result;
     };

package/dist/helpers/get-resolved-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-resolved-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-ref.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AACjF,MAAM,MAAM,SAAS,CAAC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAOlD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,IAalE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EACzC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EACrB,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,MAAM,GACzC,IAAI,GAAG,MAAM,CAAA;AAChB,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAA;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;AAW7E;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"get-resolved-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-ref.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AACjF,MAAM,MAAM,SAAS,CAAC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AA0ElD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,IAclE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EACzC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EACrB,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,MAAM,GACzC,IAAI,GAAG,MAAM,CAAA;AAChB,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAA;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;AAW7E;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA"}

package/dist/helpers/get-resolved-ref.js

@@ -1,7 +1,64 @@
 import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * Keys the store writes on an externalized stub for its own bookkeeping.
+ *
+ * They describe the stub — whether it is shared across documents, whether its chunk has loaded — not the
+ * node it points at.
+ */
+const STUB_BOOKKEEPING_KEYS = new Set(['$global', '$status']);
+const isReferenceNode = (value) => typeof value === 'object' && value !== null && '$ref' in value;
+/**
+ * Whether a reference is pure indirection: a `$ref` and the store's own bookkeeping, nothing more.
+ *
+ * A reference that carries anything else is a schema in its own right — an `$id` opens a schema
+ * resource, `$defs` and `$dynamicAnchor` bind a generic's type parameter, and `description` annotates
+ * the target — so it stays its own hop and the caller resolves it as it descends, the way it always
+ * has. Collapsing such a node into the one it points at merges two schema resources into one, and the
+ * `$dynamicRef` in the inner one then has no outer scope left to bind against.
+ */
+const isPassThroughReference = (node) => {
+    for (const key of Object.keys(node)) {
+        if (key !== '$ref' && key !== '$ref-value' && !STUB_BOOKKEEPING_KEYS.has(key)) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Follow `$ref-value` onward for as long as it lands on another reference that is pure indirection.
+ *
+ * A reference can point at a second reference. `resolve()` on a static or SSR workspace leaves exactly
+ * that behind: the component stays in the document as a `{ $ref: '#/x-ext/<hash>', $global: true }` stub
+ * and the content lives under `x-ext`, so `#/components/schemas/User` reaches the schema in two hops.
+ * Stopping at the first hop hands consumers the stub, a node with no `type` and no `properties`, which
+ * renders as an empty, non-expandable schema.
+ *
+ * Stops at a reference that has not been resolved yet and hands that node back, which is what a single
+ * hop onto an unresolved reference produces today. `seen` terminates a reference cycle on the node it
+ * comes back around to rather than looping.
+ *
+ * @param value - The value the first hop produced.
+ * @param seen - References already crossed, including the node the chain started at.
+ */
+const followPassThroughReferences = (value, seen) => {
+    let current = value;
+    while (isReferenceNode(current) && isPassThroughReference(current) && !seen.has(current)) {
+        const next = current['$ref-value'];
+        if (next === undefined) {
+            return current;
+        }
+        seen.add(current);
+        current = next;
+    }
+    return current;
+};
 const defaultTransform = (node) => {
     // Unresolved references have no value; callers must account for that state.
-    return node['$ref-value'];
+    const value = node['$ref-value'];
+    if (value === undefined) {
+        return undefined;
+    }
+    return followPassThroughReferences(value, new Set([node]));
 };
 /**
  * Transform for getResolvedRef that merges sibling properties of a $ref wrapper
@@ -10,15 +67,16 @@ const defaultTransform = (node) => {
  */
 export const mergeSiblingReferences = (node) => {
     const { '$ref-value': value, ...rest } = node;
+    const target = value === undefined ? undefined : followPassThroughReferences(value, new Set([node]));
     // A reference can land on something that is not a record: a pointer that aims at a string
     // (`$ref: '#/info/title'`), one that was never resolved, or one whose target is an array. Spreading
     // any of those copies it index by index, so a reference to a title becomes `{ 0: 'G', 1: 'a', … }`
     // and every consumer downstream treats those digits as real properties. There is nothing to merge
     // siblings onto in that case, so only the siblings survive.
-    if (!isObject(value)) {
+    if (!isObject(target)) {
         return rest;
     }
-    return { ...value, ...rest };
+    return { ...target, ...rest };
 };
 export function getResolvedRef(node, transform = defaultTransform) {
     if (typeof node === 'object' && node !== null && '$ref' in node) {

package/dist/helpers/unpack-proxy.d.ts

@@ -13,6 +13,16 @@
  * @param depth - Optional, limits recursion depth. `null` means unlimited depth (default is 1).
  * @returns - A plain object or array with all proxies removed up to the specified depth.
  */
+/**
+ * Strips the known proxies (Vue reactivity, overrides, detect-changes, magic) from a value without
+ * touching its properties, returning the raw object underneath.
+ *
+ * Use this when the raw object is wanted as an identity — a cache key or a cycle guard — rather than as
+ * data. `unpackProxyObject` walks the value's own properties and writes each one back, which costs a
+ * read and a write per property and mutates the object it unpacks; callers that only compare identities
+ * pay for neither.
+ */
+export declare const unpackProxyShallow: <T>(input: T) => T;
 export declare const unpackProxyObject: <T>(input: T, { depth }?: {
     depth?: number | null;
 }) => T;

package/dist/helpers/unpack-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unpack-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/unpack-proxy.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,YAAe;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,KAAG,CAsE9F,CAAA"}
+{"version":3,"file":"unpack-proxy.d.ts","sourceRoot":"","sources":["../../src/helpers/unpack-proxy.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,CAMhD,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,YAAe;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,KAAG,CAsE9F,CAAA"}

package/dist/helpers/unpack-proxy.js

@@ -17,6 +17,21 @@ import { unpackOverridesProxy } from '../helpers/overrides-proxy.js';
  * @param depth - Optional, limits recursion depth. `null` means unlimited depth (default is 1).
  * @returns - A plain object or array with all proxies removed up to the specified depth.
  */
+/**
+ * Strips the known proxies (Vue reactivity, overrides, detect-changes, magic) from a value without
+ * touching its properties, returning the raw object underneath.
+ *
+ * Use this when the raw object is wanted as an identity — a cache key or a cycle guard — rather than as
+ * data. `unpackProxyObject` walks the value's own properties and writes each one back, which costs a
+ * read and a write per property and mutates the object it unpacks; callers that only compare identities
+ * pay for neither.
+ */
+export const unpackProxyShallow = (input) => {
+    if (typeof input !== 'object' || input === null) {
+        return input;
+    }
+    return unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(input))));
+};
 export const unpackProxyObject = (input, { depth = 0 } = {}) => {
     // Internal DFS helper to recursively strip all known proxies (Vue, overrides, detect-changes, magic proxies)
     const dfs = (value, currentDepth = 0) => {

package/dist/request-example/builder/helpers/get-example-from-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-example-from-schema.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-example-from-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,YAAY,EAAqD,MAAM,uBAAuB,CAAA;AAG5G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AA+wB1E,KAAK,2BAA2B,GAAG;IACjC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,qDAAqD;IACrD,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9C,CAAA;AA+ND;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,YAAY,EACpB,UAAU,2BAA2B,EACrC,iEAOG,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,YAAY,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACrB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,qGAAqG;IACrG,YAAY,EAAE,YAAY,CAAA;CAC3B,CAAM,KACN,OAmNF,CAAA"}
+{"version":3,"file":"get-example-from-schema.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-example-from-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,YAAY,EAAqD,MAAM,uBAAuB,CAAA;AAG5G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AA+wB1E,KAAK,2BAA2B,GAAG;IACjC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,qDAAqD;IACrD,8BAA8B,CAAC,EAAE,OAAO,CAAA;IACxC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9C,CAAA;AAuPD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,YAAY,EACpB,UAAU,2BAA2B,EACrC,iEAOG,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,YAAY,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACrB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,qGAAqG;IACrG,YAAY,EAAE,YAAY,CAAA;CAC3B,CAAM,KACN,OAmNF,CAAA"}

package/dist/request-example/builder/helpers/get-example-from-schema.js

@@ -646,6 +646,26 @@ const createOptionsCacheKey = (options) => JSON.stringify({
         ? Object.entries(options.compositionSelection).sort(([a], [b]) => a.localeCompare(b))
         : undefined,
 });
+/** Sentinel for "nothing memoized yet", since `undefined` is itself a valid options value. */
+const NO_OPTIONS = Symbol('NO_OPTIONS');
+/** The options object `lastOptionsKey` was built from. */
+let lastOptions = NO_OPTIONS;
+let lastOptionsKey = '';
+/**
+ * The options half of the result-cache key, built once per top-level call instead of once per node.
+ *
+ * `createOptionsCacheKey` serializes the whole options object, and every schema the walk enters needs
+ * the same string. The walk is synchronous and passes the same `options` object down, so rebuilding at
+ * level 0, or whenever the identity changes, is enough: a caller that mutates its options object in
+ * place still gets a fresh key on its next top-level call, exactly as before.
+ */
+const getOptionsCacheKey = (options, level) => {
+    if (level === 0 || options !== lastOptions) {
+        lastOptionsKey = createOptionsCacheKey(options);
+        lastOptions = options;
+    }
+    return lastOptionsKey;
+};
 /** Stand-in for a truncated schema whose shape cannot be read off the document. */
 const MAX_DEPTH_EXCEEDED = '[Max Depth Exceeded]';
 /** How long a chain of composition wrappers may be unwrapped before the stack becomes the concern. */
@@ -867,7 +887,7 @@ export const getExampleFromSchema = (schema, options, { level = 0, parentSchema,
     }
     seen.add(targetValue);
     /** Make the cache key unique per options and schema path */
-    const cacheKey = createOptionsCacheKey(options) + (schemaPath.length > 0 ? `:path:${schemaPath.join('.')}` : '');
+    const cacheKey = getOptionsCacheKey(options, level) + (schemaPath.length > 0 ? `:path:${schemaPath.join('.')}` : '');
     // Check cache first for performance - avoid recomputing the same schema (skipped under a dynamic scope)
     if (!skipCache) {
         const cached = resultCache.get(targetValue)?.get(cacheKey);

package/dist/resolve.d.ts

@@ -1,7 +1,15 @@
 import type { MaybeRefSchemaObject, SchemaObject } from './schemas/v3.2/strict/schema.js';
-type ResolvedSchema<T> = T extends undefined ? undefined : SchemaObject & {
+/**
+ * A resolved schema is a read-only view.
+ *
+ * What comes back is either the document's own node or a shallow merge over it, so the nested values
+ * are the document's either way and a write reaches the document without going through the store. The
+ * `Readonly` says so to the compiler at the one level where a write is cheap to make by accident; a
+ * caller with a change to make copies what it needs, or goes through a store mutation.
+ */
+type ResolvedSchema<T> = T extends undefined ? undefined : Readonly<SchemaObject & {
     $ref?: string;
-};
+}>;
 export declare const resolve: {
     schema: <T extends MaybeRefSchemaObject | undefined>(schema: T) => ResolvedSchema<T>;
 };

package/dist/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEtF,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3F,eAAO,MAAM,OAAO;aACT,CAAC,SAAS,oBAAoB,GAAG,SAAS,UAAU,CAAC,KAAG,cAAc,CAAC,CAAC,CAAC;CAWnF,CAAA"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEtF;;;;;;;GAOG;AACH,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC,YAAY,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAWrG,eAAO,MAAM,OAAO;aACT,CAAC,SAAS,oBAAoB,GAAG,SAAS,UAAU,CAAC,KAAG,cAAc,CAAC,CAAC,CAAC;CAQnF,CAAA"}

package/dist/resolve.js

@@ -3,12 +3,20 @@ import { getResolvedRef, mergeSiblingReferences } from './helpers/get-resolved-r
 import { compose } from './schemas/compose.js';
 import { coerceValue } from './schemas/typebox-coerce.js';
 import { SchemaObjectSchema } from './schemas/v3.2/strict/openapi-document.js';
+/**
+ * The coercion target: a schema object that may still carry the `$ref` it was resolved from.
+ *
+ * `Type.Composite` merges every property of `SchemaObjectSchema` to build this, so it belongs at module
+ * scope. `resolve.schema` runs once per property of every schema a render walks, and rebuilding the
+ * composite per call dominated that walk.
+ */
+const resolvedSchemaSchema = compose(SchemaObjectSchema, Type.Object({ $ref: Type.Optional(Type.String()) }));
 export const resolve = {
     schema: (schema) => {
         if (schema === undefined) {
             return undefined;
         }
         const resoled = getResolvedRef(schema, mergeSiblingReferences);
-        return coerceValue(compose(SchemaObjectSchema, Type.Object({ $ref: Type.Optional(Type.String()) })), resoled);
+        return coerceValue(resolvedSchemaSchema, resoled);
     },
 };

package/package.json

@@ -16,7 +16,7 @@
     "openapi",
     "scalar"
   ],
-  "version": "0.62.0",
+  "version": "0.63.0",
   "engines": {
     "node": ">=22"
   },