dsh-artifact-studio 0.8.0 → 0.13.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.
- package/README.md +72 -10
- package/THIRD_PARTY_NOTICES.md +57 -0
- package/assets/canvas.engine.js +72 -72
- package/assets/canvas.viewer.js +6415 -0
- package/client.canvas.js +1 -1
- package/client.doc.js +67 -79
- package/client.js +313 -291
- package/client.sheet.js +218 -0
- package/dist/contract.js +32 -5
- package/dist/host/lib/assets.js +12 -0
- package/dist/host/lib/brief.js +127 -0
- package/dist/host/lib/checks.js +62 -8
- package/dist/host/lib/design-catalog.js +149 -0
- package/dist/host/lib/design-render.js +37 -0
- package/dist/host/lib/design-system.js +1 -1
- package/dist/host/lib/export.js +123 -5
- package/dist/host/lib/fsutil.js +41 -0
- package/dist/host/lib/generation.js +36 -0
- package/dist/host/lib/guide.js +130 -0
- package/dist/host/lib/paths.js +2 -1
- package/dist/host/lib/recipes.js +224 -0
- package/dist/host/lib/rpc.js +20 -5
- package/dist/host/lib/service.js +253 -24
- package/dist/host/lib/skill.js +59 -18
- package/dist/host/lib/store.js +107 -25
- package/dist/host/lib/svg-model.js +85 -0
- package/dist/host/lib/svg-viewer.js +380 -0
- package/dist/host/lib/tools.js +346 -35
- package/dist/host/lib/validate.js +24 -0
- package/dist/host/lib/viewer.js +150 -0
- package/dist/host/lib/xlsx.js +314 -0
- package/dist/host/worker/design-worker.js +71 -5
- package/dist/host/worker/page-model.js +169 -0
- package/dist/html-tags.js +51 -0
- package/dist/kit.js +224 -0
- package/dist/render.js +10 -3
- package/dist/sheet/formula.js +475 -0
- package/dist/sheet/functions.js +463 -0
- package/dist/sheet/index.js +9 -0
- package/dist/sheet/model.js +695 -0
- package/dist/sheet/operations.js +384 -0
- package/dist/sheet/output.js +182 -0
- package/package.json +15 -3
package/dist/host/lib/rpc.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { ArtifactError } from './errors.js';
|
|
2
|
-
import { fieldsOf, optionalEdits, optionalInteger, optionalScope, optionalString, optionalType, requiredFormat, requiredInteger, requiredString, requiredType, } from './validate.js';
|
|
2
|
+
import { fieldsOf, designSelection, designSaveOptions, optionalEdits, optionalInteger, optionalScope, optionalString, optionalType, requiredFormat, requiredInteger, requiredString, requiredType, } from './validate.js';
|
|
3
3
|
/** Every endpoint the route serves. */
|
|
4
4
|
export const ENDPOINTS = [
|
|
5
5
|
'list',
|
|
@@ -15,10 +15,13 @@ export const ENDPOINTS = [
|
|
|
15
15
|
'saveDesignSystem',
|
|
16
16
|
'clearDesignSystem',
|
|
17
17
|
'preview',
|
|
18
|
+
'designSystems',
|
|
19
|
+
'setDesignDefault',
|
|
20
|
+
'rebase',
|
|
18
21
|
];
|
|
19
22
|
/**
|
|
20
|
-
* The scope context of a request. A library request may carry a workspace id
|
|
21
|
-
*
|
|
23
|
+
* The scope context of a request. A library request may carry a workspace id
|
|
24
|
+
* from an older client; library reads ignore that id when resolving styles.
|
|
22
25
|
* @param fields the request.
|
|
23
26
|
* @returns the target.
|
|
24
27
|
*/
|
|
@@ -45,6 +48,7 @@ async function dispatch(service, endpoint, fields) {
|
|
|
45
48
|
return service.list(target, {
|
|
46
49
|
query: optionalString(fields, 'query'),
|
|
47
50
|
type: optionalType(fields),
|
|
51
|
+
recipe: optionalString(fields, 'recipe'),
|
|
48
52
|
offset: optionalInteger(fields, 'offset'),
|
|
49
53
|
limit: optionalInteger(fields, 'limit'),
|
|
50
54
|
});
|
|
@@ -56,6 +60,8 @@ async function dispatch(service, endpoint, fields) {
|
|
|
56
60
|
type: requiredType(fields),
|
|
57
61
|
title: requiredString(fields, 'title'),
|
|
58
62
|
content: optionalString(fields, 'content') ?? '',
|
|
63
|
+
recipe: optionalString(fields, 'recipe'),
|
|
64
|
+
design: designSelection(fields),
|
|
59
65
|
source: { ...user, action: 'create' },
|
|
60
66
|
}),
|
|
61
67
|
};
|
|
@@ -66,6 +72,7 @@ async function dispatch(service, endpoint, fields) {
|
|
|
66
72
|
content: optionalString(fields, 'content'),
|
|
67
73
|
edits: optionalEdits(fields),
|
|
68
74
|
title: optionalString(fields, 'title'),
|
|
75
|
+
recipe: optionalString(fields, 'recipe'),
|
|
69
76
|
source: { ...user, action: 'update' },
|
|
70
77
|
}),
|
|
71
78
|
};
|
|
@@ -82,11 +89,19 @@ async function dispatch(service, endpoint, fields) {
|
|
|
82
89
|
case 'printable':
|
|
83
90
|
return service.printable(target, requiredString(fields, 'id'), optionalInteger(fields, 'version'));
|
|
84
91
|
case 'designSystem':
|
|
85
|
-
return service.designSystem(target);
|
|
92
|
+
return service.designSystem(target, designSelection(fields));
|
|
86
93
|
case 'saveDesignSystem':
|
|
87
|
-
return service.saveDesignSystem(target, fields.tokens);
|
|
94
|
+
return service.saveDesignSystem(target, fields.tokens, designSaveOptions(fields));
|
|
88
95
|
case 'clearDesignSystem':
|
|
89
96
|
return service.clearWorkspaceDesignSystem(target);
|
|
97
|
+
case 'designSystems':
|
|
98
|
+
return service.listDesignSystems(target);
|
|
99
|
+
case 'setDesignDefault':
|
|
100
|
+
return service.setDesignDefault(target, fields.systemId === null ? null : requiredString(fields, 'systemId'), requiredInteger(fields, 'expectedRevision'));
|
|
101
|
+
case 'rebase':
|
|
102
|
+
return { manifest: await service.rebase(target, requiredString(fields, 'id'), {
|
|
103
|
+
baseVersion: requiredInteger(fields, 'baseVersion'), design: designSelection(fields), recipe: optionalString(fields, 'recipe'), source: { ...user, action: 'rebase' },
|
|
104
|
+
}) };
|
|
90
105
|
case 'preview':
|
|
91
106
|
return service.preview(target, requiredString(fields, 'id'), optionalInteger(fields, 'version'));
|
|
92
107
|
default: {
|
package/dist/host/lib/service.js
CHANGED
|
@@ -1,14 +1,38 @@
|
|
|
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,
|
|
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
|
+
}
|
|
34
|
+
/** The largest .fig file an import reads, in bytes. */
|
|
35
|
+
const FIG_IMPORT_MAX_BYTES = 128 * 1024 * 1024;
|
|
12
36
|
/**
|
|
13
37
|
* One facade over the store, the scope roots, the design system, the design
|
|
14
38
|
* renderer, and export. The route and the tools both call it, so both scopes
|
|
@@ -65,18 +89,24 @@ export class ArtifactService {
|
|
|
65
89
|
* @returns the root, or undefined.
|
|
66
90
|
*/
|
|
67
91
|
async optionalWorkspaceRoot(target) {
|
|
68
|
-
if (target.workspaceId === undefined)
|
|
92
|
+
if (target.scope === 'library' || target.workspaceId === undefined)
|
|
69
93
|
return undefined;
|
|
70
|
-
|
|
71
|
-
return workspace === undefined ? undefined : workspaceRootExisting(this.config, workspace);
|
|
94
|
+
return workspaceRootExisting(this.config, requireWorkspace(this.registry, target.workspaceId));
|
|
72
95
|
}
|
|
73
96
|
/**
|
|
74
97
|
* Resolve the design system for a target.
|
|
75
98
|
* @param target the caller's context.
|
|
76
99
|
* @returns tokens, source, and CSS.
|
|
77
100
|
*/
|
|
78
|
-
async designSystem(target) {
|
|
79
|
-
return
|
|
101
|
+
async designSystem(target, selection = {}) {
|
|
102
|
+
return resolveSystem(await this.optionalWorkspaceRoot(target), await libraryRoot(this.config), selection);
|
|
103
|
+
}
|
|
104
|
+
async listDesignSystems(target) {
|
|
105
|
+
return listSystems(await this.root(target));
|
|
106
|
+
}
|
|
107
|
+
async setDesignDefault(target, systemId, expectedRevision) {
|
|
108
|
+
await setSystemDefault(await this.root(target), systemId, expectedRevision);
|
|
109
|
+
return this.designSystem(target);
|
|
80
110
|
}
|
|
81
111
|
/**
|
|
82
112
|
* Save tokens at one scope.
|
|
@@ -84,11 +114,17 @@ export class ArtifactService {
|
|
|
84
114
|
* @param tokens partial or full tokens.
|
|
85
115
|
* @returns the saved tokens and scope.
|
|
86
116
|
*/
|
|
87
|
-
async saveDesignSystem(target, tokens) {
|
|
117
|
+
async saveDesignSystem(target, tokens, options) {
|
|
88
118
|
const root = await this.root(target);
|
|
119
|
+
const base = await this.designSystem(target);
|
|
120
|
+
if (options !== undefined)
|
|
121
|
+
return { ...await saveSystem(root, base.tokens, tokens, options), scope: root.scope };
|
|
122
|
+
const catalog = await listSystems(root);
|
|
123
|
+
if (catalog.defaultId !== null) {
|
|
124
|
+
throw new ArtifactError('artifact/stale-catalog', 'A named default is selected. Read the catalog and supply systemId and expectedRevision.');
|
|
125
|
+
}
|
|
89
126
|
const saved = await saveDesignSystem(root, await libraryRoot(this.config), tokens);
|
|
90
|
-
|
|
91
|
-
return { ...resolved, scope: saved.scope };
|
|
127
|
+
return { ...await this.designSystem(target), scope: saved.scope };
|
|
92
128
|
}
|
|
93
129
|
/**
|
|
94
130
|
* Remove the workspace override.
|
|
@@ -96,9 +132,131 @@ export class ArtifactService {
|
|
|
96
132
|
* @returns the design system now in force.
|
|
97
133
|
*/
|
|
98
134
|
async clearWorkspaceDesignSystem(target) {
|
|
99
|
-
|
|
135
|
+
const root = await this.root({ ...target, scope: 'workspace' });
|
|
136
|
+
const catalog = await listSystems(root);
|
|
137
|
+
if (catalog.defaultId !== null)
|
|
138
|
+
await setSystemDefault(root, null, catalog.revision);
|
|
139
|
+
await clearWorkspaceDesignSystem(root);
|
|
100
140
|
return this.designSystem(target);
|
|
101
141
|
}
|
|
142
|
+
/**
|
|
143
|
+
* The guides in force for a target. Reading never creates a workspace store.
|
|
144
|
+
* @param target the caller's context.
|
|
145
|
+
* @returns the workspace and library guides.
|
|
146
|
+
*/
|
|
147
|
+
async guides(target) {
|
|
148
|
+
return {
|
|
149
|
+
workspace: await readGuide(await this.optionalWorkspaceRoot(target)),
|
|
150
|
+
library: await readGuide(await libraryRoot(this.config)),
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Change one scope's guide.
|
|
155
|
+
* @param target the caller's context; `scope` picks the guide.
|
|
156
|
+
* @param patch the change.
|
|
157
|
+
* @returns the saved guide and its scope.
|
|
158
|
+
*/
|
|
159
|
+
async saveGuide(target, patch) {
|
|
160
|
+
const root = await this.root(target);
|
|
161
|
+
return { scope: root.scope, guide: await saveGuide(root, patch) };
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Resolve a recipe id for an artifact type, or refuse it.
|
|
165
|
+
* @param target the caller's context.
|
|
166
|
+
* @param id the recipe id.
|
|
167
|
+
* @param type the artifact type.
|
|
168
|
+
* @returns the recipe.
|
|
169
|
+
*/
|
|
170
|
+
async recipe(target, id, type) {
|
|
171
|
+
const recipe = findRecipe(await this.guides(target), id);
|
|
172
|
+
if (recipe === undefined) {
|
|
173
|
+
throw new ArtifactError('artifact/unknown-recipe', `No recipe "${id}". Call artifact_brief without a recipe to list them.`, { recipe: id });
|
|
174
|
+
}
|
|
175
|
+
if (!recipe.types.includes(type)) {
|
|
176
|
+
throw new ArtifactError('artifact/unknown-recipe', `The ${id} recipe is for ${recipe.types.join(', ')}, not ${type}.`, { recipe: id, type });
|
|
177
|
+
}
|
|
178
|
+
return recipe;
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* The recipe a stored artifact follows, when it names one that still resolves.
|
|
182
|
+
* @param target the caller's context.
|
|
183
|
+
* @param manifest the artifact.
|
|
184
|
+
* @returns the recipe, or undefined.
|
|
185
|
+
*/
|
|
186
|
+
async recipeOf(target, manifest) {
|
|
187
|
+
if (manifest.generation !== undefined) {
|
|
188
|
+
const pinned = (await this.store.read(await this.root(target, manifest.id), manifest.id, manifest.version)).generation?.recipe;
|
|
189
|
+
return pinned ? { ...pinned, source: manifest.scope } : undefined;
|
|
190
|
+
}
|
|
191
|
+
if (manifest.recipe === undefined)
|
|
192
|
+
return undefined;
|
|
193
|
+
const recipe = findRecipe(await this.guides({ ...target, scope: manifest.scope }), manifest.recipe);
|
|
194
|
+
return recipe !== undefined && recipe.types.includes(manifest.type) ? recipe : undefined;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Assemble the brief for a new artifact.
|
|
198
|
+
* @param target the caller's context.
|
|
199
|
+
* @param type the artifact type.
|
|
200
|
+
* @param recipeId the recipe, when the caller chose one.
|
|
201
|
+
* @returns the brief and the recipe it used.
|
|
202
|
+
*/
|
|
203
|
+
async brief(target, type, recipeId, selection = {}) {
|
|
204
|
+
const layers = await this.guides(target);
|
|
205
|
+
if (type === 'sheet') {
|
|
206
|
+
if (recipeId !== undefined) {
|
|
207
|
+
throw new ArtifactError('artifact/unknown-recipe', 'Sheets do not use recipes.', { recipe: recipeId, type });
|
|
208
|
+
}
|
|
209
|
+
return { brief: composeSheetBrief(layers) };
|
|
210
|
+
}
|
|
211
|
+
const recipe = recipeId === undefined ? undefined : findRecipe(layers, recipeId);
|
|
212
|
+
if (recipeId !== undefined && (recipe === undefined || !recipe.types.includes(type))) {
|
|
213
|
+
throw new ArtifactError('artifact/unknown-recipe', 'No compatible recipe for this artifact type.', { recipe: recipeId, type });
|
|
214
|
+
}
|
|
215
|
+
const design = await this.designSystem(target, selection);
|
|
216
|
+
const root = target.scope === 'library' ? await libraryRoot(this.config) : await this.optionalWorkspaceRoot(target);
|
|
217
|
+
const siblings = recipe === undefined || root === undefined
|
|
218
|
+
? []
|
|
219
|
+
: (await this.store.list(root, { type, recipe: recipe.id, limit: 3 })).items;
|
|
220
|
+
const brief = composeBrief({ type, recipe, layers, tokens: design.tokens, tokenSource: design.source, siblings });
|
|
221
|
+
return recipe === undefined ? { brief } : { brief, recipe };
|
|
222
|
+
}
|
|
223
|
+
async freeze(target, type, content, recipeId, selection = {}) {
|
|
224
|
+
const design = await this.designSystem(target, selection);
|
|
225
|
+
const recipe = recipeId === undefined ? null : await this.recipe(target, recipeId, type);
|
|
226
|
+
const kit = type === 'page' ? declaredKit(content) ?? null : null;
|
|
227
|
+
if (kit !== null && !getKit(kit))
|
|
228
|
+
throw new ArtifactError('artifact/unsupported-kit', 'The selected kit release is not installed.');
|
|
229
|
+
return { schemaVersion: 1, tokens: design.tokens, system: design.system ?? null, tokenSource: design.source,
|
|
230
|
+
recipe, kit, conventionsHash: generationHash(JSON.stringify(await this.guides(target))) };
|
|
231
|
+
}
|
|
232
|
+
async versionDesign(target, result) {
|
|
233
|
+
const generation = result.generation;
|
|
234
|
+
if (!generation)
|
|
235
|
+
return this.designSystem({ ...target, scope: result.manifest.scope });
|
|
236
|
+
if (generation.kit !== null && !getKit(generation.kit))
|
|
237
|
+
throw new ArtifactError('artifact/unsupported-kit', 'The saved kit release is not installed.');
|
|
238
|
+
return { tokens: generation.tokens, css: tokensToCss(generation.tokens), source: generation.tokenSource,
|
|
239
|
+
...(generation.system ? { system: generation.system } : {}) };
|
|
240
|
+
}
|
|
241
|
+
async rebase(target, id, input) {
|
|
242
|
+
const root = await this.root(target, id);
|
|
243
|
+
const current = await this.store.read(root, id);
|
|
244
|
+
if (current.manifest.type === 'design')
|
|
245
|
+
throw new ArtifactError('artifact/unsupported-type', 'Mockup source must be restyled explicitly.');
|
|
246
|
+
if (current.manifest.type === 'sheet')
|
|
247
|
+
throw new ArtifactError('artifact/unsupported-type', 'A sheet has no design or recipe to rebase.', { type: current.manifest.type });
|
|
248
|
+
const recipe = input.recipe ?? current.manifest.recipe;
|
|
249
|
+
const generation = input.recipe === undefined && input.design === undefined
|
|
250
|
+
? await this.freeze({ ...target, scope: root.scope }, current.manifest.type, current.content, recipe)
|
|
251
|
+
:
|
|
252
|
+
input.design
|
|
253
|
+
? await this.freeze({ ...target, scope: root.scope }, current.manifest.type, current.content, recipe, input.design)
|
|
254
|
+
: (current.generation ?? await this.freeze({ ...target, scope: root.scope }, current.manifest.type, current.content, recipe));
|
|
255
|
+
if (input.recipe !== undefined && generation.recipe?.id !== input.recipe) {
|
|
256
|
+
generation.recipe = await this.recipe({ ...target, scope: root.scope }, input.recipe, current.manifest.type);
|
|
257
|
+
}
|
|
258
|
+
return this.store.update(root, id, { baseVersion: input.baseVersion, recipe, generation, source: { ...input.source, action: 'rebase' } });
|
|
259
|
+
}
|
|
102
260
|
/**
|
|
103
261
|
* Create an artifact. A design is compiled before anything is written, so an
|
|
104
262
|
* invalid source never creates a directory or a version.
|
|
@@ -107,11 +265,20 @@ export class ArtifactService {
|
|
|
107
265
|
* @returns the manifest.
|
|
108
266
|
*/
|
|
109
267
|
async create(target, input) {
|
|
268
|
+
if (input.type === 'sheet' && input.recipe !== undefined) {
|
|
269
|
+
throw new ArtifactError('artifact/bad-request', 'Sheets do not use recipes.', { recipe: input.recipe, type: input.type });
|
|
270
|
+
}
|
|
271
|
+
if (input.recipe !== undefined)
|
|
272
|
+
await this.recipe(target, input.recipe, input.type);
|
|
110
273
|
const root = await this.root(target);
|
|
111
|
-
const
|
|
112
|
-
const
|
|
274
|
+
const content = input.type === 'sheet' ? canonicalSheet(input.content) : input.content;
|
|
275
|
+
const info = input.type === 'design' ? await this.designs.inspect(content) : undefined;
|
|
276
|
+
const generation = input.type === 'design' || input.type === 'sheet'
|
|
277
|
+
? undefined
|
|
278
|
+
: await this.freeze({ ...target, scope: root.scope }, input.type, content, input.recipe, input.design);
|
|
279
|
+
const manifest = await this.store.create(root, { ...input, content, generation });
|
|
113
280
|
if (info !== undefined)
|
|
114
|
-
await this.writeInfo(root, manifest.id,
|
|
281
|
+
await this.writeInfo(root, manifest.id, content, info);
|
|
115
282
|
return manifest;
|
|
116
283
|
}
|
|
117
284
|
/**
|
|
@@ -125,9 +292,10 @@ export class ArtifactService {
|
|
|
125
292
|
async read(target, id, version) {
|
|
126
293
|
const root = await this.root(target, id);
|
|
127
294
|
const result = await this.store.read(root, id, version);
|
|
128
|
-
const design = await this.
|
|
295
|
+
const design = await this.versionDesign(target, result);
|
|
129
296
|
const payload = {
|
|
130
|
-
|
|
297
|
+
manifest: result.manifest, content: result.content, version: result.version,
|
|
298
|
+
...(result.generation ? { generation: generationSummary(result.generation) } : {}),
|
|
131
299
|
designCss: design.css,
|
|
132
300
|
design: design.tokens,
|
|
133
301
|
};
|
|
@@ -150,9 +318,30 @@ export class ArtifactService {
|
|
|
150
318
|
async update(target, id, input) {
|
|
151
319
|
const root = await this.root(target, id);
|
|
152
320
|
const current = await this.store.manifest(root, id);
|
|
153
|
-
if (current.type !== 'design')
|
|
154
|
-
return this.store.update(root, id, input);
|
|
155
321
|
const existing = await this.store.read(root, id);
|
|
322
|
+
if (current.type === 'sheet') {
|
|
323
|
+
if (input.recipe !== undefined) {
|
|
324
|
+
throw new ArtifactError('artifact/bad-request', 'Sheets do not use recipes.', { type: current.type });
|
|
325
|
+
}
|
|
326
|
+
if (input.content !== undefined && input.edits !== undefined) {
|
|
327
|
+
throw new ArtifactError('artifact/bad-request', 'Send either content or edits, not both.');
|
|
328
|
+
}
|
|
329
|
+
let next = input.content;
|
|
330
|
+
if (next === undefined && input.edits !== undefined)
|
|
331
|
+
next = applyEdits(existing.content, input.edits);
|
|
332
|
+
if (next !== undefined)
|
|
333
|
+
next = canonicalSheet(next);
|
|
334
|
+
return this.store.update(root, id, { ...input, content: next, edits: undefined });
|
|
335
|
+
}
|
|
336
|
+
if (current.type !== 'design') {
|
|
337
|
+
let generation = existing.generation ?? await this.freeze({ ...target, scope: root.scope }, current.type, existing.content, input.recipe ?? current.recipe);
|
|
338
|
+
if (input.recipe !== undefined && input.recipe !== generation.recipe?.id) {
|
|
339
|
+
generation = { ...generation, recipe: await this.recipe({ ...target, scope: root.scope }, input.recipe, current.type) };
|
|
340
|
+
}
|
|
341
|
+
return this.store.update(root, id, { ...input, generation });
|
|
342
|
+
}
|
|
343
|
+
if (input.recipe !== undefined)
|
|
344
|
+
await this.recipe({ ...target, scope: root.scope }, input.recipe, current.type);
|
|
156
345
|
let next = input.content;
|
|
157
346
|
if (next === undefined && input.edits !== undefined)
|
|
158
347
|
next = applyEdits(existing.content, input.edits);
|
|
@@ -163,6 +352,30 @@ export class ArtifactService {
|
|
|
163
352
|
await this.writeInfo(root, id, next, info);
|
|
164
353
|
return manifest;
|
|
165
354
|
}
|
|
355
|
+
/**
|
|
356
|
+
* Import a .fig file as a new design. The file's first page with elements
|
|
357
|
+
* becomes the stored mockup; later pages are named in warnings. The host
|
|
358
|
+
* reads the file, and the renderer child never touches the filesystem.
|
|
359
|
+
* @param target the caller's context.
|
|
360
|
+
* @param input the path, optional title, and write source.
|
|
361
|
+
* @returns the new manifest.
|
|
362
|
+
*/
|
|
363
|
+
async importDesign(target, input) {
|
|
364
|
+
let bytes;
|
|
365
|
+
try {
|
|
366
|
+
bytes = await fs.readFile(input.path);
|
|
367
|
+
}
|
|
368
|
+
catch (error) {
|
|
369
|
+
throw new ArtifactError('artifact/bad-request', `The .fig file was not readable: ${error instanceof Error ? error.message : String(error)}`, { path: input.path });
|
|
370
|
+
}
|
|
371
|
+
if (bytes.byteLength > FIG_IMPORT_MAX_BYTES) {
|
|
372
|
+
throw new ArtifactError('artifact/bad-request', 'The .fig file is too large; imports accept up to 128 MB.', { path: input.path });
|
|
373
|
+
}
|
|
374
|
+
const imported = await this.designs.importFig(bytes);
|
|
375
|
+
const name = path.basename(input.path).replace(/\.(fig|pen)$/i, '');
|
|
376
|
+
const title = input.title ?? (name === '' ? 'Imported design' : name);
|
|
377
|
+
return this.create(target, { type: 'design', title, content: imported.source, source: input.source });
|
|
378
|
+
}
|
|
166
379
|
/**
|
|
167
380
|
* Restore an earlier version.
|
|
168
381
|
* @param target the caller's context.
|
|
@@ -173,7 +386,11 @@ export class ArtifactService {
|
|
|
173
386
|
* @returns the new manifest.
|
|
174
387
|
*/
|
|
175
388
|
async restore(target, id, version, source, baseVersion) {
|
|
176
|
-
|
|
389
|
+
const root = await this.root(target, id);
|
|
390
|
+
const old = await this.store.read(root, id, version);
|
|
391
|
+
const generation = old.manifest.type === 'design' || old.manifest.type === 'sheet' || old.generation ? undefined
|
|
392
|
+
: await this.freeze({ ...target, scope: root.scope }, old.manifest.type, old.content, old.manifest.recipe);
|
|
393
|
+
return this.store.restore(root, id, version, source, baseVersion, generation);
|
|
177
394
|
}
|
|
178
395
|
async history(target, id) {
|
|
179
396
|
return this.store.history(await this.root(target, id), id);
|
|
@@ -191,11 +408,22 @@ export class ArtifactService {
|
|
|
191
408
|
* @returns printable HTML.
|
|
192
409
|
*/
|
|
193
410
|
async printable(target, id, version) {
|
|
194
|
-
const
|
|
411
|
+
const result = await this.store.read(await this.root(target, id), id, version);
|
|
412
|
+
const { manifest, content } = result;
|
|
195
413
|
if (manifest.type === 'design') {
|
|
196
414
|
throw new ArtifactError('artifact/unsupported-format', 'A design cannot be printed.', { type: manifest.type });
|
|
197
415
|
}
|
|
198
|
-
const design = await this.
|
|
416
|
+
const design = await this.versionDesign(target, result);
|
|
417
|
+
if (manifest.type === 'sheet') {
|
|
418
|
+
let workbook;
|
|
419
|
+
try {
|
|
420
|
+
workbook = parseSheetWorkbook(content);
|
|
421
|
+
}
|
|
422
|
+
catch {
|
|
423
|
+
throw new ArtifactError('artifact/corrupt', 'The saved sheet content cannot be read.', { id: manifest.id });
|
|
424
|
+
}
|
|
425
|
+
return { html: sheetToPrintableHtml(workbook, design.css, manifest.title) };
|
|
426
|
+
}
|
|
199
427
|
return { html: manifest.type === 'page'
|
|
200
428
|
? composePage(content, design.css, PAGE_CSP, manifest.title)
|
|
201
429
|
: docToHtml(manifest.title, content, design.css, true) };
|
|
@@ -211,8 +439,9 @@ export class ArtifactService {
|
|
|
211
439
|
*/
|
|
212
440
|
async export(target, id, format, version) {
|
|
213
441
|
const root = await this.root(target, id);
|
|
214
|
-
const
|
|
215
|
-
const
|
|
442
|
+
const result = await this.store.read(root, id, version);
|
|
443
|
+
const { manifest, content, version: readVersion } = result;
|
|
444
|
+
const design = await this.versionDesign(target, result);
|
|
216
445
|
return writeExport(root, { ...manifest, version: readVersion }, content, format, design, this.now(), this.designs);
|
|
217
446
|
}
|
|
218
447
|
/**
|
package/dist/host/lib/skill.js
CHANGED
|
@@ -5,15 +5,28 @@ const CONTENT = String.raw `# Artifact design
|
|
|
5
5
|
|
|
6
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.
|
|
7
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
|
+
|
|
8
18
|
## When to use an artifact
|
|
9
19
|
|
|
10
|
-
Use \`artifact_create\` when the user asks for an artifact, an artifact page, an artifact doc,
|
|
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.
|
|
11
21
|
|
|
12
22
|
## Precedence
|
|
13
23
|
|
|
14
|
-
1.
|
|
15
|
-
2.
|
|
16
|
-
3.
|
|
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.
|
|
17
30
|
|
|
18
31
|
## Projects and scopes
|
|
19
32
|
|
|
@@ -24,6 +37,7 @@ An artifact belongs to the session's project unless the user opened or reference
|
|
|
24
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.
|
|
25
38
|
- \`page\` for anything visual or interactive: dashboards, one-pagers, explainers, calculators, diagrams, and clickable prototypes the user asks for as a page.
|
|
26
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.
|
|
27
41
|
|
|
28
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.
|
|
29
43
|
|
|
@@ -31,24 +45,35 @@ A request for a mockup or a wireframe always gets \`design\`, even when it shows
|
|
|
31
45
|
|
|
32
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.
|
|
33
47
|
|
|
34
|
-
Choose the structure by the task, not by a favorite template:
|
|
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:
|
|
35
49
|
|
|
36
|
-
- Architecture walkthrough: show boundaries, dependencies, and one request or data flow.
|
|
37
|
-
- Feature walkthrough: name the actor and starting conditions, show the actions and alternate paths, and state the resulting behavior.
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
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.
|
|
42
57
|
|
|
43
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.
|
|
44
59
|
|
|
45
60
|
## Use one design system
|
|
46
61
|
|
|
47
|
-
|
|
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.
|
|
48
71
|
|
|
49
|
-
|
|
72
|
+
## The page kit
|
|
50
73
|
|
|
51
|
-
|
|
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.
|
|
52
77
|
|
|
53
78
|
## Designs (OpenPencil Design JSX)
|
|
54
79
|
|
|
@@ -94,9 +119,9 @@ The host injects these on \`:root\` before your markup:
|
|
|
94
119
|
- Fonts: \`--artifact-font-family\` for body text, \`--artifact-font-display\` for headings, \`--artifact-font-mono\` for code and data.
|
|
95
120
|
- Sizes: \`--artifact-font-size-0\` to \`-6\`, \`--artifact-space-0\` to \`-6\`, \`--artifact-radius-sm\`, \`-md\`, \`-lg\`.
|
|
96
121
|
|
|
97
|
-
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()\`.
|
|
98
123
|
|
|
99
|
-
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. 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.
|
|
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.
|
|
100
125
|
|
|
101
126
|
## Layout and type
|
|
102
127
|
|
|
@@ -110,6 +135,22 @@ Dark mode is opt in. Add \`<meta name="color-scheme" content="light dark">\` and
|
|
|
110
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.
|
|
111
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.
|
|
112
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. When you set a fill, also set a text color that contrasts with it: use #1f2933 on light fills and #ffffff on dark fills. The panel and exports choose a readable default when color is omitted, and a low-contrast pair returns a warning. 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.
|
|
153
|
+
|
|
113
154
|
## Documents
|
|
114
155
|
|
|
115
156
|
- Lead with the answer or the decision, then the detail.
|
|
@@ -143,8 +184,8 @@ Tell the user in one or two sentences what you made or changed. Do not repeat th
|
|
|
143
184
|
/** The artifact design skill, registered by the \`dsh-artifact-studio/skill\` host plugin. */
|
|
144
185
|
export const ARTIFACT_DESIGN_SKILL = {
|
|
145
186
|
name: 'artifact-design',
|
|
146
|
-
description: 'Author artifact pages, documents, and
|
|
147
|
-
whenToUse: 'Load before artifact_create, when the user asks for an artifact,
|
|
187
|
+
description: 'Author artifact pages, documents, spreadsheets, and mockups: pick a recipe, follow the brief, build from the kit, edit cells, save 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.',
|
|
148
189
|
source: 'bundled',
|
|
149
190
|
content: CONTENT,
|
|
150
191
|
};
|