altitude-design 0.2.0 → 0.3.0

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

@@ -0,0 +1,63 @@
+// Billing pattern: quotas are Meters (never Progress) that say their state in words; the rest of the cycle is projected
+// (hatched, and said); the estimate says how it's computed; a plan change is reviewed with its proration before it's
+// confirmed, the review heading takes focus, and only a completed change says so; a downgrade lists what will be lost
+// and its button is a danger one; a locked feature stays live with its plan plate; a failed payment is a page banner
+// that asks for action; invoice amounts are formatted currency. Run after a render of every preview (it opens
+// test/p-BillingPattern-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: 1200 } });
+await page.goto(`file://${T}p-BillingPattern-daylight.html`);
+await page.waitForTimeout(600);
+
+const usage = await page.evaluate(() => { const s = document.querySelector('[aria-labelledby="bl-usage-h"]');
+  return { meters: s.querySelectorAll('.alt-meter').length, progress: s.querySelectorAll('.alt-progress, [role="progressbar"]').length, text: s.textContent }; });
+expect(usage.meters === 3 && usage.progress === 0, `quotas are Meters, never Progress (${usage.meters} meters, ${usage.progress} progress)`);
+expect(/8 of 10/.test(usage.text) && /Near limit/.test(usage.text) && /Over limit/.test(usage.text), 'each quota says its reading and state in words');
+expect(/the last two weeks of the cycle are projected/i.test(usage.text) && await page.locator('[aria-labelledby="bl-calls-h"] [data-status="projected"]').count() === 2, 'the rest of the cycle is projected, and said');
+expect(/10 seats × €24, plus €48/.test(usage.text), 'the estimate says how it is computed');
+
+await page.getByRole('button', { name: 'Review change' }).click();
+await page.waitForTimeout(200);
+expect(await page.getByText('Choose a plan you’re not on.').count() === 1, 'reviewing without a change says why it can’t');
+await page.getByRole('radio', { name: /Business/ }).click();
+await page.getByRole('button', { name: 'Review change' }).click();
+await page.waitForTimeout(300);
+const review = await page.evaluate(() => ({ focus: document.activeElement.textContent, text: document.querySelector('.bl-proration')?.textContent }));
+expect(review.focus === 'Upgrade to Business?' && /You’ll pay €\d+\.\d\d today for the rest of this cycle, then €480\.00\/month/.test(review.text), `the review states the proration and takes focus (${JSON.stringify(review)})`);
+await page.getByRole('button', { name: 'Upgrade to Business' }).click();
+await page.waitForTimeout(300);
+expect(await page.evaluate(() => [...document.querySelectorAll('[aria-labelledby="bl-plan-h"] [role="status"], [aria-labelledby="bl-plan-h"] .alt-workflow-status')].some((n) => n.textContent === 'Changing plan…')), 'the change is pending while it’s made');
+expect(await page.getByRole('heading', { name: 'You’re on Business' }).count() === 0, 'and nothing claims it’s done yet');
+await page.waitForTimeout(900);
+expect(await page.getByRole('heading', { name: 'You’re on Business' }).count() === 1, 'a completed change says so');
+
+await page.getByRole('button', { name: 'Change plan again' }).click();
+await page.waitForTimeout(200);
+await page.getByRole('radio', { name: /Free/ }).click();
+await page.getByRole('button', { name: 'Review change' }).click();
+await page.waitForTimeout(300);
+const down = await page.evaluate(() => ({ head: document.getElementById('bl-plan-h').textContent, losses: [...document.querySelectorAll('.bl-losses li')].map((l) => l.textContent),
+  danger: [...document.querySelectorAll('button')].find((b) => b.textContent === 'Downgrade to Free')?.dataset.variant }));
+expect(down.head === 'Downgrade to Free?' && down.losses.length === 3 && /SAML SSO/.test(down.losses[0]), `a downgrade lists what will be lost (${JSON.stringify(down.losses)})`);
+expect(down.danger === 'danger', 'and its button is a danger one');
+
+const gate = await page.evaluate(() => { const s = document.querySelector('[aria-labelledby="bl-roles-h"]'), b = [...s.querySelectorAll('button')].find((b) => b.textContent.includes('Create a role'));
+  return { live: !!b && !b.disabled, plate: s.textContent.includes('Business') }; });
+expect(gate.live && gate.plate, 'a locked feature stays live with its plan plate');
+
+await page.getByRole('switch', { name: 'Simulate a failed payment' }).click();
+await page.waitForTimeout(300);
+const banner = await page.evaluate(() => { const a = document.querySelector('.bl-page > .alt-alert, .bl-page > * .alt-alert');
+  return a && { role: a.getAttribute('role') || a.querySelector('[role]')?.getAttribute('role'), page: a.closest('[data-placement="page"], .alt-alert[data-placement="page"]') !== null || a.dataset.placement === 'page', action: [...a.querySelectorAll('button')].map((b) => b.textContent).join() }; });
+expect(banner && banner.page && /Update payment method/.test(banner.action), `a failed payment is a page banner asking for action (${JSON.stringify(banner)})`);
+
+const amounts = await page.evaluate(() => [...document.querySelectorAll('[aria-labelledby="bl-inv-h"] tbody td:nth-child(3)')].map((t) => t.textContent));
+expect(amounts.join() === '€264.00,€240.00,€240.00', `invoice amounts are formatted currency (${amounts})`);
+
+console.log(`Billing pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

package/dist/guidance/references/build/checks/developer-settings-pattern.mjs

@@ -0,0 +1,76 @@
+// Developer settings pattern: a new key is shown once in a dialog that Escape can't close until it's saved; the list
+// shows keys masked, never in full, with when each was last used; rolling says the old key's overlap in words; revoking
+// says what breaks behind a danger button; a webhook retry hovers as a pending write with its attempt, then lands
+// delivered; a test event shows its payload; an integration's OAuth handoff is pending until it's connected, and
+// disconnecting says what stops. Run after a render of every preview (it opens
+// test/p-DeveloperSettingsPattern-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: 1000 } });
+await page.goto(`file://${T}p-DeveloperSettingsPattern-daylight.html`);
+await page.waitForTimeout(400);
+const status = () => page.evaluate(() => document.querySelector('.dv-page > [role="status"]').textContent);
+
+await page.getByRole('button', { name: 'Create key' }).click();
+await page.waitForTimeout(400);
+await page.getByLabel('Key name').fill('Billing service');
+await page.getByRole('dialog').getByRole('button', { name: 'Create key' }).click();
+await page.waitForTimeout(800);
+const save = page.getByRole('dialog', { name: 'Save your new key' });
+const shown = await save.evaluate((d) => d.textContent + [...d.querySelectorAll('input')].map((i) => i.value).join(' '));
+expect(/You won’t see this key again/.test(shown) && /ak_live_EXAMPLE_7Hq2Xv9LmR3p/.test(shown), 'a new key is shown in full, once, with the warning');
+await page.keyboard.press('Escape');
+await page.waitForTimeout(300);
+expect(await save.count() === 1 && await save.getByRole('button', { name: 'Done' }).isDisabled(), 'the dialog can’t close until the key is saved');
+await save.getByText("I've saved this key").click();
+await page.waitForTimeout(200);
+await save.getByRole('button', { name: 'Done' }).click();
+await page.waitForTimeout(400);
+const list = await page.evaluate(() => document.querySelector('[aria-labelledby="dv-keys-h"] tbody').textContent);
+expect(/Billing service/.test(list) && !/EXAMPLE_7Hq2/.test(list) && /ak_live_••••/.test(list) && /Never used/.test(list), 'the list shows keys masked, with when each was last used');
+
+await page.getByRole('button', { name: 'Roll Production key' }).click();
+await page.waitForTimeout(400);
+let d = page.getByRole('dialog', { name: 'Roll the Production key?' });
+expect(/keeps working for 24 hours/.test(await d.textContent()), 'rolling says the old key’s overlap in words');
+await d.getByRole('button', { name: 'Roll key' }).click();
+await page.waitForTimeout(900);
+expect(/rolled\. The old key keeps working for 24 hours\./.test(await status()), 'and says so once rolled');
+await page.getByRole('button', { name: 'Revoke CI pipeline key' }).click();
+await page.waitForTimeout(400);
+d = page.getByRole('dialog', { name: 'Revoke the CI pipeline key?' });
+expect(/Requests that use it fail immediately/.test(await d.textContent()) && await d.getByRole('button', { name: 'Revoke key' }).getAttribute('data-variant') === 'danger', 'revoking says what breaks behind a danger button');
+await d.getByRole('button', { name: 'Revoke key' }).click();
+await page.waitForTimeout(900);
+expect(!/CI pipeline/.test(await page.evaluate(() => document.querySelector('[aria-labelledby="dv-keys-h"] tbody').textContent)) && /revoked/.test(await status()), 'a revoked key leaves the list, and it’s said');
+
+await page.getByRole('button', { name: 'Retry' }).click();
+await page.waitForTimeout(400);
+let item = await page.evaluate(() => { const i = [...document.querySelectorAll('.alt-timeline-item')].find((n) => n.textContent.includes('customer.updated')); return { status: i.dataset.status, text: i.textContent }; });
+expect(item.status === 'pending' && /Retrying \(attempt 4 of 5\)/.test(item.text), `a retry hovers as a pending write with its attempt (${item.status})`);
+await page.waitForTimeout(900);
+item = await page.evaluate(() => { const i = [...document.querySelectorAll('.alt-timeline-item')].find((n) => n.textContent.includes('customer.updated')); return { status: i.dataset.status, text: i.textContent }; });
+expect(item.status === 'committed' && /Delivered/.test(item.text), 'then lands, delivered');
+await page.getByRole('button', { name: 'Send test event' }).click();
+await page.waitForTimeout(300);
+expect(/"type": "invoice.paid"/.test(await page.evaluate(() => document.querySelector('.alt-code')?.textContent || '')), 'a test event shows its payload');
+
+await page.getByRole('button', { name: 'Connect Calendar sync' }).click();
+await page.waitForTimeout(500);
+const card = () => page.evaluate(() => { const c = [...document.querySelectorAll('.dv-app')].find((n) => n.textContent.includes('Calendar sync')); return { status: c.dataset.status || '', text: c.textContent }; });
+let c = await card();
+expect(c.status === 'pending' && /Waiting for authorization/.test(c.text), 'the OAuth handoff is pending');
+await page.waitForTimeout(1000);
+c = await card();
+expect(c.status !== 'pending' && /Connected/.test(c.text), 'then the integration is connected');
+await page.locator('.dv-app', { hasText: 'Team chat' }).getByRole('button', { name: 'Disconnect' }).click();
+await page.waitForTimeout(400);
+d = page.getByRole('dialog', { name: 'Disconnect Team chat?' });
+expect(/stops receiving updates/.test(await d.textContent()), 'disconnecting says what stops');
+
+console.log(`Developer settings pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

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

@@ -0,0 +1,71 @@
+// Schema, referential integrity and reproducible distribution checks (no network).
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, relative } from 'node:path';
+import { buildGuidance, inputs, listFiles, root } from '../../scripts/build-guidance.mjs';
+const {base,patterns,refs,version}=inputs();
+const read=p=>JSON.parse(readFileSync(p,'utf8'));
+const schema=read(resolve(base,'pattern.schema.json'));
+function validate(value,s,path='$') {
+  if ('const' in s) assert.equal(value,s.const,path);
+  if (s.enum) assert.ok(s.enum.includes(value),path);
+  if (s.pattern) assert.match(value,new RegExp(s.pattern),path);
+  if ('minimum' in s) assert.ok(value>=s.minimum,path);
+  assert.equal(Array.isArray(value)?'array':Number.isInteger(value)?'integer':typeof value,s.type,`${path}: expected ${s.type}`);
+  if(s.type==='object') {
+    for(const k of s.required||[])assert.ok(k in value,`${path}.${k} missing`);
+    if(s.additionalProperties===false)for(const k of Object.keys(value))assert.ok(k in s.properties,`${path}.${k} unsupported`);
+    for(const [k,v]of Object.entries(value))if(s.properties?.[k])validate(v,s.properties[k],`${path}.${k}`);
+  }
+  if(s.type==='array') {assert.ok(value.length>=(s.minItems||0));value.forEach((v,i)=>validate(v,s.items,`${path}[${i}]`));}
+  if(s.type==='string')assert.ok(value.length>=(s.minLength||0),path);
+}
+const rules=read(resolve(base,'rules.json')).rules,sources=read(resolve(base,'evidence.json')).sources;
+const ruleIds=new Set(rules.map(r=>r.id)),sourceIds=new Set(sources.map(s=>s.id));
+assert.equal(ruleIds.size,rules.length,'unique rule IDs');assert.equal(sourceIds.size,sources.length,'unique source IDs');
+const validDate=value=> typeof value==='string' && /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value)) && new Date(value).toISOString().slice(0,10)===value;
+const authority=['normative-standard','contextual-pattern','heuristic','altitude-policy','experimental-hypothesis'];
+for(const r of rules){
+  assert.match(r.id,/^ALT-[A-Z]+-\d{3}$/);assert.ok(authority.includes(r.authority));
+  assert.ok(['deterministic','application-integration','contextual-review'].includes(r.diagnosticClass));
+  assert.ok(validDate(r.reviewedAt),`${r.id}: valid review date`);assert.ok(r.owner?.trim(),`${r.id}: owner`);
+  assert.ok(Array.isArray(r.criteria));
+  if(r.authority==='normative-standard')assert.ok(r.criteria.length,`${r.id}: exact normative criterion`);
+  for(const url of r.criteria){const u=new URL(url);assert.equal(u.origin,'https://www.w3.org');assert.equal(u.pathname,'/TR/WCAG22/');assert.ok(u.hash.length>1);}
+  for(const k of ['applicability','maturity','evidenceStatus','repair'])assert.ok(r[k]);
+  assert.ok(Array.isArray(r.exceptions));assert.ok(r.sources.length);assert.ok(r.verification.length);
+  for(const id of r.sources)assert.ok(sourceIds.has(id),`${r.id}: unknown source ${id}`);
+  for(const p of r.verification)if(!p.startsWith('manual:'))assert.ok(existsSync(resolve(root,p)),`${r.id}: missing ${p}`);
+}
+for(const s of sources){assert.ok(authority.includes(s.authority));for(const k of ['title','url','status','applicability','reviewed'])assert.ok(s[k]);assert.ok(validDate(s.reviewed));
+  if(s.url.startsWith('https:'))assert.ok(new URL(s.url).hostname);else {const local=s.url.startsWith('visual/')?resolve(root,'project',s.url.slice(7)):resolve(base,s.url);assert.ok(existsSync(local),`missing local evidence ${s.url}`);}}
+assert.equal(new Set(patterns.map(p=>p.id)).size,patterns.length);
+for(const p of patterns){
+  validate(p,schema);
+  assert.ok(existsSync(resolve(base,p.document)));
+  for(const id of p.rules)assert.ok(ruleIds.has(id),`${p.id}: unknown rule ${id}`);
+  for(const id of p.sources)assert.ok(sourceIds.has(id),`${p.id}: unknown source ${id}`);
+  const prose=readFileSync(resolve(base,p.document),'utf8');
+  for(const term of ['Inputs','States','keyboard','focus','Recovery','verification','evidence'])assert.ok(prose.toLowerCase().includes(term.toLowerCase()),`${p.id}: ${term}`);
+}
+for(const p of refs)assert.ok(existsSync(resolve(root,p)),`missing ${p}`);
+// A damaged schema instance must be rejected, proving the check is active.
+assert.throws(()=>validate({...patterns[0],states:[]},schema));
+assert.throws(()=>validate({...patterns[0],unexpected:true},schema));
+const temp=mkdtempSync(resolve(tmpdir(),'altitude-guidance-'));
+try {
+  buildGuidance(temp);
+  const dist=resolve(root,'dist/guidance');
+  assert.ok(existsSync(dist),'Run npm run build first');
+  const expected=listFiles(temp).map(p=>relative(temp,p)).sort(),actual=listFiles(dist).map(p=>relative(dist,p)).sort();
+  assert.deepEqual(actual,expected,'distributed file inventory is fresh');
+  for(const p of expected)assert.deepEqual(readFileSync(resolve(dist,p)),readFileSync(resolve(temp,p)),`stale generated guidance: ${p}`);
+  assert.equal(read(resolve(dist,'index.json')).version,version);
+  const pkg=read(resolve(root,'package.json'));
+  assert.ok(existsSync(resolve(root,pkg.bin.altitude)),'shipped binary exists');
+  assert.equal(pkg.exports['./guidance'],'./dist/guidance/index.json');
+  assert.ok(!pkg.scripts.postinstall&&!pkg.scripts.install,'no install-time mutation');
+  for(const bundle of ['dist/index.js','dist/index.cjs'])assert.ok(!readFileSync(resolve(root,bundle),'utf8').includes('altitude:start'),'Node tooling is outside browser graph');
+  console.log(`guidance: ${patterns.length} patterns, ${rules.length} rules, ${expected.length} distributed files; schema/references/version/freshness pass`);
+} finally {rmSync(temp,{recursive:true,force:true});}

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

@@ -0,0 +1,69 @@
+// Import pattern: steps are a Stepper; uploading moves to mapping; a column's Select is an opening until it's mapped and
+// required fields still unmapped are listed in words; invalid cells lie in a trench on critical-soft (DataGrid
+// showInvalid) and say their problem; the problem count is said and drops as cells are fixed; "Only rows with problems"
+// narrows the grid; the review says what will be imported and skipped; the import is a cancellable Progress job that
+// ends with a receipt. Also checks DataGrid's showInvalid itself. Run after a render of every preview (it opens
+// test/p-ImportPattern-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: 900 } });
+await page.goto(`file://${T}p-ImportPattern-daylight.html`);
+await page.waitForTimeout(400);
+const current = () => page.evaluate(() => document.querySelector('[aria-label="Import steps"] [aria-current="step"]')?.textContent || 'done');
+const status = () => page.evaluate(() => document.querySelector('.im-step [role="status"]')?.textContent);
+const pick = async (col, opt) => { await page.getByRole('button', { name: col }).click(); await page.waitForTimeout(250); await page.getByRole('option', { name: opt }).locator('visible=true').click(); await page.waitForTimeout(300); };
+
+expect(/Upload/.test(await current()), 'the import starts at the upload step');
+await page.getByRole('button', { name: 'Use the sample file' }).click();
+await page.waitForTimeout(1300);
+expect(/Map columns/.test(await current()), 'an uploaded file moves to mapping');
+const empty = await page.evaluate(() => [...document.querySelectorAll('.im-map .alt-input')].map((i) => i.hasAttribute('data-filled')));
+expect(empty.every((f) => !f), 'every column starts as an opening, not mapped');
+expect(await status() === 'Map these required fields: Name, Email.' && await page.getByRole('button', { name: 'Continue' }).isDisabled(), 'required fields still unmapped are listed in words');
+await pick('Full name', 'Name (required)');
+await pick('E-mail', 'Email (required)');
+await pick('Company', 'Company');
+const filled = await page.evaluate(() => [...document.querySelectorAll('.im-map .alt-input')].map((i) => i.hasAttribute('data-filled')));
+expect(filled.join() === 'true,true,true,false' && await status() === 'Every required field is mapped.', `a mapped column fills; what's left shows (${filled})`);
+await page.getByRole('button', { name: 'Continue' }).click();
+await page.waitForTimeout(400);
+
+const cells = () => page.evaluate(() => [...document.querySelectorAll('.alt-grid-cell[data-invalid]')].map((c) => ({ text: c.textContent, name: c.getAttribute('aria-describedby') && document.getElementById(c.getAttribute('aria-describedby').split(' ')[0])?.textContent,
+  bg: getComputedStyle(c).backgroundColor, shadow: getComputedStyle(c).boxShadow, invalid: c.getAttribute('aria-invalid') })));
+let bad = await cells();
+expect(bad.length === 3 && bad.every((c) => c.invalid === 'true' && /inset/.test(c.shadow)), `invalid cells lie in a trench and are marked invalid (${bad.length})`);
+expect(bad.some((c) => c.name === 'This isn’t an email address.') && bad.some((c) => c.name === 'Enter a name.'), 'each invalid cell says its problem');
+expect(await status() === '3 problems left in 3 rows. Rows with problems are skipped.', `the problem count is said (${await status()})`);
+await page.locator('.alt-grid-cell[data-invalid]').first().click();
+await page.keyboard.press('Enter');
+await page.keyboard.press(process.platform === 'darwin' ? 'Meta+A' : 'Control+A');
+await page.keyboard.type('grace@example.com');
+await page.keyboard.press('Enter');
+await page.waitForTimeout(500);
+expect(await status() === '2 problems left in 2 rows. Rows with problems are skipped.' && (await cells()).length === 2, 'fixing a cell lifts it out and the count drops');
+await page.getByRole('switch', { name: 'Only rows with problems' }).click();
+await page.waitForTimeout(300);
+expect(await page.locator('[aria-label="Rows to import"] tbody tr').count() === 2, '"Only rows with problems" narrows the grid');
+await page.getByRole('button', { name: 'Continue' }).click();
+await page.waitForTimeout(400);
+
+expect(await page.evaluate(() => document.querySelector('.im-lead').textContent) === '5 contacts will be imported. 3 rows will be skipped: 1 duplicate and 2 with problems.', 'the review says what will be imported and skipped');
+await page.getByRole('button', { name: 'Import 5 contacts' }).click();
+await page.waitForTimeout(450);
+expect(await page.locator('.im-step [role="progressbar"]').count() === 1 && /^Importing \d of 5$/.test(await status()), 'the import is a job with progress in words');
+await page.getByRole('button', { name: 'Cancel import' }).click();
+await page.waitForTimeout(500);
+expect(await page.getByRole('heading', { name: 'Import cancelled' }).count() === 1, 'it can be cancelled, and says what was imported');
+await page.getByRole('button', { name: 'Back to review' }).click();
+await page.waitForTimeout(300);
+await page.getByRole('button', { name: 'Import 5 contacts' }).click();
+await page.waitForTimeout(2400);
+const receipt = await page.evaluate(() => [...document.querySelectorAll('.im-receipt div')].map((d) => d.textContent));
+expect(receipt.join('|') === 'Imported5 contacts|Skipped1 duplicate|Failed2 rows with problems' && await current() === 'done', `the import ends with a receipt (${receipt})`);
+
+console.log(`Import pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

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

@@ -0,0 +1,71 @@
+// Members pattern: invalid addresses are refused with the reason; sending invites is a pending write, then each new
+// invitation lands as a settled ground row with an "Invited" plate (never hovering) and the result is said per address;
+// the only owner can't change their own role and the row says why instead of offering the control; a role change hovers
+// while pending, lands as "Role changed", and a failed one drops, says so and restores the role; removing someone names
+// what they lose and is said once done; revoking an invitation is said and focus goes to the heading. Run after a render
+// of every preview (it opens test/p-MembersPattern-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: 1000 } });
+await page.goto(`file://${T}p-MembersPattern-daylight.html`);
+await page.waitForTimeout(400);
+const status = () => page.evaluate(() => [...document.querySelectorAll('.mb-page > [role="status"], .mb-page > .alt-workflow-status, .mb-page > * [role="status"]')].map((n) => n.textContent).join('|'));
+const row = (name) => page.evaluate((name) => { const r = [...document.querySelectorAll('tbody tr')].find((r) => r.querySelector('.mb-name').textContent.startsWith(name));
+  return r && { status: r.dataset.status || '', settle: r.dataset.settle || '', text: r.textContent, select: !!r.querySelector('[aria-label^="Role for"]'), remove: [...r.querySelectorAll('button')].some((b) => b.textContent === 'Remove'), badge: r.querySelector('.alt-badge')?.textContent }; }, name);
+
+const input = page.getByLabel('Email addresses');
+for (const t of ['ana@acme.dev', 'nope', 'theo@acme.dev']) {
+  await input.fill(t); await input.press('Enter'); await page.waitForTimeout(150);
+  if (t === 'nope') expect(await page.evaluate(() => document.querySelector('.mb-invite .alt-field-error')?.textContent === 'nope isn’t an email address.'), 'an invalid address is refused with the reason');
+}
+const send = page.getByRole('button', { name: 'Send 2 invites' });
+expect(await send.count() === 1, 'the button says how many invites it sends');
+await send.click();
+await page.waitForTimeout(300);
+expect(/Sending invites/.test(await status()), 'sending is said while it happens');
+await page.waitForTimeout(900);
+let r = await row('ana@acme.dev');
+expect(r && r.badge === 'Invited' && r.status === '' && r.settle !== '', `a new invitation lands as a settled row with an Invited plate (${JSON.stringify(r)})`);
+expect(await page.evaluate(() => { const r = [...document.querySelectorAll('tbody tr')].find((r) => r.textContent.includes('ana@acme.dev')); return getComputedStyle(r).animationName !== 'alt-hover'; }), 'an invitation awaiting acceptance never hovers');
+expect(/1 invite sent, 1 address is already in the workspace\./.test(await status()), `the result is said per address (${await status()})`);
+
+r = await row('Maya Chen');
+expect(r && !r.select && !r.remove && /You’re the only owner/.test(r.text), 'the only owner gets the reason instead of a role control or Remove');
+
+await page.getByRole('button', { name: 'Role for Theo Marsh' }).click();
+await page.getByRole('option', { name: 'Member' }).click();
+await page.waitForTimeout(400);
+r = await row('Theo Marsh');
+expect(r.status === 'pending' && /Changing role…/.test(r.text), `a role change hovers while it saves (${r.status})`);
+await page.waitForTimeout(700);
+r = await row('Theo Marsh');
+expect(r.status === 'committed' && /Role changed/.test(r.text), 'and lands as changed');
+await page.getByRole('switch', { name: 'Make the next role change fail' }).click();
+await page.getByRole('button', { name: 'Role for Ines Duarte' }).click();
+await page.getByRole('option', { name: 'Viewer' }).click();
+await page.waitForTimeout(1100);
+r = await row('Ines Duarte');
+const shown = await page.getByRole('button', { name: 'Role for Ines Duarte' }).textContent();
+expect(r.status === 'failed' && /Couldn’t change the role/.test(r.text) && /Member/.test(shown), `a failed change drops, says so and restores the role (${shown})`);
+await page.getByRole('switch', { name: 'Make the next role change fail' }).click();
+
+await page.evaluate(() => [...document.querySelectorAll('tbody tr')].find((r) => r.textContent.includes('Theo Marsh')).querySelector('button:last-of-type').scrollIntoView());
+await page.locator('tbody tr', { hasText: 'Theo Marsh' }).getByRole('button', { name: 'Remove' }).click();
+await page.waitForTimeout(500);
+const dialog = page.getByRole('dialog', { name: 'Remove Theo Marsh?' });
+expect(await dialog.count() === 1 && /loses access to 9 projects/.test(await dialog.textContent()), 'removing someone names what they lose');
+await dialog.getByRole('button', { name: 'Remove Theo' }).click();
+await page.waitForTimeout(1100);
+expect(!(await row('Theo Marsh')) && /Theo Marsh was removed\./.test(await status()), 'and is said once they are removed');
+
+await page.locator('tbody tr', { hasText: 'sam@acme.dev' }).getByRole('button', { name: 'Revoke' }).click();
+await page.waitForTimeout(300);
+expect(!(await row('sam@acme.dev')) && /Invitation to sam@acme.dev revoked\./.test(await status()), 'revoking an invitation is said');
+expect(await page.evaluate(() => document.activeElement.id) === 'mb-heading', 'and focus goes to the heading, not the page');
+
+console.log(`Members pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

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

@@ -0,0 +1,54 @@
+// Onboarding pattern: setup progress is a Meter, not Progress; tasks can't be checked off by clicking them, only by doing
+// them, and then they're stamped Done; the guide can be skipped before it's finished, hidden after, and found again from
+// Help; an empty region opens with its one action; no tour starts on its own, one runs when asked and doesn't dim the
+// page; "What's new" counts only unseen changes and the count goes once they're seen. Run after a render of every
+// preview (it opens test/p-OnboardingPattern-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: 1000 } });
+await page.goto(`file://${T}p-OnboardingPattern-daylight.html`);
+await page.waitForTimeout(500);
+const guide = () => page.evaluate(() => { const g = document.querySelector('.ob-guide'); return g && { meter: g.querySelectorAll('.alt-meter').length, progress: g.querySelectorAll('[role="progressbar"]').length, text: g.querySelector('.alt-meter').textContent,
+  done: [...g.querySelectorAll('.ob-task[data-done]')].map((t) => t.querySelector('.ob-title').textContent), checkboxes: g.querySelectorAll('input[type="checkbox"], [role="checkbox"]').length }; });
+
+let g = await guide();
+expect(g.meter === 1 && g.progress === 0 && /2 of 4/.test(g.text), `setup progress is a Meter reading "2 of 4" (${g.text})`);
+expect(g.checkboxes === 0 && g.done.join() === 'Create a project,Invite your team', 'tasks can’t be ticked by hand; done ones are stamped');
+expect(await page.locator('[role="dialog"]').count() === 0, 'no tour starts on its own');
+const empty = await page.evaluate(() => { const e = document.querySelector('#ob-connect .alt-empty'); return e && { buttons: e.querySelectorAll('button').length, text: e.textContent }; });
+expect(empty && empty.buttons === 1 && /No data sources yet/.test(empty.text), 'an empty region opens with its one action');
+await page.locator('#ob-connect').getByRole('button', { name: 'Connect a data source' }).click();
+await page.waitForTimeout(300);
+g = await guide();
+expect(g.done.includes('Connect a data source') && /3 of 4/.test(g.text), 'doing the task stamps it and the reading rises');
+expect(await page.locator('.ob-guide').getByRole('button', { name: 'Skip for now' }).count() === 1, 'an unfinished guide can be skipped');
+await page.locator('#ob-billing').getByRole('button', { name: 'Add billing details' }).click();
+await page.waitForTimeout(300);
+await page.locator('.ob-guide').getByRole('button', { name: 'Hide setup guide' }).click();
+await page.waitForTimeout(300);
+expect(await page.locator('.ob-guide').count() === 0 && /Open it again any time from Help/.test(await page.evaluate(() => document.querySelector('.ob-page > [role="status"]')?.textContent || '')), 'a finished guide hides, saying where to find it');
+await page.getByRole('button', { name: 'Help: setup guide' }).click();
+await page.waitForTimeout(300);
+expect(await page.locator('.ob-guide').count() === 1, 'and Help brings it back');
+
+await page.getByRole('button', { name: 'Show me what changed in the sidebar' }).click();
+await page.waitForTimeout(600);
+expect(await page.getByRole('dialog', { name: 'Projects are grouped by team' }).count() === 1 && await page.locator('[data-receded]').count() === 0, 'a tour runs when asked, without dimming the page');
+await page.keyboard.press('Escape');
+await page.waitForTimeout(400);
+
+const news = page.getByRole('button', { name: /What’s new/ });
+expect(/2/.test(await news.textContent()), 'What’s new counts unseen changes');
+await news.click();
+await page.waitForTimeout(400);
+expect(await page.getByRole('dialog', { name: 'What’s new' }).locator('.alt-timeline-item').count() === 3, 'it lists the changes as a timeline');
+await page.keyboard.press('Escape');
+await page.waitForTimeout(300);
+expect(!(await page.locator('#ob-new .alt-badge').count()), 'once seen, the count goes');
+
+console.log(`Onboarding pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

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

@@ -0,0 +1,13 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { sync } from '../../scripts/pattern-previews.mjs';
+const root = fileURLToPath(new URL('../../', import.meta.url));
+for (const config of ['build/fixtures/pattern-tsconfig.json', 'build/fixtures/pattern-examples-tsconfig.json']) {
+  const result = spawnSync(process.execPath, ['node_modules/typescript/bin/tsc', '-p', config], {cwd:root, stdio:'inherit'});
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exit(result.status || 1);
+}
+// The task patterns' examples are their Storybook previews; the two must not drift.
+const stale = sync(false);
+if (stale.length) { console.error(`Pattern previews differ from build/fixtures/patterns (run node scripts/pattern-previews.mjs): ${stale.join(', ')}`); process.exit(1); }
+console.log('Pattern types: positive/negative contracts and example compositions passed.');