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

package/src/bridge/pureRender/visualLayoutInspection.ts

@@ -1,161 +1,161 @@
-export type PureRenderVisualIssue =
-  | 'large-pre-figure-blank'
-  | 'sparse-sample-page'
-  | 'stranded-heading'
-  | 'caption-orphan'
-  | 'image-not-visible-on-risk-page'
-  | 'blank-page'
-
-export type PureRenderVisualDecision =
-  | 'observe'
-  | 'rerender-candidate'
-  | 'rerender-compact-figure-candidate'
-  | 'reject-candidate'
-  | 'accept-candidate-for-review'
-  | 'needs-vision-review'
-
-export interface PureRenderVisualLayoutMetrics {
-  pageCount?: number
-  problemPage?: number
-  figurePage?: number
-  imagePage?: number
-  captionPage?: number
-  headingPage?: number
-  blankBeforeFigurePx?: number
-  blankBeforeFigureRatio?: number
-  blankPageCount?: number
-  imageVisible?: boolean
-  captionVisible?: boolean
-  captionOrphaned?: boolean
-  strandedHeading?: boolean | null
-  topGapRatio?: number
-  bottomGapRatio?: number
-  usedHeightRatio?: number
-}
-
-export interface PureRenderVisualCandidate {
-  id: string
-  label: string
-  summary: string
-  cssPatch?: string
-}
-
-export interface PureRenderVisualInspection {
-  decision: PureRenderVisualDecision
-  recommendation: string
-  requiresUserReview: boolean
-  requiresVisionReview: boolean
-  issues: PureRenderVisualIssue[]
-  metrics: PureRenderVisualLayoutMetrics
-  candidate?: PureRenderVisualCandidate
-}
-
-const LARGE_PRE_FIGURE_BLANK_RATIO = 0.5
-const SPARSE_PAGE_USED_HEIGHT_RATIO = 0.25
-const LARGE_BOTTOM_GAP_RATIO = 0.55
-
-export function inspectPureRenderVisualLayout(
-  metrics: PureRenderVisualLayoutMetrics | undefined,
-): PureRenderVisualInspection {
-  const normalized = metrics ?? {}
-  const issues = visualIssuesForMetrics(normalized)
-  const hasIssue = issues.length > 0
-  const hasHardFailure =
-    issues.includes('caption-orphan') ||
-    issues.includes('image-not-visible-on-risk-page')
-  const canTryCompactFigure =
-    issues.includes('large-pre-figure-blank') ||
-    issues.includes('stranded-heading') ||
-    issues.includes('image-not-visible-on-risk-page')
-
-  if (!hasIssue) {
-    return {
-      decision: 'observe',
-      recommendation:
-        'No deterministic visual layout issue was detected on the sampled Paged.js output.',
-      requiresUserReview: false,
-      requiresVisionReview: false,
-      issues,
-      metrics: normalized,
-    }
-  }
-
-  if (hasHardFailure && issues.includes('caption-orphan')) {
-    return {
-      decision: 'reject-candidate',
-      recommendation:
-        'Reject this placement: the caption appears detached from its figure.',
-      requiresUserReview: true,
-      requiresVisionReview: false,
-      issues,
-      metrics: normalized,
-    }
-  }
-
-  if (canTryCompactFigure) {
-    return {
-      decision: 'rerender-compact-figure-candidate',
-      recommendation:
-        'Try a compact figure candidate before promoting any shared CSS change; the current page appears to strand a heading, hide a figure, or leave a large pre-figure blank.',
-      requiresUserReview: true,
-      requiresVisionReview: false,
-      issues,
-      metrics: normalized,
-      candidate: {
-        id: 'compact-figure',
-        label: 'Compact figure candidate',
-        summary:
-          'Cap figure media height and keep the caption attached so the next render can be compared against the current page.',
-        cssPatch:
-          'figure { break-inside: avoid; } figure img, figure svg { max-height: 72mm; object-fit: contain; margin-left: auto; margin-right: auto; }',
-      },
-    }
-  }
-
-  return {
-    decision: 'rerender-candidate',
-    recommendation:
-      'Try an alternate placement candidate and compare screenshots before changing production CSS.',
-    requiresUserReview: true,
-    requiresVisionReview: true,
-    issues,
-    metrics: normalized,
-  }
-}
-
-export function visualIssuesForMetrics(
-  metrics: PureRenderVisualLayoutMetrics,
-): PureRenderVisualIssue[] {
-  const issues: PureRenderVisualIssue[] = []
-  if (
-    typeof metrics.blankBeforeFigureRatio === 'number' &&
-    metrics.blankBeforeFigureRatio >= LARGE_PRE_FIGURE_BLANK_RATIO
-  ) {
-    issues.push('large-pre-figure-blank')
-  }
-  if (
-    typeof metrics.usedHeightRatio === 'number' &&
-    metrics.usedHeightRatio < SPARSE_PAGE_USED_HEIGHT_RATIO
-  ) {
-    issues.push('sparse-sample-page')
-  } else if (
-    typeof metrics.bottomGapRatio === 'number' &&
-    metrics.bottomGapRatio > LARGE_BOTTOM_GAP_RATIO &&
-    metrics.imageVisible === false
-  ) {
-    issues.push('sparse-sample-page')
-  }
-  if ((metrics.blankPageCount ?? 0) > 0) {
-    issues.push('blank-page')
-  }
-  if (metrics.strandedHeading === true) {
-    issues.push('stranded-heading')
-  }
-  if (metrics.captionOrphaned === true) {
-    issues.push('caption-orphan')
-  }
-  if (metrics.imageVisible === false) {
-    issues.push('image-not-visible-on-risk-page')
-  }
-  return Array.from(new Set(issues))
-}
+export type PureRenderVisualIssue =
+  | 'large-pre-figure-blank'
+  | 'sparse-sample-page'
+  | 'stranded-heading'
+  | 'caption-orphan'
+  | 'image-not-visible-on-risk-page'
+  | 'blank-page'
+
+export type PureRenderVisualDecision =
+  | 'observe'
+  | 'rerender-candidate'
+  | 'rerender-compact-figure-candidate'
+  | 'reject-candidate'
+  | 'accept-candidate-for-review'
+  | 'needs-vision-review'
+
+export interface PureRenderVisualLayoutMetrics {
+  pageCount?: number
+  problemPage?: number
+  figurePage?: number
+  imagePage?: number
+  captionPage?: number
+  headingPage?: number
+  blankBeforeFigurePx?: number
+  blankBeforeFigureRatio?: number
+  blankPageCount?: number
+  imageVisible?: boolean
+  captionVisible?: boolean
+  captionOrphaned?: boolean
+  strandedHeading?: boolean | null
+  topGapRatio?: number
+  bottomGapRatio?: number
+  usedHeightRatio?: number
+}
+
+export interface PureRenderVisualCandidate {
+  id: string
+  label: string
+  summary: string
+  cssPatch?: string
+}
+
+export interface PureRenderVisualInspection {
+  decision: PureRenderVisualDecision
+  recommendation: string
+  requiresUserReview: boolean
+  requiresVisionReview: boolean
+  issues: PureRenderVisualIssue[]
+  metrics: PureRenderVisualLayoutMetrics
+  candidate?: PureRenderVisualCandidate
+}
+
+const LARGE_PRE_FIGURE_BLANK_RATIO = 0.5
+const SPARSE_PAGE_USED_HEIGHT_RATIO = 0.25
+const LARGE_BOTTOM_GAP_RATIO = 0.55
+
+export function inspectPureRenderVisualLayout(
+  metrics: PureRenderVisualLayoutMetrics | undefined,
+): PureRenderVisualInspection {
+  const normalized = metrics ?? {}
+  const issues = visualIssuesForMetrics(normalized)
+  const hasIssue = issues.length > 0
+  const hasHardFailure =
+    issues.includes('caption-orphan') ||
+    issues.includes('image-not-visible-on-risk-page')
+  const canTryCompactFigure =
+    issues.includes('large-pre-figure-blank') ||
+    issues.includes('stranded-heading') ||
+    issues.includes('image-not-visible-on-risk-page')
+
+  if (!hasIssue) {
+    return {
+      decision: 'observe',
+      recommendation:
+        'No deterministic visual layout issue was detected on the sampled Paged.js output.',
+      requiresUserReview: false,
+      requiresVisionReview: false,
+      issues,
+      metrics: normalized,
+    }
+  }
+
+  if (hasHardFailure && issues.includes('caption-orphan')) {
+    return {
+      decision: 'reject-candidate',
+      recommendation:
+        'Reject this placement: the caption appears detached from its figure.',
+      requiresUserReview: true,
+      requiresVisionReview: false,
+      issues,
+      metrics: normalized,
+    }
+  }
+
+  if (canTryCompactFigure) {
+    return {
+      decision: 'rerender-compact-figure-candidate',
+      recommendation:
+        'Try a compact figure candidate before promoting any shared CSS change; the current page appears to strand a heading, hide a figure, or leave a large pre-figure blank.',
+      requiresUserReview: true,
+      requiresVisionReview: false,
+      issues,
+      metrics: normalized,
+      candidate: {
+        id: 'compact-figure',
+        label: 'Compact figure candidate',
+        summary:
+          'Cap figure media height and keep the caption attached so the next render can be compared against the current page.',
+        cssPatch:
+          'figure { break-inside: avoid; } figure img, figure svg { max-height: 72mm; object-fit: contain; margin-left: auto; margin-right: auto; }',
+      },
+    }
+  }
+
+  return {
+    decision: 'rerender-candidate',
+    recommendation:
+      'Try an alternate placement candidate and compare screenshots before changing production CSS.',
+    requiresUserReview: true,
+    requiresVisionReview: true,
+    issues,
+    metrics: normalized,
+  }
+}
+
+export function visualIssuesForMetrics(
+  metrics: PureRenderVisualLayoutMetrics,
+): PureRenderVisualIssue[] {
+  const issues: PureRenderVisualIssue[] = []
+  if (
+    typeof metrics.blankBeforeFigureRatio === 'number' &&
+    metrics.blankBeforeFigureRatio >= LARGE_PRE_FIGURE_BLANK_RATIO
+  ) {
+    issues.push('large-pre-figure-blank')
+  }
+  if (
+    typeof metrics.usedHeightRatio === 'number' &&
+    metrics.usedHeightRatio < SPARSE_PAGE_USED_HEIGHT_RATIO
+  ) {
+    issues.push('sparse-sample-page')
+  } else if (
+    typeof metrics.bottomGapRatio === 'number' &&
+    metrics.bottomGapRatio > LARGE_BOTTOM_GAP_RATIO &&
+    metrics.imageVisible === false
+  ) {
+    issues.push('sparse-sample-page')
+  }
+  if ((metrics.blankPageCount ?? 0) > 0) {
+    issues.push('blank-page')
+  }
+  if (metrics.strandedHeading === true) {
+    issues.push('stranded-heading')
+  }
+  if (metrics.captionOrphaned === true) {
+    issues.push('caption-orphan')
+  }
+  if (metrics.imageVisible === false) {
+    issues.push('image-not-visible-on-risk-page')
+  }
+  return Array.from(new Set(issues))
+}

package/src/bridge/react/useDebouncedEffect.ts

@@ -1,21 +1,21 @@
-import { useEffect, useRef } from 'react'
-
-/**
- * Run an effect after `delayMs` when `deps` change (leading edge cancelled).
- * Shared by host workspace persist and other bridge clients.
- */
-export function useDebouncedEffect(
-  effect: () => void | (() => void),
-  deps: React.DependencyList,
-  delayMs: number,
-): void {
-  const effectRef = useRef(effect)
-  effectRef.current = effect
-
-  useEffect(() => {
-    const timeout = window.setTimeout(() => {
-      return effectRef.current()
-    }, delayMs)
-    return () => window.clearTimeout(timeout)
-  }, [delayMs, ...deps])
-}
+import { useEffect, useRef } from 'react'
+
+/**
+ * Run an effect after `delayMs` when `deps` change (leading edge cancelled).
+ * Shared by host workspace persist and other bridge clients.
+ */
+export function useDebouncedEffect(
+  effect: () => void | (() => void),
+  deps: React.DependencyList,
+  delayMs: number,
+): void {
+  const effectRef = useRef(effect)
+  effectRef.current = effect
+
+  useEffect(() => {
+    const timeout = window.setTimeout(() => {
+      return effectRef.current()
+    }, delayMs)
+    return () => window.clearTimeout(timeout)
+  }, [delayMs, ...deps])
+}

package/src/bridge/react/useIpc.tsx

@@ -1,75 +1,75 @@
-import { useCallback, useEffect, useState, type DependencyList } from 'react'
-
-export interface UseIpcOptions {
-  /** When false, skip the request and leave loading false (default true). */
-  enabled?: boolean
-}
-
-export interface UseIpcResult<T> {
-  data: T | null
-  error: Error | null
-  loading: boolean
-  /** Re-run the request (increments an internal reload token). */
-  reload: () => void
-}
-
-/**
- * Run an async loader in `useEffect` with cancellation-safe setState.
- *
- * Plugin apps use this for bridge / lib calls — not Electron IPC directly.
- * Same pattern as ps-book `useIpc`, adapted for `@purescience/platform-ui`.
- *
- * @example
- * const { data: entries, error, loading, reload } = useIpc(
- *   () => listBookRegistry(),
- *   [],
- * )
- */
-export function useIpc<T>(
-  fn: () => Promise<T>,
-  deps: DependencyList,
-  options: UseIpcOptions = {},
-): UseIpcResult<T> {
-  const enabled = options.enabled ?? true
-  const [data, setData] = useState<T | null>(null)
-  const [error, setError] = useState<Error | null>(null)
-  const [loading, setLoading] = useState(false)
-  const [reloadToken, setReloadToken] = useState(0)
-
-  const reload = useCallback(() => {
-    setReloadToken(token => token + 1)
-  }, [])
-
-  useEffect(() => {
-    if (!enabled) return
-
-    let cancelled = false
-    setLoading(true)
-    setError(null)
-
-    async function load(): Promise<void> {
-      try {
-        const result = await fn()
-        if (cancelled) return
-        setData(result)
-        setError(null)
-      } catch (cause) {
-        if (cancelled) return
-        setData(null)
-        setError(cause instanceof Error ? cause : new Error(String(cause)))
-      } finally {
-        if (!cancelled) setLoading(false)
-      }
-    }
-
-    void load()
-
-    return () => {
-      cancelled = true
-    }
-    // fn is intentionally excluded — callers list stable deps (paths, slugs, …).
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [enabled, reloadToken, ...deps])
-
-  return { data, error, loading, reload }
-}
+import { useCallback, useEffect, useState, type DependencyList } from 'react'
+
+export interface UseIpcOptions {
+  /** When false, skip the request and leave loading false (default true). */
+  enabled?: boolean
+}
+
+export interface UseIpcResult<T> {
+  data: T | null
+  error: Error | null
+  loading: boolean
+  /** Re-run the request (increments an internal reload token). */
+  reload: () => void
+}
+
+/**
+ * Run an async loader in `useEffect` with cancellation-safe setState.
+ *
+ * Plugin apps use this for bridge / lib calls — not Electron IPC directly.
+ * Same pattern as ps-book `useIpc`, adapted for `@purescience/platform-ui`.
+ *
+ * @example
+ * const { data: entries, error, loading, reload } = useIpc(
+ *   () => listBookRegistry(),
+ *   [],
+ * )
+ */
+export function useIpc<T>(
+  fn: () => Promise<T>,
+  deps: DependencyList,
+  options: UseIpcOptions = {},
+): UseIpcResult<T> {
+  const enabled = options.enabled ?? true
+  const [data, setData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [reloadToken, setReloadToken] = useState(0)
+
+  const reload = useCallback(() => {
+    setReloadToken(token => token + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!enabled) return
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    async function load(): Promise<void> {
+      try {
+        const result = await fn()
+        if (cancelled) return
+        setData(result)
+        setError(null)
+      } catch (cause) {
+        if (cancelled) return
+        setData(null)
+        setError(cause instanceof Error ? cause : new Error(String(cause)))
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+
+    void load()
+
+    return () => {
+      cancelled = true
+    }
+    // fn is intentionally excluded — callers list stable deps (paths, slugs, …).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, reloadToken, ...deps])
+
+  return { data, error, loading, reload }
+}

package/src/bridge/react/usePlatformAgentRunLiveState.tsx

@@ -1,78 +1,78 @@
-import { useCallback, useEffect, useState } from 'react'
-import {
-  AgentRunEventType,
-  createIdleLiveTurn,
-  mergeUsageTurn,
-  reduceAgentLiveTurn,
-  type PlatformAgentRunEventPayload,
-} from '../../agents/runtime/index.js'
-import type { PlatformAgentRunSnapshot } from '../agentTypes.js'
-import { onAgentRunEvent } from '../agents.mjs'
-import type { AgentLiveTurn } from '../../components/agents/agentTypes.js'
-
-/** Subscribe to bridge run events for one runId (streaming overlay + usage). */
-export function usePlatformAgentRunLiveState(runId: string | undefined): {
-  liveRunSnapshot: PlatformAgentRunSnapshot | null
-  liveTurn: AgentLiveTurn
-  applySnapshot: (snapshot: PlatformAgentRunSnapshot) => void
-  resetLiveState: () => void
-} {
-  const [liveRunSnapshot, setLiveRunSnapshot] =
-    useState<PlatformAgentRunSnapshot | null>(null)
-  const [liveTurn, setLiveTurn] = useState<AgentLiveTurn>(createIdleLiveTurn)
-
-  const applySnapshot = useCallback((snapshot: PlatformAgentRunSnapshot) => {
-    setLiveRunSnapshot(snapshot)
-  }, [])
-
-  const resetLiveState = useCallback(() => {
-    setLiveRunSnapshot(null)
-    setLiveTurn(createIdleLiveTurn())
-  }, [])
-
-  useEffect(() => {
-    if (!runId) {
-      setLiveRunSnapshot(null)
-      setLiveTurn(createIdleLiveTurn())
-      return
-    }
-
-    let live = createIdleLiveTurn()
-
-    const unsubscribe = onAgentRunEvent(event => {
-      const payload = event as PlatformAgentRunEventPayload
-      if (payload.runId !== runId) return
-
-      if (
-        payload.type === AgentRunEventType.StateChanged &&
-        'snapshot' in payload
-      ) {
-        setLiveRunSnapshot(payload.snapshot)
-      }
-
-      if (payload.type === AgentRunEventType.UsageUpdated && 'usage' in payload) {
-        setLiveRunSnapshot(current => {
-          if (!current) return current
-          const usage = mergeUsageTurn(
-            current.usage,
-            payload.usage,
-            payload.estimated,
-          )
-          return { ...current, usage }
-        })
-      }
-
-      live = reduceAgentLiveTurn(live, payload)
-      setLiveTurn(live)
-    })
-
-    return unsubscribe
-  }, [runId])
-
-  return {
-    liveRunSnapshot,
-    liveTurn,
-    applySnapshot,
-    resetLiveState,
-  }
-}
+import { useCallback, useEffect, useState } from 'react'
+import {
+  AgentRunEventType,
+  createIdleLiveTurn,
+  mergeUsageTurn,
+  reduceAgentLiveTurn,
+  type PlatformAgentRunEventPayload,
+} from '../../agents/runtime/index.js'
+import type { PlatformAgentRunSnapshot } from '../agentTypes.js'
+import { onAgentRunEvent } from '../agents.mjs'
+import type { AgentLiveTurn } from '../../components/agents/agentTypes.js'
+
+/** Subscribe to bridge run events for one runId (streaming overlay + usage). */
+export function usePlatformAgentRunLiveState(runId: string | undefined): {
+  liveRunSnapshot: PlatformAgentRunSnapshot | null
+  liveTurn: AgentLiveTurn
+  applySnapshot: (snapshot: PlatformAgentRunSnapshot) => void
+  resetLiveState: () => void
+} {
+  const [liveRunSnapshot, setLiveRunSnapshot] =
+    useState<PlatformAgentRunSnapshot | null>(null)
+  const [liveTurn, setLiveTurn] = useState<AgentLiveTurn>(createIdleLiveTurn)
+
+  const applySnapshot = useCallback((snapshot: PlatformAgentRunSnapshot) => {
+    setLiveRunSnapshot(snapshot)
+  }, [])
+
+  const resetLiveState = useCallback(() => {
+    setLiveRunSnapshot(null)
+    setLiveTurn(createIdleLiveTurn())
+  }, [])
+
+  useEffect(() => {
+    if (!runId) {
+      setLiveRunSnapshot(null)
+      setLiveTurn(createIdleLiveTurn())
+      return
+    }
+
+    let live = createIdleLiveTurn()
+
+    const unsubscribe = onAgentRunEvent(event => {
+      const payload = event as PlatformAgentRunEventPayload
+      if (payload.runId !== runId) return
+
+      if (
+        payload.type === AgentRunEventType.StateChanged &&
+        'snapshot' in payload
+      ) {
+        setLiveRunSnapshot(payload.snapshot)
+      }
+
+      if (payload.type === AgentRunEventType.UsageUpdated && 'usage' in payload) {
+        setLiveRunSnapshot(current => {
+          if (!current) return current
+          const usage = mergeUsageTurn(
+            current.usage,
+            payload.usage,
+            payload.estimated,
+          )
+          return { ...current, usage }
+        })
+      }
+
+      live = reduceAgentLiveTurn(live, payload)
+      setLiveTurn(live)
+    })
+
+    return unsubscribe
+  }, [runId])
+
+  return {
+    liveRunSnapshot,
+    liveTurn,
+    applySnapshot,
+    resetLiveState,
+  }
+}