@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
@@ -1,3 +1,5 @@
1
+ import { motionFiles, readMotion, motionSummary } from './motion.mjs';
2
+ import { impactedEdges } from './motion-impact.mjs';
1
3
  import path from 'node:path';
2
4
  import { readFile, realpath, stat } from 'node:fs/promises';
3
5
  import { CliError, nextActions } from '../cli-output.mjs';
@@ -51,7 +53,11 @@ export async function impact(config, values, { log = console.log, openIndex = op
51
53
  async function track(file) { if (!tracked.has(file)) tracked.set(file, trackedHash(await bytes(file))); }
52
54
  const warn = (code, message, next = []) => { if (!warnings.some(warning => warning.code === code)) warnings.push({ code, message, next }); };
53
55
  const checkNext = reason => [{ argv: ['adg', 'check', '--read-only', '--json'], reason }];
54
- const verifyGeneration=()=>verifyInputGeneration({tracked,views,inputs});
56
+ const verifyGeneration=async()=>{
57
+ await verifyInputGeneration({tracked,views,inputs});
58
+ for(const v of views)if(v.motion && JSON.stringify(v.motion.files)!==JSON.stringify(motionFiles(v.config).map(f=>relative(v.config,f))))
59
+ throw new CliError('IMPACT_INPUT_CHANGED','Motion sidecar inventory changed during query.');
60
+ };
55
61
 
56
62
  try {
57
63
  let query, fileInput;
@@ -85,6 +91,10 @@ export async function impact(config, values, { log = console.log, openIndex = op
85
91
  views.push(view);
86
92
  for (const file of await configInputFiles(current)) { await track(file); view.configInputs.add(slash(path.relative(await realpath(current.root), file))); }
87
93
  for (const name of ['adg.config.mjs', 'adg.config.js', 'adg.config.ts']) await track(path.join(current.root, name));
94
+ const sidecars=motionFiles(current);
95
+ for(const file of sidecars)await track(file);
96
+ view.motion=readMotion(current,sidecars);
97
+ view.motionBindingHits=new Set();
88
98
  view.tokenFile = path.join(current.design, 'tokens.css');
89
99
  await track(view.tokenFile); view.tokenBytes = await bytes(view.tokenFile);
90
100
  if (inputs) for (const source of index.inventory.tsx) await track(path.join(current.root, source));
@@ -194,6 +204,7 @@ export async function impact(config, values, { log = console.log, openIndex = op
194
204
  if (contents === null || indexDigest(contents) !== hash || tracked.has(name) && tracked.get(name) !== fingerprint) throw new CliError('IMPACT_INPUT_CHANGED', `Implementation input changed during query: ${name}.`);
195
205
  tracked.set(name, fingerprint);
196
206
  }
207
+ for(const binding of validated.transitionBindings??[])if(binding.active && (query.kind==='file' || pathIndexes.some(i=>data.changes[i].role==='implementation')))view.motionBindingHits.add(binding.design.transition);
197
208
  for (const binding of validated.bindings) {
198
209
  const target = binding.design, facts = view.facts.get(target.source);
199
210
  if (!facts) continue;
@@ -355,13 +366,16 @@ export async function impact(config, values, { log = console.log, openIndex = op
355
366
  timings.queryMs = Math.max(0, timings.queryMs - (timings.proofMs - proofBeforeQuery));
356
367
  data.coverage.inventory = data.failures.length ? 'incomplete' : 'complete';
357
368
  if (data.unresolvedInputs.length || data.mappingFindings.length) warn('IMPACT_MAPPING_INCOMPLETE', 'Some implementation mappings are absent, unmatched or stale; inspect the resolvable targets and findings.', checkNext('Repair implementation.json and its reported locators before repeating the query.'));
358
- if (!data.frames.length) {
369
+ for(const view of views)view.motionTokenHits=seeds.filter(s=>s.view===view && s.fact.kind==='token').map(s=>s.fact);
370
+ const motion=await impactedEdges(views,query,themes,assessments,values.explain,values.transitions);
371
+ motionSummary(data,motion,values.transitions);
372
+ if (!data.frames.length && !motion.length) {
359
373
  const observed = query.kind === 'token' ? { token: query.tokens[0], theme: values.theme } : query.kind === 'file' ? { file: query.input, theme: values.theme } : null;
360
374
  warn(query.kind === 'git' ? 'IMPACT_NO_CHANGES' : 'IMPACT_NO_MATCH', 'No frame candidates matched the changed design facts.',
361
375
  query.kind === 'git' ? [] : observed ? nextActions('OWNER_UNSETTLED', { command: 'owner', values: observed }) : checkNext('Inspect design inputs and emitted part coverage.'));
362
376
  }
363
377
 
364
- if (consume) await consume({ views, rows, assessments, inputs, data });
378
+ if (consume) await consume({ views, rows, assessments, inputs, data, motionIds:new Set(motion.map(r=>r.id)) });
365
379
  } catch (cause) {
366
380
  if (inputs) { try { await verifyGeneration(); } catch (changed) { cause = changed; } }
367
381
  if (cause.code === 'OWNER_INDEX_CHANGED') cause = new CliError('IMPACT_INPUT_CHANGED', cause.message, { cause });
@@ -4,6 +4,7 @@ import { CliError } from '../cli-output.mjs';
4
4
  import { portablePath, globPattern, resolveLocator, symbolRegions, selectorMatches } from './owner-locators.mjs';
5
5
  import { indexDigest } from './index-store.mjs';
6
6
  import { mappingFacts } from './source-facts.mjs';
7
+ import { readMotion, edgeId } from './motion.mjs';
7
8
  import { jsonLocations } from './json-locations.mjs';
8
9
 
9
10
  const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -17,7 +18,7 @@ const invalid = message => { throw new CliError('OWNER_MAP_INVALID', message); }
17
18
  export function parseImplementationMap(text) {
18
19
  let value;
19
20
  try { value = JSON.parse(text); } catch { invalid('Invalid implementation.json JSON; repair the mapping file.'); }
20
- if (!keys(value, ['version', 'mappings']) || value.version !== 1 || !Array.isArray(value.mappings)) invalid('implementation.json needs version 1 and a mappings array.');
21
+ if (!keys(value, ['version', 'mappings']) || ![1,2].includes(value.version) || !Array.isArray(value.mappings)) invalid('implementation.json needs version 1 or 2 and a mappings array.');
21
22
  value.mappings.forEach((mapping, index) => {
22
23
  const pointer = `/mappings/${index}`, fail = reason => invalid(`${pointer}: ${reason}`);
23
24
  if (!keys(mapping, ['implementation', 'design']) || !Array.isArray(mapping.design) || !mapping.design.length) fail('use an implementation selector and nonempty design bindings.');
@@ -29,6 +30,7 @@ export function parseImplementationMap(text) {
29
30
  if (s.anchor !== undefined && (!nonempty(s.anchor) || !s.symbol)) fail('a nonempty anchor requires a symbol.');
30
31
  if (s.symbol && !/\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(s.file) && s.anchor === undefined) fail('this file type requires an explicit symbol anchor.');
31
32
  for (const target of mapping.design) {
33
+ if (value.version===2 && keys(target,['source','transition']) && portablePath(target.source) && target.source.endsWith('.tsx') && edgeId(target.transition)) continue;
32
34
  if (!keys(target, ['source', 'part', 'frames']) || !portablePath(target.source) || !target.source.endsWith('.tsx') ||
33
35
  target.part !== undefined && !nonempty(target.part) || target.frames !== undefined && (!Array.isArray(target.frames) || !target.frames.length || target.frames.some(frame => !nonempty(frame)))) fail('use a TSX source, optional part and nonempty exact frame list.');
34
36
  }
@@ -81,7 +83,9 @@ export async function implementationFiles(config, selector) {
81
83
  return files.sort();
82
84
  }
83
85
 
84
- export async function validateImplementationMap(config, map, { sources, selected, getBuild, onFinding = () => {}, mappingIndices, implementationSelection }) {
86
+ export async function validateImplementationMap(config, map, { sources, selected, getBuild, onFinding = () => {}, mappingIndices, implementationSelection, targetFilter }) {
87
+ let motion;
88
+ const transitionBindings = [];
85
89
  const findings = [], bindings = [], regions = {}, seen = new Set(), builds = new Map(), contents = new Map();
86
90
  const sourceSet = new Set(sources), scope = selected && new Set(selected);
87
91
  const report = (code, pointer, selector, target, message, candidates = [], frame = null) => {
@@ -91,7 +95,7 @@ export async function validateImplementationMap(config, map, { sources, selected
91
95
  };
92
96
  for (const [index, mapping] of map.mappings.entries()) {
93
97
  if (mappingIndices && !mappingIndices.has(index)) continue;
94
- const targets = mapping.design.map((target, i) => ({ target, pointer: `/mappings/${index}/design/${i}` })).filter(({ target }) => !scope || scope.has(target.source));
98
+ const targets = mapping.design.map((target, i) => ({ target, pointer: `/mappings/${index}/design/${i}` })).filter(({ target }) => (!scope || scope.has(target.source)) && (!targetFilter || targetFilter(target)));
95
99
  if (!targets.length) continue;
96
100
  const selector = mapping.implementation, pointer = `/mappings/${index}/implementation`;
97
101
  const files = implementationSelection ? implementationSelection.filter(file => selectorMatches(selector, file)) : await implementationFiles(config, selector);
@@ -105,10 +109,17 @@ export async function validateImplementationMap(config, map, { sources, selected
105
109
  }
106
110
  for (const { target, pointer: targetPointer } of targets) {
107
111
  let valid = files.length > 0 && !locator.stale, frames = [];
108
- const duplicate = JSON.stringify([Object.fromEntries(Object.entries(selector).sort()), { source: target.source, part: target.part ?? null, frames: target.frames ? [...target.frames].sort() : null }]);
112
+ const duplicate = JSON.stringify([Object.fromEntries(Object.entries(selector).sort()), { source: target.source, part: target.part ?? null, transition: target.transition ?? null, frames: target.frames ? [...target.frames].sort() : null }]);
109
113
  if (seen.has(duplicate)) { report('OWNER_MAPPING_DUPLICATE', targetPointer, selector, target, 'Duplicate implementation/design binding.'); continue; }
110
114
  seen.add(duplicate);
111
115
  if (!sourceSet.has(target.source)) { report('OWNER_SOURCE_MISSING', targetPointer, selector, target, `Undiscovered source ${target.source}.`); valid = false; }
116
+ else if (target.transition) {
117
+ motion ??= readMotion(config);
118
+ const matches = motion.ids.get(target.transition) ?? [];
119
+ if (matches.length !== 1 || matches[0].owner !== target.source || !matches[0].valid) {
120
+ report('MOTION_BINDING', targetPointer, selector, target, 'Binding needs a unique transition in its owning source.'); valid=false;
121
+ }
122
+ }
112
123
  else if (!implementationSelection || valid) {
113
124
  if (!builds.has(target.source)) builds.set(target.source, Promise.resolve(getBuild(target.source)).then(mappingFacts));
114
125
  const built = await builds.get(target.source);
@@ -121,9 +132,9 @@ export async function validateImplementationMap(config, map, { sources, selected
121
132
  frames = frames.filter(matches);
122
133
  }
123
134
  }
124
- bindings.push({ pointer: targetPointer, implementation: selector, design: target, files, anchorLine: locator.line, frames: frames.map(frame => frame.name), active: valid });
135
+ (target.transition ? transitionBindings : bindings).push({ pointer: targetPointer, implementation: selector, design: target, files, anchorLine: locator.line, frames: frames.map(frame => frame.name), active: valid });
125
136
  }
126
137
  }
127
138
  for (const [file, text] of contents) regions[file] = symbolRegions(text, file, map.mappings.map(m => m.implementation).filter(s => s.file === file));
128
- return { findings, bindings, regions, implementationHashes: Object.fromEntries([...contents].map(([file, text]) => [file, indexDigest(text)])) };
139
+ return { findings, bindings, transitionBindings, regions, implementationHashes: Object.fromEntries([...contents].map(([file, text]) => [file, indexDigest(text)])) };
129
140
  }
@@ -49,3 +49,18 @@ export async function verifyInputGeneration({ tracked, views, inputs, verifyConf
49
49
  }
50
50
  await verifyTracked();await inputs?.verifyChanges();
51
51
  }
52
+
53
+ export async function liveDependencies(views,temporaryDirectory) {
54
+ const files = new Map(), checked = new Set();
55
+ for (const view of views) for (const built of view.built.values()) {
56
+ for (const [name,hash] of Object.entries(built.dependencyHashes)) {
57
+ const file=path.resolve(view.config.design,name);
58
+ if (checked.has(file)) continue;
59
+ checked.add(file);
60
+ if (file.startsWith(temporaryDirectory+path.sep) && !file.includes(path.sep+'node_modules'+path.sep)) continue;
61
+ const physical=await realpath(file).catch(()=>file);
62
+ if (!physical.startsWith(temporaryDirectory+path.sep)) files.set(physical,hash);
63
+ }
64
+ }
65
+ return [...files];
66
+ }
@@ -154,7 +154,7 @@ export function projectInspection(data, observation, theme, config, intern, defi
154
154
  }
155
155
  }
156
156
  const scene={roots,context:elements.filter(e=>context.has(e.id)).map(e=>({...e,children:e.children.filter(id=>context.has(id)||included.has(id))})),elements:emitted,instances:[],runs:emittedRuns,size:rich.size};
157
- return {scene,matches,limitations,instanceRows:instanceRows.filter(i=>included.has(i.root)||[...context].some(id=>id===i.root)),counts:{raw:scope.size,retained:scope.size-collapsed,collapsed,logical:included.size-collapsed,cutOff:scope.size-included.size,runs:emittedRuns.length}};
157
+ return {scene,matches,scopePaths:query?new Set(idRows.filter(row=>scope.has(row.id)).map(row=>row.path)):null,limitations,instanceRows:instanceRows.filter(i=>included.has(i.root)||[...context].some(id=>id===i.root)),counts:{raw:scope.size,retained:scope.size-collapsed,collapsed,logical:included.size-collapsed,cutOff:scope.size-included.size,runs:emittedRuns.length}};
158
158
  }
159
159
 
160
160
  export function pruneTables(data) {
@@ -42,7 +42,7 @@ export interface Resource {
42
42
  }
43
43
  export interface SVGNode {id:string;tag:string;attributes:Record<string,string>;children:string[]}
44
44
  export interface InspectCommon {
45
- inspectVersion:1;identityVersion:1;project:string;complete:boolean;mode:'catalog'|'frame';
45
+ motion?:{count:number};inspectVersion:1;identityVersion:1;project:string;complete:boolean;mode:'catalog'|'frame';
46
46
  selection:{source:string|null;frame:string|null;themes:Theme[];subtree:null|{kind:'part'|'element'|'text';input:string;contains:boolean};depth:number|null;fields:FieldGroup[];wrappers:'semantic'|'all';expand:boolean};
47
47
  catalog:{source:string;frames:{name:string;locale:string|null;width:number|null;height:number|null}[]}[];
48
48
  frame:{source:string;name:string;locale:string|null;authored:{width:number|null;height:number|null};parent:{source:string;frame:string;selector:string}|null}|null;
@@ -114,5 +114,13 @@ export interface CompactInspectData extends Omit<InspectCommon,'matches'|'limita
114
114
  limitations:(Omit<InspectCommon['limitations'][number],'elements'>&{elements:number[]})[];
115
115
  }
116
116
  export type InspectData=ExpandedInspectData|CompactInspectData;
117
+ export interface MotionInspection {
118
+ project:string; complete:boolean; motionVersion:1; mode:'transitions'|'transition';
119
+ label?:string;
120
+ motion?:{count:number;edges:{id:string;label:string;from:{source:string;frame:string};to:{source:string;frame:string};input:'click'|'hover'|'focus'|'key'|'input';proposed?:string}[]};
121
+ edge?:Record<string,unknown>;bound?:boolean;findings?:Record<string,unknown>[];
122
+ themes?:Partial<Record<Theme,{sameAs:Theme}|{counts:{match:number;enter:number;exit:number;ambiguous:number};timings:Record<string,string|number|null>}>>;
123
+ }
124
+ export function inspect(config:object,args:string[],values:({transition:string}|{transitions:true;frame:string}) & {json?:boolean;explain?:boolean;theme?:Theme|'both'},options?:object):Promise<{data:MotionInspection;warnings:unknown[]}>;
117
125
  export function inspect(config:object,args?:string[],values?:Record<string,string|boolean>,options?:object):Promise<{data:InspectData;warnings:{code:string;message:string;next:{argv:string[];reason:string}[]}[]}>;
118
126
  export function inspectText(data:InspectData):string;
@@ -1,3 +1,6 @@
1
+ import { instanceKeyMatches } from './motion-check.mjs';
2
+ import { readMotion, motionFiles, motionSummary, motionRows } from './motion.mjs';
3
+ import { transitionQuery, targetsFor } from './motion-queries.mjs';
1
4
  import path from 'node:path';
2
5
  import { CliError, nextActions } from '../cli-output.mjs';
3
6
  import { openProjectIndex } from './project-index.mjs';
@@ -22,6 +25,8 @@ export function inspectSelection(values) {
22
25
  }
23
26
 
24
27
  export async function inspect(config, args=[], values={}, {log=console.log, openIndex=openProjectIndex, launchBrowser=launch, environment=observationEnvironment}={}) {
28
+ if(values.transition || values.transitions)return transitionQuery(config,'inspect',args,values,log);
29
+ const motionIds=new Set();
25
30
  const resolvedConfig=canonicalBytes(config);
26
31
  const start=performance.now(),selection=inspectSelection(values),warnings=[],tracked=new Map();
27
32
  let data={inspectVersion:1,identityVersion:1,project:config.root,complete:false,mode:'catalog',encoding:'expanded',selection,catalog:[],frame:null,
@@ -35,7 +40,9 @@ export async function inspect(config, args=[], values={}, {log=console.log, open
35
40
  const getPage=async()=>{browser??=await launchBrowser();page??=await browserTask(browser,()=>browser.newPage({locale:'en-US',timezoneId:'UTC',deviceScaleFactor:1}));return page;};
36
41
  try {
37
42
  const files=await configInputFiles(config),configInputs=new Set(files.map(f=>relative(config,f)));
38
- for(const file of [...files,path.join(config.design,'tokens.css')])tracked.set(file,trackedHash(await inputBytes(file)));
43
+ const sidecars=motionFiles(config);
44
+ for(const file of [...files,...sidecars,path.join(config.design,'tokens.css')])tracked.set(file,trackedHash(await inputBytes(file)));
45
+ const graph=readMotion(config,sidecars);
39
46
  index=await openIndex(config,{stateDirectory:values['state-dir'],fresh:true});data.coverage.discoveredSources=index.inventory.tsx.length;
40
47
  let sources=index.inventory.tsx;
41
48
  await timed('prepareMs',async()=>{
@@ -53,6 +60,8 @@ export async function inspect(config, args=[], values={}, {log=console.log, open
53
60
  const candidates=data.catalog.flatMap(s=>s.frames.filter(f=>!values.frame||f.name===values.frame).map(f=>({source:s.source,frame:f.name})));
54
61
  if(values.frame && !candidates.length)throw new CliError('FRAME_NOT_FOUND',`Unknown frame ${values.frame}.`);
55
62
  if(values.frame && candidates.length>1)throw new CliError('INSPECT_FRAME_AMBIGUOUS',`Frame ${values.frame} occurs in ${candidates.length} sources: ${candidates.map(c=>c.source).join(', ')}.`,{context:{inspectSources:candidates.map(c=>c.source)}});
63
+ const incident=motionRows(graph.records.filter(r=>r.valid && candidates.some(c=>[r.edge.from,r.edge.to].some(ref=>ref.source===c.source && ref.frame===c.frame))));
64
+ if(!selection.subtree)for(const r of incident)motionIds.add(r.edge.id);
56
65
  if(!values.frame && candidates.length!==1){
57
66
  if(['theme','part','element','text','contains','depth','fields','wrappers','expand'].some(k=>values[k]!==undefined))throw new CliError('USAGE_INVALID','Choose a unique frame before setting frame-only options.',{context:{inspectCatalog:true}});
58
67
  if(!candidates.length)warn('EMPTY_SELECTION','No TSX frames were discovered.');
@@ -83,6 +92,19 @@ export async function inspect(config, args=[], values={}, {log=console.log, open
83
92
  data.coverage.cacheHits+=Number(result.hit);data.coverage.completedObservations++;
84
93
  observations.push({theme,palette:result.value.rich.palette});
85
94
  const projected=await timed('projectMs',()=>projectInspection(data,result.value,theme,config,intern,tokens));
95
+ if(projected.scopePaths && incident.length){
96
+ const nodes=result.value.identities, byPath=new Map(nodes.map(n=>[n.path,n]));
97
+ const root=nodes[0]?.path, scoped=nodes.filter(n=>projected.scopePaths.has(n.path));
98
+ const inScope=t=>scoped.some(n=>{
99
+ if(t.frame)return n.path===root;
100
+ if(t.anchor)return n.attributes?.['data-adg-id']===t.anchor;
101
+ if(!n.owners?.some(o=>path.posix.join(relative(config,config.design),o.source)+'#'+o.export===t.part))return false;
102
+ if(t.key===undefined)return true;
103
+ const ancestors=[];for(let p=n;p;p=byPath.get(p.parentPath))ancestors.push(p);
104
+ return instanceKeyMatches(ancestors,t.key);
105
+ });
106
+ for(const {edge} of incident)if(['from','to'].some(side=>edge[side].source===chosen.source && edge[side].frame===chosen.frame && targetsFor(edge,side).some(inScope)))motionIds.add(edge.id);
107
+ }
86
108
  if(data.baseline===null){data.baselineTheme=theme;data.baseline=projected.scene;}else data.additionalThemes[theme]=projected.scene;
87
109
  for(const match of projected.matches){const existing=data.matches.find(m=>m.element===match.element);if(existing)existing.themes.push(theme);else data.matches.push(match);}
88
110
  for(const row of projected.instanceRows)if(!data.partInstances.some(i=>i.id===row.id))data.partInstances.push(row);
@@ -103,10 +125,12 @@ export async function inspect(config, args=[], values={}, {log=console.log, open
103
125
 
104
126
  }
105
127
  await index.close();
128
+ if(JSON.stringify(sidecars)!==JSON.stringify(motionFiles(config)))throw new CliError('INSPECT_INPUT_CHANGED','Transition sidecar inventory changed during inspection.');
106
129
  await verifyInputGeneration({tracked,views:[{index,config,resolved:resolvedConfig,configInputs}],verifyConfig:true,code:'INSPECT_INPUT_CHANGED'});
107
130
  } catch(cause){if(cause.code==='OWNER_INDEX_CHANGED')cause=new CliError('INSPECT_INPUT_CHANGED',cause.message,{cause});primary=commandFailure(cause,data,warnings);}
108
131
  for(const close of [()=>page?.close(),()=>browser?.close(),()=>index?.close()])try{await cleanup(close,primary);}catch(cause){primary=commandFailure(cause,data,warnings);}
109
132
  data.timings.totalMs=performance.now()-start;
133
+ motionSummary(data,[...motionIds]);
110
134
  if(primary)throw primary;
111
135
  data.complete=true;
112
136
  const projectStart=performance.now();data=compactInspection(data);if(values.expand)data=expandInspection(data);
@@ -0,0 +1,382 @@
1
+ import {matchRoots,candidates,chain} from '../../public/motion-identity.js';
2
+ import { flowLayout } from '../../public/motion-flow.js';
3
+ import { frameKey } from './motion-flows.mjs';
4
+ import { nativeTextEntry } from '../../public/motion-scene.js';
5
+ export {instanceKeyMatches} from '../../public/motion-identity.js';
6
+ import path from 'node:path';
7
+ import { loadFrame } from './browser.mjs';
8
+ import { buildSource } from './build.mjs';
9
+ import { listSources, relative, loadTokens, sourceDirectories, isFeatureInternal } from './project.mjs';
10
+ import { resolveMotionToken, timingRefs } from './motion.mjs';
11
+
12
+ // Runs inside the frame observation page. Indexes are local to this one observation.
13
+ function observe({ design, nativeTextEntry }) {
14
+ const shell = document.querySelector('[data-adg-frame]').firstElementChild;
15
+ const elements = [shell, ...shell.querySelectorAll('*')],
16
+ indexes = new Map(elements.map((el, i) => [el, i]));
17
+ function hit(el, rect) {
18
+ let left = Math.max(0, rect.left),
19
+ top = Math.max(0, rect.top),
20
+ right = Math.min(innerWidth, rect.right),
21
+ bottom = Math.min(innerHeight, rect.bottom);
22
+ for (let p = el.parentElement; p; p = p.parentElement) {
23
+ const style = getComputedStyle(p),
24
+ bounds = p.getBoundingClientRect();
25
+ if (/hidden|clip|auto|scroll/.test(style.overflowX)) {
26
+ left = Math.max(left, bounds.left);
27
+ right = Math.min(right, bounds.right);
28
+ }
29
+ if (/hidden|clip|auto|scroll/.test(style.overflowY)) {
30
+ top = Math.max(top, bounds.top);
31
+ bottom = Math.min(bottom, bounds.bottom);
32
+ }
33
+ }
34
+ if (right <= left || bottom <= top) return false;
35
+ return [0.5, 0.01, 0.99].some((x) =>
36
+ [0.5, 0.01, 0.99].some((y) =>
37
+ el.contains(document.elementFromPoint(left + (right - left) * x, top + (bottom - top) * y))
38
+ )
39
+ );
40
+ }
41
+ const rows = elements.map((el, i) => {
42
+ const parts = JSON.parse(el.dataset.adgOwners ?? '[]').map((o) => design + '/' + o.source + '#' + o.export);
43
+ const keys = JSON.parse(el.dataset.adgKeys ?? '[]');
44
+ const rect = el.getBoundingClientRect();
45
+ let limitation=null;
46
+ for(let p=el;p && !limitation;p=p.parentElement){
47
+ const style=getComputedStyle(p),b=p.getBoundingClientRect();
48
+ if(style.transform!=='none' && !Number.isFinite(new DOMMatrix(style.transform).inverse().a))limitation='non_invertible';
49
+ else if(style.clipPath!=='none' || p!==el && (
50
+ /hidden|clip|auto|scroll/.test(style.overflowX) && (rect.left<b.left || rect.right>b.right) ||
51
+ /hidden|clip|auto|scroll/.test(style.overflowY) && (rect.top<b.top || rect.bottom>b.bottom)))limitation='clipped';
52
+ }
53
+ const visible =
54
+ rect.width > 0 &&
55
+ rect.height > 0 &&
56
+ el.checkVisibility({ opacityProperty: true, visibilityProperty: true }) &&
57
+ el.getClientRects().length > 0;
58
+ return {
59
+ i,
60
+ parent: indexes.get(el.parentElement) ?? -1,
61
+ parts,
62
+ keys,
63
+ anchor: el.dataset.adgId ?? null,
64
+ box: [rect.x, rect.y, rect.width, rect.height],
65
+ limitation,
66
+ exposed: visible && !el.closest('[inert],[aria-hidden="true"]'),
67
+ pointer: visible && hit(el, rect),
68
+ disabled: el.matches(':disabled,[aria-disabled="true"]'),
69
+ textEntry: !el.readOnly && (el.matches(nativeTextEntry) || (el.hasAttribute('contenteditable') && el.isContentEditable)),
70
+ focusable: false,
71
+ keyboard: false
72
+ };
73
+ });
74
+ // Ask the browser so native controls such as summary and tabindex=-1 behave as authored.
75
+ for (const row of rows) {
76
+ const el = elements[row.i];
77
+ if (row.exposed && !row.disabled && (el.tabIndex >= 0 || el.hasAttribute('tabindex') || el.isContentEditable)) {
78
+ el.focus({ preventScroll: true });
79
+ row.focusable = document.activeElement === el;
80
+ if (row.focusable) el.blur();
81
+ }
82
+ }
83
+ for (const row of rows.toReversed()) {
84
+ row.keyboard ||= row.focusable;
85
+ if (row.parent >= 0 && row.keyboard) rows[row.parent].keyboard = true;
86
+ }
87
+ return rows;
88
+ }
89
+
90
+ export function motionEvaluator(
91
+ config,
92
+ { getPage, getBuild, bindings = [], hasMap = false, flows = new Map(), themes = ['light', 'dark'] } = {}
93
+ ) {
94
+ const builds = new Map(),
95
+ observations = new Map(),
96
+ dispatch = new Map(),
97
+ layouts = new Map();
98
+ const layers = sourceDirectories(config).filter((s) => s !== 'studies'),
99
+ top = layers.at(-1);
100
+ const inventory = new Set(listSources(config.design, sourceDirectories(config)).map((f) => relative(config, f)));
101
+ const tokens = loadTokens(config);
102
+ async function frameAt(ref) {
103
+ if (!inventory.has(ref.source)) return;
104
+ if (!builds.has(ref.source))
105
+ builds.set(
106
+ ref.source,
107
+ getBuild?.(ref.source) ?? buildSource(config, path.join(config.root, ref.source), { write: false })
108
+ );
109
+ return (await builds.get(ref.source)).frames.find((f) => f.name === ref.frame);
110
+ }
111
+ async function observeFrame(ref, frame, theme) {
112
+ const key = JSON.stringify([ref.source, ref.frame, theme]);
113
+ if (!observations.has(key)) {
114
+ const page = await getPage();
115
+ const { x, y, width, height } = await loadFrame(page, frame, theme);
116
+ const rows = await page.evaluate(observe, { design: relative(config, config.design), nativeTextEntry });
117
+ observations.set(key, { box: [x, y, width, height], rows });
118
+ }
119
+ return observations.get(key);
120
+ }
121
+ async function layoutFor(flow, theme) {
122
+ if (!layouts.has(flow)) layouts.set(flow, new Map());
123
+ const byTheme = layouts.get(flow);
124
+ if (!byTheme.has(theme)) {
125
+ const frames = [];
126
+ for (const ref of flow.frames) {
127
+ const frame = await frameAt(ref);
128
+ if (!frame) break;
129
+ frames.push(await observeFrame(ref, frame, theme));
130
+ }
131
+ byTheme.set(theme, frames.length === flow.frames.length ? flowLayout(flow, frames) : null);
132
+ }
133
+ return byTheme.get(theme);
134
+ }
135
+ return async function evaluate(record) {
136
+ const { edge: e, owner } = record,
137
+ problems = new Map(),
138
+ detail = {
139
+ edge: e,
140
+ themes: {},
141
+ bound: bindings.some((b) => b.active && b.design.source === owner && b.design.transition === e.id)
142
+ };
143
+ function issue(code, at, message, theme = null, warning = false) {
144
+ const pointer = record.pointer + at,
145
+ key = JSON.stringify([code, pointer, message]);
146
+ const found = problems.get(key);
147
+ if (found) {
148
+ if (found.theme !== theme) found.theme = null;
149
+ return;
150
+ }
151
+ problems.set(key, {
152
+ code,
153
+ pointer,
154
+ source: record.source,
155
+ transition: e.id,
156
+ frame: e.from.frame,
157
+ theme,
158
+ warning,
159
+ message,
160
+ ...(record.locations[pointer] ?? record.locations[record.pointer])
161
+ });
162
+ }
163
+ const designPath = (ref) => path.relative(config.design, path.join(config.root, ref)).split(path.sep).join('/');
164
+ const layer = (ref) => designPath(ref).split('/')[0];
165
+ if (
166
+ owner !== e.from.source ||
167
+ !layers.includes(layer(owner)) || isFeatureInternal(designPath(owner), layers) ||
168
+ (owner !== e.to.source && !(layer(owner) === top && layer(e.to.source) === top))
169
+ )
170
+ issue('MOTION_LAYER', '/from', 'Declare this edge on its public origin entry. Only surfaces can cross sources.');
171
+ const from = await frameAt(e.from),
172
+ to = await frameAt(e.to);
173
+ for (const [side, f] of [
174
+ ['from', from],
175
+ ['to', to]
176
+ ]) {
177
+ if (!f) issue('MOTION_FRAME_MISSING', '/' + side, 'Missing endpoint ' + e[side].source + '#' + e[side].frame);
178
+ else if (f.proposed && f.proposed !== e.proposed)
179
+ issue('MOTION_STATUS', '/' + side, 'Endpoint proposal scope differs from the edge.');
180
+ }
181
+ if (hasMap && config.check?.lifecycle && !e.proposed && !detail.bound)
182
+ issue('MOTION_BINDING', '/id', 'Current action needs an active implementation binding.');
183
+ for (const [i, u] of (e.unsupported ?? []).entries())
184
+ issue('MOTION_UNSUPPORTED', '/unsupported/' + i, u.effect + ': ' + u.reason, null, true);
185
+ for (const theme of themes) {
186
+ const times = {};
187
+ for (const { pointer, kind, name } of timingRefs(e)) {
188
+ times[pointer] = resolveMotionToken(tokens, theme, name, kind).value;
189
+ if (times[pointer] === null)
190
+ issue(
191
+ 'MOTION_TOKEN',
192
+ pointer,
193
+ 'Expected a project ' + kind + ' token, got ' + JSON.stringify(name ?? null),
194
+ theme
195
+ );
196
+ }
197
+ if (!from || !to) continue;
198
+ const observed = { from: await observeFrame(e.from, from, theme), to: await observeFrame(e.to, to, theme) };
199
+ const rows = { from: observed.from.rows, to: observed.to.rows };
200
+ const matched = matchRoots(rows.from, rows.to);
201
+ for (const conflict of matched.conflicts)
202
+ issue(
203
+ 'MOTION_IDENTITY_AMBIGUOUS',
204
+ '/phases',
205
+ conflict.side + ' repeats an authored instance key for ' + conflict.part + '.',
206
+ theme
207
+ );
208
+ const resolved = [];
209
+ function resolve(side, target, at, missing = 'MOTION_TARGET_MISSING') {
210
+ const list = candidates(rows[side], target);
211
+ if (list.length === 1) {
212
+ resolved.push({ side, target, index: list[0].i });
213
+ return list[0];
214
+ }
215
+ issue(
216
+ list.length ? 'MOTION_IDENTITY_AMBIGUOUS' : missing,
217
+ at,
218
+ side + ' ' + JSON.stringify(target) + ' resolved to ' + list.length + ' elements.',
219
+ theme
220
+ );
221
+ }
222
+ const t = resolve('from', e.trigger.target, '/trigger/target', 'MOTION_TRIGGER_MISSING');
223
+ if (t) {
224
+ if (e.trigger.on === 'input' && (!t.textEntry || !t.focusable))
225
+ issue('MOTION_INPUT_TARGET', '/trigger/target', 'Input requires an editable text-entry control.', theme);
226
+ if (
227
+ !t.exposed ||
228
+ t.disabled ||
229
+ (['click', 'hover'].includes(e.trigger.on) && !t.pointer) ||
230
+ (e.trigger.on === 'focus' && !t.focusable) ||
231
+ (e.trigger.on === 'key' && !e.trigger.target.frame && !t.keyboard)
232
+ )
233
+ issue('MOTION_TRIGGER_MISSING', '/trigger', 'Origin cannot receive ' + e.trigger.on + '.', theme);
234
+ const k = JSON.stringify([e.from.source, e.from.frame, theme, t.i, e.trigger.on, e.trigger.key ?? e.trigger.value]);
235
+ if (dispatch.has(k) && dispatch.get(k) !== e.id)
236
+ issue('MOTION_TRIGGER_CONFLICT', '/trigger', 'Input also dispatches ' + dispatch.get(k) + '.', theme);
237
+ else dispatch.set(k, e.id);
238
+ }
239
+ if (e.focus.target) {
240
+ const f = resolve('to', e.focus.target, '/focus/target', 'MOTION_FOCUS');
241
+ if (f && (!f.exposed || f.disabled || (!f.focusable && !e.focus.target.frame)))
242
+ issue('MOTION_FOCUS', '/focus', 'Destination cannot receive focus.', theme);
243
+ }
244
+ const claims = { from: [], to: [] },
245
+ tracks = [];
246
+ let start = 0;
247
+ for (const [i, phase] of e.phases.entries()) {
248
+ let length = 0;
249
+ for (const [j, track] of phase.entries()) {
250
+ const at = '/phases/' + i + '/' + j,
251
+ duration = times[at + '/duration'] ?? times['/duration'];
252
+ tracks.push({ phase: i, track: j, start, duration, easing: times[at + '/easing'] ?? times['/easing'] });
253
+ length = Math.max(length, duration ?? 0);
254
+ for (const [n, target] of track.targets.entries()) {
255
+ const found = {};
256
+ const sides =
257
+ track.mode === 'exit'
258
+ ? ['from']
259
+ : track.mode === 'enter' && !candidates(rows.from, target).length
260
+ ? ['to']
261
+ : ['from', 'to'];
262
+ for (const side of sides) {
263
+ const p = at + '/targets/' + n,
264
+ row = resolve(side, target, p);
265
+ if (!row) continue;
266
+ found[side] = row;
267
+ const subtree = track.mode !== 'match',
268
+ ancestors = chain(rows[side], row);
269
+ for (const prev of claims[side]) {
270
+ if (
271
+ prev.row === row
272
+ ? track.properties.some((v) => prev.props.includes(v))
273
+ : (prev.subtree && ancestors.includes(prev.row)) ||
274
+ (subtree && chain(rows[side], prev.row).includes(row))
275
+ )
276
+ issue('MOTION_TRACK_CONFLICT', p, 'Overlapping track claims on ' + side + ' endpoint.', theme);
277
+ }
278
+ claims[side].push({ row, subtree, mode: track.mode, props: track.properties, duration });
279
+ }
280
+ if (
281
+ track.mode === 'match' &&
282
+ found.from?.parts.length &&
283
+ found.to &&
284
+ !matched.pairs.some((p) => p.from === found.from.i && p.to === found.to.i)
285
+ )
286
+ issue(
287
+ 'MOTION_IDENTITY_AMBIGUOUS',
288
+ at,
289
+ 'Match track needs the same resolved owner instance in both endpoints.',
290
+ theme
291
+ );
292
+ }
293
+ }
294
+ start += length;
295
+ }
296
+ const excluded = { from: new Set(), to: new Set() };
297
+ for (const side of ['from', 'to']) {
298
+ const subtrees = new Set(claims[side].filter((c) => c.subtree).map((c) => c.row.i));
299
+ for (const row of rows[side]) if (subtrees.has(row.i) || excluded[side].has(row.parent)) excluded[side].add(row.i);
300
+ }
301
+ const implicit = excluded.from.size || excluded.to.size ? matchRoots(rows.from, rows.to, excluded) : matched;
302
+ const flow = flows.get(frameKey(e.from));
303
+ if (flow) {
304
+ const layout = await layoutFor(flow, theme);
305
+ const fromIndex = flow.frames.findIndex((ref) => frameKey(ref) === frameKey(e.from));
306
+ const toIndex = flow.frames.findIndex((ref) => frameKey(ref) === frameKey(e.to));
307
+ const warning = !config.check?.strictMotion;
308
+ if (!layout?.pin)
309
+ issue('MOTION_FLOW_ANCHOR', '/trigger/target', flow.anchor
310
+ ? 'Flow anchor must resolve to one nonempty box in every member frame.'
311
+ : 'No trigger target is present uniquely across the flow. Playback uses an unpinned stage.', theme, warning);
312
+ if (layout && flow.stage && (layout.width > flow.stage.width + 0.01 || layout.height > flow.stage.height + 0.01))
313
+ issue('MOTION_FLOW_STAGE', '/to', 'Flow stage is smaller than the aligned frame union.', theme, warning);
314
+ if (layout?.pin) {
315
+ const { boxes } = layout.pin;
316
+ if ([2, 3].some(axis => Math.abs(boxes[fromIndex][axis] - boxes[toIndex][axis]) > 0.01))
317
+ issue('MOTION_FLOW_ANCHOR', '/to', 'The persistent flow anchor changes size.', theme, warning);
318
+ }
319
+ const positions = ['from', 'to'].map((side, i) => {
320
+ const offset = layout?.offsets[i ? toIndex : fromIndex] ?? [0, 0];
321
+ return offset.map((value, axis) => value - observed[side].box[axis]);
322
+ });
323
+ checkComposition(rows, matched.pairs, excluded, claims, positions,
324
+ (code, message) => issue(code, '/phases', message, theme, warning));
325
+ }
326
+ if (implicit.ambiguous.length)
327
+ issue(
328
+ 'MOTION_IMPLICIT_FADE',
329
+ '/phases',
330
+ implicit.ambiguous.length + ' ambiguous owner groups use fades.',
331
+ theme,
332
+ true
333
+ );
334
+ detail.themes[theme] = { timings: times, tracks, targets: resolved, ...implicit };
335
+ }
336
+ if (detail.themes.dark && JSON.stringify(detail.themes.light) === JSON.stringify(detail.themes.dark))
337
+ detail.themes.dark = { sameAs: 'light' };
338
+ return { detail, findings: [...problems.values()] };
339
+ };
340
+ }
341
+
342
+ function checkComposition(rows, pairs, excluded, claims, positions, issue) {
343
+ const active = (row) => row.box[2] > 0 && row.box[3] > 0;
344
+ const identity = (row) => row.anchor ? '#' + row.anchor : row.parts.at(-1);
345
+ const matched = { from: new Set(), to: new Set() };
346
+ const compare = (left, right) => {
347
+ if (!active(left) || !active(right)) return;
348
+ matched.from.add(left.i);
349
+ matched.to.add(right.i);
350
+ const axes = ['x', 'y'].filter((axis, i) =>
351
+ Math.abs(left.box[i] + positions[0][i] - right.box[i] - positions[1][i]) > 0.01 &&
352
+ !claims.from.some((claim) => claim.row === left && claim.mode === 'match' &&
353
+ claim.props.includes(axis) && claim.duration > 0));
354
+ if (axes.length) issue('MOTION_UNANIMATED_MOVE', identity(left) + ' moves on ' + axes.join('/') + ' without a position track.');
355
+ };
356
+ const replaced = (side, row) => excluded[side].has(row.i) &&
357
+ !claims[side].some((claim) => claim.subtree && claim.row === row);
358
+ for (const pair of pairs) {
359
+ const left = rows.from[pair.from], right = rows.to[pair.to];
360
+ if (!replaced('from', left) && !replaced('to', right)) compare(left, right);
361
+ }
362
+ const anchors = new Set([...rows.from, ...rows.to].flatMap((row) => row.anchor ? [row.anchor] : []));
363
+ for (const anchor of anchors) {
364
+ const [left, right] = ['from', 'to'].map((side) => candidates(rows[side], { anchor }));
365
+ if (left.length === 1 && right.length === 1 &&
366
+ !matched.from.has(left[0].i) && !matched.to.has(right[0].i) &&
367
+ !replaced('from', left[0]) && !replaced('to', right[0])) compare(left[0], right[0]);
368
+ }
369
+ for (const side of ['from', 'to']) {
370
+ const uncovered = new Set();
371
+ for (const row of rows[side]) {
372
+ if (uncovered.has(row.parent)) {
373
+ uncovered.add(row.i);
374
+ continue;
375
+ }
376
+ if (!identity(row) || !active(row) || matched[side].has(row.i) || excluded[side].has(row.i)) continue;
377
+ uncovered.add(row.i);
378
+ issue('MOTION_UNANIMATED_PRESENCE', identity(row) + ' appears only on ' + side +
379
+ ' without ' + (side === 'from' ? 'an exit' : 'an enter') + ' track.');
380
+ }
381
+ }
382
+ }