altitude-design 0.2.1 → 0.3.1

package/dist/guidance/references/build/checks/pattern-workflows.mjs

@@ -0,0 +1,226 @@
+// Controlled service tests: mutations update service data only when explicitly accepted.
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { chromium } from 'playwright-core';
+const root = fileURLToPath(new URL('../../', import.meta.url));
+const temp = await mkdtemp(join(tmpdir(), 'altitude-patterns-'));
+const aliases = process.env.ALT_PACKAGE_ROOT ? { react: resolve(process.env.ALT_PACKAGE_ROOT, '../react'), 'react-dom': resolve(process.env.ALT_PACKAGE_ROOT, '../react-dom') } : {};
+const bundle = await build({ alias: aliases, stdin: { contents: `import * as React from 'react'; import {createRoot} from 'react-dom/client'; import * as Altitude from '${process.env.ALT_PACKAGE_ROOT ? resolve(process.env.ALT_PACKAGE_ROOT, 'dist/index.js') : process.env.ALT_PATTERN_ENTRY || './project/components/src/index.tsx'}'; window.React=React; window.createRoot=createRoot; window.Altitude=Altitude;`, resolveDir: root, loader: 'tsx' }, bundle: true, write: false, format: 'iife', define: { 'process.env.NODE_ENV': '"development"' } });
+await writeFile(join(temp, 'bundle.js'), bundle.outputFiles[0].contents);
+await writeFile(join(temp, 'index.html'), '<!doctype html><html lang="en"><title>Pattern contracts</title><body><div id="root"></div><script src="bundle.js"></script></body></html>');
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+let checks = 0;
+const rules = JSON.parse(await readFile(resolve(root, 'project/framework/rules.json'), 'utf8')).rules;
+const ruleAliases = { 'FORM-PRESERVE-INPUT':'ALT-EDIT-001', 'FORM-STALE-RESPONSE':'ALT-EDIT-001', 'FORM-VALIDATION-TIMING':'ALT-EDIT-003',
+ 'FORM-UNSAVED':'ALT-EDIT-003', 'FORM-ERROR-ASSOCIATION':'ALT-EDIT-002', 'ACTION-TRUE-OUTCOME':'ALT-EDIT-001', 'ACTION-DUPLICATE':'ALT-ACTION-001',
+ 'COLLECTION-STATES':'ALT-COLLECTION-001', 'COLLECTION-SELECTION':'ALT-COLLECTION-001', 'COLLECTION-RECOVERY':'ALT-COLLECTION-001', 'COLLECTION-IDENTITY':'ALT-COLLECTION-001',
+ 'ACTION-CONFIRMATION':'ALT-ACTION-001', 'ACTION-FOCUS':'ALT-ACTION-001', 'ACTION-RECOVERY':'ALT-ACTION-001', 'ACTION-UNDO':'ALT-ACTION-001', 'ACTION-TARGET':'ALT-ACTION-001',
+ 'REVIEW-RETAIN':'ALT-REVIEW-001', 'REVIEW-RECOVERY':'ALT-REVIEW-001', 'REVIEW-CONFIRMATION':'ALT-REVIEW-001', 'REVIEW-PROCESS':'ALT-REVIEW-001',
+ 'CONVO-DUPLICATE':'ALT-CONVO-001', 'CONVO-STALE':'ALT-CONVO-001', 'CONVO-KEEP':'ALT-CONVO-001', 'CONVO-COMPLETE':'ALT-CONVO-001', 'CONVO-ERRORS':'ALT-CONVO-001', 'CONVO-RELOAD':'ALT-CONVO-001' };
+const check = (condition, message) => {
+ const ruleId = ruleAliases[message.split(':')[0]] || 'ALT-STATUS-001';
+ if (!condition) console.error(JSON.stringify({ ruleId, classification:'deterministic', scope:'controlled fixture contract; not a general usability verdict',
+  observed:'Contract assertion returned false', expected:message, repair:rules.find(rule=>rule.id===ruleId)?.repair }));
+ assert.ok(condition, `${ruleId}: ${message}`); checks++;
+};
+const page = await browser.newPage();
+const errors = []; page.on('pageerror', error => errors.push(error.message));
+await page.goto(`file://${join(temp, 'index.html')}`);
+const mountEdit = async (validationMode = 'submit') => {
+ await page.evaluate(mode => {
+  window.fixtureRoot?.unmount(); const R = React, h = R.createElement, A = Altitude;
+  const api = { writes: [], data: { name: 'Original' }, leaves: [] }; window.harness = api;
+  function Fixture() {
+   const form = A.useEditRecord({ initialValue: { name: 'Original' }, validationMode: mode,
+    validate: value => value.name.trim() ? {} : { name: 'Enter a name.' },
+    save: draft => new Promise(resolve => { api.writes.push({ draft, resolve: result => { if (result.ok) api.data = result.value; resolve(result); } }); }),
+   }); api.form = form;
+   return h('form', { noValidate: true, onSubmit: e => { e.preventDefault(); void form.submit(); } },
+    h(A.ErrorSummary, { errors: Object.entries(form.errors).map(([key,message]) => ({ id: key, label: 'Name', message })), focusKey: form.submitCount }),
+    h(A.Field, { label: 'Name', error: form.errors.name }, h(A.Input, { id: 'name', value: form.draft.name, onChange: e => form.setField('name', e.target.value), onBlur: () => form.validateField('name') })),
+    h('button', { type: 'submit' }, 'Save changes'), h(A.WorkflowStatus, null, form.status), h('span', { id: 'phase' }, form.phase));
+  }
+  window.fixtureRoot = createRoot(document.getElementById('root')); fixtureRoot.render(h(R.StrictMode, null, h(A.AltitudeProvider, null, h(Fixture))));
+ }, validationMode);
+ await page.getByRole('textbox', { name: 'Name' }).waitFor();
+};
+const resolveWrite = (result, index = 0) => page.evaluate(({result,index}) => harness.writes[index].resolve(result), {result,index});
+const phase = value => page.waitForFunction(value => document.getElementById('phase').textContent === value, value);
+try {
+ check(await page.evaluate(() => typeof Altitude.useEditRecord === 'function'), 'FORM-PRESERVE-INPUT: edit-record hook is exported');
+ await mountEdit(); const input = page.getByRole('textbox', { name: 'Name' });
+ await input.fill(''); await input.blur(); check(await page.getByRole('alert').count() === 0, 'FORM-VALIDATION-TIMING: submit policy does not validate untouched blur');
+ await page.getByRole('button', { name: 'Save changes' }).click(); await phase('invalid');
+ check(await page.evaluate(() => harness.writes.length) === 0, 'FORM-ERROR-ASSOCIATION: invalid values never persist');
+ check(await input.getAttribute('aria-invalid') === 'true', 'FORM-ERROR-ASSOCIATION: same error drives field');
+ await page.getByRole('link', { name: 'Name: Enter a name.' }).click(); check(await input.evaluate(el => el === document.activeElement), 'FORM-ERROR-ASSOCIATION: summary link focuses field');
+ await input.fill('Retained'); check(await page.getByRole('link', { name: /Enter a name/ }).count() === 0, 'FORM-ERROR-ASSOCIATION: correction updates one error source');
+ await page.evaluate(() => { harness.form.submit(); harness.form.submit(); }); await phase('submitting');
+ check(await page.evaluate(() => harness.writes.length) === 1, 'ACTION-DUPLICATE: same-tick submissions dispatch once');
+ check(await page.evaluate(() => harness.data.name) === 'Original', 'ACTION-TRUE-OUTCOME: pending has not changed actual service data');
+ check(await page.getByRole('status').textContent() === 'Saving changes', 'ACTION-TRUE-OUTCOME: pending never claims success');
+ check(await page.evaluate(() => harness.form.requestLeave('navigation', () => {throw Error('must not prompt during pending');}))===false,'FORM-UNSAVED: pending navigation blocked without claiming cancellation');
+ await resolveWrite({ ok: false, error: 'Connection unavailable. Try again.' }); await phase('failed');
+ check(await input.inputValue() === 'Retained', 'FORM-PRESERVE-INPUT: failed write retains draft');
+ await page.evaluate(() => { void harness.form.submit(); }); await resolveWrite({ ok: true, value: { name: 'Retained' } }, 1); await phase('saved');
+ check(await page.evaluate(() => harness.data.name === 'Retained' && !harness.form.dirty), 'ACTION-TRUE-OUTCOME: retry changes data then clears dirty state');
+ await input.fill('First'); await page.evaluate(() => { void harness.form.submit(); }); await input.fill('Newer');
+ await resolveWrite({ ok: true, value: { name: 'First' } }, 2); await phase('editing');
+ check(await page.evaluate(() => harness.form.draft.name === 'Newer' && harness.form.dirty && harness.data.name === 'First'), 'FORM-STALE-RESPONSE: accepted older save cannot overwrite newer edits');
+ check(!(await page.getByRole('status').textContent()).includes('Changes saved'), 'FORM-STALE-RESPONSE: current draft not falsely marked saved');
+ check(await page.evaluate(() => harness.form.requestLeave('back', () => false)) === false, 'FORM-UNSAVED: retain blocks Back');
+ check(await page.evaluate(() => harness.form.requestLeave('navigation', () => true)) === true, 'FORM-UNSAVED: explicit discard permits navigation');
+ check(await page.evaluate(() => harness.form.draft.name) === 'First', 'FORM-UNSAVED: discard restores accepted baseline');
+ check(await page.evaluate(() => harness.form.requestLeave('cancel', () => { throw Error('must not ask clean form'); })) === true, 'FORM-UNSAVED: clean leave requires no discard decision');
+ await mountEdit('blur'); await page.getByRole('textbox', { name: 'Name' }).fill(''); await page.getByRole('textbox', { name: 'Name' }).blur(); await phase('invalid');
+ check(await page.getByRole('alert').count() === 1, 'FORM-VALIDATION-TIMING: blur reports a single inline alert');
+ await mountEdit(); await page.getByRole('textbox', {name:'Name'}).fill('Server rejects this');
+ await page.getByRole('button',{name:'Save changes'}).click(); await phase('submitting');
+ await resolveWrite({ok:false,error:'Check the name.',errors:{name:'This name is taken.'}}); await phase('failed');
+ check(await page.getByRole('region',{name:'Check these fields'}).evaluate(el=>el===document.activeElement),'FORM-ERROR-ASSOCIATION: late server errors focus the summary once');
+ await page.getByRole('textbox',{name:'Name'}).fill('Correction');
+ check(await page.getByRole('textbox',{name:'Name'}).evaluate(el=>el===document.activeElement),'FORM-ERROR-ASSOCIATION: correcting errors never steals focus back');
+ // Collection: out-of-order responses cannot replace a newer query; selection is explicit.
+ check(await page.evaluate(() => typeof Altitude.useAsyncCollection === 'function'), 'COLLECTION-STATES: collection hook is exported');
+ await page.evaluate(() => {
+  fixtureRoot.unmount(); const h = React.createElement; const api = { reads: [] }; window.harness = api;
+  function Fixture() { const collection = Altitude.useAsyncCollection({ initialQuery: '', isFiltered: query => query !== '', getKey: item => item.id, selection: 'preserve',
+   load: (query, context) => new Promise((resolve,reject) => api.reads.push({query,context,resolve,reject})) }); api.collection = collection;
+   return h('div', null, h('span', {id:'phase'}, collection.phase), h(Altitude.WorkflowStatus, null, collection.status), collection.items.map(item => h('p',{key:item.id},item.name)));
+  } fixtureRoot = createRoot(document.getElementById('root')); fixtureRoot.render(h(Fixture));
+ }); await phase('loading');
+ await page.evaluate(() => harness.reads[0].resolve([{id:'a',name:'Alpha'},{id:'b',name:'Beta'}])); await phase('populated');
+ await page.evaluate(() => { harness.collection.toggleSelection('a'); harness.collection.setQuery('missing'); }); await phase('refreshing');
+ await page.evaluate(() => harness.reads[1].resolve([])); await phase('no-results');
+ check(await page.evaluate(() => harness.collection.selectedKeys.has('a')), 'COLLECTION-SELECTION: preserve policy explicitly retains hidden stable key');
+ await page.evaluate(() => harness.collection.reset()); await phase('refreshing');
+ await page.evaluate(() => harness.reads[2].reject(Error('private server failure'))); await phase('failed');
+ check(!(await page.getByRole('status').textContent()).includes('private'), 'COLLECTION-RECOVERY: safe failure feedback');
+ await page.evaluate(() => harness.collection.refresh()); await page.evaluate(() => harness.reads[3].resolve([])); await phase('empty');
+ await page.evaluate(() => harness.collection.setQuery('older')); await page.evaluate(() => harness.collection.setQuery('newer'));
+ await page.evaluate(() => harness.reads[5].resolve([{id:'n',name:'Newest'}])); await phase('populated');
+ await page.evaluate(() => harness.reads[4].resolve([{id:'o',name:'Outdated'}]));
+ check(await page.evaluate(() => harness.collection.items[0].id) === 'n', 'COLLECTION-IDENTITY: stale query cannot replace current results');
+ await page.evaluate(() => harness.collection.refresh()); await page.evaluate(() => harness.reads[6].resolve([{id:'n',name:'One'},{id:'n',name:'Two'}])); await phase('failed');
+ check(await page.evaluate(() => harness.collection.items[0].name) === 'Newest', 'COLLECTION-IDENTITY: duplicate keys reject result and retain last good data');
+ await page.evaluate(() => {
+  fixtureRoot.unmount();const h=React.createElement;const api={};window.harness=api;
+  function Fixture(){const collection=Altitude.useAsyncCollection({initialQuery:'',isFiltered:q=>!!q,selection:'clear-on-query',getKey:item=>item.id,load:()=>[{id:'a'}]});api.collection=collection;return h('span',{id:'phase'},collection.phase);}
+  fixtureRoot=createRoot(document.getElementById('root'));fixtureRoot.render(h(React.StrictMode,null,h(Fixture)));
+ });await phase('populated');await page.evaluate(()=>{harness.collection.toggleSelection('a');harness.collection.setQuery('other');});await phase('populated');
+ check(await page.evaluate(()=>harness.collection.selectedKeys.size)===0,'COLLECTION-SELECTION: clear-on-query policy drops selection explicitly');
+ // Consequential action: confirmation does not mutate; Undo has a real inverse operation.
+ check(await page.evaluate(() => typeof Altitude.useConsequentialAction === 'function'), 'ACTION-TRUE-OUTCOME: consequential hook is exported');
+ await page.evaluate(() => {
+  fixtureRoot.unmount(); const h = React.createElement; const api = { data:['a'], writes:[], undos:[] }; window.harness=api;
+  function Fixture() { const action = Altitude.useConsequentialAction({ target:'Alpha', consequence:'Move Alpha to trash.', requiresConfirmation:true,
+   execute: () => new Promise(resolve => api.writes.push(result => {if(result.ok) api.data=[]; resolve(result);})),
+   undo: result => new Promise(resolve => api.undos.push(outcome => {if(outcome.ok) api.data=[result]; resolve(outcome);})),
+   focusFallback: () => document.getElementById('fallback') }); api.action=action;
+   return h('div',null,h('button',{id:'trigger',onClick:action.request},'Delete Alpha'),h('button',{id:'fallback'},'Next record'),h('span',{id:'phase'},action.phase),h(Altitude.WorkflowStatus,null,action.status));
+  } fixtureRoot=createRoot(document.getElementById('root')); fixtureRoot.render(h(Fixture));
+ }); await phase('idle');
+ await page.getByRole('button',{name:'Delete Alpha'}).click(); await phase('confirming');
+ check(await page.evaluate(() => harness.writes.length === 0 && harness.data.length === 1), 'ACTION-CONFIRMATION: intent decision does not execute');
+ await page.evaluate(() => harness.action.cancel()); await phase('idle');
+ check(await page.locator('#trigger').evaluate(el=>el===document.activeElement),'ACTION-FOCUS: cancel restores trigger');
+ await page.evaluate(() => { harness.action.request(); harness.action.confirm(); harness.action.confirm(); }); await phase('pending');
+ check(await page.evaluate(() => harness.writes.length) === 1,'ACTION-DUPLICATE: repeated confirmation dispatches once');
+ await page.evaluate(() => harness.writes[0]({ok:false,error:'Could not delete. Try again.'})); await phase('failed');
+ check(await page.evaluate(() => harness.data.length) === 1,'ACTION-RECOVERY: failed action leaves service data intact');
+ await page.evaluate(() => { void harness.action.retry(); }); await page.evaluate(() => harness.writes[1]({ok:true,value:'a'})); await phase('succeeded');
+ check(await page.evaluate(() => harness.data.length === 0 && harness.action.canUndo),'ACTION-TRUE-OUTCOME: succeeded after data mutation with real undo');
+ await page.evaluate(() => { void harness.action.undo(); }); await phase('undoing');
+ await page.evaluate(() => harness.undos[0]({ok:false,error:'Could not restore. Try again.'})); await phase('failed');
+ await page.evaluate(() => { void harness.action.retry(); }); await page.evaluate(() => harness.undos[1]({ok:true})); await phase('undone');
+ check(await page.evaluate(() => harness.data[0]) === 'a','ACTION-UNDO: retry performs real restoration');
+ await page.evaluate(() => {
+  fixtureRoot.unmount(); const h=React.createElement; const api={writes:[],data:['first','second']};window.harness=api;
+  function Fixture(){const [target,setTarget]=React.useState('first');api.setTarget=setTarget;api.observedTarget=target;
+   const action=Altitude.useConsequentialAction({target,consequence:`Delete ${target}.`,requiresConfirmation:true,
+    execute:()=>new Promise(resolve=>api.writes.push(()=>{api.data=api.data.filter(id=>id!==target);resolve({ok:true,value:target});})),focusFallback:()=>document.getElementById('fallback')});api.action=action;
+   return h('div',null,action.phase!=='succeeded'&&h('button',{id:'trigger',onClick:action.request},'Delete record'),h('h2',{id:'fallback',tabIndex:-1},'Remaining records'),h('span',{id:'phase'},action.phase));
+  }fixtureRoot=createRoot(document.getElementById('root'));fixtureRoot.render(h(Fixture));
+ });await phase('idle');await page.getByRole('button',{name:'Delete record'}).click();await page.evaluate(()=>harness.setTarget('second'));await page.waitForFunction(()=>harness.observedTarget==='second');
+ check(await page.evaluate(()=>harness.action.target)==='first','ACTION-TARGET: confirmation retains the named target when parent options change');
+ await page.evaluate(()=>harness.action.confirm());await page.evaluate(()=>harness.writes[0]());await phase('succeeded');
+ check(await page.evaluate(()=>harness.data.join(','))==='second','ACTION-TARGET: confirmed mutation applies only to the captured target');
+ check(await page.locator('#fallback').evaluate(el=>el===document.activeElement),'ACTION-FOCUS: removed trigger restores logical fallback after DOM commit');
+ // Review: correcting preserves answers; only a real accepted receipt completes the process.
+ check(await page.evaluate(() => typeof Altitude.useReviewSubmit === 'function'), 'REVIEW-RETAIN: review hook is exported');
+ await page.evaluate(() => {
+  fixtureRoot.unmount(); const h=React.createElement; const api={writes:[],data:[]}; window.harness=api;
+  function Fixture(){const review=Altitude.useReviewSubmit({initialValue:{name:'Original',note:'Keep this answer'},validate:value=>value.name?{}:{name:'Enter a name.'},
+   submit:draft=>new Promise(resolve=>api.writes.push(result=>{if(result.ok)api.data.push(draft);resolve(result);}))});api.review=review;
+   return h('div',null,h('span',{id:'phase'},review.phase),h(Altitude.WorkflowStatus,null,review.status),review.receipt&&h('p',null,review.receipt.reference));
+  } fixtureRoot=createRoot(document.getElementById('root'));fixtureRoot.render(h(Fixture));
+ }); await phase('editing');
+ await page.evaluate(() => harness.review.review()); await phase('review'); await page.evaluate(() => harness.review.correct()); await phase('editing');
+ await page.evaluate(() => {harness.review.setField('name','Corrected'); harness.review.review();}); await phase('review');
+ check(await page.evaluate(() => harness.review.draft.note) === 'Keep this answer','REVIEW-RETAIN: correcting preserves other answers');
+ await page.evaluate(() => {harness.review.submit();harness.review.submit();}); await phase('submitting');
+ check(await page.evaluate(() => harness.writes.length===1 && harness.review.receipt===undefined),'ACTION-TRUE-OUTCOME: submission locks and no premature receipt');
+ await page.evaluate(() => harness.writes[0]({ok:false,error:'Connection interrupted. Try again.'})); await phase('review');
+ check(await page.evaluate(() => harness.review.draft.name) === 'Corrected','REVIEW-RECOVERY: failed/interrupted submit preserves corrected data');
+ await page.evaluate(() => {void harness.review.submit();}); await page.evaluate(() => harness.writes[1]({ok:true,receipt:{reference:'Accepted #42'}})); await phase('complete');
+ check(await page.evaluate(() => harness.data.length===1 && harness.data[0].name==='Corrected' && harness.review.receipt.reference==='Accepted #42'),'REVIEW-CONFIRMATION: persistent receipt corresponds to actual accepted data');
+ await page.evaluate(() => {harness.review.correct();harness.review.setField('name','Wrong');harness.review.submit();}); await phase('complete');
+ check(await page.evaluate(() => harness.writes.length)===2,'REVIEW-CONFIRMATION: completed transaction cannot accidentally resubmit');
+ await page.evaluate(() => {
+  fixtureRoot.unmount(); const h=React.createElement;const api={writes:0};window.harness=api;
+  function Fixture(){const review=Altitude.useReviewSubmit({initialValue:{name:'Ready'},validate:()=>({}),submit:()=>{api.writes++;return {ok:true};}});api.review=review;return h('span',{id:'phase'},review.phase);}
+  fixtureRoot=createRoot(document.getElementById('root'));fixtureRoot.render(h(Fixture));
+ });await phase('editing');await page.evaluate(()=>{void harness.review.submit();});
+ check(await page.evaluate(()=>harness.writes)===0,'REVIEW-PROCESS: cannot submit before review');
+ await page.evaluate(()=>{harness.review.review();void harness.review.submit();});await page.waitForFunction(()=>harness.writes===1);await phase('review');
+ check(await page.evaluate(()=>harness.review.receipt===undefined && !!harness.review.error),'REVIEW-CONFIRMATION: malformed JavaScript success without receipt is recoverable failure');
+ // Assistant conversation (#285): a turn that can't be sent twice, drops events from a superseded stream, keeps the partial
+ // answer on Stop, completes only when the stream does, says errors in words, and shows an unfinished answer after a
+ // reload as interrupted.
+ check(await page.evaluate(() => typeof Altitude.useAssistantTurn === 'function'), 'CONVO-DUPLICATE: the turn hook is exported');
+ const mountTurn = (restored) => page.evaluate((restored) => {
+  fixtureRoot.unmount(); const h = React.createElement; const api = { streams: [] }; window.harness = api;
+  const stream = (input, signal) => {
+   const q = []; let wake = null, done = false, err = null;
+   const s = { input, signal, push: (t) => { q.push(t); wake?.(); }, end: () => { done = true; wake?.(); }, fail: (e) => { err = e; wake?.(); } };
+   api.streams.push(s);
+   return (async function* () { for (;;) { if (q.length) { yield q.shift(); continue; } if (err) throw err; if (done) return; await new Promise((r) => { wake = r; }); wake = null; } })();
+  };
+  function Fixture() { const turn = Altitude.useAssistantTurn({ stream, restored: restored ?? undefined, locale: 'en-US' }); api.turn = turn; return h('span', { id: 'phase' }, turn.state); }
+  fixtureRoot = createRoot(document.getElementById('root')); fixtureRoot.render(h(Fixture));
+ }, restored ?? null);
+ await mountTurn(); await phase('ready');
+ await page.evaluate(() => { harness.turn.submit('What changed?'); harness.turn.submit('What changed?'); }); await phase('submitted');
+ check(await page.evaluate(() => harness.streams.length) === 1, 'CONVO-DUPLICATE: a double submit sends once');
+ await page.evaluate(() => harness.streams[0].push('The billing ')); await phase('streaming');
+ check(await page.evaluate(() => harness.turn.promptStatus === 'streaming' && harness.turn.messageStatus === 'streaming'), 'CONVO-COMPLETE: streaming maps to the composer and the message');
+ await page.evaluate(() => harness.turn.stop()); await phase('stopped');
+ await page.evaluate(() => harness.streams[0].push('migration')); await page.waitForTimeout(50);
+ check(await page.evaluate(() => harness.turn.text) === 'The billing ', 'CONVO-STALE: Stop keeps the partial answer and drops what arrives after');
+ await page.evaluate(() => harness.turn.retry()); await phase('submitted');
+ await page.evaluate(() => { harness.streams[0].push(' late'); harness.streams[1].push('Two risks.'); }); await phase('streaming');
+ check(await page.evaluate(() => harness.turn.text) === 'Two risks.' && await page.evaluate(() => harness.streams[1].input) === 'What changed?', 'CONVO-STALE: retry sends the kept input and ignores the superseded stream');
+ check(await page.evaluate(() => harness.turn.state) === 'streaming', 'CONVO-COMPLETE: text alone never completes an answer');
+ await page.evaluate(() => harness.streams[1].end()); await phase('complete');
+ check(await page.evaluate(() => harness.turn.messageStatus) === 'complete', 'CONVO-COMPLETE: the answer settles when the stream says so');
+ await page.evaluate(() => harness.turn.submit('And now?')); await phase('submitted');
+ await page.evaluate(() => harness.streams[2].fail(new Altitude.AssistantError('rate-limited', undefined, new Date(2026, 9, 30, 15, 40).getTime()))); await phase('failed');
+ const failed = await page.evaluate(() => ({ text: harness.turn.errorText, input: harness.turn.input, prompt: harness.turn.promptStatus }));
+ check(failed.text === "You've reached this hour's limit. Try again at 3:40 PM." && failed.input === 'And now?' && failed.prompt === 'error', `CONVO-ERRORS: a rate limit says when, and the message is kept (${JSON.stringify(failed)})`);
+ check(await page.evaluate(() => [Altitude.assistantErrorText({ kind: 'context-full' }), Altitude.assistantErrorText({ kind: 'offline' })].every((t) => t && !/something went wrong/i.test(t))), 'CONVO-ERRORS: each kind has its own words');
+ await page.evaluate(() => { harness.turn.retry(); }); await phase('submitted');
+ await page.evaluate(() => harness.streams[3].push('Hi')); await phase('streaming');
+ await page.evaluate(() => harness.turn.awaitInput(true)); await phase('awaiting-input');
+ await page.evaluate(() => harness.turn.submit('Interrupting')); await page.waitForTimeout(30);
+ check(await page.evaluate(() => harness.streams.length) === 4, 'CONVO-DUPLICATE: nothing is sent over a turn waiting for the person');
+ await mountTurn({ input: 'What changed?', text: 'The billing', complete: false }); await phase('interrupted');
+ check(await page.evaluate(() => harness.turn.text === 'The billing' && harness.turn.messageStatus === 'error'), 'CONVO-RELOAD: an unfinished answer after a reload is interrupted, never complete');
+ await mountTurn({ input: 'What changed?', text: 'Done.', complete: true }); await phase('complete');
+ check(await page.evaluate(() => harness.turn.messageStatus) === 'complete', 'CONVO-RELOAD: a completed answer is restored as complete');
+ check(errors.length === 0, `no browser errors: ${errors.join('; ')}`);
+ console.log(`Workflow patterns: ${checks} assertions passed; Chromium ${browser.version()}.`);
+} finally { await browser.close(); await rm(temp, { recursive:true, force:true }); }

package/dist/guidance/references/build/checks/primary-scope.mjs

@@ -0,0 +1,49 @@
+// One primary per view (law 1, ALT-VISUAL-002): with devChecks, two visible primary Buttons in one page warn once,
+// naming them and law 1; one primary on the page plus one in a Dialog doesn't (a Dialog is its own view); PrimaryScope
+// separates independent parts; a hidden primary doesn't count; without devChecks in this build nothing is checked.
+// Renders its own trees into a preview page (test/p-Button-daylight.html); exits non-zero on a failure.
+import { chromium } from 'playwright-core';
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+const T = new URL('../test/', import.meta.url).pathname;
+let pass = 0, fail = 0;
+const expect = (c, m) => { if (c) pass++; else { fail++; console.log('FAIL', m); } };
+const page = await browser.newPage({ viewport: { width: 960, height: 600 } });
+const warnings = [];
+page.on('console', (m) => { if (m.type() === 'warning') warnings.push(m.text()); });
+await page.goto(`file://${T}p-Button-daylight.html`);
+await page.waitForTimeout(300);
+
+// Renders a tree in a fresh root and returns the warnings it caused.
+const run = async (tree) => {
+  warnings.length = 0;
+  await page.evaluate((tree) => new Promise((done) => {
+    const A = window.Altitude, h = React.createElement;
+    const P = (label, props = {}) => h(A.Button, { variant: 'primary', key: label, ...props }, label);
+    const S = (label) => h(A.Button, { variant: 'secondary', key: label }, label);
+    const trees = {
+      two: () => h(A.AltitudeProvider, { devChecks: true }, P('Save'), P('Publish')),
+      one: () => h(A.AltitudeProvider, { devChecks: true }, P('Save'), S('Cancel')),
+      dialog: () => h(A.AltitudeProvider, { devChecks: true }, P('Invite members'), h(A.Dialog, { open: true, title: 'Invite', footer: P('Send invites') })),
+      scoped: () => h(A.AltitudeProvider, { devChecks: true }, h(A.PrimaryScope, null, P('Upgrade')), h(A.PrimaryScope, null, P('Connect'))),
+      hidden: () => h(A.AltitudeProvider, { devChecks: true }, P('Save'), h('div', { hidden: true }, P('Publish'))),
+      off: () => h(A.AltitudeProvider, null, P('Save'), P('Publish')),
+    };
+    const d = document.createElement('div'); document.body.append(d);
+    const root = ReactDOM.createRoot(d);
+    root.render(trees[tree]());
+    setTimeout(() => { root.unmount(); d.remove(); done(); }, 400);
+  }), tree);
+  return warnings.filter((w) => w.includes('Law 1'));
+};
+
+const two = await run('two');
+expect(two.length === 1 && two[0].includes('"Save"') && two[0].includes('"Publish"'), `two visible primaries warn once, naming them (${two.join(' | ')})`);
+expect((await run('one')).length === 0, 'one primary and a secondary: no warning');
+expect((await run('dialog')).length === 0, 'a Dialog is its own view');
+expect((await run('scoped')).length === 0, 'PrimaryScope separates independent parts');
+expect((await run('hidden')).length === 0, 'a hidden primary doesn\'t count');
+expect((await run('off')).length === 0, 'without devChecks (no NODE_ENV in this build) nothing is checked');
+
+console.log(`Primary scope: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

package/dist/guidance/references/build/checks/render-tells.mjs

@@ -0,0 +1,72 @@
+// The tells of generated interfaces that only show once a page is rendered (Distinctiveness, #321). Warnings, never
+// failures: a row of genuinely equal items is legitimate, as Charts says of dashboard cards, so a person decides.
+//   LA4  three or more sibling surfaces of the same size, laid out together, none of them leading: no primary action and
+//        no larger title in one of them, and no larger title just before the set (a hero number above a row of secondary
+//        ones leads it). A set of choices (radios, options, tabs) is exempt: options should weigh the same, and the
+//        current or recommended one is said in words;
+//   LA6  a view of eight or more different sections stacked with one gap, so nothing groups.
+// It opens every preview (test/p-<Name>-daylight.html, after a render or PAGES_ONLY=1) at 960 CSS px. An element inside
+// [data-tells-ignore="<id> <reason>"] is skipped for that id. TY5 (a font that never loads) is in tells-lint.mjs: the
+// preview pages leave the font import out on purpose, so it can't be judged here.
+//   node checks/render-tells.mjs              every preview
+//   node checks/render-tells.mjs Card,Stat    just these
+import { chromium } from 'playwright-core';
+import { existsSync, readdirSync } from 'fs';
+const T = new URL('../test/', import.meta.url).pathname;
+const root = new URL('../..', import.meta.url).pathname;
+const names = process.argv[2] ? process.argv[2].split(',') : readdirSync(root + 'project/components').filter((d) => existsSync(`${root}project/components/${d}/preview.html`)).sort();
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+
+const measure = () => {
+  const out = [];
+  const ignored = (e, id) => { const s = e.closest('[data-tells-ignore]'); return !!s && new RegExp(`\\b${id}\\s+[A-Za-z]`).test(s.dataset.tellsIgnore); };
+  const visible = (e) => { const r = e.getBoundingClientRect(), cs = getComputedStyle(e); return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' && +cs.opacity !== 0; };
+  const name = (e) => `${e.tagName.toLowerCase()}${typeof e.className === 'string' && e.className.trim() ? '.' + e.className.trim().split(/\s+/).slice(0, 2).join('.') : ''}`;
+  const transparent = (c) => c === 'rgba(0, 0, 0, 0)' || c === 'transparent';
+  const surface = (e) => { const cs = getComputedStyle(e); return cs.boxShadow !== 'none' || (!transparent(cs.backgroundColor) && cs.backgroundColor !== getComputedStyle(e.parentElement).backgroundColor && parseFloat(cs.borderTopLeftRadius) > 0); };
+  const near = (a, b, t) => Math.abs(a - b) <= t * Math.max(a, b);
+  const big = (e) => [e, ...e.querySelectorAll('*')].some((x) => parseFloat(getComputedStyle(x).fontSize) >= 28 && x.textContent.trim());
+  const leads = (e) => !!e.querySelector('.alt-btn[data-variant="primary"]') || big(e);
+  // A larger title or number among the set's container's earlier siblings, or its parent's, leads the set.
+  const ledFromBefore = (p) => [p, p.parentElement].filter(Boolean).some((n) => { for (let s = n.previousElementSibling; s; s = s.previousElementSibling) if (visible(s) && big(s)) return true; return false; });
+  const choice = (e) => e.matches('[role="radio"], [role="option"], [role="tab"], [role="checkbox"]') || !!e.closest('[role="radiogroup"], [role="listbox"], [role="tablist"]');
+  for (const p of document.body.querySelectorAll('*')) {
+    const kids = [...p.children].filter(visible);
+    if (kids.length < 3) continue;
+    // LA4: a set of same-sized cards, in a row or a grid, none leading.
+    const cards = kids.filter((k) => { const r = k.getBoundingClientRect(); return r.width >= 120 && r.height >= 64 && surface(k); });
+    if (cards.length >= 3 && cards.length >= kids.length * 0.75 && !ignored(p, 'LA4')) {
+      const rs = cards.map((c) => c.getBoundingClientRect());
+      const w = rs.map((r) => r.width).sort((a, b) => a - b)[rs.length >> 1], h = rs.map((r) => r.height).sort((a, b) => a - b)[rs.length >> 1];
+      const same = rs.every((r) => near(r.width, w, 0.05) && near(r.height, h, 0.05));
+      const together = rs.some((r, i) => rs.some((q, j) => i !== j && Math.abs(r.top - q.top) < 2));
+      const leading = cards.filter(leads).length;
+      if (same && together && (leading === 0 || leading === cards.length) && !cards.every(choice) && !ledFromBefore(p))
+        out.push(['LA4', `${cards.length} equal surfaces (${Math.round(w)}×${Math.round(h)}) in ${name(p)}, none leading`]);
+    }
+    // LA6: different sections, stacked, all one gap apart.
+    if (kids.length >= 8 && !ignored(p, 'LA6')) {
+      const rs = kids.map((k) => k.getBoundingClientRect());
+      const stacked = rs.every((r, i) => i === 0 || r.top >= rs[i - 1].bottom - 1);
+      const kinds = new Set(kids.map((k) => k.tagName + '.' + (typeof k.className === 'string' ? k.className.split(/\s+/)[0] : ''))).size;
+      const gaps = new Set(rs.slice(1).map((r, i) => Math.round(r.top - rs[i].bottom)));
+      if (stacked && kinds >= 3 && gaps.size === 1 && [...gaps][0] > 0) out.push(['LA6', `${kids.length} sections in ${name(p)}, all ${[...gaps][0]}px apart`]);
+    }
+  }
+  return out;
+};
+
+const findings = [];
+for (const n of names) {
+  const file = `${T}p-${n}-daylight.html`;
+  if (!existsSync(file)) { console.error(`render-tells: no ${file}; render first (node shoot.mjs "" daylight 960, or PAGES_ONLY=1)`); process.exit(1); }
+  const page = await browser.newPage({ viewport: { width: 960, height: 900 } });
+  await page.goto('file://' + file);
+  await page.waitForTimeout(600);
+  for (const [id, text] of await page.evaluate(measure)) findings.push({ id, name: n, text });
+  await page.close();
+}
+await browser.close();
+
+for (const f of findings) console.log(process.env.GITHUB_ACTIONS ? `::warning title=Tell ${f.id} in ${f.name}::${f.text}` : `${f.id}  ${f.name}: ${f.text}`);
+console.log(`render-tells: ${names.length} previews, ${findings.length} warning(s)${findings.length ? '. Each is a judgement: give one thing the lead, group with spacing, or mark it data-tells-ignore="<id> <reason>" (project/Distinctiveness.md).' : ''}`);

package/dist/guidance/references/build/checks/screen-layout-pattern.mjs

@@ -0,0 +1,111 @@
+// Screen layout pattern: each frame's stated lead (the design record in its fixture's first lines) is the first thing
+// after the page header and, where the record says so, the largest region; there's at most one primary action and no
+// navigation sidebar. The editor saves as a status and publishes with its outcome taking focus; the decision puts its
+// consequence and both choices before the evidence, asks for a decline's reason in place, returns focus to Decline on
+// Escape, and replaces the choice with the outcome; the report's takeaway heads the chart that leads, before any other
+// heading after the title. Unled equal sets and flat stacks are render-tells.mjs's (it opens every preview). Run after a
+// render of every preview (it opens test/p-ScreenLayout*-daylight.html); exits non-zero on a failure.
+import { chromium } from 'playwright-core';
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+const T = new URL('../test/', import.meta.url).pathname;
+let pass = 0, fail = 0;
+const expect = (c, m) => { if (c) pass++; else { fail++; console.log('FAIL', m); } };
+const open = async (name) => {
+  const page = await browser.newPage({ viewport: { width: 960, height: 1000 } });
+  await page.goto(`file://${T}p-${name}-daylight.html`);
+  await page.waitForTimeout(500);
+  return page;
+};
+// The frame: main's regions in order, with their areas; the primary buttons; any navigation besides the breadcrumb.
+const frame = (page) => page.evaluate(() => {
+  const main = document.querySelector('main'), kids = [...main.children].filter((c) => getComputedStyle(c).display !== 'none');
+  return {
+    regions: kids.map((c) => ({ cls: typeof c.className === 'string' ? c.className : '', tag: c.tagName, area: c.getBoundingClientRect().width * c.getBoundingClientRect().height })),
+    primaries: [...document.querySelectorAll('button[data-variant="primary"]')].filter((b) => b.getClientRects().length).length,
+    navs: [...document.querySelectorAll('nav, [role="navigation"]')].filter((n) => !n.closest('.alt-page-head')).length,
+  };
+});
+const leads = (f, cls, largest) => {
+  const i = f.regions.findIndex((r) => r.cls.split(' ').includes(cls));
+  expect(f.regions[0]?.cls.includes('alt-page-head') && i === 1, `${cls} is the first thing after the page header (${f.regions.map((r) => r.cls || r.tag).join(', ')})`);
+  if (largest) expect(i >= 0 && f.regions.every((r, j) => j === i || r.area < f.regions[i].area), `${cls} is the largest region`);
+  expect(f.primaries <= 1 && f.navs === 0, `one primary action at most and no navigation sidebar (${f.primaries} primary, ${f.navs} nav)`);
+};
+const focused = (page) => page.evaluate(() => { const a = document.activeElement; return { id: a?.id || '', text: a?.textContent?.trim() || '', role: a?.getAttribute('role') || '', tag: a?.tagName || '' }; });
+
+{ // Focused editor.
+  const page = await open('ScreenLayoutEditor');
+  leads(await frame(page), 'le-body', true);
+  const area = (sel) => page.evaluate((s) => { const r = document.querySelector(s).getBoundingClientRect(); return r.width * r.height; }, sel);
+  expect(await area('.le-draft') > 2 * await area('.le-side'), 'the draft fills the column; its details sit beside it, narrower');
+  expect(await page.locator('.le-draft').evaluate((d, s) => d.compareDocumentPosition(document.querySelector(s)) & Node.DOCUMENT_POSITION_FOLLOWING, '.le-side') > 0, 'the draft comes before its details in reading order');
+  await page.getByLabel('Note').fill('A first line.');
+  expect(/Saving/.test(await page.locator('.alt-sync').textContent()), 'typing saves as a status, not a second button');
+  await page.waitForTimeout(1000);
+  expect(/Saved/.test(await page.locator('.alt-sync').textContent()), 'and settles to Saved');
+  await page.locator('#le-title').fill('');
+  await page.getByRole('button', { name: 'Publish' }).click();
+  await page.waitForTimeout(200);
+  expect((await focused(page)).id === 'le-title' && /Give the note a title/.test(await page.locator('.le-draft').textContent()), 'publishing without a title says so and focuses the title');
+  await page.locator('#le-title').fill('Saved views');
+  await page.getByRole('button', { name: 'Publish' }).click();
+  await page.waitForTimeout(1000);
+  const f = await focused(page);
+  expect(f.role === 'status' && /^Published/.test(f.text), `the outcome takes focus where the task ends (${f.role} “${f.text.slice(0, 30)}”)`);
+  expect(/View the changelog/.test(f.text) && (await frame(page)).primaries === 0, 'it points to what comes next, and Publish is gone');
+  await page.close();
+}
+
+{ // Decision.
+  const page = await open('ScreenLayoutDecision');
+  leads(await frame(page), 'ld-choice', false);
+  const order = await page.evaluate(() => {
+    const choice = document.querySelector('.ld-choice'), evidence = document.querySelector('.ld-evidence');
+    return { consequence: !!choice.querySelector('.ld-consequence'), buttons: [...choice.querySelectorAll('button')].map((b) => b.textContent.trim()),
+      above: choice.getBoundingClientRect().bottom <= evidence.getBoundingClientRect().top, title: document.querySelector('.alt-page-head h1, .alt-page-head h2')?.textContent };
+  });
+  expect(/\?$/.test(order.title || ''), `the question is the title (${order.title})`);
+  expect(order.consequence && order.buttons.join() === 'Approve refund,Decline' && order.above, `the consequence and both choices come before the evidence (${order.buttons.join()})`);
+  await page.getByRole('button', { name: 'Decline' }).click();
+  await page.waitForTimeout(200);
+  expect((await focused(page)).id === 'ld-reason', 'Decline asks for its reason in place, focused');
+  await page.keyboard.press('Escape');
+  await page.waitForTimeout(200);
+  expect((await focused(page)).text === 'Decline', 'Escape cancels and returns focus to Decline');
+  await page.keyboard.press('Enter');
+  await page.waitForTimeout(200);
+  await page.getByRole('button', { name: 'Send decline' }).click();
+  await page.waitForTimeout(200);
+  expect((await focused(page)).id === 'ld-reason' && /Say why/.test(await page.locator('.ld-choice').textContent()), 'a decline needs a reason, and says so');
+  await page.locator('#ld-reason').fill('The duplicate invoice was already credited on 3 October.');
+  await page.getByRole('button', { name: 'Send decline' }).click();
+  await page.waitForTimeout(1000);
+  let f = await focused(page);
+  expect(f.role === 'status' && /^Refund declined/.test(f.text) && /Next request/.test(f.text), `the outcome replaces the choice, takes focus and points to the next request (“${f.text.slice(0, 30)}”)`);
+  await page.reload(); await page.waitForTimeout(500);
+  await page.getByRole('button', { name: 'Approve refund' }).click();
+  await page.waitForTimeout(1000);
+  f = await focused(page);
+  expect(f.role === 'status' && /^Refund approved/.test(f.text) && (await frame(page)).primaries === 0, 'approving reports the outcome in its place');
+  await page.close();
+}
+
+{ // Report.
+  const page = await open('ScreenLayoutReport');
+  const f = await frame(page);
+  leads(f, 'lr-lead', true);
+  const r = await page.evaluate(() => {
+    // The takeaway is set as the figure's heading (ChartContainer's .alt-chart-takeaway): it must come before, and read
+    // at least as large as, the first heading after the title.
+    const take = document.querySelector('.lr-lead .alt-chart-takeaway'), h = [...document.querySelectorAll('main h2, main h3')].find((e) => !e.closest('.alt-page-head') && !e.closest('.lr-lead'));
+    const chart = document.querySelector('.lr-lead').getBoundingClientRect(), stats = document.querySelector('.alt-stat-group, [aria-label="October in numbers"]').getBoundingClientRect();
+    return { first: take?.textContent || '', before: !!take && !!h && !!(take.compareDocumentPosition(h) & Node.DOCUMENT_POSITION_FOLLOWING), larger: !!take && !!h && parseFloat(getComputedStyle(take).fontSize) >= parseFloat(getComputedStyle(h).fontSize), hero: document.querySelectorAll('.alt-stat[data-size="hero"]').length, ratio: (chart.width * chart.height) / (stats.width * stats.height), statsBelow: stats.top >= chart.bottom };
+  });
+  expect(r.before && r.larger && /^Signups doubled/.test(r.first), `the takeaway heads the chart that leads, before and above every heading after the title (“${r.first.slice(0, 30)}”)`);
+  expect(r.hero === 0 && r.statsBelow && r.ratio > 2, `the secondary numbers follow the chart, smaller and grouped (area ×${r.ratio.toFixed(1)})`);
+  await page.close();
+}
+
+console.log(`Screen layout pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

package/dist/guidance/references/build/checks/semantics.mjs

@@ -0,0 +1,72 @@
+import { tokensCss } from '../../scripts/tokens-css.mjs';
+import { chromium } from 'playwright-core';
+import { build } from 'esbuild';
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, '../..');
+const scratch = await mkdtemp(resolve(tmpdir(), 'altitude-semantics-'));
+const reactRoot = process.env.ALT_REACT19 ? resolve(repo, 'node_modules') : resolve(repo, 'build/node_modules');
+await build({entryPoints: [resolve(here, 'fixtures/semantics.tsx')], bundle: true, outfile: resolve(scratch, 'fixture.js'), alias: {react: resolve(reactRoot, 'react'), 'react-dom': resolve(reactRoot, 'react-dom')}, define: {'process.env.NODE_ENV': '"development"'}});
+const css = await readFile(resolve(repo, 'project/components/bundle.css'), 'utf8');
+await writeFile(resolve(scratch, 'index.html'), `<style>${tokensCss(resolve(repo, 'project/tokens.json'))}${css}</style><div id="root"></div><script src="fixture.js"></script>`);
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+let pass = 0, fail = 0;
+const expect = (condition, label) => { if (condition) { pass++; console.log('PASS', label); } else { fail++; console.error('FAIL', label); } };
+const page = await browser.newPage();
+page.on('pageerror', e => { fail++; console.error('FAIL page error', e.message); });
+await page.goto('file://' + resolve(scratch, 'index.html'));
+await page.waitForSelector('#surface');
+const count = async () => Number(await page.locator('#count').textContent());
+const activate = async (selector, key) => { await page.locator(selector).focus(); await page.keyboard.press(key); };
+await activate('#surface', 'Enter'); expect(await count() === 1, 'AUDIT Surface Enter activates');
+await page.locator('#surface').focus(); await page.keyboard.down('Space'); expect(await count() === 1, 'Surface Space waits for release'); await page.keyboard.up('Space'); expect(await count() === 2, 'AUDIT Surface Space activates');
+expect(await page.locator('#surface').getAttribute('role') === 'button', 'Surface announces button semantics');
+let before = await count();
+await activate('#link', 'Enter'); expect(await count() === before + 1 && await page.locator('#link').getAttribute('role') === null, 'Native link keeps link semantics and single activation');
+before = await count();
+await activate('#native', 'Enter'); await activate('#native', 'Space'); expect(await count() === before + 2, 'Native Surface activates exactly once per key');
+before = await count(); await activate('#nested button', 'Space');
+expect(await count() === before && await page.locator('#nested-count').textContent() === '1', 'Nested control does not activate containing Surface');
+before = await count(); await activate('#cancelled', 'Enter'); expect(await count() === before, 'Consumer preventDefault cancels synthetic activation');
+await activate('#disabled', 'Enter'); await page.locator('#disabled').click({force: true}); expect(await count() === before, 'Disabled Surface does not activate');
+await page.locator('#disabled-link').click({force:true}); await activate('#disabled-link','Enter'); expect(!page.url().includes('#disabled-navigation') && await page.locator('#disabled-link').getAttribute('tabindex') === '-1', 'Disabled native link without callback cannot navigate or remain in tab order');
+expect(await page.locator('#disabled-link').getAttribute('href') === null && await page.locator('#disabled-link').getAttribute('role') === 'link', 'Disabled link has no context-menu/middle-click destination but retains its semantic role');
+const description = () => page.getByLabel('Title', {exact: true}).evaluate(el => ({ids: el.getAttribute('aria-describedby').split(/\s+/), required: el.required, texts: el.getAttribute('aria-describedby').split(/\s+/).map(id => document.getElementById(id)?.textContent)}));
+let desc = await description();
+expect(desc.ids.length === 3 && desc.texts.every(Boolean) && desc.texts.includes('External description') && desc.texts.includes('Helpful hint'), 'AUDIT Field composes existing hint and error IDs without dangling references');
+expect(new Set(desc.ids).size === desc.ids.length && desc.required, 'Field deduplicates IDs and preserves child required');
+await page.locator('#toggle-error').click(); desc = await description(); expect(desc.ids.length === 2 && desc.texts.every(Boolean), 'Field removes stale error reference after recovery');
+expect(!await page.locator('#form').evaluate(el => el.checkValidity()), 'AUDIT Empty required Select fails native form validation');
+await page.locator('#submit').click(); expect(await page.locator('#choice').evaluate(el => document.activeElement === el), 'Invalid submission focuses visible Select trigger');
+expect(await page.locator('#choice').getAttribute('aria-invalid') === 'true' && await page.locator('#choice').evaluate(el => el.getAttribute('aria-describedby')?.split(/\s+/).some(id => document.getElementById(id)?.textContent.includes('Choose a record.'))), 'Required failure announces a linked actionable error on the visible control');
+const choose = async (id, text) => { await page.locator(id).click(); await page.getByRole('option', {name: text, exact: true}).click(); };
+await choose('#choice', 'Alpha'); expect(await page.locator('#form').evaluate(el => el.checkValidity()), 'Selected required Select satisfies native validation');
+expect(await page.locator('#choice').getAttribute('aria-invalid') === null && await page.getByText('Choose a record.',{exact:true}).count() === 0, 'Choosing a valid value clears the native required error and association');
+expect(await page.locator('#form').evaluate(el => new FormData(el).get('choice')) === 'a', 'Select contributes selected value to FormData');
+await choose('#default-choice', 'Beta'); await choose('#controlled-choice', 'Beta');
+await page.locator('#reset').click(); await page.waitForTimeout(30);
+expect(await page.locator('#choice').textContent() === 'Choose…' && await page.locator('#default-choice').textContent() === 'Alpha', 'Reset restores uncontrolled defaults and visible labels');
+expect(await page.locator('#choice').getAttribute('aria-invalid') === null && await page.getByText('Choose a record.',{exact:true}).count() === 0, 'Reset clears attempted-validation feedback even for an empty default');
+await page.locator('#form').evaluate(el=>el.checkValidity()); await page.locator('#reset').click(); await page.waitForTimeout(30); expect(await page.locator('#choice').getAttribute('aria-invalid') === null, 'Reset after a failed validation clears the required error');
+expect(await page.locator('#controlled-choice').textContent() === 'Beta' && await page.locator('#form').evaluate(el => new FormData(el).get('controlled')) === 'b', 'Controlled Select remains synchronized after reset');
+await choose('#choice', 'Alpha');
+await page.locator('#form').evaluate(el => el.addEventListener('reset', event => event.preventDefault(), {once: true}));
+await page.locator('#reset').click(); await page.waitForTimeout(30);
+expect(await page.locator('#choice').textContent() === 'Alpha', 'Cancelled reset retains Select value');
+await page.locator('#reset-controlled').click(); await page.locator('#reset').click(); await page.waitForTimeout(30);
+expect(await page.locator('#controlled-choice').textContent() === 'Alpha' && await page.locator('#form').evaluate(el => new FormData(el).get('controlled')) === 'a', 'Application reset handler can update controlled value and form data together');
+expect(!await page.locator('#unnamed-form').evaluate(el => el.checkValidity()), 'Required unnamed Select with explicit empty option validates');
+await page.locator('#disable-choice').click(); expect(await page.locator('#form').evaluate(el => el.checkValidity() && !new FormData(el).has('choice')), 'Disabled required Select excluded from validation and submission');
+await page.locator('#open-dialog').click(); await page.waitForTimeout(40);
+expect(await page.locator('.alt-dialog').evaluate(el => document.activeElement === el), 'Sparse Dialog begins on panel');
+await page.keyboard.press('Shift+Tab'); expect(await page.locator('.alt-dialog-close').evaluate(el => document.activeElement === el), 'AUDIT Sparse Dialog Shift+Tab wraps to close');
+expect(await page.locator('.alt-stage').evaluate(el => el.inert), 'Dialog isolates background');
+await page.keyboard.press('Escape'); await page.waitForTimeout(400);
+expect(await page.locator('#open-dialog').evaluate(el => document.activeElement === el) && !await page.locator('.alt-stage').evaluate(el => el.inert), 'Dialog restores invoker and releases background');
+await page.locator('#open-empty').click(); await page.waitForTimeout(40); await page.keyboard.press('Tab'); await page.keyboard.press('Shift+Tab');
+expect(await page.locator('.alt-dialog').evaluate(el => document.activeElement === el), 'No-control Dialog keeps both Tab directions on panel');
+await browser.close(); await rm(scratch, {recursive: true, force: true});
+console.log(`${pass} passed, ${fail} failed`); if (fail) process.exitCode = 1;