@lovett/ui 0.0.10 → 0.1.0

package/src/thread/__tests__/comment-body-hostile.test.tsx

@@ -0,0 +1,331 @@
+/**
+ * CommentBody under hostile and malformed markdown — ADR-148 AC#5, AC#6, AC#8.
+ *
+ * Three assertions per corpus entry (AC#6):
+ *   1. rendering does not throw (and React logs no error);
+ *   2. nothing user-controlled became executable — no script/iframe/object/
+ *      embed element, no `on*` handler attribute, no `javascript:` / `data:` /
+ *      `vbscript:` href;
+ *   3. no text was silently dropped — every VISIBLE piece of the input is in
+ *      `textContent`. "Visible" is what a reader of the source would expect
+ *      to see: link and mention TEXT, never a destination (a URL is an
+ *      attribute in every renderer); a horizontal rule has no words.
+ *
+ * Cross-comment isolation (AC#5): two bodies rendered as `comment.tsx` does —
+ * each its own `<CommentBody>` — and the second one's DOM must be
+ * byte-identical whether the first is benign or a construct CommonMark leaves
+ * open (an unclosed fence swallows the rest of ITS comment, by spec).
+ *
+ * URL allowlist (AC#8): exactly the three mention schemes pass through; every
+ * other scheme goes to `defaultUrlTransform`, and the dangerous ones render
+ * with a null or empty href (`defaultUrlTransform` returns '' and React emits
+ * the attribute empty — inert either way).
+ *
+ * The underline marker is spelled as an escape (`PP`) so the file never holds
+ * the syntax literally and stays plain UTF-8 for the CLAUDE.md section 8 greps.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { fireEvent, render } from '@testing-library/react'
+import { CommentBody, type MentionTarget } from '../comment-body'
+
+/** `++` — two U+002B PLUS SIGN. */
+const PP = '\u{2B}\u{2B}'
+
+const EXECUTABLE =
+  'script, iframe, object, embed, [onerror], [onload], [onclick], [onmouseover], [onfocus], [srcdoc]'
+const DANGEROUS_HREF = /^\s*(?:javascript|data|vbscript)\s*:/i
+
+interface Case {
+  readonly name: string
+  readonly body: string
+  /** Every entry must appear in `textContent`. Empty when the input has no words. */
+  readonly visible: readonly string[]
+  /** A selector that must match, for cases whose STRUCTURE is the point. */
+  readonly selector?: string
+}
+
+const LONG_LINE = 'lorem ipsum '.repeat(170).slice(0, 2000)
+const ADVERSARIAL_LINE = `a${PP} `.repeat(500)
+
+const CORPUS: readonly Case[] = [
+  { name: 'hello [', body: 'hello [', visible: ['hello ['] },
+  { name: 'hello ]', body: 'hello ]', visible: ['hello ]'] },
+  { name: 'hello [world', body: 'hello [world', visible: ['hello [world'] },
+  { name: 'hello ](url)', body: 'hello ](url)', visible: ['hello ](url)'] },
+  { name: 'hello `world', body: 'hello `world', visible: ['hello `world'] },
+  { name: 'hello **world', body: 'hello **world', visible: ['hello **world'] },
+  { name: 'hello _world', body: 'hello _world', visible: ['hello _world'] },
+  { name: 'a double quote', body: '"', visible: ['"'] },
+  { name: 'a single quote', body: "'", visible: ["'"] },
+  { name: 'one backslash', body: '\\', visible: ['\\'] },
+  // `\\` is a CommonMark escape for one backslash; `\\\\` for two. Rendering
+  // the escaped form is the spec, not loss.
+  { name: 'two backslashes', body: '\\\\', visible: ['\\'] },
+  { name: 'four backslashes', body: '\\\\\\\\', visible: ['\\\\'] },
+  { name: '<div>', body: '<div>', visible: ['<div>'] },
+  { name: '<div', body: '<div', visible: ['<div'] },
+  { name: '</div>', body: '</div>', visible: ['</div>'] },
+  { name: 'inline <div> in prose', body: 'hello <div>world</div>', visible: ['hello <div>world</div>'] },
+  { name: '<script>', body: '<script>alert(1)</script>', visible: ['<script>alert(1)</script>'] },
+  { name: 'inline <script> in prose', body: 'hi <script>alert(1)</script> there', visible: ['hi <script>alert(1)</script> there'] },
+  { name: '<img onerror>', body: 'x <img src=x onerror=alert(1)> y', visible: ['x <img src=x onerror=alert(1)> y'] },
+  { name: 'raw <a href="javascript:">', body: '<a href="javascript:alert(1)">click</a>', visible: ['<a href="javascript:alert(1)">click</a>'] },
+  { name: '[click](javascript:alert(1))', body: '[click](javascript:alert(1))', visible: ['click'], selector: 'a' },
+  { name: '[click](data:text/html,x)', body: '[click](data:text/html,x)', visible: ['click'], selector: 'a' },
+  { name: '[click](vbscript:msgbox)', body: '[click](vbscript:msgbox)', visible: ['click'], selector: 'a' },
+  { name: '@[foo](https://example.com)', body: '@[foo](https://example.com)', visible: ['@', 'foo'], selector: 'a[href="https://example.com"]' },
+  { name: '@[foo](user:not-valid)', body: '@[foo](user:not-valid)', visible: ['@', 'foo'] },
+  { name: 'an unclosed fence with two lines after it', body: '```\nline one\nline two', visible: ['line one', 'line two'], selector: 'pre' },
+  { name: 'a bare fence renders a code block', body: '```\nconst a = 1\n```', visible: ['const a = 1'], selector: 'pre' },
+  { name: 'an unclosed fence with a language', body: '```ts\nconst a = 1\nconst b = 2', visible: ['const a = 1', 'const b = 2'] },
+  { name: `${PP}unclosed`, body: `${PP}unclosed`, visible: [`${PP}unclosed`] },
+  { name: `${PP}text${PP} renders an underline`, body: `${PP}text${PP}`, visible: ['text'], selector: 'u' },
+  { name: 'nested **bold and _italic_**', body: 'nested **bold and _italic_**', visible: ['nested', 'bold and', 'italic'], selector: 'strong em' },
+  { name: '[`code`](https://example.com)', body: '[`code`](https://example.com)', visible: ['code'], selector: 'a code' },
+  { name: 'literal * asterisks *', body: 'literal * asterisks *', visible: ['literal * asterisks *'] },
+  { name: 'a 2,000-character single line', body: LONG_LINE, visible: [LONG_LINE.trimEnd()] },
+  { name: 'a 2,000-character line of unpaired markers', body: ADVERSARIAL_LINE, visible: [ADVERSARIAL_LINE.trimEnd()] },
+  { name: 'a body that is only ---', body: '---', visible: [], selector: 'hr' },
+  { name: 'an empty body', body: '', visible: [] },
+  { name: 'only whitespace', body: '   \n\t\n', visible: [] },
+  { name: 'a GFM table (out of the editor subset, still renders)', body: '| a | b |\n|---|---|\n| 1 | 2 |', visible: ['a', 'b', '1', '2'], selector: 'table' },
+  { name: 'a task list', body: '- [ ] open\n- [x] done', visible: ['open', 'done'] },
+  { name: 'an autolink literal', body: 'see https://example.com/path now', visible: ['see', 'https://example.com/path', 'now'], selector: 'a[href="https://example.com/path"]' },
+  { name: 'an angle-bracket javascript destination', body: '[x](<javascript:alert(1)>)', visible: ['x'] },
+  { name: 'an entity-encoded javascript scheme', body: '[x](javascript&#58;alert(1))', visible: ['x'] },
+  { name: 'an upper-case javascript scheme', body: '[x](JAVASCRIPT:alert(1))', visible: ['x'] },
+  { name: 'an image with a javascript source', body: '![alt](javascript:alert(1))', visible: ['alt'] },
+  { name: 'an image with a safe source', body: '![photo](https://example.com/x.png)', visible: ['photo'] },
+]
+
+function renderBody(body: string, onSelectMention?: (target: MentionTarget) => void) {
+  return render(
+    <CommentBody
+      bodyMd={body}
+      {...(onSelectMention === undefined ? {} : { onSelectMention })}
+    />,
+  )
+}
+
+describe('CommentBody — malformed-markdown corpus (AC#6)', () => {
+  expect(LONG_LINE).toHaveLength(2000)
+  expect(ADVERSARIAL_LINE).toHaveLength(2000)
+
+  for (const { name, body, visible, selector } of CORPUS) {
+    it(name, () => {
+      const errors = vi.spyOn(console, 'error').mockImplementation(() => {})
+      let container: HTMLElement | undefined
+
+      // 1. No throw — and no React error either (a boundary would log, not throw).
+      expect(() => {
+        container = renderBody(body).container
+      }).not.toThrow()
+      expect(errors).not.toHaveBeenCalled()
+      errors.mockRestore()
+      if (container === undefined) throw new Error('unreachable: render returned nothing')
+
+      // 2. Nothing executable reached the DOM.
+      expect(container.querySelector(EXECUTABLE)).toBeNull()
+      for (const anchor of Array.from(container.querySelectorAll('a'))) {
+        expect(anchor.getAttribute('href') ?? '').not.toMatch(DANGEROUS_HREF)
+      }
+      for (const image of Array.from(container.querySelectorAll('img'))) {
+        expect(image.getAttribute('src') ?? '').not.toMatch(DANGEROUS_HREF)
+      }
+
+      // 3. Nothing visible was dropped.
+      const text = container.textContent ?? ''
+      for (const piece of visible) expect(text).toContain(piece)
+
+      if (selector !== undefined) expect(container.querySelector(selector)).not.toBeNull()
+    })
+  }
+
+  // Images are outside the composer's subset (ADR-148 D3; ADR-151 owns
+  // attachments) but typeable. They render as alt text and nothing else — no
+  // `<img>` at all, so no request to a user-supplied URL and no empty-`src`
+  // element (React used to warn about that one) when a dangerous URL is
+  // stripped.
+  it('an image renders its alt text and no <img>, whatever the source', () => {
+    for (const [body, alt] of [
+      ['![alt](javascript:alert(1))', 'alt'],
+      ['![photo](https://example.com/x.png)', 'photo'],
+      ['![diagram](data:image/svg+xml,x)', 'diagram'],
+    ] as const) {
+      const errors = vi.spyOn(console, 'error').mockImplementation(() => {})
+      const { container, unmount } = renderBody(body)
+      expect(errors, body).not.toHaveBeenCalled()
+      errors.mockRestore()
+      expect(container.querySelector('img'), body).toBeNull()
+      expect(container.textContent, body).toBe(alt)
+      unmount()
+    }
+  })
+
+  it('an image with no alt text renders nothing, and no <img>', () => {
+    const { container } = renderBody('![](https://example.com/x.png)')
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.textContent).toBe('')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// AC#5 — cross-comment isolation
+// ---------------------------------------------------------------------------
+
+/** A second comment exercising every construct the composer can emit. */
+const SECOND_BODY = [
+  `second **bold** *italic* ${PP}under${PP} ~~gone~~ [link](https://example.com) \`code\` @[Ada](user:usr_1)`,
+  '',
+  '# heading',
+  '',
+  '- item one',
+  '- item two',
+  '',
+  '> quoted',
+  '',
+  '```',
+  'fenced',
+  '```',
+  '',
+  '---',
+  '',
+  'last line',
+].join('\n')
+
+const BENIGN_FIRST = 'a perfectly ordinary first comment'
+
+/** `[name, body, visible words]` — the words a reader of the source expects to see. */
+const OPEN_FIRSTS: ReadonlyArray<readonly [name: string, body: string, visible: readonly string[]]> = [
+  ['an unclosed fence', '```\nline one\nline two', ['line one', 'line two']],
+  ['an unclosed fence with a language', '```ts\nconst x = 1', ['const x = 1']],
+  [`an unclosed ${PP}`, `${PP}unclosed`, [`${PP}unclosed`]],
+  ['an open [', 'hello [', ['hello [']],
+  ['an open [ with text after', 'hello [world and more', ['hello [world and more']],
+  ['an unclosed **', 'hello **world', ['hello **world']],
+  ['an unclosed backtick', 'hello `world', ['hello `world']],
+  ['an unclosed raw tag', '<div', ['<div']],
+]
+
+/** Render two bodies the way `comment.tsx` does — each its own instance — and return the second's DOM. */
+function secondBodyHtml(first: string): string {
+  const { container, unmount } = render(
+    <>
+      <CommentBody bodyMd={first} />
+      <CommentBody bodyMd={SECOND_BODY} />
+    </>,
+  )
+  expect(container.children).toHaveLength(2)
+  const second = container.children[1]
+  const out = second?.outerHTML ?? ''
+  unmount()
+  return out
+}
+
+describe('CommentBody — cross-comment isolation (AC#5)', () => {
+  const control = secondBodyHtml(BENIGN_FIRST)
+
+  it('the control second body actually rendered its structure', () => {
+    // Guards against the equality below being vacuous.
+    for (const needle of ['<strong', '<em', '<u ', '<del', '<a ', '<code', '<pre', 'Copy code', '<h1', '<li', '<blockquote', '<hr', 'Ada', 'last line']) {
+      expect(control).toContain(needle)
+    }
+  })
+
+  for (const [name, first] of OPEN_FIRSTS) {
+    it(`is byte-identical after ${name}`, () => {
+      expect(secondBodyHtml(first)).toBe(control)
+    })
+  }
+
+  it('the open first body still renders its own text (strangely, by itself)', () => {
+    for (const [name, first, visible] of OPEN_FIRSTS) {
+      const { container, unmount } = renderBody(first)
+      const text = container.textContent ?? ''
+      for (const word of visible) expect(text, name).toContain(word)
+      unmount()
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// AC#8 — the URL allowlist stays exact
+// ---------------------------------------------------------------------------
+
+describe('CommentBody — URL allowlist (AC#8)', () => {
+  const MENTIONS: ReadonlyArray<readonly [scheme: MentionTarget['type'], id: string]> = [
+    ['user', 'usr_9f2'],
+    ['task_item', 'tit_44a'],
+    ['task_board', 'tbd_1'],
+  ]
+
+  for (const [scheme, id] of MENTIONS) {
+    it(`passes ${scheme}: through as a mention chip`, () => {
+      const onSelectMention = vi.fn<(target: MentionTarget) => void>()
+      const { container, unmount } = renderBody(`@[Target](${scheme}:${id})`, onSelectMention)
+      // Not an anchor — the href never reaches the DOM as a link at all.
+      expect(container.querySelector('a')).toBeNull()
+      const chip = container.querySelector('button')
+      expect(chip).not.toBeNull()
+      expect(chip?.textContent).toBe('Target')
+      if (chip !== null) fireEvent.click(chip)
+      expect(onSelectMention).toHaveBeenCalledTimes(1)
+      expect(onSelectMention).toHaveBeenCalledWith({ type: scheme, id })
+      unmount()
+    })
+
+    it(`renders ${scheme}: as an inert chip when there is no handler`, () => {
+      const { container, unmount } = renderBody(`@[Target](${scheme}:${id})`)
+      expect(container.querySelector('a')).toBeNull()
+      expect(container.querySelector('button')).toBeNull()
+      expect(container.textContent).toBe('@Target')
+      unmount()
+    })
+  }
+
+  it('javascript:, data: and vbscript: hrefs render with a null or empty href', () => {
+    for (const url of [
+      'javascript:alert(1)',
+      'JaVaScRiPt:alert(1)',
+      'javascript&#58;alert(1)',
+      'data:text/html,x',
+      'data:text/html;base64,PHNjcmlwdD5hbGVydCgxKTwvc2NyaXB0Pg==',
+      'vbscript:msgbox',
+      '<javascript:alert(1)>',
+    ]) {
+      const { container, unmount } = renderBody(`[click](${url})`)
+      const anchor = container.querySelector('a')
+      expect(anchor, url).not.toBeNull()
+      expect(anchor?.textContent, url).toBe('click')
+      // react-markdown's `defaultUrlTransform` returns '' for an unsafe
+      // protocol; React then emits the attribute empty. Either shape is inert
+      // and neither begins with the scheme — that is the outcome pinned here.
+      const href = anchor?.getAttribute('href')
+      expect(href === null || href === '', `${url} -> ${String(href)}`).toBe(true)
+      unmount()
+    }
+  })
+
+  it('does not widen the allowlist to look-alike schemes', () => {
+    for (const url of ['users:usr_1', 'user_x:1', 'task:tit_1', 'task_items:1', 'note:abc', 'user:', 'USER:usr_1']) {
+      const { container, unmount } = renderBody(`[x](${url})`)
+      // A near-miss is an ordinary link, not a chip...
+      expect(container.querySelector('button, span[class*="inline-flex"]'), url).toBeNull()
+      const anchor = container.querySelector('a')
+      expect(anchor, url).not.toBeNull()
+      // ...and its unknown scheme is dropped by the default transform.
+      const href = anchor?.getAttribute('href')
+      expect(href === null || href === '', `${url} -> ${String(href)}`).toBe(true)
+      unmount()
+    }
+  })
+
+  it('keeps ordinary safe hrefs exactly', () => {
+    for (const url of ['https://example.com/a?b=c:d', 'http://example.com', 'mailto:ada@example.com', '/relative/path', '#fragment', '?q=a:b']) {
+      const { container, unmount } = renderBody(`[x](${url})`)
+      expect(container.querySelector('a')?.getAttribute('href'), url).toBe(url)
+      unmount()
+    }
+  })
+})

package/src/thread/__tests__/comment-tree.test.ts

@@ -0,0 +1,151 @@
+// @vitest-environment node
+/**
+ * comment-tree — the shape contract, and the D4 correction.
+ *
+ * These are pure-function tests in the node environment: no DOM, no clock, no
+ * randomness. The two that matter most are the deleted-parent and absent-parent
+ * cases, because the reference collapsed them into one behaviour and that is
+ * the bug ADR-147 D4 was written to stop.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  buildCommentTree,
+  countCommentTree,
+  countDescendants,
+  engagementScore,
+  sortCommentTree,
+} from '../comment-tree'
+import type { CommentNode, ThreadComment } from '../types'
+import { FIXTURE_NOW, THREAD_FIXTURE } from './fixtures/thread-fixture'
+
+function find(nodes: readonly CommentNode[], id: string): CommentNode | undefined {
+  for (const node of nodes) {
+    if (node.id === id) return node
+    const hit = find(node.replies, id)
+    if (hit !== undefined) return hit
+  }
+  return undefined
+}
+
+const comment = (over: Partial<ThreadComment> & { id: string }): ThreadComment => ({
+  bodyMd: 'body',
+  createdAt: FIXTURE_NOW,
+  ...over,
+})
+
+describe('buildCommentTree', () => {
+  it('returns a flat list unchanged when nothing has a parent', () => {
+    const flat = [comment({ id: 'a' }), comment({ id: 'b' }), comment({ id: 'c' })]
+    const roots = buildCommentTree(flat)
+    expect(roots.map((n) => n.id)).toEqual(['a', 'b', 'c'])
+    expect(roots.every((n) => n.replies.length === 0)).toBe(true)
+    expect(roots.every((n) => n.orphanedParentId === null)).toBe(true)
+  })
+
+  it('nests by parentId and records the TRUE depth', () => {
+    const roots = buildCommentTree(THREAD_FIXTURE)
+    const deep3 = find(roots, 'c-deep-3')
+    expect(deep3).toBeDefined()
+    // Depth is stored true and capped only at render time (D3).
+    expect(deep3?.depth).toBe(3)
+    expect(find(roots, 'c-deep-0')?.depth).toBe(0)
+  })
+
+  it('D4 — a DELETED parent keeps its subtree', () => {
+    const roots = buildCommentTree(THREAD_FIXTURE)
+    const parent = roots.find((n) => n.id === 'c-deleted-parent')
+    expect(parent).toBeDefined()
+    expect(parent?.deletedAt).toBeTypeOf('number')
+    // The children are STILL under it, not promoted to top level.
+    expect(parent?.replies.map((n) => n.id)).toEqual([
+      'c-deleted-child-a',
+      'c-deleted-child-b',
+    ])
+    expect(roots.some((n) => n.id === 'c-deleted-child-a')).toBe(false)
+  })
+
+  it('D4 — an ABSENT parent surfaces the reply at top level AND flags it', () => {
+    const roots = buildCommentTree(THREAD_FIXTURE)
+    const orphan = roots.find((n) => n.id === 'c-orphan')
+    expect(orphan).toBeDefined()
+    // Never dropped...
+    expect(orphan?.bodyMd).toContain('pacing')
+    // ...and never silently promoted as if it were a new remark.
+    expect(orphan?.orphanedParentId).toBe('c-not-on-this-page')
+  })
+
+  it('does not recurse forever on a parent cycle', () => {
+    const cyclic = [
+      comment({ id: 'a', parentId: 'b' }),
+      comment({ id: 'b', parentId: 'a' }),
+    ]
+    const roots = buildCommentTree(cyclic)
+    expect(countCommentTree(roots)).toBe(2)
+    expect(roots.every((n) => n.orphanedParentId !== null)).toBe(true)
+  })
+
+  it('counts every node at every depth', () => {
+    const roots = buildCommentTree(THREAD_FIXTURE)
+    expect(countCommentTree(roots)).toBe(THREAD_FIXTURE.length)
+  })
+
+  it('countDescendants excludes the node itself', () => {
+    const roots = buildCommentTree(THREAD_FIXTURE)
+    const many = roots.find((n) => n.id === 'c-many')
+    expect(many).toBeDefined()
+    expect(many?.replies.length).toBe(8)
+    expect(many === undefined ? -1 : countDescendants(many)).toBe(8)
+  })
+})
+
+describe('engagementScore', () => {
+  it('prefers an explicit vote score', () => {
+    const [node] = buildCommentTree([comment({ id: 'a', score: 12 })])
+    expect(node === undefined ? -1 : engagementScore(node)).toBe(12)
+  })
+
+  it('otherwise totals the reaction counts', () => {
+    const [node] = buildCommentTree([
+      comment({
+        id: 'a',
+        reactions: [
+          { key: 'up', count: 3, viewerReacted: false },
+          { key: 'heart', count: 2, viewerReacted: true },
+        ],
+      }),
+    ])
+    expect(node === undefined ? -1 : engagementScore(node)).toBe(5)
+  })
+})
+
+describe('sortCommentTree', () => {
+  const roots = buildCommentTree(THREAD_FIXTURE)
+
+  it('top puts pinned first and undelivered last', () => {
+    const sorted = sortCommentTree(roots, 'top')
+    expect(sorted[0]?.id).toBe('c-reactions')
+    const ids = sorted.map((n) => n.id)
+    expect(ids.indexOf('c-pending')).toBeGreaterThan(ids.indexOf('c-one-word'))
+    expect(ids.indexOf('c-failed')).toBeGreaterThan(ids.indexOf('c-one-word'))
+  })
+
+  it('newest puts the most recent root first', () => {
+    const sorted = sortCommentTree(roots, 'new')
+    expect(sorted[0]?.id).toBe('c-pending')
+  })
+
+  it('keeps replies chronological whichever sort the roots use', () => {
+    for (const sort of ['top', 'new'] as const) {
+      const many = sortCommentTree(roots, sort).find((n) => n.id === 'c-many')
+      const times = (many?.replies ?? []).map((n) => n.createdAt)
+      expect(times).toEqual([...times].sort((a, b) => a - b))
+    }
+  })
+
+  it('is deterministic — the same input always sorts the same way', () => {
+    const a = sortCommentTree(roots, 'top').map((n) => n.id)
+    const b = sortCommentTree(buildCommentTree(THREAD_FIXTURE), 'top').map((n) => n.id)
+    expect(a).toEqual(b)
+  })
+})

package/src/thread/__tests__/emoji.test.ts

@@ -0,0 +1,187 @@
+/**
+ * The curated shortcode table (ADR-149 D3), and the source-byte discipline it
+ * has to keep (AC#9).
+ *
+ * Two things are being defended here. The first is behaviour: the search has
+ * to find what a person actually types, in the dialect they know. The second
+ * is a property of the FILE rather than the code — every glyph is written as a
+ * `\u{...}` escape, so the table can grow to a thousand emoji without a single
+ * raw high byte reaching a source file. A raw high byte makes a file grep as
+ * binary, which silently blinds the CLAUDE.md §8 gates; ADR-147 D8 learned
+ * that once and this is the assertion that keeps it learned.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  EMOJI_RESULT_LIMIT,
+  THREAD_EMOJI,
+  emojiByShortcode,
+  normalizeShortcode,
+  searchEmoji,
+  type EmojiEntry,
+} from '../emoji'
+
+/* ── D3 — the table itself ────────────────────────────────────────────────── */
+
+describe('D3 — the table', () => {
+  it('is the size the ADR budgeted for: curated, not a dataset', () => {
+    expect(THREAD_EMOJI.length).toBeGreaterThanOrEqual(120)
+    expect(THREAD_EMOJI.length).toBeLessThanOrEqual(160)
+  })
+
+  it('has no duplicate name, glyph or shortcode — a lookup can only mean one thing', () => {
+    const names = new Set<string>()
+    const glyphs = new Set<string>()
+    const codes = new Set<string>()
+    for (const entry of THREAD_EMOJI) {
+      expect(names.has(entry.name)).toBe(false)
+      names.add(entry.name)
+      expect(glyphs.has(entry.glyph)).toBe(false)
+      glyphs.add(entry.glyph)
+      for (const code of [entry.name, ...entry.aliases]) {
+        const key = normalizeShortcode(code)
+        expect(codes.has(key)).toBe(false)
+        codes.add(key)
+      }
+    }
+  })
+
+  it('spells every shortcode in the character set a `:` query can actually carry', () => {
+    // The trigger's own match is `:[^\s:]*`, so a shortcode holding a space or
+    // a colon would be unreachable by typing — a dead row in the table.
+    for (const entry of THREAD_EMOJI) {
+      for (const code of [entry.name, ...entry.aliases]) {
+        expect(code).toMatch(/^[a-z0-9_+-]+$/)
+      }
+    }
+  })
+
+  it('carries a real glyph on every row', () => {
+    for (const entry of THREAD_EMOJI) {
+      expect(entry.glyph.length).toBeGreaterThan(0)
+      expect([...entry.glyph].every((char) => char.codePointAt(0)! > 0x7f)).toBe(true)
+    }
+  })
+})
+
+/* ── D3 — the lookup ──────────────────────────────────────────────────────── */
+
+describe('D3 — resolving a shortcode', () => {
+  it('AC#3: `:side-eye:` resolves to the rolling-eyes glyph — the owner example', () => {
+    expect(emojiByShortcode('side-eye')?.glyph).toBe('\u{1F644}')
+    expect(emojiByShortcode(':side-eye:')?.glyph).toBe('\u{1F644}')
+  })
+
+  it('treats `-` and `_` as the same letter, so muscle memory works in any dialect', () => {
+    const rolling: EmojiEntry | undefined = emojiByShortcode('roll_eyes')
+    expect(rolling?.glyph).toBe('\u{1F644}')
+    expect(emojiByShortcode('side_eye')).toBe(rolling)
+    expect(emojiByShortcode('SIDE-EYE')).toBe(rolling)
+    expect(emojiByShortcode('face_with_rolling_eyes')).toBe(rolling)
+  })
+
+  it('resolves the shortcodes people reach for most', () => {
+    expect(emojiByShortcode('tada')?.glyph).toBe('\u{1F389}')
+    expect(emojiByShortcode('rocket')?.glyph).toBe('\u{1F680}')
+    expect(emojiByShortcode('thumbsup')?.glyph).toBe('\u{1F44D}')
+    expect(emojiByShortcode('+1')?.glyph).toBe('\u{1F44D}')
+    expect(emojiByShortcode('eyes')?.glyph).toBe('\u{1F440}')
+    expect(emojiByShortcode('heart')?.glyph).toBe('\u{2764}\u{FE0F}')
+  })
+
+  it('returns nothing for a shortcode the table does not hold', () => {
+    expect(emojiByShortcode('definitely_not_an_emoji')).toBeUndefined()
+    expect(emojiByShortcode('')).toBeUndefined()
+  })
+})
+
+/* ── D4 — the search ──────────────────────────────────────────────────────── */
+
+describe('D4 — prefix search over names, aliases and keywords', () => {
+  it('finds an entry by the prefix of its name', () => {
+    expect(searchEmoji('tad')[0]?.glyph).toBe('\u{1F389}')
+    expect(searchEmoji('roc')[0]?.glyph).toBe('\u{1F680}')
+  })
+
+  it("D3's worked example: `:party:` finds the party popper, whose name is `tada`", () => {
+    expect(searchEmoji('party')[0]?.name).toBe('tada')
+  })
+
+  it('finds an entry by an alias, in the dialect that spells it that way', () => {
+    expect(searchEmoji('thumbsup')[0]?.glyph).toBe('\u{1F44D}')
+    expect(searchEmoji('shipped')[0]?.glyph).toBe('\u{1F389}')
+  })
+
+  it('ranks an exact name above a longer name that merely starts the same way', () => {
+    const results = searchEmoji('star')
+    expect(results[0]?.name).toBe('star')
+  })
+
+  it('returns nothing for an empty query — a bare colon is punctuation', () => {
+    expect(searchEmoji('')).toEqual([])
+    expect(searchEmoji('   ')).toEqual([])
+  })
+
+  it('returns nothing for a query nothing matches', () => {
+    expect(searchEmoji('zzzznope')).toEqual([])
+  })
+
+  it('bounds the result list, so the popup has a known maximum height', () => {
+    // `s` is a prefix of a great many keywords; the cap is what stops the
+    // popup from becoming a page.
+    expect(searchEmoji('s').length).toBeLessThanOrEqual(EMOJI_RESULT_LIMIT)
+    expect(searchEmoji('s', 3)).toHaveLength(3)
+  })
+
+  it('is case-insensitive and tolerates the colons a person types around it', () => {
+    expect(searchEmoji('TAD')[0]?.glyph).toBe('\u{1F389}')
+    expect(searchEmoji(':tada:')[0]?.glyph).toBe('\u{1F389}')
+  })
+})
+
+/* ── AC#9 — the source files stay text ────────────────────────────────────── */
+
+/**
+ * Read a sibling source file. `.href` rather than the URL object itself
+ * because the global `URL` under jsdom is whatwg-url's, which Node's
+ * `fileURLToPath` does not always accept as one of its own.
+ */
+function sourceOf(relative: string): string {
+  return readFileSync(fileURLToPath(new URL(relative, import.meta.url).href), 'utf8')
+}
+
+describe('AC#9 — every glyph is an escape, never a raw byte', () => {
+  /**
+   * The only non-ASCII this codebase's TypeScript is allowed to carry, and it
+   * is all PROSE inside comments: the section rule, the three dashes, the
+   * ellipsis, the two arrows and the command key. No pictograph, no variation
+   * selector, nothing above the BMP. Adding to this list should feel like a
+   * decision; adding a raw emoji to it is the thing the list exists to stop.
+   */
+  const TYPOGRAPHY = new Set(
+    ['\u{00A7}', '\u{2013}', '\u{2014}', '\u{2019}', '\u{2026}', '\u{2192}', '\u{21B5}', '\u{2318}', '\u{2500}'].map(
+      (char) => char.codePointAt(0),
+    ),
+  )
+
+  const files = ['../emoji.ts', '../suggestion-list.tsx', './emoji.test.ts', './suggestion-list.test.tsx']
+
+  it.each(files)('%s holds no raw glyph', (relative) => {
+    const source = sourceOf(relative)
+    const offenders = [...source].filter((char) => {
+      const code = char.codePointAt(0) ?? 0
+      return code > 0x7f && !TYPOGRAPHY.has(code)
+    })
+    expect(offenders).toEqual([])
+  })
+
+  it('proves the point on the table itself: every glyph is absent from its own source', () => {
+    const source = sourceOf('../emoji.ts')
+    for (const entry of THREAD_EMOJI) {
+      expect(source.includes(entry.glyph)).toBe(false)
+      expect(source.includes(`'${entry.name}'`)).toBe(true)
+    }
+  })
+})