@scalar/api-client 3.3.1 → 3.4.0

package/dist/v2/features/app/hooks/use-active-document-version.js

@@ -0,0 +1,60 @@
+import { useSidebarDocuments } from "./use-sidebar-documents.js";
+import { computed } from "vue";
+//#region src/v2/features/app/hooks/use-active-document-version.ts
+/**
+* Resolves everything UI surfaces need to know about the document the user
+* is currently viewing in a registry-backed workspace.
+*
+* The breadcrumb's version picker and the right-side sync indicator both
+* need the same data:
+*
+*  - the sidebar item for the active group (so titles match the registry),
+*  - the full version list for that group (used to render dropdown rows /
+*    feed `useVersionConflictCheck`),
+*  - and the currently active version (used for the picker selection and
+*    the standalone status icon).
+*
+* Pulling this into a composable keeps both surfaces aligned and avoids
+* duplicating the active-version selection rules — in particular the
+* fallback to the version declared on `x-scalar-registry-meta` when the
+* sidebar's notion of the active version has not caught up yet (e.g. during
+* a pending fetch).
+*/
+var useActiveDocumentVersion = ({ app, registryDocuments }) => {
+	const { documents } = useSidebarDocuments({
+		app,
+		managedDocs: () => registryDocuments().documents ?? []
+	});
+	/** Registry meta for the currently active document (if any). */
+	const activeRegistryMeta = computed(() => {
+		return (app.store.value?.workspace.activeDocument)?.["x-scalar-registry-meta"];
+	});
+	/**
+	* Sidebar item representing the currently active registry-backed document.
+	* We match by `namespace + slug` because a single group can contain
+	* several versions and the active document may be any of them.
+	*/
+	const activeItem = computed(() => {
+		const meta = activeRegistryMeta.value;
+		if (!meta) return;
+		return documents.value.find((item) => item.registry?.namespace === meta.namespace && item.registry?.slug === meta.slug);
+	});
+	/** Versions for the active group, ordered with the latest first. */
+	const versions = computed(() => activeItem.value?.versions ?? []);
+	return {
+		documents,
+		activeRegistryMeta,
+		activeItem,
+		versions,
+		activeVersion: computed(() => {
+			const meta = activeRegistryMeta.value;
+			const list = versions.value;
+			if (!meta) return list[0];
+			return list.find((v) => v.version === meta.version) ?? list[0];
+		})
+	};
+};
+//#endregion
+export { useActiveDocumentVersion };
+
+//# sourceMappingURL=use-active-document-version.js.map

package/dist/v2/features/app/hooks/use-active-document-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-active-document-version.js","names":[],"sources":["../../../../../src/v2/features/app/hooks/use-active-document-version.ts"],"sourcesContent":["import { type ComputedRef, computed } from 'vue'\n\nimport type { AppState } from '@/v2/features/app/app-state'\nimport {\n  type RegistryDocumentsState,\n  type SidebarDocumentItem,\n  type SidebarDocumentVersion,\n  useSidebarDocuments,\n} from '@/v2/features/app/hooks/use-sidebar-documents'\n\n/**\n * Resolves everything UI surfaces need to know about the document the user\n * is currently viewing in a registry-backed workspace.\n *\n * The breadcrumb's version picker and the right-side sync indicator both\n * need the same data:\n *\n *  - the sidebar item for the active group (so titles match the registry),\n *  - the full version list for that group (used to render dropdown rows /\n *    feed `useVersionConflictCheck`),\n *  - and the currently active version (used for the picker selection and\n *    the standalone status icon).\n *\n * Pulling this into a composable keeps both surfaces aligned and avoids\n * duplicating the active-version selection rules — in particular the\n * fallback to the version declared on `x-scalar-registry-meta` when the\n * sidebar's notion of the active version has not caught up yet (e.g. during\n * a pending fetch).\n */\nexport const useActiveDocumentVersion = ({\n  app,\n  registryDocuments,\n}: {\n  app: AppState\n  /** Reactive accessor — components pass a getter so the composable stays prop-driven. */\n  registryDocuments: () => RegistryDocumentsState\n}): {\n  documents: ComputedRef<SidebarDocumentItem[]>\n  activeRegistryMeta: ComputedRef<\n    | {\n        namespace: string\n        slug: string\n        version?: string\n        commitHash?: string\n        conflictCheckedAgainstHash?: string\n        hasConflict?: boolean\n      }\n    | undefined\n  >\n  activeItem: ComputedRef<SidebarDocumentItem | undefined>\n  versions: ComputedRef<SidebarDocumentVersion[]>\n  activeVersion: ComputedRef<SidebarDocumentVersion | undefined>\n} => {\n  const { documents } = useSidebarDocuments({\n    app,\n    managedDocs: () => registryDocuments().documents ?? [],\n  })\n\n  /** Registry meta for the currently active document (if any). */\n  const activeRegistryMeta = computed(() => {\n    const doc = app.store.value?.workspace.activeDocument\n    return doc?.['x-scalar-registry-meta']\n  })\n\n  /**\n   * Sidebar item representing the currently active registry-backed document.\n   * We match by `namespace + slug` because a single group can contain\n   * several versions and the active document may be any of them.\n   */\n  const activeItem = computed(() => {\n    const meta = activeRegistryMeta.value\n    if (!meta) {\n      return undefined\n    }\n    return documents.value.find(\n      (item) => item.registry?.namespace === meta.namespace && item.registry?.slug === meta.slug,\n    )\n  })\n\n  /** Versions for the active group, ordered with the latest first. */\n  const versions = computed<SidebarDocumentVersion[]>(() => activeItem.value?.versions ?? [])\n\n  /**\n   * The version currently active on screen. Prefers matching the version\n   * declared on the active document's registry meta so consumers always\n   * reflect what the user is viewing, even when the sidebar's notion of the\n   * active version has not caught up yet (e.g. during a pending fetch).\n   */\n  const activeVersion = computed<SidebarDocumentVersion | undefined>(() => {\n    const meta = activeRegistryMeta.value\n    const list = versions.value\n    if (!meta) {\n      return list[0]\n    }\n    return list.find((v) => v.version === meta.version) ?? list[0]\n  })\n\n  return {\n    documents,\n    activeRegistryMeta,\n    activeItem,\n    versions,\n    activeVersion,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,4BAA4B,EACvC,KACA,wBAqBG;CACH,MAAM,EAAE,cAAc,oBAAoB;EACxC;EACA,mBAAmB,mBAAmB,CAAC,aAAa,EAAE;EACvD,CAAC;;CAGF,MAAM,qBAAqB,eAAe;AAExC,UADY,IAAI,MAAM,OAAO,UAAU,kBAC1B;GACb;;;;;;CAOF,MAAM,aAAa,eAAe;EAChC,MAAM,OAAO,mBAAmB;AAChC,MAAI,CAAC,KACH;AAEF,SAAO,UAAU,MAAM,MACpB,SAAS,KAAK,UAAU,cAAc,KAAK,aAAa,KAAK,UAAU,SAAS,KAAK,KACvF;GACD;;CAGF,MAAM,WAAW,eAAyC,WAAW,OAAO,YAAY,EAAE,CAAC;AAiB3F,QAAO;EACL;EACA;EACA;EACA;EACA,eAdoB,eAAmD;GACvE,MAAM,OAAO,mBAAmB;GAChC,MAAM,OAAO,SAAS;AACtB,OAAI,CAAC,KACH,QAAO,KAAK;AAEd,UAAO,KAAK,MAAM,MAAM,EAAE,YAAY,KAAK,QAAQ,IAAI,KAAK;IAC5D;EAQD"}

package/dist/v2/features/app/hooks/use-sidebar-documents.d.ts

@@ -1,19 +1,51 @@
 import type { AppState } from '@scalar/api-client/v2/features/app';
 import type { TraversedDocument } from '@scalar/workspace-store/schemas/navigation';
 import { type MaybeRefOrGetter } from 'vue';
+import { type VersionStatus } from '../../../../v2/features/app/helpers/compute-version-status.js';
+export type { VersionStatus };
 /**
- * A single "version" of a document grouped under a registry namespace + slug.
- * Only used on team workspaces, where multiple local documents may share the
- * same registry coordinates.
+ * A single version of a registry-backed document.
+ *
+ * On team workspaces, a registry document can advertise multiple versions and
+ * each one may or may not have been imported into the local workspace store.
+ * Loaded versions surface their `documentName` and traversal `navigation`,
+ * unloaded versions are placeholders the sidebar can fetch on demand.
  */
 export type SidebarDocumentVersion = {
-    /** Stable key, matches the workspace document name */
+    /** Stable key: workspace `documentName` when loaded, otherwise `${namespace}/${slug}@${version}`. */
     key: string;
-    /** User facing label for the version */
+    /** Version identifier as advertised by the registry. */
+    version: string;
+    /** User-facing label for the version row. */
     title: string;
-    /** Name of the document inside the workspace store */
-    documentName: string;
-    /** Traversal tree for the document (if it has been loaded) */
+    /** Workspace store document name when this version is loaded locally. */
+    documentName?: string;
+    /**
+     * Commit hash recorded on the locally loaded workspace document, if any.
+     * Undefined when the version has not been imported into the workspace
+     * store or when the loaded document does not carry a hash.
+     */
+    commitHash?: string;
+    /**
+     * Commit hash advertised by the registry for this version, if any.
+     * Compared against `commitHash` to derive `status`.
+     */
+    registryCommitHash?: string;
+    /**
+     * Sync status surfaced for the version row. Derived from the local /
+     * registry commit hashes, the document's dirty flag and the cached
+     * conflict-check result on `x-scalar-registry-meta`. `unknown` is used
+     * for versions that are not loaded into the workspace store yet.
+     */
+    status: VersionStatus;
+    /**
+     * True when this row is the canonical "latest" version of the group: the
+     * first version the registry advertises. Drafts (locally-created versions
+     * the registry has not seen yet) never get this flag, even when they are
+     * surfaced ahead of the registry-advertised rows in the picker.
+     */
+    isLatest: boolean;
+    /** Traversal tree for this version. Populated only when the version is loaded into the workspace store. */
     navigation?: TraversedDocument;
 };
 /**
@@ -23,39 +55,53 @@ export type SidebarDocumentVersion = {
  *  - A workspace document that only exists locally (no registry link)
  *  - A workspace document that was imported from the registry
  *  - A registry document that has not yet been imported into the store
+ *
+ * For registry-backed entries, the parent fields (`navigation`, `documentName`)
+ * mirror the active version so the sidebar template can render a single tree
+ * without having to look up the active version itself. The full version list
+ * lives in `versions`.
  */
 export type SidebarDocumentItem = {
-    /** Stable key used for sidebar state keyed by `namespace/slug` or document name */
+    /** Stable key used for sidebar state: `@namespace/slug` for registry-backed entries, document name otherwise. */
     key: string;
-    /** User facing title of the document */
+    /**
+     * User-facing title of the document. Registry-backed entries always surface
+     * the registry's title so the sidebar matches what the registry advertises,
+     * even when a locally loaded copy has been renamed. Standalone entries use
+     * the workspace document title.
+     */
     title: string;
-    /** Name of the document inside the workspace store (if loaded) */
+    /** Name of the document inside the workspace store (mirrors the active version on registry-backed entries). */
     documentName?: string;
-    /** Registry metadata if available */
+    /** Registry coordinates for the document group (without the version, which lives on `versions[]`). */
     registry?: {
         namespace: string;
         slug: string;
     };
-    /**
-     * Traversal tree for the document if it has been loaded in the workspace store.
-     * When `undefined` the document still needs to be fetched from the registry
-     * before its nested content can be shown.
-     */
+    /** Traversal tree of the active version (or the lone document for standalone entries). */
     navigation?: TraversedDocument;
     /** Whether the document is pinned (todo: derived from `x-scalar-pinned`) */
     isPinned?: boolean;
     /**
-     * TODO: implement versioning logic
-     * Other loaded documents that share this item's `namespace + slug`. Only
-     * populated on team workspaces where we collapse duplicates into a single
-     * entry with multiple versions.
+     * All known versions of the document, ordered with the registry's ordering
+     * preserved (latest first by convention). Loaded versions surface their
+     * workspace `documentName` and `navigation`, unloaded ones act as
+     * placeholders the sidebar can fetch on demand. Undefined for standalone
+     * entries that have no registry coordinates.
      */
     versions?: SidebarDocumentVersion[];
+    /** Key of the version currently surfaced at the parent level (matches a `versions[].key`). */
+    activeVersionKey?: string;
+};
+type RegistryDocumentVersion = {
+    version: string;
+    commitHash?: string;
 };
 export type RegistryDocument = {
     namespace: string;
     slug: string;
     title: string;
+    versions: RegistryDocumentVersion[];
 };
 /**
  * Loading-aware wrapper for the registry documents prop.
@@ -80,8 +126,10 @@ export type RegistryDocumentsState = {
  *    Registry documents are not considered at all.
  *  - Team workspaces group workspace documents by `namespace + slug` from
  *    `x-scalar-registry-meta`. Each unique registry coordinate produces a
- *    single sidebar entry whose additional matches are exposed as `versions`.
- *    Registry documents that have no loaded match are appended as entries
+ *    single sidebar entry whose versions are exposed as `versions`. The
+ *    `versions` array merges the registry-advertised versions with any
+ *    loaded workspace counterparts (matched by `version`). Registry
+ *    documents that have no loaded match are still surfaced as entries
  *    waiting to be fetched.
  */
 export declare function useSidebarDocuments({ app, managedDocs, }: {

package/dist/v2/features/app/hooks/use-sidebar-documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-sidebar-documents.d.ts","sourceRoot":"","sources":["../../../../../src/v2/features/app/hooks/use-sidebar-documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAA;AACnF,OAAO,EAAE,KAAK,gBAAgB,EAAqB,MAAM,KAAK,CAAA;AAE9D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAA;IACX,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,iBAAiB,CAAA;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAA;IACX,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qCAAqC;IACrC,QAAQ,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C;;;;OAIG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,sBAAsB,EAAE,CAAA;CACpC,CAAA;AAID,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAA;AAIxD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,WAAW,GACZ,EAAE;IACD,GAAG,EAAE,QAAQ,CAAA;IACb,WAAW,EAAE,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAA;CAClD;;;;EA+GA"}
+{"version":3,"file":"use-sidebar-documents.d.ts","sourceRoot":"","sources":["../../../../../src/v2/features/app/hooks/use-sidebar-documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAA;AACnF,OAAO,EAAE,KAAK,gBAAgB,EAAqB,MAAM,KAAK,CAAA;AAE9D,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,kDAAkD,CAAA;AAE3G,YAAY,EAAE,aAAa,EAAE,CAAA;AAE7B;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAA;IACX,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,MAAM,EAAE,aAAa,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,2GAA2G;IAC3G,UAAU,CAAC,EAAE,iBAAiB,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,iHAAiH;IACjH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,+GAA+G;IAC/G,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sGAAsG;IACtG,QAAQ,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,0FAA0F;IAC1F,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,sBAAsB,EAAE,CAAA;IACnC,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAsBD,KAAK,uBAAuB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,uBAAuB,EAAE,CAAA;CACpC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAA;AAMxD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,WAAW,GACZ,EAAE;IACD,GAAG,EAAE,QAAQ,CAAA;IACb,WAAW,EAAE,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAA;CAClD;;;;EA+HA"}

package/dist/v2/features/app/hooks/use-sidebar-documents.js

@@ -1,6 +1,8 @@
+import { computeVersionStatus } from "../helpers/compute-version-status.js";
 import { computed, toValue } from "vue";
 //#region src/v2/features/app/hooks/use-sidebar-documents.ts
 var registryKey = (namespace, slug) => `@${namespace}/${slug}`;
+var versionKey = (namespace, slug, version) => `${registryKey(namespace, slug)}@${version}`;
 /**
 * Builds a unified list of sidebar documents.
 *
@@ -9,38 +11,49 @@ var registryKey = (namespace, slug) => `@${namespace}/${slug}`;
 *    Registry documents are not considered at all.
 *  - Team workspaces group workspace documents by `namespace + slug` from
 *    `x-scalar-registry-meta`. Each unique registry coordinate produces a
-*    single sidebar entry whose additional matches are exposed as `versions`.
-*    Registry documents that have no loaded match are appended as entries
+*    single sidebar entry whose versions are exposed as `versions`. The
+*    `versions` array merges the registry-advertised versions with any
+*    loaded workspace counterparts (matched by `version`). Registry
+*    documents that have no loaded match are still surfaced as entries
 *    waiting to be fetched.
 */
 function useSidebarDocuments({ app, managedDocs }) {
 	const isTeamWorkspace = app.workspace.isTeamWorkspace;
-	/** Raw workspace documents mapped to sidebar entries (pre-grouping). */
+	/** Raw workspace documents projected into the shape the grouping logic needs. */
 	const workspaceEntries = computed(() => {
 		const store = app.store.value;
 		if (!store) return [];
 		return Object.entries(store.workspace.documents).map(([name, doc]) => {
 			const registry = doc?.["x-scalar-registry-meta"];
 			const navigation = doc?.["x-scalar-navigation"];
-			const title = navigation?.title || doc?.info?.title || "Untitled";
-			const isTeam = isTeamWorkspace.value;
 			return {
-				key: isTeam && registry ? registryKey(registry.namespace, registry.slug) : name,
-				title,
 				documentName: name,
-				registry: isTeam && registry ? {
-					namespace: registry.namespace,
-					slug: registry.slug
-				} : void 0,
+				title: navigation?.title || doc?.info?.title || "Untitled",
 				navigation,
-				isPinned: false
+				isPinned: false,
+				isDirty: doc?.["x-scalar-is-dirty"] === true,
+				registry: registry ? {
+					namespace: registry.namespace,
+					slug: registry.slug,
+					version: registry.version,
+					commitHash: registry.commitHash,
+					conflictCheckedAgainstHash: registry.conflictCheckedAgainstHash,
+					hasConflict: registry.hasConflict
+				} : void 0
 			};
 		});
 	});
 	const documents = computed(() => {
-		if (!isTeamWorkspace.value) return workspaceEntries.value;
+		if (!isTeamWorkspace.value) return workspaceEntries.value.map((entry) => ({
+			key: entry.documentName,
+			title: entry.title,
+			documentName: entry.documentName,
+			registry: void 0,
+			navigation: entry.navigation,
+			isPinned: entry.isPinned ?? false
+		}));
 		const activeDocumentSlug = app.activeEntities.documentSlug.value;
-		const groups = /* @__PURE__ */ new Map();
+		const workspaceByRegistry = /* @__PURE__ */ new Map();
 		const standalone = [];
 		for (const entry of workspaceEntries.value) {
 			if (!entry.registry) {
@@ -48,42 +61,41 @@ function useSidebarDocuments({ app, managedDocs }) {
 				continue;
 			}
 			const key = registryKey(entry.registry.namespace, entry.registry.slug);
-			const bucket = groups.get(key);
+			const bucket = workspaceByRegistry.get(key);
 			if (bucket) bucket.push(entry);
-			else groups.set(key, [entry]);
+			else workspaceByRegistry.set(key, [entry]);
 		}
 		const grouped = [];
-		for (const [, entries] of groups) {
-			const activeIndex = entries.findIndex((e) => e.documentName === activeDocumentSlug);
-			const primaryIndex = activeIndex === -1 ? 0 : activeIndex;
-			const primary = entries[primaryIndex];
-			if (!primary) continue;
-			const versions = entries.filter((_, i) => i !== primaryIndex).map((e) => ({
-				key: e.documentName,
-				title: e.title,
-				documentName: e.documentName,
-				navigation: e.navigation
-			}));
-			grouped.push({
-				...primary,
-				isPinned: entries.some((e) => e.isPinned),
-				versions: versions.length ? versions : void 0
+		const consumedRegistryKeys = /* @__PURE__ */ new Set();
+		for (const doc of toValue(managedDocs)) {
+			const key = registryKey(doc.namespace, doc.slug);
+			consumedRegistryKeys.add(key);
+			const item = buildRegistryItem({
+				key,
+				registry: doc,
+				loaded: workspaceByRegistry.get(key) ?? [],
+				activeDocumentSlug
 			});
+			if (item) grouped.push(item);
 		}
-		const loadedKeys = new Set(groups.keys());
-		const registryOnly = toValue(managedDocs).filter((doc) => !loadedKeys.has(registryKey(doc.namespace, doc.slug))).map((doc) => ({
-			key: registryKey(doc.namespace, doc.slug),
-			title: doc.title || doc.slug,
-			registry: {
-				namespace: doc.namespace,
-				slug: doc.slug
-			}
-		}));
-		return [
-			...grouped,
-			...registryOnly,
-			...standalone
-		];
+		for (const [key, loaded] of workspaceByRegistry) {
+			if (consumedRegistryKeys.has(key)) continue;
+			const first = loaded[0]?.registry;
+			if (!first) continue;
+			const item = buildRegistryItem({
+				key,
+				registry: {
+					namespace: first.namespace,
+					slug: first.slug,
+					title: loaded[0]?.title ?? first.slug,
+					versions: []
+				},
+				loaded,
+				activeDocumentSlug
+			});
+			if (item) grouped.push(item);
+		}
+		return [...grouped, ...standalone.map(toStandaloneItem)];
 	});
 	return {
 		documents,
@@ -91,6 +103,116 @@ function useSidebarDocuments({ app, managedDocs }) {
 		rest: computed(() => documents.value.filter((d) => !d.isPinned))
 	};
 }
+/** Project a standalone (non-registry) workspace entry into a sidebar item. */
+var toStandaloneItem = (entry) => ({
+	key: entry.documentName,
+	title: entry.title,
+	documentName: entry.documentName,
+	registry: void 0,
+	navigation: entry.navigation,
+	isPinned: entry.isPinned ?? false
+});
+/**
+* Build a single registry-backed sidebar item. The version list is assembled
+* by walking the registry's advertised versions in order and pairing them
+* with any loaded workspace document that claims the same `version` string.
+* Loaded versions that the registry has not advertised are appended at the
+* end so they stay visible until the registry catches up.
+*/
+var buildRegistryItem = ({ key, registry, loaded, activeDocumentSlug }) => {
+	const loadedByVersion = /* @__PURE__ */ new Map();
+	const orphans = [];
+	for (const entry of loaded) {
+		const version = entry.registry?.version;
+		if (!version) {
+			orphans.push(entry);
+			continue;
+		}
+		if (loadedByVersion.has(version)) {
+			orphans.push(entry);
+			continue;
+		}
+		loadedByVersion.set(version, entry);
+	}
+	const versions = [];
+	const groupTitle = registry.title || registry.slug;
+	const draftEntries = [];
+	for (const [version, match] of loadedByVersion) {
+		if (registry.versions.some((v) => v.version === version)) continue;
+		draftEntries.push([version, match]);
+	}
+	draftEntries.reverse();
+	for (const [version, match] of draftEntries) versions.push({
+		key: match.documentName,
+		version,
+		title: groupTitle,
+		documentName: match.documentName,
+		commitHash: match.registry?.commitHash,
+		registryCommitHash: void 0,
+		status: computeVersionStatus({
+			isLoaded: true,
+			localHash: match.registry?.commitHash,
+			registryHash: void 0,
+			isDirty: match.isDirty
+		}),
+		isLatest: false,
+		navigation: match.navigation
+	});
+	registry.versions.forEach((v, registryIndex) => {
+		const match = loadedByVersion.get(v.version);
+		const localHash = match?.registry?.commitHash;
+		const registryHash = v.commitHash;
+		versions.push({
+			key: match ? match.documentName : versionKey(registry.namespace, registry.slug, v.version),
+			version: v.version,
+			title: groupTitle,
+			documentName: match?.documentName,
+			commitHash: localHash,
+			registryCommitHash: registryHash,
+			status: computeVersionStatus({
+				isLoaded: Boolean(match),
+				localHash,
+				registryHash,
+				isDirty: match?.isDirty,
+				conflictCheckedAgainstHash: match?.registry?.conflictCheckedAgainstHash,
+				hasConflict: match?.registry?.hasConflict
+			}),
+			isLatest: registryIndex === 0,
+			navigation: match?.navigation
+		});
+	});
+	for (const orphan of orphans) versions.push({
+		key: orphan.documentName,
+		version: orphan.registry?.version ?? "",
+		title: groupTitle,
+		documentName: orphan.documentName,
+		commitHash: orphan.registry?.commitHash,
+		registryCommitHash: void 0,
+		status: computeVersionStatus({
+			isLoaded: true,
+			localHash: orphan.registry?.commitHash,
+			registryHash: void 0,
+			isDirty: orphan.isDirty
+		}),
+		isLatest: false,
+		navigation: orphan.navigation
+	});
+	if (versions.length === 0) return;
+	const activeVersion = versions.find((v) => v.documentName !== void 0 && v.documentName === activeDocumentSlug) ?? versions.find((v) => v.documentName !== void 0) ?? versions[0];
+	return {
+		key,
+		title: groupTitle,
+		documentName: activeVersion.documentName,
+		registry: {
+			namespace: registry.namespace,
+			slug: registry.slug
+		},
+		navigation: activeVersion.navigation,
+		isPinned: loaded.some((e) => e.isPinned),
+		versions,
+		activeVersionKey: activeVersion.key
+	};
+};
 //#endregion
 export { useSidebarDocuments };
 

package/dist/v2/features/app/hooks/use-sidebar-documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-sidebar-documents.js","names":[],"sources":["../../../../../src/v2/features/app/hooks/use-sidebar-documents.ts"],"sourcesContent":["import type { AppState } from '@scalar/api-client/v2/features/app'\nimport type { TraversedDocument } from '@scalar/workspace-store/schemas/navigation'\nimport { type MaybeRefOrGetter, computed, toValue } from 'vue'\n\n/**\n * A single \"version\" of a document grouped under a registry namespace + slug.\n * Only used on team workspaces, where multiple local documents may share the\n * same registry coordinates.\n */\nexport type SidebarDocumentVersion = {\n  /** Stable key, matches the workspace document name */\n  key: string\n  /** User facing label for the version */\n  title: string\n  /** Name of the document inside the workspace store */\n  documentName: string\n  /** Traversal tree for the document (if it has been loaded) */\n  navigation?: TraversedDocument\n}\n\n/**\n * A unified item for the top-level of our sidebar.\n *\n * It can represent one of three things:\n *  - A workspace document that only exists locally (no registry link)\n *  - A workspace document that was imported from the registry\n *  - A registry document that has not yet been imported into the store\n */\nexport type SidebarDocumentItem = {\n  /** Stable key used for sidebar state keyed by `namespace/slug` or document name */\n  key: string\n  /** User facing title of the document */\n  title: string\n  /** Name of the document inside the workspace store (if loaded) */\n  documentName?: string\n  /** Registry metadata if available */\n  registry?: { namespace: string; slug: string }\n  /**\n   * Traversal tree for the document if it has been loaded in the workspace store.\n   * When `undefined` the document still needs to be fetched from the registry\n   * before its nested content can be shown.\n   */\n  navigation?: TraversedDocument\n  /** Whether the document is pinned (todo: derived from `x-scalar-pinned`) */\n  isPinned?: boolean\n  /**\n   * TODO: implement versioning logic\n   * Other loaded documents that share this item's `namespace + slug`. Only\n   * populated on team workspaces where we collapse duplicates into a single\n   * entry with multiple versions.\n   */\n  versions?: SidebarDocumentVersion[]\n}\n\ntype WorkspaceDocumentEntry = SidebarDocumentItem & { documentName: string }\n\nexport type RegistryDocument = {\n  namespace: string\n  slug: string\n  title: string\n}\n\n/**\n * Loading-aware wrapper for the registry documents prop.\n *\n * The sidebar uses the `status` to decide whether to render skeleton\n * placeholders while the registry is being fetched. `documents` is optional\n * during loading so callers can either render nothing or stream in cached\n * results while a refresh is still in flight.\n */\nexport type RegistryDocumentsState =\n  | { status: 'loading'; documents?: RegistryDocument[] }\n  | { status: 'success'; documents: RegistryDocument[] }\n\nconst registryKey = (namespace: string, slug: string) => `@${namespace}/${slug}`\n\n/**\n * Builds a unified list of sidebar documents.\n *\n * Behavior:\n *  - Local workspaces (`teamUid === 'local'`) only show workspace documents.\n *    Registry documents are not considered at all.\n *  - Team workspaces group workspace documents by `namespace + slug` from\n *    `x-scalar-registry-meta`. Each unique registry coordinate produces a\n *    single sidebar entry whose additional matches are exposed as `versions`.\n *    Registry documents that have no loaded match are appended as entries\n *    waiting to be fetched.\n */\nexport function useSidebarDocuments({\n  app,\n  managedDocs,\n}: {\n  app: AppState\n  managedDocs: MaybeRefOrGetter<RegistryDocument[]>\n}) {\n  const isTeamWorkspace = app.workspace.isTeamWorkspace\n\n  /** Raw workspace documents mapped to sidebar entries (pre-grouping). */\n  const workspaceEntries = computed<WorkspaceDocumentEntry[]>(() => {\n    const store = app.store.value\n    if (!store) {\n      return []\n    }\n\n    return Object.entries(store.workspace.documents).map(([name, doc]) => {\n      const registry = doc?.['x-scalar-registry-meta']\n      const navigation = doc?.['x-scalar-navigation'] as TraversedDocument | undefined\n\n      const title = navigation?.title || doc?.info?.title || 'Untitled'\n\n      // On team workspaces we key by registry coordinates so entries with the\n      // same `namespace/slug` can later be grouped into a single row with\n      // versions. On local workspaces we always key by the workspace document\n      // name, which is guaranteed to be unique because it is the map key in\n      // `store.workspace.documents`. If we derived the key from registry meta\n      // on local workspaces too, two documents sharing the same\n      // `x-scalar-registry-meta` would produce duplicate Vue `:key`s in the\n      // sidebar `v-for` and silently collide on re-render.\n      const isTeam = isTeamWorkspace.value\n      return {\n        key: isTeam && registry ? registryKey(registry.namespace, registry.slug) : name,\n        title,\n        documentName: name,\n        registry: isTeam && registry ? { namespace: registry.namespace, slug: registry.slug } : undefined,\n        navigation,\n        // TODO: we can implement this later\n        isPinned: false,\n      }\n    })\n  })\n  const documents = computed<SidebarDocumentItem[]>(() => {\n    // Local workspaces: show the workspace document list as-is, no registry\n    // grouping and no registry document lookups.\n    if (!isTeamWorkspace.value) {\n      return workspaceEntries.value\n    }\n\n    const activeDocumentSlug = app.activeEntities.documentSlug.value\n\n    // 1. Bucket workspace documents by their registry `namespace + slug`.\n    //    Documents without registry meta remain standalone entries.\n    const groups = new Map<string, WorkspaceDocumentEntry[]>()\n    const standalone: WorkspaceDocumentEntry[] = []\n\n    for (const entry of workspaceEntries.value) {\n      if (!entry.registry) {\n        standalone.push(entry)\n        continue\n      }\n      const key = registryKey(entry.registry.namespace, entry.registry.slug)\n      const bucket = groups.get(key)\n      if (bucket) {\n        bucket.push(entry)\n      } else {\n        groups.set(key, [entry])\n      }\n    }\n\n    // 2. Collapse each group into a single sidebar entry. The active document\n    //    is promoted to primary when possible so the visible entry matches\n    //    what is currently being viewed. The remaining documents in the\n    //    group become selectable versions.\n    const grouped: SidebarDocumentItem[] = []\n    for (const [, entries] of groups) {\n      const activeIndex = entries.findIndex((e) => e.documentName === activeDocumentSlug)\n      const primaryIndex = activeIndex === -1 ? 0 : activeIndex\n      const primary = entries[primaryIndex]\n      if (!primary) {\n        continue\n      }\n\n      const versions = entries\n        .filter((_, i) => i !== primaryIndex)\n        .map<SidebarDocumentVersion>((e) => ({\n          key: e.documentName,\n          title: e.title,\n          documentName: e.documentName,\n          navigation: e.navigation,\n        }))\n\n      grouped.push({\n        ...primary,\n        isPinned: entries.some((e) => e.isPinned),\n        versions: versions.length ? versions : undefined,\n      })\n    }\n\n    // 3. Merge in registry documents that have no loaded counterpart yet.\n    //    They render as placeholders until the user clicks to fetch them.\n    const loadedKeys = new Set(groups.keys())\n    const registryOnly = toValue(managedDocs)\n      .filter((doc) => !loadedKeys.has(registryKey(doc.namespace, doc.slug)))\n      .map<SidebarDocumentItem>((doc) => ({\n        key: registryKey(doc.namespace, doc.slug),\n        title: doc.title || doc.slug,\n        registry: { namespace: doc.namespace, slug: doc.slug },\n      }))\n\n    return [...grouped, ...registryOnly, ...standalone]\n  })\n\n  const pinned = computed(() => documents.value.filter((d) => d.isPinned))\n  const rest = computed(() => documents.value.filter((d) => !d.isPinned))\n\n  return { documents, pinned, rest }\n}\n"],"mappings":";;AA0EA,IAAM,eAAe,WAAmB,SAAiB,IAAI,UAAU,GAAG;;;;;;;;;;;;;AAc1E,SAAgB,oBAAoB,EAClC,KACA,eAIC;CACD,MAAM,kBAAkB,IAAI,UAAU;;CAGtC,MAAM,mBAAmB,eAAyC;EAChE,MAAM,QAAQ,IAAI,MAAM;AACxB,MAAI,CAAC,MACH,QAAO,EAAE;AAGX,SAAO,OAAO,QAAQ,MAAM,UAAU,UAAU,CAAC,KAAK,CAAC,MAAM,SAAS;GACpE,MAAM,WAAW,MAAM;GACvB,MAAM,aAAa,MAAM;GAEzB,MAAM,QAAQ,YAAY,SAAS,KAAK,MAAM,SAAS;GAUvD,MAAM,SAAS,gBAAgB;AAC/B,UAAO;IACL,KAAK,UAAU,WAAW,YAAY,SAAS,WAAW,SAAS,KAAK,GAAG;IAC3E;IACA,cAAc;IACd,UAAU,UAAU,WAAW;KAAE,WAAW,SAAS;KAAW,MAAM,SAAS;KAAM,GAAG,KAAA;IACxF;IAEA,UAAU;IACX;IACD;GACF;CACF,MAAM,YAAY,eAAsC;AAGtD,MAAI,CAAC,gBAAgB,MACnB,QAAO,iBAAiB;EAG1B,MAAM,qBAAqB,IAAI,eAAe,aAAa;EAI3D,MAAM,yBAAS,IAAI,KAAuC;EAC1D,MAAM,aAAuC,EAAE;AAE/C,OAAK,MAAM,SAAS,iBAAiB,OAAO;AAC1C,OAAI,CAAC,MAAM,UAAU;AACnB,eAAW,KAAK,MAAM;AACtB;;GAEF,MAAM,MAAM,YAAY,MAAM,SAAS,WAAW,MAAM,SAAS,KAAK;GACtE,MAAM,SAAS,OAAO,IAAI,IAAI;AAC9B,OAAI,OACF,QAAO,KAAK,MAAM;OAElB,QAAO,IAAI,KAAK,CAAC,MAAM,CAAC;;EAQ5B,MAAM,UAAiC,EAAE;AACzC,OAAK,MAAM,GAAG,YAAY,QAAQ;GAChC,MAAM,cAAc,QAAQ,WAAW,MAAM,EAAE,iBAAiB,mBAAmB;GACnF,MAAM,eAAe,gBAAgB,KAAK,IAAI;GAC9C,MAAM,UAAU,QAAQ;AACxB,OAAI,CAAC,QACH;GAGF,MAAM,WAAW,QACd,QAAQ,GAAG,MAAM,MAAM,aAAa,CACpC,KAA6B,OAAO;IACnC,KAAK,EAAE;IACP,OAAO,EAAE;IACT,cAAc,EAAE;IAChB,YAAY,EAAE;IACf,EAAE;AAEL,WAAQ,KAAK;IACX,GAAG;IACH,UAAU,QAAQ,MAAM,MAAM,EAAE,SAAS;IACzC,UAAU,SAAS,SAAS,WAAW,KAAA;IACxC,CAAC;;EAKJ,MAAM,aAAa,IAAI,IAAI,OAAO,MAAM,CAAC;EACzC,MAAM,eAAe,QAAQ,YAAY,CACtC,QAAQ,QAAQ,CAAC,WAAW,IAAI,YAAY,IAAI,WAAW,IAAI,KAAK,CAAC,CAAC,CACtE,KAA0B,SAAS;GAClC,KAAK,YAAY,IAAI,WAAW,IAAI,KAAK;GACzC,OAAO,IAAI,SAAS,IAAI;GACxB,UAAU;IAAE,WAAW,IAAI;IAAW,MAAM,IAAI;IAAM;GACvD,EAAE;AAEL,SAAO;GAAC,GAAG;GAAS,GAAG;GAAc,GAAG;GAAW;GACnD;AAKF,QAAO;EAAE;EAAW,QAHL,eAAe,UAAU,MAAM,QAAQ,MAAM,EAAE,SAAS,CAAC;EAG5C,MAFf,eAAe,UAAU,MAAM,QAAQ,MAAM,CAAC,EAAE,SAAS,CAAC;EAErC"}
+{"version":3,"file":"use-sidebar-documents.js","names":[],"sources":["../../../../../src/v2/features/app/hooks/use-sidebar-documents.ts"],"sourcesContent":["import type { AppState } from '@scalar/api-client/v2/features/app'\nimport type { TraversedDocument } from '@scalar/workspace-store/schemas/navigation'\nimport { type MaybeRefOrGetter, computed, toValue } from 'vue'\n\nimport { type VersionStatus, computeVersionStatus } from '@/v2/features/app/helpers/compute-version-status'\n\nexport type { VersionStatus }\n\n/**\n * A single version of a registry-backed document.\n *\n * On team workspaces, a registry document can advertise multiple versions and\n * each one may or may not have been imported into the local workspace store.\n * Loaded versions surface their `documentName` and traversal `navigation`,\n * unloaded versions are placeholders the sidebar can fetch on demand.\n */\nexport type SidebarDocumentVersion = {\n  /** Stable key: workspace `documentName` when loaded, otherwise `${namespace}/${slug}@${version}`. */\n  key: string\n  /** Version identifier as advertised by the registry. */\n  version: string\n  /** User-facing label for the version row. */\n  title: string\n  /** Workspace store document name when this version is loaded locally. */\n  documentName?: string\n  /**\n   * Commit hash recorded on the locally loaded workspace document, if any.\n   * Undefined when the version has not been imported into the workspace\n   * store or when the loaded document does not carry a hash.\n   */\n  commitHash?: string\n  /**\n   * Commit hash advertised by the registry for this version, if any.\n   * Compared against `commitHash` to derive `status`.\n   */\n  registryCommitHash?: string\n  /**\n   * Sync status surfaced for the version row. Derived from the local /\n   * registry commit hashes, the document's dirty flag and the cached\n   * conflict-check result on `x-scalar-registry-meta`. `unknown` is used\n   * for versions that are not loaded into the workspace store yet.\n   */\n  status: VersionStatus\n  /**\n   * True when this row is the canonical \"latest\" version of the group: the\n   * first version the registry advertises. Drafts (locally-created versions\n   * the registry has not seen yet) never get this flag, even when they are\n   * surfaced ahead of the registry-advertised rows in the picker.\n   */\n  isLatest: boolean\n  /** Traversal tree for this version. Populated only when the version is loaded into the workspace store. */\n  navigation?: TraversedDocument\n}\n\n/**\n * A unified item for the top-level of our sidebar.\n *\n * It can represent one of three things:\n *  - A workspace document that only exists locally (no registry link)\n *  - A workspace document that was imported from the registry\n *  - A registry document that has not yet been imported into the store\n *\n * For registry-backed entries, the parent fields (`navigation`, `documentName`)\n * mirror the active version so the sidebar template can render a single tree\n * without having to look up the active version itself. The full version list\n * lives in `versions`.\n */\nexport type SidebarDocumentItem = {\n  /** Stable key used for sidebar state: `@namespace/slug` for registry-backed entries, document name otherwise. */\n  key: string\n  /**\n   * User-facing title of the document. Registry-backed entries always surface\n   * the registry's title so the sidebar matches what the registry advertises,\n   * even when a locally loaded copy has been renamed. Standalone entries use\n   * the workspace document title.\n   */\n  title: string\n  /** Name of the document inside the workspace store (mirrors the active version on registry-backed entries). */\n  documentName?: string\n  /** Registry coordinates for the document group (without the version, which lives on `versions[]`). */\n  registry?: { namespace: string; slug: string }\n  /** Traversal tree of the active version (or the lone document for standalone entries). */\n  navigation?: TraversedDocument\n  /** Whether the document is pinned (todo: derived from `x-scalar-pinned`) */\n  isPinned?: boolean\n  /**\n   * All known versions of the document, ordered with the registry's ordering\n   * preserved (latest first by convention). Loaded versions surface their\n   * workspace `documentName` and `navigation`, unloaded ones act as\n   * placeholders the sidebar can fetch on demand. Undefined for standalone\n   * entries that have no registry coordinates.\n   */\n  versions?: SidebarDocumentVersion[]\n  /** Key of the version currently surfaced at the parent level (matches a `versions[].key`). */\n  activeVersionKey?: string\n}\n\n/** Internal projection of a workspace document used during grouping. */\ntype WorkspaceDocumentEntry = {\n  documentName: string\n  title: string\n  navigation?: TraversedDocument\n  isPinned?: boolean\n  /** Whether the workspace document has uncommitted local edits. */\n  isDirty?: boolean\n  registry?: {\n    namespace: string\n    slug: string\n    version?: string\n    commitHash?: string\n    /** Last registry hash the conflict cache was computed against. */\n    conflictCheckedAgainstHash?: string\n    /** Cached conflict-check outcome for `conflictCheckedAgainstHash`. */\n    hasConflict?: boolean\n  }\n}\n\ntype RegistryDocumentVersion = {\n  version: string\n  commitHash?: string\n}\n\nexport type RegistryDocument = {\n  namespace: string\n  slug: string\n  title: string\n  versions: RegistryDocumentVersion[]\n}\n\n/**\n * Loading-aware wrapper for the registry documents prop.\n *\n * The sidebar uses the `status` to decide whether to render skeleton\n * placeholders while the registry is being fetched. `documents` is optional\n * during loading so callers can either render nothing or stream in cached\n * results while a refresh is still in flight.\n */\nexport type RegistryDocumentsState =\n  | { status: 'loading'; documents?: RegistryDocument[] }\n  | { status: 'success'; documents: RegistryDocument[] }\n\nconst registryKey = (namespace: string, slug: string) => `@${namespace}/${slug}`\n\nconst versionKey = (namespace: string, slug: string, version: string) => `${registryKey(namespace, slug)}@${version}`\n\n/**\n * Builds a unified list of sidebar documents.\n *\n * Behavior:\n *  - Local workspaces (`teamUid === 'local'`) only show workspace documents.\n *    Registry documents are not considered at all.\n *  - Team workspaces group workspace documents by `namespace + slug` from\n *    `x-scalar-registry-meta`. Each unique registry coordinate produces a\n *    single sidebar entry whose versions are exposed as `versions`. The\n *    `versions` array merges the registry-advertised versions with any\n *    loaded workspace counterparts (matched by `version`). Registry\n *    documents that have no loaded match are still surfaced as entries\n *    waiting to be fetched.\n */\nexport function useSidebarDocuments({\n  app,\n  managedDocs,\n}: {\n  app: AppState\n  managedDocs: MaybeRefOrGetter<RegistryDocument[]>\n}) {\n  const isTeamWorkspace = app.workspace.isTeamWorkspace\n\n  /** Raw workspace documents projected into the shape the grouping logic needs. */\n  const workspaceEntries = computed<WorkspaceDocumentEntry[]>(() => {\n    const store = app.store.value\n    if (!store) {\n      return []\n    }\n\n    return Object.entries(store.workspace.documents).map(([name, doc]) => {\n      const registry = doc?.['x-scalar-registry-meta']\n      const navigation = doc?.['x-scalar-navigation'] as TraversedDocument | undefined\n\n      const title = navigation?.title || doc?.info?.title || 'Untitled'\n\n      return {\n        documentName: name,\n        title,\n        navigation,\n        // TODO: we can implement this later\n        isPinned: false,\n        isDirty: doc?.['x-scalar-is-dirty'] === true,\n        registry: registry\n          ? {\n              namespace: registry.namespace,\n              slug: registry.slug,\n              version: registry.version,\n              commitHash: registry.commitHash,\n              conflictCheckedAgainstHash: registry.conflictCheckedAgainstHash,\n              hasConflict: registry.hasConflict,\n            }\n          : undefined,\n      }\n    })\n  })\n\n  const documents = computed<SidebarDocumentItem[]>(() => {\n    // Local workspaces: show the workspace document list as-is, no registry\n    // grouping and no registry document lookups. The sidebar key is derived\n    // from the workspace document name (which is guaranteed unique because\n    // it is the map key in `store.workspace.documents`). If we keyed by\n    // registry coordinates instead, two local documents sharing the same\n    // `x-scalar-registry-meta` would produce duplicate Vue `:key`s in the\n    // sidebar `v-for` and silently collide on re-render.\n    if (!isTeamWorkspace.value) {\n      return workspaceEntries.value.map<SidebarDocumentItem>((entry) => ({\n        key: entry.documentName,\n        title: entry.title,\n        documentName: entry.documentName,\n        registry: undefined,\n        navigation: entry.navigation,\n        isPinned: entry.isPinned ?? false,\n      }))\n    }\n\n    const activeDocumentSlug = app.activeEntities.documentSlug.value\n\n    // 1. Bucket workspace documents by their registry `namespace + slug`.\n    //    Documents without registry meta remain standalone entries.\n    const workspaceByRegistry = new Map<string, WorkspaceDocumentEntry[]>()\n    const standalone: WorkspaceDocumentEntry[] = []\n\n    for (const entry of workspaceEntries.value) {\n      if (!entry.registry) {\n        standalone.push(entry)\n        continue\n      }\n      const key = registryKey(entry.registry.namespace, entry.registry.slug)\n      const bucket = workspaceByRegistry.get(key)\n      if (bucket) {\n        bucket.push(entry)\n      } else {\n        workspaceByRegistry.set(key, [entry])\n      }\n    }\n\n    // 2. Build entries from the registry, merging in any loaded workspace\n    //    counterparts. The registry's version order is preserved so the\n    //    \"first\" version on each entry is the latest one advertised.\n    const grouped: SidebarDocumentItem[] = []\n    const consumedRegistryKeys = new Set<string>()\n\n    for (const doc of toValue(managedDocs)) {\n      const key = registryKey(doc.namespace, doc.slug)\n      consumedRegistryKeys.add(key)\n      const loaded = workspaceByRegistry.get(key) ?? []\n      const item = buildRegistryItem({ key, registry: doc, loaded, activeDocumentSlug })\n      if (item) {\n        grouped.push(item)\n      }\n    }\n\n    // 3. Workspace docs that point at a registry coordinate the registry has\n    //    not advertised (yet) still need to appear in the sidebar so the user\n    //    is not stranded without an entry to click.\n    for (const [key, loaded] of workspaceByRegistry) {\n      if (consumedRegistryKeys.has(key)) {\n        continue\n      }\n      const first = loaded[0]?.registry\n      if (!first) {\n        continue\n      }\n      const item = buildRegistryItem({\n        key,\n        registry: {\n          namespace: first.namespace,\n          slug: first.slug,\n          title: loaded[0]?.title ?? first.slug,\n          versions: [],\n        },\n        loaded,\n        activeDocumentSlug,\n      })\n      if (item) {\n        grouped.push(item)\n      }\n    }\n\n    return [...grouped, ...standalone.map(toStandaloneItem)]\n  })\n\n  const pinned = computed(() => documents.value.filter((d) => d.isPinned))\n  const rest = computed(() => documents.value.filter((d) => !d.isPinned))\n\n  return { documents, pinned, rest }\n}\n\n/** Project a standalone (non-registry) workspace entry into a sidebar item. */\nconst toStandaloneItem = (entry: WorkspaceDocumentEntry): SidebarDocumentItem => ({\n  key: entry.documentName,\n  title: entry.title,\n  documentName: entry.documentName,\n  registry: undefined,\n  navigation: entry.navigation,\n  isPinned: entry.isPinned ?? false,\n})\n\n/**\n * Build a single registry-backed sidebar item. The version list is assembled\n * by walking the registry's advertised versions in order and pairing them\n * with any loaded workspace document that claims the same `version` string.\n * Loaded versions that the registry has not advertised are appended at the\n * end so they stay visible until the registry catches up.\n */\nconst buildRegistryItem = ({\n  key,\n  registry,\n  loaded,\n  activeDocumentSlug,\n}: {\n  key: string\n  registry: RegistryDocument\n  loaded: WorkspaceDocumentEntry[]\n  activeDocumentSlug: string | undefined\n}): SidebarDocumentItem | undefined => {\n  // Index loaded workspace docs by the version they claim. A workspace doc\n  // that does not declare a `version` is treated as an orphan and pushed to\n  // the bottom of the version list — it still belongs to the group but we\n  // cannot reconcile it with the registry.\n  const loadedByVersion = new Map<string, WorkspaceDocumentEntry>()\n  const orphans: WorkspaceDocumentEntry[] = []\n\n  for (const entry of loaded) {\n    const version = entry.registry?.version\n    if (!version) {\n      orphans.push(entry)\n      continue\n    }\n    if (loadedByVersion.has(version)) {\n      // Multiple workspace docs claim the same version; keep the first one\n      // (registry order wins) and surface the rest as orphans so they remain\n      // visible instead of silently disappearing.\n      orphans.push(entry)\n      continue\n    }\n    loadedByVersion.set(version, entry)\n  }\n\n  const versions: SidebarDocumentVersion[] = []\n\n  // Registry-backed rows always surface the registry title so the sidebar\n  // matches what the registry advertises. Local renames are intentionally\n  // ignored here; the slug is the last-resort fallback so the row always has\n  // something to render.\n  const groupTitle = registry.title || registry.slug\n\n  // Build the drafts list first: entries left in `loadedByVersion` after we\n  // remove every version the registry advertises. The workspace store\n  // preserves insertion order, so the newest draft is naturally last —\n  // reverse it here to surface the most recently created draft first.\n  const draftEntries: [string, WorkspaceDocumentEntry][] = []\n  for (const [version, match] of loadedByVersion) {\n    if (registry.versions.some((v) => v.version === version)) {\n      continue\n    }\n    draftEntries.push([version, match])\n  }\n  draftEntries.reverse()\n\n  // Drafts go on top: the user just created them and the registry has not\n  // seen them yet, so they are the most relevant rows in the picker.\n  // Drafts never carry the \"Latest\" badge — that label always belongs to\n  // the latest registry-advertised version, regardless of row position.\n  for (const [version, match] of draftEntries) {\n    versions.push({\n      key: match.documentName,\n      version,\n      title: groupTitle,\n      documentName: match.documentName,\n      commitHash: match.registry?.commitHash,\n      registryCommitHash: undefined,\n      status: computeVersionStatus({\n        isLoaded: true,\n        localHash: match.registry?.commitHash,\n        registryHash: undefined,\n        isDirty: match.isDirty,\n      }),\n      isLatest: false,\n      navigation: match.navigation,\n    })\n  }\n\n  // Then the registry-advertised versions, in the order the registry\n  // returned them (latest first by convention). The first one is the\n  // canonical \"latest\" — flagged here so the picker can render the badge\n  // independent of row order in the array.\n  registry.versions.forEach((v, registryIndex) => {\n    const match = loadedByVersion.get(v.version)\n    const localHash = match?.registry?.commitHash\n    const registryHash = v.commitHash\n    versions.push({\n      key: match ? match.documentName : versionKey(registry.namespace, registry.slug, v.version),\n      version: v.version,\n      title: groupTitle,\n      documentName: match?.documentName,\n      commitHash: localHash,\n      registryCommitHash: registryHash,\n      status: computeVersionStatus({\n        isLoaded: Boolean(match),\n        localHash,\n        registryHash,\n        isDirty: match?.isDirty,\n        conflictCheckedAgainstHash: match?.registry?.conflictCheckedAgainstHash,\n        hasConflict: match?.registry?.hasConflict,\n      }),\n      isLatest: registryIndex === 0,\n      navigation: match?.navigation,\n    })\n  })\n\n  // Loaded docs that did not declare a version at all.\n  for (const orphan of orphans) {\n    versions.push({\n      key: orphan.documentName,\n      version: orphan.registry?.version ?? '',\n      title: groupTitle,\n      documentName: orphan.documentName,\n      commitHash: orphan.registry?.commitHash,\n      registryCommitHash: undefined,\n      status: computeVersionStatus({\n        isLoaded: true,\n        localHash: orphan.registry?.commitHash,\n        registryHash: undefined,\n        isDirty: orphan.isDirty,\n      }),\n      isLatest: false,\n      navigation: orphan.navigation,\n    })\n  }\n\n  if (versions.length === 0) {\n    return undefined\n  }\n\n  // Pick the active version: prefer a loaded match against the active\n  // document slug, then any loaded version, then fall back to the first\n  // version (the latest advertised by the registry).\n  const activeVersion =\n    versions.find((v) => v.documentName !== undefined && v.documentName === activeDocumentSlug) ??\n    versions.find((v) => v.documentName !== undefined) ??\n    versions[0]!\n\n  return {\n    key,\n    title: groupTitle,\n    documentName: activeVersion.documentName,\n    registry: { namespace: registry.namespace, slug: registry.slug },\n    navigation: activeVersion.navigation,\n    isPinned: loaded.some((e) => e.isPinned),\n    versions,\n    activeVersionKey: activeVersion.key,\n  }\n}\n"],"mappings":"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"}

package/dist/v2/features/app/hooks/use-version-conflict-check.d.ts

@@ -0,0 +1,35 @@
+import type { WorkspaceStore } from '@scalar/workspace-store/client';
+import { type MaybeRefOrGetter } from 'vue';
+import type { SidebarDocumentVersion } from '../../../../v2/features/app/hooks/use-sidebar-documents.js';
+import type { ImportDocumentFromRegistry } from '../../../../v2/types/configuration';
+/**
+ * Kicks off background `checkVersionConflict` calls for every loaded
+ * registry-backed version of the active document group whose status
+ * indicates a fresh three-way merge is needed.
+ *
+ * Scope is limited to the *active document group* on purpose: the breadcrumb
+ * only renders the picker for the document the user is currently viewing,
+ * so spending requests on versions outside that group would be wasted work.
+ * Within the active group, every loaded version is checked because the
+ * picker dropdown surfaces a status icon for each row — switching versions
+ * later should not block on a new request when the user opens the dropdown.
+ *
+ * The helper writes the result to `x-scalar-registry-meta` on the workspace
+ * document, which then flows back through `useSidebarDocuments` and updates
+ * the row icon. The in-memory `inflight` map guards against firing the same
+ * request twice while the cache write is still pending.
+ */
+export declare const useVersionConflictCheck: ({ store, fetcher, registry, versions, }: {
+    /** Workspace store the conflict result is cached on. */
+    store: MaybeRefOrGetter<WorkspaceStore | null>;
+    /** Registry fetcher used to pull the latest remote document for the merge. */
+    fetcher: MaybeRefOrGetter<ImportDocumentFromRegistry | undefined>;
+    /** Registry coordinates of the group these versions belong to. */
+    registry: MaybeRefOrGetter<{
+        namespace: string;
+        slug: string;
+    } | undefined>;
+    /** All versions of the active document group. */
+    versions: MaybeRefOrGetter<SidebarDocumentVersion[]>;
+}) => void;
+//# sourceMappingURL=use-version-conflict-check.d.ts.map

package/dist/v2/features/app/hooks/use-version-conflict-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-version-conflict-check.d.ts","sourceRoot":"","sources":["../../../../../src/v2/features/app/hooks/use-version-conflict-check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAE,KAAK,gBAAgB,EAAkB,MAAM,KAAK,CAAA;AAG3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAC3F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAA;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAAI,yCAKrC;IACD,wDAAwD;IACxD,KAAK,EAAE,gBAAgB,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IAC9C,8EAA8E;IAC9E,OAAO,EAAE,gBAAgB,CAAC,0BAA0B,GAAG,SAAS,CAAC,CAAA;IACjE,kEAAkE;IAClE,QAAQ,EAAE,gBAAgB,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;IAC3E,iDAAiD;IACjD,QAAQ,EAAE,gBAAgB,CAAC,sBAAsB,EAAE,CAAC,CAAA;CACrD,KAAG,IA0EH,CAAA"}