@astryxdesign/core 0.4.4 → 0.4.5-canary.013e728

package/src/Layout/padding.stylex.ts

@@ -326,21 +326,201 @@ export const paddingBlockStyles = stylex.create({
 });
 
 /**
- * Propagation styles for --astryx-section-padding.
+ * Inline-start-only padding override styles.
+ * Use when a component needs to override the inline-start edge independently
+ * of inline-end. Logical, so it follows the writing direction (left in LTR,
+ * right in RTL).
+ */
+export const paddingInlineStartStyles = stylex.create({
+  0: {paddingInlineStart: spacingVars['--spacing-0']},
+  0.5: {paddingInlineStart: spacingVars['--spacing-0-5']},
+  1: {paddingInlineStart: spacingVars['--spacing-1']},
+  1.5: {paddingInlineStart: spacingVars['--spacing-1-5']},
+  2: {paddingInlineStart: spacingVars['--spacing-2']},
+  3: {paddingInlineStart: spacingVars['--spacing-3']},
+  4: {paddingInlineStart: spacingVars['--spacing-4']},
+  5: {paddingInlineStart: spacingVars['--spacing-5']},
+  6: {paddingInlineStart: spacingVars['--spacing-6']},
+  8: {paddingInlineStart: spacingVars['--spacing-8']},
+  10: {paddingInlineStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Inline-end-only padding override styles.
+ * The inline-end counterpart of paddingInlineStartStyles.
+ */
+export const paddingInlineEndStyles = stylex.create({
+  0: {paddingInlineEnd: spacingVars['--spacing-0']},
+  0.5: {paddingInlineEnd: spacingVars['--spacing-0-5']},
+  1: {paddingInlineEnd: spacingVars['--spacing-1']},
+  1.5: {paddingInlineEnd: spacingVars['--spacing-1-5']},
+  2: {paddingInlineEnd: spacingVars['--spacing-2']},
+  3: {paddingInlineEnd: spacingVars['--spacing-3']},
+  4: {paddingInlineEnd: spacingVars['--spacing-4']},
+  5: {paddingInlineEnd: spacingVars['--spacing-5']},
+  6: {paddingInlineEnd: spacingVars['--spacing-6']},
+  8: {paddingInlineEnd: spacingVars['--spacing-8']},
+  10: {paddingInlineEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-start CSS variable style, set independently of
+ * inline-end so a per-edge override keeps edge-compensating children (Card,
+ * Divider, a nested Section) compensating against the padding actually
+ * applied on that edge.
+ */
+export const containerPaddingInlineStartVarStyles = stylex.create({
+  0: {'--container-padding-inline-start': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-start': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-start': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-start': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-start': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-start': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-start': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-start': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-start': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-start': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-start': spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-end CSS variable style, the counterpart of
+ * containerPaddingInlineStartVarStyles.
+ */
+export const containerPaddingInlineEndVarStyles = stylex.create({
+  0: {'--container-padding-inline-end': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-end': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-end': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-end': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-end': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-end': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-end': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-end': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-end': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-end': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-end': spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-start-only padding override styles.
+ * Use when a component needs to override the block-start (top) edge
+ * independently of block-end — e.g. a section that sits under a sticky
+ * header and needs less padding above than below.
+ */
+export const paddingBlockStartStyles = stylex.create({
+  0: {paddingBlockStart: spacingVars['--spacing-0']},
+  0.5: {paddingBlockStart: spacingVars['--spacing-0-5']},
+  1: {paddingBlockStart: spacingVars['--spacing-1']},
+  1.5: {paddingBlockStart: spacingVars['--spacing-1-5']},
+  2: {paddingBlockStart: spacingVars['--spacing-2']},
+  3: {paddingBlockStart: spacingVars['--spacing-3']},
+  4: {paddingBlockStart: spacingVars['--spacing-4']},
+  5: {paddingBlockStart: spacingVars['--spacing-5']},
+  6: {paddingBlockStart: spacingVars['--spacing-6']},
+  8: {paddingBlockStart: spacingVars['--spacing-8']},
+  10: {paddingBlockStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-end-only padding override styles.
+ * The block-end counterpart of paddingBlockStartStyles.
+ */
+export const paddingBlockEndStyles = stylex.create({
+  0: {paddingBlockEnd: spacingVars['--spacing-0']},
+  0.5: {paddingBlockEnd: spacingVars['--spacing-0-5']},
+  1: {paddingBlockEnd: spacingVars['--spacing-1']},
+  1.5: {paddingBlockEnd: spacingVars['--spacing-1-5']},
+  2: {paddingBlockEnd: spacingVars['--spacing-2']},
+  3: {paddingBlockEnd: spacingVars['--spacing-3']},
+  4: {paddingBlockEnd: spacingVars['--spacing-4']},
+  5: {paddingBlockEnd: spacingVars['--spacing-5']},
+  6: {paddingBlockEnd: spacingVars['--spacing-6']},
+  8: {paddingBlockEnd: spacingVars['--spacing-8']},
+  10: {paddingBlockEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Propagation styles for `--_section-padding-propagated`.
  * When a parent section sets explicit padding, this propagates the value
  * through the CSS custom property cascade so nested sections that use
  * useThemeDefault inherit the parent's padding instead of the theme default.
+ *
+ * This is deliberately NOT the public `--astryx-section-padding` token. The
+ * two carry different authority: the public token is the THEME's section
+ * padding, set once at the theme root, while this one is one ancestor
+ * Section's padding, propagated down the tree. An overlay has to drop the
+ * inherited value at its boundary (see {@link overlayPaddingReset}) without
+ * dropping the theme's — impossible while both live under one name.
+ * `container.stylex.ts` reads this ahead of the public token, so a propagated
+ * value still wins over the theme for nested sections, as before.
  */
 export const sectionPaddingPropagationStyles = stylex.create({
-  0: {'--astryx-section-padding': spacingVars['--spacing-0']},
-  0.5: {'--astryx-section-padding': spacingVars['--spacing-0-5']},
-  1: {'--astryx-section-padding': spacingVars['--spacing-1']},
-  1.5: {'--astryx-section-padding': spacingVars['--spacing-1-5']},
-  2: {'--astryx-section-padding': spacingVars['--spacing-2']},
-  3: {'--astryx-section-padding': spacingVars['--spacing-3']},
-  4: {'--astryx-section-padding': spacingVars['--spacing-4']},
-  5: {'--astryx-section-padding': spacingVars['--spacing-5']},
-  6: {'--astryx-section-padding': spacingVars['--spacing-6']},
-  8: {'--astryx-section-padding': spacingVars['--spacing-8']},
-  10: {'--astryx-section-padding': spacingVars['--spacing-10']},
+  0: {'--_section-padding-propagated': spacingVars['--spacing-0']},
+  0.5: {'--_section-padding-propagated': spacingVars['--spacing-0-5']},
+  1: {'--_section-padding-propagated': spacingVars['--spacing-1']},
+  1.5: {'--_section-padding-propagated': spacingVars['--spacing-1-5']},
+  2: {'--_section-padding-propagated': spacingVars['--spacing-2']},
+  3: {'--_section-padding-propagated': spacingVars['--spacing-3']},
+  4: {'--_section-padding-propagated': spacingVars['--spacing-4']},
+  5: {'--_section-padding-propagated': spacingVars['--spacing-5']},
+  6: {'--_section-padding-propagated': spacingVars['--spacing-6']},
+  8: {'--_section-padding-propagated': spacingVars['--spacing-8']},
+  10: {'--_section-padding-propagated': spacingVars['--spacing-10']},
+});
+
+/**
+ * Padding-variable reset for overlay roots (Dialog, BottomSheet, Drawer,
+ * MobileNav, Lightbox, and every layer surface).
+ *
+ * ## Why an overlay needs this
+ *
+ * The container padding system talks to descendants through inherited custom
+ * properties: a padded container announces its padding, and children read the
+ * value either to apply it or to cancel it with a negative margin
+ * (`Section`, `Divider`, `Layout`, `Table`).
+ *
+ * Inheritance follows the DOM, but an overlay leaves its parent's visual box —
+ * a fixed/top-layer `<dialog>` is a DOM descendant of the padded page while
+ * being nowhere near it on screen. It inherits values describing padding that
+ * is not there, and its content compensates against phantom space: a `Section`
+ * inside a 640px sheet rendered 672px wide and hung off both edges (#5208).
+ *
+ * Two families leak, and they need opposite treatments:
+ *
+ * - `--container-padding-*` -> `0px`. Descendants SUBTRACT these (bleed
+ *   margins). The overlay root has no padding of its own to escape, so the
+ *   honest answer is zero. Nested containers that do set padding (a Dialog's
+ *   content wrapper) re-announce their own values below this point, so
+ *   legitimate edge-to-edge bleed inside the overlay is unaffected.
+ * - `--layout-padding-*` and `--_section-padding-propagated` -> `initial`.
+ *   Descendants ADD these, so zeroing them would strip padding rather than
+ *   restore it. `initial` makes each guaranteed-invalid, so readers fall
+ *   through their own `var(…, fallback)` chain and land on the theme default —
+ *   which is what an overlay at the top of the tree should show.
+ *
+ * `initial` is also why propagation moved off `--astryx-section-padding`: that
+ * name is public theme surface, set at the theme root, and making it invalid
+ * here would blank the theme's own section padding inside every overlay.
+ *
+ * Apply on the overlay's outermost styled element.
+ *
+ * @example
+ * ```
+ * <dialog {...stylex.props(styles.dialog, overlayPaddingReset.reset)} />
+ * ```
+ */
+export const overlayPaddingReset = stylex.create({
+  reset: {
+    // Subtracted by descendants — the overlay root has no padding to escape.
+    '--container-padding-inline-start': '0px',
+    '--container-padding-inline-end': '0px',
+    '--container-padding-block-start': '0px',
+    '--container-padding-block-end': '0px',
+    // Added by descendants — fall through to each reader's own default.
+    '--layout-padding-outer-x': 'initial',
+    '--layout-padding-outer-y': 'initial',
+    '--layout-padding-inner-x': 'initial',
+    '--layout-padding-inner-y': 'initial',
+    '--_section-padding-propagated': 'initial',
+  },
 });

package/src/Lightbox/Lightbox.tsx

@@ -36,6 +36,7 @@ import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -588,7 +589,7 @@ export function Lightbox({
       aria-label={currentItem.alt || t('@astryx.lightbox.mediaViewer')}
       {...mergeProps(
         themeProps('lightbox'),
-        stylex.props(styles.dialog, xstyle),
+        stylex.props(styles.dialog, overlayPaddingReset.reset, xstyle),
         className,
         style,
       )}

package/src/Link/Link.tsx

@@ -61,7 +61,7 @@ const styles = stylex.create({
     fontWeight: 'inherit',
     textDecoration: {
       default: 'none',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': 'underline',
       },
     },
@@ -103,7 +103,7 @@ const linkColorStyles = stylex.create({
   primary: {
     color: {
       default: colorVars['--color-text-primary'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-primary']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
@@ -111,7 +111,7 @@ const linkColorStyles = stylex.create({
   secondary: {
     color: {
       default: colorVars['--color-text-secondary'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-secondary']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
@@ -125,7 +125,7 @@ const linkColorStyles = stylex.create({
   accent: {
     color: {
       default: colorVars['--color-text-accent'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },

package/src/Markdown/Markdown.doc.mjs

@@ -169,6 +169,7 @@ export const docs = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },
@@ -381,6 +382,7 @@ export const docsZh = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },
@@ -396,6 +398,7 @@ export const docsDense = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },

package/src/Markdown/Markdown.test.tsx

@@ -5,6 +5,7 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import type {ReactNode} from 'react';
 import {Markdown} from './Markdown';
 import type {MarkdownInlinePlugin} from './Markdown';
+import {parseOutlineFromMarkdown} from '../Outline/parseOutlineFromMarkdown';
 
 describe('Markdown', () => {
   it('renders with role="document"', () => {
@@ -23,6 +24,83 @@ describe('Markdown', () => {
     expect(screen.getByText('Heading 2').tagName).toBe('H2');
   });
 
+  describe('heading ids', () => {
+    // Outline's documented contract: an outline item id "should match the
+    // target heading element id". Markdown renders the ids that
+    // useOutlineFromMarkdown derives, so hash navigation resolves.
+    it('renders generated id attributes on headings', () => {
+      render(<Markdown>{'# Overview\n\ncontent\n\n# Installation'}</Markdown>);
+      expect(screen.getByText('Overview')).toHaveAttribute('id', 'overview');
+      expect(screen.getByText('Installation')).toHaveAttribute(
+        'id',
+        'installation',
+      );
+    });
+
+    it('disambiguates duplicate headings with numeric suffixes', () => {
+      render(<Markdown>{'# Setup\n\n# Setup\n\n# Setup'}</Markdown>);
+      const ids = screen.getAllByText('Setup').map(el => el.id);
+      expect(ids).toEqual(['setup', 'setup-1', 'setup-2']);
+    });
+
+    it('renders ids matching parseOutlineFromMarkdown for the same source', () => {
+      // Parity invariant: every id the outline derives must resolve to a
+      // rendered heading with that exact id — including slugified formatting,
+      // duplicate numbering, the empty-slug fallback, and code-fence decoys.
+      const source = [
+        '# **Bold** and _italic_ text',
+        '## Setup',
+        '## Setup',
+        '### !!!',
+        '```',
+        '# not a heading',
+        '```',
+        '## The `useState` hook',
+      ].join('\n\n');
+      const {container} = render(<Markdown>{source}</Markdown>);
+      const outline = parseOutlineFromMarkdown(source);
+      expect(outline.length).toBe(5);
+      for (const item of outline) {
+        const target = container.querySelector(`[id="${item.id}"]`);
+        expect(target, `no rendered heading with id "${item.id}"`).not.toBe(
+          null,
+        );
+        expect(target!.tagName).toMatch(/^H[1-6]$/);
+        expect(target!.textContent?.trim()).toBe(item.label);
+      }
+    });
+
+    it('passes the generated id to a custom heading component', () => {
+      const received: (string | undefined)[] = [];
+      render(
+        <Markdown
+          components={{
+            heading: ({children, id}: {children: ReactNode; id?: string}) => {
+              received.push(id);
+              return <h2 id={id}>{children}</h2>;
+            },
+          }}>
+          {'# Overview\n\n# Overview'}
+        </Markdown>,
+      );
+      expect(received).toEqual(['overview', 'overview-1']);
+    });
+
+    it('does not assign ids to headings nested inside blockquotes', () => {
+      // parseOutlineFromMarkdown only lists top-level headings. If nested
+      // headings consumed slugs too, duplicate numbering would drift and
+      // outline links would land on the wrong heading.
+      const source = '> # Quoted\n\n# Quoted';
+      const {container} = render(<Markdown>{source}</Markdown>);
+      const outline = parseOutlineFromMarkdown(source);
+      expect(outline.map(i => i.id)).toEqual(['quoted']);
+      const [nested, topLevel] = screen.getAllByText('Quoted');
+      expect(container.querySelector('blockquote')).toContainElement(nested);
+      expect(nested).not.toHaveAttribute('id');
+      expect(topLevel).toHaveAttribute('id', 'quoted');
+    });
+  });
+
   it('renders paragraphs as block <div> (never <p>) for composition safety', () => {
     render(<Markdown>{'Hello world'}</Markdown>);
     // Markdown paragraphs render as <div> so block-level inline content

package/src/Markdown/Markdown.tsx

@@ -53,6 +53,9 @@ import {
   parseMarkdownIncremental,
   createIncrementalState,
   trimStreamingArtifacts,
+  inlineText,
+  slugify,
+  uniqueSlug,
 } from './parser';
 import type {BlockNode, InlineNode, IncrementalState} from './parser';
 import {themeProps} from '../utils/themeProps';
@@ -108,6 +111,14 @@ export interface MarkdownComponents {
   heading?: React.ComponentType<{
     level: 1 | 2 | 3 | 4 | 5 | 6;
     children: React.ReactNode;
+    /**
+     * Generated slug for this heading, matching the ids produced by
+     * useOutlineFromMarkdown / parseOutlineFromMarkdown. Render it as the
+     * element's `id` to keep Outline hash navigation working. Undefined for
+     * headings nested inside blockquotes or list items (the outline only
+     * lists top-level headings).
+     */
+    id?: string;
   }>;
   paragraph?: React.ComponentType<{children: React.ReactNode}>;
   image?: React.ComponentType<{src: string; alt: string}>;
@@ -1045,6 +1056,7 @@ function renderBlock(
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
   t: TranslatorFn,
+  headingIdMap?: ReadonlyMap<BlockNode, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1071,10 +1083,15 @@ function renderBlock(
           components,
         ),
       );
+      // Only top-level headings get an id: the map is built from the same
+      // traversal parseOutlineFromMarkdown uses (which skips headings nested
+      // in blockquotes / list items), so rendered ids and outline ids stay
+      // identical — including duplicate-slug numbering.
+      const headingId = headingIdMap?.get(node);
       const HeadingComp = components?.heading;
       if (HeadingComp) {
         return (
-          <HeadingComp key={index} level={level}>
+          <HeadingComp key={index} level={level} id={headingId}>
             {headingChildren}
           </HeadingComp>
         );
@@ -1083,6 +1100,7 @@ function renderBlock(
       return (
         <Tag
           key={index}
+          id={headingId}
           {...mergeProps(
             themeProps('markdown-heading', {density, level}),
             stylex.props(
@@ -1652,6 +1670,27 @@ export function Markdown({
     return parseMarkdown(children, parseOptions);
   }, [display, smoothedText, children, isStreaming, parseOptions]);
 
+  // Assign each top-level heading the slug that parseOutlineFromMarkdown
+  // would derive for it, so Outline hash links built from the same source
+  // always find a matching DOM id. Mirrors that function's traversal exactly:
+  // top-level blocks only, one shared duplicate-numbering sequence.
+  // NOTE: must stay above the `display === 'inline'` early return below —
+  // hooks cannot be conditional.
+  const headingIdMap = useMemo(() => {
+    if (display === 'inline' || blocks.length === 0) {
+      return undefined;
+    }
+    const map = new Map<BlockNode, string>();
+    const counts = new Map<string, number>();
+    for (const block of blocks) {
+      if (block.type === 'heading') {
+        const label = inlineText(block.children).trim();
+        map.set(block, uniqueSlug(slugify(label), counts));
+      }
+    }
+    return map;
+  }, [display, blocks]);
+
   const inlineNodes = useMemo(() => {
     if (display !== 'inline') {
       return [];
@@ -1765,6 +1804,7 @@ export function Markdown({
           inlinePlugins,
           components,
           t,
+          headingIdMap,
         ),
       )}
     </div>

package/src/Markdown/parser.ts

@@ -3,8 +3,10 @@
 /**
  * @file parser.ts
  * @input Markdown string
- * @output Array of MarkdownNode AST nodes
- * @position Core parser; consumed by Markdown.tsx
+ * @output Array of MarkdownNode AST nodes; heading slug helpers
+ *   (inlineText, slugify, uniqueSlug) shared by Markdown rendering and
+ *   Outline's parseOutlineFromMarkdown
+ * @position Core parser; consumed by Markdown.tsx and Outline
  */
 
 // ---------------------------------------------------------------------------
@@ -1815,3 +1817,59 @@ export function parseMarkdownIncremental(
 
   return mergeSettledBlocks(settledBlocks, unsettledBlocks);
 }
+
+// ---------------------------------------------------------------------------
+// Heading slugs
+// ---------------------------------------------------------------------------
+// Single source of truth for the heading id contract: Markdown renders these
+// slugs as `id` attributes on h1–h6, and Outline's parseOutlineFromMarkdown
+// derives its item ids from the same functions, so outline hash links always
+// resolve to a rendered heading by construction.
+
+/** Flatten inline nodes into their plain text content. */
+export function inlineText(nodes: InlineNode[]): string {
+  return nodes
+    .map(node => {
+      switch (node.type) {
+        case 'text':
+        case 'code':
+          return node.content;
+        case 'bold':
+        case 'italic':
+        case 'strikethrough':
+        case 'link':
+          return inlineText(node.children);
+        case 'image':
+          return node.alt;
+        case 'citation':
+        case 'break':
+          return '';
+      }
+    })
+    .join('');
+}
+
+/** Turn heading text into a URL-safe slug (lowercase, hyphen-separated). */
+export function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Disambiguate repeated slugs with a numeric suffix (`setup`, `setup-1`, …).
+ * Empty slugs fall back to `section`. The caller owns the counts map so one
+ * document shares a single numbering sequence.
+ */
+export function uniqueSlug(
+  baseSlug: string,
+  counts: Map<string, number>,
+): string {
+  const fallbackSlug = baseSlug || 'section';
+  const count = counts.get(fallbackSlug) ?? 0;
+  counts.set(fallbackSlug, count + 1);
+  return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
+}