@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Markdown/modules/headingLinks.spec.md

@@ -1,262 +0,0 @@
----
-schema_version: 3
-template_version: 2
-kind: module
-id: module:Markdown/headingLinks
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-03
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility, layout]
-verified_by:
-  [
-    packages/core/src/Markdown/plugins/headingLinks.test.tsx,
-    packages/core/src/Markdown/plugins/headingLinks.ssr.test.tsx,
-    packages/core/src/Markdown/Markdown.public.test.ts,
-    packages/core/src/Markdown/plugins/headingLinks.a11y.chromium.spec.ts,
-    packages/core/src/Outline/parseOutlineFromMarkdown.test.ts,
-    apps/storybook/stories/MarkdownHeadingLinks.stories.tsx,
-  ]
-parent_component: component:Markdown
-references:
-  [
-    component:Markdown/DEC-2,
-    module:Outline/parseOutlineFromMarkdown,
-    spec:AST-002/DEC-8,
-    spec:AST-036/DEC-11,
-  ]
----
-
-# Markdown heading-links module contract
-
-## Contract at a glance
-
-| Area            | Contract                                                                                                                                                                                                                                |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `createMarkdownHeadingLinks(options?)` returns one first-party entry exported from `@astryxdesign/core/Markdown/plugins`.                                                                                                               |
-| Behavior        | Installing the entry gives every rendered h1–h6 a deterministic, collision-safe ID and gives each built-in heading an inline trailing `#` copy button.                                                                                  |
-| End-user impact | Readers can copy a durable heading URL with immediate confirmation without changing the current hash, scroll position, or page; incoming fragment URLs still target the heading ID.                                                     |
-| Builder impact  | Builders explicitly install one entry and may supply a stable heading namespace and safe URL base. The same entry keeps Markdown-derived Outline IDs aligned and root-only.                                                             |
-| Compatibility   | Additive and default-off. Without this module, released Markdown/Outline heading traversal, IDs, DOM, styling, and custom heading ownership remain unchanged.                                                                           |
-| Review checks   | Reject default-on behavior, a Markdown prop, an Outline-only namespace, runtime IDs, module-local entry state, unvalidated lookalikes, an anchor/fake link, bespoke reveal logic, imposed custom anatomy, or product-shaped navigation. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Builders who publish documents should be able to opt into portable, durable heading
-links without turning product identity or navigation policy into a permanent Markdown
-prop. The module owns one complete first-party composition: identity projection,
-permalink copy-button rendering, localization, and cross-surface evidence.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive and opt-in
-- Migration decision: `spec:AST-002/DEC-8`
-- Existing builders do nothing. A builder that wants all-depth heading identities
-  creates one stable entry and passes it to Markdown and any Outline derivation of the
-  same source.
-
-## Ownership boundary
-
-**Owns**
-
-- `createMarkdownHeadingLinks()` and `MarkdownHeadingLinksOptions`.
-- The stable internal plugin name and a frozen, versioned, structurally validated
-  configuration carried by the opaque entry across compatible Core package copies.
-- NFKC Unicode slugging, fallback, emitted-ID reservation, namespace composition,
-  and all-depth post-transform projection.
-- The shared IDs, labels, sanitized permalink bases, and canonical copy URLs consumed by
-  Markdown and Markdown-derived Outline.
-- The built-in sibling copy-button renderer, `useContainerReveal` composition, i18n,
-  interaction styles, Storybook example, SSR proof, and browser evidence.
-
-**Does not own / non-goals**
-
-- Markdown's generic plugin protocol, parser, transform order, default heading styles,
-  or released no-plugin root-heading projection.
-- Outline's root-only item selection, hook API, or memoization framework.
-- A caller's custom `components.heading` DOM, styling, accessibility, or permalink UI.
-- Product-specific document identity, versioning, host URL construction, viewer
-  scrolling, callbacks, or routing.
-
-## Public API and concepts
-
-| Concept                        | Closed values or states                            | Meaning                                                                                  | Default          | Owner                          | Stability |
-| ------------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------- | ------------------------------ | --------- |
-| `createMarkdownHeadingLinks()` | one factory returning `MarkdownPluginEntry<never>` | Installs a portable module entry recognized by compatible Core copies.                   | absent           | `module:Markdown/headingLinks` | stable    |
-| `headingIdPrefix`              | string or omitted                                  | Caller-owned stable namespace prepended as `<prefix>--<slug>`.                           | unprefixed       | caller                         | stable    |
-| `permalinkBaseUrl`             | safe navigation URL or omitted                     | Caller-owned base whose existing fragment is replaced by the generated fragment.         | current document | caller                         | stable    |
-| Heading projection             | absent or installed                                | Released root-only identity when absent; module-owned all-depth identity when installed. | absent           | module                         | stable    |
-| Built-in copy control          | honest sibling `type="button"`                     | Copies the canonical URL without navigation and shows a check for 1.5s.                  | absent           | module                         | stable    |
-| Custom heading renderer        | caller replacement                                 | Receives the generated ID only and keeps complete output ownership.                      | built-in         | caller                         | stable    |
-
-## Behavioral contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                      |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| FR1  | The factory and options type are exported only through the server-safe `@astryxdesign/core/Markdown/plugins` entry point. The ordinary opaque `MarkdownPluginEntry<never>` carries a frozen, versioned module configuration inside the shared structurally validated `Symbol.for` protocol envelope, so a compatible Core copy can recognize it without module-local identity or state.                                                                                                                                                           | `spec:AST-036` FR1–FR5, DEC-11             |
-| FR2  | `headingIdPrefix` and `permalinkBaseUrl` accept strings only and travel on the entry. The URL base uses Markdown's navigation sanitizer, rejects unsafe destinations, and replaces any existing fragment. Consumers recognize only the exact compatible module configuration. A valid generic same-name plugin with incompatible module data keeps ordinary plugin ordering but gains no heading-links behavior; malformed generic entries follow the existing Markdown/Outline fail-soft path. Direct invalid factory arguments may still throw. | `family:navigation-destinations`           |
-| FR3  | After transforms, every heading at every depth participates once in document order. Labels use the canonical extension text projection. Slugs use NFKC, lowercase Unicode letters/numbers, quote removal, collapsed hyphens, and `section`.                                                                                                                                                                                                                                                                                                       | `component:Markdown` FR13, FR16            |
-| FR4  | Every emitted ID is reserved. A natural numeric suffix can never collide with or re-emit an earlier generated ID.                                                                                                                                                                                                                                                                                                                                                                                                                                 | module identity ownership                  |
-| FR5  | Omitting the module preserves released root-heading IDs, nested-heading behavior, DOM, styles, Outline results, and custom-renderer ownership.                                                                                                                                                                                                                                                                                                                                                                                                    | `component:Markdown` FR12                  |
-| FR6  | Passing the same entry to Markdown and Markdown-derived Outline shares one projection. Nested headings consume identity and collisions, while Outline continues to select root headings only.                                                                                                                                                                                                                                                                                                                                                     | `module:Outline/parseOutlineFromMarkdown`  |
-| FR7  | A built-in heading remains one semantic h1–h6 and gains one honest sibling `type="button"`; a custom heading receives the generated ID and no imposed wrapper or control.                                                                                                                                                                                                                                                                                                                                                                         | `component:Markdown` FR2–FR3               |
-| FR8  | IDs are deterministic across synchronous SSR, hydration, multiple namespaced instances, reordering, and independent rendering.                                                                                                                                                                                                                                                                                                                                                                                                                    | module identity ownership                  |
-| FR9  | The public entry remains server-safe and tree-shakeable; the client renderer stays private to Markdown. Product identity, versioning, scrolling, callbacks, routing, and host URL construction never enter the module.                                                                                                                                                                                                                                                                                                                            | package export and side-effect conventions |
-| FR10 | Unmodified click, tap, Enter, or Space copies the canonical absolute URL without navigation, scroll, or hash mutation. Success shows the check and localized polite announcement for 1.5s; failure stays silent. The heading row uses canonical `useContainerReveal`, line-height-sized flow layout, stable logical-end spacing, non-overlapping 24px coarse hit geometry, and one keyboard-only focus ring.                                                                                                                                      | module interaction and layout ownership    |
-
-## Accessibility contract
-
-- **AR1 — heading semantics stay intact.** The built-in control is a sibling, so the
-  h1–h6 role/name excludes `#`; authored heading links remain valid. A custom heading
-  receives identity only.
-- **AR2 — custom ownership stays intact.** A custom heading receives identity only and
-  remains responsible for all anatomy, styling, and accessibility beyond the ID.
-- **AR3 — the renderer extension uses the canonical reveal primitive.** Its copy
-  button stays mounted, named, in the accessibility tree, and in tab order while
-  visually hidden at fine-pointer rest. Hovering anywhere in the heading row or moving
-  keyboard focus into it reveals the marker immediately. Coarse-pointer/touch
-  visibility, reduced motion, and focus safeguards follow `useContainerReveal`; the
-  module must not add a parallel media-query, marker, token, or public reveal API.
-
-## Copy-button reveal extension contract
-
-The renderer extension spreads
-`useContainerReveal().getContainerProps()` on the built-in heading row (the reveal
-owner) and `getContentRevealProps({isLayoutPreserved: true})` on its honest sibling
-`type="button"`. This produces the exact observable states: hidden at fine-pointer
-rest; visible when any part of the heading row is hovered; visible when the button or
-another row descendant owns focus; keyboard reachable without `display: none` or
-`visibility`; and visible on coarse/touch input under the hook's existing supported
-semantics. The in-flow control box has the computed block-size of its adjacent heading
-line, so it never raises the heading line-height or changes wrapping. One stable logical
-inline slot at the final visual line end keeps heading text, the control, and adjacent
-controls disjoint in either direction; reveal and the `#`/check swap change no row
-geometry or spacing. On coarse input, the interactive and focus geometry meets the
-24px AA target minimum, centered on that line-height box through overflow-visible
-internal geometry rather than block-size in flow. The extension remains unclipped and cannot overlap or
-steal input from heading text, neighboring controls, or preceding/following lines.
-Pointer activation does not paint a keyboard focus-visible ring; keyboard focus paints
-exactly one canonical, unclipped Astryx ring.
-
-Unmodified click, tap, Enter, or Space copies the canonical absolute permalink and
-never navigates, scrolls, or mutates the current hash. The heading ID remains the
-incoming fragment target. Success replaces `#` with Astryx's check icon for 1.5
-seconds and announces localized `Link copied` once through the canonical polite live
-region; failure stays silent and leaves `#` unchanged. Modified/non-primary pointer
-activation does not copy, and the button exposes no anchor, open-in-new-tab, or link
-context-menu semantics. Custom headings remain outside this renderer contract.
-
-## Design relationships
-
-| State              | Design requirement                                                                                    | Representation authority    | Module contract |
-| ------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------- | --------------- |
-| Built-in heading   | Preserve semantic h1–h6 content while adding the projected ID and sibling copy control.               | Current source and Markdown | FR5, FR7, FR10  |
-| Copy control       | Align `#`/check in the heading line box; reveal canonically and extend only to the 24px AA hit floor. | Button and module contract  | FR10            |
-| Custom heading     | Forward the projected ID without wrapping or adding sibling presentation.                             | Caller                      | FR7             |
-| No-plugin Markdown | Preserve released root-only identity and nested-heading behavior byte-for-byte.                       | Current source and Markdown | FR5             |
-
-The module adds no Markdown-local theme target. The button uses Button's existing target;
-the row is private layout.
-
-## Parent and system relationships
-
-- `component:Markdown` owns the generic plugin seam, transformed tree, built-in
-  heading part, default no-plugin projection, and custom-renderer replacement seam.
-- `module:Outline/parseOutlineFromMarkdown` owns root-only item selection and consumes
-  this module's projection only when the same entry is installed.
-- `spec:AST-036` owns the opaque plugin protocol; this first-party module uses it
-  without a privileged public capability.
-- `spec:AST-002/DEC-8` admits this factory instead of a broad Markdown prop because
-  installation, namespace, and URL base are caller decisions Astryx cannot derive.
-- `family:navigation-destinations` owns URL accept/block policy; this module owns
-  sanitizing the optional base and copying the canonical URL.
-
-## Implementation plan and boundaries
-
-1. Keep the server-safe factory and identity projection in
-   `plugins/headingLinks.ts`; carry normalized module configuration inside the shared
-   portable plugin envelope, and export only the factory and options type from
-   `plugins/index.ts`.
-2. Keep rendering and StyleX private under `plugins/`; Markdown's built-in heading path
-   invokes the renderer only when projection supplies a canonical URL. Default and
-   custom-renderer paths remain unchanged.
-3. Keep module tests, SSR proof, Storybook, and Playwright evidence with the module;
-   keep generic/no-plugin tests in Markdown and root selection in Outline.
-
-## Verification map
-
-| Contract   | Verification                                                                                              | Representative states                                                                                                              | Failure expectation                                                                                                                 |
-| ---------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR4    | module tests, public API test, typecheck, export/package checks                                           | public entry/options, duplicate copies, invalid entries/URLs, h1–h6, Unicode, suffix collisions                                    | Export drift, lost options, false recognition, unsafe URL, unstable slug, or duplicate ID fails.                                    |
-| FR5–FR7    | module tests plus Markdown and Outline integration tests                                                  | omitted/installed plugin, root/nested, honest sibling button, custom heading                                                       | Default changes, custom output is wrapped, the control fakes link semantics, or IDs diverge.                                        |
-| FR8–FR10   | SSR test, Storybook, and `plugins/headingLinks.a11y.chromium.spec.ts`                                     | hydration, copy/failure/timer, no location mutation, rest/hover/focus/touch, line-height rows, 24px target, RTL/zoom/forced colors | Hydration recovers, feedback lies/shifts, layout grows, targets overlap, pointer paints a keyboard ring, or reveal semantics drift. |
-| Repository | formatting, ESLint, knowledge/sync, i18n, Changeset validation, core typecheck, focused tests, pre-commit | module files, locale catalogs, Markdown/Outline seams, docs/specs, Storybook, workflow                                             | Stale authority, untranslated drift, duplicate ownership, type/lint failure, or unrelated diff blocks.                              |
-
-## Decision log
-
-### DEC-1 — Ship one first-party plugin factory
-
-**Reference:** `module:Markdown/headingLinks/DEC-1`
-**Decider:** `cixzhang`, `2026-10-03`
-
-One factory preserves the opaque plugin list while exposing only installation, an optional
-stable namespace, and an optional safe URL base. Its configuration rides the existing
-portable, versioned plugin envelope rather than a creating module's WeakMap or object
-identity, so duplicate compatible Core copies agree. A broad Markdown prop or separate
-Outline option would make one composition into permanent parallel API and could drift
-across surfaces.
-
-Compatible duplicate copies consume the exact envelope. A valid generic same-name plugin
-with absent or incompatible module data stays an ordinary plugin in the caller's declared
-order, but never gains this module's ID projection. A malformed generic envelope follows
-the existing consumer fail-soft path, so Markdown and Outline preserve released behavior
-instead of throwing during render. Invalid direct factory arguments remain programmer
-errors.
-
-Rejected: module-local option state; elevating same-name lookalikes into this module;
-render-time crashes for package-version skew; default-on behavior; a Markdown boolean or
-namespace prop; a separate Outline identity option; product-specific factory options.
-
-### DEC-2 — Own one all-depth identity projection
-
-**Reference:** `module:Markdown/headingLinks/DEC-2`
-**Decider:** `cixzhang`, `2026-10-03`
-
-Every transformed heading participates depth-first so rendered targets and root
-Outline entries share one collision sequence. NFKC Unicode slugging and emitted-ID
-reservation produce durable readable fragments. Caller namespace is stable data;
-runtime tree position and `useId` are not.
-
-Rejected: root-only plugin allocation; separate Markdown/Outline sluggers; ASCII-only
-slugs; collision counting that can re-emit a natural numeric suffix; runtime IDs.
-
-### DEC-3 — The renderer extension is an honest revealed copy button
-
-**Reference:** `module:Markdown/headingLinks/DEC-3`
-**Decider:** `cixzhang`, `2026-10-03`
-
-The renderer extension uses an inline trailing `#` sibling with baseline/logical
-spacing, secondary color, and inherited typography. Its primary action is copy, so it is
-a real button rather than an anchor that suppresses navigation. `useContainerReveal`
-owns fine-pointer rest, heading-row hover, focus-within, coarse/touch, and motion
-semantics. Its in-flow box matches the heading line-height, with stable logical-end space
-and non-overlapping 24px coarse hit geometry; pointer activation paints no keyboard ring.
-The heading ID remains the incoming fragment target.
-
-Rejected: native fragment navigation; a copy-plus-navigation anchor hybrid; bespoke
-reveal media logic; product routing; a new public reveal API.
-
-## Content boundary
-
-The module reads only transformed heading nodes and caller-supplied configuration carried
-by the validated plugin entry for the current document invocation. It does not persist
-document content, labels, destinations, options, or generated IDs in module-local state.
-
-## Open questions
-
-None.

package/src/Markdown/modules/remark.spec.md

@@ -1,269 +0,0 @@
----
-schema_version: 3
-template_version: 2
-kind: module
-id: module:Markdown/remark
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-15
-owners: [cixzhang]
-review_triggers: [public-api, behavior]
-verified_by: [packages/core/src/Markdown/remark.test.tsx]
-parent_component: component:Markdown
-references: [architecture:public-component-api, spec:AST-036/DEC-3]
----
-
-# remark module contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `createMarkdownRemarkTransform(plugin, ...settings)` in the separate `@astryxdesign/core/Markdown/remark` entry point returns one Markdown transform for `createMarkdownPlugin()`. It accepts a conventional Unified/Remark plugin type as well as an Astryx-authored one.                                                                               |
-| Behavior                | Each invocation runs one synchronous transform-only Remark plugin over a fresh mutable copy of the canonical tree with an isolated constrained file, then accepts a lossless round trip or rejects it.                                                                                                                                                   |
-| End-user impact         | Readers see either the plugin's supported transformation or the last valid readable document; unsupported behavior can never silently drop, approximate, or forge document content.                                                                                                                                                                      |
-| Builder impact          | Builders who import nothing are unaffected. An opt-in builder imports the adapter, proves one plugin compatible with fixtures, and reads one diagnostic when a plugin leaves the profile.                                                                                                                                                                |
-| Compatibility/readiness | Additive and opt-in; absent from Markdown's entry point and from parser-only or server bundles unless imported. Compatibility is per plugin evidence, never package identity.                                                                                                                                                                            |
-| Review checks           | Reject silent approximation, dropped fields, restored or rebuilt provenance, authored or shifted positions, edited Astryx owned nodes, raw-markup channels, async or processor-state plugins, plugin-authored diagnostic text, a refusal a plugin can catch and continue past, an unhandled rejection, or adapter imports inside Markdown or the parser. |
-| Governing rules         | [`spec:AST-036` FR18–FR20, FR24](../../../../../docs/specs/AST-036/spec.md); [`component:Markdown` FR12–FR16](../Markdown.spec.md); [`architecture:public-component-api`](../../../../../docs/architecture/public-component-api.md).                                                                                                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Teams with existing Remark transforms should be able to reuse a compatible one
-inside Astryx Markdown without adopting Unified as a Core runtime, mutating the
-canonical tree, or weakening Core-owned semantics. This module owns that narrow
-compatibility boundary: what the profile accepts, what it refuses, and how a
-refusal stays readable.
-
-Everything outside the profile fails closed. "Remark-compatible" is a claim a
-plugin earns from fixtures in this module's tests, never from a package name.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive, opt-in, separately imported; no released
-  Markdown, parser, Outline, or bundle behavior changes when the adapter is not
-  imported
-- Migration decision: `spec:AST-036/DEC-3`
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The adapter's public factory, its mutable Remark tree types, and its
-  constrained file type.
-- The supported-subset round trip and the exact rejection conditions below.
-- The isolated per-invocation copy, file data, and diagnostics.
-- Its own evidence that one real plugin is compatible.
-
-**Does not own / non-goals**
-
-- Plugin admission, transform ordering, validation, and failure recovery —
-  owned by `component:Markdown` and `spec:AST-036`.
-- Unified processors, parser or compiler registration, micromark extensions,
-  async pipelines, and `VFile` behavior beyond the constrained file.
-- Heading identity, navigation, resource policy, list, table, and document
-  semantics — owned by Core.
-
-## Public API and concepts
-
-| Concept                         | Closed values or states                                            | Meaning                                                                                                                                                                                                               | Default        | Owner                    | Stability |
-| ------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------ | --------- |
-| `createMarkdownRemarkTransform` | `(plugin, ...settings) => MarkdownTransform`                       | Adapts one attacher-shaped Remark plugin; the attacher runs once, its transformer per run.                                                                                                                            | none           | `module:Markdown/remark` | stable    |
-| Adapted tree                    | supported MDAST subset plus Astryx flow image, citation, extension | A fresh mutable copy the plugin may mutate or replace.                                                                                                                                                                | fresh per run  | `module:Markdown/remark` | stable    |
-| Constrained file                | `value`, `data`, `messages`, `message()`, `fail()`, `toString()`   | Readonly source, per-run JSON-like data, and diagnostics.                                                                                                                                                             | empty `data`   | `module:Markdown/remark` | stable    |
-| Accepted plugin type            | `MarkdownRemarkPlugin` or `MarkdownRemarkCompatiblePlugin`         | A new plugin may be authored against typed Astryx trees; a conventional Unified/Remark plugin type is accepted structurally, including a declared async or callback-style transformer that the run time then rejects. | structural     | `module:Markdown/remark` | stable    |
-| Rejection                       | one diagnostic plus the last valid document                        | The fail-closed result for anything outside the profile.                                                                                                                                                              | not applicable | `module:Markdown/remark` | stable    |
-
-## Behavioral contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                           |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1  | The adapter accepts only a plugin whose attacher synchronously returns one transformer of at most two parameters. A parser, compiler, async, callback-style, or registration-only plugin is rejected.                                                                                                                                                                                                                                                                                                                                                                   | `spec:AST-036` FR18             |
-| FR2  | Every invocation receives a fresh mutable copy of the canonical tree and a new constrained file. No canonical node, array, data value, or position is mutable, and no state survives between runs.                                                                                                                                                                                                                                                                                                                                                                      | `spec:AST-036` FR10, FR18       |
-| FR3  | The constrained file exposes exactly `value`, `data`, `messages`, `message()`, `fail()`, and `toString()`. Every other key — `path`, `cwd`, `history`, or any other — fails closed on read, write, define, and delete, rather than answering `undefined`; `in` and key enumeration answer truthfully so a plugin can feature-detect. Processor access fails closed the same way.                                                                                                                                                                                        | `spec:AST-036` FR18             |
-| FR4  | A returned or mutated tree is accepted only when every node and metadata field round-trips losslessly through the supported subset, fenced-code `meta` included; otherwise the last valid document is preserved.                                                                                                                                                                                                                                                                                                                                                        | `spec:AST-036` FR19             |
-| FR5  | A surviving source-backed node keeps Core's provenance exactly: every line, column, and offset on both points must come back unchanged. A rebuilt, retyped, duplicated, or shifted surviving node is rejected, never silently restored. Source-backed nodes, including headings, may be removed or reordered; a surviving source heading keeps its depth.                                                                                                                                                                                                               | `spec:AST-036` FR11, FR19, FR26 |
-| FR6  | Astryx-owned citation and plugin extension nodes pass through only when every owned field — including `data` and authored `source` — is exactly equal. Authoring or editing one through the adapter is rejected.                                                                                                                                                                                                                                                                                                                                                        | `spec:AST-036` FR11, FR15       |
-| FR7  | A failed run reports exactly one diagnostic, assembled only from the adapter's own vocabulary and read from adapter-owned state, never from the thrown value or any object the plugin can rewrite. Text a plugin authored — a thrown error, a `fail()` reason, a `message()` diagnostic — never becomes a diagnostic, because the plugin read the document and may quote it. Any refusal the plugin catches and continues past still fails the run, and the first recorded reason is the one reported. Later plugins and rendering continue on the last valid document. | `spec:AST-036` FR12             |
-| FR8  | An unchanged document returns the identical canonical root, so an adapted no-op costs no tree allocation and no downstream invalidation.                                                                                                                                                                                                                                                                                                                                                                                                                                | `spec:AST-036` FR13, FR21       |
-| FR9  | The adapter is a separate entry point that Markdown, the parser, and the plugin protocol never import, so parser-only and server bundles exclude it unless a caller imports it. It is registered in the exports generator, so the published subpath cannot drift from the source.                                                                                                                                                                                                                                                                                       | `spec:AST-036` FR24             |
-| FR10 | A conventional Unified/Remark plugin type-checks at the callsite without being rewritten, including a transformer that declares Unified's callback parameter or an asynchronous return union. The run time still rejects an actual promise and a callback-style transformer.                                                                                                                                                                                                                                                                                            | `spec:AST-036` FR18             |
-| FR11 | A promise the adapter refuses — from the attacher or the transformer — gets a rejection handler attached before any other verdict is applied, so a result that is both refused for another reason and rejected cannot surface as an unhandled rejection. That matters most on the server, where an unhandled rejection ends the process by default and would print a plugin-authored reason drawn from the document. `then` is read exactly once, because reading it can itself throw or trip a guard.                                                                  | `spec:AST-036` FR12, FR18       |
-| FR12 | Sticky refusal is re-checked immediately before validated output becomes observable, so a guard that fires late — inside a hostile `then` accessor, or a getter read while the result is validated — still rejects rather than letting the plugin's output through.                                                                                                                                                                                                                                                                                                     | `spec:AST-036` FR12             |
-
-### Supported round trip
-
-| Input                                                         | Round trip                                                                                                                                                      |
-| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `root`, `paragraph`, `heading`, `blockquote`, `thematicBreak` | Structure and children; heading depth stays Core-owned.                                                                                                         |
-| `text`, `strong`, `emphasis`, `delete`, `inlineCode`, `break` | Values and ordered phrasing children.                                                                                                                           |
-| `link`, `image`                                               | `url` revalidated by the navigation and resource owners; `alt` required; `title` null.                                                                          |
-| `list`, `listItem`                                            | `ordered`, `start`, `spread`, Astryx `delimiter`, and `checked`.                                                                                                |
-| `code`                                                        | `lang` and `meta`, each `null` when absent, plus `value`. The authored info string survives both conversions and the released language projection is preserved. |
-| `math`, `inlineMath`                                          | Present only when the caller enabled math.                                                                                                                      |
-| `table`, `tableRow`, `tableCell`                              | Normalized `align` and cell children.                                                                                                                           |
-| Astryx flow image, `citation`, `extension`                    | Preserved as owned nodes; readable by the plugin, not writable.                                                                                                 |
-| `position`, `data`                                            | Core-authored positions and finite JSON-like data.                                                                                                              |
-
-### Rejection matrix
-
-| Rejected input                                                                                                                                              | Result                                                            |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Async, callback-style, registration-only, or processor-state plugin                                                                                         | Last valid document plus one diagnostic; FR1, FR3                 |
-| `html` or any node outside the supported subset (definitions, references, footnotes, frontmatter, directives, MDX)                                          | Last valid document plus one diagnostic; FR4                      |
-| An unsupported field, `hName`, `hProperties`, `hChildren`, or non-JSON node or file data                                                                    | Last valid document plus one diagnostic; FR3, FR4                 |
-| Non-string fence `meta`, a link or image `title`, a loose list item, or a ragged transformed table                                                          | Last valid document plus one diagnostic; FR4                      |
-| Reading, writing, defining, or deleting an unsupported file key — `path`, `cwd`, `history`, or any other                                                    | Last valid document plus one diagnostic; FR3                      |
-| An authored, shifted, or removed position on a surviving source-backed node; a rebuilt, retyped, or duplicated source node; or a re-levelled source heading | Last valid document plus one diagnostic; FR5                      |
-| A shifted line or column on an otherwise unchanged offset                                                                                                   | Last valid document plus one diagnostic; FR5                      |
-| Provenance rebuilt from a copied position, or smuggled in from another document                                                                             | Last valid document plus one diagnostic; FR5                      |
-| An authored or edited Astryx citation or extension node, `data` and `source` included                                                                       | Last valid document plus one diagnostic; FR6                      |
-| A rejected link or image URL, invalid built-in structure, a nested link, or block output from an inline entry point                                         | Last valid document plus one diagnostic; FR4                      |
-| A transformer that throws, or any refusal the plugin caught and continued past, `fail()` included                                                           | Last valid document plus one diagnostic; FR7                      |
-| A rejected promise from the attacher or transformer, alone or on top of a caught refusal                                                                    | Last valid document, one diagnostic, no unhandled rejection; FR11 |
-| A guard that fires late, inside a `then` accessor or a getter read during validation                                                                        | Last valid document plus one diagnostic; FR12                     |
-
-### Transformation and precedence order
-
-- **ORD1 — one run.** Canonical tree → fresh mutable copy → the plugin's single
-  synchronous transformer → validated round trip → the document later plugins
-  and rendering observe. Core validates the result again; the adapter never
-  substitutes for Core's own validation.
-- **ORD2 — one diagnostic, adapter-authored.** A successful run is silent;
-  Core's only diagnostic channel reports plugin failure, so there is nothing
-  truthful to say. A failed run reports exactly one line, built from this
-  module's own vocabulary. Messages a plugin recorded stay on its file, which
-  only the plugin sees.
-- **ORD3 — defuse, then judge, then accept.** A returned value is inspected
-  and defused before any verdict is applied, so the reason a run is refused
-  never decides whether a promise is left dangling. Sticky refusal is checked
-  again immediately before output is accepted, because a guard can fire at any
-  point the adapter touches plugin-controlled values.
-
-### Performance and resources
-
-- **PR1 — one copy per invocation.** Work is proportional to document size once
-  per run; an unchanged document returns the canonical root itself.
-- **PR2 — no runtime dependency.** The adapter adds no Unified, Remark, mdast,
-  or `VFile` dependency and no parse work; it runs inside the existing transform
-  phase and cannot trigger reparsing.
-
-## Accessibility contract
-
-- **AR1 — required meaning survives.** An image must keep its text alternative
-  and a source heading its level, so a rejection is preferred over an
-  accessible-name or document-outline regression.
-- **AR2 — no markup channel.** Raw HTML and hast property channels are rejected,
-  so an adapted plugin cannot inject unlabeled or non-semantic output.
-
-## Design relationships
-
-No visual representation is owned by this compatibility adapter; adapted output
-renders through Markdown's existing parts.
-
-## Parent and system relationships
-
-- `component:Markdown` owns aggregate plugin application, validation, fallback,
-  and heading identity.
-- `spec:AST-036` owns the protocol, the canonical MDAST compatibility matrix,
-  and the limited Remark profile this record implements.
-- `family:navigation-destinations` keeps ownership of every adapted link
-  destination and image resource.
-
-## Verification map
-
-| Contract | Verification                                                                                              | Representative states                                                                                                                                                      | Mutation or failure expectation                                                                                           |
-| -------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3  | `remark.test.tsx` attachment, isolation, and constrained-file fixtures                                    | async, callback-style, processor-state, registration-only plugins; repeated invocations; every unsupported file key, read and written; caught guard refusals               | Accepting one of them, leaking file data between runs, or letting a caught refusal clear the verdict fails the fixtures.  |
-| FR4–FR6  | `remark.test.tsx` round-trip and rejection matrix, including a parsed-fence identity fixture              | every supported node kind; fences with and without an info string; each rejected input above; owned citation and extension nodes                                           | A silently dropped field — `meta` included — an accepted unsupported node, or an edited owned node fails closed fixtures. |
-| FR7      | `remark.test.tsx` diagnostics plus Markdown rendering after a rejection                                   | thrown transformer, swallowed `fail()`, forged rejection built from the adapter's own class, rewritten `message`, hand-marked fatal message, later plugin in the same list | A missing, duplicated, or plugin-authored diagnostic, a swallowed failure that succeeds, or a lost sibling plugin, fails. |
-| FR8      | `remark.test.tsx` identity fixture over the full supported document                                       | untouched document with positions, math, citations, and extension nodes                                                                                                    | Returning a copy instead of the canonical root fails identity.                                                            |
-| FR9      | `remark.test.tsx` import and manifest fixtures; `sync:exports:check`                                      | Markdown, parser, and plugin modules; the published entry point                                                                                                            | An adapter import inside Core's Markdown path, or an unregistered subpath, fails.                                         |
-| FR10     | `remark.test.tsx` compile fixture over Unified-shaped declarations                                        | attacher bound to a processor; callback-parameter and async-union transformer; inline Astryx plugin                                                                        | Narrowing the accepted type so a conventional plugin stops compiling fails the fixture.                                   |
-| FR11     | `remark.test.tsx` rejection fixtures observing `process` unhandled rejections, including server rendering | rejected attacher result; rejected transformer result; a rejected result on top of a caught guard or a caught `fail()`; a thenable whose `then` throws                     | Applying a verdict before defusing, or refusing without attaching a handler, fails the fixtures.                          |
-| FR12     | `remark.test.tsx` late-guard fixtures                                                                     | a hostile `then` accessor; a getter that trips a guard while the result is validated                                                                                       | Dropping the final sticky re-check lets caught-guard output through and fails the fixtures.                               |
-
-## Decision log
-
-### DEC-1 — Lossless round trip or a readable rejection
-
-**Reference:** `module:Markdown/remark/DEC-1`
-**Decider:** `cixzhang`, `2026-09-15`
-
-The adapter never approximates. Link titles, loose list items, raw markup,
-unsupported nodes, and metadata Astryx cannot represent — including a
-non-string fence `meta` — have no Astryx meaning, so accepting them would
-silently change or drop what a reader sees. An authored fence info string does
-have a meaning here and round-trips intact; it is rejected only when it is not
-a string. Refusing the rest keeps the last valid document readable and makes
-the gap visible to the builder in one diagnostic instead of to the reader as
-missing content.
-
-### DEC-2 — Provenance is carried, never inferred
-
-**Reference:** `module:Markdown/remark/DEC-2`
-**Decider:** `cixzhang`, `2026-09-15`
-
-A transformed node belongs to a source node only when it carries the marker the
-adapter put on the copy; matching on a position that merely looks right would
-let a rebuilt node inherit provenance it never had. Equality is exact across
-every line, column, and offset, because restoring Core's position over a
-changed one is the silent approximation this profile exists to refuse.
-
-### DEC-3 — Only the adapter speaks in diagnostics
-
-**Reference:** `module:Markdown/remark/DEC-3`
-**Decider:** `cixzhang`, `2026-09-15`
-
-A plugin's own text reached it from the document and may quote any of it, so
-forwarding it would turn a developer warning into a place private content
-leaks. The single reported line is assembled from this module's vocabulary
-instead; a plugin's messages remain on the file it was given.
-
-Everything the plugin can reach, it can also rewrite: `message` is writable on
-any Error, and catching one rejection hands it the rejection class itself. So
-the reported reason is read from adapter-owned state keyed by the thrown
-object, and every refusal — a prohibited file key, a processor access, the
-plugin's own `fail()` — is recorded in adapter-owned run state rather than on
-anything the plugin holds. A refusal the plugin catches and continues past
-still fails the run, and the first reason recorded is the one reported.
-
-### DEC-4 — Owned nodes stay Core's
-
-**Reference:** `module:Markdown/remark/DEC-4`
-**Decider:** `cixzhang`, `2026-09-15`
-
-An adapted plugin may read an Astryx citation or extension node but cannot mint
-or edit one, and cannot change a source heading. Owned nodes are how Markdown,
-Outline, and fallback agree on one document; a compatibility shim is the wrong
-place to let them drift.
-
-### DEC-5 — Accept the plugin types Remark already has
-
-**Reference:** `module:Markdown/remark/DEC-5`
-**Decider:** `cixzhang`, `2026-09-15`
-
-The whole point of the profile is reusing an existing plugin, so a plugin typed
-against Unified must compile here unchanged — Unified declares one transformer
-type carrying both the callback parameter and an async return, and refusing it
-at the type level would refuse every real plugin. The adapter accepts that
-shape structurally and rejects the unsupported behavior at run time, where it
-can fail closed with a readable document. Authors writing a new plugin against
-Astryx annotate it with `MarkdownRemarkPlugin` and keep a fully typed tree.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This record does not duplicate consumer signatures or examples, the canonical
-plugin protocol, Markdown's aggregate application and fallback rules, the AST
-compatibility matrix, or Remark's own documentation. It links to their owners.