dsh-artcraft-plugin-vectorcraft 0.2.4 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-artcraft-plugin-vectorcraft",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive VectorCraft (vector art) headlessly through its own CLI and MCP server.",
@@ -42,5 +42,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "engines": {
+    "dsh": "^0.2.1-rc.3"
   }
 }

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/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

@@ -9,6 +9,7 @@
  */
 
 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'
                                        
@@ -161,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}`
@@ -382,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 [
@@ -392,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. */
@@ -418,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 }
 
   /**
@@ -541,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`)
@@ -556,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`)
@@ -568,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
@@ -597,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))
     },
   }
 
@@ -711,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))
     },
   }
 
@@ -938,7 +1010,7 @@ export const CRAFT_SECTION_ORDER = 120
                      
            
                    
-                                                                              
+                                                                                     
    
                                                           
                                           
@@ -999,6 +1071,12 @@ export function applyCraftPlugin(
                                        
                                                                                      
                                    
+       
+                                                                                 
+                                                                                
+                                                                              
+       
+                                                                         
    ,
 )             {
   const { profile, packageRoot, config = {}, defineTool } = options
@@ -1012,8 +1090,20 @@ 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       ) {
         const typed = args                                      
@@ -1021,7 +1111,18 @@ export function applyCraftPlugin(
         try {
           const text = await spec.execute(typed)
           appendJournal(profile, { at: startedAt, kind: spec.kind, summary: journalSummary(spec.kind, typed, text, Date.now() - startedAt) })
-          return text
+          // 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,