@scalar/workspace-store 0.49.1 → 0.49.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @scalar/workspace-store
 
+## 0.49.2
+
+### Patch Changes
+
+- [#8921](https://github.com/scalar/scalar/pull/8921): Prevent infinite recursion when validating defaults on circular composed schemas.
+- [#9083](https://github.com/scalar/scalar/pull/9083): fix: prevent proxy leak into document meta breaking IndexedDB persistence
+- [#9059](https://github.com/scalar/scalar/pull/9059): feat: added the scalar-app back to open source
+- [#8921](https://github.com/scalar/scalar/pull/8921): fix nullable numeric schema defaults so empty-string defaults are normalized to null in generated request body examples.
+- [#9050](https://github.com/scalar/scalar/pull/9050): chore: depricate intermediate document state
+
 ## 0.49.1
 
 ### Patch Changes

package/README.md

@@ -7,6 +7,7 @@ A powerful data store for managing OpenAPI documents. This package provides a fl
 Server side data store which enables document chunking to reduce initial loading time specially when working with large openapi documents
 
 #### Usage
+
 Create a new store in SSR mode
 
 ```ts
@@ -44,29 +45,32 @@ const store = await createServerWorkspaceStore({
 })
 
 // Add a new document to the store
-await store.addDocument({
-  openapi: '3.1.1',
-  info: {
-    title: 'Hello World',
-    version: '1.0.0',
-  },
-  components: {
-    schemas: {
-      Person: {
-        type: 'object',
-        properties: {
-          name: { type: 'string' },
+await store.addDocument(
+  {
+    openapi: '3.1.1',
+    info: {
+      title: 'Hello World',
+      version: '1.0.0',
+    },
+    components: {
+      schemas: {
+        Person: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+        User: {
+          $ref: '#/components/schemas/Person',
         },
-      },
-      User: {
-        $ref: '#/components/schemas/Person',
       },
     },
   },
-}, {
-  name: 'document-2',
-  "x-scalar-selected-server": "server1"
-})
+  {
+    'name': 'document-2',
+    'x-scalar-selected-server': 'server1',
+  },
+)
 
 // Get the workspace
 // Workspace is going to keep all the sparse documents
@@ -74,10 +78,8 @@ const workspace = store.getWorkspace()
 
 // Get chucks using json pointers
 const chunk = store.get('#/document-name/components/schemas/Person')
-
 ```
 
-
 Create a new store in static mode
 
 ```ts
@@ -115,29 +117,32 @@ const store = await createServerWorkspaceStore({
 })
 
 // Add a new document to the store
-await store.addDocument({
-  openapi: '3.1.1',
-  info: {
-    title: 'Hello World',
-    version: '1.0.0',
-  },
-  components: {
-    schemas: {
-      Person: {
-        type: 'object',
-        properties: {
-          name: { type: 'string' },
+await store.addDocument(
+  {
+    openapi: '3.1.1',
+    info: {
+      title: 'Hello World',
+      version: '1.0.0',
+    },
+    components: {
+      schemas: {
+        Person: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+        User: {
+          $ref: '#/components/schemas/Person',
         },
-      },
-      User: {
-        $ref: '#/components/schemas/Person',
       },
     },
   },
-}, {
-  name: 'document-2',
-  "x-scalar-selected-server": "server1"
-})
+  {
+    'name': 'document-2',
+    'x-scalar-selected-server': 'server1',
+  },
+)
 
 // Generate the workspace file system
 // This will write in the filesystem the workspace and all the chucks
@@ -146,6 +151,7 @@ const workspace = await store.generateWorkspaceChunks()
 ```
 
 ### Load documents from external sources
+
 ```ts
 // Initialize the store with documents from external sources
 const store = await createServerWorkspaceStore({
@@ -153,13 +159,13 @@ const store = await createServerWorkspaceStore({
   documents: [
     {
       name: 'remoteFile',
-      url: 'http://localhost/document.json'
+      url: 'http://localhost/document.json',
     },
     {
       name: 'fsFile',
-      path: './document.json'
-    }
-  ]
+      path: './document.json',
+    },
+  ],
 })
 
 // Output: { openapi: 'x.x.x', ... }
@@ -175,35 +181,38 @@ A reactive workspace store for managing OpenAPI documents with automatic referen
 
 #### Usage
 
-```ts
+The client-side store starts empty and exposes `addDocument` for loading documents in. Workspace metadata, plugins, fetch overrides, and a file loader plugin can be supplied at construction time.
 
-// Initialize a new workspace store with default document
+```ts
+// Initialize a new (empty) workspace store
 const store = createWorkspaceStore({
-  documents: [
-    {
-      name: 'default',
-      document: {
-        info: {
-          title: 'OpenApi document',
-          version: '1.0.0',
-        },
-      },
-    },
-  ],
   meta: {
     'x-scalar-active-document': 'default',
   },
 })
 
-// Add another OpenAPI document to the workspace
+// Add the default document
 await store.addDocument({
+  name: 'default',
   document: {
+    openapi: '3.1.0',
     info: {
       title: 'OpenApi document',
       version: '1.0.0',
     },
   },
+})
+
+// Add another OpenAPI document to the workspace
+await store.addDocument({
   name: 'document',
+  document: {
+    openapi: '3.1.0',
+    info: {
+      title: 'Another document',
+      version: '1.0.0',
+    },
+  },
 })
 
 // Get the currently active document
@@ -216,7 +225,7 @@ store.workspace.documents['document']
 store.update('x-scalar-color-mode', true)
 
 // Update settings for the active document
-store.updateDocument('active', "x-scalar-watch-mode", '<value>')
+store.updateDocument('active', 'x-scalar-selected-server', 'production')
 
 // Resolve and load document chunks including any $ref references
 await store.resolve(['paths', '/users', 'get'])
@@ -224,7 +233,7 @@ await store.resolve(['paths', '/users', 'get'])
 
 #### Load documents from external sources
 
-You can only initialize the store with object literals but if you want to add documents from external sources you can use the addDocument function
+The store can also load documents from a URL or, when a file loader plugin is configured, from the local filesystem. Each call returns a boolean indicating whether the document was added successfully.
 
 ```ts
 const store = createWorkspaceStore()
@@ -232,7 +241,7 @@ const store = createWorkspaceStore()
 // Load a document into the store from a remote url
 await store.addDocument({
   name: 'default',
-  url: 'http://localhost/document.json'
+  url: 'http://localhost/document.json',
 })
 
 // Output: { openapi: 'x.x.x', ... }
@@ -241,11 +250,13 @@ console.log(store.workspace.documents.default)
 
 #### Document Persistence and Export
 
-The workspace store provides several methods for managing document persistence and exporting:
+The workspace store keeps two snapshots per document at runtime: the **original** (the last saved baseline that the user committed to with `saveDocument`) and the **active** document (the reactive in-memory state, which may include unsaved edits). Most persistence methods are anchored on those two snapshots.
+
+> **Deprecated:** an additional `intermediateDocuments` map and the helper methods `getIntermediateDocument` / `promoteIntermediateToOriginal` still exist for backward compatibility but are no longer authoritative. New code should rely on `getOriginalDocument` and the active document instead. The intermediate map is kept in sync on save / revert / rebase so existing consumers keep working until the layer is removed.
 
 ##### Export Document
 
-Export the specified document in JSON or YAML format:
+Export the specified document in JSON or YAML format. The export reads from the saved baseline (the same content `revertDocumentChanges` would restore), so it always reflects the user's last save rather than any unsaved edits.
 
 ```ts
 // Export the specified document as JSON
@@ -253,60 +264,57 @@ const jsonString = store.exportDocument('documentName', 'json')
 
 // Export the specified document as YAML
 const yamlString = store.exportDocument('documentName', 'yaml')
-```
 
-The download method returns the original, unmodified document (before any reactive wrapping) to preserve the initial structure without external references or modifications.
+// Or export the currently active document directly
+const activeJson = store.exportActiveDocument('json')
+```
 
 ##### Save Document Changes
 
-Persist the current state of the specified document back to the intermediate document (local saved version of the document):
+`saveDocument` promotes the current in-memory document to the new saved baseline. It serialises the reactive workspace document back into a plain shape (with bundler-internal keys stripped), writes it into the original-document map, and clears the document's `x-scalar-is-dirty` flag.
 
 ```ts
 // Save the specified document state
-const excludedDiffs = store.saveDocument('documentName')
+const ok = await store.saveDocument('documentName')
 
-// Check if any changes were excluded from being applied
-if (excludedDiffs) {
-  console.log('Some changes were excluded:', excludedDiffs)
+if (!ok) {
+  console.warn('Document does not exist or could not be serialised')
 }
 ```
 
-The `saveDocument` method takes the current reactive document state and persists it. It returns an array of diffs that were excluded from being applied or undefined if no specified document is available.
+`saveDocument` returns `true` on success and `false` when the document does not exist or cannot be serialised back into the original map.
 
 ##### Revert Document Changes
 
-Revert the specified document to its most recent local saved state, discarding all unsaved changes:
+Revert the specified document to its most recent saved baseline, discarding all unsaved in-memory changes.
 
 ```ts
-// Revert the specified document to its original state
-store.revertDocumentChanges('documentName')
+// Revert the specified document to its last saved state
+await store.revertDocumentChanges('documentName')
 ```
 
-The `revertDocumentChanges` method restores the specified document to its initial state by copying the original document (before any modifications) back to the specified document.
+The `revertDocumentChanges` method restores the active document from the original-document map, which is whatever `saveDocument` last wrote (or the document as it was first loaded into the workspace if it has never been saved).
 
 **Warning:** This operation will discard all unsaved changes to the specified document.
 
 ##### Complete Example
 
 ```ts
-const store = createWorkspaceStore({
-  documents: [
-    {
-      name: 'api',
-      document: {
-        openapi: '3.0.0',
-        info: { title: 'My API', version: '1.0.0' },
-        paths: {},
-      },
-    },
-  ],
+const store = createWorkspaceStore()
+await store.addDocument({
+  name: 'api',
+  document: {
+    openapi: '3.0.0',
+    info: { title: 'My API', version: '1.0.0' },
+    paths: {},
+  },
 })
 
 // Make some changes to the document
 store.workspace.documents['api'].info.title = 'Updated API Title'
 
-// This will restore the original title since we did not commit the changes yet
-store.revertDocumentChanges()
+// Restore the saved baseline since the changes were never saved
+await store.revertDocumentChanges('api')
 ```
 
 ### Workspace State Persistence
@@ -329,28 +337,25 @@ client.loadWorkspace(currentWorkspaceState)
 When you have a new or updated OpenAPI document and want to overwrite the existing one—regardless of which parts have changed—you can use the `replaceDocument` method. This method efficiently and atomically updates the entire document in place, ensuring that only the necessary changes are applied for optimal performance.
 
 ```ts
-const client = createWorkspaceStore({
-  documents: [
-    {
-      name: 'document-name',
-      document: {
-        openapi: '3.1.0',
-        info: {
-          title: 'Document Title',
-          version: '1.0.0',
-        },
-        paths: {},
-        components: {
-          schemas: {},
-        },
-        servers: [],
-      },
+const client = createWorkspaceStore()
+await client.addDocument({
+  name: 'document-name',
+  document: {
+    openapi: '3.1.0',
+    info: {
+      title: 'Document Title',
+      version: '1.0.0',
     },
-  ],
+    paths: {},
+    components: {
+      schemas: {},
+    },
+    servers: [],
+  },
 })
 
 // Update the document with the new changes
-client.replaceDocument('document-name', {
+await client.replaceDocument('document-name', {
   openapi: '3.1.0',
   info: {
     title: 'Updated Document',
@@ -370,13 +375,13 @@ Create the workspace from a specification object
 
 ```ts
 await store.importWorkspaceFromSpecification({
-  workspace: 'draft',
-  info: { title: 'My Workspace' },
-  documents: {
+  'workspace': 'draft',
+  'info': { title: 'My Workspace' },
+  'documents': {
     api: { $ref: '/examples/api.yaml' },
     petstore: { $ref: '/examples/petstore.yaml' },
   },
-  overrides: {
+  'overrides': {
     api: {
       servers: [
         {
@@ -414,10 +419,10 @@ await store.addDocument({
     servers: [
       {
         url: 'http://localhost:8080',
-        description: 'Default dev server'
-      }
-    ]
-  }
+        description: 'Default dev server',
+      },
+    ],
+  },
 })
 ```
 
@@ -425,13 +430,40 @@ When you override specific fields, those changes are applied only in-memory and
 
 ### Rebase document origin with the updated remote origin
 
-Rebases a document in the workspace with a new origin, resolving conflicts if provided.
+`rebaseDocument` reconciles a workspace document with a new upstream origin. It performs a two-way merge between:
+
+- the **incoming changes** — `diff(originalDocument, newOrigin)`
+- the **local changes** — `diff(originalDocument, activeDocument)`
+
+The call returns a discriminated result. On `ok: false` the `type` field describes why the rebase did not run (`CORRUPTED_STATE`, `FETCH_FAILED`, or `NO_CHANGES_DETECTED`). On `ok: true` it exposes the auto-mergeable `changes`, the `conflicts` that need user input, and an `applyChanges` callback that writes the merged result back into the workspace.
 
 ```ts
-// Example: Rebase a document with a new origin and resolve conflicts
-const conflicts = store.rebaseDocument('api', newOriginDoc)
-if (conflicts && conflicts.length > 0) {
-  // User resolves conflicts here...
-  store.rebaseDocument('api', newOriginDoc, userResolvedConflicts)
+// Fetch the latest origin and start a rebase
+const result = await store.rebaseDocument({
+  name: 'api',
+  // Any `WorkspaceDocumentInput` is accepted - inline document, url, or path
+  url: 'https://example.com/api/openapi.json',
+})
+
+if (!result.ok) {
+  console.warn(`Rebase did not run: ${result.type}`)
+  return
 }
-```
+
+if (result.conflicts.length === 0) {
+  // No conflicts - just apply with an empty resolution set
+  await result.applyChanges({ resolvedConflicts: [] })
+  return
+}
+
+// Surface the conflicts to the user. Each conflict is a tuple of
+// [incomingDiffs, localDiffs] - resolve by picking either side, or by
+// providing a fully resolved document.
+const resolvedConflicts = result.conflicts.flatMap(([incoming]) => incoming)
+await result.applyChanges({ resolvedConflicts })
+
+// Or, pass a complete document to use as-is (overrides the merge result):
+await result.applyChanges({ resolvedDocument: newDocument })
+```
+
+After `applyChanges` returns, the merged document becomes both the new active document and the new saved baseline, so a subsequent `revertDocumentChanges` rolls back to the post-rebase state rather than the pre-rebase original.

package/dist/client.d.ts

@@ -249,26 +249,36 @@ export type WorkspaceStore = {
      *
      * @param documentName - The name of the document to get the intermediate version of.
      * @returns The intermediate version of the document, or undefined if the document does not exist.
+     *
+     * @deprecated The intermediate document layer is being phased out. The
+     *   workspace store now keeps only two snapshots per document: the original
+     *   (last saved / loaded baseline) and the active in-memory state. Use
+     *   `getOriginalDocument` to read the saved baseline. The `intermediateDocuments`
+     *   map is no longer updated by `saveDocument` or `rebaseDocument` and only
+     *   reflects the document as it was first loaded into the workspace.
      */
     getIntermediateDocument(documentName: string): Record<string, unknown> | null;
     /**
-     * Saves the current state of the specified document to the intermediate documents map.
+     * Saves the current state of the specified document as the new baseline.
      *
-     * This function captures the latest (reactive) state of the document from the workspace and
-     * applies its changes to the corresponding entry in the `intermediateDocuments` map.
-     * The `intermediateDocuments` map represents the most recently "saved" local version of the document,
-     * which may include edits not yet synced to the remote registry.
+     * This function captures the latest (reactive) state of the document from
+     * the workspace and writes a deep clone of it back into the
+     * `originalDocuments` map - effectively promoting the in-memory state to
+     * the new "last saved" snapshot. After saving, `getOriginalDocument`
+     * returns the persisted edits and `revertDocumentChanges` rolls back to
+     * exactly this state.
      *
      * The update is performed in-place. A deep clone of the current document
-     * state is used to avoid mutating the reactive object directly.
+     * state is used to avoid mutating the reactive object directly. The
+     * dirty flag (`x-scalar-is-dirty`) is cleared on success.
      *
      * @param documentName - The name of the document to save.
-     * @returns An array of diffs that were excluded from being applied (such as changes to ignored keys),
-     *          or undefined if the document does not exist or cannot be updated.
+     * @returns `true` when the save succeeded, `false` if the document does
+     *          not exist or cannot be serialised back into the original map.
      *
      * @example
      * // Save the current state of the document named 'api'
-     * const isSuccess = store.saveDocument('api')
+     * const isSuccess = await store.saveDocument('api')
      * if (isSuccess) {
      *   console.log('Document saved successfully')
      * } else {
@@ -286,10 +296,11 @@ export type WorkspaceStore = {
     /**
      * Restores the specified document to its last locally saved state.
      *
-     * This method updates the current reactive document (in the workspace) with the contents of the
-     * corresponding intermediate document (from the `intermediateDocuments` map), effectively discarding
-     * any unsaved in-memory changes and reverting to the last saved version.
-     * Vue reactivity is preserved by updating the existing reactive object in place.
+     * This method updates the current reactive document (in the workspace)
+     * with the contents of the corresponding original document (from the
+     * `originalDocuments` map), effectively discarding any unsaved in-memory
+     * changes and reverting to the last saved version. Vue reactivity is
+     * preserved by updating the existing reactive object in place.
      *
      * **Warning:** This operation will discard all unsaved (in-memory) changes to the specified document.
      *
@@ -318,6 +329,12 @@ export type WorkspaceStore = {
      * } else {
      *   console.log('Intermediate document does not exist')
      * }
+     *
+     * @deprecated The intermediate document layer is being phased out.
+     *   `saveDocument` already writes directly to `originalDocuments`, so this
+     *   method has no remaining responsibility once the intermediate map stops
+     *   being updated. It is kept for API compatibility and will be removed in
+     *   a future release.
      */
     promoteIntermediateToOriginal(documentName: string): boolean;
     /**

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

@@ -101,6 +101,40 @@ const METADATA_ONLY_DOCUMENT_KEYS = new Set([
     // conflict cache).
     'x-scalar-registry-meta',
 ]);
+/**
+ * Removes internal and metadata keys from the provided document object.
+ *
+ * This function deletes a list of known internal keys that are only meant for
+ * in-memory/document processing use and should not be present in the final bundled document.
+ * Most of these keys are injected by the bundler or used for Scalar OpenAPI document state tracking.
+ *
+ * Note: Nested internal keys are handled elsewhere in the bundler pipeline.
+ *
+ * @param document - The OpenAPI document object to be sanitized in-place.
+ */
+const purgeInternalDocumentKeys = (input) => {
+    const result = deepClone(input);
+    // Top level keys that need to be excluded from the original document
+    // Nested keys are removed during the previous step of the bundler process
+    const EXCLUDE_KEYS = [
+        // Bundler metadata fields added temporarily during document processing
+        'x-ext',
+        'x-ext-urls',
+        // Scalar internal/external metadata fields
+        'x-scalar-navigation',
+        'x-scalar-is-dirty',
+        'x-original-oas-version',
+        'x-scalar-original-document-hash',
+        'x-scalar-original-source-url',
+        'x-scalar-registry-meta',
+    ];
+    // Remove top-level properties that should only exist temporarily or for internal usage
+    // These properties are used for internal purposes and are not needed in the final bundled document
+    for (const property of EXCLUDE_KEYS) {
+        delete result[property];
+    }
+    return result;
+};
 /**
  * Creates a reactive workspace store that manages documents and their metadata.
  * The store provides functionality for accessing, updating, and resolving document references.
@@ -351,20 +385,27 @@ export const createWorkspaceStore = (workspaceProps) => {
         return workspace[extensions.workspace.activeDocument] ?? Object.keys(workspace.documents)[0] ?? '';
     }
     function exportDocument(documentName, format, minify) {
-        const intermediateDocument = intermediateDocuments[documentName];
-        if (!intermediateDocument) {
+        // The original document map now holds the most recently saved state of
+        // the document - `saveDocument` writes directly into it and
+        // `revertDocumentChanges` reads from it. Exporting therefore mirrors
+        // exactly what the user would get if they reverted to the last save.
+        const savedDocument = originalDocuments[documentName];
+        if (!savedDocument) {
             return;
         }
         if (format === 'json') {
-            return minify ? JSON.stringify(intermediateDocument) : JSON.stringify(intermediateDocument, null, 2);
+            return minify ? JSON.stringify(savedDocument) : JSON.stringify(savedDocument, null, 2);
         }
-        return YAML.stringify(intermediateDocument);
+        return YAML.stringify(savedDocument);
     }
-    // Save the current state of the specified document to the intermediate documents map.
-    // This function captures the latest (reactive) state of the document from the workspace and
-    // applies its changes to the corresponding entry in the `intermediateDocuments` map.
-    // The `intermediateDocuments` map represents the most recently "saved" local version of the document,
-    // which may include edits not yet synced to the remote registry.
+    // Save the current state of the specified document as the new baseline.
+    // The reactive workspace document is serialised back into a plain shape
+    // (with bundler-internal keys stripped) and stored under
+    // `originalDocuments[documentName]` - the original map is now the single
+    // source of truth for "what the user has saved". The intermediate map is
+    // deprecated, but we keep mirroring writes into it so any consumer still
+    // reading from `getIntermediateDocument` observes fresh content while
+    // the layer is being phased out.
     const saveDocument = async (documentName) => {
         const activeDocument = workspace.documents[documentName];
         const newDocument = await getEditableDocument(documentName);
@@ -372,15 +413,19 @@ export const createWorkspaceStore = (workspaceProps) => {
             console.warn('Failed to save document, active document is missing');
             return false;
         }
-        // Store the new document in the intermediate documents map
-        intermediateDocuments[documentName] = newDocument;
+        // Promote the in-memory edits to the new saved baseline. Two stores
+        // get a deep clone each so subsequent mutations on either one stay
+        // isolated.
+        originalDocuments[documentName] = newDocument;
+        intermediateDocuments[documentName] = deepClone(newDocument);
         // Mark the document as not dirty since we are saving it
         activeDocument['x-scalar-is-dirty'] = false;
         return true;
     };
     // Add a document to the store synchronously from an in-memory OpenAPI document
     async function addInMemoryDocument(input, navigationOptions) {
-        const { name, meta } = input;
+        const { name } = input;
+        const meta = deepClone(input.meta);
         const clonedRawInputDocument = withMeasurementSync('deepClone', () => deepClone(input.document));
         withMeasurementSync('initialize', () => {
             if (input.initialize !== false) {
@@ -524,17 +569,18 @@ export const createWorkspaceStore = (workspaceProps) => {
         return rawDocument;
     };
     /**
-     * Promotes the intermediate document to the original document so the current
-     * intermediate becomes the new baseline. Fires workspace change for persistence.
+     * Promotes the intermediate document to the original document so the
+     * current intermediate becomes the new baseline.
+     *
+     * The intermediate layer is deprecated: `saveDocument` now writes
+     * directly into `originalDocuments`, so by the time anyone could call
+     * this method the original map already holds the latest saved baseline.
+     * Copying the (now stale) intermediate over the original would clobber
+     * the user's save, so this is a no-op for existing documents and only
+     * reports `false` when the document does not exist at all.
      */
     const promoteIntermediateToOriginal = (documentName) => {
-        const intermediate = intermediateDocuments[documentName];
-        if (!intermediate) {
-            return false;
-        }
-        const cloned = deepClone(unpackProxyObject(intermediate, { depth: 1 }));
-        originalDocuments[documentName] = cloned;
-        return true;
+        return Boolean(intermediateDocuments[documentName]);
     };
     /**
      * Retrieves an editable clone of a workspace document.
@@ -558,25 +604,7 @@ export const createWorkspaceStore = (workspaceProps) => {
             treeShake: false,
             urlMap: true,
         }));
-        // Top level keys that need to be excluded from the original document
-        // Nested keys are removed buring the previous step of the bundler process
-        const EXCLUDE_KEYS = [
-            // Bundler metadata fields added temporarily during document processing
-            'x-ext',
-            'x-ext-urls',
-            // Scalar internal/external metadata fields
-            'x-scalar-navigation',
-            'x-scalar-is-dirty',
-            'x-original-oas-version',
-            'x-scalar-original-document-hash',
-            'x-scalar-original-source-url',
-        ];
-        // Remove top level properties that should only exist in memory for the original document
-        // These properties are used for internal purposes and are not needed in the final bundled document
-        for (const property of EXCLUDE_KEYS) {
-            delete original[property];
-        }
-        return original;
+        return purgeInternalDocumentKeys(original);
     };
     /**
      * Builds (or updates) the navigation sidebar for the specified document.
@@ -634,7 +662,8 @@ export const createWorkspaceStore = (workspaceProps) => {
             return true;
         },
         async replaceDocument(documentName, input) {
-            const currentDocument = workspace.documents[documentName];
+            // Used to preserve the original metadata of the document (we need to unpack so we don't store a proxy object)
+            const currentDocument = unpackProxyObject(workspace.documents[documentName], { depth: 1 });
             if (!currentDocument) {
                 return console.error(`Document '${documentName}' does not exist in the workspace.`);
             }
@@ -646,6 +675,8 @@ export const createWorkspaceStore = (workspaceProps) => {
                 documentSource: currentDocument['x-scalar-original-source-url'],
                 documentHash: currentDocument['x-scalar-original-document-hash'],
                 meta: {
+                    // Preserve the registry meta
+                    'x-scalar-registry-meta': currentDocument['x-scalar-registry-meta'],
                     // Set the document as dirty
                     'x-scalar-is-dirty': true,
                     // Clear the navigation to trigger a rebuild
@@ -711,17 +742,30 @@ export const createWorkspaceStore = (workspaceProps) => {
         saveDocument,
         promoteIntermediateToOriginal,
         async revertDocumentChanges(documentName) {
-            const workspaceDocument = workspace.documents[documentName];
-            const intermediate = intermediateDocuments[documentName];
-            if (!workspaceDocument || !intermediate) {
+            // Used to preserve the original metadata of the document (we need to unpack so we don't store a proxy object)
+            const workspaceDocument = unpackProxyObject(workspace.documents[documentName], { depth: 1 });
+            // Restore from the original (last saved) snapshot. `saveDocument`
+            // writes here, so this reliably rolls back to whatever the user
+            // last persisted - matching the soft-deprecation path away from the
+            // intermediate document layer.
+            const baseline = unpackProxyObject(originalDocuments[documentName], { depth: 1 });
+            if (!workspaceDocument || !baseline) {
                 return;
             }
+            // Keep the deprecated intermediate map aligned with the original so
+            // any consumer still reading from `getIntermediateDocument` sees the
+            // post-revert state instead of the pre-revert one.
+            intermediateDocuments[documentName] = deepClone(baseline);
             await addInMemoryDocument({
                 name: documentName,
-                document: intermediate,
+                document: baseline,
                 documentSource: workspaceDocument['x-scalar-original-source-url'],
                 documentHash: workspaceDocument['x-scalar-original-document-hash'],
                 initialize: false,
+                meta: {
+                    // Preserve the registry meta
+                    'x-scalar-registry-meta': workspaceDocument['x-scalar-registry-meta'],
+                },
             });
         },
         commitDocument(documentName) {
@@ -770,18 +814,21 @@ export const createWorkspaceStore = (workspaceProps) => {
         rebaseDocument: async (input) => {
             const { name } = input;
             // ---- Get the current documents
+            // The intermediate snapshot has been deprecated. Rebase now reasons
+            // about exactly two local snapshots: the original (last saved
+            // baseline, written by `saveDocument`) and the active in-memory
+            // document (with any unsaved edits on top).
             const originalDocument = unpackProxyObject(originalDocuments[name], { depth: 1 });
-            const intermediateDocument = unpackProxyObject(intermediateDocuments[name], { depth: 1 });
             // raw version without any proxies
-            const activeDocument = workspace.documents[name]
-                ? unpackProxyObject(workspace.documents[name], { depth: 1 })
-                : undefined;
-            if (!originalDocument || !intermediateDocument || !activeDocument) {
+            const activeDocumentRaw = unpackProxyObject(workspace.documents[name], { depth: 1 });
+            // editable version of the document (reversing bundling and also remove internal metadata)
+            const activeDocument = await getEditableDocument(name);
+            if (!originalDocument || !activeDocument || !activeDocumentRaw) {
                 // If any required document state is missing, do nothing
                 return {
                     ok: false,
                     type: 'CORRUPTED_STATE',
-                    message: `Cannot rebase document '${name}': missing original, intermediate, or active document state`,
+                    message: `Cannot rebase document '${name}': missing original or active document state`,
                 };
             }
             // ---- Resolve input document
@@ -800,7 +847,7 @@ export const createWorkspaceStore = (workspaceProps) => {
             // Compare document hashes to see if the document has changed
             // When the hashes match, we can skip the rebase process
             const newHash = generateHash(resolve.raw);
-            if (activeDocument['x-scalar-original-document-hash'] === newHash) {
+            if (activeDocumentRaw['x-scalar-original-document-hash'] === newHash) {
                 return {
                     ok: false,
                     type: 'NO_CHANGES_DETECTED',
@@ -811,46 +858,67 @@ export const createWorkspaceStore = (workspaceProps) => {
             // ---- Override the configurations and metadata
             overrides[name] = input.overrides ?? {};
             extraDocumentConfigurations[name] = { fetch: input.fetch };
-            // ---- Get the new intermediate document
-            const changelogAA = diff(originalDocument, newDocumentOrigin);
+            // ---- Compute the merge between upstream and local edits
+            // Two-way merge anchored on the original (last saved) snapshot:
+            //   - changelogIncoming: changes the registry made on top of the
+            //     original (what we want to pull in)
+            //   - changelogLocal: changes the user has made on top of the
+            //     original since the last save (what we want to keep)
+            const changelogIncoming = diff(originalDocument, newDocumentOrigin);
             // When there are no changes, we can return early since we don't need to do anything
             // This is not supposed to happen due to the hash check above, but just in case
-            if (changelogAA.length === 0) {
+            if (changelogIncoming.length === 0) {
                 return {
                     ok: false,
                     type: 'NO_CHANGES_DETECTED',
                     message: `No changes detected for document '${name}' after fetching the latest version.`,
                 };
             }
-            const changelogAB = diff(originalDocument, intermediateDocument);
-            const changesA = merge(changelogAA, changelogAB);
+            const changelogLocal = diff(originalDocument, activeDocument);
+            const merged = merge(changelogIncoming, changelogLocal);
             return {
                 ok: true,
-                conflicts: changesA.conflicts,
-                changes: changesA.diffs,
+                conflicts: merged.conflicts,
+                changes: merged.diffs,
                 applyChanges: async (applyChangesInput) => {
-                    // Helper function to compute the new intermediate document based on resolved conflicts or a resolved document
-                    const getNewIntermediateDocument = () => {
+                    // Helper function to compute the new active document based on
+                    // resolved conflicts or a resolved document. With the
+                    // intermediate layer gone, the merged result *is* the new
+                    // active document - there is no longer an intermediate hop.
+                    const getNewActiveDocument = () => {
                         if ('resolvedConflicts' in applyChangesInput) {
-                            const changesetA = changesA.diffs.concat(applyChangesInput.resolvedConflicts);
+                            const changeset = merged.diffs.concat(applyChangesInput.resolvedConflicts);
                             // Apply the merged changes (diffs + resolved conflicts) to the original document
-                            return apply(deepClone(originalDocument), changesetA);
+                            return apply(deepClone(originalDocument), changeset);
                         }
-                        // If there are no resolved conflicts, use the provided resolved document
+                        // If the caller provided a fully resolved document, use it as-is.
                         return applyChangesInput.resolvedDocument;
                     };
-                    const newIntermediateDocument = getNewIntermediateDocument();
-                    intermediateDocuments[name] = newIntermediateDocument;
-                    // Update the original document
-                    originalDocuments[name] = newDocumentOrigin;
-                    // ---- Get the new active document
-                    const changelogBA = diff(intermediateDocument, newIntermediateDocument);
-                    const changelogBB = diff(intermediateDocument, activeDocument);
-                    const changesB = merge(changelogBA, changelogBB);
-                    // Auto-conflict resolution: pick only the changes from the first changeset
-                    // TODO: In the future, implement smarter conflict resolution if needed
-                    const changesetB = changesB.diffs.concat(changesB.conflicts.flatMap((it) => it[0]));
-                    const newActiveDocument = coerceValue(OpenAPIDocumentSchemaStrict, apply(deepClone(newIntermediateDocument), changesetB));
+                    const mergedDocument = getNewActiveDocument();
+                    const newActiveDocument = coerceValue(OpenAPIDocumentSchemaStrict, mergedDocument);
+                    // Detect whether the rebase folded in any local edits. When the
+                    // merged result matches the upstream snapshot the pull was
+                    // effectively a fast-forward (no unsaved local work to carry
+                    // over), so the document is clean relative to the registry.
+                    // When it differs we still hold unpushed changes locally - flag
+                    // the document as dirty so the push flow can surface them, the
+                    // same way `git pull --rebase` leaves you "ahead of origin"
+                    // once your local commits get replayed on top.
+                    //
+                    // We compare the pre-coerce merged document against upstream
+                    // because `coerceValue` normalises the merged result against
+                    // the strict schema and that normalisation can introduce diffs
+                    // even for pure fast-forwards. The merged document is what the
+                    // two-way merge actually produced, so its byte-for-byte equality
+                    // with upstream is the real fast-forward signal.
+                    const hasLocalChangesAgainstUpstream = diff(newDocumentOrigin, mergedDocument).length > 0;
+                    // The merged result becomes the new saved baseline so a subsequent
+                    // revert restores to the post-rebase state, not to the
+                    // pre-rebase original. Mirror the same content into the
+                    // deprecated intermediate map so any lingering consumer reads
+                    // the post-rebase state too.
+                    originalDocuments[name] = newActiveDocument;
+                    intermediateDocuments[name] = deepClone(newActiveDocument);
                     // add the new active document to the workspace but don't re-initialize
                     await addInMemoryDocument({
                         ...input,
@@ -864,6 +932,13 @@ export const createWorkspaceStore = (workspaceProps) => {
                         // Update the original document hash
                         documentHash: generateHash(resolve.raw),
                         initialize: false,
+                        meta: {
+                            ...input.meta,
+                            // Preserve the registry meta
+                            'x-scalar-registry-meta': activeDocumentRaw['x-scalar-registry-meta'],
+                            // Flag local edits that need pushing - see note above.
+                            'x-scalar-is-dirty': hasLocalChangesAgainstUpstream,
+                        },
                     });
                 },
             };

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":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAwf1E,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,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9C,CAAA;AAeD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,YAAY,EACpB,UAAU,2BAA2B,EACrC,mDAMG,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;CACrB,CAAM,KACN,OAiKF,CAAA"}
+{"version":3,"file":"get-example-from-schema.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-example-from-schema.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAsnB1E,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,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9C,CAAA;AAeD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,YAAY,EACpB,UAAU,2BAA2B,EACrC,mDAMG,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;CACrB,CAAM,KACN,OAqKF,CAAA"}

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

@@ -172,6 +172,105 @@ const mergeExamples = (baseValue, newValue) => {
     }
     return newValue;
 };
+const MAX_SCHEMA_VALIDATION_DEPTH = MAX_LEVELS_DEEP * 5;
+/** Cache composed schema resolution to preserve identity across recursion checks. */
+const composedSchemaResolutionCache = new WeakMap();
+const isValueOfType = (value, targetType) => {
+    switch (targetType) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && !Number.isNaN(value);
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'object':
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'null':
+            return value === null;
+        default:
+            return false;
+    }
+};
+const resolveComposedSchemaMember = (schema) => {
+    const rawSchema = getSchemaCacheTarget(schema);
+    if (composedSchemaResolutionCache.has(rawSchema)) {
+        return composedSchemaResolutionCache.get(rawSchema);
+    }
+    const resolved = '$ref' in schema ? resolve.schema(schema) : schema;
+    composedSchemaResolutionCache.set(rawSchema, resolved);
+    return resolved;
+};
+const schemaAllowsValue = (schema, value, seen = new Set(), level = 0) => {
+    // Depth guard prevents stack overflows when composed schemas loop through wrapped resolver objects.
+    if (level > MAX_SCHEMA_VALIDATION_DEPTH) {
+        return true;
+    }
+    const rawSchema = getSchemaCacheTarget(schema);
+    if (seen.has(rawSchema)) {
+        return true;
+    }
+    seen.add(rawSchema);
+    if ('type' in schema && schema.type) {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        const matchesType = types.some((targetType) => {
+            if (targetType === 'number' && isValueOfType(value, 'integer')) {
+                return true;
+            }
+            return isValueOfType(value, targetType);
+        });
+        if (!matchesType) {
+            seen.delete(rawSchema);
+            return false;
+        }
+    }
+    const anyOf = schema.anyOf;
+    if (Array.isArray(anyOf) && anyOf.length > 0) {
+        const matchesAnyOf = anyOf.some((item) => {
+            const resolved = resolveComposedSchemaMember(item);
+            return !!resolved && schemaAllowsValue(resolved, value, seen, level + 1);
+        });
+        if (!matchesAnyOf) {
+            seen.delete(rawSchema);
+            return false;
+        }
+    }
+    const oneOf = schema.oneOf;
+    if (Array.isArray(oneOf) && oneOf.length > 0) {
+        const matchesOneOf = oneOf.some((item) => {
+            const resolved = resolveComposedSchemaMember(item);
+            return !!resolved && schemaAllowsValue(resolved, value, seen, level + 1);
+        });
+        if (!matchesOneOf) {
+            seen.delete(rawSchema);
+            return false;
+        }
+    }
+    const allOf = schema.allOf;
+    if (Array.isArray(allOf) && allOf.length > 0) {
+        const matchesAllOf = allOf.every((item) => {
+            const resolved = resolveComposedSchemaMember(item);
+            return !resolved || schemaAllowsValue(resolved, value, seen, level + 1);
+        });
+        if (!matchesAllOf) {
+            seen.delete(rawSchema);
+            return false;
+        }
+    }
+    seen.delete(rawSchema);
+    return true;
+};
+const INVALID_DEFAULT = Symbol('INVALID_DEFAULT');
+const normalizeSchemaDefault = (schema) => {
+    const defaultValue = schema.default;
+    if (schemaAllowsValue(schema, defaultValue)) {
+        return defaultValue;
+    }
+    return INVALID_DEFAULT;
+};
 const getCompositionSelectionKey = (schemaPath, composition) => [...schemaPath, composition].join('.');
 const getCompositionSelectionIndex = (schemaPath, composition, options, length) => {
     const rawIndex = options?.compositionSelection?.[getCompositionSelectionKey(schemaPath, composition)];
@@ -477,8 +576,11 @@ export const getExampleFromSchema = (schema, options, { level = 0, parentSchema,
         return cache(_schema, _schema.example, cacheKey);
     }
     if (_schema.default !== undefined) {
-        seen.delete(targetValue);
-        return cache(_schema, _schema.default, cacheKey);
+        const normalizedDefault = normalizeSchemaDefault(_schema);
+        if (normalizedDefault !== INVALID_DEFAULT) {
+            seen.delete(targetValue);
+            return cache(_schema, normalizedDefault, cacheKey);
+        }
     }
     if (_schema.const !== undefined) {
         seen.delete(targetValue);

package/dist/request-example/types.d.ts

@@ -1,11 +1,10 @@
 import type { HttpMethod } from '@scalar/helpers/http/http-methods';
-export type Result<T> = {
-    ok: true;
-    data: T;
-} | {
-    ok: false;
-    error: string;
-};
+/**
+ * Re-exported from `@scalar/helpers/types/result` so the rest of the
+ * workspace-store codebase keeps importing `Result` from a colocated
+ * module while the canonical definition lives in helpers.
+ */
+export type { Result } from '@scalar/helpers/types/result';
 export type RequestExampleMeta = {
     path: string;
     method: HttpMethod;

package/dist/request-example/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/request-example/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,MAAM,MAAM,MAAM,CAAC,CAAC,IAChB;IACE,EAAE,EAAE,IAAI,CAAA;IACR,IAAI,EAAE,CAAC,CAAA;CACR,GACD;IACE,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAEL,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/request-example/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE;;;;GAIG;AACH,YAAY,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAA;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA"}

package/package.json

@@ -16,7 +16,7 @@
     "openapi",
     "scalar"
   ],
-  "version": "0.49.1",
+  "version": "0.49.2",
   "engines": {
     "node": ">=22"
   },
@@ -143,12 +143,12 @@
     "type-fest": "^5.3.1",
     "vue": "^3.5.30",
     "yaml": "^2.8.3",
-    "@scalar/json-magic": "0.12.11",
-    "@scalar/helpers": "0.5.5",
-    "@scalar/openapi-upgrader": "0.2.7",
+    "@scalar/helpers": "0.6.0",
+    "@scalar/json-magic": "0.12.12",
+    "@scalar/snippetz": "0.9.6",
     "@scalar/validation": "0.3.2",
-    "@scalar/types": "0.9.5",
-    "@scalar/snippetz": "0.9.5"
+    "@scalar/types": "0.9.6",
+    "@scalar/openapi-upgrader": "0.2.7"
   },
   "devDependencies": {
     "@google-cloud/storage": "7.16.0",