dsh-artifact-studio 0.3.2 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,30 +1,38 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { isDesignInfo, scopeOfId } from '../../contract.js';
1
4
  import { PAGE_CSP, composePage } from '../../render.js';
2
- import { scopeOfId } from '../../contract.js';
5
+ import { DesignRenderer, PREVIEW_MAX_SIDE } from './design-render.js';
3
6
  import { clearWorkspaceDesignSystem, resolveDesignSystem, saveDesignSystem } from './design-system.js';
4
7
  import { ArtifactError } from './errors.js';
5
8
  import { docToHtml, writeExport } from './export.js';
6
- import { libraryRoot, requireWorkspace, workspaceRoot, workspaceRootExisting } from './paths.js';
7
- import { ArtifactStore } from './store.js';
9
+ import { assertWithin, withLock, writeAtomic } from './fsutil.js';
10
+ import { assertPlainFile, libraryRoot, requireWorkspace, workspaceRoot, workspaceRootExisting } from './paths.js';
11
+ import { ArtifactStore, applyEdits, hashOf } from './store.js';
8
12
  /**
9
- * One facade over the store, the scope roots, the design system, and export.
10
- * The route and the tools both call it, so both scopes share every rule.
13
+ * One facade over the store, the scope roots, the design system, the design
14
+ * renderer, and export. The route and the tools both call it, so both scopes
15
+ * share every rule.
11
16
  */
12
17
  export class ArtifactService {
13
18
  store;
14
19
  config;
15
20
  registry;
16
21
  now;
22
+ designs;
17
23
  /**
18
24
  * @param config root locations.
19
25
  * @param registry the workspace registry.
20
26
  * @param store the store.
21
27
  * @param now the clock.
28
+ * @param designs the design renderer.
22
29
  */
23
- constructor(config, registry, store = new ArtifactStore(), now = () => new Date()) {
30
+ constructor(config, registry, store = new ArtifactStore(), now = () => new Date(), designs = new DesignRenderer()) {
24
31
  this.config = config;
25
32
  this.registry = registry;
26
33
  this.store = store;
27
34
  this.now = now;
35
+ this.designs = designs;
28
36
  }
29
37
  /**
30
38
  * Resolve a scope root. An id decides its own scope; a workspace scope needs a workspace id.
@@ -91,17 +99,79 @@ export class ArtifactService {
91
99
  await clearWorkspaceDesignSystem(await this.root({ ...target, scope: 'workspace' }));
92
100
  return this.designSystem(target);
93
101
  }
102
+ /**
103
+ * Create an artifact. A design is compiled before anything is written, so an
104
+ * invalid source never creates a directory or a version.
105
+ * @param target the caller's context.
106
+ * @param input type, title, content, and source.
107
+ * @returns the manifest.
108
+ */
94
109
  async create(target, input) {
95
- return this.store.create(await this.root(target), input);
110
+ const root = await this.root(target);
111
+ const info = input.type === 'design' ? await this.designs.inspect(input.content) : undefined;
112
+ const manifest = await this.store.create(root, input);
113
+ if (info !== undefined)
114
+ await this.writeInfo(root, manifest.id, input.content, info);
115
+ return manifest;
96
116
  }
117
+ /**
118
+ * Read an artifact. A design carries its compiled summary when one can be
119
+ * produced; a failure there never hides the source.
120
+ * @param target the caller's context.
121
+ * @param id the artifact id.
122
+ * @param version an earlier version, when the caller named one.
123
+ * @returns the payload.
124
+ */
97
125
  async read(target, id, version) {
98
- const result = await this.store.read(await this.root(target, id), id, version);
126
+ const root = await this.root(target, id);
127
+ const result = await this.store.read(root, id, version);
99
128
  const design = await this.designSystem(target);
100
- return { ...result, designCss: design.css, design: design.tokens };
129
+ const payload = {
130
+ ...result,
131
+ designCss: design.css,
132
+ design: design.tokens,
133
+ };
134
+ if (result.manifest.type === 'design') {
135
+ const info = await this.infoFor(root, id, result.content);
136
+ if (info !== undefined)
137
+ payload.designInfo = info;
138
+ }
139
+ return payload;
101
140
  }
141
+ /**
142
+ * Save a new version. A design update resolves the final source first, so
143
+ * edits are validated after they are applied and the committed content is
144
+ * exactly what the renderer accepted.
145
+ * @param target the caller's context.
146
+ * @param id the artifact id.
147
+ * @param input the update.
148
+ * @returns the new manifest.
149
+ */
102
150
  async update(target, id, input) {
103
- return this.store.update(await this.root(target, id), id, input);
151
+ const root = await this.root(target, id);
152
+ const current = await this.store.manifest(root, id);
153
+ if (current.type !== 'design')
154
+ return this.store.update(root, id, input);
155
+ const existing = await this.store.read(root, id);
156
+ let next = input.content;
157
+ if (next === undefined && input.edits !== undefined)
158
+ next = applyEdits(existing.content, input.edits);
159
+ if (next === undefined)
160
+ return this.store.update(root, id, input);
161
+ const info = await this.designs.inspect(next);
162
+ const manifest = await this.store.update(root, id, { ...input, content: next, edits: undefined });
163
+ await this.writeInfo(root, id, next, info);
164
+ return manifest;
104
165
  }
166
+ /**
167
+ * Restore an earlier version.
168
+ * @param target the caller's context.
169
+ * @param id the artifact id.
170
+ * @param version the version to restore.
171
+ * @param source who restored it.
172
+ * @param baseVersion the version the caller saw, if it checks.
173
+ * @returns the new manifest.
174
+ */
105
175
  async restore(target, id, version, source, baseVersion) {
106
176
  return this.store.restore(await this.root(target, id), id, version, source, baseVersion);
107
177
  }
@@ -122,15 +192,206 @@ export class ArtifactService {
122
192
  */
123
193
  async printable(target, id, version) {
124
194
  const { manifest, content } = await this.store.read(await this.root(target, id), id, version);
195
+ if (manifest.type === 'design') {
196
+ throw new ArtifactError('artifact/unsupported-format', 'A design cannot be printed.', { type: manifest.type });
197
+ }
125
198
  const design = await this.designSystem(target);
126
199
  return { html: manifest.type === 'page'
127
200
  ? composePage(content, design.css, PAGE_CSP, manifest.title)
128
201
  : docToHtml(manifest.title, content, design.css, true) };
129
202
  }
203
+ /**
204
+ * Export a saved version. A design is rendered from its source at that
205
+ * version; the preview cache is never used as the export source.
206
+ * @param target the caller's context.
207
+ * @param id the artifact id.
208
+ * @param format the format.
209
+ * @param version the version, when the caller named one.
210
+ * @returns the exported file.
211
+ */
130
212
  async export(target, id, format, version) {
131
213
  const root = await this.root(target, id);
132
214
  const { manifest, content, version: readVersion } = await this.store.read(root, id, version);
133
215
  const design = await this.designSystem(target);
134
- return writeExport(root, { ...manifest, version: readVersion }, content, format, design, this.now());
216
+ return writeExport(root, { ...manifest, version: readVersion }, content, format, design, this.now(), this.designs);
217
+ }
218
+ /**
219
+ * Render a design, or return its cached preview for the same source.
220
+ * @param target the caller's context.
221
+ * @param id the artifact id.
222
+ * @param version the version, when the caller named one.
223
+ * @returns the preview.
224
+ */
225
+ async preview(target, id, version) {
226
+ const root = await this.root(target, id);
227
+ const { manifest, content } = await this.store.read(root, id, version);
228
+ if (manifest.type !== 'design') {
229
+ throw new ArtifactError('artifact/unsupported-type', 'Only a design has a rendered preview.', { type: manifest.type });
230
+ }
231
+ const cached = await this.readPreview(root, id, content);
232
+ if (cached !== undefined)
233
+ return cached;
234
+ const rendered = await this.designs.preview(content, PREVIEW_MAX_SIDE);
235
+ await this.writePreview(root, id, content, rendered.info, rendered.width, rendered.height, rendered.bytes);
236
+ return {
237
+ mediaType: 'image/png',
238
+ data: rendered.bytes.toString('base64'),
239
+ width: rendered.width,
240
+ height: rendered.height,
241
+ info: rendered.info,
242
+ };
243
+ }
244
+ /**
245
+ * The cache location of a source's preview.
246
+ * @param root the scope root.
247
+ * @param id the artifact id.
248
+ * @param content the design source.
249
+ * @returns the paths.
250
+ */
251
+ previewPaths(root, id, content) {
252
+ const dir = path.join(root.root, id, 'preview');
253
+ const key = hashOf(content).slice('sha256:'.length);
254
+ return { dir, png: path.join(dir, `${key}.png`), meta: path.join(dir, `${key}.json`) };
255
+ }
256
+ /**
257
+ * Read a cached preview, when both files are plain and agree on the size.
258
+ * @param root the scope root.
259
+ * @param id the artifact id.
260
+ * @param content the design source.
261
+ * @returns the preview, or undefined.
262
+ */
263
+ async readPreview(root, id, content) {
264
+ try {
265
+ const paths = this.previewPaths(root, id, content);
266
+ await assertWithin(root.root, paths.dir);
267
+ if (!(await assertPlainFile(paths.png)) || !(await assertPlainFile(paths.meta)))
268
+ return undefined;
269
+ const parsed = JSON.parse(await fs.readFile(paths.meta, 'utf8'));
270
+ if (parsed === null || typeof parsed !== 'object')
271
+ return undefined;
272
+ const fields = { ...parsed };
273
+ if (!isDesignInfo(fields.info) || typeof fields.width !== 'number' || typeof fields.height !== 'number')
274
+ return undefined;
275
+ const bytes = await fs.readFile(paths.png);
276
+ return {
277
+ mediaType: 'image/png',
278
+ data: bytes.toString('base64'),
279
+ width: fields.width,
280
+ height: fields.height,
281
+ info: fields.info,
282
+ };
283
+ }
284
+ catch {
285
+ return undefined;
286
+ }
287
+ }
288
+ /**
289
+ * The summary of a design, from the cache or a compile.
290
+ * @param root the scope root.
291
+ * @param id the artifact id.
292
+ * @param content the design source.
293
+ * @returns the summary, or undefined when the renderer is unavailable.
294
+ */
295
+ async infoFor(root, id, content) {
296
+ const cached = await this.readCachedInfo(root, id, content);
297
+ if (cached !== undefined)
298
+ return cached;
299
+ try {
300
+ const info = await this.designs.inspect(content);
301
+ await this.writeInfo(root, id, content, info);
302
+ return info;
303
+ }
304
+ catch (error) {
305
+ console.warn('[dsh-artifact-studio] design summary failed', id, error instanceof Error ? error.message : error);
306
+ return undefined;
307
+ }
308
+ }
309
+ /**
310
+ * Read a cached summary.
311
+ * @param root the scope root.
312
+ * @param id the artifact id.
313
+ * @param content the design source.
314
+ * @returns the summary, or undefined.
315
+ */
316
+ async readCachedInfo(root, id, content) {
317
+ try {
318
+ const paths = this.previewPaths(root, id, content);
319
+ await assertWithin(root.root, paths.dir);
320
+ if (!(await assertPlainFile(paths.meta)))
321
+ return undefined;
322
+ const parsed = JSON.parse(await fs.readFile(paths.meta, 'utf8'));
323
+ if (parsed === null || typeof parsed !== 'object')
324
+ return undefined;
325
+ const fields = { ...parsed };
326
+ return isDesignInfo(fields.info) ? fields.info : undefined;
327
+ }
328
+ catch {
329
+ return undefined;
330
+ }
331
+ }
332
+ /**
333
+ * Cache a summary for a source hash.
334
+ * @param root the scope root.
335
+ * @param id the artifact id.
336
+ * @param content the design source.
337
+ * @param info the summary.
338
+ */
339
+ async writeInfo(root, id, content, info) {
340
+ try {
341
+ const paths = this.previewPaths(root, id, content);
342
+ await assertWithin(root.root, paths.dir);
343
+ await withLock(paths.dir, async () => {
344
+ await fs.mkdir(paths.dir, { recursive: true });
345
+ await assertWithin(root.root, paths.meta);
346
+ await writeAtomic(paths.meta, `${JSON.stringify({ info }, null, 2)}\n`);
347
+ await this.prunePreview(paths.dir, path.basename(paths.png));
348
+ });
349
+ }
350
+ catch (error) {
351
+ // The artifact is saved; a cache failure only costs the next reader a compile.
352
+ console.warn('[dsh-artifact-studio] design cache failed', id, error instanceof Error ? error.message : error);
353
+ }
354
+ }
355
+ /**
356
+ * Cache a rendered preview.
357
+ * @param root the scope root.
358
+ * @param id the artifact id.
359
+ * @param content the design source.
360
+ * @param info the summary.
361
+ * @param width the image width.
362
+ * @param height the image height.
363
+ * @param bytes the PNG bytes.
364
+ */
365
+ async writePreview(root, id, content, info, width, height, bytes) {
366
+ try {
367
+ const paths = this.previewPaths(root, id, content);
368
+ await assertWithin(root.root, paths.dir);
369
+ await withLock(paths.dir, async () => {
370
+ await fs.mkdir(paths.dir, { recursive: true });
371
+ await assertWithin(root.root, paths.png);
372
+ await writeAtomic(paths.png, bytes);
373
+ await assertWithin(root.root, paths.meta);
374
+ await writeAtomic(paths.meta, `${JSON.stringify({ info, width, height }, null, 2)}\n`);
375
+ await this.prunePreview(paths.dir, path.basename(paths.png));
376
+ });
377
+ }
378
+ catch (error) {
379
+ console.warn('[dsh-artifact-studio] design preview cache failed', id, error instanceof Error ? error.message : error);
380
+ }
381
+ }
382
+ /**
383
+ * Drop cache files that do not belong to the current source hash.
384
+ * @param dir the preview directory.
385
+ * @param keep the file name to keep.
386
+ */
387
+ async prunePreview(dir, keep) {
388
+ const prefix = keep.replace(/\.png$/, '');
389
+ for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
390
+ if (!entry.isFile() || entry.isSymbolicLink())
391
+ continue;
392
+ if (entry.name.startsWith(prefix))
393
+ continue;
394
+ await fs.rm(path.join(dir, entry.name), { force: true });
395
+ }
135
396
  }
136
397
  }
@@ -5,7 +5,7 @@ Use this before you call \`artifact_create\`, and before an \`artifact_update\`
5
5
 
6
6
  ## When to use an artifact
7
7
 
8
- Use \`artifact_create\` when the user asks for an artifact, an artifact page, or an artifact doc. Pick \`page\` for an artifact page and \`doc\` for an artifact doc. Never write a file in the project instead. Write a project file only when the user asks for a file in the repo.
8
+ Use \`artifact_create\` when the user asks for an artifact, an artifact page, an artifact doc, or an artifact design. Pick \`page\` for an artifact page, \`doc\` for an artifact doc, and \`design\` for an OpenPencil design. Never write a file in the project instead. Write a project file only when the user asks for a file in the repo.
9
9
 
10
10
  ## Precedence
11
11
 
@@ -16,7 +16,34 @@ Use \`artifact_create\` when the user asks for an artifact, an artifact page, or
16
16
  ## Pick the type
17
17
 
18
18
  - \`doc\` for prose: reports, briefs, plans, specs, notes. It is Markdown, edited in a rich-text editor, and exported to Word, Markdown, and HTML. Use headings, short paragraphs, lists, tables, task lists, quotes, and fenced code. Do not paste HTML into a doc.
19
- - \`page\` for anything visual or interactive: dashboards, one-pagers, explainers, calculators, diagrams, prototypes.
19
+ - \`page\` for anything visual or interactive: dashboards, one-pagers, explainers, calculators, diagrams, and clickable prototypes the user asks for as a page.
20
+ - \`design\` for a layout the user will open on a canvas: UI mockups, wireframes, layout explorations, and screens that export as PNG, SVG, or a \`.fig\` document.
21
+
22
+ A request for a mockup or a wireframe always gets \`design\`, even when it shows a flow. Draw each step of the flow as its own frame. If the user offers both, such as "a page or a mockup", make a mockup. Use \`page\` for a mockup only when the user asks for a page or for something clickable. Never title or describe a page as a mockup.
23
+
24
+ ## Designs (OpenPencil Design JSX)
25
+
26
+ A design is OpenPencil Design JSX, not React DOM and not HTML. There are no imports, no HTML tags, and no CSS classes. Icons use the bundled Material Design Icons set.
27
+
28
+ Call this artifact a mockup when you talk to the user. The tools still take type \`design\`.
29
+
30
+ - Elements: \`Frame\`, \`Text\`, \`Rectangle\`, \`Ellipse\`, \`Line\`, \`Star\`, \`Polygon\`, \`Vector\`, \`Group\`, \`Section\`.
31
+ - Layout props: \`w\`, \`h\`, \`p\`, \`px\`, \`py\`, \`gap\`, \`flex\` (\`row\` or \`col\`), \`items\`, \`justify\`, \`bg\`, \`rounded\`, \`stroke\`, \`strokeWidth\`, \`opacity\`.
32
+ - Use \`flex\`, not \`dir\`. \`dir\` is accepted and does nothing, so every child sits at the same origin. A frame with \`flex\` sizes itself to its children unless you give it \`w\` or \`h\`.
33
+ - Text props: \`size\`, \`weight\`, \`color\`, \`font\`, \`lineHeight\`, \`letterSpacing\`, \`textAlign\`, \`maxLines\`.
34
+ - Put a background on the outer \`Frame\`; the preview crops transparent space around the content.
35
+ - Example: \`<Frame w={720} p={40} bg="#ffffff" flex="col" gap={12}><Text size={40} weight={700} color="#16181d">Title</Text><Text size={16} color="#5b6170">One line of context.</Text></Frame>\`
36
+ - Icons: \`<Icon name="mdi:home" size={24} color="#1b1712" />\`. Only the \`mdi:\` set is bundled. Common names: \`home\`, \`search\`, \`user\`, \`heart\`, \`star\`, \`check\`, \`close\`, \`plus\`, \`arrow-right\`, \`settings\`, \`bell\`, \`calendar\`, \`mail\`, \`image\`, \`file\`, \`folder\`, \`trash\`, \`edit\`, \`download\`, \`lock\`, \`eye\`, \`cart\`, \`chart-bar\`, \`alert\`, \`clock\`, \`map-marker\`, \`menu\`, \`chevron-right\`. An unknown set or name refuses the save. Icons draw as vectors and keep their 24 unit box.
37
+ - Text uses Inter, Roboto, or Noto Naskh Arabic, which ship with the package. Any other family substitutes a default face and returns a warning.
38
+ - A design has no network and no external images. Use solid and gradient fills, shapes, and text.
39
+ - The stored artifact is the JSX source. Send the complete source as \`content\` when you update a design. The host compiles and validates before saving, so a compile error refuses the write and returns the compiler message.
40
+ - Export is PNG, SVG, or \`.fig\`. The user can open the \`.fig\` in OpenPencil for a full canvas editor.
41
+
42
+ ### When a design write fails
43
+
44
+ - A compile, icon, or validation error names a problem in your source. Fix the source and try again.
45
+ - Any other error, such as "The design renderer stopped" or a missing module, is a fault in the plugin, not in your source. Stop and show the user the exact error.
46
+ - Never switch to a \`page\` or a \`doc\` to work around a failed design. Do it only when the user tells you to.
20
47
 
21
48
  ## The page sandbox
22
49
 
@@ -81,7 +108,7 @@ Tell the user in one or two sentences what you made or changed. Do not repeat th
81
108
  /** The artifact design skill, registered by the \`dsh-artifact-studio/skill\` host plugin. */
82
109
  export const ARTIFACT_DESIGN_SKILL = {
83
110
  name: 'artifact-design',
84
- description: 'Design rules for artifact pages and documents: when to use an artifact, precedence, the page sandbox, design tokens, dark mode, layout, typography, and the update rule.',
111
+ description: 'Design rules for artifact pages, documents, and OpenPencil designs: when to use an artifact, precedence, the page sandbox, Design JSX, design tokens, dark mode, layout, typography, and the update rule.',
85
112
  whenToUse: 'Load before artifact_create, when the user asks for an artifact, and before an artifact_update that changes layout or styling.',
86
113
  source: 'bundled',
87
114
  content: CONTENT,
@@ -329,6 +329,15 @@ export class ArtifactStore {
329
329
  }
330
330
  return manifest;
331
331
  }
332
+ /**
333
+ * Read only the manifest, without its content.
334
+ * @param root the scope root.
335
+ * @param id the artifact id.
336
+ * @returns the manifest.
337
+ */
338
+ async manifest(root, id) {
339
+ return this.readManifest(await artifactDir(root, id));
340
+ }
332
341
  /**
333
342
  * Read the manifest and content of the current or an earlier version.
334
343
  * @param root the scope root.
@@ -124,7 +124,7 @@ const SUMMARY_SCHEMA = {
124
124
  properties: {
125
125
  id: { type: 'string' },
126
126
  scope: { type: 'string', enum: ['workspace', 'library'] },
127
- type: { type: 'string', enum: ['page', 'doc'] },
127
+ type: { type: 'string', enum: ['page', 'doc', 'design'] },
128
128
  title: { type: 'string' },
129
129
  version: { type: 'integer' },
130
130
  updatedAt: { type: 'string' },
@@ -167,9 +167,9 @@ export function createTools(host) {
167
167
  additionalProperties: false,
168
168
  required: ['type', 'title', 'content'],
169
169
  properties: {
170
- type: { type: 'string', enum: ['page', 'doc'], description: 'page for HTML, doc for Markdown.' },
170
+ type: { type: 'string', enum: ['page', 'doc', 'design'], description: 'page for HTML, doc for Markdown, design for OpenPencil Design JSX. A mockup or wireframe is always design. For a design, load the artifact-design skill first: no imports, no HTML. If a design fails for a reason other than its source, report the error; never redo it as a page.' },
171
171
  title: { type: 'string', description: 'Short title, 1 to 120 characters.' },
172
- content: { type: 'string', description: 'The full HTML document or Markdown text, up to 2 MiB.' },
172
+ content: { type: 'string', description: 'The full HTML document, Markdown text, or Design JSX source, up to 2 MiB.' },
173
173
  scope: SCOPE_PARAM,
174
174
  },
175
175
  },
@@ -189,7 +189,10 @@ export function createTools(host) {
189
189
  content,
190
190
  source: { origin: 'agent', action: 'create', ...(exec.agent === undefined ? {} : { sessionId: exec.agent.id }) },
191
191
  });
192
- return { ...summary(manifest, target), warnings: warningsFor(type, content) };
192
+ const warnings = type === 'design'
193
+ ? (await service.read(target, manifest.id)).designInfo?.warnings ?? []
194
+ : warningsFor(type, content);
195
+ return { ...summary(manifest, target), warnings };
193
196
  },
194
197
  };
195
198
  const read = {
@@ -209,15 +212,28 @@ export function createTools(host) {
209
212
  type: 'object',
210
213
  additionalProperties: false,
211
214
  required: ['artifact', 'readVersion', 'content'],
212
- properties: { artifact: SUMMARY_SCHEMA, readVersion: { type: 'integer' }, content: { type: 'string' } },
215
+ properties: {
216
+ artifact: SUMMARY_SCHEMA,
217
+ readVersion: { type: 'integer' },
218
+ content: { type: 'string' },
219
+ designInfo: {
220
+ type: 'object',
221
+ description: 'The compiled summary of a design: pages, nodes, type counts, fonts, and warnings.',
222
+ },
223
+ },
213
224
  },
214
225
  render: (_args, value) => {
215
226
  const fields = record(value);
216
227
  const artifact = record(fields.artifact ?? null);
228
+ const info = record(fields.designInfo ?? null);
229
+ const summaryLine = info.nodes === undefined
230
+ ? ''
231
+ : `\n\nDesign: ${String(info.nodes)} nodes, ${String(info.pages)} page(s), fonts ${Array.isArray(info.fonts) && info.fonts.length > 0 ? info.fonts.map(String).join(', ') : 'none'}.`
232
+ + (Array.isArray(info.warnings) && info.warnings.length > 0 ? `\nWarnings:\n${info.warnings.map((item) => `- ${String(item)}`).join('\n')}` : '');
217
233
  return [
218
234
  {
219
235
  type: 'text',
220
- text: `${line(artifact, 'Artifact')} Showing version ${String(fields.readVersion)}.\n\n${String(fields.content)}`,
236
+ text: `${line(artifact, 'Artifact')} Showing version ${String(fields.readVersion)}.${summaryLine}\n\n${String(fields.content)}`,
221
237
  },
222
238
  ];
223
239
  },
@@ -227,7 +243,15 @@ export function createTools(host) {
227
243
  const id = requiredString(fields, 'id');
228
244
  const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined);
229
245
  const result = await service.read(target, id, optionalInteger(fields, 'version'));
230
- return { artifact: summary(result.manifest, target), readVersion: result.version, content: result.content };
246
+ const info = result.designInfo;
247
+ return {
248
+ artifact: summary(result.manifest, target),
249
+ readVersion: result.version,
250
+ content: result.content,
251
+ ...(info === undefined
252
+ ? {}
253
+ : { designInfo: { pages: info.pages, nodes: info.nodes, types: info.types, fonts: info.fonts, warnings: info.warnings } }),
254
+ };
231
255
  },
232
256
  };
233
257
  const update = {
@@ -236,6 +260,7 @@ export function createTools(host) {
236
260
  'Save a new version of an artifact. For a few local changes send edits; send complete content only when you rewrite most of it. Each edit oldText must occur exactly once.',
237
261
  'The update is refused when baseVersion is not the current version, for example after the user edited it; read it again and reapply your change. Never discard the user\'s edits.',
238
262
  'A layout or styling change follows the artifact-design skill and the same precedence: the user\'s request, then the design system, then your own choices.',
263
+ 'For a design, send the complete Design JSX source as content and read it first if you did not write it; edits are applied and validated too, but a design rewrite is usually smaller as one content value.',
239
264
  'Each call writes a version the user sees. Put every fix for one request, including all returned warnings, into one update; never send one update per finding.',
240
265
  ].join('\n'),
241
266
  parameters: {
@@ -245,7 +270,7 @@ export function createTools(host) {
245
270
  properties: {
246
271
  id: { type: 'string' },
247
272
  baseVersion: { type: 'integer', description: 'The version your change is based on.' },
248
- content: { type: 'string', description: 'Complete replacement content. Use this or edits.' },
273
+ content: { type: 'string', description: 'Complete replacement content. Use this or edits. For a design, send the complete Design JSX source.' },
249
274
  edits: {
250
275
  type: 'array',
251
276
  description: 'Replace-once edits applied in order. Each oldText must occur exactly once.',
@@ -281,7 +306,10 @@ export function createTools(host) {
281
306
  title,
282
307
  source: { origin: 'agent', action: 'update', ...(exec.agent === undefined ? {} : { sessionId: exec.agent.id }) },
283
308
  });
284
- return { ...summary(manifest, target), warnings: await writtenWarnings(manifest.type, content, edits === undefined ? undefined : () => service.read(target, id, manifest.version)) };
309
+ const warnings = manifest.type === 'design'
310
+ ? (await service.read(target, id, manifest.version)).designInfo?.warnings ?? []
311
+ : await writtenWarnings(manifest.type, content, edits === undefined ? undefined : () => service.read(target, id, manifest.version));
312
+ return { ...summary(manifest, target), warnings };
285
313
  },
286
314
  };
287
315
  const list = {
@@ -292,7 +320,7 @@ export function createTools(host) {
292
320
  additionalProperties: false,
293
321
  properties: {
294
322
  scope: { type: 'string', enum: ['workspace', 'library'], description: 'Defaults to workspace.' },
295
- type: { type: 'string', enum: ['page', 'doc'] },
323
+ type: { type: 'string', enum: ['page', 'doc', 'design'] },
296
324
  query: { type: 'string', description: 'Title substring, case-insensitive.' },
297
325
  offset: { type: 'integer' },
298
326
  },
@@ -349,12 +377,12 @@ export function createTools(host) {
349
377
  };
350
378
  const exportTool = {
351
379
  name: 'artifact_export',
352
- description: 'Write an artifact to a standalone file and return its path. A page exports as html; a doc exports as md, docx, or printable html.',
380
+ description: 'Write an artifact to a standalone file and return its path. A page exports as html; a doc exports as md, docx, or printable html; a design exports as png, svg, or .fig.',
353
381
  parameters: {
354
382
  type: 'object',
355
383
  additionalProperties: false,
356
384
  required: ['id', 'format'],
357
- properties: { id: { type: 'string' }, format: { type: 'string', enum: ['html', 'md', 'docx'] },
385
+ properties: { id: { type: 'string' }, format: { type: 'string', enum: ['html', 'md', 'docx', 'png', 'svg', 'fig'] },
358
386
  version: { type: 'integer', minimum: 1, description: 'Saved version to export. Omit for the current version.' } },
359
387
  },
360
388
  output: {