pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/theme/platform/stateLayer.native.js

@@ -0,0 +1,14 @@
+"use strict";
+
+export const STATE_LAYER_OPACITY = {
+  pressed: 0.1,
+  focus: 0.1,
+  hover: 0.08,
+  dragged: 0.16,
+  disabled: 0.38
+};
+export function stateLayerScrim(mode) {
+  return mode === 'dark' ? '#ffffff' : '#000000';
+}
+export const rippleColor = mode => mode === 'dark' ? 'rgba(255,255,255,0.12)' : 'rgba(0,0,0,0.10)';
+//# sourceMappingURL=stateLayer.native.js.map

package/lib/module/theme/platform/surfaces.native.js

@@ -0,0 +1,11 @@
+"use strict";
+
+export function elevatedSurfaces(palette, mode) {
+  if (mode === 'light') return null;
+  return {
+    elevated1: palette.background[100],
+    elevated2: palette.background[200],
+    elevated3: palette.background[300]
+  };
+}
+//# sourceMappingURL=surfaces.native.js.map

package/lib/module/theme/provider/PixelizeProvider.js

@@ -1,24 +1,14 @@
 "use strict";
 
-import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, palettes, roleColors, DEFAULT_THEME } from "../tokens/index.js";
-import { elevation as renderElevation, fontStyleForWeight, getSystemColorMode, subscribeToSystemColorMode } from "../platform/index.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { HapticsContext, hasHapticsModule } from "../../core/haptics/index.js";
+import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, roleColors, assertPalette } from "../tokens/index.js";
+import { elevation as renderElevation, elevatedSurfaces, fontStyleForWeight, getSystemColorMode, subscribeToSystemColorMode } from "../platform/index.js";
 import { DEFAULT_BRAND_STORAGE_NAMESPACE, DEFAULT_STORAGE_NAMESPACE, isThemeMode, isThemeName, memoryStorageAdapter } from "./colorModeStorage.js";
-
-// A local declaration of RN's build-time global, so this file typechecks without depending on the
-// react-native ambient types being loaded. In a module scope it shadows nothing; RN replaces it.
-
-/**
- * The fully resolved theme for one (brand, resolvedMode): role colours resolved to plain strings,
- * the unitless numeric scale, and the platform-rendered pieces a token cannot hold (RN shadow props,
- * a font-style resolver). This is what `useTheme()` returns; component modules read it, never the
- * raw palette directly.
- */
+import { DEFAULT_THEME, loadPaletteSync } from "./loadPalette.js";
+import { ThemeContext, ThemeModeContext } from "./ThemeContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEFAULT_MODE = 'system';
-
-// Elevation carries no colour-mode variation at the token layer, so every theme shares one rendered
-// map instead of recomputing five shadow styles per brand/mode.
 const RENDERED_ELEVATION = {
   none: renderElevation(elevationTokens.none),
   sm: renderElevation(elevationTokens.sm),
@@ -26,12 +16,13 @@ const RENDERED_ELEVATION = {
   md: renderElevation(elevationTokens.md),
   lg: renderElevation(elevationTokens.lg)
 };
-function buildTheme(brand, mode, interLoaded) {
-  const palette = palettes[brand][mode];
+function buildTheme(brand, mode, interLoaded, paletteOverride) {
+  const palette = paletteOverride ? assertPalette(paletteOverride, "the `palette` prop") : loadPaletteSync(brand, mode);
   return {
     brand,
     mode,
     colors: roleColors(palette),
+    elevatedSurfaces: elevatedSurfaces(palette, mode),
     palette,
     space,
     radii,
@@ -46,18 +37,6 @@ function buildTheme(brand, mode, interLoaded) {
     fontStyleForWeight: weight => fontStyleForWeight(weight, interLoaded)
   };
 }
-
-/**
- * Two contexts, on purpose. `ThemeContext` holds the heavy resolved `Theme`; `ThemeModeContext` holds
- * the small mode-control triple. Both provider values are memoised on their true inputs, so:
- *  - a mode flip recomputes the theme exactly ONCE and re-renders each consumer once, and
- *  - an OS colour change while the mode is pinned (`resolvedMode` unchanged) keeps BOTH values
- *    reference-stable, so it re-renders nobody.
- * Splitting also means a `useThemeMode()` reader isn't invalidated by unrelated theme-object churn
- * and vice versa.
- */
-export const ThemeContext = /*#__PURE__*/createContext(undefined);
-export const ThemeModeContext = /*#__PURE__*/createContext(undefined);
 export function PixelizeProvider({
   children,
   brand: brandProp = DEFAULT_THEME,
@@ -65,28 +44,17 @@ export function PixelizeProvider({
   storage: storageProp,
   storageKey = DEFAULT_STORAGE_NAMESPACE,
   brandStorageKey = DEFAULT_BRAND_STORAGE_NAMESPACE,
-  interLoaded = false
+  interLoaded = false,
+  palette: paletteProp,
+  haptics: hapticsProp
 }) {
   const storage = storageProp ?? memoryStorageAdapter;
   const [modeState, setModeState] = useState(mode);
   const [brandState, setBrandState] = useState(brandProp);
-  // Read the real OS value immediately — native has no hydration step to stay deterministic for.
   const [systemMode, setSystemMode] = useState(getSystemColorMode);
-
-  // Once the user has chosen, a late async rehydrate must not clobber that fresh choice. Brand
-  // gets its own ref: touching one must never block the other's rehydrate.
   const userTouched = useRef(false);
   const userTouchedBrand = useRef(false);
   useEffect(() => subscribeToSystemColorMode(setSystemMode), []);
-
-  // `mode` is intentionally initial-only (a controlled screen drives it through `setMode`, never
-  // by re-passing a prop), but `brand` already shipped as a fully-controlled prop before this
-  // provider owned any brand state — existing call sites (this repo's own example app included)
-  // re-render with a new `brand` value and expect the theme to follow. This keeps that contract
-  // alive on top of the new persisted/`setBrand` state: an unrelenting `brandProp` still drives
-  // `brandState`, but the moment `setBrand` is called even once, the provider is considered the
-  // owner and further `brandProp` changes are ignored — the same "explicit choice wins" rule
-  // `storage` rehydration already follows below.
   useEffect(() => {
     if (userTouchedBrand.current) return;
     setBrandState(brandProp);
@@ -116,9 +84,6 @@ export function PixelizeProvider({
       cancelled = true;
     };
   }, [storage, brandStorageKey]);
-
-  // Write on the explicit action, not in an effect: it only ever persists a real user choice, so a
-  // mount default can't be written over the stored value before the rehydrate above has applied it.
   const setMode = useCallback(next => {
     userTouched.current = true;
     setModeState(next);
@@ -130,7 +95,7 @@ export function PixelizeProvider({
     Promise.resolve(storage.setItem(brandStorageKey, next)).catch(() => {});
   }, [storage, brandStorageKey]);
   const resolvedMode = modeState === 'system' ? systemMode : modeState;
-  const theme = useMemo(() => buildTheme(brandState, resolvedMode, interLoaded), [brandState, resolvedMode, interLoaded]);
+  const theme = useMemo(() => buildTheme(brandState, resolvedMode, interLoaded, paletteProp), [brandState, resolvedMode, interLoaded, paletteProp]);
   const modeValue = useMemo(() => ({
     mode: modeState,
     resolvedMode,
@@ -138,11 +103,15 @@ export function PixelizeProvider({
     brand: brandState,
     setBrand
   }), [modeState, resolvedMode, setMode, brandState, setBrand]);
+  const hapticsEnabled = hapticsProp ?? hasHapticsModule();
   return /*#__PURE__*/_jsx(ThemeContext.Provider, {
     value: theme,
     children: /*#__PURE__*/_jsx(ThemeModeContext.Provider, {
       value: modeValue,
-      children: children
+      children: /*#__PURE__*/_jsx(HapticsContext.Provider, {
+        value: hapticsEnabled,
+        children: children
+      })
     })
   });
 }

package/lib/module/theme/provider/ThemeContext.js

@@ -0,0 +1,6 @@
+"use strict";
+
+import { createContext } from 'react';
+export const ThemeContext = /*#__PURE__*/createContext(undefined);
+export const ThemeModeContext = /*#__PURE__*/createContext(undefined);
+//# sourceMappingURL=ThemeContext.js.map

package/lib/module/theme/provider/colorModeStorage.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { themeNames } from "../tokens/brands/index.js";
+import { THEME_NAMES } from "./loadPalette.js";
 
 /**
  * The user-facing colour-mode selection. `system` follows the OS; `light`/`dark` pin it.
@@ -23,7 +23,7 @@ export function isThemeMode(value) {
 /** Same untrusted-input discipline as `isThemeMode`, checked against the live brand roster so a
  * newly retired/renamed brand can never slip through as a stale stored value. */
 export function isThemeName(value) {
-  return typeof value === 'string' && themeNames.includes(value);
+  return typeof value === 'string' && THEME_NAMES.includes(value);
 }
 
 /**

package/lib/module/theme/provider/index.js

@@ -5,4 +5,5 @@ export { useTheme } from "./useTheme.js";
 export { useThemeColors } from "./useThemeColors.js";
 export { useThemeMode } from "./useThemeMode.js";
 export { createAsyncStorageAdapter, memoryStorageAdapter, isThemeMode, isThemeName, DEFAULT_STORAGE_NAMESPACE, DEFAULT_BRAND_STORAGE_NAMESPACE } from "./colorModeStorage.js";
+export { THEME_NAMES, DEFAULT_THEME, loadPalette, loadPaletteSync } from "./loadPalette.js";
 //# sourceMappingURL=index.js.map

package/lib/module/theme/provider/loadPalette.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/** Brand roster without importing any palette modules. */
+export const THEME_NAMES = ['zinc', 'lavender', 'meadow', 'radiant', 'skyline', 'slate', 'emerald', 'rosewood', 'storefront'];
+export const DEFAULT_THEME = 'zinc';
+const LIGHT_LOADERS = {
+  zinc: () => import('../tokens/brands/zinc/palette.light'),
+  lavender: () => import('../tokens/brands/lavender/palette.light'),
+  meadow: () => import('../tokens/brands/meadow/palette.light'),
+  radiant: () => import('../tokens/brands/radiant/palette.light'),
+  skyline: () => import('../tokens/brands/skyline/palette.light'),
+  slate: () => import('../tokens/brands/slate/palette.light'),
+  emerald: () => import('../tokens/brands/emerald/palette.light'),
+  rosewood: () => import('../tokens/brands/rosewood/palette.light'),
+  storefront: () => import('../tokens/brands/storefront/palette.light')
+};
+const DARK_LOADERS = {
+  zinc: () => import('../tokens/brands/zinc/palette.dark'),
+  lavender: () => import('../tokens/brands/lavender/palette.dark'),
+  meadow: () => import('../tokens/brands/meadow/palette.dark'),
+  radiant: () => import('../tokens/brands/radiant/palette.dark'),
+  skyline: () => import('../tokens/brands/skyline/palette.dark'),
+  slate: () => import('../tokens/brands/slate/palette.dark'),
+  emerald: () => import('../tokens/brands/emerald/palette.dark'),
+  rosewood: () => import('../tokens/brands/rosewood/palette.dark'),
+  storefront: () => import('../tokens/brands/storefront/palette.dark')
+};
+const paletteCache = new Map();
+function cacheKey(brand, mode) {
+  return `${brand}:${mode}`;
+}
+
+/** Loads one brand's palette for the given mode — only that brand's file is fetched. */
+export async function loadPalette(brand, mode) {
+  const key = cacheKey(brand, mode);
+  const cached = paletteCache.get(key);
+  if (cached) return cached;
+  const mod = await (mode === 'light' ? LIGHT_LOADERS[brand]() : DARK_LOADERS[brand]());
+  const palette = mod.default;
+  paletteCache.set(key, palette);
+  return palette;
+}
+const LIGHT_SYNC_LOADERS = {
+  zinc: () => require('../tokens/brands/zinc/palette.light').default,
+  lavender: () => require('../tokens/brands/lavender/palette.light').default,
+  meadow: () => require('../tokens/brands/meadow/palette.light').default,
+  radiant: () => require('../tokens/brands/radiant/palette.light').default,
+  skyline: () => require('../tokens/brands/skyline/palette.light').default,
+  slate: () => require('../tokens/brands/slate/palette.light').default,
+  emerald: () => require('../tokens/brands/emerald/palette.light').default,
+  rosewood: () => require('../tokens/brands/rosewood/palette.light').default,
+  storefront: () => require('../tokens/brands/storefront/palette.light').default
+};
+const DARK_SYNC_LOADERS = {
+  zinc: () => require('../tokens/brands/zinc/palette.dark').default,
+  lavender: () => require('../tokens/brands/lavender/palette.dark').default,
+  meadow: () => require('../tokens/brands/meadow/palette.dark').default,
+  radiant: () => require('../tokens/brands/radiant/palette.dark').default,
+  skyline: () => require('../tokens/brands/skyline/palette.dark').default,
+  slate: () => require('../tokens/brands/slate/palette.dark').default,
+  emerald: () => require('../tokens/brands/emerald/palette.dark').default,
+  rosewood: () => require('../tokens/brands/rosewood/palette.dark').default,
+  storefront: () => require('../tokens/brands/storefront/palette.dark').default
+};
+
+/** Synchronous palette for provider mount — static requires so Metro can bundle the example app. */
+export function loadPaletteSync(brand, mode) {
+  const key = cacheKey(brand, mode);
+  const cached = paletteCache.get(key);
+  if (cached) return cached;
+  const palette = (mode === 'light' ? LIGHT_SYNC_LOADERS[brand] : DARK_SYNC_LOADERS[brand])();
+  paletteCache.set(key, palette);
+  return palette;
+}
+//# sourceMappingURL=loadPalette.js.map

package/lib/module/theme/provider/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/theme/provider/useTheme.js

@@ -1,8 +1,7 @@
 "use strict";
 
 import { useContext } from 'react';
-import { ThemeContext } from "./PixelizeProvider.js";
-/** The full resolved theme: role colours, the numeric scale, and platform-rendered elevation/fonts. */
+import { ThemeContext } from "./ThemeContext.js";
 export function useTheme() {
   const theme = useContext(ThemeContext);
   if (!theme) {

package/lib/module/theme/provider/useThemeMode.js

@@ -1,7 +1,7 @@
 "use strict";
 
 import { useContext } from 'react';
-import { ThemeModeContext } from "./PixelizeProvider.js";
+import { ThemeModeContext } from "./ThemeContext.js";
 /** `{ mode, resolvedMode, setMode }` for a theme switcher. Reads the light mode-control context. */
 export function useThemeMode() {
   const value = useContext(ThemeModeContext);

package/lib/module/theme/tokens/MODULE.md

@@ -1,8 +1,13 @@
-# tokens/ — the copy-paste zone
+# tokens/ — the portable core
 
-The portable core of the design system, **byte-identical with web's `src/Theme/tokens/`** and
-hash-gated by `.tokens.sha256`. The folder layout mirrors web exactly, so the gate can compare
-like-for-like: `types.ts`, `index.ts`, `primitives/`, `brands/`, `builders/`, `roles/`.
+Platform-neutral data and pure functions: `types.ts`, `index.ts`, `primitives/`, `brands/`,
+`builders/`, `roles/`. Web's `src/Theme/tokens/` is the sibling this folder was seeded from and
+still tracks in shape and naming, but the two are **not** byte-identical and no gate requires them
+to be: mobile owns `roles/`, `assertPalette.ts` and its own `PaletteProps`, and web owns sidebar
+tokens mobile has no rail for.
+
+**[THEME-CONTRACT.md](./THEME-CONTRACT.md) is the source of truth** for required vs derived tokens,
+which token to pick by role, and why nothing may write `palette.x?.y ?? z`.
 
 ## Purity contract (lint + `__tests__/purity.test.ts` enforce it)
 
@@ -15,46 +20,45 @@ Nothing under `tokens/` may contain:
 The one subtlety a hex is allowed: `#rrggbb` / `#rrggbbaa` are values, not units — they parse the
 same on web and RN, so translucency uses 8-digit hex.
 
-**Never edit `tokens/` to fix a mobile problem.** If a token is wrong it is wrong on web too — fix
-it on web and re-copy. (Known live example: `brands/slate/palette.light.ts` `table.hover[500]`
-carries a Cyrillic homoglyph copied verbatim from web; it is fixed upstream, not here. No builder
-reads it, so no palette is affected.)
+**A token that is wrong here is fixed here.** Web is a sibling, not an upstream — the drift gate is
+per-repo by design and never reads the other repo. Flag the same defect for web; do not wait for it.
+`brands/slate/palette.light.ts` `table.hover[500]` carried a Cyrillic homoglyph (`"#dfdfе2"`,
+U+0435) on both sides for an unknown period; mobile's copy was fixed 2026-08-31, web's still ships it.
 
-**2026-07-18 — `zinc` dark primary corrected to shadcn's real value.** `PRIMARY_500` in
-`brands/zinc/palette.dark.ts` was `#fafafa` (an approximated "near-white"); verified against
-shadcn's live zinc theme registry and corrected to `#e4e4e7` — shadcn's actual dark `--primary`
-(`#fafafa` is shadcn's `--foreground`, a different token). `gradient.from` now references the
-`PRIMARY_500` constant instead of duplicating the literal, so it can't drift again. Both light
-mode's primary (`#18181b`, already an exact match) and every other zinc role were checked against
-the same registry and left unchanged — see `micro-components/.cursor/modules/theme/MODULE.md` for
-the full verification notes (web is the source of truth for token values).
+`zinc`'s dark `PRIMARY_500` is `#e4e4e7`, shadcn's real dark `--primary`, verified against its live
+theme registry (2026-07-18). `#fafafa` is shadcn's `--foreground` — a different token; do not
+"correct" it back.
 
 ## Brand roster
 
 `brands/` ships 9 identities: `zinc` (mobile-only default, the shadcn look), plus 8 mirroring web —
 `lavender`, `meadow`, `radiant`, `skyline`, `slate`, `emerald`, `rosewood`, `storefront`. Each is a
-`palette.light.ts` (usually `...basePalette` spread + brand overrides — see `emerald`/`storefront` for
-the pattern) and a `palette.dark.ts` (`buildDarkPalette(light)`, no bespoke override unless the brand
-needs one like `zinc`). Add a brand by dropping in both files and registering it in `brands/index.ts`
-+ the `ThemeName` union in `types.ts` — the `it.each(themeNames)` test sweeps pick it up automatically.
+`palette.light.ts` exporting a `BrandPaletteSource` as `source` (usually `...lavenderSource` +
+brand overrides — see `emerald`/`storefront`) and default-exporting `finalizePalette(source)`, plus a
+`palette.dark.ts` (`buildDarkPalette(light)`, no bespoke override unless the brand needs one like
+`zinc`). Add a brand by dropping in both files and registering it in `brands/index.ts`,
+`provider/loadPalette.ts` and the `ThemeName` union — the `it.each(themeNames)` sweeps pick it up.
 
 ## Copied vs not
 
-| Path | Copied to/from web? |
-|------|---------------------|
-| `tokens/**` (this folder) | **Yes** — the hash gate keeps it identical |
+| Path | Shared with web? |
+|------|------------------|
+| `tokens/**` (this folder) | **In shape and intent** — reconcile deliberately, never assume identical |
 | `platform/**` | **Never** — one file per platform, identical export *names*, RN implementations |
 
 `platform/` is where numbers become styles: DP conversion, `StyleSheet.hairlineWidth`, and the
 iOS/Android shadow split. A component imports resolved values from the theme, never from `tokens/`
 math directly.
 
-## The `.tokens.sha256` gate
+## Gates over this folder
 
-CI hashes the contents of `tokens/` and compares against `.tokens.sha256`. A mismatch means web and
-mobile diverged: either an intended change was made on one side (re-copy + regenerate the hash) or an
-accidental edit slipped in (revert it). Because the gate hashes the whole subtree, the **folder shape
-must match web** — a differently-named folder (an old `scale/` or `color/`) can never go green.
+- `__tests__/paletteContrast.test.ts` — 9 brands x 2 modes, 138 assertions: every derived token's
+  contrast guarantee, every colour value parses, no brand file hand-writes a derived token.
+- `roles/__tests__/roleColors.test.ts` — the same sweep one layer up, over `roleColors()`.
+- `__tests__/purity.test.ts` — no unit, CSS string or `platform/` import.
+- `scripts/gates/token-drift.sh` hashes this folder against its **own** committed baseline. That
+  baseline does not exist yet and `pre-pr-check.sh` does not run it, so today it gates nothing —
+  run it with `--update` once, deliberately, if you want it live.
 
 ## RN unit traps baked into the primitives
 

package/lib/module/theme/tokens/THEME-CONTRACT.md

@@ -0,0 +1,137 @@
+# Theme token contract
+
+How colour enters this library, and why nothing may guard a token with `?.` / `??`.
+Read this before adding a token, a brand, or a component that reads a palette.
+
+## The two palette types
+
+| Type | Who writes it | Contains |
+| --- | --- | --- |
+| `BrandPaletteSource` | a brand's `palette.light.ts`, by hand | every hand-authored token, all **required** |
+| `PaletteProps` | `finalizePalette`, at module load | the source **plus** every derived token |
+
+Each `palette.light.ts` annotates `export const source: BrandPaletteSource = { … }` and
+default-exports `finalizePalette(source)`. A missing token is a compile error **in that brand's
+file**. Consumers only ever see `PaletteProps`, where nothing is optional.
+
+Seven brands build on lavender by spreading its `source`, not its finalized default — a brand must
+never inherit another brand's *derived* values.
+
+## Derived tokens — never hand-written
+
+| Token | Derived by | Guarantee |
+| --- | --- | --- |
+| `semanticText.{success,error,warning,info}` | `buildSemanticText` | each status tone as ink, ≥4.5:1 on that palette's canvas |
+| `placeholder[500]` | `finalizePalette` | placeholder ink, ≥4.5:1 on `background[50]` |
+| `table.hover[500]` | `finalizePalette` | hover row steps ≥4.5:1 away from `text[500]` |
+
+Light finalizes in each brand's own file; dark finalizes inside `buildDarkPalette`. `zinc` pins its
+own dark canvas, so `palette.dark.ts` re-finalizes after the override — otherwise its derived tokens
+would be resolved against the canvas it replaced. A hand-copied hex goes stale the moment a canvas
+moves; that is the whole reason these are computed.
+
+`liftToContrast(hex, backdrop, target)` takes no colour-mode argument. It reads the direction from
+the backdrop's own luminance, so "step away from what it sits on" is one rule for both modes and for
+both directions — ink moving off a surface, and a surface moving off ink.
+
+## Tokens with no contrast guarantee
+
+`boxborder`, `border` and `sidebar` are decorative or vestigial. Measured on the canvas,
+`boxborder[500]` is 1.30–2.56:1 in light and 1.84–3.78:1 in dark — it must not be used as a control
+outline. Nothing in this library reads any of the three.
+
+| Need | Use | Never |
+| --- | --- | --- |
+| a control outline (WCAG 1.4.11) | `roleColors().border.interactive` | `boxborder[500]` |
+| status text, icon or border | `palette.semanticText[tone]` | `semantic[tone][500]` — that is the *fill* rung |
+| a status fill | `roleColors().status[role].solid` + `onSolid` | a hand-picked white or black label |
+| accent-coloured text | `roleColors().accent.text` | `primary[500]` — the *filled-control* rung |
+| secondary/muted text | `roleColors().fg.muted` | `gray[400]` — the border/icon rung |
+| a field's placeholder | `roleColors().fg.placeholder` | `fg.muted` — body copy, so empty fields read as filled |
+| a white surface | `background[50]` | `white` — that is ink on a filled control |
+
+`roleColors()` is the supported colour API; the raw palette is available as `useTheme().palette` for
+the few tokens roles do not cover. There is no sidebar rail in this library, so `sidebar` carries a
+background ramp and nothing else — web's `sidebar.active*` / `muted*` / `elevated` tokens are
+deliberately not ported.
+
+## Reading colour
+
+```ts
+const { palette } = useTheme();
+palette.semanticText.error   // guaranteed present
+```
+
+No `?.`, no `??`, no `as unknown as`. `assertPalette` runs once where a palette enters
+(`PixelizeProvider`) and throws naming every missing token. That error is the feature: it is
+visible, it names the fix, and it happens once at the boundary instead of as a wrong colour deep in
+a screen.
+
+## Adding a token
+
+1. Add it to `PaletteProps` in `types.ts`.
+2. Compile. TypeScript names every place that must handle it:
+   - `assertPalette.ts` — `type Unlisted = Exclude<keyof PaletteProps, …>` fails until the token is
+     listed in `REQUIRED_TOKENS`
+   - each brand's `palette.light.ts` — unless the token is derived, in which case exclude it from
+     `BrandPaletteSource` and compute it in `finalizePalette`
+3. Add an assertion of its guarantee to `__tests__/paletteContrast.test.ts`, for **every** brand in
+   **both** modes — no exceptions list.
+
+Adding a brand is the mirror image: one `palette.light.ts` exporting a `BrandPaletteSource`, a
+`palette.dark.ts` calling `buildDarkPalette(light)`, and entries in `brands/index.ts`,
+`provider/loadPalette.ts` and the `ThemeName` union. The `it.each(themeNames)` sweeps pick it up.
+
+## The gate
+
+`__tests__/paletteContrast.test.ts` scores every guarantee above for all 9 brands in both modes —
+138 assertions. It also asserts every colour value in every palette parses, and that no brand file
+writes a derived token by hand.
+
+`slate`'s `table.hover[500]` shipped a Cyrillic `е` (U+0435) inside `"#dfdfе2"` — a valid-looking
+string that RN resolves to no colour at all. It was fixed here on 2026-08-31 and the parse assertion
+is what keeps it fixed. **Web's `slate` palette still carries it.**
+
+## Known gap
+
+The light `semantic` ramps are near-identical across all 9 brands, and their `[500]` rungs measure
+**1.84–3.68:1** against the light canvas — unusable as ink. `semanticText` exists so no call site
+has to know that. Dark needs no such lift (5.05–9.89:1) because `buildDarkPalette` derives the
+status ramps rather than copying them. **Light is the worse mode**: every defect this contract
+resolves was light-only.
+
+## Placeholder ink is not muted text
+
+`fg.muted` is body copy. Six components used it as their `placeholderTextColor`, so an empty field
+read as one already typed into. `fg.placeholder` is the rung the brand authored — `placeholder[500]`
+shipped as-is — with a 3:1 floor underneath it, never a 4.5:1 one.
+
+**The sub-4.5 floor is deliberate.** It was tried the other way first: held to body-text contrast the
+hint stopped reading as a hint, which is the bug this section exists to prevent. 3:1 is the 1.4.11
+non-text floor, and it is what the published web library ships. Lavender light is `#7a72b0` at 4.06:1
+in both libraries; every brand lands between 3.96 and 4.13 in light.
+
+The rung is never darkened when it already clears. The floor exists only for a brand whose authored
+rung is too pale for a surface it lands on — and it does fire here, on `radiant light` and
+`rosewood light`, because of the port boundary below.
+
+### Where mobile's field surfaces differ from web's
+
+| | web `fieldSurfaces` | mobile `FIELD_SURFACES` |
+|---|---|---|
+| canvas | `backgroundColor.main` | `backgroundColor.main` |
+| field fill | `gray[50]`, `background[50]` | `background[50]` |
+| pressed | — | `backgroundColor.muted` (`bg.hover`) |
+
+Mobile is touch: a Select or Combobox trigger showing a placeholder goes to `bg.hover` while pressed,
+with the hint still on screen, so that surface is a real pairing here and not on web. On the two
+brands whose `backgroundColor.muted` is a deep tint this pulls the ink above the authored rung. That
+divergence is correct, not drift — do not "fix" it by deleting the pressed surface.
+
+Disabled fills are excluded on purpose: 1.4.3 exempts them, and folding them in would darken the hint
+on every enabled field.
+
+`roleColors.test.ts` gates both halves: the ink clears 3:1 on every field surface, and it is left
+untouched whenever the authored rung already clears. `surfaceRungs.test.ts` deliberately does **not**
+sweep `placeholder[500]` — what ships is `fg.placeholder`, not the raw rung. Web's mirror of this
+lives in `Theme/CHROME-CONSISTENCY.md`.

package/lib/module/theme/tokens/assertPalette.js

@@ -0,0 +1,29 @@
+"use strict";
+
+const REQUIRED_TOKENS = ["gradient", "primary", "secondary", "tertiary", "transparent", "black", "white", "semantic", "gray", "red", "orange", "yellow", "green", "teal", "blue", "cyan", "purple", "pink", "backgroundColor", "background", "text", "header", "placeholder", "boxShadow", "sidebar", "boxborder", "border", "table", "disabled", "semanticText"];
+
+// Adding a token to PaletteProps without listing it here is a compile error, not a silent gap.
+
+export const allPaletteTokensListed = true;
+const NESTED = [["semantic", ["success", "error", "warning", "info"]], ["backgroundColor", ["main", "base"]], ["gradient", ["from", "to"]], ["semanticText", ["success", "error", "warning", "info"]]];
+export const missingPaletteTokens = palette => {
+  if (!palette || typeof palette !== "object") return ["(no palette object)"];
+  const p = palette;
+  const missing = REQUIRED_TOKENS.filter(k => p[k] === undefined).map(String);
+  for (const [group, keys] of NESTED) {
+    const value = p[group];
+    if (!value) continue;
+    for (const key of keys) if (value[key] === undefined) missing.push(`${group}.${key}`);
+  }
+  return missing;
+};
+
+/** Fails once, loudly, where a palette enters — never as a wrong colour deep in a screen. */
+export const assertPalette = (palette, source) => {
+  const missing = missingPaletteTokens(palette);
+  if (missing.length > 0) {
+    throw new Error(`pixelize-native-library: ${source} is missing ${missing.length} palette token(s): ` + `${missing.join(", ")}. Roles read these directly and have no fallback by design.`);
+  }
+  return palette;
+};
+//# sourceMappingURL=assertPalette.js.map

package/lib/module/theme/tokens/brands/emerald/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#0f9d8a";
 const primary = {
@@ -18,8 +19,8 @@ const primary = {
 };
 
 // No `tertiary` override — emerald inherits lavender's purple tertiary, as web ships it.
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#0f9d8a",
     to: "#06b6d4"
@@ -117,9 +118,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/lavender/palette.light.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import finalizePalette from "../../builders/finalizePalette.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#8B3FC8";
 const SECONDARY_ANCHOR = "#1e0f30";
@@ -341,7 +342,7 @@ const gradient = {
   from: "#8B3FC8",
   to: "#EC4899"
 };
-const palette = {
+export const source = {
   gradient,
   primary,
   secondary,
@@ -372,5 +373,5 @@ const palette = {
   table,
   disabled
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map