@phreshos/react-ui 0.1.8 → 0.1.9

package/README.md

@@ -1,228 +1,69 @@
 # `@phreshos/react-ui`
 
-A React component library for coherent PhreshOS Program interfaces.
+Environment-neutral React components and visual interpretation for PhreshOS.
+The package depends on React and Core contracts, not on either execution SDK.
 
-## Installation
+## Appearance composition
 
-```bash
-bun add @phreshos/react-ui @phreshos/core react react-dom
-```
-
-React UI accepts an explicit `ThemeProperties` snapshot and does not require a
-running PhreshOS environment:
-
-```tsx
-import { standardTheme } from "@phreshos/core"
-import { Button, Flex, ThemeProvider } from "@phreshos/react-ui"
-
-function Example() {
-  return <ThemeProvider theme={standardTheme}>
-    <Flex align="center" gap="small">
-      <Button onPress={() => console.log("save")}>Save</Button>
-    </Flex>
-  </ThemeProvider>
-}
-```
-
-## Package status
-
-This package is one component of a larger architecture that remains under
-active testing. Its public surface is intentionally small and will grow only
-as component contracts are established. It is usable outside a running
-system, though its standard Theme contract comes from `@phreshos/core`.
-
-The library is being built up from behavior contracts rather than from a
-primitive dependency's component catalog. `Button` uses React Aria Components
-for normalized pointer, keyboard, focus, disabled, and pending behavior,
-without exposing that library as the public design language. Components still
-under evaluation may compare React Aria Components against Base UI privately,
-in tests.
-
-The library's future icon language has a tree-shakeable public subpath,
-`@phreshos/react-ui/icons`. That subpath deliberately exports nothing until an
-icon source and its contracts have been selected.
-
-`Grid` and `Flex` are appearance-neutral layout primitives. They preserve
-native element properties, styles, and refs while naming the layout decisions
-that recur throughout an interface:
-
-```tsx
-<Grid columns="repeat(auto-fit, minmax(12rem, 1fr))" gap="1rem">
-  ...
-</Grid>
-
-<Flex align="center" justify="between" gap={12} wrap>
-  ...
-</Flex>
-```
-
-Numeric gaps are expressed in pixels. Grid dimensions may be positive integer
-counts or native CSS track expressions, leaving responsive behavior to CSS
-rather than introducing a second breakpoint system.
-
-Inside a `ThemeProvider`, React UI derives its own spacing levels from the
-Theme's concrete default spacing:
-
-```tsx
-<Flex gap="small">...</Flex>
-<Grid gap="large">...</Grid>
-```
-
-Structures that own native spacing pass the explicit Theme value to React UI's
-general derivation hook:
+React UI receives complete unresolved `Appearance` plus one effective
+`"light" | "dark"` Theme:
 
 ```tsx
-import { useScale } from "@phreshos/react-ui"
-
-const spacing = useScale(theme.spacing)
-
-<section style={{ gap: spacing.large }} />
-```
+import { standardAppearance } from "@phreshos/core"
+import { AppearanceProvider, Button, Surface } from "@phreshos/react-ui"
 
-Explicit values such as `4rem` are used directly — passing them through a
-Theme hook would perform no additional work.
-
-`Surface` keeps a native `<div>` as its public container and gives every
-instance one locally owned pure-SVG material plus only the backdrop layers its
-settings enable. The material uses a deterministic 64×64 micro-pattern derived
-from the former shader grain; it creates no canvas, WebGL context, or shared
-texture:
-
-```tsx
-<Surface className="grid rounded-xl shadow-lg">
-  ...
-</Surface>
-
-<Surface color="strong" grain="large">...</Surface>
-<Surface color="#101114" grain={0.2} backdrop={4} opacity={0.9}>...</Surface>
-<Surface distortion={70} waves={8} ripples={4} saturation={1.4} brightness={1.04}>...</Surface>
+export function Example() {
+  return <AppearanceProvider appearance={standardAppearance} theme="light">
+    <Surface><Button>Continue</Button></Surface>
+  </AppearanceProvider>
+}
 ```
 
-`color` resolves from `Theme.background`; its semantic levels derive from that
-same source and a direct color remains an explicit local override. `grain`,
-`grainAmount`, `backdrop`, `opacity`, `distortion`, `waves`,
-`ripples`, `saturation`, and `brightness` resolve from `Theme.surface`, accept
-their semantic levels or direct values, and remain bounded by Core's Theme
-limits. Radius and foreground remain ordinary Theme styles. Grain intensity
-controls tonal distance while grain amount controls retained cell density.
-Each Surface owns one uniform one-pixel inset edge derived from its resolved
-material color; consumers supply only their radius and do not redraw the edge.
-When either is zero, Surface creates no grain pattern or paths. Refraction and
-native frost use independent backdrop layers so blur does not soften the
-displaced image. Enabled organic, wave, and ripple fields are combined
-mathematically before one displacement pass; each zero-valued field is absent,
-and the filter and refraction layer are absent when all three are zero.
-Backdrop blur emits no CSS function at zero. Neutral saturation and brightness
-at one are also omitted. Animation defaults to zero; only a Surface with
-visible grain and a positive rate joins the internal document clock, while
-every texture and seed remains local to its own Surface.
-
-The Theme stores unrestricted CSS background, foreground, and accent sources.
-React UI derives the fixed `subtle`, `soft`, `base`, `strong`, and `intense`
-treatments from any supplied color, preserving the value exactly at `base`.
-`useColor(value)` memoizes that calculation without implicitly choosing a
-Theme property. CSS performs the nearby mixing in OKLCH, and the System retains
-only the concrete Theme color:
-
-```tsx
-import { useColor } from "@phreshos/react-ui"
-
-const colors = useColor(theme.accent)
-
-<strong style={{ color: colors.strong }} />
-```
+`useAppearance()` returns the unresolved value. `useTheme()` returns only the
+effective mode. `useResolveTheme(themed)` resolves one property at the point
+where it is consumed. Components follow the same rule, so the provider never
+collapses Appearance into a second retained object.
 
-Shape-owning components accept the shared `Radius` value directly. Semantic
-levels are derived from the Theme's concrete radius through the same
-`scale()` rule used for spacing, while numbers and CSS values remain explicit
-overrides:
+An application using the Client SDK composes the packages explicitly:
 
 ```tsx
-<Button radius="large">...</Button>
-<Button radius="2rem">...</Button>
-```
-
-Structures whose native element owns the shape derive from the explicit
-radius value through the same React UI hook:
+const appearance = useSystemAppearance()
+const theme = useSystemTheme()
 
-```tsx
-import { useScale } from "@phreshos/react-ui"
-
-const radius = useScale(theme.radius)
-
-<section style={{ borderRadius: radius.large }} />
+return <AppearanceProvider appearance={appearance} theme={theme}>
+  {children}
+</AppearanceProvider>
 ```
 
-`Button` is the library's first interactive primitive. Its translucent
-control treatment matches the desktop's Start and sign-out controls, letting
-the surrounding Theme material remain visible. It derives spacing and radius
-from the Theme while keeping a single activation path across pointer, Enter,
-and Space input:
+## Levels
 
-```tsx
-<Button onPress={save}>Save</Button>
-<Button size="large" pending>Saving</Button>
-<Button disabled>Unavailable</Button>
-```
+`useScale(value)` and `useColor(value)` derive semantic UI levels from one
+concrete value. They do not select an Appearance property or read an
+environment. Components resolve the property they need first and then derive
+their local level.
 
-Pending Buttons remain focusable but cannot activate. Disabled Buttons leave
-the focus order entirely. The native element defaults to `type="button"`, so
-placing it inside a form never triggers an accidental submission.
+Layout primitives accept native values without a provider. Semantic gaps and
+radii require Appearance because their concrete source is `spacing` or
+`radius`.
 
-`ThemeProvider` accepts a plain `ThemeProperties` snapshot, such as Core's
-`standardTheme`, so the library remains usable without either environment SDK.
-A Program can adapt its
-observable Host value at the application boundary:
+## Surface
 
-```tsx
-import { HostProvider, useHostTheme } from "@phreshos/react"
-import { ThemeProvider } from "@phreshos/react-ui"
+`Surface` is the shared visual material. It accepts native `div` properties
+plus local overrides for color, grain, grain amount, backdrop blur, opacity,
+distortion, waves, ripples, saturation, and brightness. Omitted controls derive
+from the resolved Appearance. A zero-valued optional effect is omitted from the
+rendered material so disabled work costs nothing.
 
-function ThemedApplication({ children }) {
-  const theme = useHostTheme()
+Each Surface owns its SVG material and border. Backdrop refraction and frost
+remain separate compositor layers. Radius and foreground resolve from
+Appearance; elevation stays with the surrounding layout.
 
-  return <ThemeProvider theme={theme}>{children}</ThemeProvider>
-}
-
-<HostProvider provide={["theme"]} fallback={null}>
-  <ThemedApplication>{children}</ThemedApplication>
-</HostProvider>
-```
-
-## Standing requirements
-
-- Components preserve one recognizable visual identity.
-- Props that select a semantic treatment accept only the values documented by
-  that component. Explicit native styles and supported CSS spacing, radius,
-  and color values remain available where the component contract allows them.
-- `ThemeProvider` requires an explicit `theme` prop; it never discovers an
-  environment SDK or silently selects a global theme.
-- The provider applies a replacement `theme` value immediately to its
-  descendants.
-- Providers are scoped and nestable. The nearest `ThemeProvider` supplies the
-  complete theme for its descendants without affecting its parent or
-  siblings.
-- Accessibility, keyboard behavior, focus, and form behavior are contractual.
-- Components must work inside structurally isolated Program iframes.
-- Public types and JSDoc are part of the product.
-
-## Development
-
-```bash
-bun install --frozen-lockfile
-bun run verify
-```
+## Components
 
-`verify` type-checks the source and tests, runs the behavior suite, rebuilds the
-package, packs the publication artifact, installs it into a temporary consumer,
-and checks its runtime, TypeScript, and public subpath entry points.
-
-`Button` is the only interactive component currently exported. Private
-acceptance suites also compare Field, Select, Dialog, and Context Menu
-candidates against the same implementation-independent behaviors; those
-candidates are not part of the package's public surface. Field covers labeling,
-descriptions, validation, native states, and value changes. Select covers
-collections, keyboard input, disabled options, form submission, and cleanup.
-Dialog covers modal semantics, focus, dismissal, nesting, state changes, and
-cleanup. Context Menu covers invocation, focus, actions, disabled items,
-dismissal, and cleanup.
+- `Surface`: shared material container.
+- `Button`: normalized React Aria action with pending and disabled states.
+- `Flex` and `Grid`: small layout primitives that preserve native props.
+- `AppearanceProvider`, `useAppearance`, `useTheme`, `useResolveTheme`:
+  environment-neutral appearance composition.
+- `useScale`, `useColor`, `resolveSpacing`, `resolveRadius`: explicit visual
+  derivation helpers.

package/dist/appearance-provider.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+import type { Appearance, Theme, ThemedValue } from "@phreshos/core";
+/** Provides unresolved Appearance and one effective Theme to a React subtree. */
+export declare function AppearanceProvider({ appearance, children, theme }: AppearanceProviderProps): import("react").JSX.Element;
+/** Returns the complete unresolved Appearance supplied by the nearest provider. */
+export declare function useAppearance(): Appearance;
+/** Returns the effective Theme supplied by the nearest provider. */
+export declare function useTheme(): Theme;
+/** Resolves one themed value only where it is consumed. */
+export declare function useResolveTheme<Value, DarkValue extends Value = never>(value: ThemedValue<Value, DarkValue>): Exclude<Value, undefined>;
+/** Internal optional read for primitives that also accept direct values. */
+export declare function useAppearanceIfAvailable(): Appearance | null;
+export interface AppearanceProviderProps {
+    readonly appearance: Appearance;
+    readonly children: ReactNode;
+    readonly theme: Theme;
+}

package/dist/appearance-provider.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const missing = Symbol("AppearanceProvider");
+const AppearanceContext = createContext(missing);
+const ThemeContext = createContext(missing);
+/** Provides unresolved Appearance and one effective Theme to a React subtree. */
+export function AppearanceProvider({ appearance, children, theme }) {
+    return _jsx(AppearanceContext.Provider, { value: appearance, children: _jsx(ThemeContext.Provider, { value: theme, children: children }) });
+}
+/** Returns the complete unresolved Appearance supplied by the nearest provider. */
+export function useAppearance() {
+    const appearance = useContext(AppearanceContext);
+    if (appearance === missing)
+        throw new Error("useAppearance() requires an AppearanceProvider");
+    return appearance;
+}
+/** Returns the effective Theme supplied by the nearest provider. */
+export function useTheme() {
+    const theme = useContext(ThemeContext);
+    if (theme === missing)
+        throw new Error("useTheme() requires an AppearanceProvider");
+    return theme;
+}
+/** Resolves one themed value only where it is consumed. */
+export function useResolveTheme(value) {
+    const theme = useTheme();
+    return (theme === "dark" && "dark" in value ? value.dark : value.light);
+}
+/** Internal optional read for primitives that also accept direct values. */
+export function useAppearanceIfAvailable() {
+    const appearance = useContext(AppearanceContext);
+    return appearance === missing ? null : appearance;
+}

package/dist/button.d.ts

@@ -15,11 +15,11 @@ export interface ButtonProps extends NativeButtonProps, RadiusProps {
     readonly pending?: boolean;
     /** Runs once for a normalized pointer, Enter, or Space activation. */
     readonly onPress?: () => void;
-    /** Derives the Button's spacing from the Theme's concrete default. */
+    /** Derives the Button's spacing from Appearance's concrete default. */
     readonly size?: ScaleLevel;
     /** Additional native styles that do not replace the Button's identity. */
     readonly style?: CSSProperties;
 }
-/** A Theme-aware action with normalized pointer and keyboard behavior. */
+/** An Appearance-aware action with normalized pointer and keyboard behavior. */
 export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/button.js

@@ -3,12 +3,13 @@ import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
 import { scale } from "./scale.js";
 import { resolveRadius } from "./radius.js";
-import { useTheme } from "./theme-provider.js";
-/** A Theme-aware action with normalized pointer and keyboard behavior. */
+import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+/** An Appearance-aware action with normalized pointer and keyboard behavior. */
 export const Button = forwardRef(function Button({ children, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, type = "button", ...properties }, ref) {
-    const theme = useTheme();
-    const spacing = scale(theme.spacing, size);
-    const borderRadius = resolveRadius(radius, theme);
+    const appearance = useAppearance();
+    const spacing = scale(useResolveTheme(appearance.spacing), size);
+    const borderRadius = resolveRadius(radius, appearance);
+    const foreground = useResolveTheme(appearance.foreground);
     return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
             borderRadius,
             disabled,
@@ -18,7 +19,7 @@ export const Button = forwardRef(function Button({ children, disabled = false, p
             pending,
             size,
             spacing,
-            foreground: theme.foreground,
+            foreground,
             style
         }), children: children });
 });

package/dist/flex.js

@@ -1,17 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { alignment, justification, resolveGap } from "./layout.js";
-import { useThemeIfAvailable } from "./theme-provider.js";
+import { useAppearanceIfAvailable } from "./appearance-provider.js";
 /** A predictable Flexbox container with no visual appearance of its own. */
 export const Flex = forwardRef(function Flex({ align, direction, gap, inline = false, justify, style, wrap, ...properties }, ref) {
-    const theme = useThemeIfAvailable();
+    const appearance = useAppearanceIfAvailable();
     return _jsx("div", { ...properties, ref: ref, style: {
             ...style,
             display: inline ? "inline-flex" : "flex",
             alignItems: alignment(align) ?? style?.alignItems,
             flexDirection: direction ?? style?.flexDirection,
             flexWrap: wrap === undefined ? style?.flexWrap : wrap === "reverse" ? "wrap-reverse" : wrap ? "wrap" : "nowrap",
-            gap: gap === undefined ? style?.gap : resolveGap(gap, theme),
+            gap: gap === undefined ? style?.gap : resolveGap(gap, appearance),
             justifyContent: justification(justify) ?? style?.justifyContent
         } });
 });

package/dist/grid.js

@@ -1,15 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { alignment, justification, resolveGap, tracks } from "./layout.js";
-import { useThemeIfAvailable } from "./theme-provider.js";
+import { useAppearanceIfAvailable } from "./appearance-provider.js";
 /** A predictable CSS Grid container with no visual appearance of its own. */
 export const Grid = forwardRef(function Grid({ align, columns, flow, gap, inline = false, justify, rows, style, ...properties }, ref) {
-    const theme = useThemeIfAvailable();
+    const appearance = useAppearanceIfAvailable();
     return _jsx("div", { ...properties, ref: ref, style: {
             ...style,
             display: inline ? "inline-grid" : "grid",
             alignItems: alignment(align) ?? style?.alignItems,
-            gap: gap === undefined ? style?.gap : resolveGap(gap, theme),
+            gap: gap === undefined ? style?.gap : resolveGap(gap, appearance),
             gridAutoFlow: flow ?? style?.gridAutoFlow,
             gridTemplateColumns: tracks(columns, "columns") ?? style?.gridTemplateColumns,
             gridTemplateRows: tracks(rows, "rows") ?? style?.gridTemplateRows,

package/dist/layout.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import type { ThemeProperties } from "@phreshos/core";
+import type { Appearance } from "@phreshos/core";
 import { type Spacing } from "./spacing.js";
 /** Cross-axis alignment shared by layout containers. */
 export type LayoutAlignment = "start" | "center" | "end" | "stretch" | "baseline";
@@ -10,5 +10,5 @@ export type LayoutGap = Spacing;
 export declare function alignment(value: LayoutAlignment | undefined): CSSProperties["alignItems"] | undefined;
 export declare function justification(value: LayoutJustification | undefined): CSSProperties["justifyContent"] | undefined;
 /** Resolves semantic spacing while preserving explicit CSS gap values. */
-export declare function resolveGap(value: LayoutGap | undefined, theme: ThemeProperties | null): CSSProperties["gap"];
+export declare function resolveGap(value: LayoutGap | undefined, appearance: Appearance | null): CSSProperties["gap"];
 export declare function tracks(value: number | string | undefined, property: "columns" | "rows"): string | undefined;

package/dist/layout.js

@@ -21,8 +21,8 @@ export function justification(value) {
     return value === undefined ? undefined : justifications[value];
 }
 /** Resolves semantic spacing while preserving explicit CSS gap values. */
-export function resolveGap(value, theme) {
-    return resolveSpacing(value, theme);
+export function resolveGap(value, appearance) {
+    return resolveSpacing(value, appearance);
 }
 export function tracks(value, property) {
     if (value === undefined || typeof value === "string")

package/dist/main.d.ts

@@ -4,7 +4,7 @@
  * Components enter this surface only after their implementation-independent
  * behavior contract has been established by the package's tests.
  */
-export { ThemeProvider, useTheme, type ThemeProviderProps } from "./theme-provider.js";
+export { AppearanceProvider, useAppearance, useResolveTheme, useTheme, type AppearanceProviderProps } from "./appearance-provider.js";
 export { Flex, type FlexProps } from "./flex.js";
 export { Grid, type GridProps } from "./grid.js";
 export { Surface, type SurfaceColor, type SurfaceProps } from "./surface.js";

package/dist/main.js

@@ -4,7 +4,7 @@
  * Components enter this surface only after their implementation-independent
  * behavior contract has been established by the package's tests.
  */
-export { ThemeProvider, useTheme } from "./theme-provider.js";
+export { AppearanceProvider, useAppearance, useResolveTheme, useTheme } from "./appearance-provider.js";
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";
 export { Surface } from "./surface.js";

package/dist/radius.d.ts

@@ -1,10 +1,10 @@
 import type { CSSProperties } from "react";
-import type { Shapeable, ThemeProperties } from "@phreshos/core";
+import type { Appearance, Shapeable } from "@phreshos/core";
 import { type ScaleLevel } from "./scale.js";
-/** A Theme-derived level, pixel value, or explicit CSS corner radius. */
+/** An Appearance-derived level, pixel value, or explicit CSS corner radius. */
 export type Radius = ScaleLevel | number | (string & {});
 /** Shared semantic corner-radius capability for React UI components. */
 export interface RadiusProps extends Shapeable<Radius> {
 }
 /** Resolves a Radius while preserving explicit CSS and pixel values. */
-export declare function resolveRadius(value: Radius | undefined, theme: ThemeProperties | null): CSSProperties["borderRadius"];
+export declare function resolveRadius(value: Radius | undefined, appearance: Appearance | null): CSSProperties["borderRadius"];

package/dist/radius.js

@@ -1,9 +1,9 @@
 import { isScaleLevel, scale } from "./scale.js";
 /** Resolves a Radius while preserving explicit CSS and pixel values. */
-export function resolveRadius(value, theme) {
+export function resolveRadius(value, appearance) {
     if (!isScaleLevel(value))
         return value;
-    if (!theme)
-        throw new Error("A semantic radius requires a ThemeProvider");
-    return scale(theme.radius, value);
+    if (!appearance)
+        throw new Error("A semantic radius requires an AppearanceProvider");
+    return scale(appearance.radius.light, value);
 }

package/dist/scale.d.ts

@@ -1,6 +1,6 @@
-/** A visual level derived around one concrete Theme value. */
+/** A visual level derived around one concrete Appearance value. */
 export type ScaleLevel = "xsmall" | "small" | "medium" | "large" | "xlarge";
-/** Every visual level derived around one concrete Theme value. */
+/** Every visual level derived around one concrete Appearance value. */
 export type NumericScale = Readonly<Record<ScaleLevel, number>>;
 /** Returns whether a value names a React UI visual level. */
 export declare function isScaleLevel(value: unknown): value is ScaleLevel;
@@ -10,5 +10,5 @@ export declare function scale(value: number, level: ScaleLevel): number;
 export declare function numericScale(value: number): NumericScale;
 /** Derives a multiplier while preserving its neutral value of one. */
 export declare function scaleMultiplier(value: number, level: ScaleLevel): number;
-/** Returns every visual level derived from one concrete Theme value. */
+/** Returns every visual level derived from one concrete Appearance value. */
 export declare function useScale(value: number): NumericScale;

package/dist/scale.js

@@ -28,7 +28,7 @@ export function numericScale(value) {
 export function scaleMultiplier(value, level) {
     return 1 + (value - 1) * factors[level];
 }
-/** Returns every visual level derived from one concrete Theme value. */
+/** Returns every visual level derived from one concrete Appearance value. */
 export function useScale(value) {
     return useMemo(() => numericScale(value), [value]);
 }

package/dist/spacing.d.ts

@@ -1,8 +1,8 @@
 import type { CSSProperties } from "react";
-import type { ThemeProperties } from "@phreshos/core";
+import type { Appearance } from "@phreshos/core";
 import { type ScaleLevel } from "./scale.js";
-/** A Theme-derived level, pixel value, or explicit CSS spacing value. */
+/** An Appearance-derived level, pixel value, or explicit CSS spacing value. */
 export type Spacing = ScaleLevel | number | (string & {});
 /** Resolves spacing while preserving explicit CSS and pixel values. */
-export declare function resolveSpacing(value: ScaleLevel, theme: ThemeProperties | null): number;
-export declare function resolveSpacing(value: Spacing | undefined, theme: ThemeProperties | null): CSSProperties["gap"];
+export declare function resolveSpacing(value: ScaleLevel, appearance: Appearance | null): number;
+export declare function resolveSpacing(value: Spacing | undefined, appearance: Appearance | null): CSSProperties["gap"];

package/dist/spacing.js

@@ -1,8 +1,8 @@
 import { isScaleLevel, scale } from "./scale.js";
-export function resolveSpacing(value, theme) {
+export function resolveSpacing(value, appearance) {
     if (!isScaleLevel(value))
         return value;
-    if (!theme)
-        throw new Error("Semantic spacing requires a ThemeProvider");
-    return scale(theme.spacing, value);
+    if (!appearance)
+        throw new Error("Semantic spacing requires an AppearanceProvider");
+    return scale(appearance.spacing.light, value);
 }

package/dist/surface.d.ts

@@ -1,51 +1,51 @@
 import type { ComponentPropsWithoutRef } from "react";
 import { type ColorLevel } from "./color.js";
 import { type ScaleLevel } from "./scale.js";
-/** A Theme-derived treatment or direct CSS color. */
+/** An Appearance-derived treatment or direct CSS color. */
 export type SurfaceColor = ColorLevel | (string & {});
 /** Native div properties plus controls for the locally owned material. */
 export type SurfaceProps = Omit<ComponentPropsWithoutRef<"div">, "color" | "opacity"> & Readonly<{
-    /** Theme-derived treatment or direct CSS material color. */
+    /** Appearance-derived treatment or direct CSS material color. */
     color?: SurfaceColor;
-    /** Theme-derived level or direct grain intensity from zero to one. */
+    /** Appearance-derived level or direct grain intensity from zero to one. */
     grain?: ScaleLevel | number;
-    /** Theme-derived level or direct retained grain amount from zero to one. */
+    /** Appearance-derived level or direct retained grain amount from zero to one. */
     grainAmount?: ScaleLevel | number;
-    /** Theme-derived level or direct backdrop blur from zero to 24 CSS pixels. */
+    /** Appearance-derived level or direct backdrop blur from zero to 24 CSS pixels. */
     backdrop?: ScaleLevel | number;
-    /** Theme-derived level or direct material opacity from zero to one. */
+    /** Appearance-derived level or direct material opacity from zero to one. */
     opacity?: ScaleLevel | number;
-    /** Theme-derived level or direct organic displacement from zero to 140 pixels. */
+    /** Appearance-derived level or direct organic displacement from zero to 140 pixels. */
     distortion?: ScaleLevel | number;
-    /** Theme-derived level or direct directional displacement from zero to 40 pixels. */
+    /** Appearance-derived level or direct directional displacement from zero to 40 pixels. */
     waves?: ScaleLevel | number;
-    /** Theme-derived level or direct ripple displacement from zero to 40 pixels. */
+    /** Appearance-derived level or direct ripple displacement from zero to 40 pixels. */
     ripples?: ScaleLevel | number;
-    /** Theme-derived level or direct backdrop saturation multiplier. */
+    /** Appearance-derived level or direct backdrop saturation multiplier. */
     saturation?: ScaleLevel | number;
-    /** Theme-derived level or direct backdrop brightness multiplier. */
+    /** Appearance-derived level or direct backdrop brightness multiplier. */
     brightness?: ScaleLevel | number;
 }>;
 /** Contains content above locally owned Surface material layers. */
-export declare const Surface: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "color" | "opacity"> & Readonly<{
-    /** Theme-derived treatment or direct CSS material color. */
+export declare const Surface: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "opacity" | "color"> & Readonly<{
+    /** Appearance-derived treatment or direct CSS material color. */
     color?: SurfaceColor;
-    /** Theme-derived level or direct grain intensity from zero to one. */
+    /** Appearance-derived level or direct grain intensity from zero to one. */
     grain?: ScaleLevel | number;
-    /** Theme-derived level or direct retained grain amount from zero to one. */
+    /** Appearance-derived level or direct retained grain amount from zero to one. */
     grainAmount?: ScaleLevel | number;
-    /** Theme-derived level or direct backdrop blur from zero to 24 CSS pixels. */
+    /** Appearance-derived level or direct backdrop blur from zero to 24 CSS pixels. */
     backdrop?: ScaleLevel | number;
-    /** Theme-derived level or direct material opacity from zero to one. */
+    /** Appearance-derived level or direct material opacity from zero to one. */
     opacity?: ScaleLevel | number;
-    /** Theme-derived level or direct organic displacement from zero to 140 pixels. */
+    /** Appearance-derived level or direct organic displacement from zero to 140 pixels. */
     distortion?: ScaleLevel | number;
-    /** Theme-derived level or direct directional displacement from zero to 40 pixels. */
+    /** Appearance-derived level or direct directional displacement from zero to 40 pixels. */
     waves?: ScaleLevel | number;
-    /** Theme-derived level or direct ripple displacement from zero to 40 pixels. */
+    /** Appearance-derived level or direct ripple displacement from zero to 40 pixels. */
     ripples?: ScaleLevel | number;
-    /** Theme-derived level or direct backdrop saturation multiplier. */
+    /** Appearance-derived level or direct backdrop saturation multiplier. */
     saturation?: ScaleLevel | number;
-    /** Theme-derived level or direct backdrop brightness multiplier. */
+    /** Appearance-derived level or direct backdrop brightness multiplier. */
     brightness?: ScaleLevel | number;
 }> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/surface.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useCallback, useId, useLayoutEffect, useRef } from "react";
-import { themeLimits } from "@phreshos/core";
+import { appearanceLimits } from "@phreshos/core";
 import { color as deriveColor } from "./color.js";
 import { isScaleLevel, scale, scaleMultiplier } from "./scale.js";
 import { SurfaceMaterial } from "./surface-material.js";
-import { useTheme } from "./theme-provider.js";
+import { useAppearance, useResolveTheme } from "./appearance-provider.js";
 const layerStyle = {
     position: "absolute",
     inset: 0,
@@ -13,7 +13,11 @@ const layerStyle = {
 };
 /** Contains content above locally owned Surface material layers. */
 export const Surface = forwardRef(function Surface({ backdrop, brightness, children, color, distortion, grain, grainAmount, opacity, ripples, saturation, style, waves, ...properties }, forwardedRef) {
-    const theme = useTheme();
+    const appearance = useAppearance();
+    const background = useResolveTheme(appearance.background);
+    const foreground = useResolveTheme(appearance.foreground);
+    const radius = useResolveTheme(appearance.radius);
+    const surface = useResolveTheme(appearance.surface);
     const identity = `phresh-surface-${useId().replaceAll(":", "")}`;
     const element = useRef(null);
     const capture = useCallback((node) => {
@@ -23,17 +27,17 @@ export const Surface = forwardRef(function Surface({ backdrop, brightness, child
         else if (forwardedRef)
             forwardedRef.current = node;
     }, [forwardedRef]);
-    const resolved = resolveSurface({ backdrop, brightness, color, distortion, grain, grainAmount, opacity, ripples, saturation, waves }, theme);
+    const resolved = resolveSurface({ backdrop, brightness, color, distortion, grain, grainAmount, opacity, ripples, saturation, waves }, background, surface);
     useLayoutEffect(() => {
         const surface = element.current;
         if (surface)
             return prepareSurfaceLayout(surface);
     });
     return _jsxs("div", { ...properties, ref: capture, style: {
-            borderRadius: theme.radius,
-            color: theme.foreground,
+            borderRadius: radius,
+            color: foreground,
             ...style
-        }, children: [resolved.refracts && _jsx(BackdropLayer, { name: "refraction", filter: `url("#${identity}-distortion")`, zIndex: -3 }), resolved.frost && _jsx(BackdropLayer, { name: "frost", filter: resolved.frost, zIndex: -2 }), _jsx(SurfaceBorder, { color: resolved.material.color, opacity: resolveScale("large", resolved.material.opacity, themeLimits.surface.opacity) }), _jsx(SurfaceMaterial, { identity: identity, ...resolved.material }), children] });
+        }, children: [resolved.refracts && _jsx(BackdropLayer, { name: "refraction", filter: `url("#${identity}-distortion")`, zIndex: -3 }), resolved.frost && _jsx(BackdropLayer, { name: "frost", filter: resolved.frost, zIndex: -2 }), _jsx(SurfaceBorder, { color: resolved.material.color, opacity: resolveScale("large", resolved.material.opacity, appearanceLimits.surface.opacity) }), _jsx(SurfaceMaterial, { identity: identity, ...resolved.material }), children] });
 });
 /** Draws one uniform inset edge from the same color as the Surface material. */
 function SurfaceBorder({ color, opacity }) {
@@ -55,19 +59,19 @@ function BackdropLayer({ filter, name, zIndex }) {
             WebkitBackdropFilter: filter
         } });
 }
-function resolveSurface(values, theme) {
+function resolveSurface(values, background, surface) {
     const material = {
-        color: resolveColor(values.color, theme.background),
-        distortion: resolveScale(values.distortion, theme.surface.distortion, themeLimits.surface.distortion),
-        grain: resolveScale(values.grain, theme.surface.grain, themeLimits.surface.grain),
-        grainAmount: resolveScale(values.grainAmount, theme.surface.grainAmount, themeLimits.surface.grainAmount),
-        opacity: resolveScale(values.opacity, theme.surface.opacity, themeLimits.surface.opacity),
-        ripples: resolveScale(values.ripples, theme.surface.ripples, themeLimits.surface.ripples),
-        waves: resolveScale(values.waves, theme.surface.waves, themeLimits.surface.waves)
+        color: resolveColor(values.color, background),
+        distortion: resolveScale(values.distortion, surface.distortion, appearanceLimits.surface.distortion),
+        grain: resolveScale(values.grain, surface.grain, appearanceLimits.surface.grain),
+        grainAmount: resolveScale(values.grainAmount, surface.grainAmount, appearanceLimits.surface.grainAmount),
+        opacity: resolveScale(values.opacity, surface.opacity, appearanceLimits.surface.opacity),
+        ripples: resolveScale(values.ripples, surface.ripples, appearanceLimits.surface.ripples),
+        waves: resolveScale(values.waves, surface.waves, appearanceLimits.surface.waves)
     };
-    const backdrop = resolveScale(values.backdrop, theme.surface.backdrop, themeLimits.surface.backdrop);
-    const saturation = resolveMultiplier(values.saturation, theme.surface.saturation, themeLimits.surface.saturation);
-    const brightness = resolveMultiplier(values.brightness, theme.surface.brightness, themeLimits.surface.brightness);
+    const backdrop = resolveScale(values.backdrop, surface.backdrop, appearanceLimits.surface.backdrop);
+    const saturation = resolveMultiplier(values.saturation, surface.saturation, appearanceLimits.surface.saturation);
+    const brightness = resolveMultiplier(values.brightness, surface.brightness, appearanceLimits.surface.brightness);
     const frost = [
         backdrop === 0 ? "" : `blur(${backdrop}px)`,
         saturation === 1 ? "" : `saturate(${saturation})`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -52,7 +52,7 @@
     "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.16",
+    "@phreshos/core": "^0.1.17",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
@@ -61,7 +61,7 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.16",
+    "@phreshos/core": "^0.1.17",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",

package/dist/theme-provider.d.ts

@@ -1,15 +0,0 @@
-import type { ReactNode } from "react";
-import type { ThemeProperties } from "@phreshos/core";
-/** Provides the nearest Theme value to one React subtree. */
-export declare function ThemeProvider({ children, theme }: ThemeProviderProps): import("react").JSX.Element;
-/** Returns the complete snapshot supplied by the nearest ThemeProvider. */
-export declare function useTheme(): ThemeProperties;
-/** Internal optional read used by primitives with both raw and themed values. */
-export declare function useThemeIfAvailable(): ThemeProperties | null;
-/** Properties accepted by ThemeProvider. */
-export interface ThemeProviderProps {
-    /** Content that receives this Theme instead of any outer Theme. */
-    readonly children: ReactNode;
-    /** Complete Theme value for this subtree. */
-    readonly theme: ThemeProperties;
-}

package/dist/theme-provider.js

@@ -1,20 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
-const missing = Symbol("ThemeProvider");
-const ThemeContext = createContext(missing);
-/** Provides the nearest Theme value to one React subtree. */
-export function ThemeProvider({ children, theme }) {
-    return _jsx(ThemeContext.Provider, { value: theme, children: children });
-}
-/** Returns the complete snapshot supplied by the nearest ThemeProvider. */
-export function useTheme() {
-    const properties = useContext(ThemeContext);
-    if (properties === missing)
-        throw new Error("useTheme() requires a ThemeProvider");
-    return properties;
-}
-/** Internal optional read used by primitives with both raw and themed values. */
-export function useThemeIfAvailable() {
-    const properties = useContext(ThemeContext);
-    return properties === missing ? null : properties;
-}