@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.8

package/src/bridge/react/usePlatformJsonStore.tsx

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  readPlatformStorageJson,
+  writePlatformStorageJson,
+} from '../storage.mjs'
+
+export type PlatformJsonStoreFileName = `${string}.json`
+
+export interface UsePlatformJsonStoreOptions<TValue> {
+  appSlug: string | null
+  fileName: PlatformJsonStoreFileName | null
+  /** Default value when the JSON file does not exist yet. */
+  initialValue: TValue
+  /** Wait for bridge ready before loading (default: true when appSlug/fileName exist). */
+  enabled?: boolean
+  /** Normalize parsed JSON into the app-owned store shape. */
+  parse?: (value: unknown) => TValue
+}
+
+export interface UsePlatformJsonStoreResult<TValue> {
+  value: TValue
+  path: string | null
+  loading: boolean
+  saving: boolean
+  error: Error | null
+  saveValue: (next: TValue) => Promise<TValue>
+  updateValue: (updater: (current: TValue) => TValue) => Promise<TValue>
+  reload: () => void
+}
+
+function defaultParse<TValue>(value: unknown): TValue {
+  return value as TValue
+}
+
+/**
+ * Load and replace one shell-managed JSON store file through `storage.*`.
+ * Use this for app-owned internal records, not for user-visible documents.
+ */
+export function usePlatformJsonStore<TValue>({
+  appSlug,
+  fileName,
+  initialValue,
+  enabled = Boolean(appSlug && fileName),
+  parse = defaultParse<TValue>,
+}: UsePlatformJsonStoreOptions<TValue>): UsePlatformJsonStoreResult<TValue> {
+  const [value, setValue] = useState<TValue>(initialValue)
+  const [path, setPath] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [reloadToken, setReloadToken] = useState(0)
+  const valueRef = useRef(value)
+  const writeChainRef = useRef<Promise<TValue>>(Promise.resolve(value))
+  valueRef.current = value
+
+  const reload = useCallback(() => {
+    setReloadToken(token => token + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!enabled || !appSlug || !fileName) return
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    void readPlatformStorageJson({ appSlug, fileName })
+      .then(result => {
+        if (cancelled) return
+        const next =
+          result.value === null ? initialValue : parse(result.value)
+        valueRef.current = next
+        setValue(next)
+        setPath(result.path)
+      })
+      .catch((cause: unknown) => {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)))
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [appSlug, enabled, fileName, initialValue, parse, reloadToken])
+
+  const queueSave = useCallback(
+    (resolveNext: (current: TValue) => TValue): Promise<TValue> => {
+      if (!appSlug || !fileName) {
+        throw new Error('appSlug and fileName are required to save JSON storage')
+      }
+
+      const write = async (): Promise<TValue> => {
+        const next = resolveNext(valueRef.current)
+        setSaving(true)
+        try {
+          const result = await writePlatformStorageJson({
+            appSlug,
+            fileName,
+            value: next,
+          })
+          valueRef.current = next
+          setValue(next)
+          setPath(result.path)
+          setError(null)
+          return next
+        } catch (cause) {
+          const error =
+            cause instanceof Error ? cause : new Error(String(cause))
+          setError(error)
+          throw error
+        } finally {
+          setSaving(false)
+        }
+      }
+
+      const queued = writeChainRef.current.then(write, write)
+      writeChainRef.current = queued.catch(() => valueRef.current)
+      return queued
+    },
+    [appSlug, fileName],
+  )
+
+  const saveValue = useCallback(
+    (next: TValue): Promise<TValue> => queueSave(() => next),
+    [queueSave],
+  )
+
+  const updateValue = useCallback(
+    (updater: (current: TValue) => TValue): Promise<TValue> => {
+      return queueSave(updater)
+    },
+    [queueSave],
+  )
+
+  return {
+    value,
+    path,
+    loading,
+    saving,
+    error,
+    saveValue,
+    updateValue,
+    reload,
+  }
+}

package/src/bridge/storage.d.mts

@@ -1,9 +1,9 @@
-export type PlatformStorageJsonFileName = `${string}.json`
-
-export interface PlatformStorageJsonRequest {
-  appSlug: string
-  fileName: PlatformStorageJsonFileName
-}
+export type PlatformStorageJsonFileName = `${string}.json`
+
+export interface PlatformStorageJsonRequest {
+  appSlug: string
+  fileName: PlatformStorageJsonFileName
+}
 
 export interface PlatformStorageJsonReadResult {
   path: string

package/src/bridge/storage.test.ts

@@ -20,7 +20,7 @@ beforeEach(() => {
 
 describe('storage bridge helpers', () => {
   it('reads JSON storage using the shell request object shape', async () => {
-    const request = { appSlug: 'puretasks', fileName: 'tasks.json' } as const
+    const request = { appSlug: 'puretasks', fileName: 'tasks.json' } as const
     bridgeCall.mockResolvedValue({ path: '/tmp/tasks.json', value: null })
 
     await readPlatformStorageJson(request)
@@ -32,11 +32,11 @@ describe('storage bridge helpers', () => {
   })
 
   it('writes JSON storage using the shell request object shape', async () => {
-    const request = {
-      appSlug: 'puretasks',
-      fileName: 'tasks.json',
-      value: { tasks: [] },
-    } as const
+    const request = {
+      appSlug: 'puretasks',
+      fileName: 'tasks.json',
+      value: { tasks: [] },
+    } as const
     bridgeCall.mockResolvedValue({ path: '/tmp/tasks.json', ok: true })
 
     await writePlatformStorageJson(request)

package/src/bridge/types.ts

@@ -2,6 +2,7 @@ export type PlatformBridgeEventName =
   import('./events.mjs').PlatformBridgeEventName
 
 import type { PlatformThemeMode } from '../theme/tokens.js'
+import type { PlatformAppContextManifest } from '../context/contextConfig.js'
 
 /** Shell prefs exposed via `settings.prefs.get` / `settings.prefs.set`. */
 export type PlatformThemePreference = PlatformThemeMode
@@ -80,6 +81,8 @@ export interface PlatformAppManifest {
   productName: string
   kind: string
   description: string
+  /** Declarative context-file config for this app's package objects. */
+  context?: PlatformAppContextManifest
   peopleProviders?: Array<{
     id: string
     label: string
@@ -205,6 +208,10 @@ export interface RenderPagedSnapshotMetrics {
   captionVisible?: boolean
   captionOrphaned?: boolean
   strandedHeading?: boolean | null
+  /** Blocks on the target page that collide with each other. */
+  overlappingBlocks?: number
+  /** Blocks escaping the page content box. */
+  overflowingBlocks?: number
 }
 
 export interface RenderPagedPreviewResult {

package/src/components/agents/AgentDrawerPanel.tsx

@@ -45,6 +45,7 @@ export function AgentDrawerPanel({
   drawerOpen = true,
   composerPortaled = false,
   threadHeader = null,
+  threadHeaderHeight = 34,
 }: AgentDrawerPanelProps): React.ReactElement {
   const awaitingApproval = pendingToolCalls.length > 0
   const composerBlocked = composerDisabled
@@ -85,6 +86,7 @@ export function AgentDrawerPanel({
             messages={messages}
             assistantLabel={assistantLabel}
             threadHeader={threadHeader}
+            threadHeaderHeight={threadHeaderHeight}
           />
         </StyledAgentThreadHost>
       </StyledAgentBody>

package/src/components/agents/AgentMessageList.tsx

@@ -15,6 +15,7 @@ export interface AgentMessageListProps {
   assistantLabel?: string
   emptyMessage?: string
   threadHeader?: React.ReactNode
+  threadHeaderHeight?: number
 }
 
 export const AgentMessageList = memo(function AgentMessageList({
@@ -22,11 +23,15 @@ export const AgentMessageList = memo(function AgentMessageList({
   assistantLabel = 'assistant',
   emptyMessage = 'Ask the agent about your workspace. Tool calls wait for your approval.',
   threadHeader = null,
+  threadHeaderHeight = 34,
 }: AgentMessageListProps): React.ReactElement {
   const scrollKey = messages.map(message => message.id).join('|')
 
   return (
-    <StyledAgentScroll data-thread-header={threadHeader ? '' : undefined}>
+    <StyledAgentScroll
+      data-thread-header={threadHeader ? '' : undefined}
+      $threadHeaderHeight={threadHeaderHeight}
+    >
       {threadHeader}
       <ChatThread
         scrollKey={scrollKey}

package/src/components/agents/AgentToolCallCard.tsx

@@ -1,31 +1,31 @@
-import { Text } from '../common/typography/Text.js'
-import type { AgentUiToolCall } from './agentTypes.js'
+import { Text } from '../common/typography/Text.js'
+import type { AgentUiToolCall } from './agentTypes.js'
 import {
   formatAgentToolLabel,
   formatAgentToolSummary,
 } from './agentToolDisplay.js'
-import { formatToolCallArguments } from './formatToolCallArguments.js'
-import { StyledToolArgs, StyledToolCard } from './agentPanelStyles.js'
+import { formatToolCallArguments } from './formatToolCallArguments.js'
+import { StyledToolArgs, StyledToolCard } from './agentPanelStyles.js'
 
-export interface AgentToolCallCardProps {
-  toolCall: AgentUiToolCall
-  footer?: React.ReactNode
-}
-
-export function AgentToolCallCard({
-  toolCall,
-  footer,
+export interface AgentToolCallCardProps {
+  toolCall: AgentUiToolCall
+  footer?: React.ReactNode
+}
+
+export function AgentToolCallCard({
+  toolCall,
+  footer,
 }: AgentToolCallCardProps): React.ReactElement {
   return (
     <StyledToolCard>
       <Text weight="medium" size="sm">
         {formatAgentToolLabel(toolCall.name)}
       </Text>
-      <StyledToolArgs>
-        {formatAgentToolSummary(toolCall.name, toolCall.arguments) ||
-          formatToolCallArguments(toolCall.arguments)}
-      </StyledToolArgs>
-      {footer}
-    </StyledToolCard>
-  )
-}
+      <StyledToolArgs>
+        {formatAgentToolSummary(toolCall.name, toolCall.arguments) ||
+          formatToolCallArguments(toolCall.arguments)}
+      </StyledToolArgs>
+      {footer}
+    </StyledToolCard>
+  )
+}

package/src/components/agents/ContextPicker.tsx

@@ -0,0 +1,239 @@
+/**
+ * ContextPicker — Cmd-K-style overlay for choosing an object whose markdown
+ * context document should be attached as agent context.
+ *
+ * Generic on purpose: `search` and `onPick` are injected, so the shell
+ * drawer (IPC-backed) and plugin apps (bridge-backed `context.search`) use
+ * the same component — and agents use the same backing functions via the
+ * built-in `harness.context_search` / `harness.context_read` tools.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { styled } from 'styled-components'
+
+import type { PlatformContextSearchHit } from '../../context/contextAccess.js'
+import { SearchField } from '../common/inputs/SearchField.js'
+
+export interface ContextPickerProps {
+  open: boolean
+  onClose: () => void
+  /** Search context-enabled objects — empty query lists everything. */
+  search: (query: string) => Promise<PlatformContextSearchHit[]>
+  /** Called with the chosen object; owner fetches markdown via context.read. */
+  onPick: (hit: PlatformContextSearchHit) => void | Promise<void>
+  title?: string
+  placeholder?: string
+}
+
+const Backdrop = styled.div`
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 12vh;
+  background: color-mix(
+    in srgb,
+    var(--platform-color-background, #101014) 45%,
+    transparent
+  );
+`
+
+const Panel = styled.div`
+  width: min(560px, calc(100vw - 48px));
+  max-height: 60vh;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  border-radius: 12px;
+  border: 1px solid var(--platform-color-border, #2a2a32);
+  background: var(--platform-color-surface, #17171c);
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.35);
+`
+
+const PanelTitle = styled.div`
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--platform-color-text-muted, #8b8b95);
+  padding: 2px 4px 0;
+`
+
+const Results = styled.ul`
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+`
+
+const ResultRow = styled.li<{ $active: boolean }>`
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-radius: 8px;
+  cursor: pointer;
+  background: ${({ $active }) =>
+    $active
+      ? 'var(--platform-color-surface-raised, #22222a)'
+      : 'transparent'};
+`
+
+const ResultTitle = styled.span`
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--platform-color-text, #e8e8ee);
+`
+
+const KindBadge = styled.span`
+  flex: none;
+  font-size: 11px;
+  font-weight: 400;
+  padding: 1px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--platform-color-border, #2a2a32);
+  color: var(--platform-color-text-muted, #8b8b95);
+`
+
+const EmptyNote = styled.div`
+  padding: 14px 10px;
+  font-size: 13px;
+  color: var(--platform-color-text-muted, #8b8b95);
+`
+
+export function ContextPicker({
+  open,
+  onClose,
+  search,
+  onPick,
+  title = 'Add context',
+  placeholder = 'Search manuscripts, books, documents…',
+}: ContextPickerProps): React.ReactElement | null {
+  const [query, setQuery] = useState('')
+  const [hits, setHits] = useState<PlatformContextSearchHit[]>([])
+  const [activeIndex, setActiveIndex] = useState(0)
+  const [searching, setSearching] = useState(false)
+  const requestSeq = useRef(0)
+
+  const runSearch = useCallback(
+    (value: string) => {
+      const seq = ++requestSeq.current
+      setSearching(true)
+      void search(value)
+        .then(results => {
+          if (requestSeq.current !== seq) return
+          setHits(results)
+          setActiveIndex(0)
+        })
+        .catch(() => {
+          if (requestSeq.current !== seq) return
+          setHits([])
+        })
+        .finally(() => {
+          if (requestSeq.current === seq) setSearching(false)
+        })
+    },
+    [search],
+  )
+
+  useEffect(() => {
+    if (!open) return
+    setQuery('')
+    runSearch('')
+  }, [open, runSearch])
+
+  useEffect(() => {
+    if (!open) return
+    const timer = window.setTimeout(() => runSearch(query), 140)
+    return () => window.clearTimeout(timer)
+  }, [open, query, runSearch])
+
+  const pick = useCallback(
+    (hit: PlatformContextSearchHit | undefined) => {
+      if (!hit) return
+      void onPick(hit)
+      onClose()
+    },
+    [onClose, onPick],
+  )
+
+  const onKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        onClose()
+        return
+      }
+      if (event.key === 'ArrowDown') {
+        event.preventDefault()
+        setActiveIndex(index => Math.min(index + 1, hits.length - 1))
+        return
+      }
+      if (event.key === 'ArrowUp') {
+        event.preventDefault()
+        setActiveIndex(index => Math.max(index - 1, 0))
+        return
+      }
+      if (event.key === 'Enter') {
+        event.preventDefault()
+        pick(hits[activeIndex])
+      }
+    },
+    [activeIndex, hits, onClose, pick],
+  )
+
+  if (!open) return null
+
+  return (
+    <Backdrop
+      onMouseDown={event => {
+        if (event.target === event.currentTarget) onClose()
+      }}
+    >
+      <Panel role="dialog" aria-label={title} onKeyDown={onKeyDown}>
+        <PanelTitle>{title}</PanelTitle>
+        <SearchField
+          value={query}
+          onValueChange={setQuery}
+          placeholder={placeholder}
+          autoFocus
+        />
+        <Results role="listbox">
+          {hits.map((hit, index) => (
+            <ResultRow
+              key={hit.packagePath}
+              role="option"
+              aria-selected={index === activeIndex}
+              $active={index === activeIndex}
+              onMouseEnter={() => setActiveIndex(index)}
+              onMouseDown={event => {
+                event.preventDefault()
+                pick(hit)
+              }}
+            >
+              <ResultTitle>{hit.title}</ResultTitle>
+              <KindBadge>{hit.kind}</KindBadge>
+            </ResultRow>
+          ))}
+          {hits.length === 0 ? (
+            <EmptyNote>
+              {searching ? 'Searching…' : 'No matching objects.'}
+            </EmptyNote>
+          ) : null}
+        </Results>
+      </Panel>
+    </Backdrop>
+  )
+}

package/src/components/agents/agentPanelStyles.ts

@@ -23,7 +23,7 @@ export const StyledAgentThreadHost = styled.div`
   width: 100%;
 `
 
-export const StyledAgentScroll = styled.div`
+export const StyledAgentScroll = styled.div<{ $threadHeaderHeight: number }>`
   position: relative;
   min-height: 0;
   display: flex;
@@ -31,7 +31,8 @@ export const StyledAgentScroll = styled.div`
   --platform-agent-thread-header-height: 0px;
 
   &[data-thread-header] {
-    --platform-agent-thread-header-height: 34px;
+    --platform-agent-thread-header-height: ${({ $threadHeaderHeight }) =>
+      $threadHeaderHeight}px;
   }
 `
 

package/src/components/agents/agentTypes.ts

@@ -136,4 +136,6 @@ export interface AgentDrawerPanelProps {
   composerPortaled?: boolean
   /** Shell thread chrome (scope, session actions) — anchored to the message column. */
   threadHeader?: React.ReactNode
+  /** Reserved top space for an absolute thread header. */
+  threadHeaderHeight?: number
 }

package/src/components/chrome/WorkspaceTabStrip.tsx

@@ -169,6 +169,20 @@ const StyledDocName = styled.span`
   color: var(--pure-chrome-tertiary, #8a857c);
 `
 
+const StyledDevBadge = styled.span`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  font-size: 9px;
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--pure-chrome-tertiary, #8a857c);
+  opacity: 0.72;
+`
+
 const StyledClose = styled(X)`
   cursor: pointer;
   opacity: 0.7;
@@ -226,7 +240,7 @@ export function WorkspaceTabStrip({
       <StyledScroll role="tablist" aria-label={ariaLabel}>
         {tabs.map((tab, index) => {
           const active = tab.id === activeTabId
-          const closable = !tab.pinned && onClose
+          const closable = onClose
           return (
             <StyledTab
               key={tab.id}
@@ -306,6 +320,9 @@ export function WorkspaceTabStrip({
                   tab.label
                 )}
               </StyledLabel>
+              {tab.underDevelopment ? (
+                <StyledDevBadge title="Under development">dev</StyledDevBadge>
+              ) : null}
               {closable ? (
                 <StyledClose
                   type="button"

package/src/components/chrome/workspaceTabTypes.ts

@@ -15,6 +15,8 @@ export interface WorkspaceTabItem {
     letter: string
     label?: string
   }
+  /** True while the tab's app is owned by App Builder's dev lifecycle. */
+  underDevelopment?: boolean
   pinned?: boolean
 }
 

package/src/components/common/containers/AppFrame.test.tsx

@@ -62,10 +62,10 @@ describe('AppFrame', () => {
 
     expect(document.getElementById(MENU_PORTAL_ID)).not.toBeNull()
     const baseStyles = document.getElementById(PLATFORM_APP_FRAME_BASE_STYLE_ID)
-    expect(baseStyles).not.toBeNull()
-    expect(baseStyles?.textContent).toContain('box-sizing: border-box')
-    expect(baseStyles?.textContent).toContain('scrollbar-color')
-    expect(document.getElementById(PLATFORM_FONT_STYLESHEET_ID)).not.toBeNull()
+    expect(baseStyles).not.toBeNull()
+    expect(baseStyles?.textContent).toContain('box-sizing: border-box')
+    expect(baseStyles?.textContent).toContain('scrollbar-color')
+    expect(document.getElementById(PLATFORM_FONT_STYLESHEET_ID)).not.toBeNull()
     expect(container.querySelector('[data-app="tasks"]')).not.toBeNull()
     expect(document.documentElement.dataset.app).toBe('tasks')
     expect(container.textContent).toContain('App content')

package/src/components/common/containers/AppFrame.tsx

@@ -15,6 +15,8 @@ export interface AppFrameProps
   themeFromBridge?: boolean
   /** Optional actions rendered in the app header's action slot. */
   headerActions?: ReactNode
+  /** Open document's file name, shown beside the wordmark. */
+  headerDocumentName?: ReactNode
 }
 
 const StyledRoot = styled.div`
@@ -37,6 +39,7 @@ export function AppFrame({
   className,
   themeFromBridge = true,
   headerActions,
+  headerDocumentName,
   ...rest
 }: AppFrameProps): React.ReactElement {
   const { meta, ready } = usePlatformBridge()
@@ -73,7 +76,13 @@ export function AppFrame({
         data-platform-surface-palette={themeAttrs.surfacePalette || undefined}
         {...rest}
       >
-        {manifest && <AppHeader manifest={manifest} actions={headerActions} />}
+        {manifest && (
+          <AppHeader
+            manifest={manifest}
+            actions={headerActions}
+            documentName={headerDocumentName}
+          />
+        )}
         {children}
       </StyledRoot>
     </>