@multiplatform.one/theme 7.45.1 → 7.47.0

package/README.md

@@ -89,6 +89,39 @@ is the same filter as a pure function over a built matrix.
 Full standard: `docs/standards/frontend/knobs-system.md` in the
 [multiplatform.one repo](https://git.corp.bitspur.com/multiplatform.one/mpo).
 
+## Expo launch backgrounds
+
+Expo evaluates app configuration in Node before a React provider exists. Use the
+build-time entry to read the same background tokens as the app's initial preset:
+
+```js
+const { createExpoThemeColors } = require("@multiplatform.one/theme/expo");
+const colors = createExpoThemeColors({ preset: "default" });
+const splash = {
+  image: "./assets/splash.png",
+  resizeMode: "contain",
+  ...colors.splash,
+  dark: { ...colors.splash.dark, image: "./assets/splash.png" },
+};
+```
+
+Pass `splash` to the `expo-splash-screen` plugin, or to both `ios.splash` and
+`android.splash` when using legacy Expo splash configuration. Top-level
+`splash` alone does not configure the iOS dark appearance. Spread
+`colors.adaptiveIcon` into `android.adaptiveIcon`, alongside the foreground image.
+
+Built-in presets are `default`, `bold`, `hero`, `dense` and `roomy`. For custom
+presets, pass `presets: { name: { theme: "themeName" } }` and the actual built
+`themes` table. Each supplied table replaces its default. A blank theme name
+uses `light.background` and `dark.background`; a named theme uses
+`light_themeName.background` and `dark_themeName.background`. Raw strings and
+Tamagui `{ val: string }` tokens are accepted. Unknown presets, missing tokens
+and non-opaque colors fail configuration.
+
+Adaptive icons have one background. `adaptiveIconScheme: "dark"` selects the
+dark token; the default is light. No runtime setting can change these baked-in
+assets: changing tokens or the launch preset requires a new native build.
+
 ## License
 
 Apache-2.0

package/expo.cjs

@@ -0,0 +1,3 @@
+const { createJiti } = require("jiti");
+
+module.exports = createJiti(__filename)("./src/expo.ts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.45.1",
+  "version": "7.47.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/__snapshots__",
+    "expo.cjs",
     "types",
     "!types/.tsbuildinfo"
   ],
@@ -49,32 +50,47 @@
       "types": "./types/audit/designTokens.d.ts",
       "default": "./src/audit/designTokens.ts"
     },
+    "./ramps": {
+      "source": "./src/theme/ramps.ts",
+      "types": "./types/theme/ramps.d.ts",
+      "default": "./src/theme/ramps.ts"
+    },
     "./motion": {
       "source": "./src/theme/motionTiming.ts",
       "types": "./types/theme/motionTiming.d.ts",
       "default": "./src/theme/motionTiming.ts"
+    },
+    "./expo": {
+      "source": "./src/expo.ts",
+      "types": "./types/expo.d.ts",
+      "react-native": "./src/expo.ts",
+      "browser": "./src/expo.ts",
+      "default": "./expo.cjs"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/platform": "^7.45.1",
-    "@multiplatform.one/store": "^7.45.1",
+    "@multiplatform.one/platform": "^7.47.0",
+    "@multiplatform.one/store": "^7.47.0",
     "@tamagui/animations-react-native": "2.7.6",
     "@tamagui/colors": "2.7.6",
     "@tamagui/config": "2.7.6",
     "@tamagui/get-token": "2.7.6",
+    "@tamagui/normalize-css-color": "2.7.6",
     "@tamagui/shorthands": "2.7.6",
     "@tamagui/theme-builder": "2.7.6",
     "@tamagui/themes": "2.7.6",
     "@tamagui/toast": "2.7.6",
     "@tamagui/web": "2.7.6",
+    "jiti": "^2.7.0",
     "react-cookie": "^8.1.2"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "7.45.1",
-    "@multiplatform.one/test-utils": "7.45.1",
+    "@expo/prebuild-config": "55.0.18",
+    "@multiplatform.one/config": "7.47.0",
+    "@multiplatform.one/test-utils": "7.47.0",
     "@tamagui/animations-css": "2.7.6",
     "@tamagui/animations-reanimated": "2.7.6",
     "@tamagui/font-inter": "2.7.6",
@@ -112,6 +128,6 @@
   "scripts": {
     "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html",
     "typecheck": "tsgo --noEmit",
-    "build": "rm -rf types 2>/dev/null && tsc -p tsconfig.build.json"
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/src/audit/constraintAudit.ts

@@ -321,6 +321,7 @@ function reverseMapFontFamily(computed: string): { knob: string; offScale: boole
  * Returns an AuditReport object describing all structural CSS violations.
  */
 export function runConstraintAudit(rootSelector?: string): AuditReport {
+  if (typeof document === "undefined") throw new Error("runConstraintAudit needs a DOM");
   // ── Inline token definitions (must be self-contained for page.evaluate) ──
   // The page's published scale wins; the second argument is the default
   // scale's value, for pages that publish none.
@@ -709,7 +710,7 @@ export function runConstraintAudit(rootSelector?: string): AuditReport {
   const scope = rootSelector ? document.querySelector(rootSelector) : document;
   if (!scope) throw new Error(`Constraint audit scope not found: ${rootSelector}`);
   const allElements = [
-    ...(scope instanceof Element ? [scope] : []),
+    ...(typeof Element !== "undefined" && scope instanceof Element ? [scope] : []),
     ...Array.from(scope.querySelectorAll("*")),
   ];
   const candidates = allElements.filter((el) => {

package/src/audit/themeMatrix.ts

@@ -256,6 +256,7 @@ export interface TextContrastResult {
  * `page.evaluate(captureMatrixSnapshot)`.
  */
 export function captureMatrixSnapshot(): MatrixSnapshot {
+  if (typeof document === "undefined") throw new Error("captureMatrixSnapshot needs a DOM");
   const SKIP_TAGS = new Set([
     "script",
     "style",

package/src/expo.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { createExpoThemeColors } from "./expo";
+import { createThemesBuilder } from "./theme/createThemes";
+import { defaultBaseTheme } from "./theme/defaults/base";
+import { defaultAccentTheme } from "./theme/defaults/accent";
+import { defaultBuilderOptions } from "./theme/defaults/builderOptions";
+import * as presets from "./theme/presets";
+import { normalizeToHex } from "./theme/colorRules";
+
+const themes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes();
+
+describe("Expo theme colors", () => {
+  it.each(["purple", "blue", "orange", "gray"])("supports the app preset hue %s", (theme) => {
+    const result = createExpoThemeColors({ preset: "app", presets: { app: { theme } } });
+    expect(result.splash.backgroundColor).toBe(normalizeToHex(themes[`light_${theme}`].background));
+    expect(result.splash.dark.backgroundColor).toBe(
+      normalizeToHex(themes[`dark_${theme}`].background),
+    );
+  });
+
+  it("rejects an invalid adaptive-icon scheme from JavaScript configs", () => {
+    expect(() =>
+      createExpoThemeColors({
+        adaptiveIconScheme: "system" as "light",
+      }),
+    ).toThrow(/adaptiveIconScheme/);
+  });
+
+  it.each(Object.entries(presets))("resolves both background tokens for %s", (name, preset) => {
+    const presetName = name.replace(/Preset$/, "");
+    const suffix = preset.theme ? `_${preset.theme}` : "";
+    const result = createExpoThemeColors({ preset: presetName });
+    expect(result.splash.backgroundColor).toBe(normalizeToHex(themes[`light${suffix}`].background));
+    expect(result.splash.dark.backgroundColor).toBe(
+      normalizeToHex(themes[`dark${suffix}`].background),
+    );
+    expect(result.adaptiveIcon.backgroundColor).toBe(result.splash.backgroundColor);
+  });
+
+  it("reads changed custom tokens on every call", () => {
+    const custom = {
+      light_brand: { background: "rgb(240, 230, 220)" },
+      dark_brand: { background: { val: "hsl(210, 50%, 20%)" } },
+    };
+    const options = {
+      preset: "brand",
+      presets: { brand: { theme: "brand" } },
+      themes: custom,
+    };
+    expect(createExpoThemeColors(options).splash).toEqual({
+      backgroundColor: "#f0e6dc",
+      dark: { backgroundColor: "#19334d" },
+    });
+    custom.light_brand.background = "#abcdef";
+    expect(createExpoThemeColors(options).splash.backgroundColor).toBe("#abcdef");
+    custom.dark_brand.background.val = "#123456";
+    expect(createExpoThemeColors({ ...options, adaptiveIconScheme: "dark" }).adaptiveIcon).toEqual({
+      backgroundColor: "#123456",
+    });
+  });
+
+  it("rejects an unknown preset or missing scheme instead of baking in a fallback", () => {
+    expect(() => createExpoThemeColors({ preset: "typo" })).toThrow(/preset.*typo/i);
+    expect(() => createExpoThemeColors({ themes: { light: { background: "#fff" } } })).toThrow(
+      /dark.*background/i,
+    );
+  });
+
+  it.each(["transparent", "rgba(1, 2, 3, 0.5)", "var(--background)", "$color2", "#xyz"])(
+    "rejects an unresolved or non-opaque background: %s",
+    (background) => {
+      expect(() =>
+        createExpoThemeColors({
+          themes: { light: { background }, dark: { background: "#000" } },
+        }),
+      ).toThrow(/light.*background/i);
+    },
+  );
+});

package/src/expo.ts

@@ -0,0 +1,57 @@
+import { normalizeCSSColor } from "@tamagui/normalize-css-color";
+import { createThemesBuilder } from "./theme/createThemes";
+import { defaultAccentTheme } from "./theme/defaults/accent";
+import { defaultBaseTheme } from "./theme/defaults/base";
+import { defaultBuilderOptions } from "./theme/defaults/builderOptions";
+import { boldPreset, defaultPreset, densePreset, heroPreset, roomyPreset } from "./theme/presets";
+
+export { createThemesBuilder, defaultBaseTheme, defaultAccentTheme, defaultBuilderOptions };
+
+export interface ExpoThemeColorOptions {
+  preset?: string;
+  presets?: Record<string, { theme: string }>;
+  themes?: Record<string, { background?: string | { val: string } }>;
+  adaptiveIconScheme?: "light" | "dark";
+}
+
+const builtinPresets = {
+  default: defaultPreset,
+  bold: boldPreset,
+  dense: densePreset,
+  hero: heroPreset,
+  roomy: roomyPreset,
+};
+
+export function createExpoThemeColors({
+  preset = "default",
+  presets = builtinPresets,
+  themes = createThemesBuilder(
+    defaultBaseTheme,
+    defaultAccentTheme,
+    defaultBuilderOptions,
+  ).themes(),
+  adaptiveIconScheme = "light",
+}: ExpoThemeColorOptions = {}) {
+  if (adaptiveIconScheme !== "light" && adaptiveIconScheme !== "dark") {
+    throw new Error('Expo adaptiveIconScheme must be "light" or "dark".');
+  }
+  const selected = Object.hasOwn(presets, preset) ? presets[preset] : undefined;
+  if (!selected) throw new Error(`Unknown Expo theme preset "${preset}".`);
+  const suffix = selected.theme ? `_${selected.theme}` : "";
+  const background = (scheme: "light" | "dark") => {
+    const name = `${scheme}${suffix}`;
+    const token = themes[name]?.background;
+    const value = typeof token === "string" ? token : token?.val;
+    const color = typeof value === "string" ? normalizeCSSColor(value) : null;
+    if (color == null || (color & 0xff) !== 0xff) {
+      throw new Error(`Expo theme "${name}" needs an opaque, resolved background token.`);
+    }
+    return `#${(color >>> 8).toString(16).padStart(6, "0")}`;
+  };
+  const light = background("light");
+  const dark = background("dark");
+  return {
+    splash: { backgroundColor: light, dark: { backgroundColor: dark } },
+    adaptiveIcon: { backgroundColor: adaptiveIconScheme === "dark" ? dark : light },
+  };
+}

package/src/expoConfig.spec.ts

@@ -0,0 +1,67 @@
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { runInNewContext } from "node:vm";
+import { describe, expect, it } from "vitest";
+import { createExpoThemeColors } from "./expo";
+
+const require = createRequire(import.meta.url);
+const {
+  getIosSplashConfig,
+} = require("@expo/prebuild-config/build/plugins/unversioned/expo-splash-screen/getIosSplashConfig");
+const {
+  getAndroidSplashConfig,
+  getAndroidDarkSplashConfig,
+} = require("@expo/prebuild-config/build/plugins/unversioned/expo-splash-screen/getAndroidSplashConfig");
+
+it("loads the published CommonJS entry in plain Node without React", () => {
+  const result = JSON.parse(
+    execFileSync(
+      process.execPath,
+      [
+        "-e",
+        `
+    const { createExpoThemeColors } = require("@multiplatform.one/theme/expo");
+    const colors = createExpoThemeColors();
+    const runtime = Object.keys(require.cache).filter(path =>
+      /node_modules\\/(react|react-native|tamagui|@tamagui\\/web)\\//.test(path));
+    process.stdout.write(JSON.stringify({ colors, runtime }));
+  `,
+      ],
+      { cwd: resolve(__dirname, ".."), encoding: "utf8" },
+    ),
+  );
+  expect(result.colors).toEqual(createExpoThemeColors());
+  expect(result.runtime).toEqual([]);
+});
+
+describe.each(["one", "storybook-expo"])("%s Expo config", (app) => {
+  it("passes light/dark tokens and the original image to native prebuild", () => {
+    const filename = resolve(__dirname, "../../../apps", app, "app.config.js");
+    const appRequire = createRequire(filename);
+    const module = { exports: {} as { expo: Record<string, any> } };
+    runInNewContext(readFileSync(filename, "utf8"), {
+      module,
+      __dirname: resolve(filename, ".."),
+      process: { env: {} },
+      require: (name: string) => (name === "dotenv" ? { config() {} } : appRequire(name)),
+    });
+    const { expo } = module.exports;
+    const colors = createExpoThemeColors();
+    const ios = getIosSplashConfig(expo);
+    const android = getAndroidSplashConfig(expo);
+    const androidDark = getAndroidDarkSplashConfig(expo);
+    expect(ios.backgroundColor).toBe(colors.splash.backgroundColor);
+    expect(ios.dark.backgroundColor).toBe(colors.splash.dark.backgroundColor);
+    expect(android.backgroundColor).toBe(colors.splash.backgroundColor);
+    expect(androidDark.backgroundColor).toBe(colors.splash.dark.backgroundColor);
+    expect(ios.image).toBe("./assets/splash.png");
+    expect(android.image).toBe(ios.image);
+    expect(androidDark.image).toBe(ios.image);
+    expect(expo.android.adaptiveIcon).toEqual({
+      foregroundImage: "./assets/adaptive-icon.png",
+      ...colors.adaptiveIcon,
+    });
+  });
+});

package/src/figma/figmaTokens.spec.ts

@@ -6,6 +6,7 @@ import { normalizeToHex } from "../theme/colorRules";
 import { defaultAccentTheme } from "../theme/defaults/accent";
 import { defaultBaseTheme } from "../theme/defaults/base";
 import { interTrackingPx } from "../theme/defaults/fonts";
+import { hairlineBorderWidth } from "../theme/hairline";
 import { FIGMA_THEME_MODES, buildFigmaTokens, figmaTokenName } from "./figmaTokens";
 
 const fontFamilies = {
@@ -148,9 +149,9 @@ describe("buildFigmaTokens", () => {
       expect(result.sizing["space-1-5"]).toBe((tokens.space as Record<string, number>)["$1.5"]);
     });
 
-    it("exports knob-shaped borderWidth values including the 0.5 hairline", () => {
+    it("exports knob-shaped borderWidth values with the web hairline token (LC-148)", () => {
       expect(result.sizing["borderWidth-none"]).toBe(0);
-      expect(result.sizing["borderWidth-small"]).toBe(0.5);
+      expect(result.sizing["borderWidth-small"]).toBe(hairlineBorderWidth);
       expect(result.sizing["borderWidth-medium"]).toBe(1);
       expect(result.sizing["borderWidth-large"]).toBe(2);
     });
@@ -174,7 +175,7 @@ describe("buildFigmaTokens", () => {
     it("exports borderWidth knob modes", () => {
       expect(result.knobs.borderWidth.modes).toEqual({
         none: 0,
-        small: 0.5,
+        small: hairlineBorderWidth,
         medium: 1,
         large: 2,
       });

package/src/theme/FontKnobStyles.tsx

@@ -76,14 +76,26 @@ export interface FontScopeTables {
  * `--f-family` — live SHC console had the style tag and skipped the family).
  */
 export function getConfiguredFontFamily(category: FontCategory): string | undefined {
+  return resolveFontTokenFamily(`$${category}`);
+}
+
+/**
+ * The family stack a resolved font token names in the Tamagui config, for
+ * text no Tamagui font reaches: `resolveFontTokenFamily(knobProps.body.fontFamily)`
+ * hands a mermaid diagram's SVG labels the face the bodyFont knob picked.
+ * Undefined outside a configured runtime or for a token the config lacks.
+ */
+export function resolveFontTokenFamily(token: unknown): string | undefined {
+  if (typeof token !== "string" || !token) return undefined;
   let config: ReturnType<typeof getConfig> | undefined;
   try {
     config = getConfig();
   } catch {
     return undefined;
   }
+  const key = token.startsWith("$") ? token.slice(1) : token;
   const fontsParsed = (config as { fontsParsed?: Record<string, unknown> }).fontsParsed;
-  const font = (fontsParsed?.[`$${category}`] ?? config.fonts?.[category]) as
+  const font = (fontsParsed?.[`$${key}`] ?? config.fonts?.[key]) as
     | { family?: string | { val?: string } }
     | undefined;
   const family = font?.family;

package/src/theme/Heading.tsx

@@ -0,0 +1,70 @@
+/**
+ * Every heading takes headingFont on every platform. Regular keeps the heading
+ * weight table; bold writes 700. Consumer weight wins and rides last.
+ * H1 alone takes pageTitle: moderate $10 (40 px), display $12 (52 px), one
+ * token less below $sm (LC-143).
+ */
+import { useResolvedKnobs } from "./useResolvedKnobs";
+import {
+  H1 as RawH1,
+  H2 as RawH2,
+  H3 as RawH3,
+  H4 as RawH4,
+  H5 as RawH5,
+  H6 as RawH6,
+  Heading as RawHeading,
+  type HeadingProps,
+} from "tamagui";
+
+export type { HeadingProps };
+
+type Weight = HeadingProps["fontWeight"];
+
+function useHeadingVoice(fontWeight: Weight) {
+  const { knobProps } = useResolvedKnobs();
+  const { fontWeight: knobWeight, ...heading } = knobProps.heading;
+  const resolvedWeight = fontWeight ?? (knobWeight as Weight);
+  return {
+    heading,
+    pageTitle: knobProps.pageTitle,
+    weight: resolvedWeight === undefined ? {} : { fontWeight: resolvedWeight },
+  };
+}
+
+export function Heading({ fontWeight, ...props }: HeadingProps) {
+  const { heading, weight } = useHeadingVoice(fontWeight);
+  return <RawHeading {...heading} {...props} {...weight} />;
+}
+
+export function H1({ fontWeight, ...props }: HeadingProps) {
+  const { heading, pageTitle, weight } = useHeadingVoice(fontWeight);
+  // An explicit size ejects the whole step. Spread anyway, the knob's compact
+  // `$max-sm` entry would still override that size on a phone.
+  const step = props.size === undefined ? pageTitle : null;
+  return <RawH1 {...step} {...heading} {...props} {...weight} />;
+}
+
+export function H2({ fontWeight, ...props }: HeadingProps) {
+  const { heading, weight } = useHeadingVoice(fontWeight);
+  return <RawH2 {...heading} {...props} {...weight} />;
+}
+
+export function H3({ fontWeight, ...props }: HeadingProps) {
+  const { heading, weight } = useHeadingVoice(fontWeight);
+  return <RawH3 {...heading} {...props} {...weight} />;
+}
+
+export function H4({ fontWeight, ...props }: HeadingProps) {
+  const { heading, weight } = useHeadingVoice(fontWeight);
+  return <RawH4 {...heading} {...props} {...weight} />;
+}
+
+export function H5({ fontWeight, ...props }: HeadingProps) {
+  const { heading, weight } = useHeadingVoice(fontWeight);
+  return <RawH5 {...heading} {...props} {...weight} />;
+}
+
+export function H6({ fontWeight, ...props }: HeadingProps) {
+  const { heading, weight } = useHeadingVoice(fontWeight);
+  return <RawH6 {...heading} {...props} {...weight} />;
+}

package/src/theme/Intent.stories.tsx

@@ -1,6 +1,7 @@
-import { SizableText, XStack, YStack } from "tamagui";
+import { XStack, YStack } from "tamagui";
 import { Intent, type IntentProps } from "./Intent";
 import { useIntentContext, useResolvedKnobs } from "./useResolvedKnobs";
+import { SizableText } from "./Text";
 
 export default {
   title: "Theme/Intent",
@@ -31,7 +32,6 @@ function Probe({ label }: { label: string }) {
       {...knobProps.surface}
       {...knobProps.borderRadius}
       backgroundColor={knobProps.outlined ? "transparent" : "$background"}
-      borderColor="$borderColor"
       padding="$3"
       minWidth={140}
       testID={`intent-probe-${label}`}

package/src/theme/Preset.stories.tsx

@@ -1,6 +1,7 @@
-import { SizableText, XStack, YStack } from "tamagui";
+import { XStack, YStack } from "tamagui";
 import { Preset } from "./Preset";
 import { useResolvedKnobs } from "./useResolvedKnobs";
+import { SizableText } from "./Text";
 
 export default {
   title: "Theme/Preset",
@@ -28,7 +29,6 @@ function Probe({ label }: { label: string }) {
       {...knobProps.surface}
       {...knobProps.borderRadius}
       backgroundColor={knobProps.outlined ? "transparent" : "$background"}
-      borderColor="$borderColor"
       elevation={knobProps.elevation}
       padding="$3"
       minWidth={160}

package/src/theme/Preset.tsx

@@ -114,9 +114,11 @@ export function Preset({
   let element = <PresetContext.Provider value={ctxValue}>{children}</PresetContext.Provider>;
 
   // An explicit colour wraps in its Tamagui theme; `""` re-applies the preset's own.
+  // A Preset that takes `theme` keeps the wrapper even while it names nothing:
+  // adding it when a colour is picked re-parents the subtree and remounts it.
   const wrap = theme ? theme : theme === "" ? ctxValue.preset.theme : undefined;
-  if (wrap) {
-    element = <TamaguiTheme name={wrap}>{element}</TamaguiTheme>;
+  if (theme !== undefined) {
+    element = <TamaguiTheme name={wrap || undefined}>{element}</TamaguiTheme>;
   }
 
   return element;

package/src/theme/Surface.stories.tsx

@@ -1,6 +1,7 @@
-import { SizableText, XStack, YStack } from "tamagui";
+import { XStack, YStack } from "tamagui";
 import { Surface } from "./Surface";
 import { useResolvedKnobs } from "./useResolvedKnobs";
+import { SizableText } from "./Text";
 
 export default {
   title: "Theme/Surface",

package/src/theme/Surface.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import { createStyledContext, type SizeTokens } from "tamagui";
+import { PageGutter } from "./pageGutter";
 import { SIZE_KEYS } from "./scale/scaleInputs";
 
 /** A Tamagui size key ("$3", "$true") or `unset` for no ceiling. */
@@ -92,7 +93,8 @@ export function clampSurfaceSize(requested: SurfaceSize, parent: SurfaceSize): S
  * Forwards a size token to a subtree: every knob reader under it renders its
  * controls at `size` unless it asks for a smaller one (LC-78 ceiling).
  * `painted` marks (true) or resets (false) the painted-ancestor flag; omitted
- * inherits it.
+ * inherits it. Either way a painted value opens a new surface with its own
+ * inset, so the page gutter does not reach inside it (LC-146).
  *
  * @example A table cell's editors at the row's control height
  * <Surface size="$3">{cell}</Surface>
@@ -111,7 +113,7 @@ export function Surface({
   const nextPainted = painted ?? parent.painted ?? false;
   return (
     <SurfaceContext.Provider size={nextSize} painted={nextPainted}>
-      {children}
+      {painted === undefined ? children : <PageGutter inset={null}>{children}</PageGutter>}
     </SurfaceContext.Provider>
   );
 }