dsh-artifact-studio 0.7.3 → 0.8.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/dist/contract.js CHANGED
@@ -25,7 +25,10 @@ export const CONTENT_FILE = {
25
25
  export const ID_PATTERN = /^art_(ws|lib)_[a-z0-9]{10,32}$/;
26
26
  export const MAX_TITLE = 120;
27
27
  export const MAX_LIST_LIMIT = 50;
28
- export const COLOR_ROLES = ['primary', 'accent', 'surface', 'text', 'muted'];
28
+ export const COLOR_ROLES = [
29
+ 'primary', 'accent', 'surface', 'text', 'muted', 'background', 'raised',
30
+ 'border', 'control', 'action', 'actionText', 'focus', 'success', 'warning', 'danger',
31
+ ];
29
32
  /**
30
33
  * Narrow a design summary read from the wire or a cache file.
31
34
  * @param value the value.
@@ -138,8 +141,18 @@ export function scopeOfId(id) {
138
141
  export const DEFAULT_TOKENS = {
139
142
  schemaVersion: 1,
140
143
  name: 'Default',
141
- colors: { primary: '#2856c7', accent: '#0f8a72', surface: '#ffffff', text: '#16181d', muted: '#5b6170' },
142
- colorsDark: { primary: '#86a8ff', accent: '#45c9a8', surface: '#15171b', text: '#e8e9ec', muted: '#a0a6b2' },
144
+ colors: {
145
+ primary: '#8c3e25', accent: '#b85c3b', surface: '#fffdf8', text: '#211f1b', muted: '#6c655b',
146
+ background: '#f3efe7', raised: '#ebe4d7', border: '#d8cfbf', control: '#8a7c68',
147
+ action: '#8c3e25', actionText: '#fffdf8', focus: '#2f5f7a',
148
+ success: '#2f6b4f', warning: '#855714', danger: '#923b3b',
149
+ },
150
+ colorsDark: {
151
+ primary: '#f0a888', accent: '#e08a66', surface: '#201c17', text: '#f3eee5', muted: '#b9b0a2',
152
+ background: '#171411', raised: '#29241d', border: '#3b342b', control: '#8f806c',
153
+ action: '#e08a66', actionText: '#171411', focus: '#8fc7e0',
154
+ success: '#8fc9a7', warning: '#e0b66f', danger: '#e59a9a',
155
+ },
143
156
  typography: {
144
157
  fontFamily: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
145
158
  displayFamily: 'ui-serif, "Iowan Old Style", Charter, Georgia, serif',
@@ -150,6 +163,10 @@ export const DEFAULT_TOKENS = {
150
163
  radius: { sm: 4, md: 8, lg: 12 },
151
164
  notes: '',
152
165
  };
166
+ /** Map JSON role names to the CSS naming convention. */
167
+ function colorProperty(role) {
168
+ return `--artifact-color-` + role.replace(/[A-Z]/g, (letter) => '-' + letter.toLowerCase());
169
+ }
153
170
  /**
154
171
  * Turn tokens into CSS custom properties on `:root`.
155
172
  * @param tokens the design tokens.
@@ -158,7 +175,7 @@ export const DEFAULT_TOKENS = {
158
175
  export function tokensToCss(tokens) {
159
176
  const lines = [];
160
177
  for (const role of COLOR_ROLES)
161
- lines.push(`--artifact-color-${role}: ${tokens.colors[role]};`);
178
+ lines.push(`${colorProperty(role)}: ${tokens.colors[role]};`);
162
179
  lines.push(`--artifact-font-family: ${tokens.typography.fontFamily};`);
163
180
  lines.push(`--artifact-font-display: ${tokens.typography.displayFamily};`);
164
181
  lines.push(`--artifact-font-mono: ${tokens.typography.monoFamily};`);
@@ -167,7 +184,7 @@ export function tokensToCss(tokens) {
167
184
  tokens.spacing.scale.forEach((size, index) => lines.push(`--artifact-space-${index}: ${size}px;`));
168
185
  for (const [key, value] of Object.entries(tokens.radius))
169
186
  lines.push(`--artifact-radius-${key}: ${value}px;`);
170
- const dark = COLOR_ROLES.map((role) => `--artifact-color-${role}: ${tokens.colorsDark[role]};`).join('\n ');
187
+ const dark = COLOR_ROLES.map((role) => `${colorProperty(role)}: ${tokens.colorsDark[role]};`).join('\n ');
171
188
  return [
172
189
  `:root {\n ${lines.join('\n ')}\n}`,
173
190
  `:root[${THEME_ATTRIBUTE}="dark"] {\n color-scheme: dark;\n ${dark}\n}`,
@@ -189,7 +206,7 @@ export function tokenVariables(tokens, dark) {
189
206
  '--artifact-font-mono': tokens.typography.monoFamily,
190
207
  };
191
208
  for (const role of COLOR_ROLES)
192
- vars[`--artifact-color-${role}`] = colors[role];
209
+ vars[colorProperty(role)] = colors[role];
193
210
  tokens.typography.scale.forEach((size, index) => { vars[`--artifact-font-size-${index}`] = `${size}px`; });
194
211
  tokens.spacing.scale.forEach((size, index) => { vars[`--artifact-space-${index}`] = `${size}px`; });
195
212
  for (const [key, value] of Object.entries(tokens.radius))
@@ -123,7 +123,28 @@ async function readScopeTokens(root) {
123
123
  if (!(await assertPlainFile(file)))
124
124
  return undefined;
125
125
  try {
126
- return mergeTokens(DEFAULT_TOKENS, JSON.parse(await fs.readFile(file, 'utf8')));
126
+ const stored = JSON.parse(await fs.readFile(file, 'utf8'));
127
+ if (!isObject(stored))
128
+ return undefined;
129
+ const upgraded = { ...stored };
130
+ for (const set of ['colors', 'colorsDark']) {
131
+ const defaults = DEFAULT_TOKENS[set];
132
+ const colors = stored[set];
133
+ if (!isObject(colors))
134
+ continue;
135
+ // Legacy brands must not inherit rust actions or warm backgrounds from the new default.
136
+ upgraded[set] = {
137
+ background: colors.surface ?? defaults.surface,
138
+ raised: colors.surface ?? defaults.surface,
139
+ border: colors.muted ?? defaults.muted,
140
+ control: colors.muted ?? defaults.muted,
141
+ action: colors.primary ?? defaults.primary,
142
+ actionText: colors.surface ?? defaults.surface,
143
+ focus: colors.primary ?? defaults.primary,
144
+ ...colors,
145
+ };
146
+ }
147
+ return mergeTokens(DEFAULT_TOKENS, upgraded);
127
148
  }
128
149
  catch (error) {
129
150
  if (error instanceof SyntaxError || error instanceof ArtifactError)
@@ -1,4 +1,6 @@
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.
@@ -10,9 +12,13 @@ Use \`artifact_create\` when the user asks for an artifact, an artifact page, an
10
12
  ## Precedence
11
13
 
12
14
  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.
15
+ 2. The design system comes next. Read it with \`design_system_read\` before styling a page, and use its \`--artifact-*\` variables.
14
16
  3. Your own choices come last, and only fill the gaps.
15
17
 
18
+ ## Projects and scopes
19
+
20
+ 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.
21
+
16
22
  ## Pick the type
17
23
 
18
24
  - \`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.
@@ -21,6 +27,29 @@ Use \`artifact_create\` when the user asks for an artifact, an artifact page, an
21
27
 
22
28
  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
29
 
30
+ ## Choose the reader's task
31
+
32
+ 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
+
34
+ Choose the structure by the task, not by a favorite template:
35
+
36
+ - Architecture walkthrough: show boundaries, dependencies, and one request or data flow. Label connections and provide a textual flow beside the diagram.
37
+ - Feature walkthrough: name the actor and starting conditions, show the actions and alternate paths, and state the resulting behavior.
38
+ - 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\`.
39
+ - Technical decision: state the recommendation, compare options with evidence and tradeoffs, and name what would change the decision.
40
+ - Investigation report: separate observations, evidence, hypotheses, and unresolved checks. Do not present a hypothesis as a confirmed cause.
41
+ - Metrics 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
+
43
+ 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
+
45
+ ## Use one design system
46
+
47
+ Inspect the project's design language before choosing styles: design docs, CSS custom properties, theme configuration, and existing components. The user's explicit visual brief still wins. If the project has a system, use its palette, type, spacing, radii, and motion together. Do not copy the Artifact Studio editor's controls into the artifact.
48
+
49
+ Use resolved scope tokens when they match the project. For a requested page in a different project 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.
50
+
51
+ For a page, read the packaged HTML reference with the file-read tool: \`${PAGE_REFERENCE}\`. It shows headers, sections, native buttons and fields, a table, status badges, and a callout. Read only the relevant sections. It uses injected tokens and is intended to render through the artifact renderer; opening the bare file alone does not supply tokens. Reuse the relevant structure and CSS inline, not the specimen copy, the complete page layout, or its theme inspection controls by default. Do not add a framework, CDN, build system, or local server for a self-contained page.
52
+
24
53
  ## Designs (OpenPencil Design JSX)
25
54
 
26
55
  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 +88,15 @@ A page renders in an opaque-origin iframe with every network request blocked.
59
88
 
60
89
  The host injects these on \`:root\` before your markup:
61
90
 
62
- - Colors: \`--artifact-color-primary\`, \`-accent\`, \`-surface\`, \`-text\`, \`-muted\`.
91
+ - 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.
92
+ - \`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.
93
+ - 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
94
  - Fonts: \`--artifact-font-family\` for body text, \`--artifact-font-display\` for headings, \`--artifact-font-mono\` for code and data.
64
95
  - Sizes: \`--artifact-font-size-0\` to \`-6\`, \`--artifact-space-0\` to \`-6\`, \`--artifact-radius-sm\`, \`-md\`, \`-lg\`.
65
96
 
66
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.
67
98
 
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.
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.
69
100
 
70
101
  ## Layout and type
71
102
 
@@ -75,7 +106,9 @@ Dark mode is opt in. Add \`<meta name="color-scheme" content="light dark">\` and
75
106
  - 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
107
  - Use one motion moment at most, and respect \`prefers-reduced-motion\`.
77
108
  - 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.
109
+ - 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.
110
+ - 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
+ - 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.
79
112
 
80
113
  ## Documents
81
114
 
@@ -88,7 +121,9 @@ Dark mode is opt in. Add \`<meta name="color-scheme" content="light dark">\` and
88
121
  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
122
 
90
123
  - 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.
124
+ - 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.
125
+ - 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.
126
+ - 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
127
  - If a check after saving finds problems, fix all of them in one \`artifact_update\`. Never send one update per finding.
93
128
  - 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
129
 
@@ -108,7 +143,7 @@ Tell the user in one or two sentences what you made or changed. Do not repeat th
108
143
  /** The artifact design skill, registered by the \`dsh-artifact-studio/skill\` host plugin. */
109
144
  export const ARTIFACT_DESIGN_SKILL = {
110
145
  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.',
146
+ description: 'Author artifact pages, documents, and OpenPencil mockups with project-first design, task-specific structure, semantic tokens, a packaged HTML reference, sandbox rules, accessibility, bounded verification, and version-safe revisions.',
112
147
  whenToUse: 'Load before artifact_create, when the user asks for an artifact, and before an artifact_update that changes layout or styling.',
113
148
  source: 'bundled',
114
149
  content: CONTENT,
@@ -1,16 +1,20 @@
1
1
  import { checkPage } from './checks.js';
2
2
  import { ArtifactError } from './errors.js';
3
- import { workspaceForSession } from './paths.js';
3
+ import { requireWorkspace, workspaceForSession } from './paths.js';
4
4
  import { fieldsOf, optionalEdits, optionalInteger, optionalScope, optionalString, optionalType, requiredFormat, requiredInteger, requiredString, requiredType, } from './validate.js';
5
5
  const SCOPE_PARAM = {
6
6
  type: 'string',
7
7
  enum: ['workspace', 'library'],
8
8
  description: 'workspace (default) stores it under the Harness home for this workspace. library stores it in the user profile, shared by every project; use it only when the user asks for something reusable across projects.',
9
9
  };
10
+ const WORKSPACE_PARAM = {
11
+ type: 'string',
12
+ description: "Another registered project's workspace id, from an artifact reference. Omit for this session's project.",
13
+ };
10
14
  const PAGE_GUIDE = [
11
15
  'Load the artifact-design skill first if not loaded yet. Precedence: the user\'s request, then the design system, then your own choices.',
12
16
  'A page is one self-contained HTML document in a sandbox with no network or browser storage: inline all CSS and JavaScript, draw charts with inline SVG or canvas, and use data: URIs for images. Keep the layout fluid for a 380 to 700 px panel.',
13
- 'Style pages with the injected variables: --artifact-color-primary, -accent, -surface, -text, -muted; --artifact-font-family, -display, -mono; and the size, space, and radius scales in the skill.',
17
+ 'Use injected --artifact-* color, font, size, space, and radius variables. The skill covers semantic roles and the packaged page reference.',
14
18
  'A doc is Markdown: headings, lists, task lists, tables, quotes, and fenced code.',
15
19
  'Each save is a version the user sees. Check before saving and batch fixes into one update.',
16
20
  ].join('\n');
@@ -40,13 +44,22 @@ function warningsFor(type, content) {
40
44
  return type === 'page' && content !== undefined ? checkPage(content) : [];
41
45
  }
42
46
  /**
43
- * The scope context of a call: the session's workspace, plus an explicit scope.
47
+ * The scope context of a call: the session's workspace, or an explicitly named
48
+ * registered workspace, plus an explicit scope.
44
49
  * @param host the tool host.
45
50
  * @param exec the execution.
46
51
  * @param scope an explicit scope.
52
+ * @param workspaceId another registered workspace, when the call names one.
47
53
  * @returns the target.
48
54
  */
49
- async function targetFor(host, exec, scope) {
55
+ async function targetFor(host, exec, scope, workspaceId) {
56
+ if (workspaceId !== undefined) {
57
+ requireWorkspace(host.registry, workspaceId);
58
+ if (scope === 'library') {
59
+ throw new ArtifactError('artifact/bad-request', '"workspaceId" applies only to workspace artifacts.', { workspaceId });
60
+ }
61
+ return { workspaceId, scope: 'workspace' };
62
+ }
50
63
  if (exec.agent === undefined) {
51
64
  if (scope === 'library')
52
65
  return { scope };
@@ -171,6 +184,7 @@ export function createTools(host) {
171
184
  title: { type: 'string', description: 'Short title, 1 to 120 characters.' },
172
185
  content: { type: 'string', description: 'The full HTML document, Markdown text, or Design JSX source, up to 2 MiB.' },
173
186
  scope: SCOPE_PARAM,
187
+ workspaceId: WORKSPACE_PARAM,
174
188
  },
175
189
  },
176
190
  output: {
@@ -180,7 +194,7 @@ export function createTools(host) {
180
194
  },
181
195
  async execute(args, exec) {
182
196
  const fields = fieldsOf(args);
183
- const target = await targetFor(host, exec, optionalScope(fields));
197
+ const target = await targetFor(host, exec, optionalScope(fields), optionalString(fields, 'workspaceId'));
184
198
  const type = requiredType(fields);
185
199
  const content = optionalString(fields, 'content') ?? '';
186
200
  const manifest = await service.create(target, {
@@ -197,7 +211,7 @@ export function createTools(host) {
197
211
  };
198
212
  const read = {
199
213
  name: 'artifact_read',
200
- description: 'Read an artifact\'s current content and version, or an earlier version. Read before updating an artifact the user may have edited.',
214
+ description: 'Read an artifact\'s current content and version, or an earlier version. Read before updating an artifact the user may have edited. Pass workspaceId for an artifact in another project.',
201
215
  parameters: {
202
216
  type: 'object',
203
217
  additionalProperties: false,
@@ -205,6 +219,7 @@ export function createTools(host) {
205
219
  properties: {
206
220
  id: { type: 'string', description: 'Artifact id from artifact_create or artifact_list.' },
207
221
  version: { type: 'integer', description: 'An earlier version to read. Omit for the current one.' },
222
+ workspaceId: WORKSPACE_PARAM,
208
223
  },
209
224
  },
210
225
  output: {
@@ -241,7 +256,7 @@ export function createTools(host) {
241
256
  async execute(args, exec) {
242
257
  const fields = fieldsOf(args);
243
258
  const id = requiredString(fields, 'id');
244
- const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined);
259
+ const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined, optionalString(fields, 'workspaceId'));
245
260
  const result = await service.read(target, id, optionalInteger(fields, 'version'));
246
261
  const info = result.designInfo;
247
262
  return {
@@ -282,6 +297,7 @@ export function createTools(host) {
282
297
  },
283
298
  },
284
299
  title: { type: 'string', description: 'A new title.' },
300
+ workspaceId: WORKSPACE_PARAM,
285
301
  },
286
302
  },
287
303
  output: {
@@ -292,7 +308,7 @@ export function createTools(host) {
292
308
  async execute(args, exec) {
293
309
  const fields = fieldsOf(args);
294
310
  const id = requiredString(fields, 'id');
295
- const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined);
311
+ const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined, optionalString(fields, 'workspaceId'));
296
312
  const content = optionalString(fields, 'content');
297
313
  const edits = optionalEdits(fields);
298
314
  const title = optionalString(fields, 'title');
@@ -314,12 +330,13 @@ export function createTools(host) {
314
330
  };
315
331
  const list = {
316
332
  name: 'artifact_list',
317
- description: 'List artifacts in this project or the profile library, newest first, at most 50 per call.',
333
+ description: 'List artifacts in this project or the profile library, newest first, at most 50 per call. Pass workspaceId to list another project.',
318
334
  parameters: {
319
335
  type: 'object',
320
336
  additionalProperties: false,
321
337
  properties: {
322
338
  scope: { type: 'string', enum: ['workspace', 'library'], description: 'Defaults to workspace.' },
339
+ workspaceId: WORKSPACE_PARAM,
323
340
  type: { type: 'string', enum: ['page', 'doc', 'design'] },
324
341
  query: { type: 'string', description: 'Title substring, case-insensitive.' },
325
342
  offset: { type: 'integer' },
@@ -345,7 +362,7 @@ export function createTools(host) {
345
362
  },
346
363
  async execute(args, exec) {
347
364
  const fields = fieldsOf(args);
348
- const target = await targetFor(host, exec, optionalScope(fields));
365
+ const target = await targetFor(host, exec, optionalScope(fields), optionalString(fields, 'workspaceId'));
349
366
  const page = await service.list(target, {
350
367
  query: optionalString(fields, 'query'),
351
368
  type: optionalType(fields),
@@ -361,7 +378,7 @@ export function createTools(host) {
361
378
  type: 'object',
362
379
  additionalProperties: false,
363
380
  required: ['id'],
364
- properties: { id: { type: 'string' } },
381
+ properties: { id: { type: 'string' }, workspaceId: WORKSPACE_PARAM },
365
382
  },
366
383
  output: {
367
384
  schema: { type: 'object', additionalProperties: false, required: ['id', 'trashPath'], properties: { id: { type: 'string' }, trashPath: { type: 'string' } } },
@@ -370,7 +387,7 @@ export function createTools(host) {
370
387
  async execute(args, exec) {
371
388
  const fields = fieldsOf(args);
372
389
  const id = requiredString(fields, 'id');
373
- const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined);
390
+ const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined, optionalString(fields, 'workspaceId'));
374
391
  const result = await service.remove(target, id);
375
392
  return { id, trashPath: result.trashPath };
376
393
  },
@@ -383,7 +400,8 @@ export function createTools(host) {
383
400
  additionalProperties: false,
384
401
  required: ['id', 'format'],
385
402
  properties: { id: { type: 'string' }, format: { type: 'string', enum: ['html', 'md', 'docx', 'png', 'svg', 'fig'] },
386
- version: { type: 'integer', minimum: 1, description: 'Saved version to export. Omit for the current version.' } },
403
+ version: { type: 'integer', minimum: 1, description: 'Saved version to export. Omit for the current version.' },
404
+ workspaceId: WORKSPACE_PARAM },
387
405
  },
388
406
  output: {
389
407
  schema: { type: 'object', additionalProperties: false, required: ['path', 'bytes'], properties: { path: { type: 'string' }, bytes: { type: 'integer' } } },
@@ -392,7 +410,7 @@ export function createTools(host) {
392
410
  async execute(args, exec) {
393
411
  const fields = fieldsOf(args);
394
412
  const id = requiredString(fields, 'id');
395
- const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined);
413
+ const target = await targetFor(host, exec, id.startsWith('art_lib_') ? 'library' : undefined, optionalString(fields, 'workspaceId'));
396
414
  const file = await service.export(target, id, requiredFormat(fields), optionalInteger(fields, 'version'));
397
415
  return { path: file.path, bytes: file.bytes };
398
416
  },
@@ -400,14 +418,18 @@ export function createTools(host) {
400
418
  const designRead = {
401
419
  name: 'design_system_read',
402
420
  description: 'Read the design tokens that pages and docs in this project inherit, and whether they come from the project, the profile library, or the built-in default.',
403
- parameters: { type: 'object', additionalProperties: false, properties: {} },
421
+ parameters: { type: 'object', additionalProperties: false, properties: { workspaceId: WORKSPACE_PARAM } },
404
422
  output: {
405
423
  schema: { type: 'object', additionalProperties: false, required: ['source', 'tokens'], properties: { source: { type: 'string' }, tokens: { type: 'string' } } },
406
424
  render: (_args, value) => [{ type: 'text', text: `Design system from ${String(record(value).source)}:\n${String(record(value).tokens)}` }],
407
425
  },
408
- async execute(_args, exec) {
409
- const target = await targetFor(host, exec, undefined).catch((error) => {
410
- if (error instanceof ArtifactError && error.code === 'artifact/no-workspace')
426
+ async execute(args, exec) {
427
+ const fields = fieldsOf(args);
428
+ const workspaceId = optionalString(fields, 'workspaceId');
429
+ const target = await targetFor(host, exec, undefined, workspaceId).catch((error) => {
430
+ // A session outside every workspace can still read the library. A named
431
+ // workspace that does not resolve is a real failure.
432
+ if (workspaceId === undefined && error instanceof ArtifactError && error.code === 'artifact/no-workspace')
411
433
  return {};
412
434
  throw error;
413
435
  });
@@ -425,13 +447,14 @@ export function createTools(host) {
425
447
  properties: {
426
448
  tokens: {
427
449
  type: 'object',
428
- description: 'Partial tokens: name, notes, colors and colorsDark {primary, accent, surface, text, muted}, typography {fontFamily, displayFamily, monoFamily, scale[]}, spacing {unit, scale[]}, radius {sm, md, lg}. Sizes are pixels.',
450
+ description: 'Partial tokens: name, notes, colors and colorsDark {primary, accent, surface, text, muted, background, raised, border, control, action, actionText, focus, success, warning, danger}, typography {fontFamily, displayFamily, monoFamily, scale[]}, spacing {unit, scale[]}, radius {sm, md, lg}. Sizes are pixels.',
429
451
  },
430
452
  scope: {
431
453
  type: 'string',
432
454
  enum: ['workspace', 'library'],
433
455
  description: 'workspace (default) overrides tokens for this project only. library changes the profile default every project inherits.',
434
456
  },
457
+ workspaceId: WORKSPACE_PARAM,
435
458
  },
436
459
  },
437
460
  output: {
@@ -440,7 +463,7 @@ export function createTools(host) {
440
463
  },
441
464
  async execute(args, exec) {
442
465
  const fields = fieldsOf(args);
443
- const target = await targetFor(host, exec, optionalScope(fields));
466
+ const target = await targetFor(host, exec, optionalScope(fields), optionalString(fields, 'workspaceId'));
444
467
  const saved = await service.saveDesignSystem(target, fields.tokens);
445
468
  return { scope: saved.scope, tokens: JSON.stringify(saved.tokens, null, 2) };
446
469
  },
@@ -0,0 +1,150 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <meta name="color-scheme" content="light dark">
7
+ <title>Page design reference</title>
8
+ <!-- Render through composePage with resolved tokens. The skill supplies this file's installed path. -->
9
+ <style>
10
+ * { box-sizing: border-box; }
11
+ [hidden] { display: none !important; }
12
+ html { background: var(--artifact-color-background); scrollbar-color: var(--artifact-color-control) var(--artifact-color-background); }
13
+ body { margin: 0; color: var(--artifact-color-text); font: var(--artifact-font-size-2)/1.6 var(--artifact-font-family); overflow-wrap: anywhere; caret-color: var(--artifact-color-primary); }
14
+ ::selection { background: var(--artifact-color-action); color: var(--artifact-color-action-text); }
15
+ :focus-visible { outline: 2px solid var(--artifact-color-focus); outline-offset: 3px; }
16
+ button, input, select { font: inherit; }
17
+ button { cursor: pointer; }
18
+ a { color: var(--artifact-color-primary); text-underline-offset: .2em; }
19
+ h1, h2, h3, p { margin: 0; }
20
+ h1, h2 { font-family: var(--artifact-font-display); font-weight: 600; text-wrap: balance; }
21
+ h1 { max-width: 16ch; font-size: clamp(2.5rem, 7vw, 4.5rem); line-height: 1.03; letter-spacing: -.03em; }
22
+ h2 { font-size: clamp(1.75rem, 4vw, 2.5rem); line-height: 1.15; letter-spacing: -.02em; }
23
+ h3 { font-size: var(--artifact-font-size-2); line-height: 1.4; }
24
+ p { max-width: 65ch; }
25
+ code, .num { font-family: var(--artifact-font-mono); }
26
+ .num { text-align: right; font-variant-numeric: tabular-nums; }
27
+ .page { width: min(100% - 2 * var(--artifact-space-4), 72rem); margin: auto; padding: var(--artifact-space-6) 0; }
28
+ .header { display: flex; justify-content: space-between; align-items: flex-start; gap: var(--artifact-space-5); padding-bottom: var(--artifact-space-5); border-bottom: 1px solid var(--artifact-color-border); }
29
+ .lede { max-width: 55ch; margin-top: var(--artifact-space-4); color: var(--artifact-color-muted); }
30
+ .theme { display: flex; flex-wrap: wrap; gap: var(--artifact-space-1); flex-shrink: 0; }
31
+ .button { min-height: 44px; padding: var(--artifact-space-1) var(--artifact-space-3); border: 1px solid var(--artifact-color-control); border-radius: var(--artifact-radius-sm); background: var(--artifact-color-surface); color: var(--artifact-color-text); font-size: var(--artifact-font-size-1); font-weight: 600; }
32
+ .button:hover:not(:disabled) { border-color: var(--artifact-color-text); }
33
+ .button--primary, .theme [aria-pressed="true"] { border-color: var(--artifact-color-action); background: var(--artifact-color-action); color: var(--artifact-color-action-text); }
34
+ .button:disabled { opacity: .5; cursor: not-allowed; }
35
+ .section { padding-top: var(--artifact-space-6); }
36
+ .section-head { display: flex; align-items: baseline; justify-content: space-between; gap: var(--artifact-space-4); margin-bottom: var(--artifact-space-4); }
37
+ .note { max-width: 42ch; color: var(--artifact-color-muted); font-size: var(--artifact-font-size-1); }
38
+ .foundations { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: var(--artifact-space-5); }
39
+ .type-example { padding-top: var(--artifact-space-3); }
40
+ .type-example p + p { margin-top: var(--artifact-space-2); }
41
+ .display-example { font: 600 var(--artifact-font-size-5)/1.15 var(--artifact-font-display); letter-spacing: -.02em; }
42
+ .swatches { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: var(--artifact-space-3); }
43
+ .swatch { display: grid; gap: var(--artifact-space-1); font-size: var(--artifact-font-size-1); }
44
+ .swatch::before { content: ""; height: 44px; border: 1px solid var(--artifact-color-border); border-radius: var(--artifact-radius-sm); background: var(--swatch); }
45
+ .split { display: grid; grid-template-columns: minmax(0, 1.3fr) minmax(0, 1fr); gap: var(--artifact-space-4); align-items: start; }
46
+ .card { padding: var(--artifact-space-4); background: var(--artifact-color-surface); border: 1px solid var(--artifact-color-border); border-radius: var(--artifact-radius-lg); }
47
+ .card > p { margin-top: var(--artifact-space-2); }
48
+ .card-head { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--artifact-space-3); }
49
+ .card-head h3 { font: 600 var(--artifact-font-size-4)/1.2 var(--artifact-font-display); }
50
+ .facts { display: grid; grid-template-columns: 1fr 1fr; gap: var(--artifact-space-3); margin: var(--artifact-space-4) 0 0; }
51
+ .facts div { border-top: 1px solid var(--artifact-color-border); padding-top: var(--artifact-space-2); }
52
+ .facts dt { color: var(--artifact-color-muted); font-size: var(--artifact-font-size-1); }
53
+ .facts dd { margin: var(--artifact-space-0) 0 0; font-weight: 600; }
54
+ .callout { background: var(--artifact-color-raised); border-radius: var(--artifact-radius-md); padding: var(--artifact-space-4); }
55
+ .callout p { margin-top: var(--artifact-space-1); }
56
+ .badge { display: inline-flex; align-items: center; gap: var(--artifact-space-1); font-size: var(--artifact-font-size-1); font-weight: 600; }
57
+ .badge::before { content: ""; width: 6px; height: 6px; flex-shrink: 0; border-radius: 50%; background: currentColor; }
58
+ .badge--success { color: var(--artifact-color-success); }
59
+ .badge--warning { color: var(--artifact-color-warning); }
60
+ .badge--danger { color: var(--artifact-color-danger); }
61
+ .form { display: grid; gap: var(--artifact-space-3); max-width: 36rem; }
62
+ .field { display: grid; gap: var(--artifact-space-1); font-size: var(--artifact-font-size-1); font-weight: 600; }
63
+ .input { min-height: 44px; width: 100%; min-width: 0; padding: var(--artifact-space-1) var(--artifact-space-2); border: 1px solid var(--artifact-color-control); border-radius: var(--artifact-radius-sm); background: var(--artifact-color-surface); color: var(--artifact-color-text); }
64
+ .input::placeholder { color: var(--artifact-color-muted); opacity: 1; }
65
+ .input[aria-invalid="true"] { border-color: var(--artifact-color-danger); }
66
+ .actions { display: flex; flex-wrap: wrap; gap: var(--artifact-space-1); }
67
+ .status { color: var(--artifact-color-success); }
68
+ .error { color: var(--artifact-color-danger); }
69
+ .table-wrap { max-width: 100%; overflow-x: auto; border: 1px solid var(--artifact-color-border); border-radius: var(--artifact-radius-md); background: var(--artifact-color-surface); }
70
+ table { width: 100%; min-width: 36rem; border-collapse: collapse; font-size: var(--artifact-font-size-1); }
71
+ caption { padding: var(--artifact-space-3); text-align: left; font-weight: 600; }
72
+ th, td { padding: var(--artifact-space-2) var(--artifact-space-3); text-align: left; border-bottom: 1px solid var(--artifact-color-border); }
73
+ thead { background: var(--artifact-color-raised); }
74
+ tbody tr:last-child > * { border-bottom: 0; }
75
+ .table-hint { margin-top: var(--artifact-space-1); }
76
+ footer { margin-top: var(--artifact-space-6); border-top: 1px solid var(--artifact-color-border); padding-top: var(--artifact-space-4); }
77
+ @media (max-width: 760px) { .header, .section-head { display: grid; gap: var(--artifact-space-3); } .foundations, .split { grid-template-columns: minmax(0, 1fr); } .page { padding-top: var(--artifact-space-4); } }
78
+ @media (max-width: 420px) { .page { width: calc(100% - 2 * var(--artifact-space-3)); } .swatches { grid-template-columns: repeat(2, minmax(0, 1fr)); } .card-head { flex-wrap: wrap; } }
79
+ @media (prefers-reduced-motion: no-preference) { .button { transition: border-color .15s ease; } }
80
+ </style>
81
+ </head>
82
+ <body>
83
+ <main class="page">
84
+ <header class="header">
85
+ <div><h1>Page design reference</h1><p class="lede">A quiet editorial starting point for readable artifacts. Use the project's design language when it exists. Reuse the relevant patterns, not this specimen's content.</p></div>
86
+ <div class="theme" role="group" aria-label="Inspect theme"><button type="button" class="button" data-theme="light" aria-pressed="true">Light</button><button type="button" class="button" data-theme="dark" aria-pressed="false">Dark</button><button type="button" class="button" data-theme="host" aria-pressed="false">Follow host</button></div>
87
+ </header>
88
+ <section class="section" aria-labelledby="foundations">
89
+ <div class="section-head"><h2 id="foundations">Foundations</h2><p class="note">Warm neutral backgrounds, rust actions, and separate colors for focus and status.</p></div>
90
+ <div class="foundations"><div class="type-example"><p class="display-example">Make the decision clear.</p><p>Headings establish the hierarchy. Body text explains the evidence. Keep the reading measure near 65 characters and group related content with the spacing scale.</p><p class="note">Captions explain a source or a limit. They do not repeat the heading.</p></div>
91
+ <div class="swatches"><div class="swatch" style="--swatch:var(--artifact-color-background)">Page</div><div class="swatch" style="--swatch:var(--artifact-color-surface)">Surface</div><div class="swatch" style="--swatch:var(--artifact-color-raised)">Raised</div><div class="swatch" style="--swatch:var(--artifact-color-action)">Action</div><div class="swatch" style="--swatch:var(--artifact-color-focus)">Focus</div><div class="swatch" style="--swatch:var(--artifact-color-success)">Success</div></div></div>
92
+ </section>
93
+ <section class="section" aria-labelledby="grouping">
94
+ <div class="section-head"><h2 id="grouping">Group by meaning</h2><p class="note">Use a card for an object and a callout for a decision or limitation.</p></div>
95
+ <div class="split"><article class="card"><div class="card-head"><h3>Release review</h3><span class="badge badge--warning">Needs review</span></div><p class="note">Sample content. The mobile layout needs a review before deployment.</p><dl class="facts"><div><dt>Owner</dt><dd>Design team</dd></div><div><dt>Open checks</dt><dd class="num">3</dd></div></dl></article><aside class="callout"><h3>One system per artifact</h3><p>Use the project palette, type, and spacing together. Do not mix selected project colors with an unrelated default theme.</p></aside></div>
96
+ </section>
97
+ <section class="section" aria-labelledby="controls">
98
+ <div class="section-head"><h2 id="controls">Controls that work</h2><p class="note">This form simulates a local choice. It does not save preferences or send data.</p></div>
99
+ <form class="form" novalidate>
100
+ <label class="field" for="workspace">Workspace name<input class="input" id="workspace" name="workspaceName" autocomplete="off" maxlength="80" required aria-describedby="workspace-error" placeholder="Enter a workspace name"></label>
101
+ <p id="workspace-error" class="error" hidden>Enter a workspace name, then try again.</p>
102
+ <label class="field" for="cadence">Review cadence<select class="input" id="cadence" name="reviewCadence"><option value="weekly">Weekly</option><option value="fortnightly">Every two weeks</option><option value="monthly">Monthly</option></select></label>
103
+ <div class="actions"><button class="button button--primary" type="button" id="apply">Preview choice</button><button class="button" type="button" id="reset-choice">Reset</button><button class="button" type="button" disabled>Unavailable</button></div>
104
+ <p class="status" role="status" id="choice-status">No choice previewed yet.</p>
105
+ </form>
106
+ </section>
107
+ <section class="section" aria-labelledby="data">
108
+ <div class="section-head"><h2 id="data">Readable data</h2><p class="note">Name the units and comparison. Use text and color together for status.</p></div>
109
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Sample release checks, scroll horizontally"><table><caption>Sample release checks. Illustrative data.</caption><thead><tr><th scope="col">Check</th><th scope="col">Owner</th><th scope="col" class="num">Open items</th><th scope="col">Status</th></tr></thead><tbody>
110
+ <tr><th scope="row">API contract</th><td>Engineering</td><td class="num">0</td><td><span class="badge badge--success">Passed</span></td></tr>
111
+ <tr><th scope="row">Mobile layout</th><td>Design</td><td class="num">2</td><td><span class="badge badge--warning">Review</span></td></tr>
112
+ <tr><th scope="row">Deployment approval</th><td>Release team</td><td class="num">1</td><td><span class="badge badge--danger">Blocked</span></td></tr>
113
+ </tbody></table></div><p class="note table-hint">If columns do not fit, scroll within the table or focus it and use the arrow keys.</p>
114
+ </section>
115
+ <footer><p class="note">Use only the parts the content needs. A static report does not need fake loading states or a form. Keep charts, tables, and details tied to the same data.</p></footer>
116
+ </main>
117
+ <script>
118
+ const root = document.documentElement;
119
+ const hostTheme = root.getAttribute('data-artifact-theme');
120
+ const themeButtons = [...document.querySelectorAll('button[data-theme]')];
121
+ function setTheme(value) {
122
+ if (value === 'host') {
123
+ if (hostTheme === null) root.removeAttribute('data-artifact-theme');
124
+ else root.setAttribute('data-artifact-theme', hostTheme);
125
+ } else root.setAttribute('data-artifact-theme', value);
126
+ for (const button of themeButtons) button.setAttribute('aria-pressed', String(button.dataset.theme === value));
127
+ }
128
+ for (const button of themeButtons) button.addEventListener('click', () => setTheme(button.dataset.theme));
129
+ setTheme('host');
130
+ const form = document.querySelector('form');
131
+ const workspace = document.getElementById('workspace');
132
+ const error = document.getElementById('workspace-error');
133
+ const status = document.getElementById('choice-status');
134
+ function previewChoice() {
135
+ const valid = workspace.value.trim().length > 0;
136
+ workspace.setAttribute('aria-invalid', String(!valid));
137
+ error.hidden = valid;
138
+ if (!valid) { status.textContent = 'Choice not previewed. Enter a workspace name.'; workspace.focus(); return; }
139
+ const cadence = document.getElementById('cadence');
140
+ status.textContent = 'Preview only: ' + workspace.value.trim() + ', ' + cadence.selectedOptions[0].text.toLowerCase() + ' review. Nothing was saved or sent.';
141
+ }
142
+ form.addEventListener('submit', (event) => { event.preventDefault(); previewChoice(); });
143
+ document.getElementById('apply').addEventListener('click', previewChoice);
144
+ document.getElementById('reset-choice').addEventListener('click', () => {
145
+ form.reset(); workspace.removeAttribute('aria-invalid'); error.hidden = true;
146
+ status.textContent = 'No choice previewed yet.'; workspace.focus();
147
+ });
148
+ </script>
149
+ </body>
150
+ </html>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-artifact-studio",
3
- "version": "0.7.3",
3
+ "version": "0.8.0",
4
4
  "type": "module",
5
5
  "description": "Local-first artifacts for DeepSeek Harness: the agent creates pages and documents as versioned files, and you open, edit, restore, and export them beside the chat.",
6
6
  "keywords": [
@@ -29,6 +29,7 @@
29
29
  "client.doc.js",
30
30
  "client.canvas.js",
31
31
  "assets",
32
+ "examples/page-design-system.html",
32
33
  "cordis.patch.yml",
33
34
  "locale/*.json",
34
35
  "icon.svg",