@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/Markdown/url.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file url.ts
+ * @input Untrusted Markdown link or image destination
+ * @output Parser-compatible acceptance and normalized render-safe destinations
+ * @position Shared URL policy for parser, transforms, and renderer
+ */
+
+import {isSafeUrl, sanitizeUrl} from '../utils/safeUrl';
+
+const RENDER_DANGEROUS_URL_PATTERN = /^(?:javascript:|data:|vbscript:)/i;
+
+function normalizeMarkdownUrl(url: string): string {
+  // Browsers ignore embedded controls in schemes, so normalize before checking.
+  // eslint-disable-next-line no-control-regex -- control chars are the bypass
+  return url.replace(/[\x00-\x1f\x7f]/g, '').trim();
+}
+
+/** Preserve the released parser policy for no-plugin output compatibility. */
+export function isSafeMarkdownParserUrl(url: string): boolean {
+  return isSafeUrl(url);
+}
+
+/** Navigation and image rendering deliberately have different policies. */
+export function sanitizeMarkdownLinkUrl(url: string): string | null {
+  const normalized = sanitizeUrl(url);
+  return normalized === '' ? null : normalized;
+}
+
+export function sanitizeMarkdownUrl(url: string): string | null {
+  const normalized = normalizeMarkdownUrl(url);
+  return normalized !== '' && !RENDER_DANGEROUS_URL_PATTERN.test(normalized)
+    ? normalized
+    : null;
+}

package/src/Markdown/utils.ts

@@ -2,10 +2,20 @@
 
 /**
  * @file utils.ts
- * @output Server-safe re-exports of pure Markdown parser functions
+ * @output Server-safe exports for Markdown parsing and AST traversal
  * @position Subpath entry point: `@astryxdesign/core/Markdown/utils`
  */
 
+export {visitMarkdownNodes} from './ast';
+export type {
+  MarkdownAstExtensionNode,
+  MarkdownAstPhrasingContent,
+  MarkdownAstBlockContent,
+  MarkdownAstRoot,
+  MarkdownAstNodeMap,
+  MarkdownAstNode,
+} from './ast';
+
 export {
   parseMarkdown,
   parseInline,
@@ -26,5 +36,7 @@ export type {
   TableAlignment,
   ParseOptions,
   MathParseOptions,
+  IncrementalParseOptions,
+  IncrementalMathParseOptions,
   IncrementalState,
 } from './parser';

package/src/MetadataList/MetadataList.test.tsx

@@ -148,7 +148,9 @@ describe('MetadataList', () => {
         </MetadataList>,
       );
 
-      expect(gridTemplateOf(container)).toContain('repeat(3, auto 1fr)');
+      expect(gridTemplateOf(container)).toContain(
+        'repeat(3, auto minmax(0, 1fr))',
+      );
     });
 
     it('leaves the grid to the static rule for columns="multi"', () => {
@@ -178,7 +180,7 @@ describe('MetadataList', () => {
         </MetadataList>,
       );
 
-      expect(gridTemplateOf(container)).toContain('120px 1fr');
+      expect(gridTemplateOf(container)).toContain('120px minmax(0, 1fr)');
     });
   });
 });

package/src/MetadataList/MetadataList.tsx

@@ -113,7 +113,7 @@ const styles = stylex.create({
   // Vertical orientation — grid layout for label-value pairs
   gridSingle: {
     display: 'grid',
-    gridTemplateColumns: 'auto 1fr',
+    gridTemplateColumns: 'auto minmax(0, 1fr)',
     gap: `${spacingVars['--spacing-2']} ${spacingVars['--spacing-4']}`,
     alignItems: 'baseline',
   },
@@ -263,7 +263,7 @@ export function MetadataList({
     if (typeof columns === 'number' && columns > 1) {
       return isStacked
         ? `repeat(${columns}, 1fr)`
-        : `repeat(${columns}, auto 1fr)`;
+        : `repeat(${columns}, auto minmax(0, 1fr))`;
     }
     // A custom label width only applies to the label track of side labels.
     if (!isStacked && labelConfig.width != null) {
@@ -271,7 +271,7 @@ export function MetadataList({
         typeof labelConfig.width === 'number'
           ? `${labelConfig.width}px`
           : labelConfig.width;
-      return `${width} 1fr`;
+      return `${width} minmax(0, 1fr)`;
     }
     return null;
   };

package/src/MultiSelector/MultiSelector.test.tsx

@@ -478,39 +478,6 @@ describe('MultiSelector', () => {
     expect(trigger).toHaveAttribute('aria-required', 'true');
   });
 
-  it('renders listbox with aria-multiselectable', async () => {
-    const user = userEvent.setup();
-    render(
-      <MultiSelector
-        label="Fruit"
-        options={defaultOptions}
-        value={[]}
-        onChange={() => {}}
-      />,
-    );
-
-    await user.click(screen.getByRole('combobox'));
-    const listbox = screen.getByRole('listbox', h);
-    expect(listbox).toHaveAttribute('aria-multiselectable', 'true');
-  });
-
-  it('marks selected options with aria-selected', async () => {
-    const user = userEvent.setup();
-    render(
-      <MultiSelector
-        label="Fruit"
-        options={defaultOptions}
-        value={['Apple']}
-        onChange={() => {}}
-      />,
-    );
-
-    await user.click(screen.getByRole('combobox'));
-    const options = screen.getAllByRole('option', h);
-    expect(options[0]).toHaveAttribute('aria-selected', 'true');
-    expect(options[1]).toHaveAttribute('aria-selected', 'false');
-  });
-
   it('shows error status with aria-invalid', () => {
     render(
       <MultiSelector
@@ -1393,8 +1360,7 @@ describe('MultiSelector', () => {
     await user.click(screen.getByRole('combobox'));
     const options = screen.getAllByRole('option', h);
     expect(options).toHaveLength(3);
-    const group = screen.getByRole('group', h);
-    expect(group).toHaveAttribute('aria-label', 'Citrus');
+    expect(screen.getByText('Citrus')).toBeInTheDocument();
   });
 
   it('shows loading state with a spinner and aria-busy', () => {

package/src/MultiSelector/__tests__/MultiSelector.listbox.a11y.test.tsx

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MultiSelector.listbox.a11y.test.tsx
+ * @input Uses MultiSelector, its part/state inventory, and the shared Listbox contract
+ * @output DOM evidence for real multi-select listbox, group, and option parts
+ * @position Component-facing binding; API, form, composition, and styling stay local.
+ */
+
+import {cleanup, render, screen, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {describe, expect, it} from 'vitest';
+import {
+  expectAccessibilitySpec,
+  LISTBOX_PATTERN,
+} from '@astryxdesign/a11y-spec';
+import {MultiSelector} from '../MultiSelector';
+import {
+  LISTBOX_SCENARIOS,
+  listboxParts,
+} from '../../Selector/__tests__/Listbox.a11y.states';
+import {installListboxDialogStubs} from '../../Selector/__tests__/Listbox.a11y.dom';
+
+installListboxDialogStubs();
+
+const scenarios = LISTBOX_SCENARIOS.filter(
+  scenario => scenario.component === 'MultiSelector',
+);
+
+describe('MultiSelector Listbox semantic binding', () => {
+  it.each(scenarios)('$id', async scenario => {
+    for (const part of listboxParts(scenario)) {
+      await expectAccessibilitySpec({
+        spec: LISTBOX_PATTERN,
+        binding: `MultiSelector.${part.role}`,
+        state: part.state,
+        facts: part.facts,
+        render: async () => {
+          render(
+            <div dir={scenario.direction ?? 'ltr'}>
+              <MultiSelector
+                label="Fruit"
+                options={scenario.options}
+                value={scenario.values}
+                onChange={() => {}}
+                hasSearch={scenario.hasSearch}
+                hasSelectAll={scenario.hasSelectAll}
+                presentation={scenario.presentation}
+                isLoading={scenario.isLoading}
+                isLabelHidden={scenario.hiddenLabel}
+                renderOption={
+                  scenario.customContent
+                    ? option => <span>{option.label} details</span>
+                    : undefined
+                }
+                isDefaultOpen
+              />
+            </div>,
+          );
+          await screen.findByRole('listbox', {hidden: true});
+          if (scenario.query != null) {
+            await userEvent
+              .setup()
+              .type(
+                screen.getByRole('combobox', {hidden: true}),
+                scenario.query,
+              );
+          }
+        },
+        subject: () =>
+          part.role === 'listbox'
+            ? screen.getByRole('listbox', {hidden: true})
+            : part.role === 'group'
+              ? within(
+                  screen.getByRole('listbox', {hidden: true}),
+                ).getAllByRole('group', {hidden: true})[
+                  scenario.groups.indexOf(part.name ?? '')
+                ]
+              : within(screen.getByRole('listbox', {hidden: true})).getByRole(
+                  'option',
+                  {name: part.name, hidden: true},
+                ),
+        related: () => {
+          const listbox = screen.getByRole('listbox', {hidden: true});
+          expect(
+            within(listbox).getAllByRole('option', {hidden: true}),
+          ).toHaveLength(scenario.expectedOptions.length);
+          return {
+            listbox,
+            ...Object.fromEntries(
+              scenario.expectedOptions.map(option => [
+                `option:${option.value}`,
+                within(listbox).getByRole('option', {
+                  name: option.name,
+                  hidden: true,
+                }),
+              ]),
+            ),
+            ...Object.fromEntries(
+              scenario.groups.map((name, index) => [
+                `group:${name}`,
+                within(listbox).getAllByRole('group', {hidden: true})[index],
+              ]),
+            ),
+          };
+        },
+        cleanup,
+      });
+    }
+  });
+
+  it('keeps the bounded state matrix and select-all states explicit', () => {
+    expect(scenarios.map(scenario => scenario.id)).toEqual([
+      'multiple-unset',
+      'multiple-selected',
+      'multiple-disabled-selected',
+      'multiple-grouped',
+      'multiple-filtered',
+      'multiple-custom-rtl',
+      'multiple-sheet',
+      'multiple-sheet-search',
+      'multiple-loading',
+      'multiple-select-all-none',
+      'multiple-select-all-partial',
+      'multiple-select-all-all',
+    ]);
+  });
+});

package/src/NumberInput/NumberInput.tsx

@@ -105,9 +105,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/Outline/Outline.doc.mjs

@@ -196,11 +196,13 @@ function ControlledOutline() {
           code: `
 import {Outline, useOutlineFromMarkdown} from '@astryxdesign/core/Outline';
 
-function MarkdownOutline({markdown}) {
-  // Derives {id, label, level} items from headings in the source.
-  // The Markdown component renders the same generated ids on its
-  // headings, so outline links scroll without any extra wiring.
-  const items = useOutlineFromMarkdown(markdown);
+function MarkdownOutline({markdown, plugins, isStreaming}) {
+  // Pass the same plugins and finality to Markdown and Outline so transformed
+  // headings share labels and ids while content streams.
+  const items = useOutlineFromMarkdown(markdown, {
+    plugins,
+    isFinal: !isStreaming,
+  });
   return <Outline items={items} />;
 }
 `,

package/src/Outline/Outline.spec.md

@@ -12,7 +12,7 @@ owners: [cixzhang]
 review_triggers: [theming]
 verified_by:
   [packages/core/src/Outline/Outline.test.tsx, scripts/check-knowledge.mjs]
-modules: []
+modules: [module:Outline/parseOutlineFromMarkdown]
 families: []
 design_specs: []
 architecture: [architecture:component-theming-surface]

package/src/Outline/index.ts

@@ -15,5 +15,6 @@ export {Outline} from './Outline';
 export type {OutlineProps} from './Outline';
 export type {OutlineItem} from './types';
 export {parseOutlineFromMarkdown} from './parseOutlineFromMarkdown';
+export type {ParseOutlineFromMarkdownOptions} from './parseOutlineFromMarkdown';
 export {useOutlineFromMarkdown} from './useOutlineFromMarkdown';
 export {useOutlineFromDOM} from './useOutlineFromDOM';

package/src/Outline/modules/parseOutlineFromMarkdown.spec.md

@@ -0,0 +1,142 @@
+---
+schema_version: 3
+template_version: 1
+kind: module
+id: module:Outline/parseOutlineFromMarkdown
+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/Outline/parseOutlineFromMarkdown.test.ts]
+parent_component: component:Outline
+references:
+  [architecture:public-component-api, component:Markdown, spec:AST-036]
+---
+
+# parseOutlineFromMarkdown module contract
+
+## Intent
+
+`parseOutlineFromMarkdown` and `useOutlineFromMarkdown` derive same-document
+heading navigation from the same Markdown parse configuration, ordered immutable
+transforms, text projection, and collision allocator used by the rendered document.
+This focused module owns that utility behavior without deciding the draft Outline
+component's anatomy or theming.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive parser options; calls without plugins preserve
+  released labels, levels, IDs, and return types
+- Migration decision: `spec:AST-036`
+
+## Ownership boundary
+
+**Owns**
+
+- Deriving ordered `OutlineItem` values from Markdown headings.
+- Accepting the same parser-affecting options and ordered plugin list as Markdown.
+- Applying the same validated immutable transforms before selecting headings.
+- Using the same extension text projection and collision-safe slug allocation as
+  Markdown heading rendering.
+
+**Does not own / non-goals**
+
+- Outline component structure, active state, targets, layout, or theming.
+- Plugin rendering, block-extension navigation entries, or renderer-derived text.
+- A second parser, plugin registry, or independent heading-ID policy.
+
+## Public API and concepts
+
+`parseOutlineFromMarkdown(source, options?)` performs direct derivation.
+`useOutlineFromMarkdown(source, options?)` memoizes the same derivation for React
+callers. `options.plugins` uses the canonical opaque Markdown plugin entries. The
+same ordered transforms run before heading selection; inline extension-node `toText`
+projections then contribute to heading labels and IDs.
+
+## Behavioral contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                             | Basis                           | Acceptance and implementation state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------- |
+| FR1 | Both utilities accept the same Markdown parser options and ordered plugin list as the rendered Markdown document.                                                                                                                                                                                                                                                                     | `spec:AST-036` FR13, FR16       | pending implementation              |
+| FR2 | Both utilities apply the same validated immutable transforms before selecting headings, without allowing renderer output to affect identity.                                                                                                                                                                                                                                          | `spec:AST-036` FR13, FR16       | pending implementation              |
+| FR3 | Plugin-enabled labels and IDs use the same extension `toText` projection, slugger, and cross-base collision allocator as Markdown, producing unique matching targets.                                                                                                                                                                                                                 | `spec:AST-036` FR16             | pending implementation              |
+| FR4 | An extension node never creates an Outline entry of its own, and extension containers do not change heading traversal: entries come from the same blocks Markdown assigns heading IDs to, so a heading nested in a container is omitted exactly as one nested in a blockquote or list item is. A container never restarts, extends, or re-scopes heading identity or slug allocation. | `spec:AST-036` FR16, FR25       | pending implementation              |
+| FR5 | Omitting plugins and passing an empty list preserve released heading selection, labels, levels, IDs, return type, and memoization behavior.                                                                                                                                                                                                                                           | `spec:AST-036` FR2              | pending implementation              |
+| FR6 | The hook memoizes against source and every parse-affecting or transform-affecting option so changed configuration cannot return stale headings.                                                                                                                                                                                                                                       | `component:Markdown` FR15–FR16  | pending implementation              |
+| FR7 | A transform that removes a heading removes its Outline entry, and a transform that inserts a synthetic heading adds one, in both surfaces identically. Source-backed heading depth cannot change, so an entry's level always matches the rendered heading.                                                                                                                            | `spec:AST-036` FR26             | pending implementation              |
+| FR8 | When a plugin fails, derivation uses the same last valid root the rendered document uses, so labels, levels, and IDs still agree. Failures are reported through the shared diagnostic channel; this module adds no failure mode, fallback, or throw of its own.                                                                                                                       | `spec:AST-036` FR12, FR29       | pending implementation              |
+| FR9 | Derivation runs on the canonical tree through the shared parse path and requires no DOM, renderer, client boundary, or second parser. Because transforms are idempotent under streaming, an outline derived from a growing source prefix converges rather than oscillates.                                                                                                            | `spec:AST-036` FR32, FR33, FR36 | pending implementation              |
+
+### Transformation and precedence order
+
+Markdown parse configuration → ordered immutable transforms → heading nodes →
+shared perceivable-text projection → shared slug normalization → document-order
+collision allocation → Outline items.
+
+### Performance and resources
+
+- The hook recomputes only when source or parser/transform configuration changes.
+- Renderer output does not enter heading identity.
+- No DOM, renderer mount, registry, Remark runtime, or optional plugin resource is
+  required.
+
+## Accessibility contract
+
+Each derived label is the same perceivable heading text used for Markdown identity,
+and each derived ID targets the matching rendered heading. This module adds no
+interaction or ARIA behavior; the Outline component owns navigation presentation.
+
+## Design relationships
+
+No visual representation is owned by this parser utility.
+
+## Parent and system relationships
+
+- `component:Markdown` owns aggregate parsing, heading rendering, and the shared
+  projection/collision rules.
+- `spec:AST-036` owns the canonical plugin protocol and cross-surface parity.
+- Draft `component:Outline` owns presentation only after its separate anatomy and
+  theming decisions become current.
+
+## Verification map
+
+| Contract | Verification                                                            | Representative states                                                                                                                                                       | Mutation or failure expectation                                                                                                         |
+| -------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR6  | Outline parser tests, plugin transform parity tests, and Core typecheck | transformed, formatted, and extension headings; headings nested in extension containers, blockquotes, and list items; duplicate and cross-base slugs; omitted/empty plugins | A transform is skipped, a label/ID diverges from Markdown, a container changes which headings have identity, or default output changes. |
+| FR7–FR9  | Heading insert/remove parity, failure parity, and streaming derivation  | headings removed with/without sections; inserted synthetic headings; failing transform; growing source prefix; server derivation                                            | Outline/document disagreement, divergent fallback, a throw, stale IDs, or streamed oscillation.                                         |
+
+## Decision log
+
+### DEC-1 — Markdown owns heading identity; Outline projects it
+
+**Reference:** `module:Outline/parseOutlineFromMarkdown/DEC-1`
+**Decider:** cixzhang, 2026-09-15
+
+Outline utilities consume Markdown's parse configuration, ordered transforms, text
+projection, and collision allocator rather than defining a second heading-identity
+system. This keeps labels and link targets aligned without coupling plugin renderer
+output to navigation identity.
+
+### DEC-2 — One traversal survives containers and heading edits
+
+**Reference:** `module:Outline/parseOutlineFromMarkdown/DEC-2`
+**Decider:** cixzhang, 2026-09-16
+
+Extension containers hold ordinary Markdown but do not change which headings have identity. Markdown assigns IDs by one traversal and this module reads the same one, so Outline never links to a heading Markdown did not identify. A heading inside a container remains omitted like one inside a blockquote or list item, and the extension node is never an Outline entry. Widening traversal is a separate decision.
+
+Transforms may remove and insert headings, so Outline follows the rendered document rather than source: a dropped heading disappears, an inserted heading appears, and immutable source-backed depth keeps levels aligned. Both surfaces run the same pipeline rather than independent rules.
+
+Rejected: a container-only traversal exception; extension nodes as Outline entries; source-only derivation; module-local plugin failure fallback.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate plugin protocol details, Markdown parser mechanics,
+consumer examples, or the draft Outline component's anatomy and theming contract.

package/src/Outline/parseOutlineFromMarkdown.ts

@@ -2,10 +2,9 @@
 
 /**
  * @file parseOutlineFromMarkdown.ts
- * @input Uses Markdown parser internals (parseMarkdown + heading slug
- *   helpers) and OutlineItem type
+ * @input Uses Markdown's canonical AST parser and heading slug helpers
  * @output Exports parseOutlineFromMarkdown for extracting heading outlines from Markdown
- * @position Pure utility; consumed by useOutlineFromMarkdown and public exports
+ * @position Pure compatibility utility; consumed by useOutlineFromMarkdown and public exports
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Outline/Outline.doc.mjs
@@ -13,11 +12,19 @@
  */
 
 import {
-  parseMarkdown,
-  inlineText,
+  parseMarkdownAstInternal,
   slugify,
   uniqueSlug,
 } from '../Markdown/parser';
+import {markdownAstText} from '../Markdown/ast';
+import {
+  markdownExtensionText,
+  prepareMarkdownPlugins,
+} from '../Markdown/plugins/protocol';
+import type {
+  MarkdownExtensionNode,
+  MarkdownPluginEntry,
+} from '../Markdown/plugins/protocol';
 import type {OutlineItem} from './types';
 
 /**
@@ -28,16 +35,39 @@ import type {OutlineItem} from './types';
  * Ids come from the parser's shared slug helpers, so they always match the
  * `id` attributes Markdown renders on its headings.
  */
-export function parseOutlineFromMarkdown(markdown: string): OutlineItem[] {
+export interface ParseOutlineFromMarkdownOptions<
+  Node extends MarkdownExtensionNode = never,
+> {
+  readonly plugins?: ReadonlyArray<MarkdownPluginEntry<Node>>;
+  /** Match Markdown's transform finality while content is streaming. */
+  readonly isFinal?: boolean;
+}
+
+export function parseOutlineFromMarkdown<
+  Node extends MarkdownExtensionNode = never,
+>(
+  markdown: string,
+  options?: ParseOutlineFromMarkdownOptions<Node>,
+): OutlineItem[] {
+  const prepared =
+    options?.plugins == null
+      ? undefined
+      : prepareMarkdownPlugins(options.plugins);
   const counts = new Map<string, number>();
-  return parseMarkdown(markdown)
-    .filter(block => block.type === 'heading')
+  return parseMarkdownAstInternal(
+    markdown,
+    {plugins: options?.plugins},
+    options?.isFinal ?? true,
+  )
+    .children.filter(block => block.type === 'heading')
     .map(block => {
-      const label = inlineText(block.children).trim();
+      const label = markdownAstText(block.children, node =>
+        markdownExtensionText(prepared, node),
+      ).trim();
       return {
         id: uniqueSlug(slugify(label), counts),
         label,
-        level: block.level,
+        level: block.depth,
       };
     });
 }

package/src/Outline/useOutlineFromMarkdown.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useOutlineFromMarkdown.ts
- * @input Uses React, parseOutlineFromMarkdown
+ * @input Uses React, parseOutlineFromMarkdown, and optional Markdown plugins
  * @output Exports useOutlineFromMarkdown hook
  * @position Hook utility; consumed by applications and Outline examples
  *
@@ -15,9 +15,21 @@
 
 import {useMemo} from 'react';
 import {parseOutlineFromMarkdown} from './parseOutlineFromMarkdown';
+import type {ParseOutlineFromMarkdownOptions} from './parseOutlineFromMarkdown';
+import type {MarkdownExtensionNode} from '../Markdown/plugins/protocol';
 import type {OutlineItem} from './types';
 
 /** Extract a stable outline from a Markdown string. */
-export function useOutlineFromMarkdown(markdown: string): OutlineItem[] {
-  return useMemo(() => parseOutlineFromMarkdown(markdown), [markdown]);
+export function useOutlineFromMarkdown<
+  Node extends MarkdownExtensionNode = never,
+>(
+  markdown: string,
+  options?: ParseOutlineFromMarkdownOptions<Node>,
+): OutlineItem[] {
+  const plugins = options?.plugins;
+  const isFinal = options?.isFinal;
+  return useMemo(
+    () => parseOutlineFromMarkdown(markdown, {plugins, isFinal}),
+    [markdown, plugins, isFinal],
+  );
 }

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -188,12 +188,12 @@ export const docs = {
     },
     {
       name: 'onFocus',
-      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      type: '(e: React.FocusEvent) => void',
       description: 'Fires when focus enters the search input.',
     },
     {
       name: 'onBlur',
-      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      type: '(e: React.FocusEvent) => void',
       description: 'Fires when focus leaves the search input.',
     },
     {