@scalar/workspace-store 0.62.0 → 0.64.0

package/dist/helpers/chunk-index.js

@@ -0,0 +1,139 @@
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { escapeJsonPointer } from '@scalar/json-magic/helpers/escape-json-pointer';
+import { encodeChunkName } from '../helpers/encode-chunk-name.js';
+/**
+ * The extension key a compact sparse document carries its chunk index under.
+ *
+ * It exists on the wire only: the client expands the index back into per-node references while the
+ * document is ingested and removes the key, so nothing downstream ever sees it.
+ */
+export const CHUNK_INDEX_KEY = 'x-scalar-chunk-index';
+/** Stands in for an externalized operation on a compact path item. */
+const OPERATION_PLACEHOLDER = 0;
+/** Matches a `{slot}` in a template, or a doubled brace standing for a literal one. */
+const TEMPLATE_SLOT = /\{\{|\}\}|\{(\w+)\}/g;
+/**
+ * Fills the `{slot}`s of a chunk-reference template.
+ *
+ * `{{` and `}}` stand for literal braces, so text the writer inlined into a template — a document
+ * name, a base URL — may contain braces without being read back as a slot. An unknown slot is left
+ * alone rather than blanked, so a template from a newer writer fails visibly instead of resolving
+ * to the wrong chunk.
+ */
+export const fillChunkRef = (template, values = {}) => template.replace(TEMPLATE_SLOT, (match, slot) => slot === undefined ? match.charAt(0) : (values[slot] ?? match));
+/** Escapes text inlined into a template verbatim, so its braces are not read back as slots. */
+const escapeTemplateLiteral = (text) => text.replaceAll('{', '{{').replaceAll('}', '}}');
+const identity = (value) => value;
+/**
+ * How each template slot is spelled, per mode.
+ *
+ * Static references name files, so their variable segments go through `encodeChunkName` — the same
+ * call `generateWorkspaceChunks` makes when it writes those files. SSR references name pointers
+ * into the store's in-memory assets, which `get()` looks up with JSON Pointer segments, so only the
+ * path is escaped. A method is never encoded in either mode: it is written as it was read, and
+ * `isHttpMethod` keeps it to letters.
+ *
+ * Both sides read the table from here. A reader that encoded a segment differently would build a
+ * reference to a chunk that does not exist.
+ */
+const SLOT_ENCODERS = {
+    static: { type: encodeChunkName, name: encodeChunkName, path: encodeChunkName, method: identity },
+    ssr: { type: identity, name: identity, path: escapeJsonPointer, method: identity },
+};
+/**
+ * Builds the reference templates for one document.
+ *
+ * Filled, these produce exactly the references `externalizeComponentReferences` and
+ * `externalizePathReferences` write, so a client that expands the index lands on the same chunk.
+ */
+export const chunkRefTemplates = (meta) => {
+    if (meta.mode === 'ssr') {
+        const base = `${escapeTemplateLiteral(meta.baseUrl)}/${escapeTemplateLiteral(meta.name)}`;
+        return {
+            components: `${base}/components/{type}/{name}#`,
+            operations: `${base}/operations/{path}/{method}#`,
+            navigation: `${base}/navigation#`,
+        };
+    }
+    const base = `./chunks/${escapeTemplateLiteral(encodeChunkName(meta.name))}`;
+    return {
+        components: `${base}/components/{type}/{name}.json#`,
+        operations: `${base}/operations/{path}/{method}.json#`,
+        navigation: `${base}/navigation.json#`,
+    };
+};
+/** The reference a lazily loaded chunk is reached through. */
+export const chunkReference = (ref) => ({ '$ref': ref, $global: true });
+/**
+ * Compacts a sparse document's `components` and `paths` into an index.
+ *
+ * Takes the sections the externalizers produced rather than the document itself, so the index is
+ * built from the very references it replaces and the two cannot come to describe different sets of
+ * chunks.
+ */
+export const buildChunkIndex = ({ mode, refs, components, paths, }) => ({
+    mode,
+    refs,
+    components: Object.fromEntries(Object.entries(components).map(([type, names]) => [type, Object.keys(names)])),
+    paths: Object.fromEntries(Object.entries(paths).map(([path, pathItem]) => [
+        path,
+        Object.fromEntries(Object.entries(pathItem).map(([key, value]) => [key, isHttpMethod(key) ? OPERATION_PLACEHOLDER : value])),
+    ])),
+});
+/** Whether a value is shaped like an index this build knows how to expand. */
+const isChunkIndex = (value) => isObject(value) &&
+    (value['mode'] === 'static' || value['mode'] === 'ssr') &&
+    isObject(value['refs']) &&
+    isObject(value['components']) &&
+    isObject(value['paths']);
+/**
+ * Expands a compact sparse document into the one a non-compact server store would have sent.
+ *
+ * Mutates the document in place and drops the index key, so what the rest of the store sees is an
+ * ordinary sparse document: `resolve()`, the bundler and anything enumerating `paths` or
+ * `components` are looking at the shape they always have.
+ *
+ * A document without an index is left alone, which is every document a non-compact server store or
+ * an author produces.
+ *
+ * @param document - The document to expand, mutated in place
+ * @returns Whether an index was found and expanded
+ */
+export const expandChunkIndex = (document) => {
+    if (!isObject(document) || document[CHUNK_INDEX_KEY] === undefined) {
+        return false;
+    }
+    const index = document[CHUNK_INDEX_KEY];
+    if (!isChunkIndex(index)) {
+        // The key is dropped rather than passed on: it is not part of any document a consumer should
+        // see, and the sections it stands for are missing either way, so there is nothing a partial
+        // expansion could recover.
+        delete document[CHUNK_INDEX_KEY];
+        console.warn(`Ignoring an unreadable "${CHUNK_INDEX_KEY}"; this document's chunks cannot be resolved.`);
+        return false;
+    }
+    const encoders = SLOT_ENCODERS[index.mode];
+    // Define own properties so document keys such as `__proto__` remain data, without invoking
+    // inherited setters or changing the prototype of any expanded object.
+    const components = Object.fromEntries(Object.entries(index.components).map(([type, names]) => [
+        type,
+        Object.fromEntries(names.map((name) => [
+            name,
+            chunkReference(fillChunkRef(index.refs.components, { type: encoders.type(type), name: encoders.name(name) })),
+        ])),
+    ]));
+    const paths = Object.fromEntries(Object.entries(index.paths).map(([path, pathItem]) => [
+        path,
+        Object.fromEntries(Object.entries(pathItem).map(([key, value]) => [
+            key,
+            isHttpMethod(key)
+                ? chunkReference(fillChunkRef(index.refs.operations, { path: encoders.path(path), method: encoders.method(key) }))
+                : value,
+        ])),
+    ]));
+    document['components'] = components;
+    document['paths'] = paths;
+    delete document[CHUNK_INDEX_KEY];
+    return true;
+};

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/external-examples.d.ts

@@ -0,0 +1,17 @@
+import { type LoaderPlugin } from '@scalar/json-magic/bundle';
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser';
+import type { ExampleObject } from '../schemas/v3.2/strict/openapi-document.js';
+/** Download state lives outside the document so reading an example never creates an edit. */
+export type ExternalExampleState = {
+    status: 'idle' | 'loading' | 'loaded' | 'error';
+    value?: unknown;
+    load: () => Promise<void>;
+};
+/** A resolver belongs to one document revision and its configured transport. */
+export type ExternalExampleResolver = (example: ExampleObject) => ExternalExampleState;
+/** Cache external payloads and in-flight requests without changing authored examples. */
+export declare const createExternalExampleResolver: (options?: Parameters<typeof fetchUrls>[0] & {
+    origin?: string;
+    fileLoader?: LoaderPlugin;
+}) => ExternalExampleResolver;
+//# sourceMappingURL=external-examples.d.ts.map

package/dist/helpers/external-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-examples.d.ts","sourceRoot":"","sources":["../../src/helpers/external-examples.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAA;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,6FAA6F;AAC7F,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,CAAA;AAED,gFAAgF;AAChF,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,oBAAoB,CAAA;AAEtF,yFAAyF;AACzF,eAAO,MAAM,6BAA6B,GACxC,UAAS,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,YAAY,CAAA;CAAO,KAC7F,uBAuCF,CAAA"}

package/dist/helpers/external-examples.js

@@ -0,0 +1,50 @@
+import { resolveReferencePath } from '@scalar/json-magic/bundle';
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser';
+import { shallowReactive } from 'vue';
+/** Cache external payloads and in-flight requests without changing authored examples. */
+export const createExternalExampleResolver = (options = {}) => {
+    const loader = fetchUrls({ ...options, limit: 10 });
+    const cache = new Map();
+    return (example) => {
+        if (example.value !== undefined || !example.externalValue) {
+            return { status: 'loaded', value: example.value, load: () => Promise.resolve() };
+        }
+        const url = resolveReferencePath(options.origin ?? '', example.externalValue) ?? example.externalValue;
+        const cached = cache.get(url);
+        if (cached)
+            return cached;
+        let pending;
+        const state = shallowReactive({
+            status: 'idle',
+            load: () => {
+                if (pending)
+                    return pending;
+                if (state.status === 'loaded')
+                    return Promise.resolve();
+                state.status = 'loading';
+                pending = (async () => {
+                    try {
+                        const selectedLoader = [loader, options.fileLoader].find((candidate) => candidate?.validate(url));
+                        const result = await selectedLoader?.exec(url);
+                        if (result?.ok) {
+                            state.value = result.data === undefined ? result.raw : result.data;
+                            state.status = 'loaded';
+                        }
+                        else {
+                            state.status = 'error';
+                        }
+                    }
+                    catch {
+                        state.status = 'error';
+                    }
+                    finally {
+                        pending = undefined;
+                    }
+                })();
+                return pending;
+            },
+        });
+        cache.set(url, state);
+        return state;
+    };
+};

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