@openplanr/protocol 0.13.0 → 0.15.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.
Files changed (34) hide show
  1. package/README.md +23 -0
  2. package/package.json +6 -2
  3. package/registries/commands.json +12 -12
  4. package/registries/roles.json +43 -133
  5. package/registries/skills.json +14 -14
  6. package/registries/task-kinds.json +2 -2
  7. package/schemas/v1.20.0/design-document.schema.json +379 -0
  8. package/schemas/v1.20.0/design-review-bundle.schema.json +692 -0
  9. package/schemas/v1.21.0/diagram-authoring-bundle.schema.json +1609 -0
  10. package/schemas/v1.21.0/diagram-edit-transaction.schema.json +4369 -0
  11. package/schemas/v1.21.0/diagram-review-bundle.schema.json +4047 -0
  12. package/schemas/v1.21.0/diagram-shape-definition.schema.json +457 -0
  13. package/schemas/v1.22.0/design-document.schema.json +506 -0
  14. package/schemas/v1.22.0/design-review-bundle.schema.json +822 -0
  15. package/schemas/v1.5.0/role-registry.schema.json +4 -1
  16. package/src/browser-contracts.d.mts +5 -1
  17. package/src/browser-contracts.mjs +27 -0
  18. package/src/contracts.mjs +39 -6
  19. package/src/design-contracts.d.mts +40 -2
  20. package/src/design-contracts.mjs +258 -17
  21. package/src/design-publication-contracts.mjs +3 -1
  22. package/src/diagram-authoring-contracts.d.mts +2 -0
  23. package/src/generated/canonical-registries.mjs +71 -161
  24. package/src/index.d.mts +7 -0
  25. package/src/index.mjs +7 -0
  26. package/src/json-schema.mjs +4 -0
  27. package/src/registries.mjs +20 -4
  28. package/src/review-experience-contracts.d.mts +2 -0
  29. package/src/review-experience-contracts.mjs +77 -5
  30. package/src/shape-library-contracts.d.mts +57 -0
  31. package/src/shape-library-contracts.mjs +266 -0
  32. package/src/studio-presentation-contracts.d.mts +50 -2
  33. package/src/studio-presentation-contracts.mjs +285 -4
  34. package/src/workspace-contracts.mjs +3 -3
@@ -233,7 +233,10 @@
233
233
  ]
234
234
  },
235
235
  "nativeId": {
236
- "$ref": "common.schema.json#/$defs/identifier"
236
+ "type": "string",
237
+ "pattern": "^(?:[a-z][a-z0-9]*(?:-[a-z0-9]+)*:)?[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
238
+ "minLength": 1,
239
+ "maxLength": 128
237
240
  },
238
241
  "generatedPath": {
239
242
  "$ref": "common.schema.json#/$defs/relativePath"
@@ -15,7 +15,9 @@ export declare function protocolAssetUrl(
15
15
  | '1.13.0'
16
16
  | '1.15.0'
17
17
  | '1.16.0'
18
- | '1.17.0';
18
+ | '1.17.0'
19
+ | '1.19.0'
20
+ | '1.21.0';
19
21
  },
20
22
  ): URL;
21
23
  export declare const PROTOCOL_V113_CONTRACTS: Readonly<Record<string, string>>;
@@ -36,3 +38,5 @@ export declare function validateEnterpriseJourneyArtifact(
36
38
  kind: string,
37
39
  value: unknown,
38
40
  ): { path: string; rule: string; detail: string }[];
41
+
42
+ export declare const PROTOCOL_V121_CONTRACTS: Readonly<Record<string, string>>;
@@ -1,3 +1,4 @@
1
+ import { assertVersionedDiagramReviewBundle } from './studio-presentation-contracts.mjs';
1
2
  // @ts-check
2
3
 
3
4
  import { DESIGN_HANDOFF_CONTRACT_FILES } from './design-handoff-contracts.mjs';
@@ -61,6 +62,20 @@ export const PROTOCOL_V115_CONTRACTS = Object.freeze(
61
62
  * @type {typeof import('./browser-contracts.d.mts').validateDiagramReviewArtifact}
62
63
  */
63
64
  export function validateDiagramReviewArtifact(kind, value, { protocolVersion = '1.15.0' } = {}) {
65
+ if (kind === 'diagram-review-bundle' && ['1.17.0', '1.21.0'].includes(protocolVersion)) {
66
+ try {
67
+ assertVersionedDiagramReviewBundle(value);
68
+ return [];
69
+ } catch (error) {
70
+ return [
71
+ {
72
+ path: '$',
73
+ rule: 'diagram-review-contract',
74
+ detail: error instanceof Error ? error.message : 'Invalid diagram review data.',
75
+ },
76
+ ];
77
+ }
78
+ }
64
79
  if (protocolVersion !== '1.15.0' || !Object.hasOwn(DIAGRAM_REVIEW_SCHEMAS, kind))
65
80
  throw new RangeError(`Unknown diagram review Protocol contract: ${kind}@${protocolVersion}`);
66
81
  try {
@@ -112,6 +127,17 @@ export function validateEnterpriseJourneyArtifact(kind, value) {
112
127
  }
113
128
  }
114
129
 
130
+ export const PROTOCOL_V121_CONTRACTS = Object.freeze(
131
+ Object.fromEntries(
132
+ [
133
+ 'diagram-authoring-bundle',
134
+ 'diagram-edit-transaction',
135
+ 'diagram-review-bundle',
136
+ 'diagram-shape-definition',
137
+ ].map((kind) => [kind, `${kind}.schema.json`]),
138
+ ),
139
+ );
140
+
115
141
  const PROTOCOL_CONTRACTS_BY_VERSION = Object.freeze({
116
142
  '1.5.0': PROTOCOL_V15_CONTRACTS,
117
143
  '1.6.0': PROTOCOL_V16_CONTRACTS,
@@ -123,6 +149,7 @@ const PROTOCOL_CONTRACTS_BY_VERSION = Object.freeze({
123
149
  '1.16.0': PROTOCOL_V116_CONTRACTS,
124
150
  '1.17.0': PROTOCOL_V117_CONTRACTS,
125
151
  '1.19.0': PROTOCOL_V119_CONTRACTS,
152
+ '1.21.0': PROTOCOL_V121_CONTRACTS,
126
153
  });
127
154
 
128
155
  /**
package/src/contracts.mjs CHANGED
@@ -1,3 +1,4 @@
1
+ import { assertShapeDefinition } from './shape-library-contracts.mjs';
1
2
  // @ts-check
2
3
  /**
3
4
  * Protocol artifact schema registry and validation: resolves each kind and version to its packaged
@@ -13,6 +14,7 @@ import { dirname, join, relative, resolve, sep } from 'node:path';
13
14
  import { fileURLToPath } from 'node:url';
14
15
  import { PROTOCOL_V115_CONTRACTS, validateDiagramReviewArtifact } from './browser-contracts.mjs';
15
16
  import { deepFreeze } from './canonical-json.mjs';
17
+ import { validateDesignProps } from './design-contracts.mjs';
16
18
  import { DESIGN_HANDOFF_CONTRACT_FILES } from './design-handoff-contracts.mjs';
17
19
  import {
18
20
  assertDiagramData,
@@ -43,9 +45,9 @@ import {
43
45
  } from './skill-source-contracts.mjs';
44
46
  import {
45
47
  assertDiagramPresentation,
46
- assertDiagramReviewBundleV11,
47
48
  assertVersionedDiagramAuthoringBundle,
48
49
  assertVersionedDiagramEditTransaction,
50
+ assertVersionedDiagramReviewBundle,
49
51
  } from './studio-presentation-contracts.mjs';
50
52
 
51
53
  const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -56,6 +58,12 @@ const v16Schema = (kind) => `schemas/v1.6.0/${PROTOCOL_V16_CONTRACT_FILES[kind]}
56
58
  const v17Schema = (kind) => `schemas/v1.7.0/${PROTOCOL_V17_CONTRACT_FILES[kind]}`;
57
59
  const v18Schema = (kind) => `schemas/v1.8.0/${PROTOCOL_V18_CONTRACT_FILES[kind]}`;
58
60
 
61
+ const shapeContractKinds = [
62
+ 'diagram-authoring-bundle',
63
+ 'diagram-edit-transaction',
64
+ 'diagram-review-bundle',
65
+ 'diagram-shape-definition',
66
+ ];
59
67
  const foundationPaths = {
60
68
  ...Object.fromEntries(
61
69
  Object.keys(LARGE_OBJECT_SCHEMAS).map((name) => [
@@ -74,7 +82,11 @@ const foundationPaths = {
74
82
  },
75
83
  ]),
76
84
  ),
77
- 'design-document': { '1.9.0': 'schemas/v1.9.0/design-document.schema.json' },
85
+ 'design-document': {
86
+ '1.9.0': 'schemas/v1.9.0/design-document.schema.json',
87
+ '1.20.0': 'schemas/v1.20.0/design-document.schema.json',
88
+ '1.22.0': 'schemas/v1.22.0/design-document.schema.json',
89
+ },
78
90
  'design-review-workspace': { '1.9.0': 'schemas/v1.9.0/design-review-workspace.schema.json' },
79
91
  'design-workspace-create': { '1.9.0': 'schemas/v1.9.0/design-workspace-create.schema.json' },
80
92
  'design-workspace-revision': { '1.9.0': 'schemas/v1.9.0/design-workspace-revision.schema.json' },
@@ -83,6 +95,8 @@ const foundationPaths = {
83
95
  '1.9.0': 'schemas/v1.9.0/design-review-bundle.schema.json',
84
96
  '1.10.0': 'schemas/v1.10.0/design-review-bundle.schema.json',
85
97
  '1.16.0': 'schemas/v1.16.0/design-review-bundle.schema.json',
98
+ '1.20.0': 'schemas/v1.20.0/design-review-bundle.schema.json',
99
+ '1.22.0': 'schemas/v1.22.0/design-review-bundle.schema.json',
86
100
  },
87
101
  'design-review-context': { '1.10.0': 'schemas/v1.10.0/design-review-context.schema.json' },
88
102
  'design-review-handoff': { '1.10.0': 'schemas/v1.10.0/design-review-handoff.schema.json' },
@@ -269,6 +283,12 @@ const foundationPaths = {
269
283
  };
270
284
 
271
285
  // Authoring successors are additive; preserve every legacy diagram registration.
286
+ for (const kind of shapeContractKinds)
287
+ foundationPaths[kind] = {
288
+ ...foundationPaths[kind],
289
+ '1.21.0': `schemas/v1.21.0/${kind}.schema.json`,
290
+ };
291
+
272
292
  for (const kind of Object.keys(ENTERPRISE_JOURNEY_SCHEMAS)) {
273
293
  foundationPaths[kind] = {
274
294
  ...foundationPaths[kind],
@@ -1248,8 +1268,8 @@ function guidedQuestionnaireCompatibilityErrors(value) {
1248
1268
  export function validateProtocolArtifact(kind, value, { protocolVersion } = {}) {
1249
1269
  const journeyErrors = validateCompanyJourneyArtifact(kind, value, protocolVersion);
1250
1270
  if (journeyErrors) return journeyErrors;
1251
- const studioKind = Object.hasOwn(LARGE_OBJECT_SCHEMAS, kind);
1252
- if (studioKind && protocolVersion === '1.17.0') {
1271
+ const studioKind = Object.hasOwn(LARGE_OBJECT_SCHEMAS, kind) || shapeContractKinds.includes(kind);
1272
+ if (studioKind && ['1.17.0', '1.21.0'].includes(protocolVersion)) {
1253
1273
  return validateStudioArtifact(kind, value, sharedProtocolSchema(kind, protocolVersion));
1254
1274
  }
1255
1275
  if (Object.hasOwn(PROTOCOL_V115_CONTRACTS, kind)) {
@@ -1292,7 +1312,7 @@ export function validateProtocolArtifact(kind, value, { protocolVersion } = {})
1292
1312
  versionInput = { protocolVersion: descriptor?.value };
1293
1313
  }
1294
1314
  const version = inferredVersion(kind, versionInput, protocolVersion);
1295
- if (studioKind && version === '1.17.0') {
1315
+ if (studioKind && ['1.17.0', '1.21.0'].includes(version)) {
1296
1316
  return validateStudioArtifact(kind, value, sharedProtocolSchema(kind, version));
1297
1317
  }
1298
1318
  if (version === '1.13.0' && authoringKind) {
@@ -1347,7 +1367,8 @@ function validateStudioArtifact(kind, value, resolved) {
1347
1367
  if (Object.hasOwn(SHARING_SECURITY_SCHEMAS, kind)) assertSharingSecurityContract(value, kind);
1348
1368
  else if (kind === 'diagram-authoring-bundle') assertVersionedDiagramAuthoringBundle(value);
1349
1369
  else if (kind === 'diagram-edit-transaction') assertVersionedDiagramEditTransaction(value);
1350
- else if (kind === 'diagram-review-bundle') assertDiagramReviewBundleV11(value);
1370
+ else if (kind === 'diagram-review-bundle') assertVersionedDiagramReviewBundle(value);
1371
+ else if (kind === 'diagram-shape-definition') assertShapeDefinition(value);
1351
1372
  else if (kind === 'diagram-presentation') assertDiagramPresentation(value);
1352
1373
  else assertLargeObjectContract(value, kind);
1353
1374
  return [];
@@ -1363,6 +1384,18 @@ function validateStudioArtifact(kind, value, resolved) {
1363
1384
  }
1364
1385
  function validateGenericArtifact(kind, value, resolved) {
1365
1386
  const errors = validateResolvedArtifact(value, resolved);
1387
+ if (
1388
+ !errors.length &&
1389
+ resolved.protocolVersion === '1.22.0' &&
1390
+ ['design-document', 'design-review-bundle'].includes(kind)
1391
+ )
1392
+ errors.push(
1393
+ ...validateDesignProps(kind === 'design-document' ? value : value.design).map((detail) => ({
1394
+ path: '$',
1395
+ rule: 'design-props',
1396
+ detail,
1397
+ })),
1398
+ );
1366
1399
  if (kind === 'guided-questionnaire' && resolved.protocolVersion === '1.2.0')
1367
1400
  errors.push(...guidedQuestionnaireCompatibilityErrors(value));
1368
1401
  return errors;
@@ -11,14 +11,21 @@ export interface DesignFrame {
11
11
  id: string;
12
12
  label: string;
13
13
  width: number;
14
- height: number;
14
+ height: number | 'auto';
15
15
  }
16
16
 
17
+ export type DesignProp =
18
+ | { type: 'enum'; options: string[]; default: string }
19
+ | { type: 'boolean'; default: boolean };
20
+
21
+ export type DesignPropValue = string | boolean;
22
+
17
23
  export interface DesignScreen {
18
24
  id: string;
19
25
  title: string;
20
26
  description?: string;
21
27
  source: DesignSource;
28
+ props?: Record<string, DesignProp>;
22
29
  /** Stable feedback anchors, unique within this screen. */
23
30
  anchors?: string[];
24
31
  }
@@ -32,11 +39,32 @@ export interface DesignVariant {
32
39
  issue?: string;
33
40
  /** Sparse screen overrides inherit unchanged sources from screens. */
34
41
  sources?: Record<string, DesignSource>;
42
+ props?: Record<string, Record<string, DesignPropValue>>;
43
+ }
44
+
45
+ export interface DesignBoardPosition {
46
+ x: number;
47
+ y: number;
48
+ title?: string;
49
+ }
50
+
51
+ export interface DesignSection {
52
+ id: string;
53
+ x: number;
54
+ y: number;
55
+ text: string;
56
+ maxW?: number;
57
+ }
58
+
59
+ export interface DesignLayout {
60
+ /** Keys identify a screen, screen/frame or screen/frame/variant. */
61
+ boards?: Record<string, DesignBoardPosition>;
62
+ sections?: DesignSection[];
35
63
  }
36
64
 
37
65
  export interface DesignDocument {
38
66
  kind: 'openplanr-design-document';
39
- schemaVersion: '1.0.0';
67
+ schemaVersion: '1.0.0' | '1.1.0';
40
68
  id: string;
41
69
  title: string;
42
70
  brief: {
@@ -47,6 +75,7 @@ export interface DesignDocument {
47
75
  };
48
76
  designSystem?: { path?: string; tokens?: string; spacing?: number[] };
49
77
  assets?: string[];
78
+ layout?: DesignLayout;
50
79
  frames: DesignFrame[];
51
80
  screens: DesignScreen[];
52
81
  screenOrder: string[];
@@ -57,6 +86,15 @@ export interface DesignDocument {
57
86
  }
58
87
 
59
88
  export declare const DESIGN_DOCUMENT_VERSION: '1.0.0';
89
+ export declare const DESIGN_DOCUMENT_V1_SCHEMA: Readonly<Record<string, unknown>>;
90
+ export declare const DESIGN_DOCUMENT_V120_SCHEMA: Readonly<Record<string, unknown>>;
60
91
  export declare const DESIGN_DOCUMENT_SCHEMA: Readonly<Record<string, unknown>>;
61
92
  export declare function validateDesignDocument(value: unknown): { ok: boolean; errors: string[] };
62
93
  export declare function assertDesignDocument(value: unknown): DesignDocument;
94
+
95
+ export declare function initialFrameHeight(document: Pick<DesignDocument, 'frames'>): number;
96
+
97
+ export declare function validateDesignProps(document: {
98
+ screens: Pick<DesignScreen, 'id' | 'props'>[];
99
+ variants: Pick<DesignVariant, 'props'>[];
100
+ }): string[];
@@ -7,6 +7,16 @@ import { validateJson } from './json-schema.mjs';
7
7
  */
8
8
  export const DESIGN_DOCUMENT_VERSION = '1.0.0';
9
9
 
10
+ /** Initial viewport height for content-sized frames.
11
+ * @type {typeof import('./design-contracts.d.mts').initialFrameHeight}
12
+ */
13
+ export function initialFrameHeight(document) {
14
+ const fixed = document.frames.flatMap(({ height }) =>
15
+ typeof height === 'number' && Number.isInteger(height) ? [height] : [],
16
+ );
17
+ return fixed.length ? Math.max(...fixed) : 900;
18
+ }
19
+
10
20
  const freeze = (value) => {
11
21
  if (value && typeof value === 'object') {
12
22
  for (const nested of Object.values(value)) freeze(nested);
@@ -15,12 +25,28 @@ const freeze = (value) => {
15
25
  return value;
16
26
  };
17
27
 
28
+ const FRAME_SCHEMA = {
29
+ type: 'array',
30
+ minItems: 1,
31
+ items: {
32
+ type: 'object',
33
+ additionalProperties: false,
34
+ required: ['id', 'label', 'width', 'height'],
35
+ properties: {
36
+ id: { $ref: '#/$defs/id' },
37
+ label: { $ref: '#/$defs/text' },
38
+ width: { type: 'integer', minimum: 1, maximum: 16384 },
39
+ height: { type: 'integer', minimum: 1, maximum: 16384 },
40
+ },
41
+ },
42
+ };
43
+
18
44
  /**
19
45
  * Portable source of truth for the packaged Protocol 1.9 schema. Rendering,
20
46
  * file existence, symlink containment and revisions belong to the design domain.
21
- * @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_SCHEMA}
47
+ * @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_V1_SCHEMA}
22
48
  */
23
- export const DESIGN_DOCUMENT_SCHEMA = freeze({
49
+ export const DESIGN_DOCUMENT_V1_SCHEMA = freeze({
24
50
  $schema: 'https://json-schema.org/draft/2020-12/schema',
25
51
  $id: 'https://openplanr.dev/schemas/v1.9.0/design-document.schema.json',
26
52
  'x-openplanr-contract': { id: 'design-document', version: '1.9.0' },
@@ -71,21 +97,7 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
71
97
  },
72
98
  },
73
99
  assets: { $ref: '#/$defs/paths' },
74
- frames: {
75
- type: 'array',
76
- minItems: 1,
77
- items: {
78
- type: 'object',
79
- additionalProperties: false,
80
- required: ['id', 'label', 'width', 'height'],
81
- properties: {
82
- id: { $ref: '#/$defs/id' },
83
- label: { $ref: '#/$defs/text' },
84
- width: { type: 'integer', minimum: 1, maximum: 16384 },
85
- height: { type: 'integer', minimum: 1, maximum: 16384 },
86
- },
87
- },
88
- },
100
+ frames: FRAME_SCHEMA,
89
101
  screens: {
90
102
  type: 'array',
91
103
  minItems: 1,
@@ -163,6 +175,195 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
163
175
  },
164
176
  });
165
177
 
178
+ /** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_V120_SCHEMA} */
179
+ export const DESIGN_DOCUMENT_V120_SCHEMA = freeze({
180
+ ...DESIGN_DOCUMENT_V1_SCHEMA,
181
+ $id: 'https://openplanr.dev/schemas/v1.20.0/design-document.schema.json',
182
+ 'x-openplanr-contract': { id: 'design-document', version: '1.20.0' },
183
+ properties: {
184
+ .../** @type {Record<string, unknown>} */ (DESIGN_DOCUMENT_V1_SCHEMA.properties),
185
+ frames: {
186
+ ...FRAME_SCHEMA,
187
+ items: {
188
+ ...FRAME_SCHEMA.items,
189
+ properties: {
190
+ ...FRAME_SCHEMA.items.properties,
191
+ height: { anyOf: [{ type: 'integer', minimum: 1, maximum: 16384 }, { const: 'auto' }] },
192
+ },
193
+ },
194
+ },
195
+ layout: {
196
+ type: 'object',
197
+ additionalProperties: false,
198
+ properties: {
199
+ boards: {
200
+ type: 'object',
201
+ description:
202
+ 'Keys are screenId, screenId/frameId or screenId/frameId/variantId; each ID must exist in the document.',
203
+ additionalProperties: {
204
+ type: 'object',
205
+ additionalProperties: false,
206
+ required: ['x', 'y'],
207
+ properties: {
208
+ x: { $ref: '#/$defs/coordinate' },
209
+ y: { $ref: '#/$defs/coordinate' },
210
+ title: { $ref: '#/$defs/text' },
211
+ },
212
+ },
213
+ },
214
+ sections: {
215
+ type: 'array',
216
+ items: {
217
+ type: 'object',
218
+ additionalProperties: false,
219
+ required: ['id', 'x', 'y', 'text'],
220
+ properties: {
221
+ id: { $ref: '#/$defs/id' },
222
+ x: { $ref: '#/$defs/coordinate' },
223
+ y: { $ref: '#/$defs/coordinate' },
224
+ text: { $ref: '#/$defs/text' },
225
+ maxW: { type: 'integer', minimum: 1, maximum: 16384 },
226
+ },
227
+ },
228
+ },
229
+ },
230
+ },
231
+ },
232
+ $defs: {
233
+ .../** @type {Record<string, unknown>} */ (DESIGN_DOCUMENT_V1_SCHEMA.$defs),
234
+ coordinate: { type: 'number', minimum: -1e7, maximum: 1e7 },
235
+ },
236
+ });
237
+
238
+ const PROP_TOKEN_SCHEMA = {
239
+ type: 'string',
240
+ minLength: 1,
241
+ maxLength: 128,
242
+ pattern: '^[a-z][a-z0-9-]*(?![\\s\\S])',
243
+ };
244
+ const propTokenPattern = new RegExp(PROP_TOKEN_SCHEMA.pattern, 'u');
245
+ const isPropToken = (value) =>
246
+ typeof value === 'string' &&
247
+ value.length <= PROP_TOKEN_SCHEMA.maxLength &&
248
+ propTokenPattern.test(value);
249
+
250
+ const currentDocument =
251
+ /** @type {{ properties: Record<string, unknown>; [key: string]: unknown }} */ (
252
+ structuredClone(DESIGN_DOCUMENT_V120_SCHEMA)
253
+ );
254
+ currentDocument.$id = 'https://openplanr.dev/schemas/v1.22.0/design-document.schema.json';
255
+ currentDocument['x-openplanr-contract'] = { id: 'design-document', version: '1.22.0' };
256
+ currentDocument.properties.schemaVersion = { enum: ['1.0.0', '1.1.0'] };
257
+ const screenSchema = /** @type {{ items: { properties: Record<string, unknown> } }} */ (
258
+ currentDocument.properties.screens
259
+ );
260
+ screenSchema.items.properties.props = {
261
+ type: 'object',
262
+ propertyNames: PROP_TOKEN_SCHEMA,
263
+ additionalProperties: {
264
+ oneOf: [
265
+ {
266
+ type: 'object',
267
+ additionalProperties: false,
268
+ required: ['type', 'options', 'default'],
269
+ properties: {
270
+ type: { const: 'enum' },
271
+ options: {
272
+ type: 'array',
273
+ minItems: 1,
274
+ uniqueItems: true,
275
+ items: PROP_TOKEN_SCHEMA,
276
+ },
277
+ default: PROP_TOKEN_SCHEMA,
278
+ },
279
+ },
280
+ {
281
+ type: 'object',
282
+ additionalProperties: false,
283
+ required: ['type', 'default'],
284
+ properties: { type: { const: 'boolean' }, default: { type: 'boolean' } },
285
+ },
286
+ ],
287
+ },
288
+ };
289
+ const variantSchema = /** @type {{ items: { properties: Record<string, unknown> } }} */ (
290
+ currentDocument.properties.variants
291
+ );
292
+ variantSchema.items.properties.props = {
293
+ type: 'object',
294
+ propertyNames: { $ref: '#/$defs/id' },
295
+ additionalProperties: {
296
+ type: 'object',
297
+ propertyNames: PROP_TOKEN_SCHEMA,
298
+ additionalProperties: { anyOf: [PROP_TOKEN_SCHEMA, { type: 'boolean' }] },
299
+ },
300
+ };
301
+ currentDocument.allOf = [
302
+ {
303
+ if: { properties: { schemaVersion: { const: '1.1.0' } }, required: ['schemaVersion'] },
304
+ else: {
305
+ properties: {
306
+ screens: { items: { not: { required: ['props'] } } },
307
+ variants: { items: { not: { required: ['props'] } } },
308
+ },
309
+ },
310
+ },
311
+ ];
312
+ /** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_SCHEMA} */
313
+ export const DESIGN_DOCUMENT_SCHEMA = freeze(currentDocument);
314
+
315
+ /** Validate prop references and values after structural validation.
316
+ * @type {typeof import('./design-contracts.d.mts').validateDesignProps}
317
+ */
318
+ export function validateDesignProps(document) {
319
+ const errors = [];
320
+ const checkToken = (value, path) => {
321
+ if (!isPropToken(value))
322
+ errors.push(
323
+ `${path}: ${JSON.stringify(value)} must be a lowercase token matching ${PROP_TOKEN_SCHEMA.pattern} with at most ${PROP_TOKEN_SCHEMA.maxLength} characters`,
324
+ );
325
+ };
326
+ const screens = new Map(document.screens.map((screen) => [screen.id, screen]));
327
+ for (const [index, screen] of document.screens.entries()) {
328
+ for (const [name, prop] of Object.entries(screen.props ?? {})) {
329
+ const path = `$.screens[${index}].props.${name}`;
330
+ checkToken(name, path);
331
+ if (prop.type === 'enum') {
332
+ for (const [optionIndex, option] of prop.options.entries())
333
+ checkToken(option, `${path}.options[${optionIndex}]`);
334
+ checkToken(prop.default, `${path}.default`);
335
+ if (!prop.options.includes(prop.default))
336
+ errors.push(`${path}.default: '${prop.default}' is not an enum option`);
337
+ }
338
+ }
339
+ }
340
+ for (const [index, variant] of document.variants.entries()) {
341
+ for (const [screenId, values] of Object.entries(variant.props ?? {})) {
342
+ const screen = screens.get(screenId);
343
+ const path = `$.variants[${index}].props.${screenId}`;
344
+ if (!screen) {
345
+ errors.push(`${path}: unknown screen '${screenId}'`);
346
+ continue;
347
+ }
348
+ for (const [name, value] of Object.entries(values)) {
349
+ checkToken(name, `${path}.${name}`);
350
+ if (typeof value === 'string') checkToken(value, `${path}.${name}`);
351
+ const props = screen.props ?? {};
352
+ const prop = Object.hasOwn(props, name) ? props[name] : undefined;
353
+ if (!prop) errors.push(`${path}.${name}: unknown prop '${name}' on screen '${screenId}'`);
354
+ else if (prop.type === 'boolean' && typeof value !== 'boolean')
355
+ errors.push(`${path}.${name}: expected a boolean, received ${JSON.stringify(value)}`);
356
+ else if (
357
+ prop.type === 'enum' &&
358
+ (typeof value !== 'string' || !prop.options.includes(value))
359
+ )
360
+ errors.push(`${path}.${name}: ${JSON.stringify(value)} is not an enum option`);
361
+ }
362
+ }
363
+ }
364
+ return errors;
365
+ }
366
+
166
367
  /**
167
368
  * Validate structure plus stable identity and cross-reference constraints.
168
369
  * @returns {ReturnType<typeof import('./design-contracts.d.mts').validateDesignDocument>}
@@ -171,7 +372,17 @@ export function validateDesignDocument(value) {
171
372
  const errors = validateJson(value, DESIGN_DOCUMENT_SCHEMA).map(
172
373
  ({ path, detail }) => `${path}: ${detail}`,
173
374
  );
375
+ if (
376
+ value?.schemaVersion === '1.0.0' &&
377
+ ['screens', 'variants'].some(
378
+ (field) =>
379
+ Array.isArray(value[field]) &&
380
+ value[field].some((item) => item && Object.hasOwn(item, 'props')),
381
+ )
382
+ )
383
+ errors.push('$.schemaVersion: props require schemaVersion "1.1.0"');
174
384
  if (errors.length > 0) return { ok: false, errors };
385
+ errors.push(...validateDesignProps(value));
175
386
 
176
387
  for (const field of ['frames', 'screens', 'flows', 'variants']) {
177
388
  const seen = new Set();
@@ -200,6 +411,36 @@ export function validateDesignDocument(value) {
200
411
  if (!screenIds.has(id)) errors.push(`$.variants[${index}].sources: unknown screen '${id}'`);
201
412
  }
202
413
  }
414
+ const frameIds = new Set(value.frames.map(({ id }) => id));
415
+ const variantIds = new Set(value.variants.map(({ id }) => id));
416
+ for (const [key, position] of Object.entries(value.layout?.boards ?? {})) {
417
+ const parts = key.split('/');
418
+ const path = `$.layout.boards['${key}']`;
419
+ if (parts.length > 3 || parts.some((id) => !/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(id))) {
420
+ errors.push(`${path}: expected screenId, screenId/frameId or screenId/frameId/variantId`);
421
+ } else {
422
+ const [screenId, frameId, variantId] = parts;
423
+ if (!screenIds.has(screenId)) errors.push(`${path}: unknown screen '${screenId}'`);
424
+ if (frameId !== undefined && !frameIds.has(frameId))
425
+ errors.push(`${path}: unknown frame '${frameId}'`);
426
+ if (variantId !== undefined && !variantIds.has(variantId))
427
+ errors.push(`${path}: unknown variant '${variantId}'`);
428
+ }
429
+ for (const axis of ['x', 'y']) {
430
+ if (!Number.isFinite(position[axis]))
431
+ errors.push(`${path}.${axis}: expected a finite coordinate`);
432
+ }
433
+ }
434
+ const sectionIds = new Set();
435
+ for (const [index, section] of (value.layout?.sections ?? []).entries()) {
436
+ if (sectionIds.has(section.id))
437
+ errors.push(`$.layout.sections[${index}].id: duplicate identity '${section.id}'`);
438
+ sectionIds.add(section.id);
439
+ for (const axis of ['x', 'y']) {
440
+ if (!Number.isFinite(section[axis]))
441
+ errors.push(`$.layout.sections[${index}].${axis}: expected a finite coordinate`);
442
+ }
443
+ }
203
444
  const selected = value.variants.find(({ id }) => id === value.selectedVariant);
204
445
  if (!selected) errors.push(`$.selectedVariant: unknown variant '${value.selectedVariant}'`);
205
446
  else if (selected.status !== 'ready')
@@ -2,6 +2,7 @@
2
2
  /** Company publication constraints over the existing, compatible review bundle. */
3
3
 
4
4
  import { canonicalizeJson, sha256Hex } from './canonical-json.mjs';
5
+ import { initialFrameHeight } from './design-contracts.mjs';
5
6
  import { assertDesignReviewBundle } from './review-experience-contracts.mjs';
6
7
 
7
8
  /** @type {typeof import('./design-publication-contracts.d.mts').COMPANY_DESIGN_MAX_BYTES} */
@@ -120,7 +121,8 @@ export function assertCompanyDesignBundle(value) {
120
121
  fail('entries must uniquely map artboards to artifacts.');
121
122
  usedArtifacts.add(entry.artifactId);
122
123
  combinations.add(key);
123
- if (artifact.viewport.width !== frame.width || artifact.viewport.height !== frame.height)
124
+ const height = frame.height === 'auto' ? initialFrameHeight(design) : frame.height;
125
+ if (artifact.viewport.width !== frame.width || artifact.viewport.height !== height)
124
126
  fail('artifact viewport must match its declared frame.');
125
127
  }
126
128
  closed(envelope.viewer, ['mode', 'activeArtifactId', 'presentation'], 'viewer');
@@ -1,3 +1,4 @@
1
+ import type { ShapeReference } from './shape-library-contracts.mjs';
1
2
  export type DiagramAuthoringDigest = `sha256:${string}`;
2
3
  export type DiagramAuthoringProfile = 'flowchart' | 'process' | 'swimlane' | 'architecture';
3
4
  export type DiagramAuthoringNodeKind =
@@ -110,6 +111,7 @@ export interface DiagramRoute {
110
111
  points: Array<{ x: number; y: number }>;
111
112
  }
112
113
  export interface DiagramAppearance {
114
+ shapeRef?: ShapeReference;
113
115
  shape:
114
116
  | 'rectangle'
115
117
  | 'rounded-rectangle'