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

package/src/writing/condenseWritingStyle.ts

@@ -0,0 +1,103 @@
+import {
+  callAgentRunModel,
+  createAgentSession,
+  deleteAgentSession,
+  startAgentRun,
+} from '../bridge/agents.js'
+
+interface AgentSessionRecord {
+  sessionId: string
+  config: { modelId: string }
+}
+
+interface AgentRunSnapshot {
+  runId: string
+  state: string
+  messages: Array<{ role: string; content: string }>
+  error?: string
+}
+
+const MAX_TURNS = 4
+
+const SYSTEM_PROMPT = [
+  'You distill writing-style guidance into a compact, reusable style guide.',
+  'Capture VOICE only — tone, register, sentence rhythm, word choice, and structural habits.',
+  'Output 4–8 short imperative bullet lines, each starting with "- ".',
+  'If the guidance lists words or phrases to PREFER or to AVOID, keep them verbatim as their own "- Prefer: …" and "- Avoid: …" bullets (these are in addition to the 4–8 voice bullets).',
+  'Do NOT include the sample text, its facts, or its subject matter.',
+  'Return plain text only — no preamble, no headings, no commentary.',
+].join('\n')
+
+function latestAssistant(snapshot: AgentRunSnapshot): string {
+  return (
+    [...snapshot.messages]
+      .reverse()
+      .find(message => message.role === 'assistant')
+      ?.content.trim() ?? ''
+  )
+}
+
+/**
+ * Distill verbose style guidance (presets + voice samples) into a short,
+ * reusable style guide — the book's "style skill". Sent once and reused for
+ * every chapter draft/edit instead of the full samples, to save tokens.
+ * Falls back to the original guidance if the model is unavailable.
+ */
+export async function condenseWritingStyleWithAgent(
+  fullGuidance: string,
+): Promise<string> {
+  const trimmed = fullGuidance.trim()
+  if (!trimmed) return ''
+
+  let session: AgentSessionRecord | null = null
+  try {
+    session = (await createAgentSession({
+      scope: 'app',
+      appSlug: 'book',
+      title: 'Condense writing style',
+      config: {
+        sessionPrompt: SYSTEM_PROMPT,
+        toolPolicy: {
+          allowedTargetApps: ['__purebook_style_no_tools__'],
+          defaultRequiresApproval: true,
+        },
+      } as never,
+    })) as AgentSessionRecord
+
+    let snapshot = (await startAgentRun({
+      session: { scope: 'app', sessionId: session.sessionId, appSlug: 'book' },
+      message: trimmed,
+    })) as AgentRunSnapshot
+
+    for (let turn = 0; turn < MAX_TURNS; turn += 1) {
+      if (snapshot.state === 'ready') {
+        snapshot = (await callAgentRunModel({
+          runId: snapshot.runId,
+          sessionId: session.sessionId,
+        })) as AgentRunSnapshot
+        continue
+      }
+      break
+    }
+
+    if (snapshot.state === 'awaiting_user') {
+      const condensed = latestAssistant(snapshot)
+      if (condensed) return condensed
+    }
+    return trimmed
+  } catch {
+    return trimmed
+  } finally {
+    if (session) {
+      try {
+        await deleteAgentSession({
+          scope: 'app',
+          sessionId: session.sessionId,
+          appSlug: 'book',
+        })
+      } catch {
+        /* best-effort cleanup */
+      }
+    }
+  }
+}

package/src/writing/draftTextWithAgent.ts

@@ -0,0 +1,134 @@
+import {
+  callAgentRunModel,
+  createAgentSession,
+  deleteAgentSession,
+  startAgentRun,
+} from '../bridge/agents.js'
+
+interface AgentSessionRecord {
+  sessionId: string
+  config: { modelId: string }
+}
+
+interface AgentRunSnapshot {
+  runId: string
+  state: string
+  messages: Array<{ role: string; content: string }>
+  error?: string
+}
+
+const MAX_TURNS = 4
+
+export type DraftTextMode = 'write' | 'rewrite'
+
+export interface DraftTextInput {
+  mode: DraftTextMode
+  instruction: string
+  selectionText?: string
+  styleGuidance?: string
+  /**
+   * Grounding/reference material (e.g. a manuscript's abstract and reference
+   * list). Used for ACCURACY — facts, terminology, claims — not for voice.
+   */
+  context?: string
+}
+
+function systemPrompt(mode: DraftTextMode): string {
+  return [
+    mode === 'rewrite'
+      ? 'You rewrite a passage of a book to the author’s instruction, preserving its meaning.'
+      : 'You draft a passage of book prose from the author’s instruction.',
+    'Return clean HTML only — paragraphs <p>, sub-headings <h2>, lists where useful.',
+    'No markdown, no code fences, no <h1>, no preamble, no commentary.',
+    'Do not invent precise statistics, dates, quotations, or citations.',
+  ].join('\n')
+}
+
+function message(input: DraftTextInput): string {
+  return [
+    input.mode === 'rewrite' && input.selectionText
+      ? `Passage to rewrite:\n"""${input.selectionText.slice(0, 6000)}"""`
+      : input.selectionText
+        ? `Nearby text for context (do not repeat):\n"""${input.selectionText.slice(0, 2000)}"""`
+        : '',
+    `Instruction: ${input.instruction.trim() || (input.mode === 'rewrite' ? 'Improve this passage.' : 'Draft this.')}`,
+    input.context?.trim()
+      ? `\nReference material — use it for facts, terminology, and claims; do NOT copy its wording as voice and do NOT invent beyond it:\n"""${input.context.trim().slice(0, 4000)}"""`
+      : '',
+    input.styleGuidance ? `\n${input.styleGuidance}` : '',
+    '',
+    'Return the HTML now.',
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+function cleanHtml(raw: string): string {
+  let value = raw.trim()
+  value = value.replace(/^```(?:html)?\s*/i, '').replace(/\s*```$/i, '')
+  value = value.replace(/<h1[\s\S]*?<\/h1>/gi, '')
+  return value.trim()
+}
+
+function latestAssistant(snapshot: AgentRunSnapshot): string {
+  return (
+    [...snapshot.messages]
+      .reverse()
+      .find(entry => entry.role === 'assistant')
+      ?.content.trim() ?? ''
+  )
+}
+
+/** Draft or rewrite a passage via the agent. Returns HTML (empty on failure). */
+export async function draftTextWithAgent(
+  input: DraftTextInput,
+): Promise<string> {
+  let session: AgentSessionRecord | null = null
+  try {
+    session = (await createAgentSession({
+      scope: 'app',
+      appSlug: 'book',
+      title: 'Draft passage',
+      config: {
+        sessionPrompt: systemPrompt(input.mode),
+        toolPolicy: {
+          allowedTargetApps: ['__purebook_draft_text_no_tools__'],
+          defaultRequiresApproval: true,
+        },
+      } as never,
+    })) as AgentSessionRecord
+
+    let snapshot = (await startAgentRun({
+      session: { scope: 'app', sessionId: session.sessionId, appSlug: 'book' },
+      message: message(input),
+    })) as AgentRunSnapshot
+
+    for (let turn = 0; turn < MAX_TURNS; turn += 1) {
+      if (snapshot.state === 'ready') {
+        snapshot = (await callAgentRunModel({
+          runId: snapshot.runId,
+          sessionId: session.sessionId,
+        })) as AgentRunSnapshot
+        continue
+      }
+      break
+    }
+
+    if (snapshot.state === 'awaiting_user') {
+      return cleanHtml(latestAssistant(snapshot))
+    }
+    throw new Error(snapshot.error || `The model stopped at ${snapshot.state}.`)
+  } finally {
+    if (session) {
+      try {
+        await deleteAgentSession({
+          scope: 'app',
+          sessionId: session.sessionId,
+          appSlug: 'book',
+        })
+      } catch {
+        /* best-effort cleanup */
+      }
+    }
+  }
+}

package/src/writing/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Reusable writing-style + AI drafting toolkit.
+ *
+ * App-agnostic: the host owns persistence of the style library (pass `styles`
+ * and `onStylesChange`); everything else — the named-style manager, the
+ * "distill into skill" flow, and the draft/redraft dialog — lives here so any
+ * app can adopt it.
+ */
+
+export {
+  DraftAssistantDialog,
+  type DraftAssistantDialogProps,
+} from './DraftAssistantDialog.js'
+export {
+  WritingStyleManager,
+  type WritingStyleManagerProps,
+} from './WritingStyleManager.js'
+export {
+  draftTextWithAgent,
+  type DraftTextInput,
+  type DraftTextMode,
+} from './draftTextWithAgent.js'
+export { condenseWritingStyleWithAgent } from './condenseWritingStyle.js'
+export {
+  loadSharedWritingStyles,
+  saveSharedWritingStyles,
+} from './styleStore.js'
+export {
+  EMPTY_WRITING_STYLE,
+  buildStyleGuidance,
+  createStyleSource,
+  createWritingStyle,
+  normalizeWritingStyle,
+  styleHasContent,
+  styleRawGuidance,
+  type BookWritingStyle,
+  type StyleSource,
+  type WritingStyle,
+} from './writingStyle.js'

package/src/writing/styleStore.ts

@@ -0,0 +1,32 @@
+import { bridge, PLATFORM_BRIDGE_METHODS } from '../bridge/client.mjs'
+import { normalizeWritingStyle, type BookWritingStyle } from './writingStyle.js'
+
+/**
+ * Shared writing-style library — ONE set of named styles across every app.
+ *
+ * Stored as a single JSON file in the suite data dir (`~/PureScience/`), so a
+ * style created (and distilled) in one app is available in all of them. The
+ * bridge requires an appSlug but does not use it to scope the path, so every
+ * app that reads/writes this filename shares the same library.
+ */
+const STORAGE_SLUG = 'writing'
+const STORAGE_FILE = 'writing-styles.json'
+
+export async function loadSharedWritingStyles(): Promise<BookWritingStyle> {
+  try {
+    const result = (await bridge.call(PLATFORM_BRIDGE_METHODS.STORAGE_READ_JSON, [
+      { appSlug: STORAGE_SLUG, fileName: STORAGE_FILE },
+    ])) as { value?: unknown } | null
+    return normalizeWritingStyle(result?.value)
+  } catch {
+    return normalizeWritingStyle(null)
+  }
+}
+
+export async function saveSharedWritingStyles(
+  style: BookWritingStyle,
+): Promise<void> {
+  await bridge.call(PLATFORM_BRIDGE_METHODS.STORAGE_WRITE_JSON, [
+    { appSlug: STORAGE_SLUG, fileName: STORAGE_FILE, value: style },
+  ])
+}

package/src/writing/writingStyle.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildStyleGuidance,
+  createWritingStyle,
+  normalizeWritingStyle,
+  styleHasContent,
+  type WritingStyle,
+} from './writingStyle.js'
+
+function styleWith(overrides: Partial<WritingStyle>): WritingStyle {
+  return { ...createWritingStyle('Test'), ...overrides }
+}
+
+describe('normalizeWritingStyle', () => {
+  it('returns an empty library for junk input', () => {
+    expect(normalizeWritingStyle(undefined)).toEqual({ styles: [] })
+    expect(normalizeWritingStyle({})).toEqual({ styles: [] })
+    expect(normalizeWritingStyle({ styles: 'nope' })).toEqual({ styles: [] })
+  })
+
+  it('keeps current-shape styles and drops empty ones', () => {
+    const { styles } = normalizeWritingStyle({
+      styles: [
+        { id: 'a', name: 'Docs', sources: [{ id: 's', label: 'x', text: 'hi' }] },
+        { id: 'b', name: 'Empty', sources: [], notes: '', skill: '' },
+        { id: 'c', name: 'Notes only', notes: 'be terse' },
+      ],
+    })
+    expect(styles.map(style => style.name)).toEqual(['Docs', 'Notes only'])
+  })
+
+  it('migrates legacy { examples } samples into styles', () => {
+    const { styles } = normalizeWritingStyle({
+      presets: ['academic'],
+      examples: [{ id: 'e1', label: 'My essays', text: 'A sample paragraph.' }],
+    })
+    expect(styles).toHaveLength(1)
+    expect(styles[0].name).toBe('My essays')
+    expect(styles[0].sources[0].text).toBe('A sample paragraph.')
+    // Legacy generic presets are intentionally discarded.
+    expect(styles[0]).not.toHaveProperty('presets')
+  })
+
+  it('disables a skill flag when there is no skill text', () => {
+    const { styles } = normalizeWritingStyle({
+      styles: [{ id: 'a', name: 'X', notes: 'n', skill: '', skillEnabled: true }],
+    })
+    expect(styles[0].skillEnabled).toBe(false)
+  })
+})
+
+describe('styleHasContent', () => {
+  it('is false for an empty style and true once it has sources/notes/skill', () => {
+    expect(styleHasContent(createWritingStyle())).toBe(false)
+    expect(styleHasContent(styleWith({ notes: 'be terse' }))).toBe(true)
+    expect(styleHasContent(styleWith({ skill: '- be terse' }))).toBe(true)
+  })
+})
+
+describe('buildStyleGuidance', () => {
+  it('returns undefined when nothing is selected', () => {
+    expect(buildStyleGuidance([])).toBeUndefined()
+    expect(buildStyleGuidance([createWritingStyle()])).toBeUndefined()
+  })
+
+  it('uses the distilled skill when enabled', () => {
+    const guidance = buildStyleGuidance([
+      styleWith({
+        name: 'Docs',
+        notes: 'raw notes that should be hidden',
+        skill: '- short sentences\n- active voice',
+        skillEnabled: true,
+      }),
+    ])
+    expect(guidance).toContain('Style — Docs:')
+    expect(guidance).toContain('short sentences')
+    expect(guidance).not.toContain('raw notes that should be hidden')
+  })
+
+  it('falls back to raw notes + voice-only samples when no skill is enabled', () => {
+    const guidance = buildStyleGuidance([
+      styleWith({
+        name: 'Fiction',
+        notes: 'lyrical',
+        sources: [{ id: 's', label: 'novel', text: 'Once upon a time.' }],
+        skill: '- ignored because disabled',
+        skillEnabled: false,
+      }),
+    ])
+    expect(guidance).toContain('Guidance: lyrical')
+    expect(guidance).toContain('Match the VOICE')
+    expect(guidance).toContain('Once upon a time.')
+    expect(guidance).not.toContain('ignored because disabled')
+  })
+
+  it('emits prefer/avoid word lists, normalising separators', () => {
+    const guidance = buildStyleGuidance([
+      styleWith({
+        name: 'Docs',
+        include: 'reader,  cohort\nmodule',
+        exclude: 'utilise, leverage',
+      }),
+    ])
+    expect(guidance).toContain('Prefer these words and phrases')
+    expect(guidance).toContain('reader, cohort, module')
+    expect(guidance).toContain('Avoid these words and phrases')
+    expect(guidance).toContain('utilise, leverage')
+  })
+
+  it('counts a words-only style as having content', () => {
+    expect(styleHasContent(styleWith({ include: 'reader' }))).toBe(true)
+    expect(styleHasContent(styleWith({ exclude: 'utilise' }))).toBe(true)
+  })
+
+  it('migrates/keeps include and exclude through normalize', () => {
+    const { styles } = normalizeWritingStyle({
+      styles: [{ id: 'a', name: 'X', include: 'foo', exclude: 'bar' }],
+    })
+    expect(styles[0].include).toBe('foo')
+    expect(styles[0].exclude).toBe('bar')
+  })
+})

package/src/writing/writingStyle.ts

@@ -0,0 +1,217 @@
+/**
+ * Writing-style guidance for book generation and in-editor drafting.
+ *
+ * There are no built-in generic presets. Every style is authored and named by
+ * the user. A style carries:
+ *  - SOURCES: the author's own writing samples, mirrored for VOICE only and
+ *    never lifted as content.
+ *  - NOTES: free-text guidance the author writes themselves (their own rules).
+ *  - SKILL: a compact, distilled style guide generated from the sources+notes
+ *    (see condenseWritingStyleWithAgent). It is editable and, when enabled, is
+ *    sent to the agent instead of the raw sources+notes to save tokens.
+ *
+ * Styles are saved app-wide (book app settings) and reused across book creation
+ * and the editor drafter. Which styles apply is chosen per book / per draft.
+ */
+
+export interface StyleSource {
+  id: string
+  label: string
+  text: string
+}
+
+export interface WritingStyle {
+  id: string
+  name: string
+  sources: StyleSource[]
+  notes: string
+  /** Words/phrases to prefer (whitelist). Free text — comma or newline separated. */
+  include: string
+  /** Words/phrases to avoid (blacklist). Free text — comma or newline separated. */
+  exclude: string
+  /** Distilled compact style guide; editable. Empty until distilled. */
+  skill: string
+  /** When true and a skill exists, the skill is used instead of raw sources. */
+  skillEnabled: boolean
+}
+
+export interface BookWritingStyle {
+  styles: WritingStyle[]
+}
+
+export const EMPTY_WRITING_STYLE: BookWritingStyle = { styles: [] }
+
+function randomId(prefix: string): string {
+  return `${prefix}-${Math.random().toString(36).slice(2)}-${Date.now()}`
+}
+
+export function createWritingStyle(name = 'New style'): WritingStyle {
+  return {
+    id: randomId('style'),
+    name,
+    sources: [],
+    notes: '',
+    include: '',
+    exclude: '',
+    skill: '',
+    skillEnabled: false,
+  }
+}
+
+export function createStyleSource(label = 'Sample'): StyleSource {
+  return { id: randomId('src'), label, text: '' }
+}
+
+function coerceSource(item: unknown): StyleSource | null {
+  if (!item || typeof item !== 'object') return null
+  const entry = item as Record<string, unknown>
+  const text = typeof entry.text === 'string' ? entry.text : ''
+  return {
+    id: typeof entry.id === 'string' && entry.id ? entry.id : randomId('src'),
+    label:
+      typeof entry.label === 'string' && entry.label.trim()
+        ? entry.label.trim()
+        : 'Sample',
+    text,
+  }
+}
+
+function coerceStyle(item: unknown): WritingStyle | null {
+  if (!item || typeof item !== 'object') return null
+  const entry = item as Record<string, unknown>
+
+  // Current shape: a style with its own sources.
+  let sources = Array.isArray(entry.sources)
+    ? entry.sources
+        .map(coerceSource)
+        .filter((source): source is StyleSource => source !== null)
+    : []
+
+  // Legacy migration: a flat StyleExample { label, text } becomes one source.
+  if (sources.length === 0 && typeof entry.text === 'string' && entry.text.trim()) {
+    sources = [
+      {
+        id: typeof entry.id === 'string' && entry.id ? entry.id : randomId('src'),
+        label:
+          typeof entry.label === 'string' && entry.label.trim()
+            ? entry.label.trim()
+            : 'Sample',
+        text: entry.text,
+      },
+    ]
+  }
+
+  const name =
+    typeof entry.name === 'string' && entry.name.trim()
+      ? entry.name.trim()
+      : typeof entry.label === 'string' && entry.label.trim()
+        ? entry.label.trim()
+        : 'Untitled style'
+  const notes = typeof entry.notes === 'string' ? entry.notes : ''
+  const include = typeof entry.include === 'string' ? entry.include : ''
+  const exclude = typeof entry.exclude === 'string' ? entry.exclude : ''
+  const skill = typeof entry.skill === 'string' ? entry.skill : ''
+
+  // Keep a style only if it has something to say.
+  if (
+    sources.length === 0 &&
+    !notes.trim() &&
+    !include.trim() &&
+    !exclude.trim() &&
+    !skill.trim()
+  ) {
+    return null
+  }
+
+  return {
+    id: typeof entry.id === 'string' && entry.id ? entry.id : randomId('style'),
+    name,
+    sources,
+    notes,
+    include,
+    exclude,
+    skill,
+    skillEnabled: entry.skillEnabled === true && skill.trim().length > 0,
+  }
+}
+
+export function normalizeWritingStyle(value: unknown): BookWritingStyle {
+  const record =
+    value && typeof value === 'object' ? (value as Record<string, unknown>) : {}
+  // Current shape: { styles }. Legacy shape: { presets, examples }.
+  const source = Array.isArray(record.styles)
+    ? record.styles
+    : Array.isArray(record.examples)
+      ? record.examples
+      : []
+  const styles = source
+    .map(coerceStyle)
+    .filter((style): style is WritingStyle => style !== null)
+  return { styles }
+}
+
+/**
+ * Raw guidance for ONE style: the author's notes plus their voice samples,
+ * explicitly marked voice-only. Used both as the distillation input and as the
+ * applied guidance when no skill is enabled.
+ */
+export function styleRawGuidance(style: WritingStyle): string {
+  const lines: string[] = []
+  if (style.notes.trim()) lines.push(`Guidance: ${style.notes.trim()}`)
+  if (style.include.trim()) {
+    lines.push(
+      `Prefer these words and phrases where they fit naturally: ${normalizeWordList(style.include)}.`,
+    )
+  }
+  if (style.exclude.trim()) {
+    lines.push(`Avoid these words and phrases entirely: ${normalizeWordList(style.exclude)}.`)
+  }
+  const samples = style.sources
+    .map(source => source.text.trim())
+    .filter(Boolean)
+  if (samples.length > 0) {
+    lines.push(
+      'Match the VOICE of these writing samples — sentence rhythm, tone, and word choice only. Do NOT reuse their wording, facts, or subject matter as content:',
+    )
+    samples.forEach((text, index) => {
+      lines.push(`Sample ${index + 1}: """${text.slice(0, 1200)}"""`)
+    })
+  }
+  return lines.join('\n')
+}
+
+/** Flatten a comma/newline-separated word list into a single comma-separated line. */
+function normalizeWordList(value: string): string {
+  return value
+    .split(/[\n,]/)
+    .map(word => word.trim())
+    .filter(Boolean)
+    .join(', ')
+}
+
+/** True when a style contributes anything to the prompt. */
+export function styleHasContent(style: WritingStyle): boolean {
+  return (
+    style.skill.trim().length > 0 ||
+    style.notes.trim().length > 0 ||
+    style.include.trim().length > 0 ||
+    style.exclude.trim().length > 0 ||
+    style.sources.some(source => source.text.trim().length > 0)
+  )
+}
+
+/**
+ * Build the style-guidance prompt block from the SELECTED styles. For each
+ * style, prefer its distilled skill when enabled; otherwise fall back to the
+ * raw notes + voice samples.
+ */
+export function buildStyleGuidance(styles: WritingStyle[]): string | undefined {
+  const blocks: string[] = []
+  styles.forEach(style => {
+    const useSkill = style.skillEnabled && style.skill.trim().length > 0
+    const body = useSkill ? style.skill.trim() : styleRawGuidance(style)
+    if (body.trim()) blocks.push(`Style — ${style.name}:\n${body.trim()}`)
+  })
+  if (blocks.length === 0) return undefined
+  return ['Writing style guidance:', ...blocks].join('\n\n')
+}