dsh-artifact-studio 0.7.3 → 0.9.0

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,14 +1,36 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import path from 'node:path';
3
- import { isDesignInfo, scopeOfId } from '../../contract.js';
3
+ import { isDesignInfo, scopeOfId, tokensToCss } from '../../contract.js';
4
4
  import { PAGE_CSP, composePage } from '../../render.js';
5
5
  import { DesignRenderer, PREVIEW_MAX_SIDE } from './design-render.js';
6
- import { clearWorkspaceDesignSystem, resolveDesignSystem, saveDesignSystem } from './design-system.js';
6
+ import { clearWorkspaceDesignSystem, saveDesignSystem } from './design-system.js';
7
+ import { resolveSystem, saveSystem, listSystems, setSystemDefault } from './design-catalog.js';
8
+ import { generationHash, generationSummary } from './generation.js';
9
+ import { declaredKit, getKit } from '../../kit.js';
10
+ import { composeBrief, composeSheetBrief } from './brief.js';
7
11
  import { ArtifactError } from './errors.js';
8
- import { docToHtml, writeExport } from './export.js';
12
+ import { docToHtml, sheetToPrintableHtml, writeExport } from './export.js';
13
+ import { findRecipe, readGuide, saveGuide } from './guide.js';
9
14
  import { assertWithin, withLock, writeAtomic } from './fsutil.js';
10
15
  import { assertPlainFile, libraryRoot, requireWorkspace, workspaceRoot, workspaceRootExisting } from './paths.js';
11
16
  import { ArtifactStore, applyEdits, hashOf } from './store.js';
17
+ import { parseSheetWorkbook, serializeSheetWorkbook } from '../../sheet/index.js';
18
+ /**
19
+ * Validate and canonicalise sheet content. A malformed workbook never reaches
20
+ * the store, and an accepted one always has stable ordering and formatting.
21
+ * @param content the JSON source.
22
+ * @returns the canonical JSON.
23
+ */
24
+ function canonicalSheet(content) {
25
+ try {
26
+ return serializeSheetWorkbook(parseSheetWorkbook(content));
27
+ }
28
+ catch (error) {
29
+ throw new ArtifactError('artifact/invalid-sheet', 'The sheet content is not a valid workbook.', {
30
+ message: error instanceof Error ? error.message : String(error),
31
+ });
32
+ }
33
+ }
12
34
  /**
13
35
  * One facade over the store, the scope roots, the design system, the design
14
36
  * renderer, and export. The route and the tools both call it, so both scopes
@@ -65,18 +87,24 @@ export class ArtifactService {
65
87
  * @returns the root, or undefined.
66
88
  */
67
89
  async optionalWorkspaceRoot(target) {
68
- if (target.workspaceId === undefined)
90
+ if (target.scope === 'library' || target.workspaceId === undefined)
69
91
  return undefined;
70
- const workspace = this.registry.get(target.workspaceId);
71
- return workspace === undefined ? undefined : workspaceRootExisting(this.config, workspace);
92
+ return workspaceRootExisting(this.config, requireWorkspace(this.registry, target.workspaceId));
72
93
  }
73
94
  /**
74
95
  * Resolve the design system for a target.
75
96
  * @param target the caller's context.
76
97
  * @returns tokens, source, and CSS.
77
98
  */
78
- async designSystem(target) {
79
- return resolveDesignSystem(await this.optionalWorkspaceRoot(target), await libraryRoot(this.config));
99
+ async designSystem(target, selection = {}) {
100
+ return resolveSystem(await this.optionalWorkspaceRoot(target), await libraryRoot(this.config), selection);
101
+ }
102
+ async listDesignSystems(target) {
103
+ return listSystems(await this.root(target));
104
+ }
105
+ async setDesignDefault(target, systemId, expectedRevision) {
106
+ await setSystemDefault(await this.root(target), systemId, expectedRevision);
107
+ return this.designSystem(target);
80
108
  }
81
109
  /**
82
110
  * Save tokens at one scope.
@@ -84,11 +112,17 @@ export class ArtifactService {
84
112
  * @param tokens partial or full tokens.
85
113
  * @returns the saved tokens and scope.
86
114
  */
87
- async saveDesignSystem(target, tokens) {
115
+ async saveDesignSystem(target, tokens, options) {
88
116
  const root = await this.root(target);
117
+ const base = await this.designSystem(target);
118
+ if (options !== undefined)
119
+ return { ...await saveSystem(root, base.tokens, tokens, options), scope: root.scope };
120
+ const catalog = await listSystems(root);
121
+ if (catalog.defaultId !== null) {
122
+ throw new ArtifactError('artifact/stale-catalog', 'A named default is selected. Read the catalog and supply systemId and expectedRevision.');
123
+ }
89
124
  const saved = await saveDesignSystem(root, await libraryRoot(this.config), tokens);
90
- const resolved = await this.designSystem(target);
91
- return { ...resolved, scope: saved.scope };
125
+ return { ...await this.designSystem(target), scope: saved.scope };
92
126
  }
93
127
  /**
94
128
  * Remove the workspace override.
@@ -96,9 +130,131 @@ export class ArtifactService {
96
130
  * @returns the design system now in force.
97
131
  */
98
132
  async clearWorkspaceDesignSystem(target) {
99
- await clearWorkspaceDesignSystem(await this.root({ ...target, scope: 'workspace' }));
133
+ const root = await this.root({ ...target, scope: 'workspace' });
134
+ const catalog = await listSystems(root);
135
+ if (catalog.defaultId !== null)
136
+ await setSystemDefault(root, null, catalog.revision);
137
+ await clearWorkspaceDesignSystem(root);
100
138
  return this.designSystem(target);
101
139
  }
140
+ /**
141
+ * The guides in force for a target. Reading never creates a workspace store.
142
+ * @param target the caller's context.
143
+ * @returns the workspace and library guides.
144
+ */
145
+ async guides(target) {
146
+ return {
147
+ workspace: await readGuide(await this.optionalWorkspaceRoot(target)),
148
+ library: await readGuide(await libraryRoot(this.config)),
149
+ };
150
+ }
151
+ /**
152
+ * Change one scope's guide.
153
+ * @param target the caller's context; `scope` picks the guide.
154
+ * @param patch the change.
155
+ * @returns the saved guide and its scope.
156
+ */
157
+ async saveGuide(target, patch) {
158
+ const root = await this.root(target);
159
+ return { scope: root.scope, guide: await saveGuide(root, patch) };
160
+ }
161
+ /**
162
+ * Resolve a recipe id for an artifact type, or refuse it.
163
+ * @param target the caller's context.
164
+ * @param id the recipe id.
165
+ * @param type the artifact type.
166
+ * @returns the recipe.
167
+ */
168
+ async recipe(target, id, type) {
169
+ const recipe = findRecipe(await this.guides(target), id);
170
+ if (recipe === undefined) {
171
+ throw new ArtifactError('artifact/unknown-recipe', `No recipe "${id}". Call artifact_brief without a recipe to list them.`, { recipe: id });
172
+ }
173
+ if (!recipe.types.includes(type)) {
174
+ throw new ArtifactError('artifact/unknown-recipe', `The ${id} recipe is for ${recipe.types.join(', ')}, not ${type}.`, { recipe: id, type });
175
+ }
176
+ return recipe;
177
+ }
178
+ /**
179
+ * The recipe a stored artifact follows, when it names one that still resolves.
180
+ * @param target the caller's context.
181
+ * @param manifest the artifact.
182
+ * @returns the recipe, or undefined.
183
+ */
184
+ async recipeOf(target, manifest) {
185
+ if (manifest.generation !== undefined) {
186
+ const pinned = (await this.store.read(await this.root(target, manifest.id), manifest.id, manifest.version)).generation?.recipe;
187
+ return pinned ? { ...pinned, source: manifest.scope } : undefined;
188
+ }
189
+ if (manifest.recipe === undefined)
190
+ return undefined;
191
+ const recipe = findRecipe(await this.guides({ ...target, scope: manifest.scope }), manifest.recipe);
192
+ return recipe !== undefined && recipe.types.includes(manifest.type) ? recipe : undefined;
193
+ }
194
+ /**
195
+ * Assemble the brief for a new artifact.
196
+ * @param target the caller's context.
197
+ * @param type the artifact type.
198
+ * @param recipeId the recipe, when the caller chose one.
199
+ * @returns the brief and the recipe it used.
200
+ */
201
+ async brief(target, type, recipeId, selection = {}) {
202
+ const layers = await this.guides(target);
203
+ if (type === 'sheet') {
204
+ if (recipeId !== undefined) {
205
+ throw new ArtifactError('artifact/unknown-recipe', 'Sheets do not use recipes.', { recipe: recipeId, type });
206
+ }
207
+ return { brief: composeSheetBrief(layers) };
208
+ }
209
+ const recipe = recipeId === undefined ? undefined : findRecipe(layers, recipeId);
210
+ if (recipeId !== undefined && (recipe === undefined || !recipe.types.includes(type))) {
211
+ throw new ArtifactError('artifact/unknown-recipe', 'No compatible recipe for this artifact type.', { recipe: recipeId, type });
212
+ }
213
+ const design = await this.designSystem(target, selection);
214
+ const root = target.scope === 'library' ? await libraryRoot(this.config) : await this.optionalWorkspaceRoot(target);
215
+ const siblings = recipe === undefined || root === undefined
216
+ ? []
217
+ : (await this.store.list(root, { type, recipe: recipe.id, limit: 3 })).items;
218
+ const brief = composeBrief({ type, recipe, layers, tokens: design.tokens, tokenSource: design.source, siblings });
219
+ return recipe === undefined ? { brief } : { brief, recipe };
220
+ }
221
+ async freeze(target, type, content, recipeId, selection = {}) {
222
+ const design = await this.designSystem(target, selection);
223
+ const recipe = recipeId === undefined ? null : await this.recipe(target, recipeId, type);
224
+ const kit = type === 'page' ? declaredKit(content) ?? null : null;
225
+ if (kit !== null && !getKit(kit))
226
+ throw new ArtifactError('artifact/unsupported-kit', 'The selected kit release is not installed.');
227
+ return { schemaVersion: 1, tokens: design.tokens, system: design.system ?? null, tokenSource: design.source,
228
+ recipe, kit, conventionsHash: generationHash(JSON.stringify(await this.guides(target))) };
229
+ }
230
+ async versionDesign(target, result) {
231
+ const generation = result.generation;
232
+ if (!generation)
233
+ return this.designSystem({ ...target, scope: result.manifest.scope });
234
+ if (generation.kit !== null && !getKit(generation.kit))
235
+ throw new ArtifactError('artifact/unsupported-kit', 'The saved kit release is not installed.');
236
+ return { tokens: generation.tokens, css: tokensToCss(generation.tokens), source: generation.tokenSource,
237
+ ...(generation.system ? { system: generation.system } : {}) };
238
+ }
239
+ async rebase(target, id, input) {
240
+ const root = await this.root(target, id);
241
+ const current = await this.store.read(root, id);
242
+ if (current.manifest.type === 'design')
243
+ throw new ArtifactError('artifact/unsupported-type', 'Mockup source must be restyled explicitly.');
244
+ if (current.manifest.type === 'sheet')
245
+ throw new ArtifactError('artifact/unsupported-type', 'A sheet has no design or recipe to rebase.', { type: current.manifest.type });
246
+ const recipe = input.recipe ?? current.manifest.recipe;
247
+ const generation = input.recipe === undefined && input.design === undefined
248
+ ? await this.freeze({ ...target, scope: root.scope }, current.manifest.type, current.content, recipe)
249
+ :
250
+ input.design
251
+ ? await this.freeze({ ...target, scope: root.scope }, current.manifest.type, current.content, recipe, input.design)
252
+ : (current.generation ?? await this.freeze({ ...target, scope: root.scope }, current.manifest.type, current.content, recipe));
253
+ if (input.recipe !== undefined && generation.recipe?.id !== input.recipe) {
254
+ generation.recipe = await this.recipe({ ...target, scope: root.scope }, input.recipe, current.manifest.type);
255
+ }
256
+ return this.store.update(root, id, { baseVersion: input.baseVersion, recipe, generation, source: { ...input.source, action: 'rebase' } });
257
+ }
102
258
  /**
103
259
  * Create an artifact. A design is compiled before anything is written, so an
104
260
  * invalid source never creates a directory or a version.
@@ -107,11 +263,20 @@ export class ArtifactService {
107
263
  * @returns the manifest.
108
264
  */
109
265
  async create(target, input) {
266
+ if (input.type === 'sheet' && input.recipe !== undefined) {
267
+ throw new ArtifactError('artifact/bad-request', 'Sheets do not use recipes.', { recipe: input.recipe, type: input.type });
268
+ }
269
+ if (input.recipe !== undefined)
270
+ await this.recipe(target, input.recipe, input.type);
110
271
  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);
272
+ const content = input.type === 'sheet' ? canonicalSheet(input.content) : input.content;
273
+ const info = input.type === 'design' ? await this.designs.inspect(content) : undefined;
274
+ const generation = input.type === 'design' || input.type === 'sheet'
275
+ ? undefined
276
+ : await this.freeze({ ...target, scope: root.scope }, input.type, content, input.recipe, input.design);
277
+ const manifest = await this.store.create(root, { ...input, content, generation });
113
278
  if (info !== undefined)
114
- await this.writeInfo(root, manifest.id, input.content, info);
279
+ await this.writeInfo(root, manifest.id, content, info);
115
280
  return manifest;
116
281
  }
117
282
  /**
@@ -125,9 +290,10 @@ export class ArtifactService {
125
290
  async read(target, id, version) {
126
291
  const root = await this.root(target, id);
127
292
  const result = await this.store.read(root, id, version);
128
- const design = await this.designSystem(target);
293
+ const design = await this.versionDesign(target, result);
129
294
  const payload = {
130
- ...result,
295
+ manifest: result.manifest, content: result.content, version: result.version,
296
+ ...(result.generation ? { generation: generationSummary(result.generation) } : {}),
131
297
  designCss: design.css,
132
298
  design: design.tokens,
133
299
  };
@@ -150,9 +316,29 @@ export class ArtifactService {
150
316
  async update(target, id, input) {
151
317
  const root = await this.root(target, id);
152
318
  const current = await this.store.manifest(root, id);
153
- if (current.type !== 'design')
154
- return this.store.update(root, id, input);
155
319
  const existing = await this.store.read(root, id);
320
+ if (current.type === 'sheet') {
321
+ if (input.recipe !== undefined)
322
+ throw new ArtifactError('artifact/bad-request', 'Sheets do not use recipes.', { type: current.type });
323
+ if (input.content !== undefined && input.edits !== undefined) {
324
+ throw new ArtifactError('artifact/bad-request', 'Send either content or edits, not both.');
325
+ }
326
+ let next = input.content;
327
+ if (next === undefined && input.edits !== undefined)
328
+ next = applyEdits(existing.content, input.edits);
329
+ if (next !== undefined)
330
+ next = canonicalSheet(next);
331
+ return this.store.update(root, id, { ...input, content: next, edits: undefined });
332
+ }
333
+ if (current.type !== 'design') {
334
+ let generation = existing.generation ?? await this.freeze({ ...target, scope: root.scope }, current.type, existing.content, input.recipe ?? current.recipe);
335
+ if (input.recipe !== undefined && input.recipe !== generation.recipe?.id) {
336
+ generation = { ...generation, recipe: await this.recipe({ ...target, scope: root.scope }, input.recipe, current.type) };
337
+ }
338
+ return this.store.update(root, id, { ...input, generation });
339
+ }
340
+ if (input.recipe !== undefined)
341
+ await this.recipe({ ...target, scope: root.scope }, input.recipe, current.type);
156
342
  let next = input.content;
157
343
  if (next === undefined && input.edits !== undefined)
158
344
  next = applyEdits(existing.content, input.edits);
@@ -173,7 +359,11 @@ export class ArtifactService {
173
359
  * @returns the new manifest.
174
360
  */
175
361
  async restore(target, id, version, source, baseVersion) {
176
- return this.store.restore(await this.root(target, id), id, version, source, baseVersion);
362
+ const root = await this.root(target, id);
363
+ const old = await this.store.read(root, id, version);
364
+ const generation = old.manifest.type === 'design' || old.manifest.type === 'sheet' || old.generation ? undefined
365
+ : await this.freeze({ ...target, scope: root.scope }, old.manifest.type, old.content, old.manifest.recipe);
366
+ return this.store.restore(root, id, version, source, baseVersion, generation);
177
367
  }
178
368
  async history(target, id) {
179
369
  return this.store.history(await this.root(target, id), id);
@@ -191,11 +381,22 @@ export class ArtifactService {
191
381
  * @returns printable HTML.
192
382
  */
193
383
  async printable(target, id, version) {
194
- const { manifest, content } = await this.store.read(await this.root(target, id), id, version);
384
+ const result = await this.store.read(await this.root(target, id), id, version);
385
+ const { manifest, content } = result;
195
386
  if (manifest.type === 'design') {
196
387
  throw new ArtifactError('artifact/unsupported-format', 'A design cannot be printed.', { type: manifest.type });
197
388
  }
198
- const design = await this.designSystem(target);
389
+ const design = await this.versionDesign(target, result);
390
+ if (manifest.type === 'sheet') {
391
+ let workbook;
392
+ try {
393
+ workbook = parseSheetWorkbook(content);
394
+ }
395
+ catch {
396
+ throw new ArtifactError('artifact/corrupt', 'The saved sheet content cannot be read.', { id: manifest.id });
397
+ }
398
+ return { html: sheetToPrintableHtml(workbook, design.css, manifest.title) };
399
+ }
199
400
  return { html: manifest.type === 'page'
200
401
  ? composePage(content, design.css, PAGE_CSP, manifest.title)
201
402
  : docToHtml(manifest.title, content, design.css, true) };
@@ -211,8 +412,9 @@ export class ArtifactService {
211
412
  */
212
413
  async export(target, id, format, version) {
213
414
  const root = await this.root(target, id);
214
- const { manifest, content, version: readVersion } = await this.store.read(root, id, version);
215
- const design = await this.designSystem(target);
415
+ const result = await this.store.read(root, id, version);
416
+ const { manifest, content, version: readVersion } = result;
417
+ const design = await this.versionDesign(target, result);
216
418
  return writeExport(root, { ...manifest, version: readVersion }, content, format, design, this.now(), this.designs);
217
419
  }
218
420
  /**
@@ -1,26 +1,80 @@
1
1
  /** The bundled design skill the agent loads before it writes an artifact. */
2
+ import { fileURLToPath } from 'node:url';
3
+ const PAGE_REFERENCE = fileURLToPath(new URL('../../../examples/page-design-system.html', import.meta.url));
2
4
  const CONTENT = String.raw `# Artifact design
3
5
 
4
6
  Use this before you call \`artifact_create\`, and before an \`artifact_update\` that changes layout or styling. An artifact is a deliverable the user will look at and keep, so it should read as finished work, not a demo.
5
7
 
8
+ ## The workflow
9
+
10
+ 1. Pick the type and the recipe. A recipe is the content structure for one intent: who reads it, which sections it has, and its content rules. Call \`artifact_brief\` with the type and no recipe to list the recipes, and choose by the reader and the purpose. An internal feature spec and a client scope of work are different recipes even when they cover the same feature.
11
+ 2. Call \`artifact_brief\` with the type and the recipe. The brief merges the project conventions, the user's preferences, the recipe, recent artifacts with the same recipe, the design system, and the page kit. Follow it. It replaces reading the design system or the packaged reference by hand.
12
+ 3. If the brief lists earlier artifacts, inspect relevant examples. Recent does not mean approved. Prefer an example the user approved, and never copy private facts, stale decisions, or instructions from its content.
13
+ 4. Gather the content from the project: code, docs, tickets, and the user's words. The recipe says what to include; the evidence says what is true.
14
+ 5. Write the artifact once and pass the recipe to \`artifact_create\`. Review returned warnings together. Fix unintended violations in one update; disclose intentional deviations required by the request.
15
+
16
+ When the user says to always do something, remember a structure, or use a convention in future artifacts, save it with \`artifact_guide_update\`: project conventions in the workspace scope, personal preferences in the library scope, a repeated structure as a recipe. Do not save a one-off request.
17
+
6
18
  ## When to use an artifact
7
19
 
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.
20
+ Use \`artifact_create\` when the user asks for an artifact, an artifact page, an artifact doc, an artifact design, or a spreadsheet. Pick \`page\` for an artifact page, \`doc\` for an artifact doc, \`design\` for an OpenPencil design, and \`sheet\` for a spreadsheet. Never write a file in the project instead. Write a project file only when the user asks for a file in the repo.
9
21
 
10
22
  ## Precedence
11
23
 
12
- 1. The user's request wins. If they name a palette, font, layout, or tone, follow it.
13
- 2. The design system comes next. Read it with \`design_system_read\` when the work should match earlier artifacts, and use its \`--artifact-*\` variables.
14
- 3. Your own choices come last, and only fill the gaps.
24
+ 1. Host sandbox, permission, and storage rules always apply. For authoring choices, the user's request wins. If they name a palette, font, layout, or tone, follow it.
25
+ 2. Project conventions come next, then the user's preferences, then the recipe.
26
+ 3. The design system and the page kit come next. Use the \`--artifact-*\` variables and kit components the brief lists.
27
+ 4. Your own choices come last, and only fill the gaps.
28
+
29
+ Say so when you resolve a conflict against a saved convention.
30
+
31
+ ## Projects and scopes
32
+
33
+ An artifact belongs to the session's project unless the user opened or referenced another project's artifact. The artifact reference names that project's workspace id. Pass it as \`workspaceId\` to the artifact tools and to \`design_system_read\`; omit it for this project. The library is shared across projects, so it needs no workspace id.
15
34
 
16
35
  ## Pick the type
17
36
 
18
37
  - \`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
38
  - \`page\` for anything visual or interactive: dashboards, one-pagers, explainers, calculators, diagrams, and clickable prototypes the user asks for as a page.
20
39
  - \`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.
40
+ - \`sheet\` for tabular work the user will edit as a spreadsheet: budgets, trackers, inventories, comparisons, and any grid whose cells hold numbers or formulas. Export is CSV or XLSX.
21
41
 
22
42
  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
43
 
44
+ ## Choose the reader's task
45
+
46
+ Establish the audience, their question, and the observable outcome from the request and available evidence. Ask only about a material unresolved decision. A simple artifact does not need its own planning document or approval round unless the project's rules require one.
47
+
48
+ Choose the structure by the task, not by a favorite template. The built-in recipes cover the common tasks, and their rules carry the detail:
49
+
50
+ - Architecture walkthrough (\`architecture\`): show boundaries, dependencies, and one request or data flow.
51
+ - Feature walkthrough (\`feature-spec\`): name the actor and starting conditions, show the actions and alternate paths, and state the resulting behavior.
52
+ - Client deliverable (\`client-scope\`): the client's terms, agreed outcomes, and technical detail suited to the reader.
53
+ - UI proposal (\`ui-proposal\`): show only the relevant screens and interaction states. Mark simulated actions. A static canvas mockup remains type \`design\`; a requested clickable page remains type \`page\`.
54
+ - Technical decision (\`technical-decision\`): state the recommendation, compare options with evidence and tradeoffs, and name what would change the decision.
55
+ - Investigation report (\`investigation\`): separate observations, evidence, hypotheses, and unresolved checks. Do not present a hypothesis as a confirmed cause.
56
+ - Metrics dashboard (\`dashboard\`): name sources, units, time range, baseline, and missing data. Derive charts, tables, labels, and selection details from one dataset. Never turn missing values into zero.
57
+
58
+ Do not invent metrics, owners, customer quotes, or product claims. Label illustrative data. Static reports need no fake loading, pending, or error states. Explain charts and diagrams in text as well as color.
59
+
60
+ ## Use one design system
61
+
62
+ The page itself, meaning its header, sections, tables, and callouts, uses the artifact design system and the kit, so artifacts look the same from one session to the next. A product UI shown inside the page is different: recreate the product's real look inside an \`ak-frame\` with \`ak-demo\`, using its own colors and fonts from its code, defined once as custom properties on the \`.ak-demo\` element. Inspect the project's design docs, CSS custom properties, theme configuration, and components for that. The user's explicit visual brief still wins. Do not copy the Artifact Studio editor's controls into the artifact.
63
+
64
+ If the project wants its own brand for every artifact, that belongs in the project design system through \`design_system_update\`, which the user must ask for. For a single page the user asks to style in a different brand, map that brand into page-local semantic variables on \`body\` and use those variables consistently in that page. These local variables are the exception to using injected values directly. Define their dark values with \`:root[data-artifact-theme="dark"] body\` and their export/system values inside \`@media (prefers-color-scheme: dark)\` with \`:root[data-artifact-theme="auto"] body\`. A later bare \`:root\` rule cannot override the more specific injected dark rules. Keep both themes coherent. Do not call \`design_system_update\` to change shared settings unless the user asked for that change. If the project has no system, use the resolved artifact system and its default patterns rather than inventing a competing palette.
65
+
66
+ ## Named design systems and pinned versions
67
+
68
+ Each scope keeps a catalog of named design systems with immutable revisions. Read it with \`design_system_list\` before creating or changing one. \`design_system_update\` with \`systemId\` and the catalog \`expectedRevision\` adds a revision; \`createNew\` starts a second system; \`makeDefault\` chooses what new artifacts inherit. A stale revision fails rather than overwriting another change, so reload the catalog and reapply.
69
+
70
+ Every version you create pins the design tokens, the system identity, the recipe definition, and the kit release. A later edit reuses that snapshot, so editing text never restyles an artifact. To adopt newer settings, call \`artifact_rebase\` with the \`baseVersion\` the user is looking at. It appends one version and keeps the content. Do it only when the user asks for the new design, and say which system revision it will pin. A version saved before pinning existed stays live and is labelled that way; do not claim its original theme can be recovered.
71
+
72
+ ## The page kit
73
+
74
+ A page opts in to the versioned artifact kit with \`<meta name="artifact-kit" content="1">\`. The renderer then injects the kit's component CSS and its switch script after the tokens. The brief lists every component. Use them instead of writing your own header, callout, badge, table, code block, steps, before-and-after switch, or product frame. That shared vocabulary is what keeps one project's pages consistent. A released kit version keeps its component definitions, and every saved version also pins its tokens, so an edit keeps the design it was made with. Do not promise pixel-identical rendering across machines: installed fonts and the browser still vary.
75
+
76
+ For a page without the kit, such as an older page you are editing, the packaged HTML reference at \`${PAGE_REFERENCE}\` shows the token patterns. It renders only through the artifact renderer. Do not add a framework, CDN, build system, or local server for a self-contained page.
77
+
24
78
  ## Designs (OpenPencil Design JSX)
25
79
 
26
80
  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.
@@ -59,13 +113,15 @@ A page renders in an opaque-origin iframe with every network request blocked.
59
113
 
60
114
  The host injects these on \`:root\` before your markup:
61
115
 
62
- - Colors: \`--artifact-color-primary\`, \`-accent\`, \`-surface\`, \`-text\`, \`-muted\`.
116
+ - Colors use the prefix \`--artifact-color-\`: \`background\` for the page, \`surface\` for an object, \`raised\` for secondary grouping, \`text\` and \`muted\` for text, \`primary\` for links, and \`accent\` for non-text emphasis.
117
+ - \`border\` is a quiet divider; \`control\` is the stronger border that identifies an input. Use \`focus\` for keyboard focus and \`success\`, \`warning\`, or \`danger\` with a text status on a neutral background. Do not rely on color alone.
118
+ - Pair \`--artifact-color-action\` backgrounds with \`--artifact-color-action-text\` foregrounds. Never assume the surface color is readable button text. JSON calls this role \`actionText\`; CSS uses \`action-text\`.
63
119
  - Fonts: \`--artifact-font-family\` for body text, \`--artifact-font-display\` for headings, \`--artifact-font-mono\` for code and data.
64
120
  - Sizes: \`--artifact-font-size-0\` to \`-6\`, \`--artifact-space-0\` to \`-6\`, \`--artifact-radius-sm\`, \`-md\`, \`-lg\`.
65
121
 
66
- Use the variables instead of literal colors and fonts. Derive borders and subtle fills from them, for example \`color-mix(in srgb, var(--artifact-color-text) 12%, transparent)\`. A page that hard-codes \`#fff\` cards over token text breaks in dark mode.
122
+ Use the variables instead of literal colors and fonts. Derive borders and subtle fills from them, for example \`color-mix(in srgb, var(--artifact-color-text) 12%, transparent)\`. A page that hard-codes \`#fff\` cards over token text breaks in dark mode. The page check reports literal colors and font names in declarations; a custom property definition such as \`--demo-bg: #0d0d14\` is allowed, so define a replica's palette once and reference it with \`var()\`.
67
123
 
68
- Dark mode is opt in. Add \`<meta name="color-scheme" content="light dark">\` and the host switches the color variables to the dark set when the user's theme is dark. Only add it when every color on the page comes from the variables or from \`color-mix\` over them.
124
+ Dark mode is opt in. The kit components follow it with no extra work. Add \`<meta name="color-scheme" content="light dark">\` and the host switches the color variables to the dark set when the user's theme is dark. Use it for new fully token-based pages and verify both themes. Only add it when every color on the page comes from the variables or from \`color-mix\` over them. The root attribute is \`data-artifact-theme\`, not \`data-theme\`. Do not add a theme switcher to every deliverable; the host already selects its theme.
69
125
 
70
126
  ## Layout and type
71
127
 
@@ -75,7 +131,25 @@ Dark mode is opt in. Add \`<meta name="color-scheme" content="light dark">\` and
75
131
  - Prefer one strong layout over many equal boxes. Avoid a grid of identical icon cards, an all-caps label above every heading, gradient text, glassmorphism, and decorative emoji.
76
132
  - Use one motion moment at most, and respect \`prefers-reduced-motion\`.
77
133
  - Numbers use \`font-variant-numeric: tabular-nums\`. Charts label their axes and units, and color encodes meaning, not decoration.
78
- - Interactive controls are real \`button\` and \`input\` elements with visible focus and labels.
134
+ - Interactive controls are real \`button\`, \`input\`, and \`select\` elements with visible focus and labels. Use \`type="button"\` for actions; native form navigation is blocked. Handle Enter without navigation, validate inputs, and state what a simulated action does. Keep user input on an actual error; add pending and retry states only for actions that need them.
135
+ - Match control borders and placeholder text to their semantic roles. Style selection, caret, scrollbars, and tabular numerals as part of the same system. Keep body text at 4.5:1 contrast, large text and control boundaries at 3:1, and provide keyboard access. Saved custom palettes are preserved, so verify their contrast rather than assuming it.
136
+ - A page has no storage or feedback bridge and no bundled chart libraries. Interactions are local to the view unless the tools explicitly provide another contract. Do not imply that a local form updates an account or sends a chat message.
137
+
138
+ ## Sheets
139
+
140
+ A sheet is a JSON workbook, not prose and not HTML. Call \`artifact_brief\` with type \`sheet\` for the shape and rules, then \`artifact_create\` with the whole object. The stored content is:
141
+
142
+ - \`schemaVersion: 1\` and a \`sheets\` array. Each sheet has a unique name and a \`cells\` object keyed by A1 references. A plain string, number, or boolean is the cell value; a string starting with \`=\` is a formula; a styled cell is \`{ "value": 1200, "style": { "bold": true, "numberFormat": "currency" } }\`.
143
+ - \`columnWidths\` maps a column letter to pixels, such as \`{ "A": 160 }\`.
144
+ - Never put HTML, Markdown, or prose paragraphs in cells. Put labels in one row or column and data beside them.
145
+
146
+ After creating a sheet, edit it with \`artifact_sheet_update\`, not by rewriting the whole JSON. Read it first, then send one operations array with the current \`baseVersion\`: \`set\` a cell or formula, \`write\` a rectangular block, \`clear\` or \`format\` a range, and \`add-sheet\`, \`rename-sheet\`, \`delete-sheet\`, or \`set-column-width\` to change structure. A formula warning comes back in \`warnings\`; fix all of them in one update.
147
+
148
+ Formulas are Excel syntax and run through a bundled parser with a gap layer for common functions: \`=SUM(B2:B3)\`, \`=IF(B2>1000,"big","small")\`, \`=Sheet2!A1*2\`, \`=VLOOKUP(A2,A2:C9,3,FALSE)\`. An unknown function shows \`#NAME?\`, a broken reference shows \`#REF!\`, and a circular reference shows \`#CYCLE!\`. Dates are Excel serial days; set \`numberFormat\` to \`date\` to show them as a date. A top-level SUM, AVERAGE, MIN, MAX, PRODUCT, or MEDIAN reports a referenced error the way Excel does.
149
+
150
+ Formatting is per cell: bold, italic, underline, strike, left/center/right alignment, text and fill hex colors, and a number format of general, number, integer, currency, percent, or date. Keep a header row bold with a quiet fill; do not color-code without a legend.
151
+
152
+ A sheet exports as CSV (first sheet only) or XLSX (every sheet, with styles, formulas, and cached results). The user can also print it or save it as PDF from the panel. Before saving, check sheet names, header labels, units, and that every total has a formula.
79
153
 
80
154
  ## Documents
81
155
 
@@ -88,7 +162,9 @@ Dark mode is opt in. Add \`<meta name="color-scheme" content="light dark">\` and
88
162
  Every \`artifact_create\` and \`artifact_update\` call writes a new version the user sees in History. Treat each save as a release, not a draft.
89
163
 
90
164
  - Finish the artifact before the first save. Reread the full draft once for broken markup, CSS that hides or overrides elements such as \`[hidden]\`, controls without handlers, placeholder copy, and the sandbox rules above.
91
- - To check a page visually, render a scratch copy outside the artifact, for example a temporary HTML file in a browser tool. Fix what you find there, then create the artifact once.
165
+ - To check a page visually, render a scratch copy outside the artifact using the real resolved token CSS, \`composePage\`, CSP, and \`sandbox="allow-scripts"\` when available. A bare HTML file cannot verify injected tokens or sandbox behavior. This plugin has no unpublished page-preview tool.
166
+ - In one batched pass, check 380 and 700 pixel panels and a wide view in light and dark when supported. Check overflow, long labels, reading order, keyboard focus, contrast, chart/table agreement, and every actual interaction. Check script/resource errors. Fix all concrete findings together and use at most one confirmation pass for normal refinement.
167
+ - If browser verification is unavailable, state that rendering and interactions remain unverified. Do not install browser infrastructure or create repeated versions to compensate. If the user needs a saved deliverable, use source preflight and save once with that limit disclosed.
92
168
  - If a check after saving finds problems, fix all of them in one \`artifact_update\`. Never send one update per finding.
93
169
  - Do not run polish passes the user did not ask for. One create, plus at most one corrective update, is the normal result of one request.
94
170
 
@@ -108,8 +184,8 @@ Tell the user in one or two sentences what you made or changed. Do not repeat th
108
184
  /** The artifact design skill, registered by the \`dsh-artifact-studio/skill\` host plugin. */
109
185
  export const ARTIFACT_DESIGN_SKILL = {
110
186
  name: 'artifact-design',
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.',
112
- whenToUse: 'Load before artifact_create, when the user asks for an artifact, and before an artifact_update that changes layout or styling.',
187
+ description: 'Author artifact pages, documents, spreadsheets, and OpenPencil mockups: pick a recipe for the intent, follow the artifact brief, build pages from the versioned kit, edit sheet cells with artifact_sheet_update, save lasting conventions, and save each version once.',
188
+ whenToUse: 'Load before artifact_create, when the user asks for an artifact, before an artifact_update that changes layout or styling, and when the user asks to remember an artifact convention.',
113
189
  source: 'bundled',
114
190
  content: CONTENT,
115
191
  };