@apollion-dsi/core 5.6.0 → 5.8.0

package/lib/themes/Ground/Ground.helpers.d.ts

@@ -0,0 +1,60 @@
+import type { Theme } from '../ThemeProvider/ThemeProvider.interface';
+/**
+ * Ground channel (APOLLION-DARK-MODE-ENGINE, decision D7 — ADR-024 §ground).
+ *
+ * Every painted ground (`bgColor`, `<Ground>`, the page canvas) emits a set
+ * of CSS custom properties computed **in JS against the ground's literal**
+ * — in both modes (`light-dark()` pairs): the neutral ink hierarchy, the
+ * readable accent inks, the black/white contrast ink and the ink-alpha
+ * edges. Inks consume `var(--apollion-on-ground-…)` with a canvas-resolved
+ * fallback, so the CSS cascade resolves "the nearest painted ancestor" for
+ * free — no React context, no wrappers, works for consumer containers too.
+ *
+ * Contract: every value is AA (4.5) over the ground it was computed for
+ * (disabled excepted); `auditGroundVars` asserts it in tests.
+ */
+/** Prefix of every ground custom property. */
+export declare const GROUND_VAR_PREFIX = "--apollion-on-ground";
+/** Neutral ink roles published per ground. */
+export declare const GROUND_INK_ROLES: readonly ["primary", "secondary", "muted", "disabled"];
+export type GroundInkRole = (typeof GROUND_INK_ROLES)[number];
+/** Token the root ground (page canvas) is computed from. */
+export declare const ROOT_GROUND_TOKEN = "surface.canvas";
+/** Builds a ground custom-property name: `groundVar('ink', 'primary')` → `--apollion-on-ground-ink-primary`. */
+export declare function groundVar(...path: Array<string | number>): string;
+/** `var(--apollion-on-ground-…, fallback)` reference. */
+export declare function groundVarRef(fallback: string, ...path: Array<string | number>): string;
+/**
+ * Maps an ink token to its ground-relative custom property path, or `null`
+ * when the token is not ground-relative (fills, borders, raw colors):
+ * - `ink.<role>`            → `ink-<role>`
+ * - `<palette>` (base)      → `tx-<palette>` (readable accent over the ground)
+ * - `neutral.<120..180>`    → `neutral-<index>` (text side of the ramp)
+ */
+export declare function groundInkPath(token: string): string[] | null;
+/**
+ * A translucent ground (`wash.*`, `rgba(…, 0.2)`, `transparent`) composites
+ * over whatever is behind it — its inks are the PARENT ground's inks. Such
+ * grounds must not publish the channel (the cascade keeps the ancestor's).
+ */
+export declare function isOpaqueGround(literalGround: string): boolean;
+/**
+ * The ground custom properties for `ground` (a `theme.colors` dot-path token
+ * or a runtime CSS color), each side computed on the matching literal table
+ * and paired with `light-dark()`. Pure; memoize at the call site if hot.
+ */
+export declare function groundVars(theme: Theme, ground: string): Record<string, string>;
+/** One failing pair found by {@link auditGroundVars}. */
+export interface GroundAuditFailure {
+    ground: string;
+    mode: 'light' | 'dark';
+    variable: string;
+    ink: string;
+    ratio: number;
+}
+/**
+ * Test helper (D7 guarantee): for every ground token, computes the ground
+ * inks on both literal tables and reports every pair under the floor.
+ * `disabled` and `edge-*` are WCAG-exempt (non-text / disabled) and skipped.
+ */
+export declare function auditGroundVars(theme: Theme, grounds: readonly string[], minRatio?: number): GroundAuditFailure[];

package/lib/themes/Ground/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public barrel for the `Ground` module — the ground channel (D7, ADR-024):
+ * every painted ground publishes `--apollion-on-ground-*` custom properties
+ * computed against its own literal, in both modes.
+ */
+export * from './Ground.helpers';
+export * from './Ground';

package/lib/themes/Ground/index.esm.js

@@ -0,0 +1 @@
+import{a as j}from"../../chunks/chunk-HPM5AX5Z.esm.js";import{a,b,c,d,e,f,g,h,i}from"../../chunks/chunk-JQ66DKSQ.esm.js";import"../../chunks/chunk-YC44Q5HI.esm.js";import"../../chunks/chunk-BFABFZI7.esm.js";import"../../chunks/chunk-U525YXTZ.esm.js";import"../../chunks/chunk-STSRIPD6.esm.js";import"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-AXUWC2WH.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as GROUND_INK_ROLES,a as GROUND_VAR_PREFIX,j as Ground,c as ROOT_GROUND_TOKEN,i as auditGroundVars,f as groundInkPath,d as groundVar,e as groundVarRef,h as groundVars,g as isOpaqueGround};

package/lib/themes/Layout/Layout.interface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Container-size keys of the `theme.containerSizes` scale (ADR-025).
+ *
+ * A SEPARATE scale from the viewport breakpoints on purpose: slot widths are
+ * not viewport widths — reusing `breakpoints.values` would be a category
+ * error (a 480px slot is generous inside a 1280px page and cramped as a
+ * whole phone screen).
+ */
+export type ContainerSizeTypes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Input shape of the container-size scale. */
+export interface ContainerSizesInput {
+    unit: 'px';
+    values: Record<ContainerSizeTypes, number>;
+}
+/** Resolved `theme.containerSizes` surface. */
+export interface ContainerSizesInterface {
+    unit: 'px';
+    values: Record<ContainerSizeTypes, number>;
+    /** `@container (min-width: <value>px)` prelude for the given key — the
+     * container-relative sibling of `theme.breakpoints.up()`. Ascending,
+     * half-open bands, mobile-first: the base style IS the narrow-slot style. */
+    up: (key: ContainerSizeTypes) => string;
+    /** Raw width of a container-size key (number, in `unit`). */
+    width: (key: ContainerSizeTypes) => number;
+}
+/** Input shape of the page-layout constants. */
+export interface LayoutInput {
+    /** Max width of the centered page shell (`pageShell` prop) — previously a
+     * magic `1366` literal inside `ContainerFactory` (ADR-025 §2.3). */
+    pageMaxWidth: number;
+}
+/** Resolved `theme.layout` surface. */
+export type LayoutInterface = LayoutInput;

package/lib/themes/Layout/Layout.props.d.ts

@@ -0,0 +1,18 @@
+import { ContainerSizesInput, ContainerSizesInterface, LayoutInput, LayoutInterface } from './Layout.interface';
+/**
+ * Default container-size scale (ADR-025 §2.2). Calibrated in the S1 spike:
+ * `xs` fits a compact rail card, `sm` the classic sidebar widget, `md` a
+ * half-column panel, `lg` a comfortable article column, `xl` a wide feed.
+ */
+export declare const defaultInputContainerSizes: ContainerSizesInput;
+/** Default page-layout constants (ADR-025 §2.3). */
+export declare const defaultInputLayout: LayoutInput;
+/**
+ * Builds the `theme.containerSizes` surface — the container-relative sibling
+ * of `createBreakpoints`. Only `up()` exists: container queries in the DS are
+ * ascending `min-width` sets by contract (mobile-first; the base style is the
+ * narrow-slot style), so there is no `down()` to misuse.
+ */
+export declare const createContainerSizes: (input: ContainerSizesInput) => ContainerSizesInterface;
+/** Builds the `theme.layout` surface. */
+export declare const createLayout: (input: LayoutInput) => LayoutInterface;

package/lib/themes/Layout/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public barrel for the `Layout` module.
+ *
+ * Any other file in the project should import from the barrel, never from
+ * internal paths like `./Layout.interface` or `./Layout.props`.
+ */
+export * from './Layout.interface';
+export * from './Layout.props';

package/lib/themes/Layout/index.esm.js

@@ -0,0 +1 @@
+import{a,b,c,d}from"../../chunks/chunk-YJHYFCT7.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{c as createContainerSizes,d as createLayout,a as defaultInputContainerSizes,b as defaultInputLayout};

package/lib/themes/Mode/Mode.helpers.d.ts

@@ -0,0 +1,64 @@
+import type { A11yMode, CookieAdapterOptions, ModeDocumentOptions, ModePreference, ModeScriptOptions, ModeStorage, PersistOption, ResolvedMode } from './Mode.interface';
+/**
+ * Mode engine primitives (APOLLION-DARK-MODE-ENGINE, ADR-024) — pure,
+ * dependency-free helpers shared by `ApollionProvider`, the pre-paint script
+ * and server-side recipes (importable from a Next.js `app/layout.tsx`).
+ */
+/** Default storage key of the mode preference; the a11y preset lives under `${key}-a11y`. */
+export declare const MODE_STORAGE_KEY = "apollion-mode";
+/** Default `<html>` attribute carrying the resolved mode. */
+export declare const MODE_ATTRIBUTE = "data-apollion-mode";
+/** Default `<html>` attribute carrying the a11y preset. */
+export declare const A11Y_ATTRIBUTE = "data-apollion-a11y";
+/** `prefers-color-scheme` query the engine follows for `'system'`. */
+export declare const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+/** Storage key of the a11y preset for a given mode key. */
+export declare function a11yStorageKey(storageKey?: string): string;
+/** Type guard — a valid persisted/URL/cookie mode value. */
+export declare function isModePreference(value: unknown): value is ModePreference;
+/** Type guard — a valid a11y preset name. */
+export declare function isA11yMode(value: unknown): value is Exclude<A11yMode, null>;
+/** SSR-safe read of the OS preference (`false` without `window`/`matchMedia`). */
+export declare function prefersDarkScheme(): boolean;
+/** Resolves a preference into the mode that renders. */
+export declare function resolveMode(preference: ModePreference, systemDark: boolean): ResolvedMode;
+/** `localStorage`-backed adapter; silent on private mode / SSR. */
+export declare function localStorageAdapter(): ModeStorage;
+/** Parses a `Cookie` header / `document.cookie` string for one value. */
+export declare function readCookieValue(cookieHeader: string | null | undefined, name: string): string | null;
+/** `document.cookie`-backed adapter — the server can read the same cookie (`readModeFromCookie`). */
+export declare function cookieAdapter(options?: CookieAdapterOptions): ModeStorage;
+/** Maps the provider's `persist` prop to a storage adapter (`null` = off). */
+export declare function resolveStorage(persist: PersistOption | undefined): ModeStorage | null;
+/**
+ * Server-side read of the persisted mode preference from a `Cookie` header
+ * (App Router: `headers().get('cookie')`; Pages Router: `req.headers.cookie`).
+ * Invalid/missing → `null` (the caller falls back to `defaultMode`).
+ */
+export declare function readModeFromCookie(cookieHeader: string | null | undefined, name?: string): ModePreference | null;
+/** Server-side read of the persisted a11y preset (see {@link readModeFromCookie}). */
+export declare function readA11yFromCookie(cookieHeader: string | null | undefined, name?: string): A11yMode;
+/**
+ * Writes the resolved mode + a11y preset on the document element
+ * (`data-apollion-mode`, `data-apollion-a11y`, `style.colorScheme`) so native
+ * controls, scrollbars and `light-dark()` follow the engine. No-op without an element.
+ */
+export declare function syncDocumentMode(element: HTMLElement | null | undefined, state: {
+    mode: ResolvedMode;
+    a11y: A11yMode;
+}, options?: ModeDocumentOptions): void;
+/** Removes what {@link syncDocumentMode} wrote (provider unmount). */
+export declare function clearDocumentMode(element: HTMLElement | null | undefined, options?: ModeDocumentOptions): void;
+/**
+ * Pre-paint inline script (no-flash): reads the persisted preference
+ * (localStorage or cookie), resolves `'system'` through `matchMedia`, and
+ * writes the same attributes the provider will write — before the first
+ * paint, outside React's tree (so hydration never sees a mismatch). Every
+ * option is JSON-escaped; the body is wrapped in `try/catch`.
+ *
+ * @example
+ * ```tsx
+ * <script dangerouslySetInnerHTML={{ __html: getModeScript({ persist: 'cookie' }) }} />
+ * ```
+ */
+export declare function getModeScript(options?: ModeScriptOptions): string;

package/lib/themes/Mode/Mode.interface.d.ts

@@ -0,0 +1,54 @@
+import type { AccessibilityPreset } from '../Colors/Colors.presets';
+/**
+ * What the user asked for: a fixed mode or "follow the operating system".
+ * Persisted as-is (`'system'` stays `'system'`), resolved per render.
+ */
+export type ModePreference = 'light' | 'dark' | 'system';
+/** What actually renders — the preference with `'system'` resolved. */
+export type ResolvedMode = 'light' | 'dark';
+/**
+ * Accessibility axis — orthogonal to the mode (decision D5): any preset
+ * composes with either polarity (`dark` + `colorblind`, `light` +
+ * `high-contrast`, …). `null` = the stock palette.
+ */
+export type A11yMode = AccessibilityPreset | null;
+/**
+ * Minimal storage contract for the mode/a11y preferences. `write(key, null)`
+ * clears the entry. Implementations must never throw (private mode, SSR).
+ */
+export interface ModeStorage {
+    read(key: string): string | null;
+    write(key: string, value: string | null): void;
+}
+/**
+ * Persistence option of the provider: off, the two built-in adapters, or a
+ * custom {@link ModeStorage} (e.g. a server session).
+ */
+export type PersistOption = false | 'localStorage' | 'cookie' | ModeStorage;
+/** Cookie adapter tuning (`cookieAdapter`). */
+export interface CookieAdapterOptions {
+    /** Max-age in seconds. Default: one year. */
+    maxAge?: number;
+    /** Cookie path. Default `'/'`. */
+    path?: string;
+    /** SameSite policy. Default `'Lax'`. */
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    /** Mark the cookie `Secure`. Default: `true` when `sameSite === 'None'`. */
+    secure?: boolean;
+}
+/** Attribute names the engine writes on `<html>` (`syncDocumentMode`). */
+export interface ModeDocumentOptions {
+    /** Resolved-mode attribute. Default `data-apollion-mode`. */
+    attribute?: string;
+    /** A11y-preset attribute. Default `data-apollion-a11y`. */
+    a11yAttribute?: string;
+}
+/** Options of `getModeScript` — the pre-paint `<head>` script (no-flash). */
+export interface ModeScriptOptions extends ModeDocumentOptions {
+    /** Storage key the provider persists under. Default `apollion-mode`. */
+    storageKey?: string;
+    /** Where the preference lives. Default `'localStorage'`. */
+    persist?: 'localStorage' | 'cookie';
+    /** Preference when nothing is stored. Default `'system'`. */
+    defaultMode?: ModePreference;
+}

package/lib/themes/Mode/ModeScript.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { ModeScriptOptions } from './Mode.interface';
+/**
+ * Pre-paint mode script as a `<head>` element — drop it before any stylesheet
+ * so the resolved mode (and the a11y preset) reach `<html>` before the first
+ * paint. Pair it with `ApollionProvider persist` using the same `storageKey`.
+ *
+ * @example
+ * ```tsx
+ * // Next.js App Router — app/layout.tsx
+ * <head><ApollionModeScript persist="cookie" /></head>
+ * ```
+ */
+export declare function ApollionModeScript(props: ModeScriptOptions): React.ReactElement;

package/lib/themes/Mode/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public barrel for the `Mode` module (APOLLION-DARK-MODE-ENGINE, ADR-024).
+ *
+ * Dependency-free: importable from server code (`app/layout.tsx`, loaders)
+ * for `readModeFromCookie` / `getModeScript`.
+ */
+export * from './Mode.interface';
+export * from './Mode.helpers';
+export * from './ModeScript';

package/lib/themes/Mode/index.esm.js

@@ -0,0 +1 @@
+import{a as s}from"../../chunks/chunk-2XTVIQMG.esm.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r}from"../../chunks/chunk-TLIKQFOT.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{c as A11Y_ATTRIBUTE,s as ApollionModeScript,d as DARK_SCHEME_QUERY,b as MODE_ATTRIBUTE,a as MODE_STORAGE_KEY,e as a11yStorageKey,q as clearDocumentMode,l as cookieAdapter,r as getModeScript,g as isA11yMode,f as isModePreference,j as localStorageAdapter,h as prefersDarkScheme,o as readA11yFromCookie,k as readCookieValue,n as readModeFromCookie,i as resolveMode,m as resolveStorage,p as syncDocumentMode};

package/lib/themes/Semantic/Semantic.helpers.d.ts

@@ -1,5 +1,5 @@
-import type { SemanticLayer } from './Semantic.interface';
-import type { ColorsThemeInterface } from '../Colors/Colors.interface';
+import type { SemanticColor, SemanticLayer } from './Semantic.interface';
+import type { ColorsThemeInterface, LadderGroups } from '../Colors/Colors.interface';
 import type { SpacingThemeInterface } from '../Spacing/Spacing.interface';
 /**
  * Subset of the structural `Theme` needed to derive the Semantic layer.
@@ -48,4 +48,11 @@ export interface CreateSemanticInput {
  * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3, §5, §9
  * @see ../../docs/CONCEPTS.md §2 Layer Cake
  */
+/**
+ * Surface-ladder slice of Semantic (ADR-023): `surface.*` pairs + `ink.*` +
+ * `edge.*`, read from the structural groups assembled by `createColors` (or
+ * from an explicit ladder — `invertForSurface` passes the opposite polarity's).
+ * Falls back to the anchors for degenerate inputs (jsdom-unreachable paths).
+ */
+export declare function ladderSemantic(colors: CreateSemanticInput['colors'], ladder?: Pick<LadderGroups, 'surface' | 'ink' | 'edge'>): Pick<SemanticColor, 'surface' | 'ink' | 'edge'>;
 export declare function createSemantic(theme: CreateSemanticInput): SemanticLayer;

package/lib/themes/Semantic/Semantic.interface.d.ts

@@ -86,6 +86,31 @@ export interface SemanticColorBrand {
     second: SemanticBrandTokens;
     third: SemanticBrandTokens;
 }
+/**
+ * Surface ladder as bg/text-on pairs (ADR-023). `txtOn` is `ink.primary`,
+ * AA over every ground of the ladder by construction. Maps to
+ * `theme.colors.surface.*` at the structural level.
+ */
+export interface SemanticColorSurface {
+    canvas: SemanticBgPair;
+    sunken: SemanticBgPair;
+    paper: SemanticBgPair;
+    raised: SemanticBgPair;
+    overlay: SemanticBgPair;
+}
+/** Neutral text hierarchy (ADR-023). Maps to `theme.colors.ink.*`. */
+export interface SemanticColorInk {
+    primary: string;
+    secondary: string;
+    muted: string;
+    disabled: string;
+}
+/** Ink-alpha lines (ADR-023). Maps to `theme.colors.edge.*`. */
+export interface SemanticColorEdge {
+    hairline: string;
+    border: string;
+    strong: string;
+}
 /**
  * Color layer of Semantic.
  */
@@ -93,6 +118,9 @@ export interface SemanticColor {
     feedback: SemanticColorFeedback;
     interface: SemanticColorInterface;
     brand: SemanticColorBrand;
+    surface: SemanticColorSurface;
+    ink: SemanticColorInk;
+    edge: SemanticColorEdge;
 }
 /**
  * Spacing pre-resolved into a CSS string (`'8px'`, `'1rem'`, etc.), generated

package/lib/themes/Semantic/index.esm.js

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-2R6XFFSQ.esm.js";import"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createSemantic};
+import"../../chunks/chunk-IA234JY2.esm.js";import{b as a}from"../../chunks/chunk-6XX3UO2Y.esm.js";import"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createSemantic};

package/lib/themes/Surface/index.esm.js

@@ -1 +1 @@
-import{a as b}from"../../chunks/chunk-7AFAO7ZS.esm.js";import{a}from"../../chunks/chunk-BRXIFPWB.esm.js";import"../../chunks/chunk-3EOSES4S.esm.js";import"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as SurfaceProvider,a as invertForSurface};
+import{a as b}from"../../chunks/chunk-4ZHLV35P.esm.js";import{a}from"../../chunks/chunk-CCONLRLQ.esm.js";import"../../chunks/chunk-6XX3UO2Y.esm.js";import"../../chunks/chunk-PFLBU7HG.esm.js";import"../../chunks/chunk-STSRIPD6.esm.js";import"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-AXUWC2WH.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as SurfaceProvider,a as invertForSurface};

package/lib/themes/ThemeProvider/ThemeProvider.d.ts

@@ -1,16 +1,22 @@
 import React from 'react';
 import { ApollionProviderInterface, ApollionThemeContext } from './ThemeProvider.interface';
 /**
- * Reads the active theme and the current mode (`light`/`dark`), and toggles
- * the mode from within any component under the `ApollionProvider`.
+ * Reads the active theme and the mode engine state, and drives both axes —
+ * `setMode` (light / dark / system) and `setA11y` (grayscale / high-contrast /
+ * colorblind / null) — from within any component under the `ApollionProvider`.
  *
  * @throws when used outside an `ApollionProvider`.
  *
  * @example
  * ```tsx
- * const { themeMode, toggleTheme } = useApollionTheme();
- * <Button text={`Mode: ${themeMode}`} onClick={() => toggleTheme()} />
+ * const { resolvedMode, setMode, a11y, setA11y } = useApollionTheme();
+ * <Button text={`Mode: ${resolvedMode}`} onClick={() => setMode(resolvedMode === 'dark' ? 'light' : 'dark')} />
  * ```
  */
 export declare function useApollionTheme(): ApollionThemeContext;
+/**
+ * Optional variant of {@link useApollionTheme} — `null` outside a provider.
+ * Used by `GlobalStyle` and the ground context, which must also render without one.
+ */
+export declare function useApollionThemeOptional(): ApollionThemeContext | null;
 export declare const ApollionProvider: React.FC<ApollionProviderInterface>;

package/lib/themes/ThemeProvider/ThemeProvider.interface.d.ts

@@ -7,13 +7,25 @@ import { ComponentTokensInput, ComponentTokensLayer } from '../Component';
 import { DeepThemeInterface } from '../Deep';
 import { DepthThemeInterface } from '../Depth';
 import type { Dimension } from '../Dimension';
-import { FontInput, FontThemeInterface } from '../Font';
+import { FontInput, FontThemeInterface, TypeWeight } from '../Font';
 import { FoundationLayer } from '../Foundation';
+import { ContainerSizesInput, ContainerSizesInterface, LayoutInput, LayoutInterface } from '../Layout';
+import type { A11yMode, ModePreference, PersistOption, ResolvedMode } from '../Mode/Mode.interface';
 import { SemanticLayer } from '../Semantic';
 import { SpacingInput, SpacingThemeInterface } from '../Spacing';
 import type { SurfaceMode } from '../Surface';
 export interface ThemeInputsInterface {
     breakpoints?: BreakpointInput;
+    /**
+     * Container-size scale for the `cq` channel (ADR-025) — a separate scale
+     * from the viewport breakpoints (slot widths are not viewport widths).
+     */
+    containerSizes?: ContainerSizesInput;
+    /**
+     * Page-layout constants (ADR-025 §2.3) — e.g. `pageMaxWidth`, the cap the
+     * `pageShell` prop applies (previously a magic `1366`).
+     */
+    layout?: LayoutInput;
     spacing?: SpacingInput;
     colors?: ColorsInput;
     font?: FontInput;
@@ -27,6 +39,13 @@ export interface ThemeInputsInterface {
      * @see ../Dimension/Dimension.props.ts (DIMENSION_MULTIPLIERS calibration)
      */
     dimension?: Dimension;
+    /**
+     * Brand-level origin of the weight ladder (`light` / `regular` /
+     * `stronger`). Resolves `font.fontWeight` from a table instead of asking
+     * the consumer for raw 300/400/… numbers; `regular` is the stock ladder.
+     * Per-call-site `fontWeight` still overrides.
+     */
+    typeWeight?: TypeWeight;
     /**
      * Component token tier overrides (ADR-020). Deep-merged over the
      * defaults — override a single size of a single component without
@@ -42,6 +61,10 @@ export interface ThemeInputsInterface {
 }
 export type Theme = {
     border: BorderInput;
+    /** Container-size scale + `up()` prelude helper for the `cq` channel (ADR-025). */
+    containerSizes: ContainerSizesInterface;
+    /** Page-layout constants (`pageMaxWidth`, ADR-025 §2.3). */
+    layout: LayoutInterface;
     font: FontThemeInterface;
     colors: ColorsThemeInterface;
     breakpoints: BreakpointsInterface;
@@ -82,6 +105,17 @@ export type Theme = {
      * @see ../../docs/adr/ADR-020-component-token-tier.md
      */
     component: ComponentTokensLayer;
+    /**
+     * Mode bridge (ADR-024): the literal light/dark pair behind a projected
+     * theme. Present on every theme the `ApollionProvider` hands out — the
+     * styled tree gets `light-dark()` pairs, `useApollionTheme().theme` gets the
+     * literal of the resolved mode, both tagged with the pair. Engine math
+     * uses `forModes(theme, fn)` to compute on both tables.
+     */
+    modes?: {
+        light: Theme;
+        dark: Theme;
+    };
 };
 export type ThemeMode = 'light' | 'dark';
 export interface ApollionProviderInterface {
@@ -135,23 +169,86 @@ export interface ApollionProviderInterface {
      */
     colors?: ColorsInput;
     /**
-     * When `true` (and the mode is uncontrolled), observes the operating
-     * system's `prefers-color-scheme` to pick the initial `themeMode` and react
-     * to runtime changes. SSR-safe (no-op when there is no `window`).
+     * Mode preference — **controlled**. `'system'` follows `prefers-color-scheme`
+     * (and reacts to runtime changes); `'light'`/`'dark'` pin the mode. When set,
+     * the provider ignores its internal state: the parent is the source of truth
+     * and `setMode` only fires `onModeChange`. Added in 5.7.0 (ADR-024).
+     */
+    mode?: ModePreference;
+    /**
+     * Initial mode preference — **uncontrolled**. Restored from `persist` when a
+     * value is stored. `'system'` = follow the OS.
+     *
+     * @default 'light' (`'system'` when the legacy `useSystemPreference` is on)
+     */
+    defaultMode?: ModePreference;
+    /**
+     * SSR contract: the mode the server rendered with (e.g. from
+     * `readModeFromCookie`). The first client render uses the same value —
+     * hydration never mismatches — and a `'system'` preference is corrected
+     * from `matchMedia` before paint. Without it the client resolves the OS
+     * preference on the first render (fine for client-only apps).
+     */
+    initialMode?: ResolvedMode;
+    /** Fires on every `setMode` with the new **preference** (`'system'` stays `'system'`). */
+    onModeChange?: (mode: ModePreference) => void;
+    /**
+     * Persist the preferences (`mode` under `storageKey`, `a11y` under
+     * `` `${storageKey}-a11y` ``): `'localStorage'`, `'cookie'` (readable by the
+     * server via `readModeFromCookie`), or a custom `ModeStorage` adapter.
+     * Pair with `<ApollionModeScript />` for a no-flash first paint.
      *
      * @default false
      */
+    persist?: PersistOption;
+    /**
+     * Storage key of the mode preference.
+     *
+     * @default 'apollion-mode'
+     */
+    storageKey?: string;
+    /**
+     * Mirror the resolved mode + a11y preset on `<html>` (`data-apollion-mode`,
+     * `data-apollion-a11y`, `style.colorScheme`) so native controls, scrollbars
+     * and `light-dark()` follow the engine. Removed on unmount.
+     *
+     * @default true
+     */
+    syncDocument?: boolean;
+    /**
+     * Attribute name written by `syncDocument` for the resolved mode.
+     *
+     * @default 'data-apollion-mode'
+     */
+    attribute?: string;
+    /**
+     * Accessibility preset — **controlled**. Orthogonal to the mode (D5): the
+     * preset remaps the brand/feedback seeds (`accessibilityPalettes`) and the
+     * engine still derives light + dark from the result, so `dark` +
+     * `colorblind` is a first-class combination. Only applies with `colors`.
+     */
+    a11y?: A11yMode;
+    /**
+     * Initial accessibility preset — **uncontrolled**. Restored from `persist`.
+     *
+     * @default null
+     */
+    defaultA11y?: A11yMode;
+    /** Fires on every `setA11y`. */
+    onA11yChange?: (a11y: A11yMode) => void;
+    /**
+     * @deprecated since 5.7.0 — use `defaultMode="system"` (uncontrolled) or
+     * `mode="system"` (controlled). Still honored: `true` ≡ `defaultMode: 'system'`.
+     */
     useSystemPreference?: boolean;
     /**
-     * Controlled mode. When set, the provider renders this mode and ignores the
-     * internal state and `useSystemPreference` — the source of truth becomes the
-     * parent (e.g. a navbar toggle / `next-themes`). `toggleTheme` then only
-     * fires `onThemeModeChange`, without mutating local state.
+     * @deprecated since 5.7.0 — use `mode` (a controlled preference that also
+     * accepts `'system'`). Still honored as a controlled `'light' | 'dark'`.
      */
     themeMode?: ThemeMode;
     /**
-     * Callback fired by `toggleTheme`. Essential in controlled mode (for the
-     * parent to update its source of truth) and optional in uncontrolled mode.
+     * @deprecated since 5.7.0 — use `onModeChange`. Still fired by `setMode`/
+     * `toggleTheme` with the **resolved** mode.
      */
     onThemeModeChange?: (mode: ThemeMode) => void;
     /**
@@ -188,11 +285,33 @@ export interface ApollionProviderInterface {
      * @see ../Dimension/Dimension.interface.ts
      */
     dimension?: Dimension;
+    /**
+     * Brand-level origin of the weight ladder (`light` / `regular` /
+     * `stronger`). Convenience prop equivalent to `createTheme({ typeWeight })`;
+     * like `dimension`, it only applies when the provider builds the theme.
+     *
+     * @default 'regular' (stock ladder)
+     */
+    typeWeight?: TypeWeight;
     children?: React.ReactNode;
 }
 export interface ApollionThemeContext {
     theme: Theme;
+    /** Current mode preference (`'system'` when following the OS). */
+    mode: ModePreference;
+    /** The mode that renders (preference with `'system'` resolved). */
+    resolvedMode: ResolvedMode;
+    /** Sets the preference; persists it when `persist` is on. */
+    setMode: (mode: ModePreference) => void;
+    /** Current accessibility preset (`null` = stock palette). */
+    a11y: A11yMode;
+    /** Sets the preset; persists it when `persist` is on. */
+    setA11y: (a11y: A11yMode) => void;
+    /** `<html>` attribute carrying the resolved mode (`syncDocument`). */
+    attribute: string;
+    /** @deprecated since 5.7.0 — alias of `resolvedMode`. */
     themeMode: ThemeMode;
+    /** @deprecated since 5.7.0 — use `setMode`. Flips the resolved mode (or sets the given one). */
     toggleTheme: (mode?: ThemeMode) => void;
 }
 export type WithTheme<P> = P & {

package/lib/themes/ThemeProvider/ThemeProvider.modes.d.ts

@@ -0,0 +1,52 @@
+import type { Theme } from './ThemeProvider.interface';
+/**
+ * Mode bridge (APOLLION-DARK-MODE-ENGINE, ADR-024 — spike
+ * `2026-08-22-css-var-mode-bridge`): the styled tree receives ONE theme whose
+ * color leaves are `light-dark(<light>, <dark>)` pairs, so a mode flip is a
+ * `color-scheme` change on `<html>` — zero React re-render, identical class
+ * hashes in both modes, SSR-deterministic. Literal tables stay reachable as
+ * `theme.modes.{light,dark}` for engine math ({@link forModes}).
+ */
+/** The literal light/dark pair behind a projected theme. */
+export interface ThemePair {
+    light: Theme;
+    dark: Theme;
+}
+/** `light-dark(a, b)` — collapsed to the literal when both sides agree (brand stops, runtime colors). */
+export declare function lightDark(light: string, dark: string): string;
+/**
+ * Runs color math on the literal tables of a projected theme and returns the
+ * `light-dark()` pair of the results. On a single (un-projected) theme it is
+ * just `fn(theme)`. Use it anywhere a literal is parsed at render time
+ * (`getContrastColor`, `readableColor`, `HextoRgb`) — those cannot parse a
+ * `light-dark()` string.
+ *
+ * @example
+ * ```ts
+ * color: forModes(theme, (t) => t.colors.getContrastColor(t.colors('primary')));
+ * ```
+ */
+export declare function forModes<T extends string | undefined>(theme: Theme, fn: (literal: Theme) => T): T;
+/**
+ * Projects a literal light/dark pair into the single theme the styled tree
+ * consumes. Only mode-varying color subtrees are paired (`colors`,
+ * `semantic.color`, `foundation.{bg,text,edge}`, `depth`); dimension-driven
+ * subtrees (spacing, font, border, component tokens) are shared by
+ * construction and keep the light references. Pure: a new object, inputs
+ * untouched; `theme.modes` carries the pair.
+ */
+export declare function projectModes(pair: ThemePair): Theme;
+/** A single literal theme tagged with its pair — what `useApollionTheme().theme` hands to JS consumers. */
+export declare function withModes(theme: Theme, pair: ThemePair): Theme;
+/**
+ * Clears the bridge tag so an un-paired (single) theme carries an OWN
+ * `modes: undefined` key. Required because styled-components merges nested
+ * `<ThemeProvider>` themes shallowly (`{ ...outerTheme, ...innerTheme }`):
+ * a single-theme `ApollionProvider` nested under a mode-paired one would
+ * otherwise INHERIT the outer provider's `modes`, and {@link forModes}-based
+ * render math (Button/Link inks) would compute contrast against the outer
+ * seeds instead of the inner theme's — the "dark ink on a custom bg" bug
+ * (ADR-024). Always returns a fresh object with `modes` present-as-undefined
+ * so the shallow merge shadows any inherited pair.
+ */
+export declare function withoutModes(theme: Theme): Theme;