Interface TokenThemeProviderProps

The app baseline both modes start from, for the from-scratch case (theming a bare Grid, which has no surfaces of its own). Omit it in the common case — wrap a component that already brings its base + surfaces (Studio, WorkbookElement) and this provider is a pure override layer. Layered low → high as base ⊕ parent-provider ⊕ own, so a nested provider keeps base as a floor under the inherited tokens.

The content to theme. A provider renders no DOM box of its own — when a mode/surface is pinned or the instance is isolated, those are cloned ONTO this child, so in that case it must be a single element that forwards className / DOM attributes to its root (Studio, WorkbookElement, and intrinsic elements all do). In the common case (global, no pinned mode) nothing is injected and children render as-is.

Dark-mode token overrides. Shallow-merged over the base. Own wins.

Isolate this instance in an @scope so its tokens don't collide with another provider on the page. Default false (global) — correct for the common "theme the whole app" case, and it reaches portaled popups for free. Set true for multiple independently-themed instances on one page (note: an isolated provider's overrides don't yet reach a WRAPPED component's own portaled floats — that needs float-layer wiring off useTokenThemeContext).

The @layer the tokens emit into. Default 'sxl-overrides' — the top layer, so overrides win over the app/defaults regardless of specificity. Pass 'sxl-app' to act as an app baseline instead.

Light-mode token overrides. Shallow-merged over the base (parent provider ?? base prop). Own wins.

Pin the mode by stamping data-sxl-theme-mode on this provider's root ('auto' follows the OS / a light|dark class). Omit it in the common case — the wrapped component stamps its own mode, and the mode-keyed overrides follow it via the cascade. Pin it only when the themed content sits on this provider's own root with no inner mode (the from-scratch bare-Grid case).

Stamp data-sxl-theme-surface on the root (e.g. 'grid'). Optional — app is the default surface.

Named surface overrides (e.g. { grid: GRID_SURFACE, header: HEADER_SURFACE }), passed straight to buildThemeCSS. Only for the from-scratch case; a wrapped Studio/WorkbookElement supplies its own. Pass a stable object (it re-emits the sheet when the reference changes).