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

package/src/Link/useLinkComponent.test.tsx

@@ -208,6 +208,339 @@ describe('useLinkComponent — to prop', () => {
   });
 });
 
+// =============================================================================
+// href scheme rule
+// =============================================================================
+
+describe('useLinkComponent — href scheme rule', () => {
+  // Kept in a const so the JSX stays lint-clean — the test is ABOUT this URL.
+  const scriptUrl = 'javascript:alert(1)';
+
+  function HrefConsumer({href}: {href: string}) {
+    const LinkComponent = useLinkComponent();
+    return (
+      <LinkComponent href={href} data-testid="resolved-link">
+        Link
+      </LinkComponent>
+    );
+  }
+
+  function propSpy() {
+    return vi.fn(
+      ({
+        children,
+        ...props
+      }: {
+        children?: React.ReactNode;
+        [key: string]: unknown;
+      }) => (
+        <a data-testid="spy-link" href={props.href as string}>
+          {children}
+        </a>
+      ),
+    );
+  }
+
+  it('forwards ordinary hrefs to a custom component untouched', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    render(
+      <LinkProvider component={SpyLink}>
+        <HrefConsumer href="/docs/button" />
+      </LinkProvider>,
+    );
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({href: '/docs/button', to: '/docs/button'}),
+    );
+  });
+
+  it('withholds a script-scheme href from a custom component (href and to alike)', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    render(
+      <LinkProvider component={SpyLink}>
+        {/* eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates */}
+        <HrefConsumer href={scriptUrl} />
+      </LinkProvider>,
+    );
+    expect(spy).not.toHaveBeenCalled();
+    expect(screen.getByTestId('resolved-link')).not.toHaveAttribute('href');
+  });
+
+  it('an explicit `to` passes the same check instead of riding through ...rest', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    function ToConsumer({to}: {to: string}) {
+      const LinkComponent = useLinkComponent();
+      return (
+        <LinkComponent href="/fallback" to={to} data-testid="resolved-link">
+          Link
+        </LinkComponent>
+      );
+    }
+    render(
+      <LinkProvider component={SpyLink}>
+        {/* eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never reaches the router */}
+        <ToConsumer to={scriptUrl} />
+      </LinkProvider>,
+    );
+    expect(spy).not.toHaveBeenCalled();
+    expect(screen.getByTestId('resolved-link')).not.toHaveAttribute('href');
+  });
+
+  it('an ordinary explicit `to` keeps its precedence over href', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    function ToConsumer() {
+      const LinkComponent = useLinkComponent();
+      return (
+        <LinkComponent
+          href="/fallback"
+          to="/routed"
+          data-testid="resolved-link">
+          Link
+        </LinkComponent>
+      );
+    }
+    render(
+      <LinkProvider component={SpyLink}>
+        <ToConsumer />
+      </LinkProvider>,
+    );
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({href: '/fallback', to: '/routed'}),
+    );
+  });
+});
+
+// =============================================================================
+// structured router `to`
+// =============================================================================
+
+describe('useLinkComponent — structured router `to`', () => {
+  const scriptUrl = 'javascript:alert(1)';
+
+  function propSpy() {
+    return vi.fn(
+      ({
+        children,
+        ...props
+      }: {
+        children?: React.ReactNode;
+        [key: string]: unknown;
+      }) => (
+        <a data-testid="spy-link" href={props.href as string}>
+          {children}
+        </a>
+      ),
+    );
+  }
+
+  function ToConsumer({to}: {to: unknown}) {
+    const LinkComponent = useLinkComponent();
+    return (
+      <LinkComponent href="/fallback" to={to} data-testid="resolved-link">
+        Link
+      </LinkComponent>
+    );
+  }
+
+  it('preserves a structured destination for the router (no crash, same object)', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    const to = {pathname: '/docs', search: '?q=1', hash: '#top'};
+    render(
+      <LinkProvider component={SpyLink}>
+        <ToConsumer to={to} />
+      </LinkProvider>,
+    );
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({href: '/fallback', to}),
+    );
+    expect(spy.mock.calls[0][0].to).toBe(to);
+  });
+
+  it('preserves a structured destination that carries no pathname', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    const to = {search: '?page=2'};
+    render(
+      <LinkProvider component={SpyLink}>
+        <ToConsumer to={to} />
+      </LinkProvider>,
+    );
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({to}));
+  });
+
+  it('withholds a structured destination whose pathname is a script scheme', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    render(
+      <LinkProvider component={SpyLink}>
+        <ToConsumer to={{pathname: scriptUrl}} />
+      </LinkProvider>,
+    );
+    expect(spy).not.toHaveBeenCalled();
+    expect(screen.getByTestId('resolved-link')).not.toHaveAttribute('href');
+  });
+
+  it('withholds a structured destination whose href is a script scheme', () => {
+    const spy = propSpy();
+    function SpyLink(props: {[key: string]: unknown}) {
+      return spy(props);
+    }
+    render(
+      <LinkProvider component={SpyLink}>
+        <ToConsumer to={{href: scriptUrl}} />
+      </LinkProvider>,
+    );
+    expect(spy).not.toHaveBeenCalled();
+    expect(screen.getByTestId('resolved-link')).not.toHaveAttribute('href');
+  });
+});
+
+// =============================================================================
+// Shared native and router boundary
+// =============================================================================
+
+describe('useLinkComponent — rejected destinations are inert', () => {
+  function Consumer({
+    href,
+    to,
+    as,
+    onClick,
+    linkRef,
+  }: {
+    href?: unknown;
+    to?: unknown;
+    as?: LinkComponentType;
+    onClick?: () => void;
+    linkRef?: React.Ref<HTMLAnchorElement>;
+  }) {
+    const Component = useLinkComponent(as);
+    return (
+      <Component
+        href={href}
+        to={to}
+        ref={linkRef}
+        onClick={onClick}
+        className="consumer-class"
+        aria-label="Destination"
+        data-testid="destination">
+        Go
+      </Component>
+    );
+  }
+
+  for (const mode of ['native', 'provider', 'as'] as const) {
+    it.each([
+      {href: 'javascript:alert(1)'},
+      {href: 'vbscript:MsgBox(1)'},
+      {href: 'data:text/html,<b>x</b>'},
+      {href: 'java\nscript:alert(1)'},
+      {href: '/safe', to: 'javascript:alert(1)'},
+      {href: 'vbscript:MsgBox(1)', to: '/safe'},
+      {href: {protocol: 'javascript:', pathname: 'alert(1)'}},
+      {href: '/safe', to: {protocol: 'data:', pathname: 'text/html,x'}},
+    ])(`${mode}: rejects %j without calling a router`, props => {
+      const router = vi.fn(() => {
+        throw new Error('rejected router invoked');
+      });
+      const onClick = vi.fn();
+      const linkRef = vi.fn();
+      render(
+        <LinkProvider component={mode === 'provider' ? router : 'a'}>
+          <Consumer
+            {...props}
+            as={mode === 'as' ? router : undefined}
+            onClick={onClick}
+            linkRef={linkRef}
+          />
+        </LinkProvider>,
+      );
+      const node = screen.getByTestId('destination');
+      expect(router).not.toHaveBeenCalled();
+      expect(node.tagName).toBe('A');
+      expect(node).not.toHaveAttribute('href');
+      expect(node).not.toHaveAttribute('to');
+      expect(node).not.toHaveAttribute('aria-disabled');
+      expect(node).toHaveAttribute('aria-label', 'Destination');
+      expect(node).toHaveClass('consumer-class');
+      expect(linkRef.mock.calls[0][0]).toBe(node);
+      node.click();
+      expect(onClick).toHaveBeenCalledOnce();
+    });
+  }
+
+  it.each([
+    '/relative',
+    '#fragment',
+    'https://example.com',
+    'http://example.com',
+    'mailto:a@example.com',
+    'tel:+1234567890',
+    'custom:document',
+    'data:text/plain,download',
+  ])('preserves native href and download affordances for %s', href => {
+    function Download() {
+      const Component = useLinkComponent();
+      return (
+        <Component
+          href={href}
+          download="note.txt"
+          target="_blank"
+          rel="noopener"
+          data-testid="download">
+          Download
+        </Component>
+      );
+    }
+    render(<Download />);
+    const node = screen.getByTestId('download');
+    expect(node).toHaveAttribute('href', href);
+    expect(node).toHaveAttribute('download', 'note.txt');
+    expect(node).toHaveAttribute('target', '_blank');
+    expect(node).toHaveAttribute('rel', 'noopener');
+  });
+
+  it('preserves both structured prop identities and safe explicit precedence', () => {
+    const router = vi.fn<(props: {href?: unknown; to?: unknown}) => null>(
+      () => null,
+    );
+    const href = {
+      protocol: 'https:',
+      hostname: 'example.com',
+      pathname: '/docs',
+    };
+    const to = {pathname: '/next', search: '?q=1', hash: '#top'};
+    render(<Consumer as={router} href={href} to={to} />);
+    expect(router.mock.calls[0][0].href).toBe(href);
+    expect(router.mock.calls[0][0].to).toBe(to);
+  });
+
+  it('keeps the native node stable while accepted props update', () => {
+    const {rerender} = render(<Consumer href="/first" />);
+    const node = screen.getByTestId('destination');
+    rerender(<Consumer href="/second" />);
+    expect(screen.getByTestId('destination')).toBe(node);
+    expect(node).toHaveAttribute('href', '/second');
+  });
+});
+
 // =============================================================================
 // LinkProvider
 // =============================================================================

package/src/Link/useLinkComponent.ts

@@ -4,89 +4,61 @@
 
 /**
  * @file useLinkComponent.ts
- * @input React use, useMemo, createElement, forwardRef, LinkContext, LinkComponentType
- * @output Exports useLinkComponent hook
- * @position Hook for resolving the link component in Astryx components
+ * @input Per-component override, LinkProvider context, and navigation props
+ * @output Stable link component with destination checks and custom-router `to` injection
+ * @position Shared native and custom link boundary; rejected destinations render
+ *   as destination-less anchors without invoking a router.
  *
- * Resolution order: per-component `as` prop > LinkProvider context > native `<a>`.
- *
- * When the resolved component is a custom component (not native `<a>`),
- * wraps it to pass `to={href}` alongside `href`. This enables compatibility
- * with routers that use `to` (React Router, TanStack Router)
- * without requiring an adapter component.
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Link/index.ts
- * - /packages/core/src/Link/Link.doc.mjs
+ * SYNC: Link.doc.mjs and LinkProvider.doc.mjs describe this boundary.
  */
 
 import {use, useMemo, createElement} from 'react';
 import {LinkContext} from './LinkContext';
+import {isSafeDestination} from '../utils/safeUrl';
 import type {LinkComponentType} from './types';
 
-/**
- * Creates a wrapper component that passes both `href` and `to` props
- * to the underlying link component. This enables routers that use `to`
- * (React Router, TanStack Router) to work without an adapter.
- *
- * The wrapper is transparent: it forwards refs and all other props unchanged.
- * Native `<a>` elements ignore the unknown `to` prop harmlessly.
- */
-function createLinkWithTo(
-  Component: LinkComponentType,
-): LinkComponentType {
-  function LinkWithTo({
+function createSafeLink(Component: LinkComponentType): LinkComponentType {
+  function SafeLink({
     href,
+    to,
     ref,
     ...rest
   }: {
-    href?: string;
-    to?: string;
+    href?: unknown;
+    to?: unknown;
     ref?: React.Ref<unknown>;
   }) {
-    return createElement(Component, {ref, href, to: href, ...rest});
+    // An undefined destination can crash a router or resolve to the current
+    // route. Reject the whole handoff, not just one prop or a fallback value.
+    if (!isSafeDestination(href) || !isSafeDestination(to)) {
+      return createElement('a', {ref, ...rest});
+    }
+    if (Component === 'a') {
+      return createElement('a', {ref, ...rest, href});
+    }
+    return createElement(Component, {ref, ...rest, href, to: to ?? href});
   }
-  LinkWithTo.displayName = `LinkWithTo(${
+  SafeLink.displayName = `SafeLink(${
     typeof Component === 'string'
       ? Component
       : Component.displayName || Component.name || 'Component'
   })`;
-  return LinkWithTo as LinkComponentType;
+  return SafeLink as LinkComponentType;
 }
 
 /**
- * Resolves the link component to use.
- *
- * Priority: `as` prop > `LinkProvider` context > native `<a>`.
- *
- * When the resolved component is a custom component (not the native `<a>`),
- * it is wrapped to receive both `href` and `to` props set to the same value.
- * This allows `to`-based routers (React Router, TanStack Router) to work
- * out of the box without a manual adapter.
- *
- * @param as - Per-component override. If provided, takes highest priority.
- * @returns The resolved link component (with `to` injection for custom components).
+ * Resolve `as`, then LinkProvider, then a native anchor. Both destination props
+ * are checked before rendering; accepted structured values retain identity.
+ * Custom components receive `to={href}` unless an explicit `to` is supplied.
  *
  * @example
  * ```
- * function MyComponent({ as }: { as?: LinkComponentType }) {
- *   const LinkComponent = useLinkComponent(as);
- *   return <LinkComponent href="/foo">Click me</LinkComponent>;
- * }
+ * const LinkComponent = useLinkComponent(as);
+ * return <LinkComponent href="/docs">Documentation</LinkComponent>;
  * ```
  */
-export function useLinkComponent(
-  as?: LinkComponentType,
-): LinkComponentType {
+export function useLinkComponent(as?: LinkComponentType): LinkComponentType {
   const ctx = use(LinkContext);
   const resolved = as ?? ctx?.component ?? 'a';
-
-  // Memoize the wrapper to maintain referential stability.
-  // The wrapper is only created for custom components (not native <a>).
-  return useMemo(() => {
-    if (resolved === 'a') {
-      return 'a';
-    }
-    return createLinkWithTo(resolved);
-  }, [resolved]);
+  return useMemo(() => createSafeLink(resolved), [resolved]);
 }

package/src/List/List.doc.mjs

@@ -41,6 +41,12 @@ export const docs = {
       description: 'Show dividers between items.',
       default: 'false',
     },
+    {
+      name: 'edgeCompensation',
+      type: "'inline'",
+      description:
+        "Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged.",
+    },
     {
       name: 'header',
       type: 'ReactNode',

package/src/List/List.spec.md

@@ -0,0 +1,200 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:List
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-21
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming]
+verified_by:
+  [
+    packages/core/src/List/List.test.tsx,
+    packages/core/src/Item/Item.test.tsx,
+    packages/core/src/theme/derivedVarRegistry.test.ts,
+    packages/core/src/theme/generateThemeRules.test.ts,
+    apps/storybook/stories/List.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:container-padding, architecture:public-component-api]
+contributing: [contributing:api-conventions]
+system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2]
+---
+
+# List component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | Add optional `edgeCompensation?: 'inline'`; omission preserves current layout.                                                                                                                   |
+| Behavior                | Every ListItem row moves its content toward a neutral host's inline content edges, reaching them when the host inset is at least the Item inset, while retaining Item-owned interaction padding. |
+| End-user impact         | List content can reduce or remove the extra inset beside its optional header and adjacent content without shrinking hover, press, selection, or focus paint.                                     |
+| Builder impact          | Builders opt in only when the List is placed directly in an eligible container-padding host state.                                                                                               |
+| Compatibility/readiness | Additive API; implementation and required real-browser evidence are pending.                                                                                                                     |
+| Review checks           | Reject header movement, unbounded negative margins, duplicated padding values, physical-edge logic, automatic opt-in, or a ListItem-level public prop.                                           |
+| Governing rules         | `architecture:container-padding/INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`.                                                                                                                         |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+List owns collection-wide edge alignment because its optional header is not
+horizontally inset while every ListItem retains Item's inline padding. The caller
+knows whether the List is placed in a neutral host where these content lines
+should align; List cannot derive that design relationship from its children.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; omission keeps current List and ListItem geometry.
+- Compatibility class: additive optional prop with no default behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: `component:List/DEC-1` and `component:List/DEC-2`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The collection-wide `edgeCompensation` opt-in and its propagation to every
+  ListItem row.
+- Keeping the optional header in place while moving row content toward its line.
+- The supported relationship between ListItem row geometry and Item's normal
+  density- and theme-aware inline inset.
+
+**Does not own / non-goals**
+
+- Container padding values, nesting, or overlay resets — owned by
+  `architecture:container-padding`.
+- A ListItem-level compensation prop, automatic host detection, full bleed, or
+  arbitrary margin controls.
+- TabList or Button projections.
+
+## Public concepts
+
+| Concept           | Closed values or states | Meaning                                                                                               | Availability by variant/orientation/state               | Default | Owner            | Stability                        | Invalid-value behavior                       |
+| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------- | ---------------- | -------------------------------- | -------------------------------------------- |
+| Edge compensation | omitted, `inline`       | Move row content toward both logical host content edges while retaining row-local interaction padding | Every List density and marker style in an eligible host | omitted | `component:List` | accepted; implementation pending | Other values are rejected by the public type |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                         | Basis                                                               | Status                                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
+| FR1 | List MUST own `edgeCompensation?: 'inline'`; ListItem MUST NOT expose a parallel public prop.                                                                                                                                                                                                                                                                     | `component:List/DEC-1`                                              | Accepted contract; implementation pending |
+| FR2 | Omission MUST preserve current header, list, and row geometry. Enabling `inline` MUST leave the optional header in place and apply one compensation policy to every ListItem, including non-interactive rows.                                                                                                                                                     | Owner direction                                                     | Accepted contract; implementation pending |
+| FR3 | Each row MUST resolve each logical margin independently as the negative smaller of its own component-owned inline inset and the matching available host inset. Missing host inset MUST resolve to zero. Content reaches the host line only when the host inset is at least the row inset; otherwise it moves toward that line without crossing the host boundary. | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2` | Accepted contract; implementation pending |
+| FR4 | The retained row inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee; `edgeCompensation` MUST NOT mirror or infer that arbitrary CSS.                                                       | Shared two-owner geometry contract                                  | Accepted contract; implementation pending |
+| FR5 | Compensation MUST preserve Item's hover, press, selection, focus, content, semantics, and hit target. It MUST NOT make the row a full-bleed surface or pull it past either available host edge.                                                                                                                                                                   | Owner direction                                                     | Accepted contract; implementation pending |
+| FR6 | The opt-in is valid only under a host state whose published inline inset matches its applied padding and whose relevant boundary is visually neutral. Current automatic LayoutContent/LayoutPanel states with known publication mismatch are not eligible until that conformance gap is fixed.                                                                    | `architecture:container-padding/INV8–INV11`                         | Accepted contract; implementation pending |
+
+### Allowed variation
+
+- Density and `item.paddingInline` theme overrides may change the retained inset;
+  compensation follows the same derived value.
+- Container padding may be uniform, asymmetric, zero, or absent; each logical
+  edge resolves independently.
+- Labels, descriptions, markers, start/end content, interactivity, and selection
+  may vary without changing the collection-wide alignment rule.
+
+### Representative states
+
+| State                                | Required invariant                                                                      | Allowed variation                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Default/omitted                      | Header and every row keep current geometry.                                             | Any current List content and density.                     |
+| Host inset at least Item inset       | Row content reaches the host content line; row-local paint keeps Item padding.          | Uniform or asymmetric inline padding.                     |
+| Smaller, zero, or missing host inset | The row moves only by the available inset and is never pulled beyond the host boundary. | Either logical edge may independently be smaller or zero. |
+| LTR or RTL                           | Logical start/end mapping follows direction without changing the `inline` meaning.      | Writing direction.                                        |
+| Themed Item padding                  | Row padding and compensation move together.                                             | Supported `item.paddingInline` value.                     |
+
+### Transformation and precedence order
+
+- **ORD1 — Host bound.** Read the matching published host inset for each selected
+  logical edge, with missing values falling back to zero.
+- **ORD2 — Local inset.** Resolve Item's component-owned inline inset from density
+  and theme through the same private value that supplies applied padding.
+- **ORD3 — Compensation.** Apply the negative minimum of those values to the row;
+  then compose supported consumer styles without claiming alignment for a consumer
+  override of row inline padding.
+
+### Performance and resources
+
+- **PR1 — CSS geometry only.** Edge compensation MUST add no measurement,
+  observer, listener, state, Effect, or render pass.
+
+## Accessibility contract
+
+- **AR1 — Interaction geometry remains local.** Compensation MUST NOT change the
+  interactive element, accessible role/name/state, focus target, tab order, or
+  hit target.
+- **AR2 — Direction remains logical.** The same `inline` value MUST produce the
+  corresponding mirrored geometry under RTL without changing DOM order.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                                          | Representation authority | Hierarchy role     | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------ | ------------------ |
+| Optional header  | Stays on the host content line and is not moved by row compensation.                                        | `component:List/DEC-1`   | Context            | FR2                |
+| ListItem row     | Retains local interaction paint and hit-target padding.                                                     | Item composition         | Supporting surface | FR3–FR5            |
+| Row content      | Moves toward each host content line and reaches it only when the host inset can fully absorb the row inset. | `component:List/DEC-2`   | Prominent          | FR2–FR5            |
+
+## Family and system relationships
+
+- `architecture:container-padding` owns host publication, the shared
+  `edgeCompensation` vocabulary, eligibility, logical-edge semantics, and overlay
+  reset.
+- `architecture:public-component-api` and `spec:AST-002` own public API admission.
+- Item remains the implementation owner of row padding and interaction paint;
+  List owns only the collection-level opt-in and row application.
+
+## Verification map
+
+| Contract         | Verification                                                 | Representative states                                                                                                               | Mutation or failure expectation                                                                          | Audit section       |
+| ---------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
+| FR1–FR4          | List, Item, and theme-registry tests                         | omitted/enabled; all densities; theme override; static/interactive rows                                                             | Removing context propagation, duplicating a padding value, or using one host edge for both margins fails | `audit:List/layout` |
+| FR2–FR6, AR1–AR2 | Real-browser List geometry evidence                          | header; LTR/RTL; uniform/asymmetric/zero/missing host inset; host inset smaller/equal/larger than Item inset; hover/selection/focus | Header movement, over-pull, wrong bounded movement, or lost row-local paint fails                        | `audit:List/visual` |
+| Documentation    | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs` | public prop/default and representative composition                                                                                  | Missing or stale contract, docs, or example fails                                                        | `audit:List/docs`   |
+
+## Decision log
+
+### DEC-1 — List owns the collection-wide opt-in
+
+**Reference:** `component:List/DEC-1`
+
+**Decider:** cixzhang, 2026-09-21
+
+The List header and ListItem rows otherwise begin on different content lines.
+Only the caller knows when the containing composition requires alignment, while
+List can apply one consistent decision to every row without exposing Item-level
+configuration.
+
+### DEC-2 — Compensation is row-local and bounded
+
+**Reference:** `component:List/DEC-2`
+
+**Decider:** cixzhang, 2026-09-21
+
+Each row cancels no more than its own component-owned inline inset or the
+matching host inset. When the host inset is at least the row inset, content
+reaches the host content line. When it is smaller, content moves toward that line
+without pulling row paint beyond the host boundary.
+
+Rejected: `isFullBleed`, because the row may stop inside the host padding and the
+name would promise outer-edge bleed that the component does not provide.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This claim-scoped contract does not duplicate List's complete prop table,
+container-padding internals, consumer examples, implementation steps, or future
+TabList/Button projections. Those remain with their named owners.