altitude-design 0.2.0 → 0.3.0

package/dist/guidance/references/build/fixtures/patterns/assistant-conversation.jsx

@@ -0,0 +1,79 @@
+// Assistant conversation pattern (project/framework/patterns/assistant-conversation.md): send, stream, stop, retry and
+// recover without losing the person's words. useAssistantTurn holds the turn: a double Enter sends once, Stop keeps the
+// partial answer, an answer settles only when the stream says so, a failure keeps the message and says what happened
+// in words (offline, rate limited, context full), and an unfinished answer after a reload is "Interrupted". A Meter in
+// the toolbar shows how much of the context window is used.
+// The lines between the preview markers are its "AssistantConversationPattern" preview (scripts/pattern-previews.mjs
+// copies them); build/checks/pattern-types.mjs type-checks this file against the public declarations.
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const answer = 'The billing migration is two days behind: the invoice backfill is still running. The EU data residency review needs a decision from legal by Friday.';
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+/** @param {'offline' | 'rate-limited' | 'context-full' | 'none'} failure */
+function scripted(failure) {
+  /** @param {string} _input @param {AbortSignal} signal */
+  return async function* (_input, signal) {
+    await wait(350);
+    if (failure === 'offline') throw new A.AssistantError('offline');
+    if (failure === 'rate-limited') throw new A.AssistantError('rate-limited', undefined, Date.now() + 25 * 60000);
+    if (failure === 'context-full') throw new A.AssistantError('context-full');
+    for (let n = 0; n < answer.length; n += 6) { if (signal.aborted) return; await wait(45); yield answer.slice(n, n + 6); }
+  };
+}
+/** @param {{ restored?: { input: string, text: string, complete: boolean } }} props */
+function Thread({ restored }) {
+  const [failure, setFailure] = React.useState(/** @type {'offline' | 'rate-limited' | 'context-full' | 'none'} */ ('none'));
+  const [draft, setDraft] = React.useState('');
+  const [used, setUsed] = React.useState(64);
+  const turn = A.useAssistantTurn({ stream: scripted(failure), restored });
+  // A failed send keeps the message: it goes back in the composer.
+  React.useEffect(() => { if (turn.state === 'failed' && turn.input) setDraft(turn.input); }, [turn.state]); // eslint-disable-line react-hooks/exhaustive-deps
+  React.useEffect(() => { if (turn.state === 'complete') setUsed((u) => Math.min(99, u + 9)); }, [turn.state]);
+  return (
+    <div className="col ac">
+      <A.ToggleGroup type="single" size="sm" aria-label="Make the next send fail" value={failure} onValueChange={(v) => setFailure(/** @type {any} */ (v) || 'none')}>
+        <A.ToggleGroupItem value="none">Works</A.ToggleGroupItem>
+        <A.ToggleGroupItem value="offline">Offline</A.ToggleGroupItem>
+        <A.ToggleGroupItem value="rate-limited">Rate limited</A.ToggleGroupItem>
+        <A.ToggleGroupItem value="context-full">Context full</A.ToggleGroupItem>
+      </A.ToggleGroup>
+      <A.Conversation aria-label="Assistant">
+        <A.ConversationContent>
+          {turn.input !== undefined && <A.Message from="user"><A.MessageContent>{turn.input}</A.MessageContent></A.Message>}
+          {(turn.text || turn.state === 'streaming' || turn.state === 'interrupted') && (
+            <A.Message from="assistant" status={turn.messageStatus} onRetry={turn.state === 'stopped' || turn.state === 'interrupted' ? turn.retry : undefined}>
+              <A.MessageContent><A.Markdown streaming={turn.state === 'streaming'}>{turn.text}</A.Markdown></A.MessageContent>
+              {turn.state === 'interrupted' && <p className="ac-note">Interrupted: the page reloaded before this answer finished.</p>}
+            </A.Message>
+          )}
+        </A.ConversationContent>
+      </A.Conversation>
+      {turn.state === 'failed' && (
+        <A.Alert tone={turn.error?.kind === 'context-full' ? 'caution' : 'critical'} title={turn.errorText}
+          action={turn.error?.kind === 'context-full' ? <A.Button size="sm" variant="secondary">Start a new conversation</A.Button> : <A.Button size="sm" variant="secondary" onClick={() => { setFailure('none'); setDraft(''); }}>Try again</A.Button>} />
+      )}
+      <A.PromptInput status={turn.promptStatus === 'error' ? 'ready' : turn.promptStatus} value={draft} onValueChange={setDraft} onStop={turn.stop}
+        onSubmit={({ text }) => { turn.submit(text); }}>
+        <A.PromptInputTextarea placeholder="Ask about the release" />
+        <A.PromptInputToolbar>
+          <A.Meter className="ac-context" label="Context" value={used} max={100} high={80} critical={95} format={(v) => `${v}% of context used`} />
+          <A.PromptInputSubmit />
+        </A.PromptInputToolbar>
+      </A.PromptInput>
+    </div>
+  );
+}
+function App() {
+  const [reloaded, setReloaded] = React.useState(false);
+  return (
+    <div className="col">
+      <A.Button size="sm" variant="ghost" onClick={() => setReloaded((r) => !r)}>{reloaded ? 'Start fresh' : 'Reload mid-answer'}</A.Button>
+      {reloaded
+        ? <Thread key="restored" restored={{ input: 'What are the open risks?', text: 'The billing migration is two days behind: the invoice', complete: false }} />
+        : <Thread key="fresh" />}
+    </div>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/audit-log.jsx

@@ -0,0 +1,81 @@
+// Audit log pattern (project/framework/patterns/audit-log.md): the workspace audit log is a DataTable of flush entries,
+// each one sentence, filtered with a FilterBar and paged by the server; an entry expands to show what changed. A record's
+// own activity is a Timeline. Exporting is a job: Progress while it runs, then a toast with the download, and the export
+// is itself logged.
+// The lines between the preview markers are its "AuditLogPattern" preview (scripts/pattern-previews.mjs copies them);
+// build/checks/pattern-types.mjs type-checks this file against the public declarations and fails if the two differ.
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const ACTORS = [{ value: 'Maya Chen', label: 'Maya Chen' }, { value: 'Theo Marsh', label: 'Theo Marsh' }, { value: 'Ines Duarte', label: 'Ines Duarte' }];
+const ACTIONS = [{ value: 'role', label: 'Changed a role' }, { value: 'invite', label: 'Invited someone' }, { value: 'key', label: 'Rotated an API key' }, { value: 'export', label: 'Exported data' }];
+/** @typedef {{ id: string, actor: string, action: string, resource: string, sentence: string, at: string, ip: string, before: Record<string, string>, after: Record<string, string> }} AuditEvent */
+const SEED = Array.from({ length: 22 }, /** @returns {AuditEvent} */ (_, i) => {
+  const actor = ACTORS[i % 3].value, kind = ACTIONS[i % 3].value, day = String(28 - Math.floor(i / 3)).padStart(2, '0');
+  const at = `2026-10-${day}T${String(17 - (i % 3) * 3).padStart(2, '0')}:${String((i * 7) % 60).padStart(2, '0')}:00Z`;
+  if (kind === 'role') return { id: 'e' + i, actor, action: kind, resource: 'Ines Duarte', sentence: `${actor} changed Ines Duarte’s role from Member to Admin`, at, ip: '81.2.69.' + (10 + i), before: { role: 'Member' }, after: { role: 'Admin' } };
+  if (kind === 'invite') return { id: 'e' + i, actor, action: kind, resource: `guest${i}@acme.dev`, sentence: `${actor} invited guest${i}@acme.dev as a Viewer`, at, ip: '81.2.69.' + (10 + i), before: { invited: 'No' }, after: { invited: 'Yes, as Viewer' } };
+  return { id: 'e' + i, actor, action: kind, resource: 'Production key', sentence: `${actor} rotated the Production API key`, at, ip: '81.2.69.' + (10 + i), before: { key: 'ak_live_EXAMPLE…4f2a' }, after: { key: 'ak_live_EXAMPLE…9c1d' } };
+});
+/** @type {A.FilterField[]} */
+const FIELDS = [{ key: 'actor', label: 'Actor', type: 'enum', options: ACTORS }, { key: 'action', label: 'Action', type: 'enum', options: ACTIONS }, { key: 'at', label: 'Date', type: 'date' }];
+const test = (row, f) => {
+  if (f.value === undefined || f.value === '') return true;
+  const v = f.field === 'at' ? row.at.slice(0, 10) : row[f.field];
+  if (f.operator === 'is') return v === f.value;
+  if (f.operator === 'is not') return v !== f.value;
+  if (f.operator === 'before') return v < f.value;
+  if (f.operator === 'after') return v > f.value;
+  if (f.operator === 'between' && typeof f.value === 'object') return v >= f.value.start && v <= f.value.end;
+  return true;
+};
+function App() {
+  const [log, setLog] = React.useState(SEED);
+  const [filters, setFilters] = React.useState(/** @type {A.Filter[]} */ ([]));
+  const [page, setPage] = React.useState(1);
+  const [loading, setLoading] = React.useState(false);
+  const [exporting, setExporting] = React.useState(/** @type {number | null} */ (null));
+  const matching = log.filter((r) => filters.every((f) => test(r, f)));
+  const pageCount = Math.max(1, Math.ceil(matching.length / 5));
+  const rows = matching.slice((page - 1) * 5, page * 5);
+  const turn = async (p) => { setLoading(true); await wait(400); setPage(p); setLoading(false); };
+  const runExport = async () => {
+    for (const pct of [0, 20, 40, 60, 80, 100]) { setExporting(pct); await wait(250); }
+    setExporting(null);
+    setLog((l) => [{ id: 'x' + l.length, actor: 'Maya Chen', action: 'export', resource: 'Audit log', sentence: `Maya Chen exported ${matching.length} audit log events as CSV`, at: '2026-10-29T09:00:00Z', ip: '81.2.69.4', before: {}, after: { file: 'audit-log.csv' } }, ...l]);
+    A.toast({ title: 'Your export is ready', description: `${matching.length} events, audit-log.csv`, tone: 'positive', duration: 0, action: { label: 'Download', onClick: () => {} } });
+  };
+  return (
+    <main className="al-page">
+      <h2 className="al-h">Audit log</h2>
+      <p className="al-note">Every change in the Acme workspace, kept for 90 days on the Pro plan. Older events are deleted.</p>
+      <div className="al-tools">
+        <A.FilterBar aria-label="Filter events" fields={FIELDS} value={filters} onValueChange={(f) => { setFilters(f); setPage(1); }} resultCount={matching.length} />
+        <A.Button onClick={runExport} disabled={exporting !== null}>Export CSV</A.Button>
+      </div>
+      {exporting !== null && <div className="al-export"><A.Progress value={exporting} aria-label="Preparing export" /><span role="status">Preparing export, {exporting}%</span></div>}
+      <A.DataTable aria-label="Audit log events" noun="events" rows={rows} getRowId={(r) => r.id} getRowLabel={(r) => r.sentence}
+        empty="No events match these filters. Remove a filter to see more."
+        columns={[
+          { key: 'sentence', header: 'Event', width: '46%' },
+          { key: 'actor', header: 'Actor' },
+          { key: 'at', header: 'Time', cell: (r) => <A.RelativeTime date={r.at} locale="en-IE" /> },
+          { key: 'ip', header: 'IP address' },
+        ]}
+        renderExpanded={(r) => <A.DiffView mode="properties" before={r.before} after={r.after} caption={`${r.resource}: what changed`} />}
+        pagination={{ page, pageCount, total: matching.length, onPageChange: turn, loading, noun: 'events' }} />
+      <section className="al-record" aria-labelledby="al-activity-h">
+        <h3 id="al-activity-h" className="al-sub">Activity on Q4 plan</h3>
+        <A.Timeline aria-label="Activity on Q4 plan" groupBy="none" locale="en-IE">
+          <A.TimelineItem key="a1" time="2026-10-28T15:10:00Z">Theo Marsh changed the due date to 15 December</A.TimelineItem>
+          <A.TimelineItem key="a2" time="2026-10-27T11:02:00Z" detail={<A.DiffView mode="properties" before={{ owner: 'Maya Chen' }} after={{ owner: 'Ines Duarte' }} />}>Maya Chen made Ines Duarte the owner</A.TimelineItem>
+          <A.TimelineItem key="a3" time="2026-10-26T09:45:00Z" href="#/docs/q4">Ines Duarte linked the Q4 pricing doc</A.TimelineItem>
+        </A.Timeline>
+      </section>
+      <A.Toaster />
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/auth.jsx

@@ -0,0 +1,150 @@
+// Auth pattern (project/framework/patterns/auth.md): sign in on a raised Card (level 1, never a Dialog), with SSO, a
+// password, or an emailed link; sign up and verify the email; two-factor with a one-time code or a recovery code; reset. The copy never reveals
+// whether an account exists, rate limits are said with the wait, nothing is submitted for the person, and the email
+// is kept across steps. Demo: any email; the password is "altitude"; the code is 123456.
+// The lines between the preview markers are its "AuthPattern" preview (scripts/pattern-previews.mjs copies them);
+// build/checks/pattern-types.mjs type-checks this file against the public declarations and fails if the two differ.
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const isEmail = (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+const RULES = [{ label: 'At least 12 characters', test: (v) => v.length >= 12 }, { label: 'Not just letters', test: (v) => /[^a-z]/i.test(v) }];
+function App() {
+  const [step, setStep] = React.useState('sign-in');
+  const [email, setEmail] = React.useState('');
+  const [password, setPassword] = React.useState('');
+  const [name, setName] = React.useState('');
+  const [code, setCode] = React.useState('');
+  const [recovery, setRecovery] = React.useState('');
+  const [trust, setTrust] = React.useState(false);
+  const [busy, setBusy] = React.useState('');
+  const [errors, setErrors] = React.useState(/** @type {{ id: string, label: string, message: string }[]} */ ([]));
+  const [tries, setTries] = React.useState(0);
+  const [submits, setSubmits] = React.useState(0);
+  const [resendIn, setResendIn] = React.useState(0);
+  const heading = React.useRef(/** @type {HTMLHeadingElement | null} */ (null));
+  React.useEffect(() => { if (resendIn <= 0) return; const t = setTimeout(() => setResendIn((s) => s - 1), 1000); return () => clearTimeout(t); }, [resendIn]);
+  const go = (next) => { setStep(next); setErrors([]); setBusy(''); requestAnimationFrame(() => heading.current?.focus()); };
+  const fail = (list) => { setErrors(list); setSubmits((n) => n + 1); };
+  const signIn = async (e) => {
+    e.preventDefault();
+    const list = [];
+    if (!isEmail(email)) list.push({ id: 'au-email', label: 'Email', message: 'Enter your email address, like name@example.com.' });
+    if (!password) list.push({ id: 'au-password', label: 'Password', message: 'Enter your password.' });
+    if (list.length) return fail(list);
+    if (tries >= 3) return fail([{ id: 'au-password', label: 'Password', message: 'Too many attempts. Wait 5 minutes, then try again, or reset your password.' }]);
+    setBusy('password'); await wait(800); setBusy('');
+    if (password !== 'altitude') { setTries((n) => n + 1); setPassword(''); return fail([{ id: 'au-password', label: 'Password', message: 'That email and password don’t match. Try again or reset your password.' }]); }
+    go('two-factor');
+  };
+  const sendLink = async (next) => {
+    if (!isEmail(email)) return fail([{ id: 'au-email', label: 'Email', message: 'Enter your email address, like name@example.com.' }]);
+    setBusy('link'); await wait(700); setResendIn(30); go(next);
+  };
+  const signUp = async (e) => {
+    e.preventDefault();
+    const list = [];
+    if (!name.trim()) list.push({ id: 'au-name', label: 'Name', message: 'Enter your name.' });
+    if (!isEmail(email)) list.push({ id: 'au-email', label: 'Email', message: 'Enter your email address, like name@example.com.' });
+    if (!RULES.every((r) => r.test(password))) list.push({ id: 'au-password', label: 'Password', message: 'Choose a password that meets both requirements.' });
+    if (list.length) return fail(list);
+    setBusy('password'); await wait(800); setCode(''); setResendIn(30); go('verify');
+  };
+  const verify = async (value) => {
+    setBusy('code'); await wait(700);
+    if (value !== '123456') { setBusy(''); setCode(''); return fail([{ id: 'au-code', label: 'Code', message: 'That code didn’t work. Check your authenticator app and enter the newest code.' }]); }
+    go('done');
+  };
+  const field = (id) => errors.find((x) => x.id === id)?.message;
+  const resend = <p className="au-note">{resendIn > 0 ? `You can resend the email in ${resendIn} ${resendIn === 1 ? 'second' : 'seconds'}.` : <A.Button variant="ghost" size="sm" onClick={() => sendLink(step)}>Resend the email</A.Button>}</p>;
+  return (
+    <main className="au-page">
+      <A.Card className="au-card">
+        {step === 'sign-in' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Sign in to Acme</h2>
+          <A.Button className="au-wide" onClick={() => go('sso')}>Continue with single sign-on (SSO)</A.Button>
+          <A.Separator label="or" />
+          <form className="au-form" noValidate onSubmit={signIn} aria-labelledby="au-pw-h">
+            <span id="au-pw-h" hidden>Sign in with a password</span>
+            <A.ErrorSummary errors={errors} focusKey={submits} title="We couldn’t sign you in" />
+            <A.Field label="Email" error={field('au-email')}><A.Input id="au-email" type="email" autoComplete="username" value={email} onChange={(e) => setEmail(e.target.value)} /></A.Field>
+            <A.Field label="Password" error={field('au-password')}><A.PasswordInput id="au-password" autoComplete="current-password" value={password} onChange={(e) => setPassword(e.target.value)} /></A.Field>
+            <A.Button type="submit" variant="primary" className="au-wide" loading={busy === 'password'}>{busy === 'password' ? 'Signing in' : 'Sign in'}</A.Button>
+          </form>
+          <div className="au-links"><A.Button variant="ghost" size="sm" loading={busy === 'link'} onClick={() => sendLink('link-sent')}>Email me a sign-in link</A.Button><A.Button variant="ghost" size="sm" onClick={() => go('reset')}>Forgot your password?</A.Button></div>
+          <p className="au-note">New to Acme? <A.Button variant="ghost" size="sm" onClick={() => { setPassword(''); go('sign-up'); }}>Create an account</A.Button></p>
+        </>}
+        {step === 'sign-up' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Create your Acme account</h2>
+          <form className="au-form" noValidate onSubmit={signUp} aria-label="Create an account">
+            <A.ErrorSummary errors={errors} focusKey={submits} />
+            <A.Field label="Name" error={field('au-name')}><A.Input id="au-name" autoComplete="name" value={name} onChange={(e) => setName(e.target.value)} /></A.Field>
+            <A.Field label="Email" error={field('au-email')}><A.Input id="au-email" type="email" autoComplete="email" value={email} onChange={(e) => setEmail(e.target.value)} /></A.Field>
+            <A.Field label="Password" error={field('au-password')}><A.PasswordInput id="au-password" autoComplete="new-password" requirements={RULES} value={password} onChange={(e) => setPassword(e.target.value)} /></A.Field>
+            <A.Button type="submit" variant="primary" className="au-wide" loading={busy === 'password'}>{busy === 'password' ? 'Creating account' : 'Create account'}</A.Button>
+          </form>
+          <A.Button variant="ghost" size="sm" onClick={() => go('sign-in')}>I already have an account</A.Button>
+        </>}
+        {step === 'verify' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Verify your email</h2>
+          <p>We sent a 6-digit code to <strong>{email}</strong>. It works for 10 minutes.</p>
+          <A.ErrorSummary errors={errors} focusKey={submits} title="We couldn’t verify that code" />
+          <A.Field label="Verification code" error={field('au-code')}><A.InputOTP id="au-code" maxLength={6} value={code} onChange={setCode} verifying={busy === 'code'} autoComplete="one-time-code" /></A.Field>
+          <A.Button variant="primary" className="au-wide" loading={busy === 'code'} disabled={code.length < 6} onClick={() => verify(code)}>{busy === 'code' ? 'Verifying' : 'Verify email'}</A.Button>
+          {resend}
+          <A.Button variant="ghost" size="sm" onClick={() => go('sign-up')}>Change email address</A.Button>
+        </>}
+        {step === 'link-sent' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Check your email</h2>
+          <p>If <strong>{email}</strong> has an Acme account, we’ve sent a sign-in link to it. The link works once, for 15 minutes.</p>
+          {resend}
+          <A.Button variant="ghost" size="sm" onClick={() => go('sign-in')}>Use a different email address</A.Button>
+        </>}
+        {step === 'sso' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Sign in with SSO</h2>
+          <A.Field label="Work email" hint="We’ll send you to your company’s sign-in page."><A.Input type="email" autoComplete="username" value={email} onChange={(e) => setEmail(e.target.value)} /></A.Field>
+          <A.Button variant="primary" className="au-wide" onClick={() => go('sign-in')}>Continue</A.Button>
+          <A.Button variant="ghost" size="sm" onClick={() => go('sign-in')}>Back to sign in</A.Button>
+        </>}
+        {step === 'two-factor' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Enter your code</h2>
+          <p>Open your authenticator app and enter the 6-digit code for Acme.</p>
+          <A.ErrorSummary errors={errors} focusKey={submits} title="We couldn’t verify that code" />
+          <A.Field label="Authentication code" error={field('au-code')}>
+            <A.InputOTP id="au-code" maxLength={6} value={code} onChange={setCode} verifying={busy === 'code'} autoComplete="one-time-code" />
+          </A.Field>
+          <A.Checkbox label="Trust this device for 30 days" checked={trust} onCheckedChange={setTrust} />
+          <A.Button variant="primary" className="au-wide" loading={busy === 'code'} disabled={code.length < 6} onClick={() => verify(code)}>{busy === 'code' ? 'Verifying' : 'Verify'}</A.Button>
+          <A.Button variant="ghost" size="sm" onClick={() => go('recovery')}>Use a recovery code instead</A.Button>
+        </>}
+        {step === 'recovery' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Use a recovery code</h2>
+          <A.Field label="Recovery code" hint="One of the codes you saved when you set up two-factor. Each works once."><A.Input autoComplete="off" value={recovery} onChange={(e) => setRecovery(e.target.value)} /></A.Field>
+          <A.Button variant="primary" className="au-wide" onClick={() => go('done')}>Verify</A.Button>
+          <A.Button variant="ghost" size="sm" onClick={() => go('two-factor')}>Use your authenticator app</A.Button>
+        </>}
+        {step === 'reset' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Reset your password</h2>
+          <A.ErrorSummary errors={errors} focusKey={submits} />
+          <A.Field label="Email" error={field('au-email')}><A.Input id="au-email" type="email" autoComplete="username" value={email} onChange={(e) => setEmail(e.target.value)} /></A.Field>
+          <A.Button variant="primary" className="au-wide" loading={busy === 'link'} onClick={() => sendLink('reset-sent')}>Send reset link</A.Button>
+          <A.Button variant="ghost" size="sm" onClick={() => go('sign-in')}>Back to sign in</A.Button>
+        </>}
+        {step === 'reset-sent' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">Check your email</h2>
+          <p>If <strong>{email}</strong> has an Acme account, we’ve sent a link to reset its password. The link works once, for 1 hour.</p>
+          {resend}
+          <A.Button variant="ghost" size="sm" onClick={() => go('sign-in')}>Back to sign in</A.Button>
+        </>}
+        {step === 'done' && <>
+          <h2 ref={heading} tabIndex={-1} className="au-h">You’re signed in</h2>
+          <p>{trust ? 'This device won’t ask for a code for 30 days.' : 'We’ll ask for a code next time you sign in on this device.'}</p>
+          <A.Button variant="ghost" size="sm" onClick={() => { setPassword(''); setCode(''); setTries(0); go('sign-in'); }}>Sign out</A.Button>
+        </>}
+      </A.Card>
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/billing.jsx

@@ -0,0 +1,96 @@
+// Billing pattern (project/framework/patterns/billing.md): usage against plan limits as readings (Meters, never
+// Progress), history with the rest of the cycle as Projected, an estimate that says how it's computed, a plan change
+// reviewed with its proration before it's confirmed (a downgrade lists what will be lost), a locked feature, a failed
+// payment as a page banner, and invoices.
+// The lines between the preview markers are its "BillingPattern" preview (scripts/pattern-previews.mjs copies them);
+// build/checks/pattern-types.mjs type-checks this file against the public declarations and fails if the two differ.
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const PLANS = [
+  { id: 'free', name: 'Free', price: 0, currency: 'EUR', unit: 'per seat', features: ['3 projects', 'Community support'] },
+  { id: 'pro', name: 'Pro', price: { month: 2400, year: 2000 }, currency: 'EUR', unit: 'per seat', features: ['Unlimited projects', 'SAML SSO', 'Audit log'] },
+  { id: 'business', name: 'Business', price: { month: 4800, year: 4000 }, currency: 'EUR', unit: 'per seat', features: ['Everything in Pro', 'Custom roles', '99.9% uptime SLA'] },
+];
+const LOSSES = { free: ['SAML SSO, which 8 members sign in with', 'The audit log and its 90 days of history', '9 of your 12 projects become read-only'], pro: ['Custom roles: 2 members on the “Finance” role move to Member'] };
+const eur = (minor) => A.formatNumber(minor, { format: 'currency', currency: 'EUR', locale: 'en-IE' });
+const usage = [
+  { week: '2026-10-05', calls: 210000 }, { week: '2026-10-12', calls: 260000 }, { week: '2026-10-19', calls: 310000 },
+  { week: '2026-10-26', calls: 290000 }, { week: '2026-11-02', calls: 300000 }, { week: '2026-11-09', calls: 320000 },
+];
+function PlanChange({ current, period, onPeriod, onChanged, onAgain }) {
+  const rank = (id) => PLANS.findIndex((p) => p.id === id);
+  const flow = A.useReviewSubmit({
+    initialValue: { plan: current }, validate: (d) => (d.plan === current ? { plan: 'Choose a plan you’re not on.' } : {}),
+    submit: async (d) => { await wait(900); return { ok: true, receipt: { plan: d.plan } }; },
+    messages: { submitting: 'Changing plan…', complete: 'Plan changed', failed: 'We couldn’t change your plan. Nothing was charged. Try again.' },
+  });
+  React.useEffect(() => { if (flow.phase === 'review' || flow.phase === 'complete') document.getElementById('bl-plan-h')?.focus(); if (flow.phase === 'complete' && flow.receipt) onChanged(flow.receipt.plan); }, [flow.phase]);
+  const next = PLANS.find((p) => p.id === flow.draft.plan) || PLANS[0], down = rank(flow.draft.plan) < rank(current);
+  const per = (p) => (typeof p.price === 'number' ? p.price : p.price[period]) * 10;
+  const today = Math.max(0, Math.round((per(next) - per(PLANS[rank(current)])) * 0.35));
+  return (
+    <section className="bl-section" aria-labelledby="bl-plan-h">
+      <h3 id="bl-plan-h" tabIndex={-1} className="bl-sub">{flow.phase === 'complete' ? `You’re on ${next.name}` : flow.phase === 'editing' ? 'Change plan' : down ? `Downgrade to ${next.name}?` : `Upgrade to ${next.name}?`}</h3>
+      {flow.phase === 'editing' && <>
+        <A.PlanPicker plans={PLANS} value={flow.draft.plan} onValueChange={(v) => flow.setField('plan', v)} current={current} recommended="business" period={period} onPeriodChange={onPeriod} locale="en-IE" aria-label="Plans" />
+        {flow.errors.plan && <p className="bl-note" role="alert">{flow.errors.plan}</p>}
+        <div><A.Button variant="primary" onClick={flow.review}>Review change</A.Button></div>
+      </>}
+      {(flow.phase === 'review' || flow.phase === 'submitting') && <>
+        <p className="bl-proration">{down ? `Your plan changes to ${next.name} at the end of this cycle, on 30 November. Then you’ll pay ${eur(per(next))}/${period}.` : `You’ll pay ${eur(today)} today for the rest of this cycle, then ${eur(per(next))}/${period} for 10 seats.`}</p>
+        {down && <div className="bl-losses"><strong>You’ll lose</strong><ul>{(LOSSES[next.id] || []).map((l) => <li key={l}>{l}</li>)}</ul></div>}
+        <div className="bl-actions"><A.Button disabled={flow.phase === 'submitting'} onClick={flow.correct}>Choose another plan</A.Button>
+          <A.Button variant={down ? 'danger' : 'primary'} loading={flow.phase === 'submitting'} onClick={() => void flow.submit()}>{flow.phase === 'submitting' ? 'Changing plan' : down ? `Downgrade to ${next.name}` : `Upgrade to ${next.name}`}</A.Button></div>
+      </>}
+      {flow.phase === 'complete' && <p className="bl-note">{down ? `${next.name} starts on 30 November. Until then everything on your current plan keeps working.` : `${next.name} features are on now. A receipt is on its way to finance@acme.dev.`}</p>}
+      {flow.phase === 'complete' && <div><A.Button variant="ghost" onClick={onAgain}>Change plan again</A.Button></div>}
+      <A.WorkflowStatus>{flow.status}</A.WorkflowStatus>
+    </section>
+  );
+}
+function App() {
+  const [current, setCurrent] = React.useState('pro');
+  const [period, setPeriod] = React.useState('month');
+  const [attempt, setAttempt] = React.useState(0);
+  const [failed, setFailed] = React.useState(false);
+  return (
+    <main className="bl-page">
+      {failed && <A.Alert placement="page" tone="critical" variant="raised" title="Your last payment failed"
+        action={<A.Button size="sm" onClick={() => setFailed(false)}>Update payment method</A.Button>}>We couldn’t charge the card ending 4242 on 1 November. Update it by 8 November to keep your workspace active.</A.Alert>}
+      <h2 className="bl-h">Billing</h2>
+      <A.Switch label="Simulate a failed payment" checked={failed} onCheckedChange={setFailed} />
+      <section className="bl-section" aria-labelledby="bl-usage-h">
+        <h3 id="bl-usage-h" className="bl-sub">Usage this cycle</h3>
+        <div className="bl-meters">
+          <A.Meter label="Seats" value={8} max={10} high={8} format={(v) => String(v)} />
+          <A.Meter label="Storage" value={62} max={100} high={80} format={(v) => `${v} GB`} />
+          <A.Meter label="API calls" value={1.2} max={1} high={0.8} format={(v) => `${v}M`} />
+        </div>
+        <A.Stat label="Estimated next bill" value={28800} format={eur} help="10 seats × €24, plus €48 for 0.2M API calls over the 1M included. Updated hourly; the final amount is on your invoice." />
+        <A.ChartContainer aria-labelledby="bl-calls-h" config={{ calls: { label: 'API calls', format: (v) => A.formatNumber(v, { format: 'compact', locale: 'en-IE' }) } }} height={180}>
+          <A.BarChart data={usage} x="week" status={(d) => (String(d.week) > '2026-10-30' ? 'projected' : undefined)} />
+        </A.ChartContainer>
+        <p id="bl-calls-h" className="bl-note">API calls per week. The last two weeks of the cycle are projected.</p>
+      </section>
+      <PlanChange key={attempt} current={current} period={period} onPeriod={setPeriod} onChanged={setCurrent} onAgain={() => setAttempt((n) => n + 1)} />
+      <section className="bl-section" aria-labelledby="bl-roles-h">
+        <h3 id="bl-roles-h" className="bl-sub">Custom roles</h3>
+        <A.FeatureGate requires="Business" description="Create roles with exactly the permissions a team needs." onUpgrade={() => document.getElementById('bl-plan-h')?.focus()}>
+          <A.Button>Create a role</A.Button>
+        </A.FeatureGate>
+      </section>
+      <section className="bl-section" aria-labelledby="bl-inv-h">
+        <h3 id="bl-inv-h" className="bl-sub">Invoices</h3>
+        <A.Table aria-labelledby="bl-inv-h">
+          <A.TableHeader><A.TableRow><A.TableHead>Date</A.TableHead><A.TableHead>Invoice</A.TableHead><A.TableHead align="end">Amount</A.TableHead><A.TableHead>Status</A.TableHead></A.TableRow></A.TableHeader>
+          <A.TableBody>{[{ d: '1 Oct 2026', n: 'INV-0042', a: 26400, s: 'Paid' }, { d: '1 Sep 2026', n: 'INV-0041', a: 24000, s: 'Paid' }, { d: '1 Aug 2026', n: 'INV-0040', a: 24000, s: 'Refunded' }].map(({ d, n, a, s }) =>
+            <A.TableRow key={n}><A.TableCell>{d}</A.TableCell><A.TableCell><A.Link href={'#/invoices/' + n}>{n}</A.Link></A.TableCell><A.TableCell align="end"><A.FormattedNumber value={a} format="currency" currency="EUR" locale="en-IE" /></A.TableCell><A.TableCell><A.Badge tone={s === 'Paid' ? 'positive' : 'neutral'}>{s}</A.Badge></A.TableCell></A.TableRow>)}</A.TableBody>
+        </A.Table>
+      </section>
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/developer-settings.jsx

@@ -0,0 +1,95 @@
+// Developer settings pattern (project/framework/patterns/developer-settings.md): API keys created in a dialog that can't
+// close until the secret is saved, listed masked with when each was last used, rolled with an overlap said in words and
+// revoked with what breaks; webhooks whose deliveries are a Timeline, a retry hovering as a pending write and a test
+// event's payload shown in a CodeBlock; integrations as interactive cards, the OAuth handoff pending, disconnect named.
+// The lines between the preview markers are its "DeveloperSettingsPattern" preview (scripts/pattern-previews.mjs copies
+// them); build/checks/pattern-types.mjs type-checks this file against the public declarations and fails if they differ.
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const PAYLOAD = JSON.stringify({ id: 'evt_EXAMPLE_1042', type: 'invoice.paid', created: '2026-10-29T09:12:00Z', data: { invoice: 'INV-0042', amount: 26400, currency: 'eur' } }, null, 2);
+function App() {
+  const [keys, setKeys] = React.useState([{ id: 'k1', name: 'Production', tail: '4f2a', used: 'Used 3 minutes ago by 3 services' }, { id: 'k2', name: 'CI pipeline', tail: '8d0e', used: 'Used yesterday' }]);
+  const [creating, setCreating] = React.useState(/** @type {null | { name: string, secret?: string, saved?: boolean }} */ (null));
+  const [confirm, setConfirm] = React.useState(/** @type {null | { kind: 'roll' | 'revoke' | 'disconnect', id: string, busy?: boolean }} */ (null));
+  const [status, setStatus] = React.useState('');
+  const [deliveries, setDeliveries] = React.useState(/** @type {{ id: string, event: string, at: string, result: 'Delivered' | 'Failed', status?: 'pending' | 'committed' | 'failed', attempt: number }[]} */ ([
+    { id: 'd1', event: 'invoice.paid', at: '2026-10-29T09:12:00Z', result: 'Delivered', attempt: 1 },
+    { id: 'd2', event: 'customer.updated', at: '2026-10-29T08:40:00Z', result: 'Failed', status: 'failed', attempt: 3 },
+  ]));
+  const [test, setTest] = React.useState(false);
+  const [apps, setApps] = React.useState([{ id: 'chat', name: 'Team chat', about: 'Post alerts to a channel.', state: 'connected' }, { id: 'cal', name: 'Calendar sync', about: 'Add due dates to calendars.', state: 'idle' }, { id: 'store', name: 'Cloud storage', about: 'Attach files from your drive.', state: 'idle' }]);
+  const heading = React.useRef(/** @type {HTMLHeadingElement | null} */ (null));
+  const key = confirm && keys.find((k) => k.id === confirm.id);
+  const app = confirm && apps.find((a) => a.id === confirm.id);
+  const create = async () => { if (!creating) return; await wait(500); setCreating({ ...creating, secret: 'ak_live_EXAMPLE_7Hq2Xv9LmR3p' }); };
+  const finishCreate = () => { if (!creating) return; setKeys((l) => [...l, { id: 'k' + (l.length + 1), name: creating.name || 'Untitled key', tail: '3p0K', used: 'Never used' }]); setStatus(`Key “${creating.name || 'Untitled key'}” created.`); setCreating(null); };
+  const retry = async (id) => {
+    setDeliveries((l) => l.map((d) => (d.id === id ? { ...d, status: 'pending', attempt: d.attempt + 1 } : d)));
+    await wait(1000);
+    setDeliveries((l) => l.map((d) => (d.id === id ? { ...d, status: 'committed', result: 'Delivered' } : d)));
+  };
+  const act = async () => {
+    if (!confirm) return;
+    setConfirm({ ...confirm, busy: true }); await wait(700);
+    if (confirm.kind === 'revoke') { setKeys((l) => l.filter((k) => k.id !== confirm.id)); setStatus(`Key “${key?.name}” revoked. Requests that use it now fail.`); }
+    if (confirm.kind === 'roll') { setKeys((l) => l.map((k) => (k.id === confirm.id ? { ...k, tail: 'Zx81', used: 'New key. The old one works until tomorrow, 09:12' } : k))); setStatus(`Key “${key?.name}” rolled. The old key keeps working for 24 hours.`); }
+    if (confirm.kind === 'disconnect') { setApps((l) => l.map((a) => (a.id === confirm.id ? { ...a, state: 'idle' } : a))); setStatus(`${app?.name} disconnected.`); }
+    setConfirm(null); requestAnimationFrame(() => heading.current?.focus());
+  };
+  const connect = async (id) => {
+    setApps((l) => l.map((a) => (a.id === id ? { ...a, state: 'pending' } : a)));
+    await wait(1200);
+    setApps((l) => l.map((a) => (a.id === id ? { ...a, state: 'connected' } : a)));
+  };
+  return (
+    <main className="dv-page">
+      <h2 ref={heading} tabIndex={-1} className="dv-h">Developers</h2>
+      <section className="dv-section" aria-labelledby="dv-keys-h">
+        <div className="dv-row"><h3 id="dv-keys-h" className="dv-sub">API keys</h3><A.Button size="sm" onClick={() => setCreating({ name: '' })}>Create key</A.Button></div>
+        <A.Table aria-labelledby="dv-keys-h">
+          <A.TableHeader><A.TableRow><A.TableHead>Name</A.TableHead><A.TableHead>Key</A.TableHead><A.TableHead>Last used</A.TableHead><A.TableHead align="end"><span className="dv-vh">Actions</span></A.TableHead></A.TableRow></A.TableHeader>
+          <A.TableBody>{keys.map((k) => <A.TableRow key={k.id}><A.TableCell>{k.name}</A.TableCell><A.TableCell><code className="dv-mask">ak_live_••••{k.tail}</code></A.TableCell><A.TableCell className="dv-muted">{k.used}</A.TableCell>
+            <A.TableCell align="end"><div className="dv-actions"><A.Button size="sm" variant="ghost" aria-label={`Roll ${k.name} key`} onClick={() => setConfirm({ kind: 'roll', id: k.id })}>Roll</A.Button><A.Button size="sm" variant="ghost" aria-label={`Revoke ${k.name} key`} onClick={() => setConfirm({ kind: 'revoke', id: k.id })}>Revoke</A.Button></div></A.TableCell></A.TableRow>)}</A.TableBody>
+        </A.Table>
+      </section>
+      <section className="dv-section" aria-labelledby="dv-hooks-h">
+        <h3 id="dv-hooks-h" className="dv-sub">Webhooks</h3>
+        <A.Card className="dv-hook">
+          <div className="dv-row"><code>https://api.acme.dev/hooks/altitude</code><A.Badge tone="positive">Active</A.Badge></div>
+          <div className="dv-events">{['invoice.paid', 'customer.updated', 'member.removed'].map((e) => <A.Checkbox key={e} label={e} defaultChecked={e !== 'member.removed'} />)}</div>
+          <A.Timeline aria-label="Recent deliveries" groupBy="none" locale="en-IE">
+            {deliveries.map((d) => <A.TimelineItem key={d.id} time={d.at} status={d.status} onRetry={d.result === 'Failed' ? () => retry(d.id) : undefined}>
+              <span className="dv-delivery"><code>{d.event}</code> <A.Badge tone={d.status === 'pending' ? 'neutral' : d.result === 'Delivered' ? 'positive' : 'critical'}>{d.status === 'pending' ? `Retrying (attempt ${d.attempt} of 5)` : d.result}</A.Badge></span>
+            </A.TimelineItem>)}
+          </A.Timeline>
+          <div><A.Button size="sm" onClick={() => setTest(true)}>Send test event</A.Button></div>
+          {test && <A.CodeBlock title="Test event sent: invoice.paid" language="json" code={PAYLOAD} />}
+        </A.Card>
+      </section>
+      <section className="dv-section" aria-labelledby="dv-apps-h" data-tells-ignore="LA4 installed integrations are peers; none should lead">
+        <h3 id="dv-apps-h" className="dv-sub">Integrations</h3>
+        <div className="dv-apps">{apps.map((a) => <A.Card key={a.id} className="dv-app" status={a.state === 'pending' ? 'pending' : undefined}>
+          <div className="dv-row"><strong>{a.name}</strong>{a.state === 'connected' && <A.Badge tone="positive">Connected</A.Badge>}</div>
+          <p className="dv-muted">{a.about}</p>
+          {a.state === 'connected' ? <A.Button size="sm" variant="ghost" onClick={() => setConfirm({ kind: 'disconnect', id: a.id })}>Disconnect</A.Button>
+            : <A.Button size="sm" loading={a.state === 'pending'} onClick={() => connect(a.id)}>{a.state === 'pending' ? 'Waiting for authorization' : `Connect ${a.name}`}</A.Button>}
+        </A.Card>)}</div>
+      </section>
+      <p className="dv-muted" role="status">{status}</p>
+      <A.Dialog open={!!creating} dismissible={!creating?.secret || !!creating?.saved} onOpenChange={(o) => { if (!o) setCreating(null); }} title={creating?.secret ? 'Save your new key' : 'Create an API key'}
+        footer={creating?.secret ? <A.Button variant="primary" disabled={!creating.saved} onClick={finishCreate}>Done</A.Button> : <><A.Button onClick={() => setCreating(null)}>Cancel</A.Button><A.Button variant="primary" onClick={create}>Create key</A.Button></>}>
+        {creating?.secret ? <A.SecretField label="Secret key" value={creating.secret} once warning="You won’t see this key again. Store it somewhere safe, like your secrets manager." onAcknowledge={() => setCreating({ ...creating, saved: true })} />
+          : <A.Field label="Key name" hint="Say where it’s used, like “Billing service”."><A.Input value={creating?.name || ''} onChange={(e) => creating && setCreating({ ...creating, name: e.target.value })} /></A.Field>}
+      </A.Dialog>
+      <A.Dialog open={!!confirm} background="stationary" size="sm" dismissible={!confirm?.busy} onOpenChange={(o) => { if (!o) setConfirm(null); }}
+        title={confirm?.kind === 'roll' ? `Roll the ${key?.name} key?` : confirm?.kind === 'revoke' ? `Revoke the ${key?.name} key?` : `Disconnect ${app?.name}?`}
+        description={confirm?.kind === 'roll' ? 'You’ll get a new key now. The old key keeps working for 24 hours, so you can update your services first.'
+          : confirm?.kind === 'revoke' ? `Requests that use it fail immediately. ${key?.used}.` : `${app?.name} stops receiving updates, and anyone using it loses access to Acme data through it.`}
+        footer={<><A.Button disabled={confirm?.busy} onClick={() => setConfirm(null)}>Cancel</A.Button><A.Button variant={confirm?.kind === 'roll' ? 'primary' : 'danger'} loading={confirm?.busy} onClick={act}>{confirm?.kind === 'roll' ? 'Roll key' : confirm?.kind === 'revoke' ? 'Revoke key' : 'Disconnect'}</A.Button></>} />
+    </main>
+  );
+}
+// preview:end
+export default App;