@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/components/assets/asset-library/hooks/useAssetLibraryMutations.ts

@@ -0,0 +1,266 @@
+import { useCallback, useState } from 'react'
+import {
+  deleteCollectionAsset,
+  updateCollectionAsset,
+  updateCollectionAssetSource,
+  updateCollectionAssetSourceScoped,
+} from '../../../../bridge/assets.mjs'
+import { revealPlatformPath } from '../../../../bridge/os.mjs'
+import type { PlatformAssetSummary } from '../../../../bridge/types.js'
+import {
+  canDeleteCollectionAsset,
+  canEditAssetMetadata,
+  canRevealCollectionAsset,
+  inlineAssetKind,
+  isInlineCollectionAsset,
+  isInsertableCollectionAsset,
+  messageForError,
+} from '../helpers.js'
+import type {
+  AssetLibraryActionsModel,
+  AssetLibraryBusyAction,
+  AssetLibraryStatus,
+} from '../types.js'
+import { uploadCollectionAssetFromDialog } from '../utils/uploadCollectionAsset.js'
+import type { UseAssetDetailDraftResult } from './useAssetDetailDraft.js'
+
+export interface UseAssetLibraryMutationsOptions {
+  collectionPath: string
+  /** When set, inline source edits use `assets.updateSourceScoped`. */
+  documentFiles?: string[]
+  collectionLabel: string
+  insertTargetLabel: string
+  uploadRelativeDir?: string
+  insertAssetHandler?: (asset: PlatformAssetSummary) => Promise<void>
+  selectedAsset: PlatformAssetSummary | null
+  draft: UseAssetDetailDraftResult
+  refreshAssets: (preferredId?: string | null) => Promise<void>
+  setStatus: (status: AssetLibraryStatus | null) => void
+  onDocumentSourceSaved?: (info: {
+    sourceDocumentPath?: string
+    relativePath: string
+  }) => void
+}
+
+export function useAssetLibraryMutations({
+  collectionPath,
+  documentFiles,
+  collectionLabel,
+  insertTargetLabel,
+  uploadRelativeDir,
+  insertAssetHandler,
+  selectedAsset,
+  draft,
+  refreshAssets,
+  setStatus,
+  onDocumentSourceSaved,
+}: UseAssetLibraryMutationsOptions): AssetLibraryActionsModel {
+  const [busy, setBusy] = useState<AssetLibraryBusyAction>(null)
+
+  const canInsertAsset = useCallback(
+    (asset: PlatformAssetSummary): boolean =>
+      Boolean(
+        insertAssetHandler && isInsertableCollectionAsset(asset) && !busy,
+      ),
+    [busy, insertAssetHandler],
+  )
+
+  const uploadAsset = useCallback(async (): Promise<void> => {
+    setBusy('uploading')
+    setStatus(null)
+    try {
+      const relativePath = await uploadCollectionAssetFromDialog({
+        collectionPath,
+        uploadRelativeDir,
+      })
+      if (!relativePath) return
+      await refreshAssets(relativePath)
+      setStatus({
+        tone: 'success',
+        message: `Added image to this ${collectionLabel}'s assets.`,
+      })
+    } catch (error) {
+      setStatus({ tone: 'error', message: messageForError(error) })
+    } finally {
+      setBusy(null)
+    }
+  }, [
+    collectionLabel,
+    collectionPath,
+    refreshAssets,
+    setStatus,
+    uploadRelativeDir,
+  ])
+
+  const saveMetadata = useCallback(async (): Promise<void> => {
+    if (
+      !selectedAsset ||
+      !canEditAssetMetadata(selectedAsset) ||
+      !draft.isDirty
+    ) {
+      return
+    }
+    setBusy('saving')
+    setStatus(null)
+    try {
+      const saved = isInlineCollectionAsset(selectedAsset)
+        ? await (async () => {
+            const kind = inlineAssetKind(selectedAsset)
+            const assetId = selectedAsset.sourceNodeId?.trim()
+            if (!kind || !assetId) {
+              throw new Error(
+                'This inline asset cannot be edited from the library.',
+              )
+            }
+            const sourceRequest = {
+              collectionPath,
+              relativePath: selectedAsset.relativePath,
+              assetId,
+              kind,
+              sourceCode: draft.sourceDraft,
+              label: draft.labelDraft,
+              caption: draft.captionDraft,
+            }
+            return documentFiles?.length
+              ? updateCollectionAssetSourceScoped({
+                  ...sourceRequest,
+                  documentFiles,
+                })
+              : updateCollectionAssetSource(sourceRequest)
+          })()
+        : await updateCollectionAsset({
+            collectionPath,
+            relativePath: selectedAsset.relativePath,
+            label: draft.labelDraft,
+            caption: draft.captionDraft,
+          })
+      await refreshAssets(saved.id)
+      if (isInlineCollectionAsset(selectedAsset)) {
+        onDocumentSourceSaved?.({
+          sourceDocumentPath: saved.sourceDocumentPath,
+          relativePath: saved.relativePath,
+        })
+      }
+      setStatus({
+        tone: 'success',
+        message: `Saved details for ${saved.label}.`,
+      })
+    } catch (error) {
+      setStatus({ tone: 'error', message: messageForError(error) })
+    } finally {
+      setBusy(null)
+    }
+  }, [
+    collectionPath,
+    documentFiles,
+    draft.captionDraft,
+    draft.isDirty,
+    draft.labelDraft,
+    draft.sourceDraft,
+    onDocumentSourceSaved,
+    refreshAssets,
+    selectedAsset,
+    setStatus,
+  ])
+
+  const deleteSelected = useCallback(async (): Promise<void> => {
+    if (!selectedAsset || !canDeleteCollectionAsset(selectedAsset)) return
+    if (
+      selectedAsset.usedIn.length > 0 &&
+      !window.confirm(
+        `"${selectedAsset.label}" is already used in ${
+          selectedAsset.usedIn.length
+        } ${
+          selectedAsset.usedIn.length === 1
+            ? insertTargetLabel
+            : `${insertTargetLabel}s`
+        }. Delete it anyway? Existing references may break.`,
+      )
+    ) {
+      return
+    }
+    setBusy('deleting')
+    setStatus(null)
+    try {
+      await deleteCollectionAsset({
+        collectionPath,
+        relativePath: selectedAsset.relativePath,
+      })
+      await refreshAssets(null)
+      setStatus({
+        tone: 'success',
+        message: `Deleted ${selectedAsset.label}.`,
+      })
+    } catch (error) {
+      setStatus({ tone: 'error', message: messageForError(error) })
+    } finally {
+      setBusy(null)
+    }
+  }, [
+    collectionPath,
+    insertTargetLabel,
+    refreshAssets,
+    selectedAsset,
+    setStatus,
+  ])
+
+  const revealSelected = useCallback(async (): Promise<void> => {
+    if (!selectedAsset || !canRevealCollectionAsset(selectedAsset)) return
+    setStatus(null)
+    try {
+      await revealPlatformPath(selectedAsset.absolutePath)
+    } catch (error) {
+      setStatus({ tone: 'error', message: messageForError(error) })
+    }
+  }, [selectedAsset, setStatus])
+
+  const insertAsset = useCallback(
+    async (asset: PlatformAssetSummary): Promise<void> => {
+      if (!insertAssetHandler || !canInsertAsset(asset)) return
+      setBusy('inserting')
+      setStatus(null)
+      try {
+        await insertAssetHandler(asset)
+        setStatus({
+          tone: 'success',
+          message: `Inserted ${asset.label} into the current ${insertTargetLabel}.`,
+        })
+      } catch (error) {
+        setStatus({ tone: 'error', message: messageForError(error) })
+      } finally {
+        setBusy(null)
+      }
+    },
+    [canInsertAsset, insertAssetHandler, insertTargetLabel, setStatus],
+  )
+
+  const insertSelected = useCallback(async (): Promise<void> => {
+    if (!selectedAsset) return
+    await insertAsset(selectedAsset)
+  }, [insertAsset, selectedAsset])
+
+  return {
+    busy,
+    uploadAsset,
+    saveMetadata,
+    deleteSelected,
+    revealSelected,
+    insertSelected,
+    insertAsset,
+    canSaveMetadata: Boolean(
+      selectedAsset &&
+        canEditAssetMetadata(selectedAsset) &&
+        draft.isDirty &&
+        !busy,
+    ),
+    canDeleteSelected: Boolean(
+      selectedAsset && canDeleteCollectionAsset(selectedAsset) && !busy,
+    ),
+    canRevealSelected: Boolean(
+      selectedAsset && canRevealCollectionAsset(selectedAsset) && !busy,
+    ),
+    canInsertSelected: Boolean(selectedAsset && canInsertAsset(selectedAsset)),
+    canInsertAsset,
+    insertTargetLabel,
+  }
+}

package/src/components/assets/asset-library/hooks/useAssetLibrarySelectionSync.ts

@@ -0,0 +1,24 @@
+import { useEffect } from 'react'
+import { setSelectedCollectionAsset } from '../../../../bridge/assets.mjs'
+
+/**
+ * Keeps shell selection in sync while the library is open (MCP / agents).
+ * Clears selection when the dialog closes.
+ */
+export function useAssetLibrarySelectionSync(
+  open: boolean,
+  collectionPath: string,
+  selectedRelativePath: string | null | undefined,
+): void {
+  useEffect(() => {
+    if (!open) {
+      void setSelectedCollectionAsset(null).catch(() => undefined)
+      return
+    }
+    if (!selectedRelativePath) return
+    void setSelectedCollectionAsset({
+      collectionPath,
+      relativePath: selectedRelativePath,
+    }).catch(() => undefined)
+  }, [collectionPath, open, selectedRelativePath])
+}

package/src/components/assets/asset-library/hooks/useAssetLibraryVersions.ts

@@ -0,0 +1,145 @@
+import { useCallback, useMemo, useState } from 'react'
+import {
+  swapCollectionAssetReferences,
+  swapCollectionAssetReferencesScoped,
+} from '../../../../bridge/assets.mjs'
+import type { PlatformAssetSummary } from '../../../../bridge/types.js'
+import { isFileCollectionAsset, messageForError } from '../helpers.js'
+import type { AssetLibraryStatus, AssetLibraryVersionsModel } from '../types.js'
+
+/**
+ * Version lineage + reference swap for file assets.
+ *
+ * Lineage is derived from the in-memory `assets` list (same filter as ps-book).
+ * TODO: When agents add versions while the dialog stays open, refresh via an
+ * explicit shell event or caller hook — not a background poll.
+ */
+export interface UseAssetLibraryVersionsOptions {
+  collectionPath: string
+  /** When set, collection-wide swaps use `assets.swapReferencesScoped`. */
+  documentFiles?: string[]
+  assets: PlatformAssetSummary[]
+  selectedAsset: PlatformAssetSummary | null
+  currentDocumentFile?: string | null
+  collectionLabel: string
+  insertTargetLabel: string
+  selectAsset: (assetId: string) => void
+  refreshAssets: (preferredId?: string | null) => Promise<void>
+  setStatus: (status: AssetLibraryStatus | null) => void
+}
+
+export function useAssetLibraryVersions({
+  collectionPath,
+  documentFiles,
+  assets,
+  selectedAsset,
+  currentDocumentFile,
+  collectionLabel,
+  insertTargetLabel,
+  selectAsset,
+  refreshAssets,
+  setStatus,
+}: UseAssetLibraryVersionsOptions): AssetLibraryVersionsModel {
+  const [swapping, setSwapping] = useState(false)
+
+  const visible = Boolean(selectedAsset && isFileCollectionAsset(selectedAsset))
+
+  const versions = useMemo(() => {
+    if (!selectedAsset || !visible) return []
+    return assets
+      .filter(asset => asset.lineageId === selectedAsset.lineageId)
+      .sort((left, right) => left.versionNumber - right.versionNumber)
+  }, [assets, selectedAsset, visible])
+
+  const previewVersion = useCallback(
+    (assetId: string): void => {
+      selectAsset(assetId)
+      setStatus({
+        tone: 'info',
+        message: 'Previewing this version. Use insert or swap to apply it.',
+      })
+    },
+    [selectAsset, setStatus],
+  )
+
+  const swapToVersion = useCallback(
+    async (
+      target: PlatformAssetSummary,
+      scope: 'document' | 'collection',
+    ): Promise<void> => {
+      if (!selectedAsset || !visible) return
+      if (selectedAsset.relativePath === target.relativePath) return
+
+      if (scope === 'document' && !currentDocumentFile) {
+        setStatus({
+          tone: 'error',
+          message: `Open a ${insertTargetLabel} before swapping references in it only.`,
+        })
+        return
+      }
+
+      setSwapping(true)
+      setStatus(null)
+      try {
+        const swapRequest = {
+          collectionPath,
+          fromRelativePath: selectedAsset.relativePath,
+          toRelativePath: target.relativePath,
+          scope,
+          documentFile:
+            scope === 'document' ? currentDocumentFile ?? undefined : undefined,
+        }
+        const result =
+          scope === 'collection' && documentFiles?.length
+            ? await swapCollectionAssetReferencesScoped({
+                ...swapRequest,
+                documentFiles,
+              })
+            : await swapCollectionAssetReferences(swapRequest)
+        await refreshAssets(target.id)
+        setStatus({
+          tone: 'success',
+          message:
+            scope === 'document'
+              ? `Replaced ${result.updatedReferences} reference${
+                  result.updatedReferences === 1 ? '' : 's'
+                } in this ${insertTargetLabel} with ${target.label}.`
+              : `Replaced ${result.updatedReferences} reference${
+                  result.updatedReferences === 1 ? '' : 's'
+                } across ${result.updatedDocuments} ${
+                  result.updatedDocuments === 1
+                    ? insertTargetLabel
+                    : `${insertTargetLabel}s`
+                } in this ${collectionLabel} with ${target.label}.`,
+        })
+      } catch (error) {
+        setStatus({ tone: 'error', message: messageForError(error) })
+      } finally {
+        setSwapping(false)
+      }
+    },
+    [
+      collectionLabel,
+      collectionPath,
+      currentDocumentFile,
+      documentFiles,
+      insertTargetLabel,
+      refreshAssets,
+      selectedAsset,
+      setStatus,
+      visible,
+    ],
+  )
+
+  return {
+    visible,
+    versions,
+    selectedRelativePath: selectedAsset?.relativePath ?? null,
+    previewVersion,
+    swapToVersion,
+    busy: swapping,
+    canSwapInDocument: Boolean(currentDocumentFile),
+    collectionLabel,
+    insertTargetLabel,
+  }
+}

package/src/components/assets/asset-library/hooks/useInlineAssetPreview.ts

@@ -0,0 +1,44 @@
+import { useEffect, useState } from 'react'
+import type { InlineAssetKind } from '../helpers/assetKind.js'
+import {
+  renderInlineAssetPreview,
+  type InlineAssetPreviewResult,
+} from '../../../../bridge/inlinePreview.js'
+
+export interface UseInlineAssetPreviewResult {
+  preview: InlineAssetPreviewResult | null
+  loading: boolean
+}
+
+export function useInlineAssetPreview(
+  kind: InlineAssetKind | null,
+  sourceCode: string,
+): UseInlineAssetPreviewResult {
+  const [preview, setPreview] = useState<InlineAssetPreviewResult | null>(null)
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (!kind) {
+      setPreview(null)
+      setLoading(false)
+      return
+    }
+
+    let cancelled = false
+    setLoading(true)
+
+    void renderInlineAssetPreview(kind, sourceCode)
+      .then(result => {
+        if (!cancelled) setPreview(result)
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [kind, sourceCode])
+
+  return { preview, loading }
+}

package/src/components/assets/asset-library/index.ts

@@ -0,0 +1,19 @@
+export { AssetLibraryDialog } from './AssetLibraryDialog.js'
+export { AssetLibraryWorkspace } from './AssetLibraryWorkspace.js'
+export type {
+  AssetLibraryDialogProps,
+  AssetLibraryWorkspaceProps,
+  CollectionAssetDocumentAdapter,
+} from './types.js'
+
+export { DEFAULT_COLLECTION_FIGURES_DIR } from '../../../bridge/collectionAssets.js'
+export { DEFAULT_UPLOAD_RELATIVE_DIR } from './utils/uploadCollectionAsset.js'
+
+export type {
+  AssetLibraryFilter,
+  AssetLibrarySection,
+  AssetLibrarySortMode,
+} from './utils/assetLibraryUtils.js'
+
+export { useAssetLibraryDialog } from './hooks/useAssetLibraryDialog.js'
+export type { UseAssetLibraryDialogOptions } from './hooks/useAssetLibraryDialog.js'

package/src/components/assets/asset-library/layout/assetLibraryLayout.ts

@@ -0,0 +1,201 @@
+import { styled } from 'styled-components'
+
+export const StyledAssetLibraryLayout = styled.div<{ $fill?: boolean }>`
+  display: grid;
+  grid-template-columns: ${({ $fill }) =>
+    $fill
+      ? 'minmax(340px, 400px) minmax(0, 1fr)'
+      : 'minmax(248px, 320px) minmax(0, 1fr)'};
+  width: 100%;
+  height: 100%;
+  max-height: ${({ $fill }) =>
+    $fill ? 'none' : 'min(620px, calc(100dvh - 190px))'};
+  min-height: 0;
+  min-width: 0;
+  overflow: hidden;
+
+  @media (max-width: 760px) {
+    grid-template-columns: minmax(0, 1fr);
+  }
+`
+
+export const StyledAssetLibrarySidebar = styled.aside`
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  min-width: 0;
+  border-right: 1px solid rgb(from var(--platform-colors-border) r g b / 0.72);
+  background: var(--platform-colors-surface);
+
+  @media (max-width: 760px) {
+    border-right: 0;
+    border-bottom: 1px solid var(--platform-colors-border);
+  }
+`
+
+export const StyledAssetLibraryDetail = styled.div`
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(300px, 360px);
+  min-height: 0;
+  min-width: 0;
+  background: var(--platform-colors-app-viewport, var(--platform-colors-bg));
+
+  @media (max-width: 760px) {
+    grid-template-columns: minmax(0, 1fr);
+    min-height: 320px;
+  }
+`
+
+export const StyledAssetLibraryDetailEmpty = styled.div`
+  display: flex;
+  flex: 1;
+  align-items: center;
+  justify-content: center;
+  min-height: 0;
+  padding: var(--platform-spacing-lg);
+  text-align: center;
+`
+
+export const StyledAssetLibraryDetailMain = styled.div`
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-height: 0;
+  min-width: 0;
+  overflow: hidden;
+`
+
+export const StyledAssetLibraryDetailPanels = styled.div<{ $columns: number }>`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-sm);
+  min-height: 0;
+  overflow: auto;
+  padding: var(--platform-spacing-md) 0 0;
+`
+
+export const StyledAssetLibrarySidePanel = styled.section`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-sm);
+  min-width: 0;
+  padding: var(--platform-spacing-sm) 0;
+  border-top: 1px solid rgb(from var(--platform-colors-border) r g b / 0.7);
+`
+
+export const StyledAssetLibrarySidePanelHeading = styled.h3`
+  margin: 0;
+  font-size: var(--platform-typography-font-size-xs);
+  font-weight: var(--platform-typography-font-weight-bold);
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--platform-colors-text-secondary);
+`
+
+export const StyledAssetLibrarySidePanelEmpty = styled.p`
+  margin: 0;
+  font-size: var(--platform-typography-font-size-sm);
+  color: var(--platform-colors-text-secondary);
+`
+
+export const StyledAssetLibraryUsageList = styled.ul`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-sm);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+`
+
+export const StyledAssetLibraryUsageItem = styled.li`
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+`
+
+export const StyledAssetLibraryUsageTitle = styled.span`
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--platform-typography-font-size-sm);
+  font-weight: var(--platform-typography-font-weight-medium);
+  color: var(--platform-colors-text);
+`
+
+export const StyledAssetLibraryUsagePath = styled.span`
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--platform-typography-font-size-xs);
+  color: var(--platform-colors-text-secondary);
+`
+
+export const StyledAssetLibraryVersionList = styled.ul`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-sm);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+`
+
+export const StyledAssetLibraryVersionItem = styled.li`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-xs);
+  padding-bottom: var(--platform-spacing-sm);
+  border-bottom: 1px solid var(--platform-colors-border);
+
+  &:last-child {
+    padding-bottom: 0;
+    border-bottom: 0;
+  }
+`
+
+export const StyledAssetLibraryVersionMeta = styled.div`
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--platform-spacing-sm);
+  min-width: 0;
+`
+
+export const StyledAssetLibraryVersionTitle = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+`
+
+export const StyledAssetLibraryVersionLabel = styled.span`
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--platform-typography-font-size-sm);
+  font-weight: var(--platform-typography-font-weight-medium);
+  color: var(--platform-colors-text);
+`
+
+export const StyledAssetLibraryVersionSub = styled.span`
+  font-size: var(--platform-typography-font-size-xs);
+  color: var(--platform-colors-text-secondary);
+`
+
+export const StyledAssetLibraryVersionBadge = styled.span`
+  flex-shrink: 0;
+  font-size: var(--platform-typography-font-size-xs);
+  color: var(--platform-colors-text-secondary);
+`
+
+export const StyledAssetLibraryVersionPrompt = styled.p`
+  margin: 0;
+  font-size: var(--platform-typography-font-size-xs);
+  color: var(--platform-colors-text-secondary);
+`
+
+export const StyledAssetLibraryVersionActions = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--platform-spacing-xs);
+`