@scalar/workspace-store 0.10.2 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @scalar/workspace-store
 
+## 0.12.0
+
+### Minor Changes
+
+- 952bde2: feat(json-magic): move json tooling to the new package
+- ae8d1b9: feat(workspace-store): rebase document origin with a remote origin
+- 2888e18: feat(openapi-parser): partial bundle to a depth
+
+### Patch Changes
+
+- 5301a80: feat: make content reactive and update workspace store
+- 8199955: fix(workspace-store): never write overrides back to the intermediate state
+- Updated dependencies [952bde2]
+- Updated dependencies [2888e18]
+  - @scalar/openapi-parser@0.19.0
+  - @scalar/json-magic@0.1.0
+
+## 0.11.0
+
+### Minor Changes
+
+- 9924c47: feat(workspace-store): support replacing the whole document
+- a0c92d9: feat(workspace-store): create store from workspace specification object
+
+### Patch Changes
+
+- a5534e6: fix: show path parameters on operation
+- 6b6c72c: fix: hiddenClients: true and move clients to workspace store
+- Updated dependencies [ccf875a]
+- Updated dependencies [d4cb86b]
+- Updated dependencies [94d6d0c]
+- Updated dependencies [c345d2c]
+- Updated dependencies [c0d6793]
+- Updated dependencies [f3d0216]
+  - @scalar/openapi-types@0.3.7
+  - @scalar/types@0.2.11
+  - @scalar/code-highlight@0.1.9
+  - @scalar/openapi-parser@0.18.3
+  - @scalar/helpers@0.0.7
+
 ## 0.10.2
 
 ### Patch Changes

package/README.md

@@ -196,7 +196,7 @@ const store = createWorkspaceStore({
 })
 
 // Add another OpenAPI document to the workspace
-store.addDocumentSync({
+await store.addDocument({
   document: {
     info: {
       title: 'OpenApi document',
@@ -261,7 +261,7 @@ const store = createWorkspaceStore({
 You can override specific document configuration when you add the document to the store
 
 ```ts
-store.addDocumentSync({
+await store.addDocument({
   name: 'example',
   document: {
     openapi: '3.0.0',
@@ -276,7 +276,7 @@ store.addDocumentSync({
 })
 ```
 
-To get the active document configuration you can use config getter\
+To get the active document configuration you can use config getter
 
 ```ts
 // Get the configuration for the active document
@@ -368,4 +368,116 @@ const currentWorkspaceState = client.exportWorkspace()
 
 // Reload the workspace state
 client.loadWorkspace(currentWorkspaceState)
+```
+
+### Replace the Entire Document
+
+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: [],
+      },
+    },
+  ],
+})
+
+// Update the document with the new changes
+client.replaceDocument('document-name', {
+  openapi: '3.1.0',
+  info: {
+    title: 'Updated Document',
+    version: '1.0.0',
+  },
+  paths: {},
+  components: {
+    schemas: {},
+  },
+  servers: [],
+})
+```
+
+### Create workspace from specification
+
+Create the workspace from a specification object
+
+```ts
+await store.importWorkspaceFromSpecification({
+  workspace: 'draft',
+  info: { title: 'My Workspace' },
+  documents: {
+    api: { $ref: '/examples/api.yaml' },
+    petstore: { $ref: '/examples/petstore.yaml' },
+  },
+  overrides: {
+    api: {
+      servers: [
+        {
+          url: 'http://localhost:9090',
+        },
+      ],
+    },
+  },
+  'x-scalar-dark-mode': true,
+})
+```
+
+### Override specific fields from the document and it's metadata
+
+This feature is helpful when you want to override specific fields in a document without altering the original source. Overrides allow you to customize certain values in-memory, ensuring the original document remains unchanged.
+
+```ts
+const store = createWorkspaceStore()
+await store.addDocument({
+  name: 'default',
+  document: {
+    openapi: '3.1.0',
+    info: {
+      title: 'Document Title',
+      version: '1.0.0',
+    },
+    paths: {},
+    components: {
+      schemas: {},
+    },
+    servers: [],
+  },
+  // Override the servers field
+  overrides: {
+    servers: [
+      {
+        url: 'http://localhost:8080',
+        description: 'Default dev server'
+      }
+    ]
+  }
+})
+```
+
+When you override specific fields, those changes are applied only in-memory and will never be written back to the original document. The original source remains unchanged, and any modifications made through overrides are isolated to the current session.
+
+### Rebase document origin with the updated remote origin
+
+Rebases a document in the workspace with a new origin, resolving conflicts if provided.
+
+```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)
+}
 ```

package/dist/client.d.ts

@@ -1,7 +1,10 @@
+import type { DeepPartial, DeepRequired } from './types.js';
 import { type createNavigationOptions } from './navigation/index.js';
-import type { Workspace, WorkspaceDocumentMeta, WorkspaceMeta } from './schemas/workspace.js';
+import { type OpenApiDocument } from './schemas/v3.1/strict/openapi-document.js';
 import type { Config } from './schemas/workspace-specification/config.js';
-import type { DeepTransform } from './types.js';
+import type { WorkspaceSpecification } from './schemas/workspace-specification/index.js';
+import type { Workspace, WorkspaceDocumentMeta, WorkspaceMeta } from './schemas/workspace.js';
+import { merge, type Difference } from '@scalar/json-magic/diff';
 /**
  * Input type for workspace document metadata and configuration.
  * This type defines the required and optional fields for initializing a document in the workspace.
@@ -15,6 +18,8 @@ type WorkspaceDocumentMetaInput = {
     name: string;
     /** Optional configuration for generating navigation structure */
     config?: Config & Partial<createNavigationOptions>;
+    /** Overrides for the document */
+    overrides?: DeepPartial<OpenApiDocument>;
 };
 /**
  * Represents a document that is loaded from a URL.
@@ -37,7 +42,7 @@ export type ObjectDoc = {
  * - ObjectDoc: Direct document object with metadata
  */
 export type WorkspaceDocumentInput = UrlDoc | ObjectDoc;
-declare const defaultConfig: DeepTransform<Config, 'NonNullable'>;
+declare const defaultConfig: DeepRequired<Config>;
 /**
  * Configuration object for initializing a workspace store.
  * Defines the initial state and documents for the workspace.
@@ -45,8 +50,6 @@ declare const defaultConfig: DeepTransform<Config, 'NonNullable'>;
 type WorkspaceProps = {
     /** Optional metadata for the workspace including theme, active document, etc */
     meta?: WorkspaceMeta;
-    /** In-mem open api documents. Async source documents (like URLs) can be loaded after initialization */
-    documents?: ObjectDoc[];
     /** Workspace configuration */
     config?: Config;
 };
@@ -63,12 +66,12 @@ export type WorkspaceStore = {
     update<K extends keyof WorkspaceMeta>(key: K, value: WorkspaceMeta[K]): void;
     /** Updates a specific metadata field in a document */
     updateDocument<K extends keyof WorkspaceDocumentMeta>(name: 'active' | (string & {}), key: K, value: WorkspaceDocumentMeta[K]): void;
+    /** Replaces the content of a specific document in the workspace with the provided input */
+    replaceDocument(documentName: string, input: Record<string, unknown>): void;
     /** Resolves a reference in the active document by following the provided path and resolving any external $ref references */
     resolve(path: string[]): Promise<unknown>;
     /** Adds a new document to the workspace */
     addDocument(input: WorkspaceDocumentInput): Promise<void>;
-    /** Similar to addDocument but requires and in-mem object to be provided and loads the document synchronously */
-    addDocumentSync(input: ObjectDoc): void;
     /** Returns the merged configuration for the active document */
     readonly config: typeof defaultConfig;
     /** Downloads the specified document in the requested format */
@@ -83,6 +86,10 @@ export type WorkspaceStore = {
     exportWorkspace(): string;
     /** Imports a workspace from a serialized JSON string. */
     loadWorkspace(input: string): void;
+    /** Imports a workspace from a specification object */
+    importWorkspaceFromSpecification(specification: WorkspaceSpecification): Promise<void[]>;
+    /** Rebase document with a remote origin */
+    rebaseDocument: (documentName: string, newDocumentOrigin: Record<string, unknown>, resolvedConflicts?: Difference[]) => void | ReturnType<typeof merge>['conflicts'];
 };
 /**
  * Creates a reactive workspace store that manages documents and their metadata.

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":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAKxD,OAAO,EAAoB,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAG7E,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAEpG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0CAA0C,CAAA;AAEtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAA;AAE/E,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAG1F,OAAO,EAAe,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAE7E;;;;;GAKG;AACH,KAAK,0BAA0B,GAAG;IAChC,wEAAwE;IACxE,IAAI,CAAC,EAAE,qBAAqB,CAAA;IAC5B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;IAClD,iCAAiC;IACjC,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,CAAA;CACzC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAA;IACX,wIAAwI;IACxI,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC5F,GAAG,0BAA0B,CAAA;AAE9B,iGAAiG;AACjG,MAAM,MAAM,SAAS,GAAG;IACtB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC,GAAG,0BAA0B,CAAA;AAE9B;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,CAAA;AAEvD,QAAA,MAAM,aAAa,EAAE,YAAY,CAAC,MAAM,CAEvC,CAAA;AAiCD;;;GAGG;AACH,KAAK,cAAc,GAAG;IACpB,gFAAgF;IAChF,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,yDAAyD;IACzD,MAAM,CAAC,CAAC,SAAS,MAAM,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAC5E,sDAAsD;IACtD,cAAc,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAClD,IAAI,EAAE,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC9B,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAAA;IACP,2FAA2F;IAC3F,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3E,4HAA4H;IAC5H,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzC,2CAA2C;IAC3C,WAAW,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAA;IACrC,+DAA+D;IAC/D,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACjF,8FAA8F;IAC9F,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACzD,2DAA2D;IAC3D,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACjD,qCAAqC;IACrC,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1C,mGAAmG;IACnG,eAAe,IAAI,MAAM,CAAA;IACzB,yDAAyD;IACzD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,sDAAsD;IACtD,gCAAgC,CAAC,aAAa,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IACxF,2CAA2C;IAC3C,cAAc,EAAE,CACd,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,iBAAiB,CAAC,EAAE,UAAU,EAAE,KAC7B,IAAI,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,WAAW,CAAC,CAAA;CAClD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,oBAAqB,cAAc,KAAG,cAolBtE,CAAA;AAGD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA"}

package/dist/client.js

@@ -1,18 +1,21 @@
-import { bundle, upgrade } from "@scalar/openapi-parser";
-import { fetchUrls } from "@scalar/openapi-parser/plugins-browser";
-import { reactive, toRaw } from "vue";
 import YAML from "yaml";
+import { reactive } from "vue";
+import { upgrade } from "@scalar/openapi-parser";
+import { createMagicProxy, getRaw } from "@scalar/json-magic/magic-proxy";
 import { applySelectiveUpdates } from "./helpers/apply-selective-updates.js";
 import { deepClone, isObject, safeAssign } from "./helpers/general.js";
 import { getValueByPath } from "./helpers/json-path-utils.js";
 import { mergeObjects } from "./helpers/merge-object.js";
-import { createMagicProxy, getRaw } from "./helpers/proxy.js";
 import { createNavigation } from "./navigation/index.js";
 import { extensions } from "./schemas/extensions.js";
-import { InMemoryWorkspaceSchema } from "./schemas/inmemory-workspace.js";
-import { defaultReferenceConfig } from "./schemas/reference-config/index.js";
 import { coerceValue } from "./schemas/typebox-coerce.js";
 import { OpenAPIDocumentSchema } from "./schemas/v3.1/strict/openapi-document.js";
+import { defaultReferenceConfig } from "./schemas/reference-config/index.js";
+import { InMemoryWorkspaceSchema } from "./schemas/inmemory-workspace.js";
+import { createOverridesProxy } from "./helpers/overrides-proxy.js";
+import { bundle } from "@scalar/json-magic/bundle";
+import { fetchUrls } from "@scalar/json-magic/bundle/plugins/browser";
+import { apply, diff, merge } from "@scalar/json-magic/diff";
 const defaultConfig = {
   "x-scalar-reference-config": defaultReferenceConfig
 };
@@ -29,6 +32,7 @@ const createWorkspaceStore = (workspaceProps) => {
   const originalDocuments = {};
   const intermediateDocuments = {};
   const documentConfigs = {};
+  const overrides = {};
   const workspace = reactive({
     ...workspaceProps?.meta,
     documents: {},
@@ -47,18 +51,63 @@ const createWorkspaceStore = (workspaceProps) => {
   function getActiveDocumentName() {
     return workspace[extensions.workspace.activeDocument] ?? Object.keys(workspace.documents)[0] ?? "";
   }
-  function addDocumentSync(input) {
+  function saveDocument(documentName) {
+    const intermediateDocument = intermediateDocuments[documentName];
+    const workspaceDocument = workspace.documents[documentName];
+    if (!workspaceDocument) {
+      return;
+    }
+    const updatedDocument = getRaw(workspaceDocument);
+    if (!intermediateDocument || !updatedDocument) {
+      return;
+    }
+    const excludedDiffs = applySelectiveUpdates(intermediateDocument, updatedDocument);
+    return excludedDiffs;
+  }
+  async function addInMemoryDocument(input) {
     const { name, meta } = input;
     const document = coerceValue(OpenAPIDocumentSchema, upgrade(input.document).specification);
     originalDocuments[name] = deepClone({ ...document, ...meta });
     intermediateDocuments[name] = deepClone({ ...document, ...meta });
     documentConfigs[name] = input.config ?? {};
+    overrides[name] = input.overrides ?? {};
     if (document[extensions.document.navigation] === void 0) {
       document[extensions.document.navigation] = createNavigation(document, input.config ?? {}).entries;
     }
-    workspace.documents[name] = createMagicProxy({ ...document, ...meta });
+    if (document[extensions.document.navigation] === void 0) {
+      await bundle(input.document, { treeShake: false, plugins: [fetchUrls()] });
+    }
+    workspace.documents[name] = createOverridesProxy(createMagicProxy({ ...document, ...meta }), input.overrides);
+  }
+  async function addDocument(input) {
+    const { name, meta } = input;
+    const resolve = await loadDocument(input);
+    if (!resolve.ok) {
+      console.error(`Failed to fetch document '${name}': request was not successful`);
+      workspace.documents[name] = {
+        ...meta,
+        openapi: "3.1.0",
+        info: {
+          title: `Document '${name}' could not be loaded`,
+          version: "unknown"
+        }
+      };
+      return;
+    }
+    if (!isObject(resolve.data)) {
+      console.error(`Failed to load document '${name}': response data is not a valid object`);
+      workspace.documents[name] = {
+        ...meta,
+        openapi: "3.1.0",
+        info: {
+          title: `Document '${name}' could not be loaded`,
+          version: "unknown"
+        }
+      };
+      return;
+    }
+    await addInMemoryDocument({ ...input, document: resolve.data });
   }
-  workspaceProps?.documents?.forEach(addDocumentSync);
   const visitedNodesCache = /* @__PURE__ */ new Set();
   return {
     /**
@@ -100,6 +149,30 @@ const createWorkspaceStore = (workspaceProps) => {
       }
       Object.assign(currentDocument, { [key]: value });
     },
+    /**
+     * Replaces the content of a specific document in the workspace with the provided input.
+     * This method computes the difference between the current document and the new input,
+     * then applies only the necessary changes in place. The updates are applied atomically,
+     * ensuring the document is updated in a single operation.
+     *
+     * @param documentName - The name of the document to update.
+     * @param input - The new content to apply to the document (as a plain object).
+     * @example
+     * // Replace the content of the 'api' document with new data
+     * store.replaceDocument('api', {
+     *   openapi: '3.1.0',
+     *   info: { title: 'Updated API', version: '1.0.1' },
+     *   paths: {},
+     * })
+     */
+    replaceDocument(documentName, input) {
+      const currentDocument = workspace.documents[documentName];
+      if (!currentDocument) {
+        return console.error(`Document '${documentName}' does not exist in the workspace.`);
+      }
+      const newDocument = coerceValue(OpenAPIDocumentSchema, upgrade(input).specification);
+      applySelectiveUpdates(currentDocument, newDocument);
+    },
     /**
      * Resolves a reference in the active document by following the provided path and resolving any external $ref references.
      * This method traverses the document structure following the given path and resolves any $ref references it encounters.
@@ -154,54 +227,7 @@ const createWorkspaceStore = (workspaceProps) => {
      *   }
      * })
      */
-    addDocument: async (input) => {
-      const { name, meta, config } = input;
-      const resolve = await loadDocument(input);
-      if (!resolve.ok) {
-        console.error(`Failed to fetch document '${name}': request was not successful`);
-        workspace.documents[name] = {
-          ...meta,
-          openapi: "3.1.0",
-          info: {
-            title: `Document '${name}' could not be loaded`,
-            version: "unknown"
-          }
-        };
-        return;
-      }
-      if (!isObject(resolve.data)) {
-        console.error(`Failed to load document '${name}': response data is not a valid object`);
-        workspace.documents[name] = {
-          ...meta,
-          openapi: "3.1.0",
-          info: {
-            title: `Document '${name}' could not be loaded`,
-            version: "unknown"
-          }
-        };
-        return;
-      }
-      addDocumentSync({ document: resolve.data, name, meta, config });
-    },
-    /**
-     * Similar to addDocument but requires and in-mem object to be provided and loads the document synchronously
-     * @param document - The document content to add. This should be a valid OpenAPI/Swagger document or other supported format
-     * @param meta - Metadata for the document, including its name and other properties defined in WorkspaceDocumentMeta
-     * @example
-     * // Add a new OpenAPI document to the workspace
-     * store.addDocument({
-     *   name: 'name',
-     *   document: {
-     *     openapi: '3.0.0',
-     *     info: { title: 'title' },
-     *   },
-     *   meta: {
-     *     'x-scalar-active-auth': 'Bearer',
-     *     'x-scalar-active-server': 'production'
-     *   }
-     * })
-     */
-    addDocumentSync,
+    addDocument,
     /**
      * Returns the merged configuration for the active document.
      *
@@ -267,15 +293,7 @@ const createWorkspaceStore = (workspaceProps) => {
      * // Save the current state of the document named 'api'
      * const excludedDiffs = store.saveDocument('api')
      */
-    saveDocument(documentName) {
-      const intermediateDocument = intermediateDocuments[documentName];
-      const updatedDocument = toRaw(getRaw(workspace.documents[documentName]));
-      if (!intermediateDocument || !updatedDocument) {
-        return;
-      }
-      const excludedDiffs = applySelectiveUpdates(intermediateDocument, updatedDocument);
-      return excludedDiffs;
-    },
+    saveDocument,
     /**
      * Restores the specified document to its last locally saved state.
      *
@@ -294,8 +312,12 @@ const createWorkspaceStore = (workspaceProps) => {
      * store.revertDocumentChanges('api')
      */
     revertDocumentChanges(documentName) {
+      const workspaceDocument = workspace.documents[documentName];
+      if (!workspaceDocument) {
+        return;
+      }
       const intermediateDocument = intermediateDocuments[documentName];
-      const updatedDocument = getRaw(workspace.documents[documentName]);
+      const updatedDocument = getRaw(workspaceDocument);
       if (!intermediateDocument || !updatedDocument) {
         return;
       }
@@ -332,14 +354,15 @@ const createWorkspaceStore = (workspaceProps) => {
               name,
               // Extract the raw document data for export, removing any Vue reactivity wrappers.
               // When importing, the document can be wrapped again in a magic proxy.
-              toRaw(getRaw(doc))
+              createOverridesProxy(getRaw(doc), overrides[name])
             ])
           )
         },
         meta: workspaceProps?.meta ?? {},
         documentConfigs,
         originalDocuments,
-        intermediateDocuments
+        intermediateDocuments,
+        overrides
       });
     },
     /**
@@ -360,7 +383,90 @@ const createWorkspaceStore = (workspaceProps) => {
       safeAssign(originalDocuments, result.originalDocuments);
       safeAssign(intermediateDocuments, result.intermediateDocuments);
       safeAssign(documentConfigs, result.documentConfigs);
+      safeAssign(overrides, result.overrides);
       safeAssign(workspace, result.meta);
+    },
+    /**
+     * Imports a workspace from a WorkspaceSpecification object.
+     *
+     * This method assigns workspace metadata and adds all documents defined in the specification.
+     * Each document is added using its $ref and optional overrides.
+     *
+     * @example
+     * ```ts
+     * await store.importWorkspaceFromSpecification({
+     *   documents: {
+     *     api: { $ref: '/specs/api.yaml' },
+     *     petstore: { $ref: '/specs/petstore.yaml' }
+     *   },
+     *   overrides: {
+     *     api: { config: { features: { showModels: true } } }
+     *   },
+     *   info: { title: 'My Workspace' },
+     *   workspace: 'v1',
+     *   "x-scalar-dark-mode": true
+     * })
+     * ```
+     *
+     * @param specification - The workspace specification to import.
+     */
+    importWorkspaceFromSpecification: (specification) => {
+      const { documents, overrides: overrides2, info, workspace: workspaceVersion, ...meta } = specification;
+      safeAssign(workspace, meta);
+      return Promise.all(
+        Object.entries(documents ?? {}).map(
+          ([name, doc]) => addDocument({ url: doc.$ref, name, overrides: overrides2?.[name] })
+        )
+      );
+    },
+    /**
+     * Rebases a document in the workspace with a new origin, resolving conflicts if provided.
+     *
+     * This method is used to rebase a document (e.g., after pulling remote changes) by applying the changes
+     * from the new origin and merging them with local edits. If there are conflicts, they can be resolved
+     * by providing a list of resolved conflicts.
+     *
+     * @param documentName - The name of the document to rebase.
+     * @param newDocumentOrigin - The new origin document (as an object) to rebase onto.
+     * @param resolvedConflicts - (Optional) An array of resolved conflicts to apply.
+     * @returns If there are unresolved conflicts and no resolution is provided, returns the list of conflicts.
+     *
+     * @example
+     * // 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)
+     * }
+     */
+    rebaseDocument: (documentName, newDocumentOrigin, resolvedConflicts) => {
+      const newOrigin = coerceValue(OpenAPIDocumentSchema, upgrade(newDocumentOrigin).specification);
+      const originalDocument = originalDocuments[documentName];
+      const intermediateDocument = intermediateDocuments[documentName];
+      const activeDocument = workspace.documents[documentName] ? getRaw(workspace.documents[documentName]) : void 0;
+      if (!originalDocument || !intermediateDocument || !activeDocument) {
+        return console.error("[ERROR]: Specified document is missing or internal corrupted workspace state");
+      }
+      const changelogAA = diff(originalDocument, newOrigin);
+      const changelogAB = diff(originalDocument, intermediateDocument);
+      const changesA = merge(changelogAA, changelogAB);
+      if (resolvedConflicts === void 0) {
+        return changesA.conflicts;
+      }
+      const changesetA = changesA.diffs.concat(resolvedConflicts);
+      const newIntermediateDocument = apply(deepClone(originalDocument), changesetA);
+      intermediateDocuments[documentName] = newIntermediateDocument;
+      originalDocuments[documentName] = newOrigin;
+      const changelogBA = diff(intermediateDocument, newIntermediateDocument);
+      const changelogBB = diff(intermediateDocument, activeDocument);
+      const changesB = merge(changelogBA, changelogBB);
+      const changesetB = changesB.diffs.concat(changesB.conflicts.flatMap((it) => it[0]));
+      const newActiveDocument = apply(deepClone(newIntermediateDocument), changesetB);
+      workspace.documents[documentName] = createOverridesProxy(
+        createMagicProxy({ ...newActiveDocument }),
+        overrides[documentName]
+      );
+      return;
     }
   };
 };