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

package/src/bridge/pureRender/types.ts

@@ -0,0 +1,264 @@
+export type PureRenderProfile = 'writer' | 'manuscript' | 'book'
+
+export interface PureRenderMetadata {
+  title?: string
+  authorsHtml?: string
+  authorsText?: string
+  affiliationsHtml?: string
+  affiliationsText?: string
+  abstractHtml?: string
+  abstractText?: string
+  keywords?: readonly string[]
+  profileLabel?: string
+}
+
+export interface PureRenderOptions {
+  variant?: 'two-column' | string
+  pageSize?: string
+  outline?: boolean
+}
+
+export interface PureRenderRequest {
+  html: string
+  profile: PureRenderProfile
+  theme?: PureRenderTheme
+  metadata?: PureRenderMetadata
+  options?: PureRenderOptions
+}
+
+export interface PureRenderTheme {
+  $schema?: string
+  name: string
+  version: string
+  color: {
+    ink: string
+    'ink-soft': string
+    muted: string
+    surface?: string
+    paper?: string
+    rule: string
+    'rule-soft': string
+    accent: string
+    'accent-ink'?: string
+  }
+  type: {
+    body: string
+    lead: number | string
+    measure: string
+    scaleRatio: number
+    fonts: {
+      display?: string
+      serif: string
+      sans: string
+      mono: string
+    }
+  }
+  rhythm: string
+  page?: {
+    trim?: string
+    margin?: string
+    columns?: number
+    recto_verso?: boolean
+  }
+  setting?: {
+    align?: 'justified' | 'flush-left' | string
+    hyphenate?: boolean
+  }
+  enforced_rules?: readonly string[]
+  profile_rules?: PureRenderProfileRules
+}
+
+export interface PureRenderProfileRules {
+  running_heads?: {
+    presence?: 'present' | 'absent' | string
+    position?: string
+    transform?: 'uppercase' | 'small-caps' | 'title-case' | 'none' | string
+    rule?: 'none' | 'hairline' | 'solid' | string
+    font_role?: 'display' | 'body' | 'caption' | 'sans' | string
+  }
+  folio?: {
+    position?: string
+    style?: 'plain' | 'small-caps' | 'bracketed' | string
+    suppress_on?: readonly string[]
+  }
+  opener?: {
+    spacing?: 'compact' | 'balanced' | 'generous' | string
+    recto_start?: boolean
+    ornament?: 'none' | 'rule' | 'divider' | 'fleuron' | 'chapter-mark' | string
+    drop_cap?: boolean
+  }
+  ornaments?: {
+    kind?: 'none' | 'rule' | 'divider' | 'fleuron' | 'chapter-mark' | string
+    weight?: 'hairline' | 'light' | 'medium' | string
+    placement?: string
+  }
+  table?: {
+    rule_weight?: 'hairline' | 'light' | 'medium' | string
+    header_treatment?: string
+    density?: 'airy' | 'balanced' | 'dense' | string
+  }
+  caption?: {
+    position?: 'above' | 'below' | string
+    label_style?: 'bold' | 'small-caps' | 'plain' | string
+    alignment?: 'left' | 'center' | 'justified' | string
+  }
+}
+
+export interface PureRenderValidationError {
+  code: string
+  message: string
+}
+
+export interface PureRenderNormalizeResult {
+  html: string
+  title: string
+  errors: PureRenderValidationError[]
+}
+
+export interface PrintStyleProfile {
+  schema_version: '1.0' | string
+  sources?: readonly { id: string; note?: string }[]
+  exemplar_quality: {
+    usable: boolean
+    reason: string
+    confidence: number
+  }
+  observations: {
+    palette?: readonly PrintStylePaletteObservation[]
+    type?: readonly PrintStyleTypeObservation[]
+    type_pairing?: PrintStyleTypePairingObservation
+    type_scale?: PrintStyleTypeScaleObservation
+    text_setting?: PrintStyleTextSettingObservation
+    page_model?: PrintStylePageModelObservation
+    running_heads?: PrintStyleRunningHeadsObservation
+    folio?: PrintStyleFolioObservation
+    opener?: PrintStyleOpenerObservation
+    ornaments?: PrintStyleOrnamentObservation
+    table_treatment?: PrintStyleTableTreatmentObservation
+    caption_treatment?: PrintStyleCaptionTreatmentObservation
+    finish?: { register?: string; confidence?: number }
+  }
+  rules?: readonly PrintStyleRule[]
+  derived?: unknown
+}
+
+export interface PrintStylePaletteObservation {
+  role: 'surface' | 'ink' | 'accent' | 'secondary' | string
+  approx_hex?: string
+  coverage?: 'dominant' | 'frequent' | 'sparse' | string
+  where_seen?: string
+  confidence: number
+}
+
+export interface PrintStyleTypeObservation {
+  role: 'display' | 'body' | 'caption' | 'mono' | string
+  class: 'serif' | 'sans' | 'slab' | 'script' | string
+  mood?:
+    | 'old-style'
+    | 'transitional'
+    | 'slab'
+    | 'humanist-sans'
+    | 'grotesque-sans'
+    | 'geometric-sans'
+    | 'mono'
+    | string
+  serif_detail?: 'bracketed' | 'slab' | 'hairline' | 'wedge' | 'none' | string
+  confidence: number
+}
+
+export interface PrintStyleTypePairingObservation {
+  size_contrast?: 'dramatic' | 'moderate' | 'subtle' | string
+  confidence?: number
+}
+
+export interface PrintStyleTypeScaleObservation {
+  body_pt?: number
+  title_scale?: number
+  chapter_title_scale?: number
+  section_scale?: number
+  caption_scale?: number
+  footnote_scale?: number
+  confidence?: number
+}
+
+export interface PrintStyleTextSettingObservation {
+  alignment?: 'justified' | 'flush-left' | string
+  hyphenation?: 'present' | 'absent' | string
+  measure_cpl?: number
+  leading_feel?: 'tight' | 'normal' | 'airy' | string
+  confidence?: number
+}
+
+export interface PrintStylePageModelObservation {
+  columns?: number
+  margin_generosity?: 'tight' | 'moderate' | 'generous' | string
+  margin_asymmetry?: string
+  running_heads?: 'present' | 'absent' | string
+  folio_position?: string
+  caption_position?: 'above' | 'below' | string
+  confidence?: number
+}
+
+export interface PrintStyleRunningHeadsObservation {
+  presence?: 'present' | 'absent' | string
+  position?: string
+  transform?: 'uppercase' | 'small-caps' | 'title-case' | 'none' | string
+  rule?: 'none' | 'hairline' | 'solid' | string
+  font_role?: 'display' | 'body' | 'caption' | 'sans' | string
+  evidence?: string
+  confidence?: number
+}
+
+export interface PrintStyleFolioObservation {
+  position?: string
+  style?: 'plain' | 'small-caps' | 'bracketed' | string
+  suppress_on?: readonly string[]
+  evidence?: string
+  confidence?: number
+}
+
+export interface PrintStyleOpenerObservation {
+  spacing?: 'compact' | 'balanced' | 'generous' | string
+  recto_start?: boolean
+  ornament?: 'none' | 'rule' | 'divider' | 'fleuron' | 'chapter-mark' | string
+  drop_cap?: boolean
+  evidence?: string
+  confidence?: number
+}
+
+export interface PrintStyleOrnamentObservation {
+  kind?: 'none' | 'rule' | 'divider' | 'fleuron' | 'chapter-mark' | string
+  weight?: 'hairline' | 'light' | 'medium' | string
+  placement?: string
+  evidence?: string
+  confidence?: number
+}
+
+export interface PrintStyleTableTreatmentObservation {
+  rule_weight?: 'hairline' | 'light' | 'medium' | string
+  header_treatment?: string
+  row_rules?: 'none' | 'hairline' | 'light' | string
+  density?: 'airy' | 'balanced' | 'dense' | string
+  evidence?: string
+  confidence?: number
+}
+
+export interface PrintStyleCaptionTreatmentObservation {
+  position?: 'above' | 'below' | string
+  label_style?: 'bold' | 'small-caps' | 'plain' | string
+  alignment?: 'left' | 'center' | 'justified' | string
+  evidence?: string
+  confidence?: number
+}
+
+export interface PrintStyleRule {
+  rule: string
+  evidence?: string
+  confidence: number
+}
+
+export interface CompilePrintThemeResult {
+  theme: PureRenderTheme | null
+  decisions: readonly [type: string, message: string][]
+  rules: readonly string[]
+}

package/src/bridge/pureRender/visualLayoutInspection.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { inspectPureRenderVisualLayout } from './visualLayoutInspection.js'
+
+describe('inspectPureRenderVisualLayout', () => {
+  it('observes clean pages without requesting vision review', () => {
+    const result = inspectPureRenderVisualLayout({
+      pageCount: 3,
+      topGapRatio: 0.08,
+      bottomGapRatio: 0.12,
+      usedHeightRatio: 0.8,
+      blankBeforeFigureRatio: 0.1,
+      imageVisible: true,
+      captionOrphaned: false,
+      strandedHeading: false,
+    })
+
+    expect(result.decision).toBe('observe')
+    expect(result.requiresVisionReview).toBe(false)
+    expect(result.issues).toEqual([])
+  })
+
+  it('reuses image break candidate logic for stranded figure pages', () => {
+    const result = inspectPureRenderVisualLayout({
+      pageCount: 5,
+      problemPage: 2,
+      figurePage: 3,
+      imagePage: 3,
+      captionPage: 3,
+      headingPage: 2,
+      blankBeforeFigureRatio: 0.62,
+      imageVisible: true,
+      captionOrphaned: false,
+      strandedHeading: true,
+    })
+
+    expect(result.decision).toBe('rerender-compact-figure-candidate')
+    expect(result.requiresVisionReview).toBe(false)
+    expect(result.issues).toEqual([
+      'large-pre-figure-blank',
+      'stranded-heading',
+    ])
+    expect(result.candidate?.id).toBe('compact-figure')
+  })
+
+  it('rejects caption orphan candidates deterministically', () => {
+    const result = inspectPureRenderVisualLayout({
+      imagePage: 2,
+      captionPage: 3,
+      imageVisible: true,
+      captionOrphaned: true,
+    })
+
+    expect(result.decision).toBe('reject-candidate')
+    expect(result.requiresVisionReview).toBe(false)
+    expect(result.issues).toContain('caption-orphan')
+  })
+})

package/src/bridge/pureRender/visualLayoutInspection.ts

@@ -0,0 +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))
+}

package/src/bridge/react/useDebouncedEffect.ts

@@ -0,0 +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])
+}

package/src/bridge/react/useIpc.tsx

@@ -0,0 +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 }
+}

package/src/bridge/react/usePlatformAgentRunLiveState.tsx

@@ -0,0 +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,
+  }
+}