dsh-artcraft-plugin-vectorcraft 0.2.2 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-artcraft-plugin-vectorcraft",
-  "version": "0.2.2",
+  "version": "0.2.7",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive VectorCraft (vector art) headlessly through its own CLI and MCP server.",

package/src/index.js

@@ -16,6 +16,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { applyCraftPlugin, profileOf } from './kit/index.js'
                                                        
 import { PLUGIN_ROOT } from './root.js'
+import { readFileSync } from 'node:fs'
 
 export const name = 'dsh-artcraft-vectorcraft'
 export const inject = ['tools', 'systemPrompt']
@@ -26,6 +27,27 @@ export const craft = profileOf('vectorcraft')
 /** Configuration is the shared craft config. */
                                       
 
+/**
+ * Commit a rendered preview so the transcript shows the document after the call.
+ * The attachment service is optional: without it the path stays in the text.
+ */
+const attachImage = async (ctx         , path        )                   => {
+  const attachments = ctx.get('attachments')   
+                                                                                                     
+               
+  if (attachments?.saveImage === undefined) return undefined
+  try {
+    const ref = await attachments.saveImage({
+      data: readFileSync(path),
+      mediaType: 'image/png',
+      name: path.split(/[\\/]/).pop(),
+    })
+    return { type: 'image', attachment: ref }
+  } catch {
+    return undefined
+  }
+}
+
 export function apply(ctx         , config         = {})       {
   if (craft === undefined) throw new Error('dsh-artcraft-vectorcraft: profile "vectorcraft" is missing from the inlined kernel')
   // `ctx.effect` ties the registration and the MCP server to this plugin's fiber.
@@ -34,5 +56,6 @@ export function apply(ctx         , config         = {})       {
     packageRoot: PLUGIN_ROOT,
     config,
     defineTool: defineTool         ,
+    attachImage: (path        ) => attachImage(ctx, path),
   }))
 }

package/src/index.ts

@@ -16,6 +16,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import { applyCraftPlugin, profileOf } from './kit/index.js'
 import type { CraftPluginConfig } from './kit/index.js'
 import { PLUGIN_ROOT } from './root.ts'
+import { readFileSync } from 'node:fs'
 
 export const name = 'dsh-artcraft-vectorcraft'
 export const inject = ['tools', 'systemPrompt']
@@ -26,6 +27,27 @@ export const craft = profileOf('vectorcraft')
 /** Configuration is the shared craft config. */
 export type Config = CraftPluginConfig
 
+/**
+ * Commit a rendered preview so the transcript shows the document after the call.
+ * The attachment service is optional: without it the path stays in the text.
+ */
+const attachImage = async (ctx: Context, path: string): Promise<unknown> => {
+  const attachments = ctx.get('attachments') as
+    | { saveImage?: (input: { data: Buffer; mediaType: string; name?: string }) => Promise<unknown> }
+    | undefined
+  if (attachments?.saveImage === undefined) return undefined
+  try {
+    const ref = await attachments.saveImage({
+      data: readFileSync(path),
+      mediaType: 'image/png',
+      name: path.split(/[\\/]/).pop(),
+    })
+    return { type: 'image', attachment: ref }
+  } catch {
+    return undefined
+  }
+}
+
 export function apply(ctx: Context, config: Config = {}): void {
   if (craft === undefined) throw new Error('dsh-artcraft-vectorcraft: profile "vectorcraft" is missing from the inlined kernel')
   // `ctx.effect` ties the registration and the MCP server to this plugin's fiber.
@@ -34,5 +56,6 @@ export function apply(ctx: Context, config: Config = {}): void {
     packageRoot: PLUGIN_ROOT,
     config,
     defineTool: defineTool as never,
+    attachImage: (path: string) => attachImage(ctx, path),
   }))
 }

package/src/kit/journal.js

@@ -0,0 +1,55 @@
+/**
+ * A readable work journal for the craft tools.
+ *
+ * The harness shows each tool call, but a session that builds a report spans a
+ * dozen calls across four applications, and reconstructing what actually happened
+ * means scrolling a transcript. Every call also appends one line to a per-craft
+ * journal in the workspace (`.artcraft/journal/`), so the user can open one file
+ * and read the story: which craft, which operation, how long, what came out.
+ *
+ * A journal line is best-effort and never fails a tool call: a read-only
+ * workspace loses the record, not the work.
+ * @module @dsh-artcraft/craft-kit/journal
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+                                              
+
+/** One recorded event. */
+                               
+                                   
+                     
+                                            
+                       
+                                                                        
+                          
+                                          
+                                        
+ 
+
+/** Where the journals live, relative to the workspace the agent runs in. */
+export function journalDir(cwd         = process.cwd())         {
+  return join(cwd, '.artcraft', 'journal')
+}
+
+/**
+ * Append one entry to the craft's journal.
+ * @param profile - the craft that ran.
+ * @param entry - what happened.
+ * @param cwd - workspace root; defaults to the process cwd.
+ */
+export function appendJournal(profile              , entry              , cwd         = process.cwd())       {
+  try {
+    const dir = journalDir(cwd)
+    mkdirSync(dir, { recursive: true })
+    const time = new Date(entry.at).toTimeString().slice(0, 8)
+    const artifacts = entry.artifacts !== undefined && entry.artifacts.length > 0
+      ? `\n  → ${entry.artifacts.join(', ')}`
+      : ''
+    appendFileSync(join(dir, `${profile.id}.md`), `${time} · ${entry.kind} · ${entry.summary}${artifacts}\n`)
+    appendFileSync(join(dir, 'events.jsonl'), JSON.stringify({ craft: profile.id, ...entry }) + '\n')
+  } catch {
+    // A journal is a convenience; never let it fail the call that produced it.
+  }
+}

package/src/kit/present.js

@@ -0,0 +1,206 @@
+/**
+ * Render intents for the craft tools: what a call looks like *while running* and
+ * what its result looks like afterwards.
+ *
+ * A craft run is one call that performs a dozen steps, and a raw JSONL dump is a
+ * poor card: the reader cannot see how many steps there are, which one failed, or
+ * what files came out. These presenters turn the same result into a titled card
+ * (a UI that understands {@link ToolCallView}/{@link ToolResultView} shows it as a
+ * tool row with a header and a short body).
+ *
+ * The kernel stays DSH-free: these are plain objects shaped like the harness's
+ * view contracts, and the calling plugin passes them to `defineTool`.
+ * @module @dsh-artcraft/craft-kit/present
+ */
+
+                                              
+
+/** One text block, as the harness's content-block shape expects. */
+                                
+                       
+                       
+ 
+
+/** A file the call touches, for editor follow-along. */
+                               
+                       
+                        
+ 
+
+/** Pending-call card: `{card:'generic'}` with a title and an optional body. */
+                           
+                          
+                        
+                                                                                                
+                             
+                                             
+                                              
+ 
+
+/** Completed-call card: a replacement title and reformatted content. */
+                             
+                          
+                         
+                                            
+ 
+
+/** Arguments the model passed, as far as these presenters care. */
+                                   
+
+/** First `count` entries of a list, plus a count when longer. */
+function summarise   (items              , render                     , count = 8)                  {
+  const shown = items.slice(0, count).map(render)
+  if (items.length > shown.length) shown.push(`…and ${items.length - shown.length} more`)
+  return shown.length === 0 ? [{ type: 'text', text: '(no commands)' }] : shown.map(text => ({ type: 'text', text }))
+}
+
+/** The command list a run call carries, whether objects or raw strings. */
+function commandLabels(raw         )           {
+  if (!Array.isArray(raw)) return []
+  return raw.map((entry) => {
+    if (typeof entry === 'string') return entry
+    if (typeof entry === 'object' && entry !== null) {
+      const record = entry                                    
+      const id = typeof record.id === 'string' ? record.id : '(unnamed)'
+      const json = record.json === undefined ? '' : ` ${JSON.stringify(record.json)}`
+      return `${id}${json.length > 60 ? `${json.slice(0, 60)}…` : json}`
+    }
+    return String(entry)
+  })
+}
+
+/** A path from the arguments, when the call writes one. */
+function outputPath(args      )                     {
+  for (const key of ['save', 'export', 'output', 'out']         ) {
+    const value = args[key]
+    if (typeof value === 'string' && value.length > 0) return value
+  }
+  return undefined
+}
+
+/** A path from the arguments, when the call reads one. */
+function inputPath(args      )                     {
+  const value = args.input ?? args.file
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * The pending-call card for one tool.
+ * @param profile - the craft, for the title.
+ * @param kind - which tool of the set is being called.
+ * @param args - the model's arguments.
+ * @returns a generic call view.
+ */
+export function craftCallView(profile              , kind        , args      )           {
+  const name = profile.product
+  switch (kind) {
+    case 'run': {
+      const labels = commandLabels(args.commands)
+      const target = outputPath(args)
+      return {
+        card: 'generic',
+        kind: 'execute',
+        title: `${name} · ${labels.length} command${labels.length === 1 ? '' : 's'}${target === undefined ? '' : ` → ${target}`}`,
+        content: summarise(labels, label => `• ${label}`),
+        ...target === undefined ? {} : { locations: [{ path: target }] },
+      }
+    }
+    case 'commands': {
+      const search = typeof args.search === 'string' && args.search.length > 0 ? ` "${args.search}"` : ''
+      return { card: 'generic', kind: 'search', title: `${name} · command catalogue${search}` }
+    }
+    case 'describe': {
+      const id = typeof args.id === 'string' ? args.id : ''
+      return { card: 'generic', kind: 'read', title: `${name} · describe ${id}` }
+    }
+    case 'inspect': {
+      const file = inputPath(args) ?? '(default)'
+      return { card: 'generic', kind: 'read', title: `${name} · inspect ${file}`, locations: [{ path: file }] }
+    }
+    case 'convert': {
+      const input = inputPath(args) ?? ''
+      const output = typeof args.output === 'string' ? args.output : ''
+      return {
+        card: 'generic',
+        kind: 'execute',
+        title: `${name} · convert ${input}${output.length === 0 ? '' : ` → ${output}`}`,
+        locations: output.length === 0 ? [] : [{ path: output }],
+      }
+    }
+    case 'mcpCall': {
+      const tool = typeof args.tool === 'string' ? args.tool : '(tool)'
+      const attach = typeof args.attach === 'number' ? ` · attached :${args.attach}` : ''
+      return { card: 'generic', kind: 'execute', title: `${name} · ${tool}${attach}`, rawInput: args.arguments }
+    }
+    case 'mcpTools': {
+      const search = typeof args.search === 'string' && args.search.length > 0 ? ` "${args.search}"` : ''
+      return { card: 'generic', kind: 'search', title: `${name} · MCP tools, resources and prompts${search}` }
+    }
+    case 'mcpStatus':
+      return { card: 'generic', kind: 'read', title: `${name} · MCP bridge status` }
+    case 'job': {
+      const action = typeof args.action === 'string' ? args.action : 'list'
+      const job = typeof args.job === 'string' ? ` ${args.job}` : ''
+      return { card: 'generic', kind: 'other', title: `${name} · job ${action}${job}` }
+    }
+    default:
+      return { card: 'generic', kind: 'other', title: `${name} · ${kind}` }
+  }
+}
+
+/** What a run result text says: exit status, duration, artifacts, per-step failures. */
+function summariseRun(profile              , text        )             {
+  const steps = text.split('\n').filter(line => line.startsWith('{"command"') || line.startsWith('{"step"'))
+  let ok = 0
+  let failed = 0
+  let firstFailure = ''
+  for (const line of steps) {
+    try {
+      const parsed = JSON.parse(line)                                                      
+      if (parsed.ok === false) {
+        failed += 1
+        if (firstFailure.length === 0) firstFailure = `${parsed.command ?? 'step'}: ${parsed.error ?? 'failed'}`
+      } else ok += 1
+    } catch {
+      // A craft that prints non-JSON progress lines still runs; the exit line below decides.
+    }
+  }
+  const exit = /exited (\d+) in (\d+)ms/.exec(text)
+  const artifacts = [...text.matchAll(/^(?:wrote|saved|exported) (.+)$/gm)].map(match => match[1])
+  const title = `${profile.product} · ${steps.length > 0 ? `${ok} ok${failed > 0 ? `, ${failed} failed` : ''}` : 'finished'}${exit === null ? '' : ` · exit ${exit[1]}`}`
+  const body           = []
+  if (failed > 0) body.push(`first failure — ${firstFailure}`)
+  if (artifacts.length > 0) body.push(`wrote ${artifacts.join(', ')}`)
+  if (exit !== null) body.push(`took ${exit[2]} ms`)
+  if (body.length === 0) body.push(text.trim().split('\n')[0] ?? '(no output)')
+  return { card: 'generic', title, content: body.map(line => ({ type: 'text', text: line })) }
+}
+
+/**
+ * The completed-call card for one tool.
+ * @param profile - the craft, for the title.
+ * @param kind - which tool ran.
+ * @param text - the model-facing result.
+ * @param isError - whether the call failed.
+ * @returns a generic result view.
+ */
+export function craftResultView(profile              , kind        , text        , isError         )             {
+  if (isError) {
+    return {
+      card: 'generic',
+      title: `${profile.product} · ${kind} failed`,
+      content: [{ type: 'text', text: text.split('\n').slice(0, 4).join('\n') }],
+    }
+  }
+  if (kind === 'run') return summariseRun(profile, text)
+  const all = text.trim().split('\n').filter(line => line.trim().length > 0)
+  // A few lines are usually the whole story (job status, an image path and its
+  // dimensions); keep them rather than collapsing to one line and a count.
+  const shown = all.slice(0, 4)
+  if (all.length > shown.length) shown.push(`…and ${all.length - shown.length} more lines`)
+  return {
+    card: 'generic',
+    title: `${profile.product} · ${kind}`,
+    content: (shown.length === 0 ? ['(no output)'] : shown).map(line => ({ type: 'text', text: line })),
+  }
+}

package/src/kit/preview.js

@@ -0,0 +1,210 @@
+/**
+ * Render a document's current state for the live preview.
+ *
+ * Three things share this module: the image block a tool returns after an edit,
+ * the local panel in `scripts/preview/`, and the DSH client panel: they all read
+ * the same state directory (`docs/PREVIEW.md` holds the contract).
+ *
+ * Rendering goes through the craft's own binary — never a screenshot of a window
+ * — so the preview shows what the application itself would show.
+ * @module @dsh-artcraft/craft-kit/preview
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { runCraft } from './exec.js'
+                                                           
+
+/** Where the previews live when no configuration overrides it. */
+export function previewRoot(configured         )         {
+  if (configured !== undefined && configured.length > 0) return configured
+  const fromEnv = process.env.DSH_ARTCRAFT_PREVIEW_DIR
+  if (fromEnv !== undefined && fromEnv.length > 0) return fromEnv
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  return join(home, 'artcraft', 'preview')
+}
+
+/**
+ * How one craft renders a document to an image.
+ *
+ * A craft with no recipe still reports a step in the panel; it just has no
+ * picture (SoundCraft has no page, and the MCP-only crafts need their server).
+ */
+                         
+                                                        
+                                                                                
+ 
+
+/** Per-craft render recipes, verified against the 2026-11 CLI releases. */
+const RECIPES                                = {
+  // `render FILE OUT [--page N] [--scale S]` draws a page as a PNG.
+  wordcraft: { argv: (file, out, scale) => ['render', file, out, '--page', '1', '--scale', String(scale)] },
+  // `convert` picks the format from the output extension.
+  cadcraft: { argv: (file, out) => ['convert', file, out] },
+  figcraft: { argv: (file, out) => ['convert', file, out] },
+  // `render FILE [--slide N] [--scale S] OUT` draws one slide as a PNG.
+  deckcraft: { argv: (file, out, scale) => ['render', file, '--slide', '0', '--scale', String(scale), out] },
+  // VectorCraft exports the active artboard through `run --export`.
+  vectorcraft: { argv: (file, out) => ['run', file, '--export', out] },
+  // TextureCraft renders the viewport (2D view; the 3D one needs a GPU).
+  texturecraft: { argv: (file, out) => ['render', file, out, '--view', '2d'] },
+  // PhotoCraft converts the document; `convert` picks the format by extension.
+  photocraft: { argv: (file, out) => ['convert', file, out] },
+  // EffectCraft renders one frame at t=0 without the render queue.
+  effectcraft: { argv: (file, out) => ['render-frame', '--time', '0', '--out', out] },
+  // LightCraft develops one file through the same encoder as the export dialog.
+  lightcraft: { argv: (file, out) => ['render', file, '-o', out] },
+}
+
+/** Whether a craft can render a preview at all. */
+export function canPreview(profile              )          {
+  return RECIPES[profile.id] !== undefined
+}
+
+/** One preview step, as documented in docs/PREVIEW.md. */
+                              
+                    
+                     
+                       
+                        
+                          
+                         
+                         
+                         
+                          
+                              
+                                                                                   
+ 
+
+/**
+ * One clip on a time-based craft's timeline, in seconds.
+ *
+ * `timeline` is a property of the DOCUMENT (the whole sequence), not of a step:
+ * the panel draws one bar under the current render, and a per-step bar would
+ * make it jump between steps that did not change the sequence.
+ */
+                              
+                        
+                           
+                        
+ 
+
+/** A craft's `state.json`. */
+                               
+                        
+                          
+                       
+                        
+                            
+                          
+                                                                            
+                                            
+                                        
+ 
+
+/**
+ * Render one document to `<dir>/<craft>/step-NNN.png`.
+ *
+ * Never throws: a preview is a convenience, and a craft that cannot render must
+ * not fail the edit that produced it.
+ * @param profile - the craft that wrote the document.
+ * @param binary - its resolved binary.
+ * @param options - document path, output directory and render scale.
+ * @returns the absolute image path, or `undefined` when the craft cannot render.
+ */
+export async function renderPreview(
+  profile              ,
+  binary             ,
+  options                                                                                                                             ,
+)                              {
+  const recipe = RECIPES[profile.id]
+  if (recipe === undefined) return undefined
+  if (!existsSync(options.file)) return undefined
+  try {
+    mkdirSync(options.dir, { recursive: true })
+    const argv = recipe.argv(options.file, options.out, options.scale ?? 1.5)
+    const result = await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs: options.timeoutMs ?? 60_000 })
+    return result.ok && existsSync(options.out) ? options.out : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The next step number for a craft, across processes.
+ *
+ * A plugin process starts its own counter at zero, so numbering from memory
+ * alone makes a restarted session overwrite the earlier steps it wrote to disk.
+ * The state file is the truth: continue after the highest number recorded.
+ * @param root - preview root.
+ * @param craft - craft id.
+ * @returns the next 1-based step number.
+ */
+export function nextStepNumber(root        , craft        )         {
+  try {
+    const state = JSON.parse(readFileSync(join(root, craft, 'state.json'), 'utf8'))                
+    return state.steps.reduce((highest, step) => Math.max(highest, step.n), 0) + 1
+  } catch {
+    return 1
+  }
+}
+
+/** Read-modify-write one craft's state and refresh the index. */
+export function recordPreview(
+  root        ,
+  profile              ,
+  step             ,
+  file        ,
+  pages        ,
+  timeline                         ,
+)               {
+  const craftDir = join(root, profile.id)
+  mkdirSync(craftDir, { recursive: true })
+  const statePath = join(craftDir, 'state.json')
+  let previous                          
+  try {
+    previous = JSON.parse(readFileSync(statePath, 'utf8'))                
+  } catch {
+    previous = undefined
+  }
+  const resolved              = { ...step, n: previous === undefined ? step.n : Math.max(step.n, (previous.steps.reduce((highest, entry) => Math.max(highest, entry.n), 0)) + 1) }
+  const steps = [...(previous?.steps ?? []).filter(entry => entry.n !== resolved.n), resolved]
+  const state               = {
+    craft: profile.id,
+    product: profile.product,
+    file,
+    pages,
+    updatedAt: new Date().toISOString(),
+    current: resolved.n,
+    // Keep the last known timeline: a step that only moved the playhead must
+    // not erase the clips a previous step reported.
+    ...timeline !== undefined ? { timeline } : previous?.timeline !== undefined ? { timeline: previous.timeline } : {},
+    steps,
+  }
+  writeFileSync(statePath, JSON.stringify(state, undefined, 2) + '\n')
+
+  // index.json is the panel's first read: one entry per craft, no history.
+  const indexPath = join(root, 'index.json')
+  let index                                                                                                                       =
+    { updatedAt: state.updatedAt, crafts: {} }
+  try {
+    index = JSON.parse(readFileSync(indexPath, 'utf8'))                
+  } catch {
+    // First write for this session.
+  }
+  index.crafts[profile.id] = { file, pages, stepCount: state.steps.length, updatedAt: state.updatedAt }
+  index.updatedAt = state.updatedAt
+  writeFileSync(indexPath, JSON.stringify(index, undefined, 2) + '\n')
+  return state
+}
+
+/** A stable name for this step's render, e.g. `step-003.png`. */
+export function stepName(n        )         {
+  return `step-${String(n).padStart(3, '0')}.png`
+}
+
+/** The display name of a document path, for the panel's header. */
+export function documentLabel(file        )         {
+  return basename(dirname(file)) + '/' + basename(file)
+}

package/src/kit/tools.js

@@ -8,6 +8,9 @@
  * @module @dsh-artcraft/craft-kit/tools
  */
 
+import { craftCallView, craftResultView } from './present.js'
+import { canPreview, nextStepNumber, previewRoot, recordPreview, renderPreview, stepName } from './preview.js'
+import { appendJournal } from './journal.js'
 import { CraftMcpClient, renderSchema } from './mcp.js'
                                        
 import { groupsOf, loadCatalog, score } from './catalog.js'
@@ -159,10 +162,35 @@ export function createRuntime(profile              , packageRoot        , config
   let catalogCache                                                                                                          
   const mcpClients = new Map                        ()
   const artifacts = config.artifactsDir ?? join(tmpdir(), 'dsh-artcraft', profile.id)
+  const previewDir = previewRoot(config.previewDir)
+  let previewStep = 0
   const jobs = new Map                       ()
   const jobChildren = new Map                                                   ()
   let jobCounter = 0
   return {
+    async preview(options) {
+      if (config.preview === 'off') return undefined
+      if (!canPreview(profile)) return undefined
+      const binary = this.binary()
+      if (binary === undefined) return undefined
+      previewStep = nextStepNumber(previewDir, profile.id)
+      const n = previewStep
+      const dir = join(previewDir, profile.id)
+      const out = join(dir, stepName(n))
+      const scale = options.scale ?? config.previewScale ?? 1.5
+      const rendered = await renderPreview(profile, binary, { file: options.file, dir, out, scale })
+      const relative = rendered === undefined ? undefined : stepName(n)
+      recordPreview(previewDir, profile, {
+        n,
+        at: new Date().toISOString(),
+        tool: options.tool,
+        title: options.title,
+        summary: options.summary,
+        ...relative === undefined ? {} : { image: relative, thumb: relative },
+        ...options.durationMs === undefined ? {} : { durationMs: options.durationMs },
+      }, options.file, 1)
+      return rendered
+    },
     startJob(binary, argv) {
       jobCounter += 1
       const id = `j${jobCounter}`
@@ -314,13 +342,17 @@ export function renderCatalog(
                                
  
 
-/** One tool's definition: name/description/schema plus its executor. */
+/** One tool's definition: name/description/schema plus its executor and views. */
                                              
                   
                        
                               
                                               
                                                                       
+                                                          
+                                                                   
+                                                     
+                                                                                                     
  
 
 /**
@@ -376,7 +408,13 @@ export function createToolSet(runtime              )               {
    * Renders, bakes and bounces outlast the tool timeout; a job keeps the process
    * alive after the call returns and leaves its output in a log file.
    */
-  const runOrStart = async (binary             , argv                   , background         )                  => {
+  const runOrStart = async (
+    binary             ,
+    argv                   ,
+    background         ,
+    document         ,
+    label         ,
+  )                  => {
     if (background === true) {
       const job = runtime.startJob(binary, argv)
       return [
@@ -386,7 +424,21 @@ export function createToolSet(runtime              )               {
         `or wait with {"action":"wait","job":"${job.id}","timeoutMs":300000}`,
       ].join('\n')
     }
-    return renderRun(await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs }), profile)
+    const result = await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs })
+    let text = renderRun(result, profile)
+    // A render after every write is what turns the transcript into a step-by-step
+    // view of the document; the same image feeds the preview panel.
+    if (result.ok && document !== undefined && config.preview !== 'off') {
+      const rendered = await runtime.preview({
+        file: document,
+        tool: 'run',
+        title: label === undefined || label.length === 0 ? `${profile.id}_run` : label,
+        summary: `exit ${result.exitCode ?? 0} · ${result.durationMs} ms`,
+        durationMs: result.durationMs,
+      })
+      if (rendered !== undefined) text += `\n[preview] ${rendered}`
+    }
+    return text
   }
 
   /** Guard every tool: a missing binary is an answer, never a crash. */
@@ -412,6 +464,32 @@ export function createToolSet(runtime              )               {
     return await runOrStart(binary, argv, background)
   }
 
+  /** A short, human step label: the first command ids, not the tool name. */
+  const labelOf = (args                         )                     => {
+    const raw = args.commands
+    if (!Array.isArray(raw) || raw.length === 0) return undefined
+    const ids = raw.map((entry) => {
+      if (typeof entry === 'string') return entry.trim().split(/\s+/)[0] ?? ''
+      if (typeof entry === 'object' && entry !== null) {
+        const id = (entry                    ).id
+        return typeof id === 'string' ? id : ''
+      }
+      return ''
+    }).filter(id => id.length > 0)
+    if (ids.length === 0) return undefined
+    const shown = ids.slice(0, 3).join(', ')
+    return `${profile.product} · ${ids.length <= 3 ? shown : `${shown} +${ids.length - 3}`}`
+  }
+
+  /** The document this call wrote or opened, when it named one. */
+  const documentOf = (args                         )                     => {
+    for (const key of ['save', 'export', 'input']         ) {
+      const value = args[key]
+      if (typeof value === 'string' && value.length > 0) return value
+    }
+    return undefined
+  }
+
   const session               = { commands: [], stale: false }
 
   /**
@@ -535,7 +613,7 @@ export function createToolSet(runtime              )               {
         }
         writeFileSync(scriptPath, typeof body === 'string' ? body : JSON.stringify(body, null, 2) + '\n')
         const extra = Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : []
-        return await runOrStart(binary, [...argv, ...extra], args.background)
+        return await runOrStart(binary, [...argv, ...extra], args.background, documentOf(args), labelOf(args))
       }
       if (profile.run.scriptFlag !== undefined) {
         const scriptPath = join(craftWorkDir(profile), `steps-${Date.now()}.json`)
@@ -550,7 +628,7 @@ export function createToolSet(runtime              )               {
           profile.run.scriptFlag, scriptPath,
           ...Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : [],
         ]
-        return await runOrStart(binary, [profile.run.verb, ...extra], args.background)
+        return await runOrStart(binary, [profile.run.verb, ...extra], args.background, documentOf(args), labelOf(args))
       }
       if (profile.run.scriptMode === true) {
         const scriptPath = join(craftWorkDir(profile), `run-${Date.now()}.jsonl`)
@@ -562,7 +640,7 @@ export function createToolSet(runtime              )               {
           scriptPath,
           ...Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : [],
         ]
-        return await runOrStart(binary, [...globalFlagsFor(profile, args), profile.run.verb, ...extra], args.background)
+        return await runOrStart(binary, [...globalFlagsFor(profile, args), profile.run.verb, ...extra], args.background, documentOf(args), labelOf(args))
       }
       // PdfCraft's `run` accepts exactly one tool per invocation; sending a
       // list would produce "expected key=value" from the CLI, so the extra
@@ -591,7 +669,7 @@ export function createToolSet(runtime              )               {
         ...args.print === true ? { print: true } : {},
         ...Array.isArray(args.extraArgs) ? { extra: args.extraArgs.filter((a)              => typeof a === 'string') } : {},
       })
-      return await runOrStart(binary, argv, args.background)
+      return await runOrStart(binary, argv, args.background, documentOf(args), labelOf(args))
     },
   }
 
@@ -705,7 +783,7 @@ export function createToolSet(runtime              )               {
       else if (argMode === 'section') argv.push(typeof args.section === 'string' && args.section.length > 0 ? args.section : inspectSpec.section ?? 'project')
       if (inspectSpec.projectFlag !== undefined && typeof args.project === 'string') argv.push(inspectSpec.projectFlag, args.project)
       argv.push(...inspectSpec.extraArgs ?? [], ...extra)
-      return await runOrStart(binary, argv, args.background)
+      return await runOrStart(binary, argv, args.background, documentOf(args), labelOf(args))
     },
   }
 
@@ -918,6 +996,7 @@ export function createToolSet(runtime              )               {
 }
 
 
+
 /** Prompt-section slot: after the built-in tool sections, app prose follows. */
 export const CRAFT_SECTION_ORDER = 120
 
@@ -931,11 +1010,37 @@ export const CRAFT_SECTION_ORDER = 120
                      
            
                    
-                                                                              
+                                                                                     
    
                                                           
+                                          
+                                                                                                                                
              
 
+/** One-line journal summary for a finished call. */
+function journalSummary(kind        , args                         , text        , elapsedMs        )         {
+  const output = ['save', 'export', 'output', 'out'].map(key => args[key]).find(value => typeof value === 'string' && value.length > 0)
+  switch (kind) {
+    case 'run': {
+      const count = Array.isArray(args.commands) ? args.commands.length : 0
+      const exit = /exited (\d+)/.exec(text)
+      return `${count} command(s)${output === undefined ? '' : ` → ${String(output)}`}`
+        + `${exit === null ? '' : ` · exit ${exit[1]}`} · ${elapsedMs}ms`
+    }
+    case 'mcpCall':
+      return `tool ${String(args.tool ?? '?')} · ${elapsedMs}ms`
+    case 'job':
+      return `job ${String(args.action ?? 'list')}${typeof args.job === 'string' ? ` ${args.job}` : ''}`
+    case 'inspect':
+    case 'convert':
+      return `${String(args.file ?? args.input ?? '')}${args.output === undefined ? '' : ` → ${String(args.output)}`}`
+    default: {
+      const first = text.trim().split('\n')[0] ?? ''
+      return first.length > 120 ? `${first.slice(0, 120)}…` : first
+    }
+  }
+}
+
 /** The `ctx` surface the kernel uses; kept structural for the same reason. */
                                      
                                                              
@@ -966,6 +1071,12 @@ export function applyCraftPlugin(
                                        
                                                                                      
                                    
+       
+                                                                                 
+                                                                                
+                                                                              
+       
+                                                                         
    ,
 )             {
   const { profile, packageRoot, config = {}, defineTool } = options
@@ -979,12 +1090,59 @@ export function applyCraftPlugin(
       description: spec.description,
       parameters: spec.parameters,
       output: {
-        schema: { type: 'string' },
-        render: (_args         , value        ) => [{ type: 'text'         , text: value }],
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            text: { type: 'string' },
+            images: { type: 'array', items: { type: 'json' } },
+          },
+        },
+        render: (_args         , value                                      ) => {
+          const blocks            = []
+          if (value.text.length > 0) blocks.push({ type: 'text'         , text: value.text })
+          for (const image of value.images ?? []) if (image !== undefined) blocks.push(image)
+          return blocks.length > 0 ? blocks : [{ type: 'text'         , text: '' }]
+        },
       },
       async execute(args       ) {
-        return await spec.execute(args                                      )
+        const typed = args                                      
+        const startedAt = Date.now()
+        try {
+          const text = await spec.execute(typed)
+          appendJournal(profile, { at: startedAt, kind: spec.kind, summary: journalSummary(spec.kind, typed, text, Date.now() - startedAt) })
+          // A preview line becomes a real image block when the plugin can commit
+          // one: that is what makes the transcript show each step of the work.
+          const previewPaths = [...text.matchAll(/^\[preview\] (.+)$/gm)].map(match => match[1].trim())
+          if (previewPaths.length > 0 && options.attachImage !== undefined) {
+            const images            = []
+            for (const path of previewPaths) {
+              const block = await options.attachImage(path)
+              if (block !== undefined) images.push(block)
+            }
+            return { text: text.replace(/^\[preview\] .+$/gm, '').trim(), images }
+          }
+          return { text, images: [] }
+        } catch (error) {
+          appendJournal(profile, {
+            at: startedAt,
+            kind: spec.kind,
+            summary: `failed: ${String((error         ).message ?? error).slice(0, 140)}`,
+          })
+          throw error
+        }
       },
+      // Cards: a run is one call with a dozen steps, so the raw JSONL is a poor
+      // row. These turn it into a titled card — what the call does, then what it
+      // produced — and the journal keeps the same story on disk.
+      presentCall: (args         ) => craftCallView(profile, spec.kind, (args ?? {})                           ),
+      presentResult: (args         , result                                                                            ) =>
+        craftResultView(
+          profile,
+          spec.kind,
+          (result.content ?? []).filter(block => block.type === 'text').map(block => block.text ?? '').join('\n'),
+          result.isError === true,
+        ),
     })))
   }
   ctx.systemPrompt.section({