@scalar/workspace-store 0.63.0 → 0.65.0

package/dist/client.js

@@ -16,16 +16,20 @@ import { reactive } from 'vue';
 import YAML from 'yaml';
 import { createAuthStore } from './entities/auth/index.js';
 import { createHistoryStore } from './entities/history/index.js';
+import { chunkReference, expandChunkIndex } from './helpers/chunk-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 { createExternalExampleResolver } from './helpers/external-examples.js';
 import { safeAssign } from './helpers/general.js';
 import { getFetch } from './helpers/get-fetch.js';
+import { getResolvedRef } from './helpers/get-resolved-ref.js';
 import { mergeObjects } from './helpers/merge-object.js';
+import { normalizeBooleanSchemas } from './helpers/normalize-boolean-schemas.js';
 import { createOverridesProxy } from './helpers/overrides-proxy.js';
 import { unpackProxyObject } from './helpers/unpack-proxy.js';
 import { createNavigation, traverseAsyncApiDocument } from './navigation/index.js';
-import { externalValueResolver, loadingStatus, normalizeAuthSchemes, normalizeRefs, refsEverywhere, removeExtraScalarKeys, restoreOriginalRefs, syncPathParameters, } from './plugins/bundler/index.js';
+import { externalValueResolver, loadingStatus, normalizeAuthSchemes, normalizeRefs, openApiDocument, refsEverywhere, removeExtraScalarKeys, resolveOpenApiDocument, restoreOriginalRefs, syncPathParameters, } from './plugins/bundler/index.js';
 import { extensions } from './schemas/extensions.js';
 import { isAsyncApiDocument, isOpenApiDocument } from './schemas/type-guards.js';
 import { generateSchema } from './schemas/v3.2/openapi/index.js';
@@ -129,8 +133,10 @@ const purgeInternalDocumentKeys = (input) => {
         // Bundler metadata fields added temporarily during document processing
         'x-ext',
         'x-ext-urls',
+        'x-scalar-original-refs',
         // Scalar internal/external metadata fields
         'x-scalar-navigation',
+        'x-scalar-navigation-chunk',
         'x-scalar-is-dirty',
         'x-original-oas-version',
         'x-scalar-original-document-hash',
@@ -156,7 +162,7 @@ const purgeInternalDocumentKeys = (input) => {
  * @returns An object containing methods and getters for managing the workspace
  */
 export const createWorkspaceStore = (workspaceProps) => {
-    const { verbose = false } = workspaceProps ?? {};
+    const { verbose = false, reactive: isReactiveWorkspace = true } = workspaceProps ?? {};
     const withMeasurementSync = (name, fn) => (verbose ? measureSync(name, fn) : fn());
     const withMeasurementAsync = (name, fn) => verbose ? measureAsync(name, fn) : fn();
     /**
@@ -165,6 +171,11 @@ export const createWorkspaceStore = (workspaceProps) => {
      * This can include settings that can not be persisted between sessions (not JSON serializable)
      */
     const extraDocumentConfigurations = {};
+    const externalExampleResolvers = new WeakMap();
+    const fallbackExternalExamples = createExternalExampleResolver({
+        fetch: workspaceProps?.fetch,
+        fileLoader: workspaceProps?.fileLoader,
+    });
     /**
      * Notifies all workspace plugins of a workspace state change event.
      *
@@ -177,20 +188,9 @@ export const createWorkspaceStore = (workspaceProps) => {
         workspaceProps?.plugins?.forEach((plugin) => plugin.hooks?.onWorkspaceStateChanges?.(event));
     };
     /**
-     * An object containing the reactive workspace state.
-     *
-     * Every change to the workspace, is tracked and broadcast to all registered plugins.
-     * allowing for change tracking.
-     *
-     * NOTE:
-     * The detect changes proxy is applied separately beacause the vue reactitvity proxy have to be the outer most proxy.
-     * If the order is reversed, Vue cannot properly track mutations, leading to lost reactivity and bugs.
-     * By wrapping the contents with the detect changes proxy first, and then passing the result to Vue's `reactive`,
-     * we ensure that Vue manages its reactivity as expected and our change detection hooks
-     * are also triggered reliably.
-     * Do not reverse this order‼️
+     * The plain workspace state, before any observability wrappers are applied.
      */
-    const workspace = reactive(createDetectChangesProxy({
+    const workspaceState = {
         ...workspaceProps?.meta,
         documents: {},
         /**
@@ -203,88 +203,105 @@ export const createWorkspaceStore = (workspaceProps) => {
         get activeDocument() {
             return workspace.documents[getActiveDocumentName()];
         },
-    }, {
-        hooks: {
-            onAfterChange(path) {
-                const type = path[0];
-                /** Document changes */
-                if (type === 'documents') {
-                    // We are overriding the while documents object, ignore. This should not happen
-                    if (path.length < 2) {
-                        console.log('[WARN]: Overriding entire documents object is not supported');
+    };
+    /**
+     * An object containing the reactive workspace state.
+     *
+     * Every change to the workspace, is tracked and broadcast to all registered plugins.
+     * allowing for change tracking.
+     *
+     * With `reactive: false` the state is used as-is, so reads cost nothing beyond the plain object and
+     * nothing observes a write. See the `reactive` option for the full list of what stops happening.
+     *
+     * NOTE:
+     * The detect changes proxy is applied separately beacause the vue reactitvity proxy have to be the outer most proxy.
+     * If the order is reversed, Vue cannot properly track mutations, leading to lost reactivity and bugs.
+     * By wrapping the contents with the detect changes proxy first, and then passing the result to Vue's `reactive`,
+     * we ensure that Vue manages its reactivity as expected and our change detection hooks
+     * are also triggered reliably.
+     * Do not reverse this order‼️
+     */
+    const workspace = !isReactiveWorkspace
+        ? workspaceState
+        : reactive(createDetectChangesProxy(workspaceState, {
+            hooks: {
+                onAfterChange(path) {
+                    const type = path[0];
+                    /** Document changes */
+                    if (type === 'documents') {
+                        // We are overriding the while documents object, ignore. This should not happen
+                        if (path.length < 2) {
+                            console.log('[WARN]: Overriding entire documents object is not supported');
+                            return;
+                        }
+                        const documentName = path[1];
+                        const document = workspace.documents[documentName] ?? {
+                            openapi: '3.1.0',
+                            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,
+                            value: unpackProxyObject(document),
+                            path: path.slice(2),
+                        };
+                        // Don't mark as dirty when the document is first created or when
+                        // only metadata-only fields change. `x-scalar-registry-meta` is
+                        // updated programmatically (commit hash, conflict cache) and
+                        // does not represent a user edit.
+                        if (event.path.length > 0 && !METADATA_ONLY_DOCUMENT_KEYS.has(event.path[0])) {
+                            // The document has been modified since it was last saved
+                            document['x-scalar-is-dirty'] = true;
+                        }
+                        fireWorkspaceChange(event);
                         return;
                     }
-                    const documentName = path[1];
-                    const document = workspace.documents[documentName] ?? {
-                        openapi: '3.1.0',
-                        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,
-                        value: unpackProxyObject(document),
-                        path: path.slice(2),
-                    };
-                    // Don't mark as dirty when the document is first created or when
-                    // only metadata-only fields change. `x-scalar-registry-meta` is
-                    // updated programmatically (commit hash, conflict cache) and
-                    // does not represent a user edit.
-                    if (event.path.length > 0 && !METADATA_ONLY_DOCUMENT_KEYS.has(event.path[0])) {
-                        // The document has been modified since it was last saved
-                        document['x-scalar-is-dirty'] = true;
+                    /** Active document changes */
+                    if (type === 'activeDocument') {
+                        const documentName = getActiveDocumentName();
+                        const document = workspace.documents[documentName] ?? {
+                            openapi: '3.1.0',
+                            info: { title: '', version: '' },
+                            'x-scalar-original-document-hash': '',
+                        };
+                        bumpDocumentRevision(document);
+                        // Active document changed
+                        const event = {
+                            type: 'documents',
+                            documentName,
+                            value: unpackProxyObject(document),
+                            path: path.slice(2),
+                        };
+                        // Don't mark as dirty when the document is first created or when
+                        // only metadata-only fields change. `x-scalar-registry-meta` is
+                        // updated programmatically (commit hash, conflict cache) and
+                        // does not represent a user edit.
+                        if (event.path.length > 0 && !METADATA_ONLY_DOCUMENT_KEYS.has(event.path[0])) {
+                            // The document has been modified since it was last saved
+                            document['x-scalar-is-dirty'] = true;
+                        }
+                        fireWorkspaceChange(event);
+                        return;
                     }
-                    fireWorkspaceChange(event);
-                    return;
-                }
-                /** Active document changes */
-                if (type === 'activeDocument') {
-                    const documentName = getActiveDocumentName();
-                    const document = workspace.documents[documentName] ?? {
-                        openapi: '3.1.0',
-                        info: { title: '', version: '' },
-                        'x-scalar-original-document-hash': '',
-                    };
-                    bumpDocumentRevision(document);
-                    // Active document changed
+                    /** Workspace meta changes */
+                    const { activeDocument: _a, documents: _d, ...meta } = workspace;
                     const event = {
-                        type: 'documents',
-                        documentName,
-                        value: unpackProxyObject(document),
-                        path: path.slice(2),
+                        type: 'meta',
+                        value: unpackProxyObject(meta, { depth: 1 }),
                     };
-                    // Don't mark as dirty when the document is first created or when
-                    // only metadata-only fields change. `x-scalar-registry-meta` is
-                    // updated programmatically (commit hash, conflict cache) and
-                    // does not represent a user edit.
-                    if (event.path.length > 0 && !METADATA_ONLY_DOCUMENT_KEYS.has(event.path[0])) {
-                        // The document has been modified since it was last saved
-                        document['x-scalar-is-dirty'] = true;
-                    }
                     fireWorkspaceChange(event);
                     return;
-                }
-                /** Workspace meta changes */
-                const { activeDocument: _a, documents: _d, ...meta } = workspace;
-                const event = {
-                    type: 'meta',
-                    value: unpackProxyObject(meta, { depth: 1 }),
-                };
-                fireWorkspaceChange(event);
-                return;
+                },
             },
-        },
-    }));
+        }));
     /**
-     * An object containing all the workspace state, wrapped in a detect changes proxy.
-     *
-     * Every change to the workspace state (documents, configs, metadata, etc.) can be detected here,
-     * allowing for change tracking.
+     * The plain document snapshot maps, before the detect changes proxy is applied.
      */
-    const { originalDocuments, intermediateDocuments, overrides } = createDetectChangesProxy({
+    const documentSnapshots = {
         /**
          * Holds the original, unmodified documents as they were initially loaded into the workspace.
          * These documents are stored in their raw form—prior to any reactive wrapping, dereferencing, or bundling.
@@ -316,46 +333,57 @@ export const createWorkspaceStore = (workspaceProps) => {
          * OpenAPI document representing the overridden fields.
          */
         overrides: {},
-    }, {
-        hooks: {
-            onAfterChange(path) {
-                const type = path[0];
-                if (!type) {
-                    return;
-                }
-                if (path.length < 2) {
-                    return;
-                }
-                const documentName = path[1];
-                if (type === 'originalDocuments') {
-                    const event = {
-                        type,
-                        documentName: documentName,
-                        value: unpackProxyObject(originalDocuments[documentName] ?? {}),
-                        path: path.splice(2),
-                    };
-                    fireWorkspaceChange(event);
-                }
-                if (type === 'intermediateDocuments') {
-                    const event = {
-                        type,
-                        documentName: documentName,
-                        value: unpackProxyObject(intermediateDocuments[documentName] ?? {}),
-                        path: path.splice(2),
-                    };
-                    fireWorkspaceChange(event);
-                }
-                if (type === 'overrides') {
-                    const event = {
-                        type,
-                        documentName: documentName,
-                        value: unpackProxyObject(overrides[documentName] ?? {}),
-                    };
-                    fireWorkspaceChange(event);
-                }
+    };
+    /**
+     * An object containing all the workspace state, wrapped in a detect changes proxy.
+     *
+     * Every change to the workspace state (documents, configs, metadata, etc.) can be detected here,
+     * allowing for change tracking.
+     *
+     * With `reactive: false` the maps are used as-is and a write to them notifies nobody.
+     */
+    const { originalDocuments, intermediateDocuments, overrides } = !isReactiveWorkspace
+        ? documentSnapshots
+        : createDetectChangesProxy(documentSnapshots, {
+            hooks: {
+                onAfterChange(path) {
+                    const type = path[0];
+                    if (!type) {
+                        return;
+                    }
+                    if (path.length < 2) {
+                        return;
+                    }
+                    const documentName = path[1];
+                    if (type === 'originalDocuments') {
+                        const event = {
+                            type,
+                            documentName: documentName,
+                            value: unpackProxyObject(originalDocuments[documentName] ?? {}),
+                            path: path.splice(2),
+                        };
+                        fireWorkspaceChange(event);
+                    }
+                    if (type === 'intermediateDocuments') {
+                        const event = {
+                            type,
+                            documentName: documentName,
+                            value: unpackProxyObject(intermediateDocuments[documentName] ?? {}),
+                            path: path.splice(2),
+                        };
+                        fireWorkspaceChange(event);
+                    }
+                    if (type === 'overrides') {
+                        const event = {
+                            type,
+                            documentName: documentName,
+                            value: unpackProxyObject(overrides[documentName] ?? {}),
+                        };
+                        fireWorkspaceChange(event);
+                    }
+                },
             },
-        },
-    });
+        });
     /**
      * This store is used to track the history of requests and responses for documents and operations.
      */
@@ -387,6 +415,17 @@ export const createWorkspaceStore = (workspaceProps) => {
             },
         },
     });
+    /**
+     * Whether a document needs to be wrapped in the overrides proxy.
+     *
+     * A reactive workspace always wraps, so the default mode keeps every document the same shape it has
+     * always had. A non-reactive workspace wraps only a document that actually has overrides: with an
+     * empty override map the proxy resolves to the target on every read and write anyway, so all it adds
+     * is a proxy hop on every nested read. Nothing outside this file reads the proxy's identity, and the
+     * store rebuilds the document from the current override map whenever the map changes, so a document
+     * that gains overrides later gains the proxy along with them.
+     */
+    const needsOverridesProxy = (documentOverrides) => isReactiveWorkspace || (isObject(documentOverrides) && Object.keys(documentOverrides).length > 0);
     /**
      * Returns the name of the currently active document in the workspace.
      * The active document is determined by the 'x-scalar-active-document' metadata field,
@@ -440,6 +479,10 @@ export const createWorkspaceStore = (workspaceProps) => {
         const { name } = input;
         const meta = deepClone(input.meta);
         const clonedRawInputDocument = withMeasurementSync('deepClone', () => deepClone(input.document));
+        // A compact sparse document is expanded back into per-node chunk references before anything
+        // else reads it, so every step below — including the check for a server-generated navigation —
+        // sees the document a non-compact server store would have sent.
+        withMeasurementSync('expandChunkIndex', () => expandChunkIndex(clonedRawInputDocument));
         withMeasurementSync('initialize', () => {
             if (input.initialize !== false) {
                 // Store the original document in the originalDocuments map
@@ -502,9 +545,10 @@ export const createWorkspaceStore = (workspaceProps) => {
                 const navigation = traverseAsyncApiDocument(name, asyncApiDocument, navigationOptions);
                 asyncApiDocument[extensions.document.navigation] = navigation;
             }
-            workspace.documents[name] = createOverridesProxy(asyncApiDocument, {
-                overrides: unpackProxyObject(overrides[name]),
-            });
+            const asyncApiOverrides = unpackProxyObject(overrides[name]);
+            workspace.documents[name] = needsOverridesProxy(asyncApiOverrides)
+                ? createOverridesProxy(asyncApiDocument, { overrides: asyncApiOverrides })
+                : asyncApiDocument;
             return;
         }
         const inputDocument = withMeasurementSync('upgrade', () => upgrade(deepClone(clonedRawInputDocument), '3.1'));
@@ -514,7 +558,7 @@ export const createWorkspaceStore = (workspaceProps) => {
             'x-original-oas-version': originalDocuments[name]?.openapi ?? originalDocuments[name]?.swagger,
             'x-scalar-original-document-hash': input.documentHash,
             'x-scalar-original-source-url': input.documentSource,
-        }, { showInternal: true });
+        }, { showInternal: true, documentUri: resolveOpenApiDocument(inputDocument, input.documentSource ?? '/')?.baseUri });
         // If the document navigation is not already present, bundle the entire document to resolve all references.
         // This typically applies when the document is not preprocessed by the server and needs local reference resolution.
         // We need to bundle document first before we validate, so we can also validate the external references
@@ -523,8 +567,9 @@ export const createWorkspaceStore = (workspaceProps) => {
                 treeShake: false,
                 plugins: [
                     ...loaders,
+                    openApiDocument(),
                     normalizeRefs(),
-                    externalValueResolver(),
+                    externalValueResolver({ lazy: true }),
                     refsEverywhere(),
                     normalizeAuthSchemes(),
                     syncPathParameters(),
@@ -533,7 +578,7 @@ export const createWorkspaceStore = (workspaceProps) => {
                 origin: input.documentSource, // use the document origin (if provided) as the base URL for resolution
             }));
             // We coerce the values only when the document is not preprocessed by the server-side-store
-            const coerced = withMeasurementSync('coerceValue', () => coerce(openapiSchema, deepClone(strictDocument)));
+            const coerced = withMeasurementSync('coerceValue', () => coerce(openapiSchema, normalizeBooleanSchemas(deepClone(strictDocument))));
             withMeasurementSync('mergeObjects', () => mergeObjects(strictDocument, coerced));
         }
         const isValid = Value.Check(OpenAPIDocumentSchemaStrict, strictDocument);
@@ -555,9 +600,13 @@ export const createWorkspaceStore = (workspaceProps) => {
         // Create a proxied document with magic proxy and apply any overrides, then store it in the workspace documents map
         // We create a new proxy here in order to hide internal properties after validation and processing
         // This ensures that the workspace document only exposes the intended OpenAPI properties and extensions
-        workspace.documents[name] = createOverridesProxy(createMagicProxy(getRaw(strictDocument)), {
-            overrides: unpackProxyObject(overrides[name]),
+        const documentOverrides = unpackProxyObject(overrides[name]);
+        const magicDocument = createMagicProxy(getRaw(strictDocument), {
+            documentUri: resolveOpenApiDocument(getRaw(strictDocument), input.documentSource ?? '/')?.baseUri,
         });
+        workspace.documents[name] = needsOverridesProxy(documentOverrides)
+            ? createOverridesProxy(magicDocument, { overrides: documentOverrides })
+            : magicDocument;
     }
     // Asynchronously adds a new document to the workspace by loading and validating the input.
     // If loading fails, a placeholder error document is added instead.
@@ -650,9 +699,11 @@ export const createWorkspaceStore = (workspaceProps) => {
             // If the document does not exist, return null
             return null;
         }
-        // Reverse all external references and restore original $refs
+        // This is the shared cleanup boundary for editing and saving. Both JSON and YAML
+        // exports read the cleaned saved baseline, so serializers need no marker filtering.
+        // Reverse all external references and restore original $refs.
         const original = (await bundle(deepClone(rawDocument), {
-            plugins: [restoreOriginalRefs(), removeExtraScalarKeys()],
+            plugins: [openApiDocument(), restoreOriginalRefs(), removeExtraScalarKeys()],
             treeShake: false,
             urlMap: true,
         }));
@@ -688,10 +739,106 @@ export const createWorkspaceStore = (workspaceProps) => {
         document[extensions.document.navigation] = navigation;
         return true;
     };
+    /**
+     * Fetches the chunk a compact document keeps its navigation children in.
+     *
+     * The reference is bundled on an object of its own rather than in the document, so nothing of it
+     * is left behind: the chunk lands in that object's `x-ext` and is dropped along with it, and the
+     * navigation is never a reference, not even while the request is in flight. Navigation has one
+     * owner, so the children go on the document as they are and there is nothing for a shared `x-ext`
+     * entry to save.
+     *
+     * `depth: 0` stops the bundler at the reference itself, which is as far as a navigation chunk
+     * goes: its entries address the document through their own `ref` strings and carry no `$ref`.
+     *
+     * The chunk is handed back unwrapped: what it holds goes on the document, and a magic proxy there
+     * would enumerate a virtual `$ref-value` and stop the document being structured-cloned into
+     * storage. Unwrapping one level is enough, because the proxy wraps lazily.
+     *
+     * @returns The navigation the chunk holds, or `undefined` when it could not be loaded — the
+     *   bundler reports that failure the same way it reports an unreachable component chunk.
+     */
+    const fetchNavigationChunk = async (documentName, ref, origin) => {
+        const holder = createMagicProxy(chunkReference(ref));
+        await bundle(getRaw(holder), {
+            plugins: [
+                fetchUrls({
+                    fetch: extraDocumentConfigurations[documentName]?.fetch ?? workspaceProps?.fetch,
+                    limit: EXTERNAL_FETCH_CONCURRENCY_LIMIT,
+                }),
+                ...(workspaceProps?.fileLoader ? [workspaceProps.fileLoader] : []),
+            ],
+            treeShake: false,
+            origin,
+            depth: 0,
+            urlMap: true,
+        });
+        return getRaw(getResolvedRef(holder));
+    };
+    /** Share concurrent requests only within the same document instance, including after a workspace reload. */
+    const navigationChildrenLoads = new WeakMap();
+    /**
+     * Loads a compact document's navigation children and assigns them onto its navigation in place.
+     *
+     * Only a compact document carries `x-scalar-navigation-chunk`, and only until its children are
+     * loaded, so the key answers both "is there anything to load" and "has it already happened". It
+     * travels with the document, which is what lets a workspace exported before the children were
+     * loaded still load them once it has been imported into another store. A failed load leaves the
+     * key in place, so asking again retries.
+     */
+    const loadNavigationChildren = async (documentName) => {
+        const document = workspace.documents[documentName];
+        if (!isOpenApiDocument(document)) {
+            return;
+        }
+        const ref = document[extensions.document.navigationChunk];
+        const navigation = document[extensions.document.navigation];
+        if (ref === undefined || navigation === undefined) {
+            return;
+        }
+        const pending = navigationChildrenLoads.get(document);
+        if (pending) {
+            return pending;
+        }
+        const load = (async () => {
+            const chunk = await fetchNavigationChunk(documentName, ref, document['x-scalar-original-source-url']);
+            // A replaced or deleted document must not publish changes from a stale request.
+            if (chunk === undefined || workspace.documents[documentName] !== document) {
+                return;
+            }
+            // Assigned through the store's document, so the write is observed: a Vue effect reading the
+            // children re-runs, and the workspace plugins see the document change.
+            navigation.children = chunk.children ?? [];
+            delete document[extensions.document.navigationChunk];
+        })();
+        navigationChildrenLoads.set(document, load);
+        try {
+            await load;
+        }
+        finally {
+            navigationChildrenLoads.delete(document);
+        }
+    };
     // Cache to track visited nodes during reference resolution to prevent bundling the same subtree multiple times
     // This is needed because we are doing partial bundle operations
     const visitedNodesCache = new Set();
     return {
+        externalExamples: (documentName) => {
+            const name = documentName ?? getActiveDocumentName();
+            const document = workspace.documents[name];
+            if (!document)
+                return fallbackExternalExamples;
+            const existing = externalExampleResolvers.get(document);
+            if (existing)
+                return existing;
+            const resolver = createExternalExampleResolver({
+                origin: document['x-scalar-original-source-url'],
+                fileLoader: workspaceProps?.fileLoader,
+                fetch: extraDocumentConfigurations[name]?.fetch ?? workspaceProps?.fetch,
+            });
+            externalExampleResolvers.set(document, resolver);
+            return resolver;
+        },
         get workspace() {
             return workspace;
         },
@@ -743,8 +890,15 @@ export const createWorkspaceStore = (workspaceProps) => {
                 initialize: false,
             });
         },
-        resolve: (path) => {
+        resolve: async (path) => {
             const activeDocument = workspace.activeDocument;
+            // The navigation is never a reference: a compact document externalizes its children alone, and
+            // loading them is all there is to resolve here. Everything a navigation entry points at, it
+            // points at with a `ref` string of its own, so the bundler has nothing left to follow.
+            if (path[0] === extensions.document.navigation) {
+                await loadNavigationChildren(getActiveDocumentName());
+                return getValueAtPath(activeDocument, path);
+            }
             const target = getValueAtPath(activeDocument, path);
             if (!isObject(target)) {
                 console.error(`Invalid path provided for resolution. Path: [${path.join(', ')}]. Found value of type: ${typeof target}. Expected an object.`);
@@ -761,7 +915,16 @@ export const createWorkspaceStore = (workspaceProps) => {
                 root: activeDocument,
                 origin: activeDocument?.['x-scalar-original-source-url'],
                 treeShake: false,
-                plugins: [fetchUrls(), loadingStatus(), externalValueResolver()],
+                plugins: [
+                    openApiDocument(),
+                    fetchUrls({
+                        fetch: extraDocumentConfigurations[getActiveDocumentName()]?.fetch ?? workspaceProps?.fetch,
+                        limit: EXTERNAL_FETCH_CONCURRENCY_LIMIT,
+                    }),
+                    ...(workspaceProps?.fileLoader ? [workspaceProps.fileLoader] : []),
+                    loadingStatus(),
+                    externalValueResolver({ lazy: true }),
+                ],
                 urlMap: true,
                 visitedNodes: visitedNodesCache,
             });
@@ -855,12 +1018,25 @@ export const createWorkspaceStore = (workspaceProps) => {
             };
         },
         loadWorkspace(input) {
-            safeAssign(workspace.documents, Object.fromEntries(Object.entries(input.documents).map(([name, doc]) => [
-                name,
-                createOverridesProxy(createMagicProxy(doc), {
-                    overrides: input.overrides[name],
-                }),
-            ])));
+            // A workspace from a compact server store carries an index rather than per-node chunk
+            // references; expanded here for the same reason `addInMemoryDocument` expands.
+            for (const document of Object.values(input.documents)) {
+                expandChunkIndex(document);
+            }
+            safeAssign(workspace.documents, Object.fromEntries(Object.entries(input.documents).map(([name, doc]) => {
+                // Hydration only rewraps: an exported document has already been upgraded, bundled, coerced
+                // and given its navigation, so nothing here re-processes it.
+                const magicDocument = createMagicProxy(doc, {
+                    documentUri: resolveOpenApiDocument(doc, doc['x-scalar-original-source-url'] ?? '/')?.baseUri,
+                });
+                const documentOverrides = input.overrides[name];
+                return [
+                    name,
+                    needsOverridesProxy(documentOverrides)
+                        ? createOverridesProxy(magicDocument, { overrides: documentOverrides })
+                        : magicDocument,
+                ];
+            })));
             safeAssign(originalDocuments, input.originalDocuments);
             safeAssign(intermediateDocuments, input.intermediateDocuments);
             safeAssign(overrides, input.overrides);