@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/Link/__tests__/Link.a11y.states.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** AST-021 state inventory for the Link binding of the shared Link contract. */
+
+import type {LinkStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface LinkA11yState {
+  readonly id:
+    | 'text-native'
+    | 'icon-labelled'
+    | 'current-page'
+    | 'external-new-tab'
+    | 'provider-router'
+    | 'as-router';
+  readonly summary: string;
+  readonly facts: LinkStateFacts;
+  readonly storyId: string;
+}
+
+export type LinkA11yRow = (typeof LINK_A11Y_STATES)[number];
+
+const story = (id: string) => `a11y-link-pattern--${id}`;
+
+/**
+ * Every destination is a same-document fragment, so following a link keeps the
+ * story mounted. The router component records its own navigations; the browser
+ * records native ones.
+ */
+export const LINK_A11Y_DESTINATION = '#link-destination';
+
+export const LINK_A11Y_STATES = [
+  {
+    id: 'text-native',
+    summary: 'a native anchor named by its visible text',
+    facts: {name: 'Documentation', current: null},
+    storyId: story('text-native'),
+  },
+  {
+    id: 'icon-labelled',
+    summary: 'an icon-only link named by its label prop',
+    facts: {name: 'Close dialog', current: null},
+    storyId: story('icon-labelled'),
+  },
+  {
+    id: 'current-page',
+    summary: 'a link the caller marks as the current page',
+    facts: {name: 'Overview', current: 'page'},
+    storyId: story('current-page'),
+  },
+  {
+    id: 'external-new-tab',
+    summary:
+      'an external link whose name carries the new-tab notice and which opens a new tab',
+    facts: {name: 'GitHub (opens in new tab)', current: null},
+    storyId: story('external-new-tab'),
+  },
+  {
+    id: 'provider-router',
+    summary:
+      'a link rendered by a router component supplied through LinkProvider',
+    facts: {name: 'Projects', current: null},
+    storyId: story('provider-router'),
+  },
+  {
+    id: 'as-router',
+    summary: 'a link rendered by a router component supplied through `as`',
+    facts: {name: 'Settings', current: null},
+    storyId: story('as-router'),
+  },
+] as const satisfies ReadonlyArray<LinkA11yState>;
+
+export const LINK_A11Y_EXCLUSIONS = [
+  {
+    owner: 'Link component tests and family:navigation-destinations FR7',
+    reason:
+      'A disabled Link renders an href-less anchor that is neither a link nor focusable. That disabled semantics is member-owned, so disabled states are not bound to this available-link contract.',
+  },
+  {
+    owner: 'Link component tests (button rendering)',
+    reason:
+      'A Link without href renders a button for an action; the button contract, not this one, owns that role.',
+  },
+  {
+    owner: 'family:navigation-destinations and its verification map',
+    reason:
+      'Which destinations are accepted or blocked, and how rejected destinations render, is navigation safety rather than an accessibility outcome.',
+  },
+  {
+    owner:
+      'BreadcrumbItem, SideNavItem, TopNavItem, Citation, and ClickableCard',
+    reason:
+      'Links inside navigation aggregates and enlarged surfaces bind separately; this first binding covers the Link component and both custom-router seams.',
+  },
+  {
+    owner: 'Link visual and Tooltip evidence',
+    reason:
+      'Underline, hover color, focus ring paint, truncation, and tooltip presentation require rendered and component checks.',
+  },
+  {
+    owner: 'AST-009',
+    reason:
+      'This binding claims DOM, accessibility-tree, and real-browser behavior, not spoken wording, virtual-cursor, or assistive-technology activation.',
+  },
+] as const;

package/src/Link/__tests__/Link.a11y.test.tsx

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Fast DOM binding for Link against the shared Link contract. */
+
+import {cleanup, render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  LINK_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {LINK_A11Y_RENDERS} from './Link.a11y.renders';
+import {
+  LINK_A11Y_EXCLUSIONS,
+  LINK_A11Y_STATES,
+  type LinkA11yRow,
+} from './Link.a11y.states';
+
+const SUBJECT_SELECTOR = '[data-a11y-link]';
+
+function subjectFor(): HTMLElement {
+  const subjects = document.querySelectorAll(SUBJECT_SELECTOR);
+  if (subjects.length !== 1 || !(subjects[0] instanceof HTMLElement)) {
+    throw new Error(
+      `binding rendered ${subjects.length} link subjects instead of one`,
+    );
+  }
+  return subjects[0];
+}
+
+async function checkState(state: LinkA11yRow): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: LINK_PATTERN,
+    binding: 'Link',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(LINK_A11Y_RENDERS[state.id]());
+      return createJsdomHarness({subject: subjectFor()});
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('the shared Link pattern, jsdom lane', () => {
+  it.each(
+    LINK_A11Y_STATES.map(
+      state => [`Link [${state.id}]`, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: LINK_PATTERN,
+      binding: 'Link',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(LINK_A11Y_RENDERS[state.id]());
+      },
+      subject: subjectFor,
+      cleanup,
+    });
+  });
+
+  it('runs DOM expectations and reports tree and browser outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of LINK_A11Y_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(LINK_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect([...report.unrunLayers].sort()).toEqual([
+      'accessibility-tree',
+      'real-browser',
+    ]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('the Link binding inventory', () => {
+  it('names a distinct checked-in story for every state', () => {
+    const ids = LINK_A11Y_STATES.map(state => state.storyId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('records every adjacent exclusion with an owner and reason', () => {
+    expect(LINK_A11Y_EXCLUSIONS.every(row => row.owner && row.reason)).toBe(
+      true,
+    );
+  });
+
+  it('renders an anchor with a destination for every state', () => {
+    for (const state of LINK_A11Y_STATES) {
+      render(LINK_A11Y_RENDERS[state.id]());
+      const subject = subjectFor();
+      expect(subject.tagName, state.id).toBe('A');
+      expect(subject.getAttribute('href'), state.id).not.toBeNull();
+      cleanup();
+    }
+  });
+
+  it('renders both custom-router seams through the router component', () => {
+    for (const id of ['provider-router', 'as-router'] as const) {
+      render(LINK_A11Y_RENDERS[id]());
+      expect(subjectFor().hasAttribute('data-a11y-link-router'), id).toBe(true);
+      cleanup();
+    }
+    for (const state of LINK_A11Y_STATES.filter(
+      row => row.id !== 'provider-router' && row.id !== 'as-router',
+    )) {
+      render(LINK_A11Y_RENDERS[state.id]());
+      expect(subjectFor().hasAttribute('data-a11y-link-router'), state.id).toBe(
+        false,
+      );
+      cleanup();
+    }
+  });
+
+  it('opens the external state in a new tab', () => {
+    render(LINK_A11Y_RENDERS['external-new-tab']());
+    expect(subjectFor().getAttribute('target')).toBe('_blank');
+    cleanup();
+  });
+});

package/src/Markdown/Markdown.doc.mjs

@@ -29,7 +29,7 @@ const anatomy = [
     name: 'Code block',
     required: false,
     description:
-      'Fenced code block; a custom code renderer replaces the default part.',
+      'Fenced code block; long lines wrap rather than scroll sideways. A custom code renderer replaces the default part.',
   },
   {
     name: 'Blockquote',

package/src/Markdown/Markdown.fr23.perf.test.ts

@@ -19,8 +19,10 @@
  * The timed region inside each process is the spec's protocol, unsmoothed:
  * ten untimed warmups, then one median of nine alternating paired rounds,
  * for a stable plugin list and a recreated equivalent one, against the
- * omitted baseline. One over-budget A/B triggers two fresh-process attempts;
- * the unchanged budget fails only when at least two of the three exceed it.
+ * omitted baseline. A first attempt within budget on both paths certifies
+ * them. Otherwise up to nine fresh-process attempts decide each path on its
+ * own: a path fails the unchanged budget when a majority of the nine (five)
+ * exceed it, and collection stops as soon as both paths are decided.
  */
 
 import {execFileSync} from 'node:child_process';
@@ -166,18 +168,64 @@ function logBenchmarkResult(result: BenchmarkResult, attempt: number): void {
   );
 }
 
+/** The two paths FR23 measures; each is held to the budget on its own. */
+const FR23_PATHS = ['stable', 'recreated'] as const;
+type FR23Path = (typeof FR23_PATHS)[number];
+
+/**
+ * Fresh-process attempts that decide a path after a noisy first one. On CI a
+ * clean representative set measures about 1.19 at 500 sections with about
+ * ±0.04 of sample noise, so a single attempt lands over the budget roughly
+ * one time in ten; a majority of nine does so well under one time in a
+ * thousand, while a slowdown of 0.1 or more still exceeds it nearly always.
+ */
+const FR23_ATTEMPTS = 9;
+const FR23_MAJORITY = Math.floor(FR23_ATTEMPTS / 2) + 1;
+
+function attemptsOverBudget(
+  attempts: ReadonlyArray<BenchmarkResult>,
+  fr23Path: FR23Path,
+): number {
+  return attempts.filter(result => result[fr23Path] > FR23_BUDGET).length;
+}
+
+/** Whether the remaining attempts can no longer change this path's verdict. */
+function pathDecided(
+  attempts: ReadonlyArray<BenchmarkResult>,
+  fr23Path: FR23Path,
+): boolean {
+  const over = attemptsOverBudget(attempts, fr23Path);
+  return over >= FR23_MAJORITY || attempts.length - over >= FR23_MAJORITY;
+}
+
 function collectFR23Attempts(
   sections: number,
   runAttempt: (sections: number) => BenchmarkResult = runSettledBenchmark,
 ): ReadonlyArray<BenchmarkResult> {
   const attempts = [runAttempt(sections)];
-  if (exceedsFR23Budget(attempts[0])) {
-    attempts.push(runAttempt(sections));
+  if (!exceedsFR23Budget(attempts[0])) {
+    return attempts;
+  }
+  while (
+    attempts.length < FR23_ATTEMPTS &&
+    !FR23_PATHS.every(fr23Path => pathDecided(attempts, fr23Path))
+  ) {
     attempts.push(runAttempt(sections));
   }
   return attempts;
 }
 
+/** The paths whose attempts exceed the budget in a majority of nine. */
+function pathsOverBudget(
+  attempts: ReadonlyArray<BenchmarkResult>,
+): ReadonlyArray<FR23Path> {
+  return FR23_PATHS.filter(fr23Path =>
+    attempts.length > 1
+      ? attemptsOverBudget(attempts, fr23Path) >= FR23_MAJORITY
+      : attemptsOverBudget(attempts, fr23Path) > 0,
+  );
+}
+
 describe('Markdown FR23 helper overhead', () => {
   it('reports one nine-pair median without selecting the cheapest baseline', () => {
     // Paired ratios: four 1.1s, one 1.2, four 10s. The median is 1.2,
@@ -218,35 +266,104 @@ describe('Markdown FR23 helper overhead', () => {
     }
   });
 
-  it('retries one over-budget A/B twice and uses the three-attempt majority', () => {
+  describe('deciding each path from fresh-process attempts', () => {
     const result = (stable: number, recreated: number): BenchmarkResult => ({
-      sections: 200,
+      sections: 500,
       stable,
       recreated,
       control: 1,
     });
-    const passFirst = [result(1.2, 1.22)];
-    expect(collectFR23Attempts(200, () => passFirst.shift()!)).toHaveLength(1);
-
-    const retryResults = [
-      result(1.27, 1.1),
-      result(1.2, 1.22),
-      result(1.18, 1.19),
-    ];
-    const attempts = collectFR23Attempts(200, () => retryResults.shift()!);
-    expect(attempts).toHaveLength(3);
-    expect(attempts.filter(exceedsFR23Budget)).toHaveLength(1);
-
-    const majorityResults = [
-      result(1.27, 1.1),
-      result(1.2, 1.26),
-      result(1.18, 1.19),
-    ];
-    expect(
-      collectFR23Attempts(200, () => majorityResults.shift()!).filter(
-        exceedsFR23Budget,
-      ),
-    ).toHaveLength(2);
+    const run = (results: BenchmarkResult[]) => {
+      const queue = [...results];
+      let calls = 0;
+      const attempts = collectFR23Attempts(500, () => {
+        calls++;
+        const next = queue.shift();
+        if (next == null) {
+          throw new Error('asked for an unplanned attempt');
+        }
+        return next;
+      });
+      return {attempts, calls, failing: pathsOverBudget(attempts)};
+    };
+
+    it('certifies both paths from one attempt within budget', () => {
+      const {calls, failing} = run([result(1.2, 1.22)]);
+      expect(calls).toBe(1);
+      expect(failing).toEqual([]);
+    });
+
+    it('fails a single attempt over budget only if no retry ran', () => {
+      expect(pathsOverBudget([result(1.26, 1.2)])).toEqual(['stable']);
+    });
+
+    it('judges each path by its own majority, not either path per attempt', () => {
+      // Main run 38393555595: stable was over in attempt 1 and recreated in
+      // attempt 2, which the old either-path-per-attempt count read as a
+      // two-of-three failure although neither path was over in a majority.
+      const {attempts, failing} = run([
+        result(1.256, 1.201),
+        result(1.145, 1.275),
+        result(1.183, 1.187),
+        result(1.18, 1.2),
+        result(1.19, 1.21),
+        result(1.2, 1.22),
+        result(1.17, 1.19),
+      ]);
+      // Each path needs five attempts within budget; each had one over.
+      expect(attempts).toHaveLength(6);
+      expect(failing).toEqual([]);
+    });
+
+    it('stops as soon as both paths are decided', () => {
+      // Recreated is decided after five passes, stable after one more.
+      const {calls} = run([
+        result(1.3, 1.2),
+        result(1.2, 1.2),
+        result(1.2, 1.2),
+        result(1.2, 1.2),
+        result(1.2, 1.2),
+        result(1.2, 1.2),
+      ]);
+      expect(calls).toBe(6);
+    });
+
+    it('fails a path that is over budget in a majority of nine', () => {
+      const {attempts, failing} = run([
+        result(1.3, 1.2),
+        result(1.27, 1.2),
+        result(1.2, 1.2),
+        result(1.26, 1.21),
+        result(1.22, 1.2),
+        result(1.28, 1.19),
+        result(1.26, 1.2),
+      ]);
+      expect(attempts).toHaveLength(7);
+      expect(failing).toEqual(['stable']);
+    });
+
+    it('fails a consistent slowdown on both paths after five attempts', () => {
+      const {calls, failing} = run(
+        Array.from({length: 9}, () => result(1.4, 1.42)),
+      );
+      expect(calls).toBe(5);
+      expect(failing).toEqual(['stable', 'recreated']);
+    });
+
+    it('never runs more than nine attempts', () => {
+      const {calls} = run([
+        result(1.3, 1.3),
+        result(1.2, 1.2),
+        result(1.3, 1.3),
+        result(1.2, 1.2),
+        result(1.3, 1.3),
+        result(1.2, 1.2),
+        result(1.3, 1.3),
+        result(1.2, 1.2),
+        result(1.3, 1.3),
+      ]);
+      expect(calls).toBe(9);
+    });
   });
 
   it.each([200, 500])(
@@ -257,28 +374,32 @@ describe('Markdown FR23 helper overhead', () => {
       // attempt counts: a value over budget is machine noise, so that process
       // is replaced before its A/B result can certify or fail the helpers.
       //
-      // A single over-budget A/B is also noisy at this threshold. Retry that
-      // result twice in fresh processes and fail only when a majority (at
-      // least two of the three independent attempts) exceeds the unchanged
-      // 1.25 budget.
+      // A single over-budget A/B is also noisy at this threshold. Each path
+      // is then decided by a majority of up to nine fresh-process attempts
+      // against the unchanged 1.25 budget.
       const attempts = collectFR23Attempts(sections);
-      if (attempts.length === 3) {
+      if (attempts.length > 1) {
         console.log(
           `  ${sections} sections: first A/B exceeded ${FR23_BUDGET};` +
-            ' retried twice in fresh processes',
+            ` decided each path from ${attempts.length} fresh processes`,
         );
       }
       attempts.forEach((result, index) =>
         logBenchmarkResult(result, index + 1),
       );
-      const overBudget = attempts.filter(exceedsFR23Budget).length;
+      const failing = pathsOverBudget(attempts);
       expect(
-        overBudget,
-        `${overBudget} of ${attempts.length} fresh FR23 attempts exceeded ` +
-          `the ${FR23_BUDGET} budget`,
-      ).toBeLessThan(2);
+        failing,
+        failing
+          .map(
+            fr23Path =>
+              `${fr23Path}: ${attemptsOverBudget(attempts, fr23Path)} of ` +
+              `${attempts.length} fresh FR23 attempts exceeded the ${FR23_BUDGET} budget`,
+          )
+          .join('; '),
+      ).toEqual([]);
     },
-    300_000,
+    600_000,
   );
 
   it('fails loudly when the benchmark process cannot produce a result', () => {

package/src/Markdown/Markdown.spec.md

@@ -50,6 +50,7 @@ system_specs:
     spec:AST-036/DEC-4,
     spec:AST-061/DEC-5,
     spec:AST-061/DEC-6,
+    spec:AST-061/DEC-9,
     spec:AST-064/DEC-6,
     spec:AST-036/DEC-12,
   ]
@@ -64,18 +65,37 @@ constrained renderer seams. Callers may opt into the canonical plugin protocol f
 bounded source syntax, immutable document transformation, typed extension
 rendering, and native typed document-start frontmatter. They may separately opt into dollar-delimited math by supplying one typed
 renderer for both inline and display expressions. The parser accepts matching
-explicit options. Existing parsing, rendering, styling, and streaming behavior
-remain unchanged when plugins and math are absent.
+explicit options. Plugins and math change nothing when absent; the default Code
+block path renders `diff` and `diff-<language>` fences as CodeBlock's diff layer
+(FR29) and wraps every fence's long lines (`spec:AST-061` FR5, DEC-9), and every
+other parsing, rendering, styling, and streaming behavior is the released one.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive, opt-in public API; existing parser nodes, DOM,
-  styling, targets, dollar-delimited text, `components`, and `inlinePlugins` remain
-  unchanged unless the caller supplies `plugins`, supplies `components.math`, or
-  passes the matching explicit parser option.
+- Released default preserved: `yes`, except the default Code block path for `diff` fences (FR29, below) and its long-line wrap (below)
+- Compatibility class: additive, opt-in public API, with two visible
+  default-path rendering changes (the FR29 diff layer and the fenced-code wrap,
+  below); existing parser nodes, DOM, styling, targets,
+  dollar-delimited text, `components`, and `inlinePlugins` remain unchanged unless
+  the caller supplies `plugins`, supplies `components.math`, or passes the matching
+  explicit parser option.
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
+- Default-path rendering change for diff fences (FR29), a visible default change
+  and not a breaking one: a `diff` fence that rendered as plain text renders as CodeBlock's diff
+  layer over plaintext with a `diff` label, and a `diff-<language>` fence —
+  which rendered as plain text with a `diff` label and viewport name, its
+  leading word being all Markdown read — as the layer over that language with
+  a `<language> diff` label; the header, copy, disclosure, and viewport name
+  stay, and a supplied `code` renderer's contract is unchanged. The way back to
+  plain text is a `text` fence or a custom `code` renderer. Every other fence
+  is unchanged apart from the wrap below.
+- Default-path wrap change (`spec:AST-061` FR5, DEC-9), visual and not breaking:
+  the default Code block wraps long lines instead of scrolling them sideways, so
+  a fence whose lines no longer overflow also no longer takes the conditional
+  scroll-region tab stop. Text, line numbers, syntax colours, copy output, and a
+  supplied `code` renderer's contract are unchanged. The way back to sideways
+  scrolling is a custom `code` renderer.
 - Default-path layout change (FR26–FR28): a default table's columns may become
   wider than the released fixed buckets, never narrower; header labels wrap
   instead of truncating; a table that squashed its columns may now scroll.
@@ -228,6 +248,7 @@ unions. Enabled calls return the explicit `InlineNodeWithMath` and
 | FR26 | On the default table path each column has a content-derived width floor: the larger of its own longest unbreakable token and a readable minimum derived from that column's content, bounded so a table of short columns still fits its container. The floor applies to the cell's text, not to its padded box, so it means the same amount of content at every density. A header label contributes its own readable minimum to that comparison. A table whose floors exceed the container grows and scrolls rather than dividing the container equally. |
 | FR27 | Default table header cells never truncate: no ellipsis and no width clamp. A header reads in full, on one line up to a bounded width and wrapping past it. Inline code inside a default table cell keeps its token whole rather than breaking mid-token; a supplied `inlineCode` renderer owns its own wrapping.                                                                                                                                                                                                                                        |
 | FR28 | Markdown's Table block owns spacing, sizing, and alignment. The nested Table's own Scroll region remains the sole owner of the table's horizontal overflow, its accessible name, and its conditional keyboard focusability; Markdown adds no second scroll container, name, or tab stop of its own.                                                                                                                                                                                                                                                     |
+| FR29 | On the default Code block path the fence's full first word selects CodeBlock's diff layer (`component:CodeBlock` FR9): `diff` renders the layer over plaintext, `diff-<language>` the layer over `<language>` (the language read by the same leading-word rule as any other fence); every other fence takes no diff layer. A supplied `code` renderer's contract is unchanged: it keeps receiving the leading word characters as `language` — `diff` for both `diff` and `diff-<language>` fences — and nothing new.                                    |
 
 FR23 includes CommonMark-compatible lazy paragraph continuation inside blockquotes
 and ordered, unordered, or task-list items. Omitting a repeated quote marker or
@@ -421,22 +442,23 @@ and this change preserves the existing spelling exactly.
 
 ## Verification map
 
-| Contract               | Verification                                                                      | Representative states                                                                                                                                | Failure signal                                                                                                                                                                                             |
-| ---------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR5                | `Markdown.test.tsx`, theme-target tests, and `scripts/check-knowledge.mjs`        | Default block/inline output and all current targets                                                                                                  | Existing DOM, target, spacing, or renderer behavior changes.                                                                                                                                               |
-| FR6–FR10               | `parser.test.ts` and `Markdown.test.tsx`                                          | Opt-out, inline/display math, escapes, currency, code, links, plugins                                                                                | A delimiter is claimed without opt-in, TeX is formatted as Markdown, or opaque contexts leak.                                                                                                              |
-| FR11                   | `incremental.test.ts` and `Markdown.test.tsx`                                     | Every-character top-level/list/task-list/blockquote splits, CRLF, source ranges                                                                      | Streaming diverges from a full parse, shows partial syntax, mistakes a nested closer for an opener, or crosses a closed container.                                                                         |
-| FR12–FR16              | plugin, transform, adapter, performance, and Outline parser tests                 | omitted/empty lists, immutable transforms, invalid outputs, live updates, one compatible Remark plugin, duplicate headings                           | Empty behavior forks, input mutates, invalid structure escapes, transforms reparse, adapter loses content, budgets fail, or heading targets diverge.                                                       |
-| FR17–FR18              | container parse/validation, ownership, and dependency tests                       | leaf/container declarations, nested containers, foreign read/remove/mint/edit, unmet/misordered dependencies                                         | Plugin-built parsed children, invalid content, lost fallback children, foreign mint/edit, or generic ownership codes.                                                                                      |
-| FR19                   | diagnostic-channel tests in development and production                            | every phase, advisory reports, rate suppression, no handler, malformed list, duplicate Core, version skew                                            | A silent production failure, document content in a diagnostic, or one entrypoint throwing where another recovers.                                                                                          |
-| FR20–FR22              | canonical/server imports, inference, streaming, preparation, theming tests        | server imports, no explicit type args, chunk boundaries, recreated lists, themed/unthemed extensions                                                 | Client references, explicit-type workarounds, oscillation, per-render re-preparation, or unreachable opted-in output.                                                                                      |
-| FR23                   | parser, incremental, renderer, nesting, and public option tests                   | mixed lists; escaped prose/code table cells, nested inline code, full/streaming parity; autolink omitted/enabled                                     | A mixed list splits or loses state, an escaped table pipe changes cells or exposes its backslash, or autolink changes other syntax.                                                                        |
-| FR24                   | `plugins/frontmatter.test.tsx`, Storybook, and server rendering                   | complete, malformed, non-leading, LF/CRLF, unfinished streaming, full plugin stack                                                                   | Metadata syntax renders after completion, unfinished syntax leaks while streaming, typing is lost, or later plugins stop composing.                                                                        |
-| FR25                   | `parser.public.test.ts`, plugin SSR tests, and package export checks              | server/RSC parsing with plugins, synchronous SSR, suspending renderer streaming boundary                                                             | A server import gains `use client`, plugin execution needs serialization, SSR loses fallback, or direct RSC rendering is misrepresented as supported.                                                      |
-| FR26–FR28              | `Markdown.test.tsx` and a real-browser layer over checked-in narrow-width stories | short, prose, and token-heavy tables; header-only rows and empty cells; long headers over short bodies; reading columns from phone to document width | A column collapses below its content floor, cell padding eats the floor, a header truncates, an inline-code token breaks mid-token, or a second scroll viewport, name, or tab stop appears around a table. |
-| Public syntax/types    | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs`                 | Legacy exhaustive switches, math opt-ins, inferred extension-node unions                                                                             | A released union widens, an enabled union loses nodes, or docs drift from declarations.                                                                                                                    |
-| Navigation contract    | `parser.test.ts`, `Markdown.test.tsx`, and `Markdown.renderBoundary.test.tsx`     | Parsed and rendered links, including transformed built-in links; accepted ordinary schemes; rejected destinations; links versus images               | A blocked destination reaches navigation or a custom link renderer, or resource policy narrows accepted navigation.                                                                                        |
-| Security/accessibility | `parser.test.ts`, `Markdown.test.tsx`, and renderer guidance                      | Inert expression strings and renderer-owned semantics                                                                                                | Astryx executes math as HTML or silently claims renderer-owned accessibility.                                                                                                                              |
+| Contract               | Verification                                                                                                                                                                                                  | Representative states                                                                                                                                | Failure signal                                                                                                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR5                | `Markdown.test.tsx`, theme-target tests, and `scripts/check-knowledge.mjs`                                                                                                                                    | Default block/inline output and all current targets                                                                                                  | Existing DOM, target, spacing, or renderer behavior changes.                                                                                                                                               |
+| FR6–FR10               | `parser.test.ts` and `Markdown.test.tsx`                                                                                                                                                                      | Opt-out, inline/display math, escapes, currency, code, links, plugins                                                                                | A delimiter is claimed without opt-in, TeX is formatted as Markdown, or opaque contexts leak.                                                                                                              |
+| FR11                   | `incremental.test.ts` and `Markdown.test.tsx`                                                                                                                                                                 | Every-character top-level/list/task-list/blockquote splits, CRLF, source ranges                                                                      | Streaming diverges from a full parse, shows partial syntax, mistakes a nested closer for an opener, or crosses a closed container.                                                                         |
+| FR12–FR16              | plugin, transform, adapter, performance, and Outline parser tests                                                                                                                                             | omitted/empty lists, immutable transforms, invalid outputs, live updates, one compatible Remark plugin, duplicate headings                           | Empty behavior forks, input mutates, invalid structure escapes, transforms reparse, adapter loses content, budgets fail, or heading targets diverge.                                                       |
+| FR17–FR18              | container parse/validation, ownership, and dependency tests                                                                                                                                                   | leaf/container declarations, nested containers, foreign read/remove/mint/edit, unmet/misordered dependencies                                         | Plugin-built parsed children, invalid content, lost fallback children, foreign mint/edit, or generic ownership codes.                                                                                      |
+| FR19                   | diagnostic-channel tests in development and production                                                                                                                                                        | every phase, advisory reports, rate suppression, no handler, malformed list, duplicate Core, version skew                                            | A silent production failure, document content in a diagnostic, or one entrypoint throwing where another recovers.                                                                                          |
+| FR20–FR22              | canonical/server imports, inference, streaming, preparation, theming tests                                                                                                                                    | server imports, no explicit type args, chunk boundaries, recreated lists, themed/unthemed extensions                                                 | Client references, explicit-type workarounds, oscillation, per-render re-preparation, or unreachable opted-in output.                                                                                      |
+| FR23                   | parser, incremental, renderer, nesting, and public option tests                                                                                                                                               | mixed lists; escaped prose/code table cells, nested inline code, full/streaming parity; autolink omitted/enabled                                     | A mixed list splits or loses state, an escaped table pipe changes cells or exposes its backslash, or autolink changes other syntax.                                                                        |
+| FR24                   | `plugins/frontmatter.test.tsx`, Storybook, and server rendering                                                                                                                                               | complete, malformed, non-leading, LF/CRLF, unfinished streaming, full plugin stack                                                                   | Metadata syntax renders after completion, unfinished syntax leaks while streaming, typing is lost, or later plugins stop composing.                                                                        |
+| FR25                   | `parser.public.test.ts`, plugin SSR tests, and package export checks                                                                                                                                          | server/RSC parsing with plugins, synchronous SSR, suspending renderer streaming boundary                                                             | A server import gains `use client`, plugin execution needs serialization, SSR loses fallback, or direct RSC rendering is misrepresented as supported.                                                      |
+| FR26–FR28              | `Markdown.test.tsx` and a real-browser layer over checked-in narrow-width stories                                                                                                                             | short, prose, and token-heavy tables; header-only rows and empty cells; long headers over short bodies; reading columns from phone to document width | A column collapses below its content floor, cell padding eats the floor, a header truncates, an inline-code token breaks mid-token, or a second scroll viewport, name, or tab stop appears around a table. |
+| FR29                   | `Markdown.test.tsx` (a `diff` fence → plaintext + layer, a `diff-tsx` fence → tsx + layer, a plain fence unchanged, a custom `code` renderer receives `language="diff"` for both diff fences and nothing new) | default path and custom renderer, `diff` and `diff-<language>` fences                                                                                | a fence word other than `diff`/`diff-<language>` reaching the layer, or a custom renderer receiving a new prop or a different `language`                                                                   |
+| Public syntax/types    | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs`                                                                                                                                             | Legacy exhaustive switches, math opt-ins, inferred extension-node unions                                                                             | A released union widens, an enabled union loses nodes, or docs drift from declarations.                                                                                                                    |
+| Navigation contract    | `parser.test.ts`, `Markdown.test.tsx`, and `Markdown.renderBoundary.test.tsx`                                                                                                                                 | Parsed and rendered links, including transformed built-in links; accepted ordinary schemes; rejected destinations; links versus images               | A blocked destination reaches navigation or a custom link renderer, or resource policy narrows accepted navigation.                                                                                        |
+| Security/accessibility | `parser.test.ts`, `Markdown.test.tsx`, and renderer guidance                                                                                                                                                  | Inert expression strings and renderer-owned semantics                                                                                                | Astryx executes math as HTML or silently claims renderer-owned accessibility.                                                                                                                              |
 
 Focused tests continue to pin all nine current target names and default block
 placement. Math intentionally adds no target and no default anatomy.