@moxxy/core 0.3.0

package/src/usage-stats.ts

@@ -0,0 +1,119 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { addModelTotals, createMutex, type ModelUsageTotals } from '@moxxy/sdk';
+import { writeFileAtomic } from '@moxxy/sdk/server';
+
+/**
+ * Cross-session token usage, persisted at ~/.moxxy/usage.json. A forward-going
+ * aggregate keyed by `"<provider>/<model>"`: each session folds its own
+ * `provider_response` usage and merges the delta in on shutdown (see
+ * `@moxxy/plugin-usage-stats`). Purely additive counters — no derived/cost
+ * fields — so a session's contribution is added once and the file stays a sum.
+ *
+ * Like preferences, this is best-effort: a missing or malformed file reads as
+ * empty, and a write failure never blocks shutdown.
+ */
+export interface StoredModelUsage extends ModelUsageTotals {
+  /** ISO timestamp of the first session that recorded usage for this model. */
+  readonly firstSeen: string;
+  /** ISO timestamp of the most recent session that recorded usage. */
+  readonly lastSeen: string;
+}
+
+export interface UsageStatsFile {
+  readonly version: 1;
+  /** ISO timestamp of the last merge/clear. */
+  readonly updatedAt: string;
+  /** Per-`provider/model` lifetime totals. */
+  readonly models: Record<string, StoredModelUsage>;
+}
+
+export function usageStatsPath(): string {
+  return path.join(os.homedir(), '.moxxy', 'usage.json');
+}
+
+function emptyStats(): UsageStatsFile {
+  return { version: 1, updatedAt: new Date().toISOString(), models: {} };
+}
+
+/**
+ * Read the usage aggregate. Returns an empty file when missing or unparseable —
+ * usage stats are an optional, non-load-blocking layer.
+ */
+export async function loadUsageStats(filePath: string = usageStatsPath()): Promise<UsageStatsFile> {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      typeof (parsed as UsageStatsFile).models === 'object' &&
+      (parsed as UsageStatsFile).models !== null
+    ) {
+      return parsed as UsageStatsFile;
+    }
+  } catch {
+    // missing or malformed — start fresh
+  }
+  return emptyStats();
+}
+
+async function writeAtomic(file: UsageStatsFile, filePath: string): Promise<void> {
+  await writeFileAtomic(filePath, JSON.stringify(file, null, 2) + '\n');
+}
+
+// Serializes the read-modify-write in `mergeUsageStats` so two concurrent
+// merges (e.g. overlapping shutdowns) can't both read the same snapshot and
+// have the second write clobber the first's delta.
+const mergeMutex = createMutex();
+
+/**
+ * Merge a session's per-model delta into the persisted aggregate and write it
+ * back. Reads the current file, adds each delta field-wise, refreshes
+ * first/lastSeen, and writes atomically. Returns the updated file.
+ *
+ * Best-effort: a write failure logs to stderr but does not throw — losing one
+ * session's stats must never block shutdown.
+ */
+export async function mergeUsageStats(
+  delta: Record<string, ModelUsageTotals>,
+  filePath: string = usageStatsPath(),
+): Promise<UsageStatsFile> {
+  // An empty delta writes nothing, so there's no read-modify-write to
+  // serialize: skip the mutex entirely and read the current file directly. A
+  // session with no recorded usage produces an empty delta on every shutdown,
+  // so this avoids needless I/O + contention on the common no-op path.
+  const keys = Object.keys(delta);
+  if (keys.length === 0) return loadUsageStats(filePath);
+
+  return mergeMutex.run(async () => {
+    const current = await loadUsageStats(filePath);
+
+    const now = new Date().toISOString();
+    const models: Record<string, StoredModelUsage> = { ...current.models };
+    for (const key of keys) {
+      const d = delta[key]!;
+      if (d.calls === 0) continue;
+      const existing = models[key];
+      models[key] = existing
+        ? { ...addModelTotals(existing, d), firstSeen: existing.firstSeen, lastSeen: now }
+        : { ...d, firstSeen: now, lastSeen: now };
+    }
+    const next: UsageStatsFile = { version: 1, updatedAt: now, models };
+    try {
+      await writeAtomic(next, filePath);
+    } catch (err) {
+      process.stderr.write(
+        `moxxy: failed to persist usage stats to ${filePath}: ` +
+          `${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    }
+    return next;
+  });
+}
+
+/** Reset the aggregate to empty (the user-facing `/usage clear`). */
+export async function clearUsageStats(filePath: string = usageStatsPath()): Promise<void> {
+  await writeAtomic(emptyStats(), filePath);
+}

package/src/view/default-renderer.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_VIEW_TAGS } from '@moxxy/sdk';
+import { defaultViewRenderer } from './default-renderer.js';
+
+describe('defaultViewRenderer', () => {
+  it('is named moxxy/default and exposes the default allow-list', () => {
+    expect(defaultViewRenderer.name).toBe('moxxy/default');
+    expect(defaultViewRenderer.allowList).toBe(DEFAULT_VIEW_TAGS);
+  });
+
+  it('parse returns ok for a valid spec and the expected title', () => {
+    const r = defaultViewRenderer.parse('<view title="hi"><text>x</text></view>');
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.doc.title).toBe('hi');
+  });
+
+  it('parse returns errors for an invalid spec', () => {
+    const r = defaultViewRenderer.parse('<view><nope/></view>');
+    expect(r.ok).toBe(false);
+  });
+
+  it('validate flags a hand-built unknown tag, passes a parsed doc', () => {
+    const r = defaultViewRenderer.parse('<view><text>x</text></view>');
+    if (!r.ok) throw new Error('expected ok');
+    expect(defaultViewRenderer.validate(r.doc)).toEqual([]);
+    const bad = defaultViewRenderer.validate({ root: { kind: 'element', tag: 'iframe', props: {}, children: [] } });
+    expect(bad.length).toBeGreaterThan(0);
+  });
+});

package/src/view/default-renderer.ts

@@ -0,0 +1,14 @@
+import { DEFAULT_VIEW_TAGS, defineViewRenderer } from '@moxxy/sdk';
+import { parseView, validateDoc } from './parse.js';
+
+/**
+ * The built-in view-spec renderer, seeded into every session's
+ * {@link ViewRendererRegistry}. Plugins may register/replace and `setActive`
+ * an alternative renderer with a different vocabulary.
+ */
+export const defaultViewRenderer = defineViewRenderer({
+  name: 'moxxy/default',
+  allowList: DEFAULT_VIEW_TAGS,
+  parse: (source) => parseView(source, DEFAULT_VIEW_TAGS),
+  validate: (doc) => validateDoc(doc, DEFAULT_VIEW_TAGS),
+});

package/src/view/parse-extended.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_VIEW_TAGS, type ViewNode } from '@moxxy/sdk';
+import { countNodes, parseView } from './parse.js';
+
+const parse = (src: string) => parseView(src, DEFAULT_VIEW_TAGS);
+const ok = (src: string) => {
+  const r = parse(src);
+  if (!r.ok) throw new Error(`expected ok, got errors: ${r.errors.map((e) => e.message).join('; ')}`);
+  return r.doc;
+};
+const errs = (src: string): string[] => {
+  const r = parse(src);
+  if (r.ok) throw new Error('expected errors');
+  return r.errors.map((e) => e.message);
+};
+const hasErr = (src: string, re: RegExp) => expect(errs(src).some((m) => re.test(m))).toBe(true);
+
+function find(node: ViewNode, tag: string): Extract<ViewNode, { kind: 'element' }> | null {
+  if (node.kind === 'element') {
+    if (node.tag === tag) return node;
+    for (const c of node.children) {
+      const hit = find(c, tag);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+function findAll(node: ViewNode, tag: string): Array<Extract<ViewNode, { kind: 'element' }>> {
+  const out: Array<Extract<ViewNode, { kind: 'element' }>> = [];
+  const walk = (n: ViewNode) => {
+    if (n.kind !== 'element') return;
+    if (n.tag === tag) out.push(n);
+    n.children.forEach(walk);
+  };
+  walk(node);
+  return out;
+}
+function firstText(node: ViewNode): string | null {
+  if (node.kind === 'text') return node.value;
+  for (const c of node.children) {
+    const t = firstText(c);
+    if (t != null) return t;
+  }
+  return null;
+}
+
+describe('attribute coercion', () => {
+  it('coerces booleans: bare, ="true", ="false"', () => {
+    const doc = ok('<view><input name="a" required /><input name="b" required="true" /><input name="c" required="false" /></view>');
+    const inputs = findAll(doc.root, 'input');
+    expect(inputs[0]!.props.required).toBe(true);
+    expect(inputs[1]!.props.required).toBe(true);
+    expect(inputs[2]!.props.required).toBe(false);
+  });
+
+  it('coerces numbers including negatives and floats are range-checked', () => {
+    expect(find(ok('<view><grid cols="4"></grid></view>').root, 'grid')!.props.cols).toBe(4);
+    hasErr('<view><grid cols="0"></grid></view>', /must be ≥ 1/);
+    hasErr('<view><grid cols="abc"></grid></view>', /must be a number/);
+    hasErr('<view><heading level="5">x</heading></view>', /must be ≤ 3/);
+  });
+
+  it('validates each enum attribute', () => {
+    ok('<view><stack gap="lg" align="center"></stack></view>');
+    ok('<view><row justify="between"></row></view>');
+    ok('<view><text tone="muted" weight="bold">x</text></view>');
+    ok('<view><button action="a" label="b" variant="danger" /></view>');
+    ok('<view><input name="n" type="email" /></view>');
+    hasErr('<view><stack gap="huge"></stack></view>', /gap.*must be one of/);
+    hasErr('<view><input name="n" type="color" /></view>', /type.*must be one of/);
+    hasErr('<view><button action="a" label="b" variant="rainbow" /></view>', /variant.*must be one of/);
+  });
+
+  it('rejects a value-less non-boolean attribute', () => {
+    hasErr('<view><text tone>x</text></view>', /tone.*must be one of|expects a value/);
+  });
+
+  it('parses single-quoted, double-quoted, and brace values', () => {
+    const doc = ok(`<view title='single'><image src="https://x/i.png" alt='a "b"' /></view>`);
+    expect(doc.title).toBe('single');
+  });
+});
+
+describe('text + entities + comments', () => {
+  it('decodes entities and collapses whitespace', () => {
+    const doc = ok('<view><text>a &amp; b   &lt;tag&gt;  &quot;q&quot;</text></view>');
+    expect(firstText(find(doc.root, 'text')!)).toBe('a & b <tag> "q"');
+  });
+
+  it('drops whitespace-only text nodes', () => {
+    const doc = ok('<view>\n  <stack>\n    <text>hi</text>\n  </stack>\n</view>');
+    const stack = find(doc.root, 'stack')!;
+    expect(stack.children.every((c) => c.kind === 'element')).toBe(true);
+  });
+
+  it('strips comments', () => {
+    const doc = ok('<view><!-- a comment --><text>x</text></view>');
+    expect(find(doc.root, 'text')).not.toBeNull();
+  });
+
+  it('treats self-closing and explicit-close equivalently', () => {
+    expect(ok('<view><divider /></view>')).toBeTruthy();
+    // divider is a void element; an explicit close with content would error,
+    // but an empty explicit close is acceptable structurally.
+    expect(parse('<view><divider></divider></view>').ok).toBe(true);
+  });
+});
+
+describe('nesting rules', () => {
+  it('accepts table → tr → th/td', () => {
+    ok('<view><table><tr><th>H</th></tr><tr><td>1</td></tr></table></view>');
+  });
+  it('rejects table → td directly (must be tr)', () => {
+    hasErr('<view><table><td>x</td></table></view>', /<table> may not contain <td>/);
+  });
+  it('rejects list → text (must be item)', () => {
+    hasErr('<view><list><text>x</text></list></view>', /<list> may not contain <text>/);
+  });
+  it('accepts list → item', () => {
+    ok('<view><list ordered="true"><item>one</item><item>two</item></list></view>');
+  });
+  it('rejects select → input (must be option)', () => {
+    hasErr('<view><select name="s"><input name="x" /></select></view>', /<select> may not contain <input>/);
+  });
+  it('rejects children on void elements', () => {
+    hasErr('<view><image src="https://x/i.png">child</image></view>', /<image> may not have children|may not contain text/);
+  });
+});
+
+describe('structural errors collect or fail clearly', () => {
+  it('reports multiple validation errors in one pass', () => {
+    const messages = errs('<view><blink/><text foo="1">x</text></view>');
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+  });
+  it('unbalanced / mismatched / multi-root', () => {
+    hasErr('<view><card>', /unclosed tag <card>/);
+    hasErr('<view><card></row></view>', /mismatched closing tag/);
+    hasErr('<a/><b/>', /exactly one root element/);
+    hasErr('   ', /exactly one root element|root/);
+  });
+});
+
+describe('security rejections', () => {
+  it('rejects script/style/iframe/object tags as unknown', () => {
+    for (const tag of ['script', 'style', 'iframe', 'object', 'embed', 'svg']) {
+      hasErr(`<view><${tag}>x</${tag}></view>`, new RegExp(`unknown tag <${tag}>`));
+    }
+  });
+  it('rejects every on* handler attribute', () => {
+    for (const h of ['onclick', 'onload', 'onerror', 'onmouseover']) {
+      hasErr(`<view><button action="a" label="b" ${h}="evil()" /></view>`, /forbidden attribute/);
+    }
+  });
+  it('URL scheme allow-list on href and src', () => {
+    ok('<view><link href="https://ok.com">x</link></view>');
+    ok('<view><link href="mailto:a@b.com">x</link></view>');
+    ok('<view><link href="/relative/path">x</link></view>');
+    ok('<view><link href="#anchor">x</link></view>');
+    ok('<view><image src="data:image/png;base64,AAAA" /></view>');
+    hasErr('<view><link href="javascript:alert(1)">x</link></view>', /disallowed URL scheme/);
+    hasErr('<view><link href="vbscript:x">y</link></view>', /disallowed URL scheme/);
+    hasErr('<view><image src="data:text/html,<script>" />\n</view>', /disallowed URL scheme/);
+    hasErr('<view><link href="ftp://x">y</link></view>', /disallowed URL scheme/);
+  });
+});
+
+describe('action extraction', () => {
+  it('form action carries all descendant field names (excluding buttons)', () => {
+    const doc = ok(`
+      <view><form action="go" submit="Go">
+        <input name="a" /><row><select name="b"><option value="x">x</option></select></row>
+        <checkbox name="c" /><button action="other" label="Other" />
+      </form></view>`);
+    const form = find(doc.root, 'form')!;
+    expect(form.action?.name).toBe('go');
+    expect(form.action?.fields).toEqual(['a', 'b', 'c']);
+  });
+  it('standalone button parses fields csv (trimmed, empties dropped)', () => {
+    const doc = ok('<view><button action="x" label="L" fields=" a , ,b " /></view>');
+    expect(find(doc.root, 'button')!.action?.fields).toEqual(['a', 'b']);
+  });
+  it('button with no fields has empty fields array', () => {
+    const doc = ok('<view><button action="x" label="L" /></view>');
+    expect(find(doc.root, 'button')!.action?.fields).toEqual([]);
+  });
+});
+
+describe('client-side navigation (to → nav)', () => {
+  it('sets node.nav from a `to` on a link and on a button', () => {
+    const doc = ok('<view><link to="search">Back</link><button to="results" label="Results" /></view>');
+    expect(find(doc.root, 'link')!.nav).toBe('search');
+    expect(find(doc.root, 'button')!.nav).toBe('results');
+  });
+  it('a button with action (no to) carries an action, not nav', () => {
+    const doc = ok('<view><button action="go" label="Go" /></view>');
+    const b = find(doc.root, 'button')!;
+    expect(b.action?.name).toBe('go');
+    expect(b.nav).toBeUndefined();
+  });
+  it('reads the view name onto the root props', () => {
+    const doc = ok('<view name="search" title="Search">x</view>');
+    const root = doc.root as Extract<typeof doc.root, { kind: 'element' }>;
+    expect(root.props.name).toBe('search');
+  });
+});
+
+describe('results expansion', () => {
+  const doc = ok(`
+    <view><results>
+      <result id="UA42" title="United SFO→JFK" subtitle="08:10 → 16:45" badge="$312" />
+      <result id="B6-11" title="JetBlue SFO→JFK" subtitle="11:30 → 20:05" badge="$289" />
+    </results></view>`);
+
+  it('removes component tags and emits one card per result', () => {
+    expect(find(doc.root, 'results')).toBeNull();
+    expect(find(doc.root, 'result')).toBeNull();
+    expect(findAll(doc.root, 'card')).toHaveLength(2);
+  });
+  it('defaults each result to an open:<id> action button', () => {
+    const buttons = findAll(doc.root, 'button');
+    expect(buttons.map((b) => b.action?.name)).toEqual(['open:UA42', 'open:B6-11']);
+  });
+  it('renders title, subtitle and badge in the tree', () => {
+    const texts = findAll(doc.root, 'text').map(firstText);
+    expect(texts).toContain('United SFO→JFK');
+    expect(texts).toContain('08:10 → 16:45');
+    expect(findAll(doc.root, 'badge').map(firstText)).toContain('$312');
+  });
+  it('honours an explicit `to` (client nav) or `action` over the default', () => {
+    const d = ok('<view><results><result title="A" to="detail:a" /><result title="B" action="buy:b" /></results></view>');
+    const buttons = findAll(d.root, 'button');
+    expect(buttons[0]!.nav).toBe('detail:a');
+    expect(buttons[1]!.action?.name).toBe('buy:b');
+  });
+  it('an expanded tree contains no component tags', () => {
+    expect(findAll(doc.root, 'results').length + findAll(doc.root, 'result').length).toBe(0);
+  });
+});
+
+describe('countNodes', () => {
+  it('counts elements and text nodes', () => {
+    const doc = ok('<view><text>a</text><text>b</text></view>');
+    // view + 2 text elements + 2 text nodes = 5
+    expect(countNodes(doc.root)).toBe(5);
+  });
+});
+
+describe('large / deep documents', () => {
+  it('parses deeply nested stacks', () => {
+    let inner = '<text>deep</text>';
+    for (let i = 0; i < 40; i++) inner = `<stack>${inner}</stack>`;
+    const doc = ok(`<view>${inner}</view>`);
+    expect(firstText(doc.root)).toBe('deep');
+  });
+});

package/src/view/parse.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_VIEW_TAGS, type ViewNode } from '@moxxy/sdk';
+import { parseView, validateDoc } from './parse.js';
+
+const parse = (src: string) => parseView(src, DEFAULT_VIEW_TAGS);
+
+function find(node: ViewNode, tag: string): Extract<ViewNode, { kind: 'element' }> | null {
+  if (node.kind === 'element') {
+    if (node.tag === tag) return node;
+    for (const c of node.children) {
+      const hit = find(c, tag);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+function findAll(node: ViewNode, tag: string): Array<Extract<ViewNode, { kind: 'element' }>> {
+  const out: Array<Extract<ViewNode, { kind: 'element' }>> = [];
+  const walk = (n: ViewNode) => {
+    if (n.kind !== 'element') return;
+    if (n.tag === tag) out.push(n);
+    n.children.forEach(walk);
+  };
+  walk(node);
+  return out;
+}
+
+describe('parseView — valid', () => {
+  it('parses a form, extracts the title and the form action + fields', () => {
+    const res = parse(`
+      <view title="Find flights">
+        <form action="search_flights" submit="Search">
+          <row gap="md">
+            <input name="from" label="From" required />
+            <input name="to" label="To" required />
+          </row>
+          <input name="depart" type="date" label="Depart" />
+          <select name="cabin" value="economy">
+            <option value="economy">Economy</option>
+            <option value="business">Business</option>
+          </select>
+        </form>
+      </view>
+    `);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.doc.title).toBe('Find flights');
+    const form = find(res.doc.root, 'form')!;
+    expect(form.action?.name).toBe('search_flights');
+    expect(form.action?.fields).toEqual(['from', 'to', 'depart', 'cabin']);
+    // submit is a recognized attribute, coerced onto props
+    expect(form.props.submit).toBe('Search');
+  });
+
+  it('expands results into a card stack with open buttons', () => {
+    const res = parse(`
+      <view title="2 results">
+        <results>
+          <result id="UA42" title="United SFO→JFK" subtitle="08:10 → 16:45" badge="$312" />
+          <result id="B6-11" title="JetBlue SFO→JFK" subtitle="11:30 → 20:05" badge="$289" />
+        </results>
+      </view>
+    `);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    // No component tags survive expansion.
+    expect(find(res.doc.root, 'results')).toBeNull();
+    expect(find(res.doc.root, 'result')).toBeNull();
+    const cards = findAll(res.doc.root, 'card');
+    expect(cards).toHaveLength(2);
+    const buttons = findAll(res.doc.root, 'button');
+    // No explicit action/to → defaults to open:<id>.
+    expect(buttons.map((b) => b.action?.name)).toEqual(['open:UA42', 'open:B6-11']);
+  });
+
+  it('coerces number, boolean and enum attributes', () => {
+    const res = parse(`<view><grid cols="3" gap="lg"><input name="q" required /></grid></view>`);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    const grid = find(res.doc.root, 'grid')!;
+    expect(grid.props.cols).toBe(3);
+    expect(grid.props.gap).toBe('lg');
+    const input = find(res.doc.root, 'input')!;
+    expect(input.props.required).toBe(true);
+  });
+
+  it('u50-2: decodes HTML entities in attribute string values (consistent with text)', () => {
+    const res = parse(`<view><image src="/logo.png" alt="Tom &amp; Jerry &lt;3" /></view>`);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    const img = find(res.doc.root, 'image')!;
+    expect(img.props.alt).toBe('Tom & Jerry <3');
+  });
+
+  it('u50-2: entity-decoded href is still scheme-checked on the decoded value', () => {
+    // A plain disallowed scheme stays rejected (unchanged).
+    expect(parse(`<view><link href="javascript:alert(1)">x</link></view>`).ok).toBe(false);
+    // An href whose entities decode to a still-safe value is accepted, with
+    // the decoded form on props.
+    const res = parse(`<view><link href="https://x.test/?a=1&amp;b=2">x</link></view>`);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(find(res.doc.root, 'link')!.props.href).toBe('https://x.test/?a=1&b=2');
+  });
+
+  it('carries explicit button fields from a csv', () => {
+    const res = parse(`<view><button action="go" label="Go" fields="a, b ,c" /></view>`);
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(find(res.doc.root, 'button')!.action?.fields).toEqual(['a', 'b', 'c']);
+  });
+});
+
+describe('parseView — rejected (security + allow-list)', () => {
+  const expectError = (src: string, match: RegExp) => {
+    const res = parse(src);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.errors.some((e) => match.test(e.message))).toBe(true);
+  };
+
+  it('rejects unknown tags (incl. <script>)', () => {
+    expectError(`<view><script>alert(1)</script></view>`, /unknown tag <script>/);
+    expectError(`<view><marquee>hi</marquee></view>`, /unknown tag <marquee>/);
+  });
+
+  it('rejects unknown attributes', () => {
+    expectError(`<view><text style="color:red">x</text></view>`, /unknown attribute "style"/);
+  });
+
+  it('u50-3: an unknown tag yields exactly one error, not one-per-attribute', () => {
+    const res = parse(`<view><evil a="1" b="2" /></view>`);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    // Exactly the tag error — no `unknown attribute` spam for a/b on top of it.
+    expect(res.errors.some((e) => /unknown tag <evil>/.test(e.message))).toBe(true);
+    expect(res.errors.some((e) => /unknown attribute/.test(e.message))).toBe(false);
+    expect(res.errors).toHaveLength(1);
+  });
+
+  it('u50-3: on* handlers on an unknown tag are still rejected (no attr-suppression bypass)', () => {
+    const res = parse(`<view><evil onclick="boom()" /></view>`);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.errors.some((e) => /unknown tag <evil>/.test(e.message))).toBe(true);
+    expect(res.errors.some((e) => /forbidden attribute "onclick"/.test(e.message))).toBe(true);
+  });
+
+  it('rejects on* handler attributes', () => {
+    expectError(`<view><button action="x" label="y" onclick="evil()" /></view>`, /forbidden attribute "onclick"/);
+  });
+
+  it('rejects disallowed URL schemes on href/src', () => {
+    expectError(`<view><link href="javascript:alert(1)">x</link></view>`, /disallowed URL scheme/);
+    expectError(`<view><image src="javascript:alert(1)" /></view>`, /disallowed URL scheme/);
+  });
+
+  it('allows https and relative URLs', () => {
+    expect(parse(`<view><link href="https://example.com">x</link></view>`).ok).toBe(true);
+    expect(parse(`<view><link href="/local">x</link></view>`).ok).toBe(true);
+  });
+
+  it('allows mailto/tel hrefs and data:image src; rejects data:text src', () => {
+    expect(parse(`<view><link href="mailto:a@b.c">x</link></view>`).ok).toBe(true);
+    expect(parse(`<view><link href="tel:+15551234">x</link></view>`).ok).toBe(true);
+    expect(parse(`<view><image src="data:image/png;base64,AAAA" /></view>`).ok).toBe(true);
+    expectError(`<view><image src="data:text/html,<script>1</script>" /></view>`, /disallowed URL scheme/);
+    expectError(`<view><link href="data:image/png;base64,AAAA">x</link></view>`, /disallowed URL scheme/);
+  });
+
+  it('rejects out-of-range numbers and bad enums', () => {
+    expectError(`<view><grid cols="9"></grid></view>`, /must be ≤ 6/);
+    expectError(`<view><text tone="rainbow">x</text></view>`, /must be one of/);
+  });
+
+  it('rejects missing required attributes', () => {
+    expectError(`<view><input label="no name" /></view>`, /missing required attribute "name"/);
+  });
+
+  it('rejects disallowed children', () => {
+    expectError(`<view><list><text>not an item</text></list></view>`, /<list> may not contain <text>/);
+    expectError(`<view><divider>nope</divider></view>`, /<divider> may not contain text/);
+  });
+
+  it('rejects structural errors', () => {
+    expectError(`<view><card>unclosed`, /unclosed tag <card>/);
+    expectError(`<view></card></view>`, /mismatched closing tag/);
+    expectError(`<card>a</card><card>b</card>`, /exactly one root element/);
+  });
+});
+
+describe('validateDoc', () => {
+  it('passes a parsed (expanded) doc and flags a hand-built bad node', () => {
+    const ok = parse(`<view><text>hi</text></view>`);
+    expect(ok.ok).toBe(true);
+    if (!ok.ok) return;
+    expect(validateDoc(ok.doc, DEFAULT_VIEW_TAGS)).toEqual([]);
+
+    const bad = validateDoc(
+      { root: { kind: 'element', tag: 'evil', props: {}, children: [] } },
+      DEFAULT_VIEW_TAGS,
+    );
+    expect(bad.some((e) => /unknown tag <evil>/.test(e.message))).toBe(true);
+  });
+
+  it('rejects disallowed URL schemes in a hand-built AST (href/src never bypass the parser)', () => {
+    const errsFor = (tag: string, props: Record<string, string>) =>
+      validateDoc(
+        {
+          root: {
+            kind: 'element',
+            tag: 'view',
+            props: {},
+            children: [{ kind: 'element', tag, props, children: [] }],
+          },
+        },
+        DEFAULT_VIEW_TAGS,
+      );
+    expect(
+      errsFor('link', { href: 'javascript:alert(1)' }).some((e) => /disallowed URL scheme/.test(e.message)),
+    ).toBe(true);
+    expect(
+      errsFor('image', { src: 'data:text/html,<script>1</script>' }).some((e) =>
+        /disallowed URL scheme/.test(e.message),
+      ),
+    ).toBe(true);
+    // Safe schemes stay clean.
+    expect(errsFor('link', { href: 'https://example.com' })).toEqual([]);
+    expect(errsFor('image', { src: 'data:image/png;base64,AAAA' })).toEqual([]);
+  });
+});