@multiplatform.one/components 7.10.0 → 7.15.0

package/src/adjacency.l1.spec.tsx

@@ -0,0 +1,175 @@
+/**
+ * `00` L1 test 1, the adjacency check (MPO-23, gap ledger GL-41). A Button,
+ * an Input, a Select trigger and a ListItem in one `XStack` at the same size
+ * token, with only a `gap`, must agree on height and on radius. They differ
+ * only in interior padding (`00` L9f). `constraintAudit` checks that each
+ * value lands on a token step; nothing checked that siblings agree.
+ *
+ * The DOM here cannot lay out and does not resolve Tamagui's CSS variables,
+ * so each frame's box is read from the atoms it paints (`_h-44px`,
+ * `_btlr-t-radius-4`, `_mih-t-size-4`) and resolved through the live token
+ * table. That is the same box a browser computes for these frames: none of
+ * them grows past its height or min-height with one line of content.
+ *
+ * The law holds for height at every size stop and for the controls' radius at
+ * the default stop. ListItem joins the height check only: it is a flush row
+ * (SP-EDGE, radius 0) and never takes the controls' radius (Clay 2026-09-26,
+ * MPO-23 ruling 1A). Two disagreements are open and pinned below as expected
+ * failures, each naming its culprit. Fixing one makes its `it.fails` go red,
+ * which is the signal to turn it into a plain assertion.
+ */
+
+import { Input, Select } from "@multiplatform.one/forms";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset, type Size } from "@multiplatform.one/theme";
+import { cleanup } from "@testing-library/react";
+import type { ReactElement } from "react";
+import { getTokens } from "tamagui";
+import { afterEach, describe, expect, it } from "vitest";
+import { Button } from "./Button";
+import { ListItem, XStack } from "./tamagui";
+
+afterEach(cleanup);
+
+type Box = { height: number; radius: number };
+type Row = Record<"Button" | "Input" | "Select trigger" | "ListItem", Box>;
+
+const stops = [
+  ["small", "$3"],
+  ["medium", "$4"],
+  ["large", "$5"],
+] as const satisfies readonly (readonly [Size, string])[];
+
+function atom(el: HTMLElement, prop: string) {
+  for (const cls of String(el.className || "").split(/\s+/)) {
+    if (!cls.startsWith(`_${prop}-`)) continue;
+    const value = cls.slice(prop.length + 2);
+    if (/^-?\d+(?:\.\d+)?px$|^t-(?:size|radius)-\d+$/.test(value)) return value;
+  }
+  return undefined;
+}
+
+function px(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const literal = value.match(/^(-?\d+(?:\.\d+)?)px$/);
+  if (literal) return Number(literal[1]);
+  const [, scale, step] = value.match(/^t-(size|radius)-(\d+)$/) ?? [];
+  const tokens = getTokens() as unknown as Record<string, Record<string, { val: unknown }>>;
+  return Number.parseFloat(String(tokens[scale ?? ""]?.[`$${step}`]?.val));
+}
+
+function box(el: HTMLElement | null, name: string): Box {
+  if (!el) throw new Error(`${name} frame not rendered`);
+  const height = px(atom(el, "h") ?? atom(el, "mih"));
+  if (height === undefined) throw new Error(`${name} paints no height`);
+  return { height, radius: px(atom(el, "btlr")) ?? 0 };
+}
+
+function measure(ui: ReactElement): Row {
+  const { container } = renderWithProviders(ui);
+  const frame = (selector: string) => container.querySelector<HTMLElement>(selector);
+  return {
+    Button: box(frame("[data-mp-button-height]"), "Button"),
+    Input: box(frame("[data-mp-input-box]"), "Input"),
+    "Select trigger": box(frame('[data-testid="select-trigger"]'), "Select trigger"),
+    ListItem: box(frame('[data-testid="l1-list-item"]'), "ListItem"),
+  };
+}
+
+/** The mpo size channel: the size knob, which every house control reads. */
+function atKnob(knob: Size, token: string) {
+  return measure(
+    <Preset overrides={{ size: knob }}>
+      <XStack gap="$2">
+        <Button>Save</Button>
+        <Input placeholder="Name" />
+        <Select options={[{ value: "a", label: "A" }]} placeholder="Pick" />
+        <ListItem size={token as "$4"} title="Row" data-testid="l1-list-item" />
+      </XStack>
+    </Preset>,
+  );
+}
+
+/** The same token handed to each component directly. */
+function atSizeProp(token: "$3" | "$4" | "$5") {
+  return measure(
+    <XStack gap="$2">
+      <Button size={token}>Save</Button>
+      <Input size={token} placeholder="Name" />
+      <Select size={token} options={[{ value: "a", label: "A" }]} placeholder="Pick" />
+      <ListItem size={token} title="Row" data-testid="l1-list-item" />
+    </XStack>,
+  );
+}
+
+function heights(row: Row) {
+  return Object.fromEntries(Object.entries(row).map(([name, b]) => [name, b.height]));
+}
+
+function radii(row: Row, names: (keyof Row)[]) {
+  return Object.fromEntries(names.map((name) => [name, row[name].radius]));
+}
+
+function agreed(values: Record<string, number>) {
+  const first = Object.values(values)[0];
+  return Object.fromEntries(Object.keys(values).map((name) => [name, first]));
+}
+
+const controls: (keyof Row)[] = ["Button", "Input", "Select trigger"];
+
+describe("00 L1 adjacency: Button, Input, Select trigger and ListItem at one size token", () => {
+  for (const [knob, token] of stops) {
+    it(`all four paint one height at size ${knob} (${token})`, () => {
+      const row = heights(atKnob(knob, token));
+      expect(row).toEqual(agreed(row));
+    });
+  }
+
+  it("catches a deliberate violation: a Button ejected to its own height", () => {
+    const row = heights(
+      measure(
+        <XStack gap="$2">
+          <Button height={30} sizeRecipeEscape="L1 adjacency fixture">
+            Save
+          </Button>
+          <Input placeholder="Name" />
+          <Select options={[{ value: "a", label: "A" }]} placeholder="Pick" />
+          <ListItem size="$4" title="Row" data-testid="l1-list-item" />
+        </XStack>,
+      ),
+    );
+    expect(row.Button).toBe(30);
+    expect(row).not.toEqual(agreed(row));
+  });
+
+  it("Button, Input and Select trigger paint one radius at the default size", () => {
+    const row = radii(atKnob("medium", "$4"), controls);
+    expect(row).toEqual(agreed(row));
+    expect(row.Button).toBeGreaterThan(0);
+  });
+
+  it("ListItem stays a flush row beside them: radius 0, never the controls' radius", () => {
+    const row = radii(atKnob("medium", "$4"), [...controls, "ListItem"]);
+    expect(row.ListItem).toBe(0);
+    expect(row.Button).toBeGreaterThan(0);
+  });
+
+  for (const [knob, token] of stops.filter(([k]) => k !== "medium")) {
+    it.fails(`OPEN: Button and Input paint one radius at size ${knob} (Button's radius follows size, Input's only the radius knob)`, () => {
+      const row = radii(atKnob(knob, token), controls);
+      expect(row).toEqual(agreed(row));
+    });
+  }
+
+  it("an explicit size prop agrees with itself at the default token", () => {
+    const row = heights(atSizeProp("$4"));
+    expect(row).toEqual(agreed(row));
+  });
+
+  for (const token of ["$3", "$5"] as const) {
+    it.fails(`OPEN: an explicit size=${token} moves Input and Select trigger with Button (Input paints the knob height, Select ignores size)`, () => {
+      const row = heights(atSizeProp(token));
+      expect(row).toEqual(agreed(row));
+    });
+  }
+});

package/src/code/Code/code.spec.tsx

@@ -1,5 +1,5 @@
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import { Code, CodeInline } from "./index";
 
 describe("Code", () => {
@@ -27,7 +27,7 @@ describe("Code", () => {
     const codeElement = container.querySelector("code");
     expect(codeElement).toBeTruthy();
     expect(codeElement!.getAttribute("data-code-font")).toBe("mono");
-    // React lowercases an unknown dataSet prop to dataset="[object Object]".
+    // An RN prop map on this host would land as dataset="[object Object]".
     expect(codeElement!.hasAttribute("dataset")).toBe(false);
   });
 });
@@ -51,21 +51,4 @@ describe("CodeInline", () => {
     const codeElement = container.querySelector("code");
     expect(codeElement).toBeDefined();
   });
-
-  it("emits data-code-font on web without a dataSet host-prop leak", () => {
-    const leak = /does not recognize the `dataSet` prop on a DOM element/;
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    try {
-      const { container } = renderWithProviders(<CodeInline>npm install</CodeInline>);
-      const codeElement = container.querySelector("code");
-      expect(codeElement).toBeDefined();
-      expect(codeElement?.getAttribute("data-code-font")).toBe("mono");
-      const leaks = errorSpy.mock.calls
-        .map((args) => args.map(String).join(" "))
-        .filter((message) => leak.test(message));
-      expect(leaks).toEqual([]);
-    } finally {
-      errorSpy.mockRestore();
-    }
-  });
 });

package/src/code/Code/index.tsx

@@ -81,12 +81,6 @@ export const CodeInline = CodeInlineFrame.styleable((props, ref) => {
       fontFamily="$mono"
       letterSpacing={0}
       data-code-font="mono"
-      // react-native-web reads dataSet; React-DOM warns on the camel host
-      // prop. Keep the kebab attribute on every target; spread dataSet
-      // only when TAMAGUI_TARGET is native.
-      {...(process.env.TAMAGUI_TARGET === "native"
-        ? ({ dataSet: { codeFont: "mono" } } as object)
-        : {})}
     />
   );
 });

package/src/code/CodeBlock/index.tsx

@@ -10,10 +10,11 @@ import { LinearGradient } from "@tamagui/linear-gradient";
 import { ClipboardIcon } from "@phosphor-icons/react";
 import {
   MIN_PRESS_TARGET,
-  isTouchSurface,
+  useTouchSurface,
   pressTargetHitSlop,
   sizeRecipeForToken,
   useResolvedKnobs,
+  transitionProps,
 } from "@multiplatform.one/theme";
 import { useEffect, useRef, useState } from "react";
 import { useTranslation } from "../../shared/i18n";
@@ -75,6 +76,7 @@ export function CodeBlock({
   const { region, copy } = useCopyFeedback();
   const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
+  const touch = useTouchSurface();
   // Content type scale follows the size knob (T-VALUE via sizeToken, LC-18);
   // an explicit size prop ejects.
   const codeSize = (size ?? knobProps.sizeToken) as any;
@@ -126,7 +128,7 @@ export function CodeBlock({
   const activateCopy = () => {
     void copy(codeText);
   };
-  const capSquare = sizeRecipeForToken(String(codeSize), { touch: isTouchSurface() }).height;
+  const capSquare = sizeRecipeForToken(String(codeSize), { touch }).height;
 
   return (
     <YStack position="relative" marginBottom="$4">
@@ -134,11 +136,11 @@ export function CodeBlock({
         <YStack
           ref={clampRef}
           position="relative"
+          {...transitionProps(transition)}
           {...(clamped && {
             maxHeight: expandTarget ?? clampHeight,
             overflow: "hidden" as const,
             ...knobProps.borderRadius,
-            ...(transition ? { transition } : {}),
           })}
         >
           {isCutoff && expandTarget == null && (

package/src/code/highlightedCode.spec.tsx

@@ -125,8 +125,8 @@ describe("HighlightedCode", () => {
     // The actual LC-07 pin: bodyFont serif / fontWeight bold must not reach
     // code text, so the line keeps the mono family class.
     expect(line!.className).toContain("font_mono");
-    // React does not recognise `dataSet`; leaving it on the line logged an
-    // unknown-prop error and wrote dataset="[object Object]" on every node.
+    // React does not recognise the RN prop map; leaving it on the line logged
+    // an unknown-prop error and wrote dataset="[object Object]" on every node.
     expect(container.querySelectorAll("[dataset]")).toHaveLength(0);
   });
 });

package/src/code/hostProps.spec.tsx

@@ -0,0 +1,55 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import type { ReactElement } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Code, CodeInline } from "./Code";
+import type { HighlightLine } from "./Highlighter";
+import { HighlightedCode } from "./HighlightedCode";
+
+const tokens: HighlightLine[] = [[{ content: "const x = 1;" }]];
+
+const cases: [string, ReactElement][] = [
+  ["Code", <Code>const x = 1;</Code>],
+  ["CodeInline", <CodeInline>npm install</CodeInline>],
+  ["HighlightedCode", <HighlightedCode tokens={tokens} />],
+];
+
+function hostProps(el: Element): Record<string, unknown> {
+  const key = Object.keys(el).find((k) => k.startsWith("__reactProps$"));
+  return key ? ((el as unknown as Record<string, Record<string, unknown>>)[key] ?? {}) : {};
+}
+
+function formatConsoleCall(args: unknown[]): string {
+  const [format = "", ...substitutions] = args.map(String);
+  let next = 0;
+  return format.replace(/%s/g, () => substitutions[next++] ?? "");
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe.each(["web", "native"])("code family host props, TAMAGUI_TARGET=%s", (target) => {
+  it.each(cases)("%s hands the code-font node no dataset prop map", (_name, node) => {
+    vi.stubEnv("TAMAGUI_TARGET", target);
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const { container } = renderWithProviders(node);
+      const hosts = Array.from(container.querySelectorAll("[data-code-font]"));
+      expect(hosts.length).toBeGreaterThan(0);
+      for (const host of hosts) {
+        const props = hostProps(host);
+        expect(props["data-code-font"]).toBe("mono");
+        expect(Object.keys(props).filter((key) => key.toLowerCase() === "dataset")).toEqual([]);
+        expect(host.hasAttribute("dataset")).toBe(false);
+      }
+      // React warns once per prop name per process, so the console alone
+      // cannot prove a later case clean; the props check above can.
+      const unknownProps = errorSpy.mock.calls
+        .map(formatConsoleCall)
+        .filter((message) => /does not recognize the `\w+` prop on a DOM element/.test(message));
+      expect(unknownProps).toEqual([]);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});

package/src/icons/themed.hydration.spec.tsx

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { renderToString } from "react-dom/server";
+import { hydrateRoot } from "react-dom/client";
+import { TestProviders } from "@multiplatform.one/test-utils";
+import { sizeRecipeForToken } from "@multiplatform.one/theme";
+import { describe, expect, it, vi } from "vitest";
+import { themed } from "./themed";
+
+const host = vi.hoisted(() => ({ touch: false }));
+vi.mock("@multiplatform.one/platform", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@multiplatform.one/platform")>()),
+  isWeb: true,
+  isTouchable: false,
+  get isWebTouchable() {
+    return host.touch;
+  },
+}));
+
+const Icon = themed(({ size }: { size?: string | number }) => <svg width={size} height={size} />);
+function Fixture() {
+  return (
+    <TestProviders>
+      <Icon size="$4" />
+    </TestProviders>
+  );
+}
+
+describe("token icon hydration", () => {
+  it("preserves the server SVG before adopting touch sizing", async () => {
+    host.touch = false;
+    const container = document.createElement("div");
+    container.innerHTML = renderToString(<Fixture />);
+    document.body.append(container);
+    const icon = container.querySelector("svg");
+    const errors: unknown[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((...args) => errors.push(args));
+    host.touch = true;
+    let root: ReturnType<typeof hydrateRoot> | undefined;
+    try {
+      await act(async () => {
+        root = hydrateRoot(container, <Fixture />, {
+          onRecoverableError: (error) => errors.push(error),
+        });
+      });
+      expect(container.querySelector("svg")).toBe(icon);
+      expect(icon?.getAttribute("width")).toBe(
+        String(sizeRecipeForToken("$4", { touch: true }).iconSize),
+      );
+      expect(
+        errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error))),
+      ).toEqual([]);
+    } finally {
+      await act(async () => root?.unmount());
+      spy.mockRestore();
+      container.remove();
+      host.touch = false;
+    }
+  });
+});

package/src/icons/themed.tsx

@@ -1,4 +1,4 @@
-import { isTouchSurface, sizeRecipeForToken } from "@multiplatform.one/theme";
+import { useTouchSurface, sizeRecipeForToken } from "@multiplatform.one/theme";
 import type { FC } from "react";
 import { getVariable, useProps, useTheme } from "tamagui";
 
@@ -9,6 +9,7 @@ import { getVariable, useProps, useTheme } from "tamagui";
  */
 export function themed<A extends FC>(Component: A) {
   return ((props: any) => {
+    const touch = useTouchSurface();
     const { color, disableTheme, size } = useProps(props);
     const theme = useTheme();
     const fromTheme =
@@ -19,11 +20,7 @@ export function themed<A extends FC>(Component: A) {
       <Component
         {...props}
         color={colorValue}
-        size={
-          typeof size === "string"
-            ? sizeRecipeForToken(size, { touch: isTouchSurface() }).iconSize
-            : size
-        }
+        size={typeof size === "string" ? sizeRecipeForToken(size, { touch }).iconSize : size}
       />
     );
   }) as A;

package/src/knobImmuneExports.ts

@@ -35,9 +35,9 @@ export const knobImmuneExports: Readonly<Record<string, string>> = {
   ScrollView: "scroll container lego; no opinionated chrome, fragments ride the content",
   // Separator left the registry 2026-08-28 (MPO-47): bare `Separator` is now
   // a house implementation (./Separator — painted 1px line), so it no longer
-  // qualifies for a row (house implementations ARE the knob story). The
-  // weight-knob question stays an ADJUDICATION-CANDIDATE on the component
-  // header (MPO-21 G10 / G0-clay R9).
+  // qualifies for a row (house implementations ARE the knob story). Its
+  // weight has no knob by ruling (MPO-21 G10-A, 2026-09-26), and Circle and
+  // Square stay knob-immune lego with no per-role radius (MPO-21 R-B).
   // MPO-21 G1 — Fold's substrate. Logic shell only; Accordion (and Fold)
   // own the painted chrome. Restored with the three below after MPO-21 R9 G8
   // (the Adapt drop) rewrote this file from a pre-MPO-21 copy and took them

package/src/layouts/PaneScaffold.spec.tsx

@@ -1,6 +1,6 @@
-import { cleanup, screen } from "@testing-library/react";
+import { cleanup, fireEvent, screen } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { Paragraph, YStack } from "tamagui";
 import {
   FeedLayout,
@@ -8,6 +8,7 @@ import {
   PaneScaffold,
   ReadingWidth,
   SupportingPaneLayout,
+  type PaneScaffoldProps,
 } from "./PaneScaffold";
 import * as Layouts from "./index";
 
@@ -277,3 +278,148 @@ describe("ReadingWidth", () => {
     expect(el).toHaveStyle({ maxWidth: "70ch" });
   });
 });
+
+// MPO-253: the seam runs on one axis. A vertical scaffold docks secondary
+// under primary with the sash, clamps and fraction contract the side-by-side
+// split already has, turned on its side.
+describe("PaneScaffold orientation (MPO-253)", () => {
+  function renderSplit(props: Partial<PaneScaffoldProps> = {}) {
+    renderWithProviders(
+      <PaneScaffold
+        sizeClass="expanded"
+        primary={<Paragraph>Body</Paragraph>}
+        secondary={<Paragraph>Editor</Paragraph>}
+        {...props}
+      />,
+    );
+    return screen.getByTestId("pane-sash");
+  }
+
+  function boundRow(width: number, height: number) {
+    const row = screen.getByTestId("pane-primary").parentElement as HTMLElement;
+    row.getBoundingClientRect = () =>
+      ({
+        x: 0,
+        y: 0,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: height,
+        width,
+        height,
+        toJSON: () => ({}),
+      }) as DOMRect;
+  }
+
+  it("docks secondary under primary behind a horizontal sash", () => {
+    const sash = renderSplit({ orientation: "vertical" });
+    const root = screen.getByTestId("pane-scaffold");
+    expect(root).toHaveAttribute("data-orientation", "vertical");
+    expect(root).toHaveAttribute("data-pane-layout", "split");
+    expect(root).toHaveAttribute("data-sash", "true");
+    expect(sash).toHaveAttribute("aria-orientation", "horizontal");
+    const primary = screen.getByTestId("pane-primary");
+    const secondary = screen.getByTestId("pane-secondary");
+    expect(
+      primary.compareDocumentPosition(secondary) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("keeps the side-by-side sash vertical by default", () => {
+    const sash = renderSplit();
+    expect(screen.getByTestId("pane-scaffold")).toHaveAttribute("data-orientation", "horizontal");
+    expect(sash).toHaveAttribute("aria-orientation", "vertical");
+  });
+
+  it.each([
+    ["horizontal", "ArrowRight", "ArrowLeft"],
+    ["vertical", "ArrowDown", "ArrowUp"],
+  ] as const)("%s: arrows step the fraction along its own axis", (orientation, forward, back) => {
+    const sash = renderSplit({ orientation });
+    expect(sash).toHaveAttribute("aria-valuenow", "50");
+    fireEvent.keyDown(sash, { key: forward });
+    expect(sash).toHaveAttribute("aria-valuenow", "52");
+    fireEvent.keyDown(sash, { key: forward, shiftKey: true });
+    expect(sash).toHaveAttribute("aria-valuenow", "62");
+    fireEvent.keyDown(sash, { key: back });
+    expect(sash).toHaveAttribute("aria-valuenow", "60");
+    fireEvent.keyDown(sash, { key: "Enter" });
+    expect(sash).toHaveAttribute("aria-valuenow", "50");
+  });
+
+  it("vertical ignores the horizontal arrows", () => {
+    const sash = renderSplit({ orientation: "vertical" });
+    fireEvent.keyDown(sash, { key: "ArrowRight" });
+    fireEvent.keyDown(sash, { key: "ArrowLeft" });
+    expect(sash).toHaveAttribute("aria-valuenow", "50");
+  });
+
+  it("vertical honours the clamps: the default is clamped, Home / End land on min / max", () => {
+    const sash = renderSplit({
+      orientation: "vertical",
+      paneFlex: [9, 1],
+      minPaneFraction: 0.3,
+      maxPaneFraction: 0.7,
+    });
+    expect(sash).toHaveAttribute("aria-valuemin", "30");
+    expect(sash).toHaveAttribute("aria-valuemax", "70");
+    expect(sash).toHaveAttribute("aria-valuenow", "70");
+    fireEvent.keyDown(sash, { key: "Home" });
+    expect(sash).toHaveAttribute("aria-valuenow", "30");
+    fireEvent.keyDown(sash, { key: "End" });
+    expect(sash).toHaveAttribute("aria-valuenow", "70");
+  });
+
+  it("vertical is controlled through primaryFraction / onPrimaryFractionChange", () => {
+    const onChange = vi.fn();
+    const sash = renderSplit({
+      orientation: "vertical",
+      primaryFraction: 0.4,
+      onPrimaryFractionChange: onChange,
+    });
+    expect(sash).toHaveAttribute("aria-valuenow", "40");
+    fireEvent.keyDown(sash, { key: "ArrowDown" });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.calls[0][0]).toBeCloseTo(0.42);
+    expect(sash).toHaveAttribute("aria-valuenow", "40");
+  });
+
+  it.each([
+    ["horizontal", { clientX: 200, clientY: 0 }, { clientX: 280, clientY: 0 }],
+    ["vertical", { clientX: 0, clientY: 100 }, { clientX: 0, clientY: 140 }],
+  ] as const)(
+    "%s: dragging the seam moves the fraction by the distance over the row",
+    (orientation, down, move) => {
+      const sash = renderSplit({ orientation });
+      boundRow(800, 400);
+      fireEvent.pointerDown(sash, { button: 0, ...down });
+      fireEvent.pointerMove(window, move);
+      expect(sash).toHaveAttribute("aria-valuenow", "60");
+      fireEvent.pointerUp(window, move);
+      fireEvent.pointerMove(window, { clientX: 0, clientY: 0 });
+      expect(sash).toHaveAttribute("aria-valuenow", "60");
+    },
+  );
+
+  it("vertical stacks like horizontal below the two-pane budget", () => {
+    renderWithProviders(
+      <PaneScaffold
+        sizeClass="compact"
+        orientation="vertical"
+        primary={<Paragraph>Body</Paragraph>}
+        secondary={<Paragraph>Editor</Paragraph>}
+      />,
+    );
+    const root = screen.getByTestId("pane-scaffold");
+    expect(root).toHaveAttribute("data-pane-layout", "stack");
+    expect(root).toHaveAttribute("data-orientation", "vertical");
+    expect(screen.queryByTestId("pane-sash")).not.toBeInTheDocument();
+    expect(screen.getByText("Editor")).toBeInTheDocument();
+  });
+
+  it("vertical keeps the seam on a narrow window when maxPanes ejects", () => {
+    const sash = renderSplit({ orientation: "vertical", sizeClass: "compact", maxPanes: 2 });
+    expect(screen.getByTestId("pane-scaffold")).toHaveAttribute("data-pane-layout", "split");
+    expect(sash).toHaveAttribute("aria-orientation", "horizontal");
+  });
+});

package/src/layouts/PaneScaffold.stories.tsx

@@ -110,7 +110,7 @@ const meta: Meta<typeof PaneScaffold> = {
     docs: {
       description: {
         component:
-          'Adaptive TWO-pane shell (DG-LAY-01/02) — `primary` and `secondary`, no more. Size classes: compact <640, medium ≥640, expanded ≥860 (FloatingPanel), large ≥1024, xl ≥1280. Two panes from expanded up unless `maxPanes` ejects. Side-by-side uses a hairline sash (Linear / VS Code / Polaris Frame); pass `paneGap` to eject to spaced columns. Below expanded the panes stack and the sash goes away, so nothing is hidden on a phone; `narrowLayout="swap"` (what `activePane` opts into) is the list-detail exception. Three regions come from nesting a scaffold inside a pane — see the Nested three-region story; the size class rides down, so the inner scaffold stacks with the outer.',
+          'Adaptive TWO-pane shell (DG-LAY-01/02) — `primary` and `secondary`, no more. Size classes: compact <640, medium ≥640, expanded ≥860 (FloatingPanel), large ≥1024, xl ≥1280. Two panes from expanded up unless `maxPanes` ejects. Side-by-side uses a hairline sash (Linear / VS Code / Polaris Frame); pass `paneGap` to eject to spaced columns. Below expanded the panes stack and the sash goes away, so nothing is hidden on a phone; `narrowLayout="swap"` (what `activePane` opts into) is the list-detail exception. Three regions come from nesting a scaffold inside a pane — see the Nested three-region story; the size class rides down, so the inner scaffold stacks with the outer. `orientation="vertical"` docks `secondary` under `primary` with the same sash turned on its side (↑/↓, Home/End, double-press resets) — see the Docked editor story.',
       },
     },
   },
@@ -119,6 +119,7 @@ const meta: Meta<typeof PaneScaffold> = {
       control: "select",
       options: ["compact", "medium", "expanded", "large", "xl"],
     },
+    orientation: { control: "radio", options: ["horizontal", "vertical"] },
     activePane: { control: "radio", options: ["primary", "secondary"] },
     narrowLayout: { control: "radio", options: ["stack", "swap"] },
     maxPanes: { control: "radio", options: [1, 2, undefined] },
@@ -202,6 +203,37 @@ export const NestedThreeRegion: Story = {
   ),
 };
 
+export const DockedEditor: Story = {
+  name: "Docked editor (vertical)",
+  args: { sizeClass: "xl", orientation: "vertical" },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`orientation="vertical"` runs the seam across the page: the body above, an editor docked below, resized by dragging the seam (↑/↓ from the keyboard, Home/End for the clamps, double-press resets). The body here is itself a horizontal scaffold, which is how a strip editor sits under a multi-pane page. A vertical scaffold splits the height its parent gives it, so the frame is bounded.',
+      },
+    },
+  },
+  render: (args) => (
+    <YStack height={520} padding="$4">
+      <SplitFrame height={480}>
+        <PaneScaffold
+          {...args}
+          paneFlex={[3, 1]}
+          primary={
+            <PaneScaffold
+              paneFlex={[2, 1]}
+              primary={<PaneFill label="Page body" hint="Drag the seam below · ↑/↓ resize" />}
+              secondary={<PaneFill label="Inspector" muted />}
+            />
+          }
+          secondary={<PaneFill label="Editor" hint="Docked under the page" muted />}
+        />
+      </SplitFrame>
+    </YStack>
+  ),
+};
+
 export const CompactActiveSecondary: Story = {
   name: "Compact (swap)",
   args: { sizeClass: "compact", activePane: "secondary" },