dsh-output-styles 0.3.2 → 0.4.0

package/src/renderers.ts

@@ -0,0 +1,264 @@
+/**
+ * The `output.render.*` protocol: a presenter registry that turns raw
+ * model-visible text into display text. A renderer is a pure function —
+ * `presenter(text, meta)` maps args to presentation data and never touches
+ * the DOM — matched by tool name and content type, ordered by priority.
+ * Every rendered result carries its original text alongside, so any consumer
+ * (this plugin's `/export`, third-party panels) can log both and keep the
+ * "model-visible ⟺ reconstructable" invariant.
+ *
+ * This module is dependency-free (no DOM, no node: imports, no DSH imports)
+ * so the protocol vocabulary itself is portable and unit-testable anywhere.
+ * @module dsh-output-styles/renderers
+ */
+
+/** Content-type vocabulary a renderer can match on. */
+export type ContentType = 'text' | 'markdown' | 'html'
+
+/** Match rule deciding whether a renderer applies to one render request. */
+export interface RendererMatch {
+  /** Tool names the renderer applies to ('*' = every tool); omitted = match all. */
+  readonly tool?: string | readonly string[]
+  /** Content types the renderer applies to; omitted = match all. */
+  readonly contentType?: ContentType | readonly ContentType[]
+}
+
+/** Facts a render request carries (structural; the DOM never reaches this layer). */
+export interface RenderContext {
+  /** The tool that produced the text, or '' for assistant/user prose. */
+  readonly tool: string
+  /** The declared content type of the text ('text' when unknown). */
+  readonly contentType: ContentType
+  /** The session the text belongs to (per-session rules match on it). */
+  readonly sessionId?: string
+  /** Session-scoped extras a presenter may read (workspace title etc.). */
+  readonly meta?: Readonly<Record<string, string>>
+}
+
+/** The renderer contract a third-party plugin registers. */
+export interface OutputRenderer {
+  /** Unique renderer id (kebab-case); the rule field and `/export --renderer` name it. */
+  readonly id: string
+  /** Human-readable name. */
+  readonly name: string
+  /** One sentence on what the presenter does. */
+  readonly description: string
+  /** Applicability rules; an empty array matches everything. */
+  readonly match: readonly RendererMatch[]
+  /** Higher priority wins; ties break by registration order (earlier first). */
+  readonly priority: number
+  /** Pure presentation function: args in, display data out. */
+  readonly presenter: (text: string, context: RenderContext) => string
+}
+
+/** The auditable render result: original and rendered travel together. */
+export interface RenderedText {
+  /** The original model-visible text (never mutated). */
+  readonly original: string
+  /** The presented text (equal to the original when nothing matched). */
+  readonly rendered: string
+  /** The renderer that applied, or undefined when no renderer matched. */
+  readonly rendererId?: string
+  /** Whether the presentation changed the text. */
+  readonly changed: boolean
+}
+
+/** One per-session/per-tool style rule from the configuration. */
+export interface StyleRule {
+  /** Match facts; an empty object matches everything. */
+  readonly match: {
+    /** Tool name or '*' (omitted = any tool). */
+    readonly tool?: string
+    /** Content type (omitted = any). */
+    readonly contentType?: ContentType
+    /** Exact session id (omitted = any session) — the per-session axis. */
+    readonly session?: string
+  }
+  /** Renderer id to apply (built-ins mirror the style names: concise, step-by-step). */
+  readonly style: string
+  /** Higher priority wins; ties break by rule order (earlier first). */
+  readonly priority: number
+}
+
+/** Registry handle returned by register(). */
+export type RendererDisposer = () => void
+
+/**
+ * Validates a renderer before registration: id grammar, name, description,
+ * match shape, priority, presenter function. Throws on the first violation
+ * (fail-loud — a bad renderer never sits in the registry).
+ * @param renderer - candidate renderer.
+ */
+export function validateRenderer(renderer: OutputRenderer): void {
+  if (typeof renderer !== 'object' || renderer === null) throw new Error('renderer must be an object')
+  if (typeof renderer.id !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(renderer.id)) {
+    throw new Error(`invalid renderer id ${JSON.stringify(renderer.id)}: use kebab-case`)
+  }
+  if (typeof renderer.name !== 'string' || renderer.name === '') throw new Error('renderer name must be a non-empty string')
+  if (typeof renderer.description !== 'string' || renderer.description === '') throw new Error('renderer description must be a non-empty string')
+  if (!Array.isArray(renderer.match)) throw new Error('renderer match must be an array')
+  for (const match of renderer.match) {
+    if (match.tool !== undefined) {
+      const tools = Array.isArray(match.tool) ? match.tool : [match.tool]
+      if (!tools.every((item: unknown) => typeof item === 'string')) {
+        throw new Error('renderer match.tool must be a string or string array')
+      }
+    }
+    if (match.contentType !== undefined) {
+      const types = Array.isArray(match.contentType) ? match.contentType : [match.contentType]
+      if (!types.every((item: unknown) => typeof item === 'string')) {
+        throw new Error('renderer match.contentType must be a string or string array')
+      }
+    }
+  }
+  if (typeof renderer.priority !== 'number' || !Number.isFinite(renderer.priority)) {
+    throw new Error('renderer priority must be a finite number')
+  }
+  if (typeof renderer.presenter !== 'function') throw new Error('renderer presenter must be a function')
+}
+
+/** Match one rule fact (a string, a string list, or undefined=any) against a value. */
+function factMatches(fact: string | readonly string[] | undefined, value: string): boolean {
+  if (fact === undefined) return true
+  if (typeof fact === 'string') return fact === '*' || fact === value
+  return fact.includes('*') || fact.includes(value)
+}
+
+/** Whether a renderer matches a render request. */
+function rendererMatches(renderer: OutputRenderer, context: RenderContext): boolean {
+  if (renderer.match.length === 0) return true
+  return renderer.match.some(match =>
+    factMatches(match.tool, context.tool)
+    && factMatches(match.contentType, context.contentType))
+}
+
+/** Whether a configured rule matches a render request. */
+function ruleMatches(rule: StyleRule, context: RenderContext): boolean {
+  if (rule.match.tool !== undefined && rule.match.tool !== '*' && rule.match.tool !== context.tool) return false
+  if (rule.match.contentType !== undefined && rule.match.contentType !== context.contentType) return false
+  if (rule.match.session !== undefined && rule.match.session !== context.sessionId) return false
+  return true
+}
+
+/**
+ * The renderer registry: reversible registration, ordered resolution, and
+ * rule-driven rendering. Registration is a caller-owned effect (the runtime
+ * hands register()'s disposer to ctx.effect); the registry itself is pure
+ * state with no timers, listeners, or I/O.
+ */
+export class RendererRegistry {
+  private readonly renderers = new Map<string, { renderer: OutputRenderer; order: number }>()
+  private order = 0
+
+  /** Register a renderer; the disposer removes exactly this registration. */
+  register(renderer: OutputRenderer): RendererDisposer {
+    validateRenderer(renderer)
+    if (this.renderers.has(renderer.id)) {
+      throw new Error(`renderer ${JSON.stringify(renderer.id)} is already registered`)
+    }
+    const order = this.order++
+    this.renderers.set(renderer.id, { renderer, order })
+    return () => {
+      if (this.renderers.get(renderer.id)?.order === order) this.renderers.delete(renderer.id)
+    }
+  }
+
+  /** Every registered renderer, deterministic order (priority desc, registration asc). */
+  list(): OutputRenderer[] {
+    return [...this.renderers.values()]
+      .sort((a, b) => b.renderer.priority - a.renderer.priority || a.order - b.order)
+      .map(entry => entry.renderer)
+  }
+
+  /** Resolve the renderers that match a request, highest priority first. */
+  resolve(context: RenderContext): OutputRenderer[] {
+    return this.list().filter(renderer => rendererMatches(renderer, context))
+  }
+
+  /**
+   * Render text through the rule table, then the matching renderer pipeline:
+   * the first matching rule names a renderer (applied alone, it is explicit),
+   * otherwise every matching renderer applies in priority order (each sees the
+   * previous renderer's output — composition, not competition).
+   * @param text - the raw model-visible text.
+   * @param context - tool / content-type / session facts.
+   * @param rules - configured style rules, highest priority first.
+   * @returns the auditable result (original always preserved).
+   */
+  render(text: string, context: RenderContext, rules: readonly StyleRule[] = []): RenderedText {
+    const sortedRules = [...rules].sort((a, b) => b.priority - a.priority)
+    const hit = sortedRules.find(rule => ruleMatches(rule, context))
+    if (hit !== undefined) {
+      const renderer = this.renderers.get(hit.style)
+      if (renderer === undefined) {
+        throw new Error(`rule style ${JSON.stringify(hit.style)} names no registered renderer (available: ${this.list().map(item => item.id).join(', ') || 'none'})`)
+      }
+      const rendered = renderer.renderer.presenter(text, context)
+      return { original: text, rendered, rendererId: renderer.renderer.id, changed: rendered !== text }
+    }
+    let rendered = text
+    let rendererId: string | undefined
+    for (const renderer of this.resolve(context)) {
+      rendered = renderer.presenter(rendered, context)
+      rendererId = renderer.id
+    }
+    return { original: text, rendered, ...rendererId === undefined ? {} : { rendererId }, changed: rendered !== text }
+  }
+}
+
+/** Collapse whitespace runs and blank-line stacks; trim the ends. */
+function compact(text: string, maxLines: number, maxChars: number, marker: string): string {
+  const collapsed = text
+    .split(/\r?\n/)
+    .map(line => line.replace(/[ \t]+/g, ' ').trimEnd())
+    .reduce((lines: string[], line) => {
+      if (line === '' && lines[lines.length - 1] === '') return lines
+      lines.push(line)
+      return lines
+    }, [])
+    .join('\n')
+    .trim()
+  let out = maxLines > 0 && collapsed.split('\n').length > maxLines
+    ? collapsed.split('\n').slice(0, maxLines).join('\n') + marker
+    : collapsed
+  if (maxChars > 0 && out.length > maxChars) out = out.slice(0, maxChars) + marker
+  return out
+}
+
+/** Turn a list-shaped text into consistently numbered steps. */
+function enumerate(text: string): string {
+  const lines = text.split(/\r?\n/)
+  const items = lines.filter(line => /^\s*(?:[-*•]|\d+[.)])\s+/.test(line))
+  if (items.length === 0) return text
+  let counter = 0
+  return lines.map((line) => {
+    if (!/^\s*(?:[-*•]|\d+[.)])\s+/.test(line)) return line
+    counter += 1
+    return line.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, `${counter}. `)
+  }).join('\n')
+}
+
+/**
+ * The built-in style renderers, mirroring the two headline styles: `concise`
+ * compacts whitespace under a line/char budget, `step-by-step` numbers list
+ * items consistently. Their ids double as `/style`-compatible names in the
+ * rule table.
+ */
+export const BUILTIN_RENDERERS: readonly OutputRenderer[] = [
+  {
+    id: 'concise',
+    name: 'Concise',
+    description: 'Compacts whitespace runs and blank lines, and caps the presented text at a budget with a truncation marker.',
+    match: [],
+    priority: 10,
+    presenter: text => compact(text, 40, 4000, '\n\n[truncated]'),
+  },
+  {
+    id: 'step-by-step',
+    name: 'Step-by-step',
+    description: 'Numbers list items (dashes, bullets, or digits) consistently from 1 so the presentation reads as ordered steps.',
+    match: [],
+    priority: 10,
+    presenter: text => enumerate(text),
+  },
+]

package/src/runtime.ts

@@ -24,6 +24,8 @@ import { installInvariant, PACKAGE_NAME, type InvariantFacts, type InvariantRegi
 import { loadStyleLibrary, truncateStyle, type OutputStyle } from './style-library.ts'
 import { applyStyleEvent, EMPTY_STYLE_STATE, parseStyleInput, STYLE_COMMAND, type StyleFoldState } from './style-command.ts'
 import { OUTPUT_STYLE_DOMAIN, STYLE_SOURCE, styleSelectionViewSchema, type StyleSelection, type StyleSelectionView } from './types.ts'
+import { BUILTIN_RENDERERS, RendererRegistry, type OutputRenderer, type RenderContext, type RenderedText, type StyleRule } from './renderers.ts'
+import { conversationLines, renderExport } from './export.ts'
 
 /** Bundled style-library directory (package `styles/`), the lowest-priority `stylesDir` entry. */
 export const DEFAULT_STYLES_DIR = fileURLToPath(new URL('../styles/', import.meta.url))
@@ -436,4 +438,112 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     }
     registry.register(PACKAGE_NAME, installInvariant(facts))
   })
+
+  // ── output.render.* protocol: the renderer registry service ───────────────
+  // Third-party plugins register presenters (id / match rules / pure
+  // presenter / priority) through `ctx.outputRenderers`; registration is a
+  // caller-owned effect (register() returns the disposer). The built-in
+  // concise/step-by-step renderers mirror the two headline styles. Rendering
+  // runs the `output.render/before` waterfall first — listeners transform the
+  // request and MUST call next() — then applies the rule table and matching
+  // renderers; every result keeps the original text beside the rendered one.
+  const renderers = new RendererRegistry()
+  for (const renderer of BUILTIN_RENDERERS) {
+    ctx.effect(() => renderers.register(renderer), `dsh-output-styles: renderer ${renderer.id}`)
+  }
+  let effectiveRules: readonly StyleRule[] = resolved.rules
+  const renderText = (text: string, context: RenderContext): Promise<RenderedText> =>
+    ctx.waterfall('output.render/before', { text, context }, async (request: { text: string; context: RenderContext }) =>
+      renderers.render(request.text, request.context, effectiveRules))
+  const renderService = {
+    register: (renderer: OutputRenderer) => renderers.register(renderer),
+    list: () => renderers.list(),
+    resolve: (context: RenderContext) => renderers.resolve(context),
+    renderText,
+  }
+  ctx.provide('outputRenderers', renderService)
+
+  // Per-session/per-tool rules over the settings seam: the `output-style-rules`
+  // namespace carries the rule table (composition `base` + user overrides);
+  // rules referencing an unknown renderer fail at write time, and rendering
+  // fails loudly at call time if a renderer left the registry.
+  installSettingsSection(
+    ctx,
+    settingsNamespace('output-style-rules'),
+    z.object({
+      rules: z.array(z.object({
+        match: z.object({
+          tool: z.string().required(false),
+          contentType: z.union([z.const('text'), z.const('markdown'), z.const('html')]).required(false),
+          session: z.string().required(false),
+        }).required(false),
+        style: z.string().min(1),
+        priority: z.number().required(false),
+      })).default([]),
+    }),
+    { rules: resolved.rules },
+    {
+      setSource: current => {
+        effectiveRules = current().rules.map(rule => ({ match: rule.match ?? {}, style: rule.style, priority: rule.priority ?? 0 }))
+      },
+      onChange: () => {},
+      validate: value => {
+        for (const rule of value.rules) {
+          if (rule.style === '' || /[^a-z0-9-]/.test(rule.style)) {
+            throw new Error(`dsh-output-styles: rule style ${JSON.stringify(rule.style)} must be a kebab-case renderer id`)
+          }
+        }
+      },
+    },
+  )
+
+  // The /export command: renders the current session's message surface to
+  // Markdown or sanitized HTML through the renderer pipeline. The document
+  // itself is the visible artifact; the original lines are the session log
+  // the export was projected from — rendered and original stay reconstructable.
+  if (resolved.enableExport) {
+    ctx.inject(['commands'], (commandCtx) => {
+      commandCtx.commands.register({
+        name: 'export',
+        description: 'Export this session as Markdown or HTML (renderer-aware)',
+        input: { hint: '[markdown|html] [--renderer=<id>]' },
+        handler: async ({ agent, rawInput }) => {
+          const input = parseExportInput(rawInput)
+          if (input.kind === 'error') {
+            return { kind: 'error', text: 'usage: /export [markdown|html] [--renderer=<id>]' }
+          }
+          const lines = conversationLines(agent.session.events)
+          const rules: StyleRule[] = input.renderer === undefined
+            ? [...effectiveRules]
+            : [{ match: {}, style: input.renderer, priority: 0 }]
+          const document = renderExport(renderers, lines, input.format, rules)
+          return { kind: 'success', text: document.text }
+        },
+      })
+    })
+  }
+}
+
+/** Parsed `/export` invocation. */
+type ExportInput = { kind: 'ok'; format: 'markdown' | 'html'; renderer?: string } | { kind: 'error' }
+
+/** Parse `/export [markdown|html] [--renderer=<id>]` from the raw command input. */
+export function parseExportInput(rawInput: unknown): ExportInput {
+  const raw = String(rawInput ?? '').trim()
+  const parts = raw === '' ? [] : raw.split(/\s+/)
+  let format: 'markdown' | 'html' = 'markdown'
+  let renderer: string | undefined
+  for (const part of parts) {
+    if (part === 'markdown' || part === 'html') {
+      format = part
+      continue
+    }
+    const match = /^--renderer=([a-z0-9][a-z0-9-]*)$/.exec(part)
+    if (match !== null) {
+      renderer = match[1]
+      continue
+    }
+    return { kind: 'error' }
+  }
+  return { kind: 'ok', format, ...renderer === undefined ? {} : { renderer } }
 }

package/src/types.ts

@@ -11,6 +11,7 @@
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import { z as zod } from 'zod'
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import type { OutputRenderer, RenderContext, RenderedText } from './renderers.ts'
 
 /** The reserved switch target that removes a session's selection. */
 export const OFF = 'off'
@@ -84,3 +85,30 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
     style: StyleSelectionView
   }
 }
+
+/** The `ctx.outputRenderers` service: the output.render.* renderer registry. */
+export interface OutputRenderersService {
+  /** Register a renderer (returns the disposer; caller owns it via ctx.effect). */
+  register(renderer: OutputRenderer): () => void
+  /** Every registered renderer, deterministic order (priority desc, registration asc). */
+  list(): OutputRenderer[]
+  /** Renderers matching a request, highest priority first. */
+  resolve(context: RenderContext): OutputRenderer[]
+  /** Render text through the `output.render/before` waterfall, then rules + matched renderers. */
+  renderText(text: string, context: RenderContext): Promise<RenderedText>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** The output.render.* renderer registry provided by dsh-output-styles. */
+    outputRenderers: OutputRenderersService
+  }
+  interface Events {
+    /**
+     * Pre-render waterfall: listeners receive `{ text, context }` and MUST
+     * call `next()` with their transformed request (or the unchanged one);
+     * returning without `next()` short-circuits the render pipeline.
+     */
+    'output.render/before'(request: { text: string; context: RenderContext }, next: (request: { text: string; context: RenderContext }) => Promise<RenderedText>): Promise<RenderedText>
+  }
+}