@whzxc/agent-design-gallery 0.15.0 → 0.16.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 (76) hide show
  1. package/README.md +5 -2
  2. package/package.json +2 -1
  3. package/public/app.js +602 -64
  4. package/public/assets.js +25 -10
  5. package/public/boards.js +8 -3
  6. package/public/frame-identity.js +25 -12
  7. package/public/icons.js +7 -0
  8. package/public/index.html +14 -2
  9. package/public/motion-flow.js +28 -0
  10. package/public/motion-identity.js +100 -0
  11. package/public/motion-paint.js +332 -0
  12. package/public/motion-scene.js +165 -0
  13. package/public/motion-specimens.js +335 -0
  14. package/public/player.css +270 -0
  15. package/public/player.js +753 -0
  16. package/public/recent-updates.js +535 -0
  17. package/public/style.css +17 -2
  18. package/public/tokens.css +6 -0
  19. package/public/view-boards.css +131 -0
  20. package/public/view-boards.js +350 -0
  21. package/public/view-route.js +1 -1
  22. package/src/boards/motion-board.mjs +202 -0
  23. package/src/boards/token-board.mjs +9 -5
  24. package/src/cli-output.mjs +3 -1
  25. package/src/cli.mjs +52 -18
  26. package/src/http.mjs +5 -2
  27. package/src/recent-frames.mjs +295 -0
  28. package/src/recent-history.mjs +100 -0
  29. package/src/recent-job.mjs +63 -0
  30. package/src/recent-worker.mjs +171 -0
  31. package/src/server.mjs +229 -18
  32. package/src/toolkit/arch-git.mjs +8 -14
  33. package/src/toolkit/browser.mjs +1 -13
  34. package/src/toolkit/build-store.mjs +9 -1
  35. package/src/toolkit/build-worker.mjs +6 -0
  36. package/src/toolkit/build.mjs +22 -16
  37. package/src/toolkit/commands.mjs +93 -2
  38. package/src/toolkit/compare.mjs +13 -11
  39. package/src/toolkit/config.mjs +2 -2
  40. package/src/toolkit/diff-inputs.mjs +35 -26
  41. package/src/toolkit/diff.mjs +24 -11
  42. package/src/toolkit/frame-declarations.mjs +36 -0
  43. package/src/toolkit/git-blobs.mjs +50 -0
  44. package/src/toolkit/impact-inputs.mjs +11 -19
  45. package/src/toolkit/impact-selection.mjs +2 -2
  46. package/src/toolkit/impact.mjs +17 -3
  47. package/src/toolkit/implementation-map.mjs +17 -6
  48. package/src/toolkit/input-generation.mjs +15 -0
  49. package/src/toolkit/inspect-output.mjs +1 -1
  50. package/src/toolkit/inspect.d.ts +9 -1
  51. package/src/toolkit/inspect.mjs +25 -1
  52. package/src/toolkit/motion-check.mjs +382 -0
  53. package/src/toolkit/motion-css.mjs +105 -0
  54. package/src/toolkit/motion-flows.mjs +95 -0
  55. package/src/toolkit/motion-impact.mjs +87 -0
  56. package/src/toolkit/motion-inventory.mjs +202 -0
  57. package/src/toolkit/motion-label.mjs +111 -0
  58. package/src/toolkit/motion-patterns.mjs +216 -0
  59. package/src/toolkit/motion-primitives.mjs +94 -0
  60. package/src/toolkit/motion-queries.mjs +169 -0
  61. package/src/toolkit/motion.mjs +300 -0
  62. package/src/toolkit/owner.mjs +19 -6
  63. package/src/toolkit/play-endpoint.mjs +66 -0
  64. package/src/toolkit/project-index.mjs +2 -2
  65. package/src/toolkit/recent-structure.mjs +201 -0
  66. package/src/toolkit/results.mjs +2 -2
  67. package/src/toolkit/review-document.mjs +9 -4
  68. package/src/toolkit/review-embed-document.mjs +671 -0
  69. package/src/toolkit/review-filmstrip.mjs +76 -0
  70. package/src/toolkit/review-motion-card.mjs +51 -0
  71. package/src/toolkit/review-motion.mjs +159 -0
  72. package/src/toolkit/review-playback.js +123 -0
  73. package/src/toolkit/review-sheet.mjs +36 -28
  74. package/src/toolkit/review.mjs +131 -31
  75. package/src/toolkit/runtime.mjs +7 -1
  76. package/src/viewer-cache.mjs +48 -12
@@ -0,0 +1,300 @@
1
+ import path from 'node:path';
2
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
3
+ import { lexer } from 'css-tree';
4
+ import { CliError } from '../cli-output.mjs';
5
+ import { jsonLocations } from './json-locations.mjs';
6
+ import { portablePath } from './owner-locators.mjs';
7
+ import { motionFlows } from './motion-flows.mjs';
8
+ import { relative } from './project.mjs';
9
+ import { loadMotionPatterns, patternEdge } from './motion-patterns.mjs';
10
+ import { motionPrimitives } from './motion-primitives.mjs';
11
+
12
+ const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
13
+ const fields = (value, allowed) => object(value) && Object.keys(value).every((key) => allowed.includes(key));
14
+ const text = (value) => typeof value === 'string' && value.trim().length > 0;
15
+ export const edgeId = (value) => typeof value === 'string' && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value);
16
+ const frameRef = (value) =>
17
+ fields(value, ['source', 'frame']) && portablePath(value.source) && value.source.endsWith('.tsx') && text(value.frame);
18
+ const modes = ['match', 'enter', 'exit', 'crossfade'];
19
+ function target(value) {
20
+ if (fields(value, ['frame'])) return value.frame === true;
21
+ if (fields(value, ['anchor'])) return text(value.anchor);
22
+ if (!fields(value, ['part', 'key']) || !text(value.part)) return false;
23
+ const [source, part, ...extra] = value.part.split('#');
24
+ return (
25
+ !extra.length &&
26
+ portablePath(source) &&
27
+ source.endsWith('.tsx') &&
28
+ text(part) &&
29
+ (value.key === undefined || text(value.key) || Number.isFinite(value.key))
30
+ );
31
+ }
32
+
33
+ function validateShape(e, issue) {
34
+ if (
35
+ !fields(e, [
36
+ 'id',
37
+ 'label',
38
+ 'from',
39
+ 'to',
40
+ 'trigger',
41
+ 'duration',
42
+ 'easing',
43
+ 'phases',
44
+ 'interrupt',
45
+ 'reduced',
46
+ 'focus',
47
+ 'rememberTrigger',
48
+ 'proposed',
49
+ 'unsupported'
50
+ ])
51
+ )
52
+ issue('MOTION_SCHEMA', '', 'Use only version 1 edge fields.');
53
+ if (!object(e)) return;
54
+ if (!edgeId(e.id)) issue('MOTION_SCHEMA', '/id', 'Use a project-unique kebab-case ID.');
55
+ for (const side of ['from', 'to'])
56
+ if (!frameRef(e[side])) issue('MOTION_SCHEMA', '/' + side, 'Expected an exact project-relative TSX source and frame.');
57
+ if (e.label !== undefined && (!text(e.label) || /[\r\n\x00-\x1f]|<\/?[a-z][^>]*>/i.test(e.label)))
58
+ issue('MOTION_SCHEMA', '/label', 'Use a nonempty plain-text action name.');
59
+ const t = e.trigger;
60
+ if (
61
+ !fields(t, ['on', 'target', 'key', 'value']) ||
62
+ !['click', 'hover', 'focus', 'key', 'input'].includes(t.on) ||
63
+ !target(t.target) ||
64
+ (t.on === 'input' ? typeof t.value !== 'string' : t.value !== undefined) ||
65
+ (t.on === 'key' ? !(text(t.key) || t.key === ' ') : t.key !== undefined)
66
+ )
67
+ issue('MOTION_SCHEMA', '/trigger', 'Choose an input and a unique target; key takes a key and input takes an exact string value.');
68
+ if (e.interrupt !== 'finish') issue('MOTION_SCHEMA', '/interrupt', 'Version 1 requires finish.');
69
+ if (e.reduced !== 'instant') issue('MOTION_REDUCED_MISSING', '/reduced', 'Declare the instant fallback.');
70
+ if (
71
+ !['frame', 'preserve', 'restore-trigger'].includes(e.focus) &&
72
+ !(fields(e.focus, ['target']) && target(e.focus.target))
73
+ )
74
+ issue('MOTION_FOCUS', '/focus', 'Declare a focus outcome or one destination target.');
75
+ if (e.rememberTrigger !== undefined && ![true, 'replace'].includes(e.rememberTrigger))
76
+ issue('MOTION_SCHEMA', '/rememberTrigger', 'Use true or replace.');
77
+ if (e.proposed !== undefined && !text(e.proposed)) issue('MOTION_STATUS', '/proposed', 'Name an active review scope.');
78
+ if (
79
+ e.unsupported !== undefined &&
80
+ !(
81
+ Array.isArray(e.unsupported) &&
82
+ e.unsupported.length &&
83
+ e.unsupported.every((u) => fields(u, ['effect', 'reason']) && text(u.effect) && text(u.reason))
84
+ )
85
+ )
86
+ issue('MOTION_SCHEMA', '/unsupported', 'Name each unsupported effect and its reason.');
87
+ if (!Array.isArray(e.phases)) {
88
+ issue('MOTION_SCHEMA', '/phases', 'Declare a phase array.');
89
+ return;
90
+ }
91
+ e.phases.forEach((phase, i) => {
92
+ const at = '/phases/' + i;
93
+ if (!Array.isArray(phase) || !phase.length) {
94
+ issue('MOTION_SCHEMA', at, 'A phase needs tracks.');
95
+ return;
96
+ }
97
+ phase.forEach((track, j) => {
98
+ const p = at + '/' + j;
99
+ if (
100
+ !fields(track, ['targets', 'properties', 'mode', 'duration', 'easing', 'fromOpacity']) ||
101
+ !modes.includes(track.mode) ||
102
+ !Array.isArray(track.targets) ||
103
+ !track.targets.length ||
104
+ !track.targets.every(target)
105
+ ) {
106
+ issue('MOTION_SCHEMA', p, 'Invalid track mode, targets or fields.');
107
+ return;
108
+ }
109
+ if (
110
+ track.fromOpacity !== undefined &&
111
+ !(track.mode === 'enter' && Number.isFinite(track.fromOpacity) && track.fromOpacity >= 0 && track.fromOpacity <= 1)
112
+ )
113
+ issue('MOTION_SCHEMA', p + '/fromOpacity', 'Only enter accepts a starting opacity in [0,1].');
114
+ const props = track.properties,
115
+ allowed = track.mode === 'match' ? ['x', 'y', 'width', 'height', 'opacity'] : ['opacity'];
116
+ if (
117
+ !Array.isArray(props) ||
118
+ !props.length ||
119
+ props.some((prop) => !allowed.includes(prop)) ||
120
+ new Set(props).size !== props.length
121
+ )
122
+ issue('MOTION_TRACK_CONFLICT', p + '/properties', 'Select distinct properties supported by this track mode.');
123
+ });
124
+ });
125
+ }
126
+
127
+ export function motionFiles(config) {
128
+ function visit(dir) {
129
+ if (!existsSync(dir)) return [];
130
+ return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
131
+ if (entry.name.startsWith('.') || entry.name === 'node_modules') return [];
132
+ const file = path.join(dir, entry.name);
133
+ return entry.isDirectory() ? visit(file) : entry.isFile() && file.endsWith('.motion.json') ? [file] : [];
134
+ });
135
+ }
136
+ return visit(config.design).sort();
137
+ }
138
+
139
+ export function readMotion(config, files = motionFiles(config)) {
140
+ const records = [],
141
+ declarations = [],
142
+ findings = [],
143
+ ids = new Map();
144
+ let catalog;
145
+ for (const file of files) {
146
+ const source = relative(config, file),
147
+ owner = source.replace(/\.motion\.json$/, '.tsx');
148
+ let raw, doc;
149
+ try {
150
+ raw = readFileSync(file, 'utf8');
151
+ doc = JSON.parse(raw);
152
+ } catch (cause) {
153
+ throw new CliError('SOURCE_BUILD_FAILED', source + ': ' + cause.message, { cause });
154
+ }
155
+ if (object(doc) && Object.hasOwn(doc, 'version') && doc.version !== 1)
156
+ throw new CliError('SOURCE_BUILD_FAILED', source + ': unsupported motion version.');
157
+ const locations = jsonLocations(raw);
158
+ function issue(code, pointer, message, id) {
159
+ findings.push({
160
+ code,
161
+ source,
162
+ pointer,
163
+ message,
164
+ transition: id ?? null,
165
+ ...(locations[pointer] ?? locations['']),
166
+ frame: null,
167
+ theme: null
168
+ });
169
+ }
170
+ if (!fields(doc, ['version', 'edges', 'flows']) || doc.version !== 1 || !Array.isArray(doc.edges)) {
171
+ issue('MOTION_SCHEMA', '', 'Expected version 1 and an edges array.');
172
+ continue;
173
+ }
174
+ if (doc.flows !== undefined && !Array.isArray(doc.flows))
175
+ issue('MOTION_FLOW_SCHEMA', '/flows', 'Expected a flows array.');
176
+ for (const [index, declaration] of (Array.isArray(doc.flows) ? doc.flows : []).entries()) {
177
+ const pointer = '/flows/' + index;
178
+ if (!fields(declaration, ['start', 'anchor', 'stage', 'ends']) ||
179
+ !frameRef(declaration.start) || declaration.start.source !== owner ||
180
+ !target(declaration.anchor) || declaration.anchor.frame ||
181
+ (declaration.stage !== undefined && (!fields(declaration.stage, ['width', 'height']) ||
182
+ ![declaration.stage.width, declaration.stage.height].every((value) => Number.isFinite(value) && value > 0)))) {
183
+ issue('MOTION_FLOW_SCHEMA', pointer, 'Use a start frame in this sidecar’s source, a part or motion anchor, and optional positive stage dimensions.');
184
+ continue;
185
+ }
186
+ let ends;
187
+ if (declaration.ends !== undefined) {
188
+ if (!Array.isArray(declaration.ends) || declaration.ends.some(ref =>
189
+ !fields(ref, ['source', 'frame']) || !frameRef({ source: owner, ...ref }))) {
190
+ issue('MOTION_FLOW_SCHEMA', pointer + '/ends', 'Use an array of frame references. Omit source for frames in this sidecar’s source.');
191
+ continue;
192
+ }
193
+ ends = declaration.ends.map(ref => ({ source: owner, ...ref }));
194
+ }
195
+ declarations.push({ declaration: { ...declaration, ...(ends && { ends }) }, source, pointer, locations });
196
+ }
197
+ doc.edges.forEach((edge, index) => {
198
+ const pointer = '/edges/' + index,
199
+ problems = [];
200
+ const report = (code, suffix, message) => {
201
+ problems.push(code);
202
+ issue(code, pointer + suffix, message, edge?.id);
203
+ };
204
+ const pattern = edge?.pattern;
205
+ const resolved = pattern === undefined ? edge : patternEdge(edge, catalog ??= loadMotionPatterns(config), report);
206
+ if (!problems.length) validateShape(resolved, report);
207
+ const record = { source, owner, edge: resolved, pointer, locations, valid: problems.length === 0,
208
+ ...(pattern === undefined ? {} : { pattern }) };
209
+ records.push(record);
210
+ if (!edgeId(edge?.id)) return;
211
+ if (!ids.has(edge.id)) ids.set(edge.id, []);
212
+ ids.get(edge.id).push(record);
213
+ });
214
+ }
215
+ for (const group of ids.values())
216
+ if (group.length > 1)
217
+ for (const r of group) {
218
+ r.valid = false;
219
+ const pointer = r.pointer + '/id';
220
+ findings.push({
221
+ code: 'MOTION_ID_CONFLICT',
222
+ source: r.source,
223
+ pointer,
224
+ ...r.locations[pointer],
225
+ transition: r.edge.id,
226
+ frame: null,
227
+ theme: null,
228
+ message: 'Duplicate transition ID ' + r.edge.id
229
+ });
230
+ }
231
+ const { byFrame: flows, findings: flowFindings, deadEnds } = motionFlows(records.filter((r) => r.valid), declarations);
232
+ findings.push(...flowFindings);
233
+ return { records, findings, ids, declarations, flows, deadEnds, files: files.map((f) => relative(config, f)) };
234
+ }
235
+
236
+ const cssNumber = '[+-]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:[eE][+-]?\\d+)?';
237
+ const linearStop = new RegExp(
238
+ '^(?:' + cssNumber + '(?:\\s+' + cssNumber + '%){0,2}|(?:' + cssNumber + '%\\s+){1,2}' + cssNumber + ')$'
239
+ );
240
+ function validEasing(raw) {
241
+ // The bundled CSS grammar predates the piecewise linear() function.
242
+ const linear = /^linear\(([^()]*)\)$/i.exec(raw);
243
+ if (linear) {
244
+ const stops = linear[1].split(',').map((value) => value.trim());
245
+ return stops.length >= 2 && stops.every((stop) => linearStop.test(stop));
246
+ }
247
+ if (!lexer.matchType('easing-function', raw).matched) return false;
248
+ const steps = /^steps\(\s*(\d+)\s*(?:,\s*([\w-]+)\s*)?\)$/i.exec(raw);
249
+ return !steps || Number(steps[1]) >= (steps[2]?.toLowerCase() === 'jump-none' ? 2 : 1);
250
+ }
251
+
252
+ const expandedTokens = new WeakMap();
253
+ export function resolveMotionToken(tokens, theme, name, kind) {
254
+ if (typeof name === 'string' && /^(--adg-motion-|--motion-spring-)/.test(name)) {
255
+ if (!expandedTokens.has(tokens)) expandedTokens.set(tokens, motionPrimitives(tokens).tokens);
256
+ tokens = expandedTokens.get(tokens);
257
+ }
258
+ const names = [],
259
+ invalid = () => ({ names, value: null });
260
+ if (typeof name !== 'string' || !/^--[\w-]+$/.test(name)) return invalid();
261
+ let key = name;
262
+ while (!names.includes(key)) {
263
+ names.push(key);
264
+ const raw = (theme === 'dark' ? tokens.dark.get(key) : undefined) ?? tokens.light.get(key);
265
+ if (!raw) return invalid();
266
+ const alias = /^var\(\s*(--[\w-]+)\s*\)$/.exec(raw);
267
+ if (alias) {
268
+ key = alias[1];
269
+ continue;
270
+ }
271
+ if (kind === 'duration') {
272
+ const time = /^(\+?(?:\d+(?:\.\d+)?|\.\d+))(ms|s)$/i.exec(raw);
273
+ const ms = time ? Number(time[1]) * (time[2].toLowerCase() === 's' ? 1000 : 1) : NaN;
274
+ return Number.isFinite(ms) ? { names, value: ms } : invalid();
275
+ }
276
+ if (!validEasing(raw)) return invalid();
277
+ return { names, value: raw };
278
+ }
279
+ return invalid();
280
+ }
281
+
282
+ export function timingRefs(edge) {
283
+ const refs = [{ pointer: '', scope: edge }];
284
+ edge.phases.forEach((phase, i) => phase.forEach((scope, j) => refs.push({ pointer: '/phases/' + i + '/' + j, scope })));
285
+ return refs.flatMap(({ pointer, scope }) =>
286
+ ['duration', 'easing']
287
+ .filter((kind) => !pointer || Object.hasOwn(scope, kind))
288
+ .map((kind) => ({ pointer: pointer + '/' + kind, kind, name: scope[kind] }))
289
+ );
290
+ }
291
+
292
+ export function motionSummary(data, rows, expanded = false) {
293
+ if (rows.length || expanded) data.motion = { count: rows.length, ...(expanded ? { edges: rows } : {}) };
294
+ }
295
+
296
+ export function motionRows(records) {
297
+ return [...new Map(records.filter((r) => edgeId(r.edge?.id)).map((r) => [r.edge.id, r])).values()].sort((a, b) =>
298
+ a.edge.id.localeCompare(b.edge.id, 'en')
299
+ );
300
+ }
@@ -1,3 +1,4 @@
1
+ import { boundEdges, tokenEdges, transitionQuery } from './motion-queries.mjs';
1
2
  import { readFile } from 'node:fs/promises';
2
3
  import path from 'node:path';
3
4
  import { CliError, nextActions } from '../cli-output.mjs';
@@ -49,15 +50,24 @@ async function ownerPart(config, values, { log = console.log } = {}) {
49
50
  for (const implementation of implementations) row.evidence.push({ matchKind: 'mapping_part', frame: null, theme: null, elementPath: null, boxes: [], owners: [], detail: { kind: 'mapping', file: map.source, pointer: binding.pointer, implementation: implementation.file, selector, symbol: selector.symbol ?? null, region: implementation.region } });
50
51
  data.owners.push(row);
51
52
  }
53
+ await boundEdges(config,validated.transitionBindings,data,values.transitions);
52
54
  data.complete = true;
53
- if (!data.owners.length) warnings.push({ code: 'OWNER_NO_MATCH', message: 'No implementation binding matched the requested design part.', next: [] });
55
+ if (!data.owners.length && !data.motion?.count) warnings.push({ code: 'OWNER_NO_MATCH', message: 'No implementation binding matched the requested design part.', next: [] });
54
56
  if (!values.json) for (const row of data.owners) log(`${row.source}${row.part ? `#${row.part}` : ''} [${row.matchKind}] ${row.evidence.map(e => e.detail.implementation).join(', ')}`);
55
57
  return { data, warnings };
56
58
  }
57
59
 
58
60
  export async function owner(config, values, { log = console.log, openIndex = openProjectIndex, launchBrowser = launch, environment = observationEnvironment } = {}) {
61
+ if (values.transition !== undefined) return transitionQuery(config,'owner',[],values,log);
59
62
  if (values.part !== undefined) return ownerPart(config, values, { log });
60
- if (values.file === undefined) return (await import('./owner-search.mjs')).searchOwner(config, values, { log, openIndex, launchBrowser, environment });
63
+ if (values.file === undefined) {
64
+ const result=await (await import('./owner-search.mjs')).searchOwner(config, values, { log, openIndex, launchBrowser, environment });
65
+ if(values.token!==undefined){
66
+ await tokenEdges(config,values,result.data);
67
+ if(result.data.motion?.count)result.warnings=result.warnings.filter(w=>w.code!=='OWNER_NO_MATCH');
68
+ }
69
+ return result;
70
+ }
61
71
  const { query, text } = await normalizeFileQuery(config, values);
62
72
  const data = { project: config.root, complete: false, query, region: null, owners: [], tokens: [], ambiguous: false, tokenAmbiguous: false, matchedImplementationFiles: [], mappingFindings: [],
63
73
  coverage: { discoveredSources: 0, builtSources: 0, requestedObservations: 0, completedObservations: 0, mappingState: 'absent', activeBindings: 0, excludedBindings: 0, domain: 'tsx' } };
@@ -79,11 +89,14 @@ export async function owner(config, values, { log = console.log, openIndex = ope
79
89
  const validated = await index.mappings({ map, mappingIndices, implementationSelection: files, onFinding: finding => { data.mappingFindings.push(finding); data.coverage.mappingState = 'stale'; } });
80
90
  data.mappingFindings = validated.findings;
81
91
  data.coverage.mappingState = !map.present ? 'absent' : validated.findings.length ? 'stale' : 'valid';
92
+ await boundEdges(config,validated.transitionBindings,data,values.transitions);
82
93
  const active = validated.bindings.filter(binding => binding.active);
83
- data.coverage.activeBindings = active.length; data.coverage.excludedBindings = validated.bindings.length - active.length;
94
+ const allBindings = [...validated.bindings, ...validated.transitionBindings];
95
+ const activeBindings = allBindings.filter(binding => binding.active);
96
+ data.coverage.activeBindings = activeBindings.length; data.coverage.excludedBindings = allBindings.length - activeBindings.length;
84
97
  if (!map.present) warn('OWNER_MAPPING_MISSING', 'Add implementation.json to declare implementation ownership, then validate it.');
85
98
  if (validated.findings.length) warn('OWNER_MAPPING_STALE', 'Repair the reported implementation mapping findings, then repeat the query.');
86
- if ((query.line !== null || query.symbol !== null) && !active.some(binding => binding.implementation.symbol)) warn('OWNER_LOCATOR_UNMAPPED', 'Add or refine a symbol/anchor binding for this implementation region, then repeat the query.', true);
99
+ if ((query.line !== null || query.symbol !== null) && !activeBindings.some(binding => binding.implementation.symbol)) warn('OWNER_LOCATOR_UNMAPPED', 'Add or refine a symbol/anchor binding for this implementation region, then repeat the query.', true);
87
100
  const tasks = new Map();
88
101
  for (const binding of active) {
89
102
  const target = binding.design, key = JSON.stringify([target.source, target.part ?? null]), kind = bindingKind(binding.implementation, query), rank = fileRank(binding.implementation, kind);
@@ -175,11 +188,11 @@ export async function owner(config, values, { log = console.log, openIndex = ope
175
188
  data.tokens.sort((a, b) => compareNames(a.name, b.name));
176
189
  data.ambiguous = data.owners.length > 1 && compareRanks(data.owners[0].rank, data.owners[1].rank) === 0;
177
190
  if (data.ambiguous) warn('OWNER_AMBIGUOUS', 'Several owners share the best rank; narrow the file locator, text or theme before choosing an owner.', true);
178
- if (!data.owners.length && !data.tokens.length) warn('OWNER_NO_MATCH', 'No ownership evidence matched. Validate current sources and add or refine an implementation mapping.');
191
+ if (!data.owners.length && !data.tokens.length && !data.motion?.count) warn('OWNER_NO_MATCH', 'No ownership evidence matched. Validate current sources and add or refine an implementation mapping.');
179
192
  if (!data.coverage.discoveredSources) warnings.push({ code: 'EMPTY_SELECTION', message: 'No TSX design sources were discovered.', next: [] });
180
193
  data.complete = true;
181
194
  if (!values.json) {
182
- if (!data.owners.length) log('No ownership evidence matched.');
195
+ if (!data.owners.length && !data.motion?.count) log('No ownership evidence matched.');
183
196
  if (data.ambiguous) log('Multiple owners share the best rank.');
184
197
  for (const row of data.owners) log(`${row.source}${row.part ? `#${row.part}` : ''} [${row.matchKind}] ${[...new Set(row.frames.map(frame => frame.frame))].join(', ')}${row.tokens.length ? `; tokens: ${row.tokens.join(', ')}` : ''}`);
185
198
  for (const warning of warnings) log(`${warning.code}: ${warning.message}`);
@@ -0,0 +1,66 @@
1
+ import { edgePresentation } from './motion-label.mjs';
2
+ import path from 'node:path';
3
+ import { existsSync } from 'node:fs';
4
+ import { frameKey, motionFlows } from './motion-flows.mjs';
5
+ import { readMotion, resolveMotionToken, timingRefs } from './motion.mjs';
6
+ import { relative, loadTokens } from './project.mjs';
7
+ import { CliError } from '../cli-output.mjs';
8
+
9
+ // The server has already resolved the requested name against its current TSX inventory.
10
+ export function sourceMotion(config, root, source) {
11
+ const owner = relative(config, path.join(root, source));
12
+ const sidecar = path.join(root, source.replace(/\.tsx$/, '.motion.json'));
13
+ const graph = readMotion(config, existsSync(sidecar) ? [sidecar] : []);
14
+ return {
15
+ records: graph.records.filter(r => r.valid && r.edge.from.source === owner),
16
+ declarations: graph.declarations
17
+ };
18
+ }
19
+ export function playbackGraph(config, root, owners, inventory) {
20
+ const records = [], declarations = [];
21
+ for (const source of [...owners.keys()].sort()) {
22
+ const indexed = owners.get(source);
23
+ if (indexed.error) continue;
24
+ try {
25
+ indexed.motion ??= sourceMotion(config, root, source);
26
+ records.push(...indexed.motion.records);
27
+ declarations.push(...indexed.motion.declarations);
28
+ } catch (error) {
29
+ indexed.error = error;
30
+ }
31
+ }
32
+ const design = relative(config, root);
33
+ const prefix = design ? design + '/' : '';
34
+ const available = (ref) => ref.source.startsWith(prefix) && inventory.has(ref.source.slice(prefix.length));
35
+ const playable = records.filter(({ edge }) => available(edge.from) && available(edge.to));
36
+ return { records, flows: motionFlows(playable, declarations).byFrame };
37
+ }
38
+
39
+ export async function playEndpoint(config, root, source, frame, theme, build, graph) {
40
+ const ref = { source: relative(config, path.join(root, source)), frame };
41
+ const records = graph.records.filter(r => r.edge.from.source === ref.source && r.edge.from.frame === frame);
42
+ const built = await build(source),
43
+ endpoint = built.frames.find((f) => f.name === frame);
44
+ if (!endpoint) throw new CliError('FRAME_NOT_FOUND', 'Unknown playback frame.');
45
+ const tokens = loadTokens(config),
46
+ design = relative(config, root);
47
+ const edges = records.map(({ edge }) => playbackEdge(edge, endpoint, tokens, theme, design));
48
+ return {
49
+ design,
50
+ source,
51
+ frame,
52
+ html: endpoint.html,
53
+ css: built.css,
54
+ width: endpoint.width,
55
+ height: endpoint.height,
56
+ edges,
57
+ flow: graph.flows.get(frameKey(ref)) ?? null
58
+ };
59
+ }
60
+
61
+ export function playbackEdge(edge, endpoint, tokens, theme, design) {
62
+ const timings = Object.fromEntries(timingRefs(edge).map(({ pointer, name, kind }) =>
63
+ [pointer, resolveMotionToken(tokens, theme, name, kind).value]));
64
+ if (Object.values(timings).includes(null)) throw Error('Unresolved timing on ' + edge.id + '. Run adg check.');
65
+ return { ...edge, ...edgePresentation(edge, endpoint.html, design), authoredLabel: !!edge.label, timings };
66
+ }
@@ -47,7 +47,7 @@ async function resolutionFiles(config, artifactDirectory) {
47
47
  return files.sort();
48
48
  }
49
49
 
50
- export async function openProjectIndex(config, { stateDirectory = defaultStateDirectory, persist = true, fresh = false, artifactDirectory } = {}) {
50
+ export async function openProjectIndex(config, { stateDirectory = defaultStateDirectory, persist = true, fresh = false, frameOrigins = false, artifactDirectory } = {}) {
51
51
  const inventory = discoverProject(config), root = await realpath(config.root), buildPromises = new Map();
52
52
  const directory = path.join(stateDirectory, 'cache', indexDigest(root), 'index-v1');
53
53
  const shards = await createIndexStore({ directory, persist });
@@ -91,7 +91,7 @@ export async function openProjectIndex(config, { stateDirectory = defaultStateDi
91
91
  if (!materializations.has(source)) {
92
92
  requestedSources.add(source); freshPool ??= new BuildPool();
93
93
  materializations.set(source, freshPool.run({ config: { root, design: physicalDesign ?? config.design, output: config.output,
94
- sources: config.sources, arch: config.arch, check: config.check, allowLegacy: false },
94
+ sources: config.sources, arch: config.arch, check: config.check, allowLegacy: false, frameOrigins },
95
95
  name: path.relative(physicalDesign ?? config.design, path.join(root, source)).split(path.sep).join('/') }, new AbortController().signal).then(built => {
96
96
  observeDependencies(built);
97
97
  for (const frame of built.frames) frame.document = theme => frameDocument(frame, theme, built.css);
@@ -0,0 +1,201 @@
1
+ import { declarations } from './frame-declarations.mjs';
2
+ import path from 'node:path';
3
+ import { liveDependencies } from './input-generation.mjs';
4
+ import { readFile } from 'node:fs/promises';
5
+ import { prepareImpactInputs } from './impact-inputs.mjs';
6
+ import { canonicalBytes } from './impact-proof.mjs';
7
+ import { impact } from './impact.mjs';
8
+ import { openProjectIndex } from './project-index.mjs';
9
+ import { readGroups, relative, sourceFeature } from './project.mjs';
10
+
11
+ function inventoryMoves(rows, renames, complete) {
12
+ const removed = rows.filter((r) => r.status === 'removed'),
13
+ added = rows.filter((r) => r.status === 'added');
14
+ const paired = new Map(),
15
+ consumed = new Set();
16
+ // Git source rename plus stable frame name wins even when several sources use that name.
17
+ // Otherwise a name must occur only once in each complete endpoint inventory.
18
+ const afterById = new Map(added.map((r) => [JSON.stringify([r.source, r.frame]), r]));
19
+ for (const old of removed) {
20
+ const next = afterById.get(JSON.stringify([renames.get(old.source), old.frame]));
21
+ if (next) {
22
+ paired.set(next, old);
23
+ consumed.add(old);
24
+ }
25
+ }
26
+ if (!complete) return { paired, consumed };
27
+ const before = new Map(),
28
+ after = new Map();
29
+ for (const row of rows) {
30
+ if (row.before) before.set(row.frame, before.has(row.frame) ? null : row);
31
+ if (row.after) after.set(row.frame, after.has(row.frame) ? null : row);
32
+ }
33
+ for (const old of removed) {
34
+ const next = after.get(old.frame);
35
+ if (!consumed.has(old) && before.get(old.frame) === old && next?.status === 'added' && !paired.has(next)) {
36
+ paired.set(next, old);
37
+ consumed.add(old);
38
+ }
39
+ }
40
+ return { paired, consumed };
41
+ }
42
+
43
+ export async function structuralChanges(config, options) {
44
+ const started = performance.now();
45
+ const inputs = await prepareImpactInputs(config, options);
46
+ // An immutable documentation-only range outside both design and architecture trees
47
+ // has identical source inputs. Config imports and the effective capture policy still count.
48
+ const endpoints = [inputs.session.before, inputs.session.after];
49
+ const policy = ({ config: c }) =>
50
+ canonicalBytes({
51
+ sources: c.sources,
52
+ design: relative(c, c.design),
53
+ arch: c.arch && relative(c, c.arch),
54
+ check: c.check,
55
+ diff: c.diff
56
+ });
57
+ if (
58
+ options.head &&
59
+ !inputs.session.globalChanges.length &&
60
+ policy(endpoints[0]) === policy(endpoints[1]) &&
61
+ inputs.session.changes
62
+ .flatMap((c) => [c.before, c.after])
63
+ .filter(Boolean)
64
+ .every(
65
+ (file) =>
66
+ /\.(md|txt)$/i.test(file) &&
67
+ endpoints.every(
68
+ ({ config: c, sources }) =>
69
+ !sources.has(file) &&
70
+ !file.startsWith(relative(c, c.design) + '/') &&
71
+ !(c.arch && file.startsWith(relative(c, c.arch) + '/'))
72
+ )
73
+ )
74
+ ) {
75
+ await inputs.close();
76
+ return {
77
+ rows: [],
78
+ globalCauses: [],
79
+ dependencies: [],
80
+ failures: [],
81
+ complete: true,
82
+ timings: { prepareMs: performance.now() - started }
83
+ };
84
+ }
85
+ let projection;
86
+ const { data } = await impact(
87
+ config,
88
+ { ...options, json: true },
89
+ {
90
+ prepareInputs: async () => inputs,
91
+ tolerateSourceFailures: true,
92
+ openIndex: (config, opts) => openProjectIndex(config, { ...opts, frameOrigins: true }),
93
+ async consume({ views, rows, data, assessments, inputs }) {
94
+ const facts = new Map(data.facts.map((f) => [f.id, f]));
95
+ const globalCauses = [
96
+ ...new Set(
97
+ data.changes.filter((c) => ['config', 'environment'].includes(c.role)).map((c) => c.after ?? c.before)
98
+ )
99
+ ].sort();
100
+ const changed = new Set(
101
+ data.facts.filter((f) => ['source', 'architecture'].includes(f.kind)).map((f) => f.source)
102
+ );
103
+ const sides = await Promise.all(
104
+ views.map(async (view) => {
105
+ const { config } = view,
106
+ code = new Map(),
107
+ chapters = new Map();
108
+ for (const group of readGroups(config.design, config.sources))
109
+ for (const file of group.assets)
110
+ chapters.set(relative(config, path.join(config.design, file)), group.title);
111
+ for (const file of changed) {
112
+ if (!file?.endsWith('.tsx') || !view.index.inventory.tsx.includes(file)) continue;
113
+ if (data.failures.some((f) => f.source === file)) continue;
114
+ code.set(file, declarations(await readFile(path.join(config.root, file), 'utf8')));
115
+ }
116
+ const frames = new Map();
117
+ for (const [source, built] of view.built)
118
+ frames.set(source, new Map(built.frames.map((f) => [f.name, f])));
119
+ const feature = (file) =>
120
+ sourceFeature(path.posix.relative(relative(config, config.design), file), config.sources);
121
+ return { code, chapters, frames, feature };
122
+ })
123
+ );
124
+ const result = [];
125
+ const renames = new Map(inputs.session.renames.map((r) => [r.before, r.after]));
126
+ const { paired, consumed } = inventoryMoves(rows, renames, !data.failures.length);
127
+ const changedPaths = new Set(inputs.session.changes.flatMap((c) => [c.before, c.after]));
128
+ for (const row of rows) {
129
+ if (consumed.has(row)) continue;
130
+ const { source, frame } = row,
131
+ entry = { source, frame, status: row.status };
132
+ const chapter = sides[row.after ? 1 : 0].chapters.get(source);
133
+ if (chapter) entry.chapter = chapter;
134
+ if (row.status !== 'matched') {
135
+ const old = paired.get(row);
136
+ if (old) Object.assign(entry, { status: 'moved', former: { source: old.source, frame: old.frame } });
137
+ result.push(entry);
138
+ continue;
139
+ }
140
+ const causes = new Set();
141
+ const inputsChanged = ['light', 'dark']
142
+ .map((t) => assessments.get(JSON.stringify([source, frame, t])))
143
+ .filter((a) => a && a.disposition !== 'proven_unaffected');
144
+ for (const assessment of inputsChanged)
145
+ for (const reason of assessment.reasons) {
146
+ const fact = facts.get(reason.fact);
147
+ if (!fact?.source || reason.scope === 'support') continue;
148
+ if (
149
+ fact.source !== source &&
150
+ ['token', 'source', 'global_css'].includes(fact.kind) &&
151
+ (fact.kind !== 'global_css' ||
152
+ views.some((v) => v.facts.get(source)?.dependencies.includes(fact.source)))
153
+ )
154
+ causes.add(fact.source);
155
+ if (fact.kind === 'architecture')
156
+ for (const i of fact.pathIndexes) {
157
+ const file = path.posix.relative(
158
+ inputs.projectPrefix || '.',
159
+ data.changes[i].after ?? data.changes[i].before
160
+ );
161
+ if (file !== source) causes.add(file);
162
+ }
163
+ }
164
+ const [old, current] = sides.map((s) => s.frames.get(source)?.get(frame));
165
+ const fragments = sides.map((side, i) => {
166
+ const declared = i ? current : old,
167
+ loc = declared?.declaration;
168
+ return loc && side.code.get(loc.source)?.site(loc);
169
+ });
170
+ let direct = fragments[0] !== fragments[1];
171
+ const owners = [...(row.before.parts ?? []), ...(row.after.parts ?? [])];
172
+ for (const { source: file, part } of owners) {
173
+ if (!changed.has(file)) continue;
174
+ if (sides[0].code.get(file)?.part(part) === sides[1].code.get(file)?.part(part)) continue;
175
+ if (sides[1].feature(file) === sides[1].feature(source)) direct = true;
176
+ }
177
+ // Generated values or a local unexported helper can change the individual
178
+ // frame while the JSX at its call site stays the same. Ignore sheet-wide CSS.
179
+ const ownChanged = changedPaths.has(source);
180
+ if (ownChanged && !causes.size && (source.endsWith('.mmd') || localFrame(old) !== localFrame(current)))
181
+ direct = true;
182
+ if (!direct && !causes.size) continue;
183
+ result.push({ ...entry, status: 'changed', ...(!direct ? { causes: [...causes].sort() } : {}) });
184
+ }
185
+ projection = {
186
+ rows: result,
187
+ globalCauses,
188
+ complete: !data.failures.length,
189
+ failures: data.failures,
190
+ dependencies: await liveDependencies(views, options.temporaryDirectory)
191
+ };
192
+ }
193
+ }
194
+ );
195
+ return { ...projection, timings: { ...data.timings, totalMs: performance.now() - started } };
196
+ }
197
+ function localFrame(frame) {
198
+ if (!frame) return '';
199
+ const { declaration, document, ...props } = frame;
200
+ return JSON.stringify(props);
201
+ }
@@ -3,10 +3,10 @@ import { CliError, classifyError } from '../cli-output.mjs';
3
3
  /** @typedef {'light' | 'dark'} Theme */
4
4
  /** @typedef {{source: string | null, frame: string | null, theme: Theme | null, line: number | null, column: number | null}} Location */
5
5
  /** @typedef {Location & {code: string, message: string}} Finding */
6
- /** @typedef {{project: string, readOnly: boolean, complete: boolean, impact: object | null, sources: string[], summary: {sources: number, frames: number, evaluations: number, problems: number}, findings: Finding[]}} CheckData */
6
+ /** @typedef {{project: string, readOnly: boolean, complete: boolean, impact: object | null, sources: string[], summary: {sources: number, frames: number, evaluations: number, problems: number}, findings: Finding[], motionPatterns?: {animations: number, unmapped: number, unused: number, findings: number, omitted: number}}} CheckData */
7
7
  /** @typedef {{source: string, frame: string, theme: Theme, path: string, scale: number, width: number, height: number, pixelWidth: number, pixelHeight: number}} Capture */
8
8
  /** @typedef {{project: string, outputDirectory: string, complete: boolean, impact: object | null, base: {rev: string, sha: string} | null, themes: Theme[], captures: Capture[], deleted: string[]}} RenderData */
9
- /** @typedef {{source: string, frame: string, fixture: string, theme: Theme, settled: boolean, size: {design: [number, number], implementation: [number, number]}, matched: number, offBy2px: {text: string, dx: number, dy: number, dw: number, off: number}[], missing: string[], extra: string[], paths: {design: string, implementation: string, overlay: string, report: string, html: string}}} Comparison */
9
+ /** @typedef {{source: string, frame: string, fixture: string, theme: Theme, settled: boolean, size: {design: [number, number], implementation: [number, number]}, matched: number, offBy2px: {text: string, dx: number, dy: number, dw: number, off: number}[], missing: string[], extra: string[], paths: {design?: string, implementation?: string, overlay?: string, report: string, html: string}}} Comparison */
10
10
  /** @typedef {{project: string, complete: boolean, all: boolean, comparisons: Comparison[], skipped: {source: string, frame: string, reason: 'no_fixture'}[], summary: {frames: number, matched: number, offsets: number, missing: number, extra: number}, indexPath: string | null, summaryPath: string | null}} CompareData */
11
11
 
12
12
  /**