From da08cc9a5c2bc9ae9b7d162c388358d208a14444 Mon Sep 17 00:00:00 2001
From: Exoridus <github@codexo.de>
Date: Thu, 27 Aug 2026 21:23:27 +0200
Subject: [PATCH 1/6] feat(ui): give UI style values a skin-shaped theme type

A theme is a skin, not a colour table: per role and per state it carries a
background descriptor, a text style and insets. Insets are layout input,
which is why a later style setter has to invalidate layout as well as paint.

The background descriptor covers what the widgets draw today (a rounded
fill with an optional border) and the nine-slice case the texture-based
widget suite needs, so the value type does not have to change again when
skins become textured.

`defaultUITheme` reproduces the widgets' current look exactly and is frozen
in development builds, so a caller who mutates a shared skin fails at the
write instead of silently restyling every widget that inherited it.
---
 src/ui/theme.ts       | 225 ++++++++++++++++++++++++++++++++++++++++++
 test/ui/theme.test.ts |  73 ++++++++++++++
 2 files changed, 298 insertions(+)
 create mode 100644 src/ui/theme.ts
 create mode 100644 test/ui/theme.test.ts

diff --git a/src/ui/theme.ts b/src/ui/theme.ts
new file mode 100644
index 000000000..b12f3b5ab
--- /dev/null
+++ b/src/ui/theme.ts
@@ -0,0 +1,225 @@
+import { Color } from '#core/Color';
+import type { NineSliceInsets, NineSliceModes } from '#rendering/sprite/nineSlice';
+import type { TextStyleOptions } from '#rendering/text/TextStyle';
+import type { Texture } from '#rendering/texture/Texture';
+import type { TextureRegion } from '#rendering/texture/TextureRegion';
+
+/**
+ * Per-edge pixel insets. A skin's insets are layout input, not decoration: they
+ * describe the content box a widget positions its content in, so changing them
+ * re-lays out the widget rather than only repainting it.
+ */
+export interface UIInsets {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/**
+ * Visual state a widget paints in. A widget that tracks no interaction stays on
+ * `'normal'`; states a skin set leaves undefined fall back to `'normal'`.
+ */
+export type UIWidgetState = 'normal' | 'hover' | 'pressed' | 'disabled' | 'focused';
+
+/** Widget surface that paints nothing - the whole node is its content. */
+export interface UINoBackground {
+  readonly kind: 'none';
+}
+
+/** Vector background: a rounded rectangle with an optional stroked border. */
+export interface UIFillBackground {
+  readonly kind: 'fill';
+  readonly color: Color;
+  readonly borderColor: Color;
+  /** Border thickness in pixels; `0` draws no border. */
+  readonly borderWidth: number;
+  /** Corner radius in pixels, clamped to half the widget's smaller side. */
+  readonly cornerRadius: number;
+}
+
+/**
+ * Textured background drawn as a nine-slice, so corners stay pixel-perfect
+ * while edges and center fill the widget's layout size.
+ */
+export interface UINineSliceBackground {
+  readonly kind: 'nineSlice';
+  readonly texture: Texture | TextureRegion;
+  /** Source-texture slice widths, in texels. */
+  readonly slices: number | Partial<NineSliceInsets>;
+  /** Destination border widths; defaults to `slices` (1:1 corners). */
+  readonly border?: number | Partial<NineSliceInsets>;
+  readonly modes?: NineSliceModes;
+}
+
+/** How a widget paints its body. */
+export type UIBackground = UINoBackground | UIFillBackground | UINineSliceBackground;
+
+/**
+ * The look of one widget surface in one state: what it paints, how its text is
+ * styled, and the content box its layout works against.
+ */
+export interface UISkin {
+  readonly background: UIBackground;
+  readonly text: TextStyleOptions;
+  readonly insets: UIInsets;
+}
+
+/**
+ * One skin per state. Only `normal` is required - {@link resolveUISkin} falls
+ * back to it for every state a set does not define.
+ */
+export type UISkinSet = { readonly normal: UISkin } & { readonly [State in Exclude<UIWidgetState, 'normal'>]?: UISkin };
+
+/**
+ * A themed surface. Roles are per painted surface, not per widget class: a
+ * progress bar draws its track and its fill from two independent roles.
+ */
+export type UIThemeRole = 'panel' | 'button' | 'label' | 'progressBarTrack' | 'progressBarFill';
+
+/** Skins for every role, as resolved for a widget. */
+export type UITheme = { readonly [Role in UIThemeRole]: UISkinSet };
+
+/** Skin fields to override; an omitted field keeps the inherited one. */
+export type UISkinPatch = Partial<UISkin>;
+
+/** Per-state skin overrides. */
+export type UISkinSetPatch = { readonly [State in UIWidgetState]?: UISkinPatch };
+
+/**
+ * Theme overrides applied on top of an inherited theme. Fields are replaced
+ * whole: naming `background` replaces the entire descriptor, since blending
+ * half a fill into a nine-slice has no meaning. Single-property tweaks belong
+ * on the widget (`panel.color = ...`), not in a theme patch.
+ */
+export type UIThemePatch = { readonly [Role in UIThemeRole]?: UISkinSetPatch };
+
+const zeroInsets: UIInsets = { left: 0, top: 0, right: 0, bottom: 0 };
+
+const noBackground: UINoBackground = { kind: 'none' };
+
+const fill = (color: Color, cornerRadius: number, borderColor: Color = new Color(255, 255, 255, 0), borderWidth = 0): UIFillBackground => ({
+  kind: 'fill',
+  color,
+  borderColor,
+  borderWidth,
+  cornerRadius,
+});
+
+const skin = (background: UIBackground, text: TextStyleOptions = {}, insets: UIInsets = zeroInsets): UISkin => ({ background, text, insets });
+
+const buttonText: TextStyleOptions = { fillColor: new Color(255, 255, 255, 1), fontSize: 16, align: 'center' };
+
+/**
+ * The theme a UI layer uses until one is assigned. It reproduces the widgets'
+ * built-in look, so assigning a patch changes only what the patch names.
+ */
+export const defaultUITheme: UITheme = {
+  panel: {
+    normal: skin(fill(new Color(30, 34, 45, 0.92), 8, new Color(255, 255, 255, 0.12), 0)),
+  },
+  button: {
+    normal: skin(fill(new Color(54, 120, 220, 1), 8), buttonText),
+    hover: skin(fill(new Color(74, 140, 240, 1), 8), buttonText),
+    pressed: skin(fill(new Color(40, 96, 180, 1), 8), buttonText),
+    disabled: skin(fill(new Color(70, 76, 90, 1), 8), buttonText),
+  },
+  label: {
+    normal: skin(noBackground, { fillColor: new Color(255, 255, 255, 1), fontSize: 16 }),
+  },
+  progressBarTrack: {
+    normal: skin(fill(new Color(255, 255, 255, 0.16), 4)),
+  },
+  progressBarFill: {
+    normal: skin(fill(new Color(80, 220, 120, 1), 4)),
+  },
+};
+
+/** The skin a state paints with, falling back to `normal` where undefined. */
+export const resolveUISkin = (set: UISkinSet, state: UIWidgetState): UISkin => set[state] ?? set.normal;
+
+const mergeSkin = (base: UISkin, patch: UISkinPatch): UISkin => ({
+  background: patch.background ?? base.background,
+  text: patch.text ?? base.text,
+  insets: patch.insets ?? base.insets,
+});
+
+const mergeSkinSet = (base: UISkinSet, patch: UISkinSetPatch): UISkinSet => {
+  const merged: { normal: UISkin } & { [State in Exclude<UIWidgetState, 'normal'>]?: UISkin } = { ...base };
+
+  for (const state of Object.keys(patch) as UIWidgetState[]) {
+    const skinPatch = patch[state];
+
+    if (skinPatch !== undefined) {
+      merged[state] = mergeSkin(resolveUISkin(base, state), skinPatch);
+    }
+  }
+
+  return merged;
+};
+
+/**
+ * Resolve `patch` against `base`, role by role and state by state. Roles the
+ * patch does not name keep the base object itself, so an unchanged theme stays
+ * identical by reference - which is what makes a cascade refresh a pointer
+ * comparison rather than a deep diff.
+ */
+export const createUITheme = (patch: UIThemePatch, base: UITheme = defaultUITheme): UITheme => {
+  const roles = Object.keys(patch) as UIThemeRole[];
+
+  if (roles.length === 0) {
+    return base;
+  }
+
+  const merged = { ...base };
+
+  for (const role of roles) {
+    const setPatch = patch[role];
+
+    if (setPatch !== undefined) {
+      merged[role] = mergeSkinSet(base[role], setPatch);
+    }
+  }
+
+  return merged;
+};
+
+// Dev builds freeze the default theme so a caller who mutates a shared skin -
+// or a `Color` inside one - fails at the write instead of silently restyling
+// every widget that inherited it. `Color` fills its `_rgba` / `_array` caches
+// lazily, so each one is warmed before freezing; an unwarmed frozen colour
+// would throw on a plain read.
+if (__DEV__) {
+  const freezeColor = (color: Color): void => {
+    color.toRgba8();
+    color.toArray();
+    Object.freeze(color);
+  };
+
+  const freezeBackground = (background: UIBackground): void => {
+    if (background.kind === 'fill') {
+      freezeColor(background.color);
+      freezeColor(background.borderColor);
+    }
+
+    Object.freeze(background);
+  };
+
+  for (const set of Object.values(defaultUITheme)) {
+    for (const stateSkin of Object.values(set) as UISkin[]) {
+      freezeBackground(stateSkin.background);
+
+      if (stateSkin.text.fillColor !== undefined) {
+        freezeColor(stateSkin.text.fillColor);
+      }
+
+      Object.freeze(stateSkin.text);
+      Object.freeze(stateSkin.insets);
+      Object.freeze(stateSkin);
+    }
+
+    Object.freeze(set);
+  }
+
+  Object.freeze(defaultUITheme);
+}
diff --git a/test/ui/theme.test.ts b/test/ui/theme.test.ts
new file mode 100644
index 000000000..2378e8ad5
--- /dev/null
+++ b/test/ui/theme.test.ts
@@ -0,0 +1,73 @@
+import { Color } from '#core/Color';
+import type { UIFillBackground, UISkinSet } from '#ui/theme';
+import { createUITheme, defaultUITheme, resolveUISkin } from '#ui/theme';
+
+const fillOf = (set: UISkinSet, state: 'normal' | 'hover' | 'pressed' | 'disabled' | 'focused' = 'normal'): UIFillBackground => {
+  const background = resolveUISkin(set, state).background;
+
+  if (background.kind !== 'fill') {
+    throw new Error(`expected a fill background, got '${background.kind}'`);
+  }
+
+  return background;
+};
+
+describe('defaultUITheme', () => {
+  test('carries the widgets built-in look', () => {
+    expect(fillOf(defaultUITheme.panel).color.toRgba8()).toEqual(new Color(30, 34, 45, 0.92).toRgba8());
+    expect(fillOf(defaultUITheme.button).color.toRgba8()).toEqual(new Color(54, 120, 220, 1).toRgba8());
+    expect(fillOf(defaultUITheme.button, 'pressed').color.toRgba8()).toEqual(new Color(40, 96, 180, 1).toRgba8());
+    expect(fillOf(defaultUITheme.progressBarFill).cornerRadius).toBe(4);
+    expect(defaultUITheme.label.normal.background.kind).toBe('none');
+  });
+
+  test('is frozen in development builds, so a shared skin cannot be restyled by accident', () => {
+    expect(() => fillOf(defaultUITheme.panel).color.set(1, 2, 3, 1)).toThrow();
+    expect(Object.isFrozen(defaultUITheme.panel.normal)).toBe(true);
+  });
+});
+
+describe('resolveUISkin', () => {
+  test('falls back to the normal skin for states a set does not define', () => {
+    expect(resolveUISkin(defaultUITheme.panel, 'hover')).toBe(defaultUITheme.panel.normal);
+    expect(resolveUISkin(defaultUITheme.button, 'hover')).toBe(defaultUITheme.button.hover);
+  });
+});
+
+describe('createUITheme', () => {
+  test('returns the base itself for an empty patch', () => {
+    expect(createUITheme({})).toBe(defaultUITheme);
+  });
+
+  test('keeps unpatched roles identical by reference', () => {
+    const theme = createUITheme({ panel: { normal: { insets: { left: 4, top: 4, right: 4, bottom: 4 } } } });
+
+    expect(theme.button).toBe(defaultUITheme.button);
+    expect(theme.panel).not.toBe(defaultUITheme.panel);
+  });
+
+  test('replaces named skin fields and keeps the rest', () => {
+    const background: UIFillBackground = { kind: 'fill', color: new Color(1, 2, 3, 1), borderColor: new Color(0, 0, 0, 1), borderWidth: 2, cornerRadius: 0 };
+    const theme = createUITheme({ panel: { normal: { background } } });
+
+    expect(theme.panel.normal.background).toBe(background);
+    expect(theme.panel.normal.insets).toBe(defaultUITheme.panel.normal.insets);
+  });
+
+  test('derives a patched state from the normal skin when the base does not define it', () => {
+    const insets = { left: 6, top: 6, right: 6, bottom: 6 };
+    const theme = createUITheme({ panel: { hover: { insets } } });
+
+    expect(theme.panel.hover?.insets).toBe(insets);
+    expect(theme.panel.hover?.background).toBe(defaultUITheme.panel.normal.background);
+    expect(theme.panel.normal).toBe(defaultUITheme.panel.normal);
+  });
+
+  test('resolves against an explicit base theme rather than the default', () => {
+    const dark = createUITheme({ label: { normal: { text: { fontSize: 24 } } } });
+    const larger = createUITheme({ button: { normal: { text: { fontSize: 32 } } } }, dark);
+
+    expect(larger.label.normal.text.fontSize).toBe(24);
+    expect(larger.button.normal.text.fontSize).toBe(32);
+  });
+});

From 3ddb5d52dfb2b5c11d871a179b1c43a42557aec0 Mon Sep 17 00:00:00 2001
From: Exoridus <github@codexo.de>
Date: Thu, 27 Aug 2026 21:24:15 +0200
Subject: [PATCH 2/6] feat(ui): cascade the theme through the scene tree and
 split invalidation

The theme travels the scene graph: `ThemedContainer` carries one for the
subtree below it, `UIRoot` owns the layer's, and a widget resolves the
nearest themed ancestor's theme with its own overrides applied on top.
A widget without overrides reuses the inherited object by reference, so
"did my theme change?" stays a pointer comparison, and reparenting
re-resolves the same way `effectiveEnabled` already does. No global theme
registry - two UI layers can carry different themes.

Widgets now paint in `_repaint` and place content in `_relayout`, with
`_invalidatePaint` and `_invalidateLayout` naming which of the two a change
needs. A theme change takes the layout path: skin insets are layout input,
so a paint-only refresh would be wrong as soon as a skin changes them.
---
 src/ui/ThemedContainer.ts     |  66 ++++++++++++++
 src/ui/UIRoot.ts              |  33 ++++++-
 src/ui/Widget.ts              | 126 +++++++++++++++++++++++---
 test/ui/theme-cascade.test.ts | 160 ++++++++++++++++++++++++++++++++++
 4 files changed, 373 insertions(+), 12 deletions(-)
 create mode 100644 src/ui/ThemedContainer.ts
 create mode 100644 test/ui/theme-cascade.test.ts

diff --git a/src/ui/ThemedContainer.ts b/src/ui/ThemedContainer.ts
new file mode 100644
index 000000000..941dcc11a
--- /dev/null
+++ b/src/ui/ThemedContainer.ts
@@ -0,0 +1,66 @@
+import { Container } from '#rendering/Container';
+import type { RenderNode } from '#rendering/RenderNode';
+
+import type { UITheme } from './theme';
+import { defaultUITheme } from './theme';
+
+/**
+ * A container that carries a {@link UITheme} for the subtree below it. Widgets
+ * resolve their skins from the nearest themed ancestor, which is how a theme
+ * assigned on a {@link UIRoot} reaches every widget in that layer without a
+ * global registry.
+ */
+export abstract class ThemedContainer extends Container {
+  protected _theme: UITheme = defaultUITheme;
+
+  /** The theme in effect for this node and everything below it. */
+  public get theme(): UITheme {
+    return this._theme;
+  }
+
+  /**
+   * @internal - re-resolve this node's theme against its ancestor chain. The
+   * cascade calls this on every themed node below a change; `force` re-resolves
+   * even when the inherited theme is unchanged, which is what a change to the
+   * node's own overrides needs.
+   */
+  public abstract _refreshTheme(force?: boolean): void;
+
+  /** The nearest themed ancestor's theme, or the built-in default when this node has none. */
+  protected _resolveInheritedTheme(): UITheme {
+    for (let current = this.parent; current !== null; current = current.parent) {
+      if (current instanceof ThemedContainer) {
+        return current.theme;
+      }
+    }
+
+    return defaultUITheme;
+  }
+
+  /** Push a theme refresh into every themed descendant. */
+  protected _cascadeTheme(): void {
+    for (const child of this.children) {
+      cascadeThemeInto(child);
+    }
+  }
+}
+
+/**
+ * Push a theme refresh into `node`: directly if it is themed, or forwarded to
+ * themed descendants through any plain container in between.
+ *
+ * @internal
+ */
+export const cascadeThemeInto = (node: RenderNode): void => {
+  if (node instanceof ThemedContainer) {
+    node._refreshTheme();
+
+    return;
+  }
+
+  if (node instanceof Container) {
+    for (const child of node.children) {
+      cascadeThemeInto(child);
+    }
+  }
+};
diff --git a/src/ui/UIRoot.ts b/src/ui/UIRoot.ts
index 489628ac9..1e31b81ec 100644
--- a/src/ui/UIRoot.ts
+++ b/src/ui/UIRoot.ts
@@ -1,7 +1,9 @@
 import { Signal } from '#core/Signal';
-import { Container } from '#rendering/Container';
 import type { RenderingContext } from '#rendering/RenderingContext';
 
+import { ThemedContainer } from './ThemedContainer';
+import type { UITheme } from './theme';
+
 /**
  * Root of a scene's screen-fixed UI layer. Reached through {@link Scene.ui};
  * you do not construct it directly.
@@ -15,14 +17,41 @@ import type { RenderingContext } from '#rendering/RenderingContext';
  *
  * Add widgets with `scene.ui.addChild(...)`. The {@link UIRoot.onResize} signal
  * fires whenever the screen size changes, so anchored widgets can re-layout.
+ *
+ * The root also carries the layer's {@link UIRoot.theme}: widgets resolve their
+ * skins from the nearest themed ancestor, so assigning a theme here restyles
+ * every widget below that does not override it.
  */
-export class UIRoot extends Container {
+export class UIRoot extends ThemedContainer {
   /** Fires with `(width, height)` whenever the screen size changes. */
   public readonly onResize = new Signal<[width: number, height: number]>();
 
   private _screenWidth = 0;
   private _screenHeight = 0;
 
+  /**
+   * Base theme for every widget in this layer. Widgets override parts of it
+   * per subtree with `Widget.setTheme`; there is no global theme, so two UI
+   * layers can carry different ones. Assigning restyles the whole layer at
+   * once - every widget below repaints and re-lays out.
+   */
+  public override get theme(): UITheme {
+    return this._theme;
+  }
+
+  public override set theme(value: UITheme) {
+    if (this._theme !== value) {
+      this._theme = value;
+      this._cascadeTheme();
+    }
+  }
+
+  /** @internal - a UI layer's theme is assigned, never inherited, so there is nothing to re-resolve here. */
+  public override _refreshTheme(): void {
+    // A UIRoot owns its theme outright; the cascade stops descending only into
+    // its children, which it pushes itself when the theme is assigned.
+  }
+
   /** Screen width the UI is laid out against, in logical pixels. */
   public get screenWidth(): number {
     return this._screenWidth;
diff --git a/src/ui/Widget.ts b/src/ui/Widget.ts
index f884d4527..98d0dd88a 100644
--- a/src/ui/Widget.ts
+++ b/src/ui/Widget.ts
@@ -1,6 +1,9 @@
 import { Container } from '#rendering/Container';
 import type { RenderNode } from '#rendering/RenderNode';
 
+import { ThemedContainer } from './ThemedContainer';
+import type { UISkin, UITheme, UIThemePatch, UIThemeRole, UIWidgetState } from './theme';
+import { createUITheme, resolveUISkin } from './theme';
 import type { UIRoot } from './UIRoot';
 
 /** Anchor position of a widget within its container's box. */
@@ -31,12 +34,21 @@ const anchorFactors = (anchor: WidgetAnchor): readonly [number, number] => {
  * (independent of child bounds / scale), an `enabled` flag, and optional
  * screen-edge anchoring that re-applies on resize.
  *
- * Subclasses redraw size-dependent content in {@link Widget._relayout} and
- * react to enable/disable in {@link Widget._onEnabledChanged}.
+ * Widgets read their look from the theme of the nearest themed ancestor - the
+ * layer's {@link UIRoot}, or any widget above them that set overrides with
+ * {@link Widget.setTheme}.
+ *
+ * Subclasses paint in {@link Widget._repaint}, place size-dependent content in
+ * {@link Widget._relayout}, and react to enable/disable in
+ * {@link Widget._onEnabledChanged}.
  */
-export abstract class Widget extends Container {
+export abstract class Widget extends ThemedContainer {
   protected _uiWidth = 0;
   protected _uiHeight = 0;
+  /** The state this widget's skins are resolved for; see {@link Widget._setSkinState}. */
+  protected _skinState: UIWidgetState = 'normal';
+  private _themePatch: UIThemePatch | null = null;
+  private _inheritedTheme: UITheme = this._theme;
   private _enabled = true;
   private _effectiveEnabled = true;
   private _uiAnchor: WidgetAnchor | null = null;
@@ -65,16 +77,30 @@ export abstract class Widget extends Container {
     if (this._uiWidth !== w || this._uiHeight !== h) {
       this._uiWidth = w;
       this._uiHeight = h;
-      this._relayout();
-
-      if (this._uiAnchorRoot !== null) {
-        this._applyAnchor(this._uiAnchorRoot.screenWidth, this._uiAnchorRoot.screenHeight);
-      }
+      this._invalidateLayout();
     }
 
     return this;
   }
 
+  /** This widget's own theme overrides, or `null` when it purely inherits. */
+  public get themeOverrides(): UIThemePatch | null {
+    return this._themePatch;
+  }
+
+  /**
+   * Override parts of the inherited theme for this widget and its descendants.
+   * `null` clears the override. Repaints and re-lays out every widget in the
+   * subtree that the change reaches - skin insets are layout input, so a theme
+   * change is never paint-only.
+   */
+  public setTheme(patch: UIThemePatch | null): this {
+    this._themePatch = patch;
+    this._refreshTheme(true);
+
+    return this;
+  }
+
   /**
    * The widget's own enabled flag, independent of any ancestor's. Disabling a
    * container widget does not change this on its children - see
@@ -141,9 +167,63 @@ export abstract class Widget extends Container {
     this.setPosition(ax * (containerWidth - this._uiWidth) + this._uiAnchorOffsetX, ay * (containerHeight - this._uiHeight) + this._uiAnchorOffsetY);
   }
 
-  /** Redraw size-dependent content (background, child positions). Override in subclasses. */
+  /**
+   * Redraw this widget's own painted surfaces for the current size and skin.
+   * Override in subclasses that draw a background.
+   */
+  protected _repaint(): void {
+    // Overridden by subclasses that paint a sized surface.
+  }
+
+  /**
+   * Re-place size-dependent content and repaint. Override in subclasses that
+   * position children; call `super._relayout()` to keep the repaint.
+   */
   protected _relayout(): void {
-    // Overridden by subclasses that draw a sized background.
+    this._repaint();
+  }
+
+  /**
+   * Repaint without re-laying out - for a change that cannot move anything,
+   * such as a colour or a state flip. Applied immediately, not batched.
+   */
+  protected _invalidatePaint(): void {
+    this._repaint();
+  }
+
+  /**
+   * Re-lay out and repaint, then re-apply screen anchoring. This is the right
+   * invalidation for anything a skin's insets or a font size can move, and for
+   * every size change.
+   */
+  protected _invalidateLayout(): void {
+    this._relayout();
+
+    if (this._uiAnchorRoot !== null) {
+      this._applyAnchor(this._uiAnchorRoot.screenWidth, this._uiAnchorRoot.screenHeight);
+    }
+  }
+
+  /** The skin `role` paints with in this widget's current state. */
+  protected _skin(role: UIThemeRole): UISkin {
+    return resolveUISkin(this._theme[role], this._skinState);
+  }
+
+  /** Switch the state skins resolve for, repainting when it actually changes. */
+  protected _setSkinState(state: UIWidgetState): void {
+    if (this._skinState !== state) {
+      this._skinState = state;
+      this._invalidatePaint();
+    }
+  }
+
+  /**
+   * React to a resolved-theme change. The default re-lays out and repaints;
+   * override to re-read skin values that are cached elsewhere first, then call
+   * `super._onThemeChanged()`.
+   */
+  protected _onThemeChanged(): void {
+    this._invalidateLayout();
   }
 
   /**
@@ -155,6 +235,31 @@ export abstract class Widget extends Container {
     // Overridden by interactive subclasses (e.g. Button dimming).
   }
 
+  /**
+   * @internal - re-resolve {@link ThemedContainer.theme} from the nearest
+   * themed ancestor and this widget's own overrides, then push the same
+   * recompute into every themed descendant.
+   */
+  public override _refreshTheme(force = false): void {
+    const inherited = this._resolveInheritedTheme();
+
+    if (!force && inherited === this._inheritedTheme) {
+      return;
+    }
+
+    this._inheritedTheme = inherited;
+
+    const next = this._themePatch === null ? inherited : createUITheme(this._themePatch, inherited);
+
+    if (next === this._theme && !force) {
+      return;
+    }
+
+    this._theme = next;
+    this._onThemeChanged();
+    this._cascadeTheme();
+  }
+
   /**
    * Recompute {@link effectiveEnabled} from the current own flag and parent
    * chain. No-ops if it did not actually change; otherwise fires
@@ -215,6 +320,7 @@ export abstract class Widget extends Container {
   public override _setParent(parent: Container | null): void {
     super._setParent(parent);
     this._refreshEffectiveEnabled();
+    this._refreshTheme();
   }
 
   public override destroy(): void {
diff --git a/test/ui/theme-cascade.test.ts b/test/ui/theme-cascade.test.ts
new file mode 100644
index 000000000..65b63a400
--- /dev/null
+++ b/test/ui/theme-cascade.test.ts
@@ -0,0 +1,160 @@
+import { Color } from '#core/Color';
+import { Container } from '#rendering/Container';
+import type { UIFillBackground, UITheme } from '#ui/theme';
+import { createUITheme, defaultUITheme } from '#ui/theme';
+import { UIRoot } from '#ui/UIRoot';
+import { Widget } from '#ui/Widget';
+
+class ProbeWidget extends Widget {
+  public paints = 0;
+  public layouts = 0;
+
+  protected override _repaint(): void {
+    this.paints++;
+  }
+
+  protected override _relayout(): void {
+    this.layouts++;
+    super._relayout();
+  }
+
+  /** The panel fill this widget currently resolves, for state-free assertions. */
+  public get panelColor(): Color {
+    return (this._skin('panel').background as UIFillBackground).color;
+  }
+}
+
+const red: UITheme = createUITheme({
+  panel: { normal: { background: { kind: 'fill', color: new Color(255, 0, 0, 1), borderColor: Color.black, borderWidth: 0, cornerRadius: 0 } } },
+});
+const blue: UITheme = createUITheme({
+  panel: { normal: { background: { kind: 'fill', color: new Color(0, 0, 255, 1), borderColor: Color.black, borderWidth: 0, cornerRadius: 0 } } },
+});
+
+describe('theme cascade', () => {
+  test('a detached widget reads the default theme', () => {
+    expect(new ProbeWidget().theme).toBe(defaultUITheme);
+  });
+
+  test('attaching to a UI layer adopts that layer theme', () => {
+    const root = new UIRoot();
+    const widget = new ProbeWidget();
+
+    root.theme = red;
+    root.addChild(widget);
+
+    expect(widget.theme).toBe(red);
+  });
+
+  test('assigning a layer theme restyles the widgets already in it', () => {
+    const root = new UIRoot();
+    const widget = new ProbeWidget();
+
+    root.addChild(widget);
+    const layoutsBefore = widget.layouts;
+
+    root.theme = red;
+
+    expect(widget.theme).toBe(red);
+    expect(widget.layouts).toBe(layoutsBefore + 1);
+  });
+
+  test('reaches widgets through a plain container in between', () => {
+    const root = new UIRoot();
+    const group = new Container();
+    const widget = new ProbeWidget();
+
+    group.addChild(widget);
+    root.addChild(group);
+    root.theme = red;
+
+    expect(widget.theme).toBe(red);
+  });
+
+  test('a widget inherits from the nearest widget ancestor, not the layer', () => {
+    const root = new UIRoot();
+    const parent = new ProbeWidget();
+    const child = new ProbeWidget();
+
+    root.theme = red;
+    root.addChild(parent);
+    parent.addChild(child);
+    parent.setTheme({ panel: { normal: { background: blue.panel.normal.background } } });
+
+    expect(child.panelColor.toRgba8()).toBe(new Color(0, 0, 255, 1).toRgba8());
+    expect(parent.themeOverrides).not.toBeNull();
+  });
+
+  test('overrides stay inside their subtree', () => {
+    const root = new UIRoot();
+    const overridden = new ProbeWidget();
+    const sibling = new ProbeWidget();
+
+    root.theme = red;
+    root.addChild(overridden);
+    root.addChild(sibling);
+    overridden.setTheme({ panel: { normal: { background: blue.panel.normal.background } } });
+
+    expect(sibling.theme).toBe(red);
+  });
+
+  test('clearing an override falls back to the inherited theme', () => {
+    const root = new UIRoot();
+    const widget = new ProbeWidget();
+
+    root.theme = red;
+    root.addChild(widget);
+    widget.setTheme({ panel: { normal: { insets: { left: 4, top: 4, right: 4, bottom: 4 } } } });
+    widget.setTheme(null);
+
+    expect(widget.theme).toBe(red);
+    expect(widget.themeOverrides).toBeNull();
+  });
+
+  test('reparenting re-resolves the inherited theme', () => {
+    const first = new UIRoot();
+    const second = new UIRoot();
+    const widget = new ProbeWidget();
+
+    first.theme = red;
+    second.theme = blue;
+    first.addChild(widget);
+    second.addChild(widget);
+
+    expect(widget.theme).toBe(blue);
+  });
+
+  test('an unchanged theme does not repaint', () => {
+    const root = new UIRoot();
+    const widget = new ProbeWidget();
+
+    root.theme = red;
+    root.addChild(widget);
+    const layoutsBefore = widget.layouts;
+
+    root.theme = red;
+    widget._refreshTheme();
+
+    expect(widget.layouts).toBe(layoutsBefore);
+  });
+});
+
+describe('paint and layout invalidation', () => {
+  test('a size change lays out and paints', () => {
+    const widget = new ProbeWidget();
+
+    widget.setSize(100, 50);
+
+    expect(widget.layouts).toBe(1);
+    expect(widget.paints).toBe(1);
+  });
+
+  test('an unchanged size does neither', () => {
+    const widget = new ProbeWidget();
+
+    widget.setSize(100, 50);
+    widget.setSize(100, 50);
+
+    expect(widget.layouts).toBe(1);
+  });
+});

From fe0ade01c751c4ee26c95e7ddaf7afef09f7e519 Mon Sep 17 00:00:00 2001
From: Exoridus <github@codexo.de>
Date: Thu, 27 Aug 2026 21:32:35 +0200
Subject: [PATCH 3/6] feat(ui): paint widgets from skins and put their style
 behind setters

Panel, Button, ProgressBar and Label read their look from the theme role
they paint and keep only their own overrides. `WidgetBackground` owns the
node a background descriptor needs - a `Graphics` for a fill, a
`NineSliceSprite` for a texture - and swaps it in place at a fixed child
slot, so the texture case is painted rather than merely declared.

Style is no longer a mutable object handed out by a getter: `setFill`,
`setBackground` and `setTextStyle` are the way in, and each one invalidates
paint or layout as the change requires. Button carries one skin per state,
so hover, pressed and disabled follow the theme instead of four hardcoded
colours; label placement now respects the skin's insets.

Serialization writes a widget's overrides instead of its resolved values,
so a scene saved under one theme no longer replays that theme when it is
loaded under another.
---
 src/core/serialization/serializerHelpers.ts |  30 +++
 src/core/serialization/uiSerializers.ts     |  54 ++++--
 src/ui/Button.ts                            | 192 ++++++++++++++++----
 src/ui/Label.ts                             |  50 ++++-
 src/ui/Panel.ts                             | 128 +++++++++----
 src/ui/ProgressBar.ts                       | 132 +++++++++-----
 src/ui/UIRoot.ts                            |   2 +-
 src/ui/Widget.ts                            |   2 +-
 src/ui/WidgetBackground.ts                  | 111 +++++++++++
 src/ui/index.ts                             |  20 +-
 src/ui/theme.ts                             |  47 ++++-
 test/core/serialization.test.ts             |   2 +-
 test/ui/widgets.test.ts                     | 131 ++++++++++++-
 13 files changed, 748 insertions(+), 153 deletions(-)
 create mode 100644 src/ui/WidgetBackground.ts

diff --git a/src/core/serialization/serializerHelpers.ts b/src/core/serialization/serializerHelpers.ts
index e90b63144..ff7e6db37 100644
--- a/src/core/serialization/serializerHelpers.ts
+++ b/src/core/serialization/serializerHelpers.ts
@@ -84,6 +84,36 @@ export const serializeStyle = (style: {
 };
 
 /** Rebuild {@link TextStyleOptions} from serialized style data, or `undefined`. */
+/**
+ * Serialize a partial text style - a widget's own style overrides - writing
+ * exactly the fields it names, so a widget that takes its style from a theme
+ * round-trips as "no override" instead of baking that theme's values in. A
+ * `FontFace` has no serialized form and is skipped.
+ */
+export const serializeStyleOptions = (options: TextStyleOptions | null): Record<string, unknown> | undefined => {
+  if (options === null) {
+    return undefined;
+  }
+
+  const out: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined || key === 'font') {
+      continue;
+    }
+
+    if (value instanceof Color) {
+      out[key] = colorToArray(value);
+    } else if (Array.isArray(value)) {
+      out[key] = (value as unknown[]).map(entry => (entry instanceof Color ? colorToArray(entry) : entry));
+    } else {
+      out[key] = value;
+    }
+  }
+
+  return Object.keys(out).length > 0 ? out : undefined;
+};
+
 export const deserializeStyleOptions = (data: unknown): TextStyleOptions | undefined => {
   if (typeof data !== 'object' || data === null) {
     return undefined;
diff --git a/src/core/serialization/uiSerializers.ts b/src/core/serialization/uiSerializers.ts
index f2c1ce56e..982fc72b3 100644
--- a/src/core/serialization/uiSerializers.ts
+++ b/src/core/serialization/uiSerializers.ts
@@ -5,15 +5,28 @@ import { Panel } from '#ui/Panel';
 import { ProgressBar } from '#ui/ProgressBar';
 import { ScrollContainer, type ScrollDirection } from '#ui/ScrollContainer';
 import { Stack } from '#ui/Stack';
+import type { UIFillPatch } from '#ui/theme';
 import { UIRoot } from '#ui/UIRoot';
 
 import type { NodeSerializer } from './NodeSerializer';
 import { asSerializedNode } from './read';
 import type { SerializationRegistry } from './SerializationRegistry';
-import { arrayToColor, colorToArray, compact, deserializeStyleOptions, serializeStyle } from './serializerHelpers';
+import { arrayToColor, colorToArray, compact, deserializeStyleOptions, serializeStyleOptions } from './serializerHelpers';
 
 const num = (value: unknown): number | undefined => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
 
+/** The fields a widget's fill overrides contribute, omitting what it does not override. */
+const serializeFill = (fill: UIFillPatch | null): Record<string, unknown> => ({
+  ...(fill?.color !== undefined && { color: colorToArray(fill.color) }),
+  ...(fill?.borderColor !== undefined && { borderColor: colorToArray(fill.borderColor) }),
+  ...(fill?.borderWidth !== undefined && { borderWidth: fill.borderWidth }),
+  ...(fill?.cornerRadius !== undefined && { cornerRadius: fill.cornerRadius }),
+});
+
+/** Just the colour of a fill override, under the key the widget's options use for it. */
+const serializeFillColor = (key: string, fill: UIFillPatch | null): Record<string, unknown> =>
+  fill?.color !== undefined ? { [key]: colorToArray(fill.color) } : {};
+
 // Widget composition note: widgets own internal children (a Label's Text, a
 // Panel's background Graphics, a ScrollContainer's content Container, etc.) that
 // their constructors rebuild - those are never serialized. Only user-added
@@ -21,13 +34,18 @@ const num = (value: unknown): number | undefined => (typeof value === 'number' &
 // round-trip; for ScrollContainer those live one level down, inside `content`.
 // Anchoring (anchorIn) references a UIRoot and is not serialized; the resolved
 // position still round-trips via the common fields.
+//
+// Style: only a widget's OWN overrides round-trip, never the values it resolved
+// from a theme - otherwise loading a scene under a different theme would replay
+// the theme it was saved under. Whole-background overrides (`setBackground`)
+// are skipped as well: a texture reference has no serialized form here.
 
 // ── Label ────────────────────────────────────────────────────────────────────
 
 const labelSerializer: NodeSerializer<Label> = {
   write(node) {
     const out: Record<string, unknown> = { text: node.text };
-    const style = serializeStyle(node.textNode.style);
+    const style = serializeStyleOptions(node.textStyleOverrides);
 
     if (style !== undefined) out.style = style;
     if (!node.enabled) out.enabled = false;
@@ -47,18 +65,16 @@ const labelSerializer: NodeSerializer<Label> = {
 
 const panelSerializer: NodeSerializer<Panel> = {
   write(node, ctx) {
+    const fill = node.fillOverrides;
     const out: Record<string, unknown> = {
       width: node.uiWidth,
       height: node.uiHeight,
-      color: colorToArray(node.color),
-      borderColor: colorToArray(node.borderColor),
-      borderWidth: node.borderWidth,
-      cornerRadius: node.cornerRadius,
+      ...serializeFill(fill),
     };
 
     if (!node.enabled) out.enabled = false;
 
-    const userChildren = node.children.filter(child => child !== node.background);
+    const userChildren = node.children.filter(child => child !== node.backgroundNode);
     if (userChildren.length > 0) out.children = userChildren.map(child => ctx.writeNode(child));
 
     return out;
@@ -93,19 +109,22 @@ const panelSerializer: NodeSerializer<Panel> = {
 
 const buttonSerializer: NodeSerializer<Button> = {
   write(node) {
+    const normal = node.fillOverridesIn('normal');
     const out: Record<string, unknown> = {
       width: node.uiWidth,
       height: node.uiHeight,
       label: node.label,
-      cornerRadius: node.cornerRadius,
-      color: colorToArray(node.colors.normal),
-      hoverColor: colorToArray(node.colors.hover),
-      pressedColor: colorToArray(node.colors.pressed),
-      disabledColor: colorToArray(node.colors.disabled),
-      textColor: colorToArray(node.textColor),
-      fontSize: node.fontSize,
+      ...serializeFill(normal),
+      ...serializeFillColor('hoverColor', node.fillOverridesIn('hover')),
+      ...serializeFillColor('pressedColor', node.fillOverridesIn('pressed')),
+      ...serializeFillColor('disabledColor', node.fillOverridesIn('disabled')),
     };
 
+    const style = node.textStyleOverrides;
+
+    if (style?.fillColor !== undefined) out.textColor = colorToArray(style.fillColor);
+    if (style?.fontSize !== undefined) out.fontSize = style.fontSize;
+
     if (!node.enabled) out.enabled = false;
 
     return out;
@@ -136,13 +155,14 @@ const buttonSerializer: NodeSerializer<Button> = {
 
 const progressBarSerializer: NodeSerializer<ProgressBar> = {
   write(node) {
+    const { track, bar } = node.fillOverrides;
     const out: Record<string, unknown> = {
       width: node.uiWidth,
       height: node.uiHeight,
       value: node.value,
-      trackColor: colorToArray(node.trackColor),
-      fillColor: colorToArray(node.fillColor),
-      cornerRadius: node.cornerRadius,
+      ...serializeFillColor('trackColor', track),
+      ...serializeFillColor('fillColor', bar),
+      ...(track?.cornerRadius !== undefined && { cornerRadius: track.cornerRadius }),
     };
 
     if (!node.enabled) out.enabled = false;
diff --git a/src/ui/Button.ts b/src/ui/Button.ts
index db9d2830d..51348d002 100644
--- a/src/ui/Button.ts
+++ b/src/ui/Button.ts
@@ -1,11 +1,14 @@
-import { Color } from '#core/Color';
+import type { Color } from '#core/Color';
 import { Signal } from '#core/Signal';
 import type { KeyEvent } from '#input/KeyEvent';
 import { Keyboard } from '#input/types';
-import { Graphics } from '#rendering/primitives/Graphics';
 import { Text } from '#rendering/text/Text';
+import type { TextStyleOptions } from '#rendering/text/TextStyle';
 
+import type { UIBackground, UIFillPatch, UIWidgetState } from './theme';
+import { applyUIFillPatch, resolveUISkin } from './theme';
 import { Widget } from './Widget';
+import { WidgetBackground } from './WidgetBackground';
 
 export interface ButtonOptions {
   width?: number;
@@ -21,41 +24,65 @@ export interface ButtonOptions {
   fontSize?: number;
 }
 
-type ButtonState = 'normal' | 'hover' | 'pressed' | 'disabled';
+/** The states a button paints in. */
+export type ButtonState = 'normal' | 'hover' | 'pressed' | 'disabled';
+
+const buttonStates: readonly ButtonState[] = ['normal', 'hover', 'pressed', 'disabled'];
+
+const fillColorOf = (background: UIBackground): Color | null => (background.kind === 'fill' ? background.color : null);
 
 /**
  * Clickable button with a rounded background, a centered label, hover/pressed
  * visual states, and keyboard activation (Enter / Space while focused).
  * Listen to {@link Button.onClick} for activation.
+ *
+ * The button paints the `button` role of its inherited theme, one skin per
+ * state. Constructor options and the setters below are per-button overrides on
+ * top of that skin.
  */
 export class Button extends Widget {
   /** Fires when the button is activated by click, tap, or Enter/Space. */
   public readonly onClick = new Signal<[Button]>();
 
-  private readonly _background = new Graphics();
+  private readonly _surface = new WidgetBackground(this, 0);
   private readonly _label: Text;
-  private readonly _colors: Record<ButtonState, Color>;
-  private readonly _cornerRadius: number;
-  private _state: ButtonState = 'normal';
+  private readonly _backgrounds: Partial<Record<UIWidgetState, UIBackground>> = {};
+  private readonly _fills: Partial<Record<UIWidgetState, UIFillPatch>> = {};
+  private _textStyle: TextStyleOptions | null = null;
+  /** The skin text object last pushed into the label, for a cheap identity check per paint. */
+  private _appliedText: TextStyleOptions | null = null;
   private _pointerInside = false;
 
   public constructor(options: ButtonOptions = {}) {
     super();
 
-    this._colors = {
-      normal: (options.color ?? new Color(54, 120, 220, 1)).clone(),
-      hover: (options.hoverColor ?? new Color(74, 140, 240, 1)).clone(),
-      pressed: (options.pressedColor ?? new Color(40, 96, 180, 1)).clone(),
-      disabled: (options.disabledColor ?? new Color(70, 76, 90, 1)).clone(),
+    const perState: Partial<Record<ButtonState, Color>> = {
+      ...(options.color !== undefined && { normal: options.color }),
+      ...(options.hoverColor !== undefined && { hover: options.hoverColor }),
+      ...(options.pressedColor !== undefined && { pressed: options.pressedColor }),
+      ...(options.disabledColor !== undefined && { disabled: options.disabledColor }),
     };
-    this._cornerRadius = options.cornerRadius ?? 8;
-    this._label = new Text(options.label ?? '', {
-      fillColor: options.textColor ?? Color.white,
-      fontSize: options.fontSize ?? 16,
-      align: 'center',
-    });
-
-    this.addChild(this._background);
+
+    for (const state of buttonStates) {
+      const color = perState[state];
+      const patch: { -readonly [Key in keyof UIFillPatch]: UIFillPatch[Key] } = {};
+
+      if (color !== undefined) patch.color = color.clone();
+      if (options.cornerRadius !== undefined) patch.cornerRadius = options.cornerRadius;
+
+      if (Object.keys(patch).length > 0) this._fills[state] = patch;
+    }
+
+    if (options.textColor !== undefined || options.fontSize !== undefined) {
+      this._textStyle = {
+        ...(options.textColor !== undefined && { fillColor: options.textColor }),
+        ...(options.fontSize !== undefined && { fontSize: options.fontSize }),
+      };
+    }
+
+    this._appliedText = resolveUISkin(this.theme.button, 'normal').text;
+    this._label = new Text(options.label ?? '', { ...this._appliedText, ...this._textStyle });
+
     this.addChild(this._label);
 
     this.interactive = true;
@@ -81,14 +108,41 @@ export class Button extends Widget {
     this._positionLabel();
   }
 
-  /** The per-state fill colours (`normal` / `hover` / `pressed` / `disabled`). */
-  public get colors(): Readonly<Record<'normal' | 'hover' | 'pressed' | 'disabled', Color>> {
-    return this._colors;
+  /** The {@link Text} node drawing the label, for advanced styling. */
+  public get labelNode(): Text {
+    return this._label;
   }
 
-  /** Corner radius in pixels. */
+  /** The state the button currently paints in. */
+  public get state(): ButtonState {
+    return this._skinState as ButtonState;
+  }
+
+  /** The background painted in `state`: this button's overrides over its skin. */
+  public backgroundIn(state: UIWidgetState = this._skinState): UIBackground {
+    return this._backgrounds[state] ?? applyUIFillPatch(resolveUISkin(this.theme.button, state).background, this._fills[state] ?? null);
+  }
+
+  /** The per-state fill colours; `null` for a state that does not paint a fill. */
+  public get colors(): Readonly<Record<ButtonState, Color | null>> {
+    return {
+      normal: fillColorOf(this.backgroundIn('normal')),
+      hover: fillColorOf(this.backgroundIn('hover')),
+      pressed: fillColorOf(this.backgroundIn('pressed')),
+      disabled: fillColorOf(this.backgroundIn('disabled')),
+    };
+  }
+
+  /** The fill overrides carried for `state`, or `null` when it takes its skin as is. */
+  public fillOverridesIn(state: UIWidgetState = 'normal'): UIFillPatch | null {
+    return this._fills[state] ?? null;
+  }
+
+  /** Corner radius in pixels of the normal state; `0` when it paints no fill. */
   public get cornerRadius(): number {
-    return this._cornerRadius;
+    const background = this.backgroundIn('normal');
+
+    return background.kind === 'fill' ? background.cornerRadius : 0;
   }
 
   /** Label fill colour. */
@@ -101,6 +155,52 @@ export class Button extends Widget {
     return this._label.style.fontSize;
   }
 
+  /** The text-style overrides this button carries, or `null` when it takes the skin's. */
+  public get textStyleOverrides(): TextStyleOptions | null {
+    return this._textStyle;
+  }
+
+  /**
+   * Override fill properties for one state on top of its skin. `null` drops
+   * that state's overrides.
+   */
+  public setFill(patch: UIFillPatch | null, state: UIWidgetState = 'normal'): this {
+    if (patch === null) {
+      delete this._fills[state];
+    } else {
+      this._fills[state] = { ...this._fills[state], ...patch };
+    }
+
+    this._invalidatePaint();
+
+    return this;
+  }
+
+  /** Replace one state's whole background descriptor; `null` restores the skin's. */
+  public setBackground(background: UIBackground | null, state: UIWidgetState = 'normal'): this {
+    if (background === null) {
+      delete this._backgrounds[state];
+    } else {
+      this._backgrounds[state] = background;
+    }
+
+    this._invalidateLayout();
+
+    return this;
+  }
+
+  /**
+   * Override label text style on top of the skin's; `null` returns to it.
+   * Layout-invalidating - the label is re-measured and re-centered.
+   */
+  public setTextStyle(style: TextStyleOptions | null): this {
+    this._textStyle = style === null ? null : { ...this._textStyle, ...style };
+    this._appliedText = null;
+    this._invalidateLayout();
+
+    return this;
+  }
+
   private readonly _onPointerOver = (): void => {
     this._pointerInside = true;
     this._refreshState();
@@ -113,8 +213,7 @@ export class Button extends Widget {
 
   private readonly _onPointerDown = (): void => {
     if (this.effectiveEnabled) {
-      this._state = 'pressed';
-      this._draw();
+      this._setSkinState('pressed');
     }
   };
 
@@ -149,8 +248,7 @@ export class Button extends Widget {
       state = 'hover';
     }
 
-    this._state = state;
-    this._draw();
+    this._setSkinState(state);
   }
 
   protected override _onEnabledChanged(effectiveEnabled: boolean): void {
@@ -158,27 +256,45 @@ export class Button extends Widget {
     this._refreshState();
   }
 
+  protected override _repaint(): void {
+    this._applyTextStyle();
+    this._surface.apply(this.backgroundIn(), this._uiWidth, this._uiHeight);
+  }
+
   protected override _relayout(): void {
-    this._draw();
+    super._relayout();
     this._positionLabel();
   }
 
-  private _draw(): void {
-    const g = this._background;
-
-    g.clear();
+  /**
+   * Push the current state's text style into the label, skipping the re-style
+   * and re-measure when the skin is handing out the same style object it did
+   * last time - which is the common case for a state flip.
+   */
+  private _applyTextStyle(): void {
+    const skinText = resolveUISkin(this.theme.button, this._skinState).text;
 
-    if (this._uiWidth <= 0 || this._uiHeight <= 0) {
+    if (skinText === this._appliedText) {
       return;
     }
 
-    g.fillColor = this._colors[this._state];
-    g.drawRoundedRectangle(0, 0, this._uiWidth, this._uiHeight, this._cornerRadius);
+    this._appliedText = skinText;
+    this._label.style = { ...skinText, ...this._textStyle };
+    this._positionLabel();
   }
 
+  /** Center the label in the content box the skin's insets leave. */
   private _positionLabel(): void {
+    const insets = resolveUISkin(this.theme.button, this._skinState).insets;
     const bounds = this._label.getLocalBounds();
+    const contentWidth = this._uiWidth - insets.left - insets.right;
+    const contentHeight = this._uiHeight - insets.top - insets.bottom;
+
+    this._label.setPosition(insets.left + (contentWidth - bounds.width) / 2, insets.top + (contentHeight - bounds.height) / 2);
+  }
 
-    this._label.setPosition((this._uiWidth - bounds.width) / 2, (this._uiHeight - bounds.height) / 2);
+  public override destroy(): void {
+    this._surface.destroy();
+    super.destroy();
   }
 }
diff --git a/src/ui/Label.ts b/src/ui/Label.ts
index d0fce8de4..b9c06b223 100644
--- a/src/ui/Label.ts
+++ b/src/ui/Label.ts
@@ -1,4 +1,3 @@
-import { Color } from '#core/Color';
 import { Text } from '#rendering/text/Text';
 import type { TextStyleOptions } from '#rendering/text/TextStyle';
 
@@ -7,14 +6,23 @@ import { Widget } from './Widget';
 /**
  * Text label widget. Wraps a {@link Text} node and keeps the widget's layout
  * size in sync with the measured text, so it anchors and stacks correctly.
+ *
+ * The label takes its text style from the `label` role of its inherited theme;
+ * the constructor style and {@link Label.setTextStyle} override parts of it for
+ * this label only.
  */
 export class Label extends Widget {
   private readonly _text: Text;
+  private _textStyle: TextStyleOptions | null;
+  /** The skin text object last pushed into the text node, for a cheap identity check per layout. */
+  private _appliedText: TextStyleOptions;
 
   public constructor(text = '', style: TextStyleOptions = {}) {
     super();
 
-    this._text = new Text(text, { fillColor: Color.white, fontSize: 16, ...style });
+    this._textStyle = Object.keys(style).length > 0 ? { ...style } : null;
+    this._appliedText = this._skin('label').text;
+    this._text = new Text(text, { ...this._appliedText, ...this._textStyle });
     this.addChild(this._text);
     this._syncSize();
   }
@@ -35,6 +43,44 @@ export class Label extends Widget {
     return this._text;
   }
 
+  /** The text-style overrides this label carries, or `null` when it takes the skin's. */
+  public get textStyleOverrides(): TextStyleOptions | null {
+    return this._textStyle;
+  }
+
+  /**
+   * Override text style on top of the skin's; `null` returns to it. The label
+   * is re-measured, so its layout size follows the new style.
+   */
+  public setTextStyle(style: TextStyleOptions | null): this {
+    this._textStyle = style === null ? null : { ...this._textStyle, ...style };
+    this._applyTextStyle(true);
+
+    return this;
+  }
+
+  protected override _relayout(): void {
+    this._applyTextStyle(false);
+    super._relayout();
+  }
+
+  /**
+   * Push the skin's text style into the text node and resize to the new
+   * measurement. Skips the work when the skin hands out the same style object
+   * as last time, unless `force` says this label's own overrides changed.
+   */
+  private _applyTextStyle(force: boolean): void {
+    const skinText = this._skin('label').text;
+
+    if (skinText === this._appliedText && !force) {
+      return;
+    }
+
+    this._appliedText = skinText;
+    this._text.style = { ...skinText, ...this._textStyle };
+    this._syncSize();
+  }
+
   private _syncSize(): void {
     const bounds = this._text.getLocalBounds();
 
diff --git a/src/ui/Panel.ts b/src/ui/Panel.ts
index c4ffad08b..d4dc0488a 100644
--- a/src/ui/Panel.ts
+++ b/src/ui/Panel.ts
@@ -1,83 +1,133 @@
-import { Color } from '#core/Color';
-import { Graphics } from '#rendering/primitives/Graphics';
+import type { Color } from '#core/Color';
 
+import type { UIBackground, UIFillPatch } from './theme';
+import { applyUIFillPatch } from './theme';
 import { Widget } from './Widget';
+import { WidgetBackground } from './WidgetBackground';
 
 export interface PanelOptions {
   width?: number;
   height?: number;
-  /** Fill color. Default: a translucent dark slate. */
+  /** Fill color override. Default: the theme's panel fill. */
   color?: Color;
-  /** Border color (only drawn when `borderWidth > 0`). */
+  /** Border color override (only drawn when `borderWidth > 0`). */
   borderColor?: Color;
   borderWidth?: number;
   cornerRadius?: number;
+  /** Whole-background override, e.g. a nine-slice skin, replacing the theme's. */
+  background?: UIBackground;
 }
 
 /**
  * Rectangular background container with rounded corners and an optional border.
  * The base building block for HUD boxes, dialogs, and menus - add content with
  * `panel.addChild(...)`.
+ *
+ * The panel paints the `panel` role of its inherited theme. Constructor options
+ * and the setters below are per-panel overrides on top of it; each one
+ * repaints immediately.
  */
 export class Panel extends Widget {
-  private readonly _background = new Graphics();
-  private readonly _color: Color;
-  private readonly _borderColor: Color;
-  private readonly _borderWidth: number;
-  private readonly _cornerRadius: number;
+  private readonly _surface = new WidgetBackground(this, 0);
+  private _background: UIBackground | null = null;
+  private _fill: UIFillPatch | null = null;
 
   public constructor(options: PanelOptions = {}) {
     super();
 
-    this._color = (options.color ?? new Color(30, 34, 45, 0.92)).clone();
-    this._borderColor = (options.borderColor ?? new Color(255, 255, 255, 0.12)).clone();
-    this._borderWidth = options.borderWidth ?? 0;
-    this._cornerRadius = options.cornerRadius ?? 8;
+    if (options.background !== undefined) {
+      this._background = options.background;
+    }
 
-    this.addChild(this._background);
+    this._fill = fillPatchFrom(options);
     this.setSize(options.width ?? 0, options.height ?? 0);
   }
 
-  /** The background {@link Graphics}, for advanced customization. */
-  public get background(): Graphics {
-    return this._background;
+  /** The node painting the background, or `null` while it paints nothing. */
+  public get backgroundNode(): WidgetBackground['node'] {
+    return this._surface.node;
   }
 
-  /** Fill colour. */
-  public get color(): Color {
-    return this._color;
+  /** The background actually painted: this panel's overrides over its skin. */
+  public get background(): UIBackground {
+    return this._background ?? applyUIFillPatch(this._skin('panel').background, this._fill);
   }
 
-  /** Border colour (drawn only when {@link borderWidth} is greater than 0). */
-  public get borderColor(): Color {
-    return this._borderColor;
+  /** Fill colour, or `null` when the panel does not paint a fill. */
+  public get color(): Color | null {
+    const background = this.background;
+
+    return background.kind === 'fill' ? background.color : null;
+  }
+
+  /** Border colour, or `null` when the panel does not paint a fill. */
+  public get borderColor(): Color | null {
+    const background = this.background;
+
+    return background.kind === 'fill' ? background.borderColor : null;
   }
 
-  /** Border thickness in pixels. */
+  /** Border thickness in pixels; `0` when the panel does not paint a fill. */
   public get borderWidth(): number {
-    return this._borderWidth;
+    const background = this.background;
+
+    return background.kind === 'fill' ? background.borderWidth : 0;
   }
 
-  /** Corner radius in pixels. */
+  /** Corner radius in pixels; `0` when the panel does not paint a fill. */
   public get cornerRadius(): number {
-    return this._cornerRadius;
+    const background = this.background;
+
+    return background.kind === 'fill' ? background.cornerRadius : 0;
   }
 
-  protected override _relayout(): void {
-    const g = this._background;
+  /** The fill overrides this panel carries, or `null` when it takes its skin as is. */
+  public get fillOverrides(): UIFillPatch | null {
+    return this._fill;
+  }
 
-    g.clear();
+  /**
+   * Override fill properties on top of the skin. Overriding a colour on a
+   * panel whose skin paints a texture switches it to a fill. Passing `null`
+   * drops the overrides and returns the panel to its skin.
+   */
+  public setFill(patch: UIFillPatch | null): this {
+    this._fill = patch === null ? null : { ...this._fill, ...patch };
+    this._invalidatePaint();
 
-    if (this._uiWidth <= 0 || this._uiHeight <= 0) {
-      return;
-    }
+    return this;
+  }
 
-    if (this._borderWidth > 0) {
-      g.lineWidth = this._borderWidth;
-      g.lineColor = this._borderColor;
-    }
+  /**
+   * Replace the whole background descriptor, ignoring the skin's. `null`
+   * restores it. Layout-invalidating: a nine-slice and a fill can imply
+   * different content boxes.
+   */
+  public setBackground(background: UIBackground | null): this {
+    this._background = background;
+    this._invalidateLayout();
 
-    g.fillColor = this._color;
-    g.drawRoundedRectangle(0, 0, this._uiWidth, this._uiHeight, this._cornerRadius);
+    return this;
+  }
+
+  protected override _repaint(): void {
+    this._surface.apply(this.background, this._uiWidth, this._uiHeight);
+  }
+
+  public override destroy(): void {
+    this._surface.destroy();
+    super.destroy();
   }
 }
+
+/** The fill overrides a constructor options object asks for, or `null` for none. */
+const fillPatchFrom = (options: PanelOptions): UIFillPatch | null => {
+  const patch: { -readonly [Key in keyof UIFillPatch]: UIFillPatch[Key] } = {};
+
+  if (options.color !== undefined) patch.color = options.color.clone();
+  if (options.borderColor !== undefined) patch.borderColor = options.borderColor.clone();
+  if (options.borderWidth !== undefined) patch.borderWidth = options.borderWidth;
+  if (options.cornerRadius !== undefined) patch.cornerRadius = options.cornerRadius;
+
+  return Object.keys(patch).length > 0 ? patch : null;
+};
diff --git a/src/ui/ProgressBar.ts b/src/ui/ProgressBar.ts
index 605bf8c57..083fa39b4 100644
--- a/src/ui/ProgressBar.ts
+++ b/src/ui/ProgressBar.ts
@@ -1,8 +1,10 @@
-import { Color } from '#core/Color';
+import type { Color } from '#core/Color';
 import { clamp } from '#math/utils';
-import { Graphics } from '#rendering/primitives/Graphics';
 
+import type { UIBackground, UIFillPatch } from './theme';
+import { applyUIFillPatch } from './theme';
 import { Widget } from './Widget';
+import { WidgetBackground } from './WidgetBackground';
 
 export interface ProgressBarOptions {
   width?: number;
@@ -16,26 +18,27 @@ export interface ProgressBarOptions {
 
 /**
  * Horizontal progress / health bar. {@link ProgressBar.value} is the fill
- * fraction in `[0, 1]`; setting it redraws only the fill.
+ * fraction in `[0, 1]`; setting it redraws only the bar.
+ *
+ * The two surfaces are themed independently: the groove paints the
+ * `progressBarTrack` role, the bar `progressBarFill`.
  */
 export class ProgressBar extends Widget {
-  private readonly _track = new Graphics();
-  private readonly _fill = new Graphics();
-  private readonly _trackColor: Color;
-  private readonly _fillColor: Color;
-  private readonly _cornerRadius: number;
+  private readonly _track = new WidgetBackground(this, 0);
+  private readonly _bar = new WidgetBackground(this, 1);
+  private _trackBackground: UIBackground | null = null;
+  private _barBackground: UIBackground | null = null;
+  private _trackFill: UIFillPatch | null = null;
+  private _barFill: UIFillPatch | null = null;
   private _value: number;
 
   public constructor(options: ProgressBarOptions = {}) {
     super();
 
     this._value = clamp(options.value ?? 0, 0, 1);
-    this._trackColor = (options.trackColor ?? new Color(255, 255, 255, 0.16)).clone();
-    this._fillColor = (options.fillColor ?? new Color(80, 220, 120, 1)).clone();
-    this._cornerRadius = options.cornerRadius ?? 4;
+    this._trackFill = fillPatchFrom(options.trackColor, options.cornerRadius);
+    this._barFill = fillPatchFrom(options.fillColor, options.cornerRadius);
 
-    this.addChild(this._track);
-    this.addChild(this._fill);
     this.setSize(options.width ?? 200, options.height ?? 12);
   }
 
@@ -49,55 +52,100 @@ export class ProgressBar extends Widget {
 
     if (this._value !== next) {
       this._value = next;
-      this._drawFill();
+      this._paintBar();
     }
   }
 
-  /** Track (background) colour. */
-  public get trackColor(): Color {
-    return this._trackColor;
+  /** The background painted behind the bar. */
+  public get trackBackground(): UIBackground {
+    return this._trackBackground ?? applyUIFillPatch(this._skin('progressBarTrack').background, this._trackFill);
   }
 
-  /** Fill (foreground) colour. */
-  public get fillColor(): Color {
-    return this._fillColor;
+  /** The background painted for the filled portion. */
+  public get barBackground(): UIBackground {
+    return this._barBackground ?? applyUIFillPatch(this._skin('progressBarFill').background, this._barFill);
   }
 
-  /** Corner radius in pixels. */
+  /** Track colour, or `null` when the track does not paint a fill. */
+  public get trackColor(): Color | null {
+    const background = this.trackBackground;
+
+    return background.kind === 'fill' ? background.color : null;
+  }
+
+  /** Bar colour, or `null` when the bar does not paint a fill. */
+  public get fillColor(): Color | null {
+    const background = this.barBackground;
+
+    return background.kind === 'fill' ? background.color : null;
+  }
+
+  /** Corner radius in pixels of the track; `0` when it paints no fill. */
   public get cornerRadius(): number {
-    return this._cornerRadius;
+    const background = this.trackBackground;
+
+    return background.kind === 'fill' ? background.cornerRadius : 0;
   }
 
-  protected override _relayout(): void {
-    this._drawTrack();
-    this._drawFill();
+  /** The fill overrides carried by the track and the bar, `null` where none. */
+  public get fillOverrides(): { readonly track: UIFillPatch | null; readonly bar: UIFillPatch | null } {
+    return { track: this._trackFill, bar: this._barFill };
   }
 
-  private _drawTrack(): void {
-    const g = this._track;
+  /** Override fill properties of the track on top of its skin; `null` drops them. */
+  public setTrackFill(patch: UIFillPatch | null): this {
+    this._trackFill = patch === null ? null : { ...this._trackFill, ...patch };
+    this._invalidatePaint();
 
-    g.clear();
+    return this;
+  }
 
-    if (this._uiWidth <= 0 || this._uiHeight <= 0) {
-      return;
-    }
+  /** Override fill properties of the bar on top of its skin; `null` drops them. */
+  public setBarFill(patch: UIFillPatch | null): this {
+    this._barFill = patch === null ? null : { ...this._barFill, ...patch };
+    this._invalidatePaint();
 
-    g.fillColor = this._trackColor;
-    g.drawRoundedRectangle(0, 0, this._uiWidth, this._uiHeight, this._cornerRadius);
+    return this;
   }
 
-  private _drawFill(): void {
-    const g = this._fill;
+  /** Replace the track's whole background descriptor; `null` restores the skin's. */
+  public setTrackBackground(background: UIBackground | null): this {
+    this._trackBackground = background;
+    this._invalidateLayout();
 
-    g.clear();
+    return this;
+  }
 
-    const width = this._uiWidth * this._value;
+  /** Replace the bar's whole background descriptor; `null` restores the skin's. */
+  public setBarBackground(background: UIBackground | null): this {
+    this._barBackground = background;
+    this._invalidateLayout();
 
-    if (width <= 0 || this._uiHeight <= 0) {
-      return;
-    }
+    return this;
+  }
 
-    g.fillColor = this._fillColor;
-    g.drawRoundedRectangle(0, 0, width, this._uiHeight, Math.min(this._cornerRadius, width / 2));
+  protected override _repaint(): void {
+    this._track.apply(this.trackBackground, this._uiWidth, this._uiHeight);
+    this._paintBar();
+  }
+
+  private _paintBar(): void {
+    this._bar.apply(this.barBackground, this._uiWidth * this._value, this._uiHeight);
+  }
+
+  public override destroy(): void {
+    this._track.destroy();
+    this._bar.destroy();
+    super.destroy();
   }
 }
+
+/** The fill overrides a colour and radius pair asks for, or `null` for none. */
+const fillPatchFrom = (color: Color | undefined, cornerRadius: number | undefined): UIFillPatch | null => {
+  const patch: { -readonly [Key in keyof UIFillPatch]: UIFillPatch[Key] } = {};
+
+  if (color !== undefined) patch.color = color.clone();
+  if (cornerRadius !== undefined) patch.cornerRadius = cornerRadius;
+
+  return Object.keys(patch).length > 0 ? patch : null;
+};
diff --git a/src/ui/UIRoot.ts b/src/ui/UIRoot.ts
index 1e31b81ec..7b36c0031 100644
--- a/src/ui/UIRoot.ts
+++ b/src/ui/UIRoot.ts
@@ -1,8 +1,8 @@
 import { Signal } from '#core/Signal';
 import type { RenderingContext } from '#rendering/RenderingContext';
 
-import { ThemedContainer } from './ThemedContainer';
 import type { UITheme } from './theme';
+import { ThemedContainer } from './ThemedContainer';
 
 /**
  * Root of a scene's screen-fixed UI layer. Reached through {@link Scene.ui};
diff --git a/src/ui/Widget.ts b/src/ui/Widget.ts
index 98d0dd88a..077851ebb 100644
--- a/src/ui/Widget.ts
+++ b/src/ui/Widget.ts
@@ -1,9 +1,9 @@
 import { Container } from '#rendering/Container';
 import type { RenderNode } from '#rendering/RenderNode';
 
-import { ThemedContainer } from './ThemedContainer';
 import type { UISkin, UITheme, UIThemePatch, UIThemeRole, UIWidgetState } from './theme';
 import { createUITheme, resolveUISkin } from './theme';
+import { ThemedContainer } from './ThemedContainer';
 import type { UIRoot } from './UIRoot';
 
 /** Anchor position of a widget within its container's box. */
diff --git a/src/ui/WidgetBackground.ts b/src/ui/WidgetBackground.ts
new file mode 100644
index 000000000..85c478372
--- /dev/null
+++ b/src/ui/WidgetBackground.ts
@@ -0,0 +1,111 @@
+import type { Container } from '#rendering/Container';
+import { Graphics } from '#rendering/primitives/Graphics';
+import { NineSliceSprite } from '#rendering/sprite/NineSliceSprite';
+
+import type { UIBackground, UINineSliceBackground } from './theme';
+
+const sameNineSlice = (a: UINineSliceBackground, b: UINineSliceBackground): boolean =>
+  a.texture === b.texture && a.slices === b.slices && a.border === b.border && a.modes === b.modes;
+
+/**
+ * One painted widget surface. Owns whichever node the current
+ * {@link UIBackground} needs - a {@link Graphics} for a vector fill, a
+ * {@link NineSliceSprite} for a texture - and swaps it in place when the
+ * descriptor's kind changes, keeping the node at its declared child index so a
+ * widget's own content stays on top of its background.
+ *
+ * @internal
+ */
+export class WidgetBackground {
+  private readonly _owner: Container;
+  private readonly _index: number;
+  private _node: Graphics | NineSliceSprite | null = null;
+  private _painted: UIBackground | null = null;
+
+  /**
+   * `index` is the child slot this surface claims in `owner`. It is honoured on
+   * every (re)insertion, so a background that was dropped - zero size, or a
+   * `'none'` skin - comes back underneath the widget's content instead of on
+   * top of it.
+   */
+  public constructor(owner: Container, index: number) {
+    this._owner = owner;
+    this._index = index;
+  }
+
+  /** The live node, or `null` while the background paints nothing. */
+  public get node(): Graphics | NineSliceSprite | null {
+    return this._node;
+  }
+
+  /** Paint `background` at `width` x `height`, replacing whatever was there. */
+  public apply(background: UIBackground, width: number, height: number): void {
+    if (background.kind === 'none' || width <= 0 || height <= 0) {
+      this._replaceNode(null);
+      this._painted = background;
+
+      return;
+    }
+
+    if (background.kind === 'fill') {
+      const graphics = this._node instanceof Graphics ? this._node : this._replaceNode(new Graphics());
+
+      graphics.clear();
+
+      if (background.borderWidth > 0) {
+        graphics.lineWidth = background.borderWidth;
+        graphics.lineColor = background.borderColor;
+      }
+
+      graphics.fillColor = background.color;
+      graphics.drawRoundedRectangle(0, 0, width, height, background.cornerRadius);
+    } else {
+      // The sampled region, slice widths and fill modes are constructor-only on
+      // `NineSliceSprite`, so a descriptor that changes any of them needs a new
+      // sprite rather than an in-place update.
+      const reusable =
+        this._node instanceof NineSliceSprite && this._painted !== null && this._painted.kind === 'nineSlice' && sameNineSlice(this._painted, background);
+      const sprite = reusable
+        ? (this._node as NineSliceSprite)
+        : this._replaceNode(
+            new NineSliceSprite(background.texture, {
+              slices: background.slices,
+              width,
+              height,
+              ...(background.border !== undefined && { border: background.border }),
+              ...(background.modes !== undefined && { modes: background.modes }),
+            }),
+          );
+
+      sprite.setSize(width, height);
+    }
+
+    this._painted = background;
+  }
+
+  public destroy(): void {
+    this._replaceNode(null);
+    this._painted = null;
+  }
+
+  /** Swap the painted node, re-inserting the replacement at the declared slot. */
+  private _replaceNode<T extends Graphics | NineSliceSprite | null>(next: T): T {
+    const previous = this._node;
+
+    if (previous === next) {
+      return next;
+    }
+
+    if (previous !== null) {
+      previous.destroy();
+    }
+
+    if (next !== null) {
+      this._owner.addChildAt(next, Math.min(this._index, this._owner.children.length));
+    }
+
+    this._node = next;
+
+    return next;
+  }
+}
diff --git a/src/ui/index.ts b/src/ui/index.ts
index e627209c8..54674c704 100644
--- a/src/ui/index.ts
+++ b/src/ui/index.ts
@@ -1,4 +1,4 @@
-export type { ButtonOptions } from './Button';
+export type { ButtonOptions, ButtonState } from './Button';
 export { Button } from './Button';
 export { Label } from './Label';
 export type { PanelOptions } from './Panel';
@@ -9,6 +9,24 @@ export type { ScrollContainerOptions, ScrollDirection } from './ScrollContainer'
 export { ScrollContainer } from './ScrollContainer';
 export type { StackDirection, StackOptions } from './Stack';
 export { Stack } from './Stack';
+export type {
+  UIBackground,
+  UIFillBackground,
+  UIFillPatch,
+  UIInsets,
+  UINineSliceBackground,
+  UINoBackground,
+  UISkin,
+  UISkinPatch,
+  UISkinSet,
+  UISkinSetPatch,
+  UITheme,
+  UIThemePatch,
+  UIThemeRole,
+  UIWidgetState,
+} from './theme';
+export { createUITheme, defaultUITheme, resolveUISkin } from './theme';
+export { ThemedContainer } from './ThemedContainer';
 export type { TooltipOptions } from './Tooltip';
 export { Tooltip } from './Tooltip';
 export { UIRoot } from './UIRoot';
diff --git a/src/ui/theme.ts b/src/ui/theme.ts
index b12f3b5ab..5c9318332 100644
--- a/src/ui/theme.ts
+++ b/src/ui/theme.ts
@@ -69,7 +69,7 @@ export interface UISkin {
  * One skin per state. Only `normal` is required - {@link resolveUISkin} falls
  * back to it for every state a set does not define.
  */
-export type UISkinSet = { readonly normal: UISkin } & { readonly [State in Exclude<UIWidgetState, 'normal'>]?: UISkin };
+export type UISkinSet = { readonly normal: UISkin } & Partial<Readonly<Record<Exclude<UIWidgetState, 'normal'>, UISkin>>>;
 
 /**
  * A themed surface. Roles are per painted surface, not per widget class: a
@@ -78,21 +78,29 @@ export type UISkinSet = { readonly normal: UISkin } & { readonly [State in Exclu
 export type UIThemeRole = 'panel' | 'button' | 'label' | 'progressBarTrack' | 'progressBarFill';
 
 /** Skins for every role, as resolved for a widget. */
-export type UITheme = { readonly [Role in UIThemeRole]: UISkinSet };
+export type UITheme = Readonly<Record<UIThemeRole, UISkinSet>>;
 
 /** Skin fields to override; an omitted field keeps the inherited one. */
 export type UISkinPatch = Partial<UISkin>;
 
 /** Per-state skin overrides. */
-export type UISkinSetPatch = { readonly [State in UIWidgetState]?: UISkinPatch };
+export type UISkinSetPatch = Partial<Readonly<Record<UIWidgetState, UISkinPatch>>>;
 
 /**
  * Theme overrides applied on top of an inherited theme. Fields are replaced
  * whole: naming `background` replaces the entire descriptor, since blending
  * half a fill into a nine-slice has no meaning. Single-property tweaks belong
- * on the widget (`panel.color = ...`), not in a theme patch.
+ * on the widget (`panel.setFill({ color })`), not in a theme patch.
  */
-export type UIThemePatch = { readonly [Role in UIThemeRole]?: UISkinSetPatch };
+export type UIThemePatch = Partial<Readonly<Record<UIThemeRole, UISkinSetPatch>>>;
+
+/** Fill properties to override on a widget's background; omitted ones keep the skin's value. */
+export interface UIFillPatch {
+  readonly color?: Color;
+  readonly borderColor?: Color;
+  readonly borderWidth?: number;
+  readonly cornerRadius?: number;
+}
 
 const zeroInsets: UIInsets = { left: 0, top: 0, right: 0, bottom: 0 };
 
@@ -135,6 +143,31 @@ export const defaultUITheme: UITheme = {
   },
 };
 
+const neutralFill: UIFillBackground = fill(new Color(0, 0, 0, 0), 0, new Color(0, 0, 0, 0), 0);
+
+/**
+ * Apply a widget's fill overrides on top of the background its skin provides.
+ * A patched skin that does not paint a fill (a nine-slice, or nothing) becomes
+ * one: the caller asked for a colour, so they get a colour.
+ *
+ * @internal
+ */
+export const applyUIFillPatch = (background: UIBackground, patch: UIFillPatch | null): UIBackground => {
+  if (patch === null) {
+    return background;
+  }
+
+  const base = background.kind === 'fill' ? background : neutralFill;
+
+  return {
+    kind: 'fill',
+    color: patch.color ?? base.color,
+    borderColor: patch.borderColor ?? base.borderColor,
+    borderWidth: patch.borderWidth ?? base.borderWidth,
+    cornerRadius: patch.cornerRadius ?? base.cornerRadius,
+  };
+};
+
 /** The skin a state paints with, falling back to `normal` where undefined. */
 export const resolveUISkin = (set: UISkinSet, state: UIWidgetState): UISkin => set[state] ?? set.normal;
 
@@ -145,7 +178,7 @@ const mergeSkin = (base: UISkin, patch: UISkinPatch): UISkin => ({
 });
 
 const mergeSkinSet = (base: UISkinSet, patch: UISkinSetPatch): UISkinSet => {
-  const merged: { normal: UISkin } & { [State in Exclude<UIWidgetState, 'normal'>]?: UISkin } = { ...base };
+  const merged: { normal: UISkin } & Partial<Record<Exclude<UIWidgetState, 'normal'>, UISkin>> = { ...base };
 
   for (const state of Object.keys(patch) as UIWidgetState[]) {
     const skinPatch = patch[state];
@@ -206,7 +239,7 @@ if (__DEV__) {
   };
 
   for (const set of Object.values(defaultUITheme)) {
-    for (const stateSkin of Object.values(set) as UISkin[]) {
+    for (const stateSkin of Object.values(set)) {
       freezeBackground(stateSkin.background);
 
       if (stateSkin.text.fillColor !== undefined) {
diff --git a/test/core/serialization.test.ts b/test/core/serialization.test.ts
index 0582c0c93..1f7aaa820 100644
--- a/test/core/serialization.test.ts
+++ b/test/core/serialization.test.ts
@@ -846,7 +846,7 @@ describe('serialization — UI widgets', () => {
     const restored = deserializeTree(data) as Panel;
     expect(restored.uiWidth).toBe(120);
     expect(restored.borderWidth).toBe(2);
-    const userChildren = restored.children.filter(child => child !== restored.background);
+    const userChildren = restored.children.filter(child => child !== restored.backgroundNode);
     expect(userChildren).toHaveLength(1);
     expect(userChildren[0].name).toBe('content');
   });
diff --git a/test/ui/widgets.test.ts b/test/ui/widgets.test.ts
index 9eb9993fb..bd66b5992 100644
--- a/test/ui/widgets.test.ts
+++ b/test/ui/widgets.test.ts
@@ -2,16 +2,21 @@ import { Color } from '#core/Color';
 import { KeyEvent } from '#input/KeyEvent';
 import { Keyboard } from '#input/types';
 import { Rectangle } from '#math/Rectangle';
+import { Container } from '#rendering/Container';
 import { Graphics } from '#rendering/primitives/Graphics';
+import { NineSliceSprite } from '#rendering/sprite/NineSliceSprite';
 import type { GlyphAtlas } from '#rendering/text/GlyphAtlas';
 import type { GlyphAtlasPool } from '#rendering/text/GlyphAtlasPool';
 import { resetDefaultGlyphAtlasPool } from '#rendering/text/GlyphAtlasPool';
 import type { GlyphInfo } from '#rendering/text/types';
+import type { Texture } from '#rendering/texture/Texture';
 import { Button } from '#ui/Button';
 import { Label } from '#ui/Label';
 import { Panel } from '#ui/Panel';
 import { ProgressBar } from '#ui/ProgressBar';
 import { Stack } from '#ui/Stack';
+import type { UITheme } from '#ui/theme';
+import { createUITheme } from '#ui/theme';
 import { UIRoot } from '#ui/UIRoot';
 
 // Text (used by Label/Button) needs a glyph atlas; inject a deterministic mock
@@ -66,14 +71,15 @@ describe('Panel', () => {
     expect(panel.borderWidth).toBe(0);
   });
 
-  test('exposes background, color, borderColor, borderWidth, cornerRadius getters', () => {
+  test('exposes its painted node and the fill values in effect', () => {
     const color = new Color(10, 20, 30, 1);
     const borderColor = new Color(1, 2, 3, 1);
     const panel = new Panel({ width: 100, height: 50, color, borderColor, borderWidth: 3, cornerRadius: 12 });
 
-    expect(panel.background).toBeInstanceOf(Graphics);
-    expect(panel.color.r).toBe(10);
-    expect(panel.borderColor.r).toBe(1);
+    expect(panel.backgroundNode).toBeInstanceOf(Graphics);
+    expect(panel.background.kind).toBe('fill');
+    expect(panel.color?.r).toBe(10);
+    expect(panel.borderColor?.r).toBe(1);
     expect(panel.borderWidth).toBe(3);
     expect(panel.cornerRadius).toBe(12);
   });
@@ -394,3 +400,120 @@ describe('Stack', () => {
     expect(stack.uiHeight).toBe(20);
   });
 });
+
+// ── Skins, themes and controlled setters ─────────────────────────────────────
+
+const textureStub = (): Texture =>
+  ({
+    width: 128,
+    height: 64,
+    version: 1,
+    source: null,
+    addDestroyListener: () => undefined,
+    removeDestroyListener: () => undefined,
+  }) as unknown as Texture;
+
+const themeWith = (color: Color): UITheme =>
+  createUITheme({ panel: { normal: { background: { kind: 'fill', color, borderColor: Color.black, borderWidth: 0, cornerRadius: 2 } } } });
+
+describe('widget skins', () => {
+  test('a panel paints the theme it inherits and follows a later theme change', () => {
+    const root = new UIRoot();
+    const panel = new Panel({ width: 40, height: 20 });
+
+    root.addChild(panel);
+    root.theme = themeWith(new Color(9, 8, 7, 1));
+
+    expect(panel.color?.r).toBe(9);
+    expect(panel.cornerRadius).toBe(2);
+    expect(panel.backgroundNode).toBeInstanceOf(Graphics);
+  });
+
+  test('a panel override wins over the theme and repaints', () => {
+    const root = new UIRoot();
+    const panel = new Panel({ width: 40, height: 20 });
+
+    root.addChild(panel);
+    root.theme = themeWith(new Color(9, 8, 7, 1));
+    panel.setFill({ color: new Color(1, 1, 1, 1) });
+
+    expect(panel.color?.r).toBe(1);
+    expect(panel.fillOverrides?.color?.r).toBe(1);
+
+    panel.setFill(null);
+
+    expect(panel.color?.r).toBe(9);
+  });
+
+  test('a texture skin swaps the painted node and keeps it below the content', () => {
+    const panel = new Panel({ width: 40, height: 20 });
+    const content = new Container();
+
+    panel.addChild(content);
+    panel.setBackground({ kind: 'nineSlice', texture: textureStub(), slices: 4 });
+
+    expect(panel.backgroundNode).toBeInstanceOf(NineSliceSprite);
+    expect(panel.children[0]).toBe(panel.backgroundNode);
+
+    panel.setBackground(null);
+
+    expect(panel.backgroundNode).toBeInstanceOf(Graphics);
+    expect(panel.children[0]).toBe(panel.backgroundNode);
+  });
+
+  test('a button resolves a skin per state and overrides one state at a time', () => {
+    const button = new Button({ width: 80, height: 30 });
+
+    expect(button.state).toBe('normal');
+    expect(button.colors.hover?.r).toBe(74);
+
+    button.setFill({ color: new Color(3, 3, 3, 1) }, 'hover');
+
+    expect(button.colors.hover?.r).toBe(3);
+    expect(button.colors.normal?.r).toBe(54);
+  });
+
+  test('a disabled button paints its disabled skin', () => {
+    const button = new Button({ width: 80, height: 30 });
+
+    button.enabled = false;
+
+    expect(button.state).toBe('disabled');
+    expect(button.colors.disabled?.r).toBe(70);
+  });
+
+  test('a button follows the theme text style and re-centers the label', () => {
+    const root = new UIRoot();
+    const button = new Button({ width: 80, height: 30, label: 'Go' });
+
+    root.addChild(button);
+    root.theme = createUITheme({ button: { normal: { text: { fontSize: 32 } } } });
+
+    expect(button.fontSize).toBe(32);
+  });
+
+  test('a label takes its style from the theme and re-measures on an override', () => {
+    const root = new UIRoot();
+    const label = new Label('Score');
+
+    root.addChild(label);
+    root.theme = createUITheme({ label: { normal: { text: { fontSize: 40 } } } });
+
+    expect(label.textNode.style.fontSize).toBe(40);
+
+    label.setTextStyle({ fontSize: 8 });
+
+    expect(label.textNode.style.fontSize).toBe(8);
+    expect(label.textStyleOverrides?.fontSize).toBe(8);
+  });
+
+  test('a progress bar themes its track and its bar independently', () => {
+    const bar = new ProgressBar({ width: 100, height: 10, value: 0.5 });
+
+    bar.setTrackFill({ color: new Color(2, 2, 2, 1) });
+
+    expect(bar.trackColor?.r).toBe(2);
+    expect(bar.fillColor?.r).toBe(80);
+    expect(bar.fillOverrides.bar).toBeNull();
+  });
+});

From e086aefb40bb3fcfc7b4af1e61693e6fd5ced9f4 Mon Sep 17 00:00:00 2001
From: Exoridus <github@codexo.de>
Date: Thu, 27 Aug 2026 21:34:55 +0200
Subject: [PATCH 4/6] docs(api): regenerate the API reference for the UI theme
 surface

Adds the skin and theme types, `ThemedContainer`, and the widgets' new
style accessors; refreshes the public export snapshots.
---
 site/src/content/api/button-state.json        |   87 +
 site/src/content/api/button.json              | 1412 +++++--
 site/src/content/api/functions.json           |  163 +-
 site/src/content/api/label.json               |  722 +++-
 site/src/content/api/panel-options.json       |   33 +-
 site/src/content/api/panel.json               |  846 +++-
 site/src/content/api/progress-bar.json        | 1021 ++++-
 site/src/content/api/scroll-container.json    |  581 ++-
 site/src/content/api/stack.json               |  581 ++-
 site/src/content/api/themed-container.json    | 3556 +++++++++++++++++
 site/src/content/api/uibackground.json        |   79 +
 site/src/content/api/uifill-background.json   |  155 +
 site/src/content/api/uifill-patch.json        |  150 +
 site/src/content/api/uiinsets.json            |  134 +
 .../content/api/uinine-slice-background.json  |  211 +
 site/src/content/api/uino-background.json     |   71 +
 site/src/content/api/uiroot.json              |   90 +-
 site/src/content/api/uiskin-patch.json        |   75 +
 site/src/content/api/uiskin-set-patch.json    |  107 +
 site/src/content/api/uiskin-set.json          |  151 +
 site/src/content/api/uiskin.json              |  113 +
 site/src/content/api/uitheme-patch.json       |  107 +
 site/src/content/api/uitheme-role.json        |   95 +
 site/src/content/api/uitheme.json             |   95 +
 site/src/content/api/uiwidget-state.json      |   95 +
 site/src/content/api/widget.json              |  586 ++-
 .../root-index-snapshot.test.ts.snap          |    4 +
 .../root-index-type-inventory.test.ts.snap    |   19 +
 28 files changed, 10954 insertions(+), 385 deletions(-)
 create mode 100644 site/src/content/api/button-state.json
 create mode 100644 site/src/content/api/themed-container.json
 create mode 100644 site/src/content/api/uibackground.json
 create mode 100644 site/src/content/api/uifill-background.json
 create mode 100644 site/src/content/api/uifill-patch.json
 create mode 100644 site/src/content/api/uiinsets.json
 create mode 100644 site/src/content/api/uinine-slice-background.json
 create mode 100644 site/src/content/api/uino-background.json
 create mode 100644 site/src/content/api/uiskin-patch.json
 create mode 100644 site/src/content/api/uiskin-set-patch.json
 create mode 100644 site/src/content/api/uiskin-set.json
 create mode 100644 site/src/content/api/uiskin.json
 create mode 100644 site/src/content/api/uitheme-patch.json
 create mode 100644 site/src/content/api/uitheme-role.json
 create mode 100644 site/src/content/api/uitheme.json
 create mode 100644 site/src/content/api/uiwidget-state.json

diff --git a/site/src/content/api/button-state.json b/site/src/content/api/button-state.json
new file mode 100644
index 000000000..3ae7c6901
--- /dev/null
+++ b/site/src/content/api/button-state.json
@@ -0,0 +1,87 @@
+{
+  "title": "ButtonState",
+  "description": "The states a button paints in.",
+  "symbol": "ButtonState",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "The states a button paints in."
+      ],
+      "importLine": "import { ButtonState } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "ButtonState",
+          "signature": "\"disabled\" | \"hover\" | \"normal\" | \"pressed\"",
+          "signatureTokens": [
+            {
+              "text": "\"disabled\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"hover\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"normal\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"pressed\"",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/Button.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/Button.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/Button.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/Button.ts"
+}
diff --git a/site/src/content/api/button.json b/site/src/content/api/button.json
index a2aef64de..9d715c6fb 100644
--- a/site/src/content/api/button.json
+++ b/site/src/content/api/button.json
@@ -1,16 +1,16 @@
 {
   "title": "Button",
-  "description": "Clickable button with a rounded background, a centered label, hover/pressed visual states, and keyboard activation (Enter / Space while focused). Listen to Button.onClick for activation.",
+  "description": "Clickable button with a rounded background, a centered label, hover/pressed visual states, and keyboard activation (Enter / Space while focused). Listen to Button.onClick for activation. The button paints the `button` role of its inherited theme, one skin per state. Constructor options and the setters below are per-button overrides on top of that skin.",
   "symbol": "Button",
   "kind": "class",
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 108,
+  "memberCount": 127,
   "counts": {
     "constructors": 1,
-    "methods": 46,
-    "properties": 46,
+    "methods": 60,
+    "properties": 51,
     "events": 15
   },
   "sections": [
@@ -19,7 +19,8 @@
       "title": "Import",
       "members": [],
       "paragraphs": [
-        "Clickable button with a rounded background, a centered label, hover/pressed visual states, and keyboard activation (Enter / Space while focused). Listen to Button.onClick for activation."
+        "Clickable button with a rounded background, a centered label, hover/pressed visual states, and keyboard activation (Enter / Space while focused). Listen to Button.onClick for activation.",
+        "The button paints the `button` role of its inherited theme, one skin per state. Constructor options and the setters below are per-button overrides on top of that skin."
       ],
       "importLine": "import { Button } from '@codexo/exojs'",
       "sourceLink": null
@@ -152,6 +153,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(effectiveEnabled: boolean): void",
@@ -199,6 +287,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -226,7 +343,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -546,17 +815,29 @@
           "description": "Anchor this widget within root's screen box at anchor, offset by (offsetX, offsetY). The position is recomputed whenever the screen resizes. E.g. widget.anchorIn(scene.ui, 'bottom-right', -20, -20) pins it to the bottom-right corner with a 20px margin."
         },
         {
-          "name": "blur",
-          "signature": "blur(): this",
+          "name": "backgroundIn",
+          "signature": "backgroundIn(state: UIWidgetState): UIBackground",
           "signatureTokens": [
             {
-              "text": "blur",
+              "text": "backgroundIn",
               "kind": "name"
             },
             {
               "text": "(",
               "kind": "punctuation"
             },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
             {
               "text": ")",
               "kind": "punctuation"
@@ -566,20 +847,26 @@
               "kind": "punctuation"
             },
             {
-              "text": "this",
-              "kind": "keyword"
+              "text": "UIBackground",
+              "kind": "type"
             }
           ],
-          "params": [],
-          "returnType": "this",
-          "description": "Release keyboard focus from this node if it currently holds it."
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "UIBackground",
+          "description": "The background painted in state: this button's overrides over its skin."
         },
         {
-          "name": "clearFilters",
-          "signature": "clearFilters(): this",
+          "name": "blur",
+          "signature": "blur(): this",
           "signatureTokens": [
             {
-              "text": "clearFilters",
+              "text": "blur",
               "kind": "name"
             },
             {
@@ -601,7 +888,36 @@
           ],
           "params": [],
           "returnType": "this",
-          "description": ""
+          "description": "Release keyboard focus from this node if it currently holds it."
+        },
+        {
+          "name": "clearFilters",
+          "signature": "clearFilters(): this",
+          "signatureTokens": [
+            {
+              "text": "clearFilters",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": ""
         },
         {
           "name": "collidesWith",
@@ -755,6 +1071,61 @@
           "returnType": "void",
           "description": "Destroy this container and every node beneath it. Ownership is by containment: detaching a subtree only unlinks it, so the descendants' GPU-backed resources (cached textures, filters, render textures) and signal listeners would outlive the tree that owned them and leak on every scene change."
         },
+        {
+          "name": "fillOverridesIn",
+          "signature": "fillOverridesIn(state: UIWidgetState): UIFillPatch | null",
+          "signatureTokens": [
+            {
+              "text": "fillOverridesIn",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "UIFillPatch | null",
+          "description": "The fill overrides carried for state, or null when it takes its skin as is."
+        },
         {
           "name": "focus",
           "signature": "focus(): this",
@@ -1422,11 +1793,435 @@
               "kind": "name"
             },
             {
-              "text": "(",
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "removeChildren",
+          "signature": "removeChildren(begin: number, end: number): this",
+          "signatureTokens": [
+            {
+              "text": "removeChildren",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "begin",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "end",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "begin",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "end",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Remove children in the half-open range [begin, end). Defaults to the entire child list. Throws if the range is invalid."
+        },
+        {
+          "name": "removeFilter",
+          "signature": "removeFilter(filter: Filter): this",
+          "signatureTokens": [
+            {
+              "text": "removeFilter",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "filter",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Filter",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "filter",
+              "type": "Filter",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "render",
+          "signature": "render(backend: RenderBackend): this",
+          "signatureTokens": [
+            {
+              "text": "render",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "backend",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderBackend",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "backend",
+              "type": "RenderBackend",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Raw rendering entry point. Direct backend access - bypasses the RenderPlan pipeline machinery. Prefer the high-level RenderingContext.render path via the owning RenderingContext wherever possible."
+        },
+        {
+          "name": "rotate",
+          "signature": "rotate(degrees: number): this",
+          "signatureTokens": [
+            {
+              "text": "rotate",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "degrees",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "degrees",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setBackground",
+          "signature": "setBackground(background: UIBackground | null, state: UIWidgetState): this",
+          "signatureTokens": [
+            {
+              "text": "setBackground",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "background",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "background",
+              "type": "UIBackground | null",
+              "optional": false
+            },
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Replace one state's whole background descriptor; null restores the skin's."
+        },
+        {
+          "name": "setChildIndex",
+          "signature": "setChildIndex(child: RenderNode, index: number): this",
+          "signatureTokens": [
+            {
+              "text": "setChildIndex",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setFill",
+          "signature": "setFill(patch: UIFillPatch | null, state: UIWidgetState): this",
+          "signatureTokens": [
+            {
+              "text": "setFill",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
               "kind": "punctuation"
             },
             {
-              "text": "index",
+              "text": "state",
               "kind": "param"
             },
             {
@@ -1434,8 +2229,8 @@
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
+              "text": "UIWidgetState",
+              "kind": "type"
             },
             {
               "text": ")",
@@ -1452,20 +2247,25 @@
           ],
           "params": [
             {
-              "name": "index",
-              "type": "number",
+              "name": "patch",
+              "type": "UIFillPatch | null",
+              "optional": false
+            },
+            {
+              "name": "state",
+              "type": "UIWidgetState",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Override fill properties for one state on top of its skin. null drops that state's overrides."
         },
         {
-          "name": "removeChildren",
-          "signature": "removeChildren(begin: number, end: number): this",
+          "name": "setOrigin",
+          "signature": "setOrigin(x: number, y: number): this",
           "signatureTokens": [
             {
-              "text": "removeChildren",
+              "text": "setOrigin",
               "kind": "name"
             },
             {
@@ -1473,7 +2273,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "begin",
+              "text": "x",
               "kind": "param"
             },
             {
@@ -1489,7 +2289,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "end",
+              "text": "y",
               "kind": "param"
             },
             {
@@ -1515,25 +2315,25 @@
           ],
           "params": [
             {
-              "name": "begin",
+              "name": "x",
               "type": "number",
               "optional": false
             },
             {
-              "name": "end",
+              "name": "y",
               "type": "number",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": "Remove children in the half-open range [begin, end). Defaults to the entire child list. Throws if the range is invalid."
+          "description": ""
         },
         {
-          "name": "removeFilter",
-          "signature": "removeFilter(filter: Filter): this",
+          "name": "setPosition",
+          "signature": "setPosition(x: number, y: number): this",
           "signatureTokens": [
             {
-              "text": "removeFilter",
+              "text": "setPosition",
               "kind": "name"
             },
             {
@@ -1541,7 +2341,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "filter",
+              "text": "x",
               "kind": "param"
             },
             {
@@ -1549,46 +2349,15 @@
               "kind": "punctuation"
             },
             {
-              "text": "Filter",
-              "kind": "type"
-            },
-            {
-              "text": ")",
-              "kind": "punctuation"
-            },
-            {
-              "text": ": ",
-              "kind": "punctuation"
-            },
-            {
-              "text": "this",
+              "text": "number",
               "kind": "keyword"
-            }
-          ],
-          "params": [
-            {
-              "name": "filter",
-              "type": "Filter",
-              "optional": false
-            }
-          ],
-          "returnType": "this",
-          "description": ""
-        },
-        {
-          "name": "render",
-          "signature": "render(backend: RenderBackend): this",
-          "signatureTokens": [
-            {
-              "text": "render",
-              "kind": "name"
             },
             {
-              "text": "(",
+              "text": ", ",
               "kind": "punctuation"
             },
             {
-              "text": "backend",
+              "text": "y",
               "kind": "param"
             },
             {
@@ -1596,8 +2365,8 @@
               "kind": "punctuation"
             },
             {
-              "text": "RenderBackend",
-              "kind": "type"
+              "text": "number",
+              "kind": "keyword"
             },
             {
               "text": ")",
@@ -1614,20 +2383,25 @@
           ],
           "params": [
             {
-              "name": "backend",
-              "type": "RenderBackend",
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": "Raw rendering entry point. Direct backend access - bypasses the RenderPlan pipeline machinery. Prefer the high-level RenderingContext.render path via the owning RenderingContext wherever possible."
+          "description": ""
         },
         {
-          "name": "rotate",
-          "signature": "rotate(degrees: number): this",
+          "name": "setRotation",
+          "signature": "setRotation(degrees: number): this",
           "signatureTokens": [
             {
-              "text": "rotate",
+              "text": "setRotation",
               "kind": "name"
             },
             {
@@ -1670,11 +2444,11 @@
           "description": ""
         },
         {
-          "name": "setChildIndex",
-          "signature": "setChildIndex(child: RenderNode, index: number): this",
+          "name": "setScale",
+          "signature": "setScale(x: number, y: number): this",
           "signatureTokens": [
             {
-              "text": "setChildIndex",
+              "text": "setScale",
               "kind": "name"
             },
             {
@@ -1682,7 +2456,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "child",
+              "text": "x",
               "kind": "param"
             },
             {
@@ -1690,15 +2464,15 @@
               "kind": "punctuation"
             },
             {
-              "text": "RenderNode",
-              "kind": "type"
+              "text": "number",
+              "kind": "keyword"
             },
             {
               "text": ", ",
               "kind": "punctuation"
             },
             {
-              "text": "index",
+              "text": "y",
               "kind": "param"
             },
             {
@@ -1724,12 +2498,12 @@
           ],
           "params": [
             {
-              "name": "child",
-              "type": "RenderNode",
+              "name": "x",
+              "type": "number",
               "optional": false
             },
             {
-              "name": "index",
+              "name": "y",
               "type": "number",
               "optional": false
             }
@@ -1738,11 +2512,11 @@
           "description": ""
         },
         {
-          "name": "setOrigin",
-          "signature": "setOrigin(x: number, y: number): this",
+          "name": "setSize",
+          "signature": "setSize(width: number, height: number): this",
           "signatureTokens": [
             {
-              "text": "setOrigin",
+              "text": "setSize",
               "kind": "name"
             },
             {
@@ -1750,7 +2524,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "x",
+              "text": "width",
               "kind": "param"
             },
             {
@@ -1766,7 +2540,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "y",
+              "text": "height",
               "kind": "param"
             },
             {
@@ -1792,25 +2566,25 @@
           ],
           "params": [
             {
-              "name": "x",
+              "name": "width",
               "type": "number",
               "optional": false
             },
             {
-              "name": "y",
+              "name": "height",
               "type": "number",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Set the widget's layout size; triggers a redraw and re-anchors if anchored."
         },
         {
-          "name": "setPosition",
-          "signature": "setPosition(x: number, y: number): this",
+          "name": "setSkew",
+          "signature": "setSkew(x: number, y: number): this",
           "signatureTokens": [
             {
-              "text": "setPosition",
+              "text": "setSkew",
               "kind": "name"
             },
             {
@@ -1874,11 +2648,11 @@
           "description": ""
         },
         {
-          "name": "setRotation",
-          "signature": "setRotation(degrees: number): this",
+          "name": "setTextStyle",
+          "signature": "setTextStyle(style: TextStyleOptions | null): this",
           "signatureTokens": [
             {
-              "text": "setRotation",
+              "text": "setTextStyle",
               "kind": "name"
             },
             {
@@ -1886,7 +2660,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "degrees",
+              "text": "style",
               "kind": "param"
             },
             {
@@ -1894,7 +2668,15 @@
               "kind": "punctuation"
             },
             {
-              "text": "number",
+              "text": "TextStyleOptions",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
               "kind": "keyword"
             },
             {
@@ -1912,20 +2694,20 @@
           ],
           "params": [
             {
-              "name": "degrees",
-              "type": "number",
+              "name": "style",
+              "type": "TextStyleOptions | null",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Override label text style on top of the skin's; null returns to it. Layout-invalidating - the label is re-measured and re-centered."
         },
         {
-          "name": "setScale",
-          "signature": "setScale(x: number, y: number): this",
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
           "signatureTokens": [
             {
-              "text": "setScale",
+              "text": "setTheme",
               "kind": "name"
             },
             {
@@ -1933,7 +2715,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "x",
+              "text": "patch",
               "kind": "param"
             },
             {
@@ -1941,159 +2723,115 @@
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
+              "text": "Partial",
+              "kind": "type"
             },
             {
-              "text": ", ",
+              "text": "<",
               "kind": "punctuation"
             },
             {
-              "text": "y",
-              "kind": "param"
+              "text": "Readonly",
+              "kind": "type"
             },
             {
-              "text": ": ",
+              "text": "<",
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
-            },
-            {
-              "text": ")",
-              "kind": "punctuation"
+              "text": "Record",
+              "kind": "type"
             },
             {
-              "text": ": ",
+              "text": "<",
               "kind": "punctuation"
             },
             {
-              "text": "this",
-              "kind": "keyword"
-            }
-          ],
-          "params": [
-            {
-              "name": "x",
-              "type": "number",
-              "optional": false
-            },
-            {
-              "name": "y",
-              "type": "number",
-              "optional": false
-            }
-          ],
-          "returnType": "this",
-          "description": ""
-        },
-        {
-          "name": "setSize",
-          "signature": "setSize(width: number, height: number): this",
-          "signatureTokens": [
-            {
-              "text": "setSize",
-              "kind": "name"
+              "text": "UIThemeRole",
+              "kind": "type"
             },
             {
-              "text": "(",
+              "text": ", ",
               "kind": "punctuation"
             },
             {
-              "text": "width",
-              "kind": "param"
+              "text": "Partial",
+              "kind": "type"
             },
             {
-              "text": ": ",
+              "text": "<",
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
+              "text": "Readonly",
+              "kind": "type"
             },
             {
-              "text": ", ",
+              "text": "<",
               "kind": "punctuation"
             },
             {
-              "text": "height",
-              "kind": "param"
+              "text": "Record",
+              "kind": "type"
             },
             {
-              "text": ": ",
+              "text": "<",
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
-            },
-            {
-              "text": ")",
-              "kind": "punctuation"
+              "text": "UIWidgetState",
+              "kind": "type"
             },
             {
-              "text": ": ",
+              "text": ", ",
               "kind": "punctuation"
             },
             {
-              "text": "this",
-              "kind": "keyword"
-            }
-          ],
-          "params": [
-            {
-              "name": "width",
-              "type": "number",
-              "optional": false
-            },
-            {
-              "name": "height",
-              "type": "number",
-              "optional": false
-            }
-          ],
-          "returnType": "this",
-          "description": "Set the widget's layout size; triggers a redraw and re-anchors if anchored."
-        },
-        {
-          "name": "setSkew",
-          "signature": "setSkew(x: number, y: number): this",
-          "signatureTokens": [
+              "text": "Partial",
+              "kind": "type"
+            },
             {
-              "text": "setSkew",
-              "kind": "name"
+              "text": "<",
+              "kind": "punctuation"
             },
             {
-              "text": "(",
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
               "kind": "punctuation"
             },
             {
-              "text": "x",
-              "kind": "param"
+              "text": ">",
+              "kind": "punctuation"
             },
             {
-              "text": ": ",
+              "text": ">",
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
+              "text": ">",
+              "kind": "punctuation"
             },
             {
-              "text": ", ",
+              "text": ">",
               "kind": "punctuation"
             },
             {
-              "text": "y",
-              "kind": "param"
+              "text": ">",
+              "kind": "punctuation"
             },
             {
-              "text": ": ",
+              "text": ">",
               "kind": "punctuation"
             },
             {
-              "text": "number",
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
               "kind": "keyword"
             },
             {
@@ -2111,18 +2849,13 @@
           ],
           "params": [
             {
-              "name": "x",
-              "type": "number",
-              "optional": false
-            },
-            {
-              "name": "y",
-              "type": "number",
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
         },
         {
           "name": "swapChildren",
@@ -2682,7 +3415,7 @@
         },
         {
           "name": "colors",
-          "signature": "colors: Readonly<Record<\"disabled\" | \"hover\" | \"normal\" | \"pressed\", Color>>",
+          "signature": "colors: Readonly<Record<ButtonState, Color | null>>",
           "signatureTokens": [
             {
               "text": "colors",
@@ -2709,41 +3442,25 @@
               "kind": "punctuation"
             },
             {
-              "text": "\"disabled\"",
-              "kind": "keyword"
-            },
-            {
-              "text": " | ",
-              "kind": "punctuation"
-            },
-            {
-              "text": "\"hover\"",
-              "kind": "keyword"
+              "text": "ButtonState",
+              "kind": "type"
             },
             {
-              "text": " | ",
+              "text": ", ",
               "kind": "punctuation"
             },
             {
-              "text": "\"normal\"",
-              "kind": "keyword"
+              "text": "Color",
+              "kind": "type"
             },
             {
               "text": " | ",
               "kind": "punctuation"
             },
             {
-              "text": "\"pressed\"",
+              "text": "null",
               "kind": "keyword"
             },
-            {
-              "text": ", ",
-              "kind": "punctuation"
-            },
-            {
-              "text": "Color",
-              "kind": "type"
-            },
             {
               "text": ">",
               "kind": "punctuation"
@@ -2755,7 +3472,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "The per-state fill colours (normal / hover / pressed / disabled)."
+          "description": "The per-state fill colours; null for a state that does not paint a fill."
         },
         {
           "name": "cornerRadius",
@@ -2776,7 +3493,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "Corner radius in pixels."
+          "description": "Corner radius in pixels of the normal state; 0 when it paints no fill."
         },
         {
           "name": "cullable",
@@ -3029,6 +3746,27 @@
           "returnType": null,
           "description": ""
         },
+        {
+          "name": "labelNode",
+          "signature": "labelNode: Text",
+          "signatureTokens": [
+            {
+              "text": "labelNode",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Text",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The Text node drawing the label, for advanced styling."
+        },
         {
           "name": "left",
           "signature": "left: number",
@@ -3268,6 +4006,27 @@
           "returnType": null,
           "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
         },
+        {
+          "name": "state",
+          "signature": "state: ButtonState",
+          "signatureTokens": [
+            {
+              "text": "state",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "ButtonState",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The state the button currently paints in."
+        },
         {
           "name": "textColor",
           "signature": "textColor: Color",
@@ -3289,6 +4048,185 @@
           "returnType": null,
           "description": "Label fill colour."
         },
+        {
+          "name": "textStyleOverrides",
+          "signature": "textStyleOverrides: TextStyleOptions | null",
+          "signatureTokens": [
+            {
+              "text": "textStyleOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "TextStyleOptions",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The text-style overrides this button carries, or null when it takes the skin's."
+        },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/site/src/content/api/functions.json b/site/src/content/api/functions.json
index 5eacba124..d8dfd2fda 100644
--- a/site/src/content/api/functions.json
+++ b/site/src/content/api/functions.json
@@ -6,11 +6,11 @@
   "subsystem": "core",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 63,
+  "memberCount": 66,
   "counts": {
     "constructors": 0,
-    "methods": 34,
-    "properties": 29,
+    "methods": 36,
+    "properties": 30,
     "events": 0
   },
   "sections": [
@@ -549,6 +549,74 @@
           "returnType": "GamepadMapping",
           "description": "Nintendo Switch Pro Controller over USB or Bluetooth. Index 17 is the Capture button (SWITCH_PRO_BUTTON_CAPTURE == BUTTON_INDEX_COUNT); Home maps to Guide, Minus/Plus to Select/Start. Some browsers only recognise the controller after it has been paired through Steam or a dedicated driver."
         },
+        {
+          "name": "createUITheme",
+          "signature": "createUITheme(patch: UIThemePatch, base: UITheme): UITheme",
+          "signatureTokens": [
+            {
+              "text": "createUITheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemePatch",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "base",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "UIThemePatch",
+              "optional": false
+            },
+            {
+              "name": "base",
+              "type": "UITheme",
+              "optional": false
+            }
+          ],
+          "returnType": "UITheme",
+          "description": "Resolve patch against base, role by role and state by state. Roles the patch does not name keep the base object itself, so an unchanged theme stays identical by reference - which is what makes a cascade refresh a pointer comparison rather than a deep diff."
+        },
         {
           "name": "createXboxGamepadMapping",
           "signature": "createXboxGamepadMapping(): GamepadMapping",
@@ -1672,6 +1740,74 @@
           "returnType": "RenderStats",
           "description": "Advance the frame counter and zero all per-frame accumulators in place. Call once at the start of each render tick before recording new data. Note: RenderStats.gpuMemoryBytes is intentionally **not** reset here. It is a running total of live GPU resources owned by the backend's resource accountant, which persists across frames; zeroing it each tick would make it read 0 after the first frame."
         },
+        {
+          "name": "resolveUISkin",
+          "signature": "resolveUISkin(set: UISkinSet, state: UIWidgetState): UISkin",
+          "signatureTokens": [
+            {
+              "text": "resolveUISkin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "set",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkinSet",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "set",
+              "type": "UISkinSet",
+              "optional": false
+            },
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin a state paints with, falling back to normal where undefined."
+        },
         {
           "name": "serializeCacheRecordKey",
           "signature": "serializeCacheRecordKey(key: CacheRecordKey): string",
@@ -2017,6 +2153,27 @@
           "returnType": null,
           "description": "The built-in csv asset type."
         },
+        {
+          "name": "defaultUITheme",
+          "signature": "defaultUITheme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "defaultUITheme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme a UI layer uses until one is assigned. It reproduces the widgets' built-in look, so assigning a patch changes only what the patch names."
+        },
         {
           "name": "fontType",
           "signature": "fontType: FontAssetType",
diff --git a/site/src/content/api/label.json b/site/src/content/api/label.json
index d720a112b..c234b8a1e 100644
--- a/site/src/content/api/label.json
+++ b/site/src/content/api/label.json
@@ -1,16 +1,16 @@
 {
   "title": "Label",
-  "description": "Text label widget. Wraps a Text node and keeps the widget's layout size in sync with the measured text, so it anchors and stacks correctly.",
+  "description": "Text label widget. Wraps a Text node and keeps the widget's layout size in sync with the measured text, so it anchors and stacks correctly. The label takes its text style from the `label` role of its inherited theme; the constructor style and Label.setTextStyle override parts of it for this label only.",
   "symbol": "Label",
   "kind": "class",
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 104,
+  "memberCount": 117,
   "counts": {
     "constructors": 1,
-    "methods": 46,
-    "properties": 43,
+    "methods": 56,
+    "properties": 46,
     "events": 14
   },
   "sections": [
@@ -19,7 +19,8 @@
       "title": "Import",
       "members": [],
       "paragraphs": [
-        "Text label widget. Wraps a Text node and keeps the widget's layout size in sync with the measured text, so it anchors and stacks correctly."
+        "Text label widget. Wraps a Text node and keeps the widget's layout size in sync with the measured text, so it anchors and stacks correctly.",
+        "The label takes its text style from the `label` role of its inherited theme; the constructor style and Label.setTextStyle override parts of it for this label only."
       ],
       "importLine": "import { Label } from '@codexo/exojs'",
       "sourceLink": null
@@ -173,6 +174,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(_effectiveEnabled: boolean): void",
@@ -220,6 +308,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -247,7 +364,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -2146,11 +2415,11 @@
           "description": ""
         },
         {
-          "name": "swapChildren",
-          "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
+          "name": "setTextStyle",
+          "signature": "setTextStyle(style: TextStyleOptions | null): this",
           "signatureTokens": [
             {
-              "text": "swapChildren",
+              "text": "setTextStyle",
               "kind": "name"
             },
             {
@@ -2158,7 +2427,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "firstChild",
+              "text": "style",
               "kind": "param"
             },
             {
@@ -2166,24 +2435,16 @@
               "kind": "punctuation"
             },
             {
-              "text": "RenderNode",
+              "text": "TextStyleOptions",
               "kind": "type"
             },
             {
-              "text": ", ",
-              "kind": "punctuation"
-            },
-            {
-              "text": "secondChild",
-              "kind": "param"
-            },
-            {
-              "text": ": ",
+              "text": " | ",
               "kind": "punctuation"
             },
             {
-              "text": "RenderNode",
-              "kind": "type"
+              "text": "null",
+              "kind": "keyword"
             },
             {
               "text": ")",
@@ -2200,22 +2461,240 @@
           ],
           "params": [
             {
-              "name": "firstChild",
-              "type": "RenderNode",
-              "optional": false
-            },
-            {
-              "name": "secondChild",
-              "type": "RenderNode",
+              "name": "style",
+              "type": "TextStyleOptions | null",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Override text style on top of the skin's; null returns to it. The label is re-measured, so its layout size follows the new style."
         },
         {
-          "name": "updateBounds",
-          "signature": "updateBounds(): this",
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
+        },
+        {
+          "name": "swapChildren",
+          "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
+          "signatureTokens": [
+            {
+              "text": "swapChildren",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "firstChild",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "secondChild",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "firstChild",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "secondChild",
+              "type": "RenderNode",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "updateBounds",
+          "signature": "updateBounds(): this",
           "signatureTokens": [
             {
               "text": "updateBounds",
@@ -3191,6 +3670,185 @@
           "returnType": null,
           "description": "The underlying Text node, for advanced styling."
         },
+        {
+          "name": "textStyleOverrides",
+          "signature": "textStyleOverrides: TextStyleOptions | null",
+          "signatureTokens": [
+            {
+              "text": "textStyleOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "TextStyleOptions",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The text-style overrides this label carries, or null when it takes the skin's."
+        },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/site/src/content/api/panel-options.json b/site/src/content/api/panel-options.json
index 4130cd933..55d1bf986 100644
--- a/site/src/content/api/panel-options.json
+++ b/site/src/content/api/panel-options.json
@@ -6,11 +6,11 @@
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 6,
+  "memberCount": 7,
   "counts": {
     "constructors": 0,
     "methods": 0,
-    "properties": 6,
+    "properties": 7,
     "events": 0
   },
   "sections": [
@@ -26,6 +26,31 @@
       "id": "properties",
       "title": "Properties",
       "members": [
+        {
+          "name": "background",
+          "signature": "background?: UIBackground",
+          "signatureTokens": [
+            {
+              "text": "background",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Whole-background override, e.g. a nine-slice skin, replacing the theme's."
+        },
         {
           "name": "borderColor",
           "signature": "borderColor?: Color",
@@ -49,7 +74,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "Border color (only drawn when borderWidth > 0)."
+          "description": "Border color override (only drawn when borderWidth > 0)."
         },
         {
           "name": "borderWidth",
@@ -99,7 +124,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "Fill color. Default: a translucent dark slate."
+          "description": "Fill color override. Default: the theme's panel fill."
         },
         {
           "name": "cornerRadius",
diff --git a/site/src/content/api/panel.json b/site/src/content/api/panel.json
index cc8bb36b8..5a22b0d8c 100644
--- a/site/src/content/api/panel.json
+++ b/site/src/content/api/panel.json
@@ -1,16 +1,16 @@
 {
   "title": "Panel",
-  "description": "Rectangular background container with rounded corners and an optional border. The base building block for HUD boxes, dialogs, and menus - add content with `panel.addChild(...)`.",
+  "description": "Rectangular background container with rounded corners and an optional border. The base building block for HUD boxes, dialogs, and menus - add content with `panel.addChild(...)`. The panel paints the `panel` role of its inherited theme. Constructor options and the setters below are per-panel overrides on top of it; each one repaints immediately.",
   "symbol": "Panel",
   "kind": "class",
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 107,
+  "memberCount": 122,
   "counts": {
     "constructors": 1,
-    "methods": 46,
-    "properties": 46,
+    "methods": 57,
+    "properties": 50,
     "events": 14
   },
   "sections": [
@@ -19,7 +19,8 @@
       "title": "Import",
       "members": [],
       "paragraphs": [
-        "Rectangular background container with rounded corners and an optional border. The base building block for HUD boxes, dialogs, and menus - add content with `panel.addChild(...)`."
+        "Rectangular background container with rounded corners and an optional border. The base building block for HUD boxes, dialogs, and menus - add content with `panel.addChild(...)`.",
+        "The panel paints the `panel` role of its inherited theme. Constructor options and the setters below are per-panel overrides on top of it; each one repaints immediately."
       ],
       "importLine": "import { Panel } from '@codexo/exojs'",
       "sourceLink": null
@@ -152,6 +153,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(_effectiveEnabled: boolean): void",
@@ -199,6 +287,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -226,7 +343,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -1670,11 +1939,11 @@
           "description": ""
         },
         {
-          "name": "setChildIndex",
-          "signature": "setChildIndex(child: RenderNode, index: number): this",
+          "name": "setBackground",
+          "signature": "setBackground(background: UIBackground | null): this",
           "signatureTokens": [
             {
-              "text": "setChildIndex",
+              "text": "setBackground",
               "kind": "name"
             },
             {
@@ -1682,7 +1951,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "child",
+              "text": "background",
               "kind": "param"
             },
             {
@@ -1690,23 +1959,15 @@
               "kind": "punctuation"
             },
             {
-              "text": "RenderNode",
+              "text": "UIBackground",
               "kind": "type"
             },
             {
-              "text": ", ",
-              "kind": "punctuation"
-            },
-            {
-              "text": "index",
-              "kind": "param"
-            },
-            {
-              "text": ": ",
+              "text": " | ",
               "kind": "punctuation"
             },
             {
-              "text": "number",
+              "text": "null",
               "kind": "keyword"
             },
             {
@@ -1724,25 +1985,143 @@
           ],
           "params": [
             {
-              "name": "child",
-              "type": "RenderNode",
-              "optional": false
-            },
-            {
-              "name": "index",
-              "type": "number",
+              "name": "background",
+              "type": "UIBackground | null",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Replace the whole background descriptor, ignoring the skin's. null restores it. Layout-invalidating: a nine-slice and a fill can imply different content boxes."
         },
         {
-          "name": "setOrigin",
-          "signature": "setOrigin(x: number, y: number): this",
+          "name": "setChildIndex",
+          "signature": "setChildIndex(child: RenderNode, index: number): this",
           "signatureTokens": [
             {
-              "text": "setOrigin",
+              "text": "setChildIndex",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setFill",
+          "signature": "setFill(patch: UIFillPatch | null): this",
+          "signatureTokens": [
+            {
+              "text": "setFill",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "UIFillPatch | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override fill properties on top of the skin. Overriding a colour on a panel whose skin paints a texture switches it to a fill. Passing null drops the overrides and returns the panel to its skin."
+        },
+        {
+          "name": "setOrigin",
+          "signature": "setOrigin(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "setOrigin",
               "kind": "name"
             },
             {
@@ -2124,6 +2503,161 @@
           "returnType": "this",
           "description": ""
         },
+        {
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
+        },
         {
           "name": "swapChildren",
           "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
@@ -2528,7 +3062,7 @@
         },
         {
           "name": "background",
-          "signature": "background: Graphics",
+          "signature": "background: UIBackground",
           "signatureTokens": [
             {
               "text": "background",
@@ -2538,18 +3072,55 @@
               "text": ": ",
               "kind": "punctuation"
             },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The background actually painted: this panel's overrides over its skin."
+        },
+        {
+          "name": "backgroundNode",
+          "signature": "backgroundNode: Graphics | NineSliceSprite | null",
+          "signatureTokens": [
+            {
+              "text": "backgroundNode",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
             {
               "text": "Graphics",
               "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "NineSliceSprite",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
             }
           ],
           "params": [],
           "returnType": null,
-          "description": "The background Graphics, for advanced customization."
+          "description": "The node painting the background, or null while it paints nothing."
         },
         {
           "name": "borderColor",
-          "signature": "borderColor: Color",
+          "signature": "borderColor: Color | null",
           "signatureTokens": [
             {
               "text": "borderColor",
@@ -2562,11 +3133,19 @@
             {
               "text": "Color",
               "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
             }
           ],
           "params": [],
           "returnType": null,
-          "description": "Border colour (drawn only when borderWidth is greater than 0)."
+          "description": "Border colour, or null when the panel does not paint a fill."
         },
         {
           "name": "borderWidth",
@@ -2587,7 +3166,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "Border thickness in pixels."
+          "description": "Border thickness in pixels; 0 when the panel does not paint a fill."
         },
         {
           "name": "bottom",
@@ -2745,7 +3324,7 @@
         },
         {
           "name": "color",
-          "signature": "color: Color",
+          "signature": "color: Color | null",
           "signatureTokens": [
             {
               "text": "color",
@@ -2758,11 +3337,19 @@
             {
               "text": "Color",
               "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
             }
           ],
           "params": [],
           "returnType": null,
-          "description": "Fill colour."
+          "description": "Fill colour, or null when the panel does not paint a fill."
         },
         {
           "name": "cornerRadius",
@@ -2783,7 +3370,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "Corner radius in pixels."
+          "description": "Corner radius in pixels; 0 when the panel does not paint a fill."
         },
         {
           "name": "cullable",
@@ -2898,6 +3485,35 @@
           "returnType": null,
           "description": "The widget's own enabled flag, independent of any ancestor's. Disabling a container widget does not change this on its children - see effectiveEnabled for the value interaction and keyboard focus actually consult, and for what disabling a container does to them."
         },
+        {
+          "name": "fillOverrides",
+          "signature": "fillOverrides: UIFillPatch | null",
+          "signatureTokens": [
+            {
+              "text": "fillOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The fill overrides this panel carries, or null when it takes its skin as is."
+        },
         {
           "name": "filters",
           "signature": "filters: readonly Filter[]",
@@ -3233,6 +3849,156 @@
           "returnType": null,
           "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
         },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/site/src/content/api/progress-bar.json b/site/src/content/api/progress-bar.json
index f1556a7c9..cc23ebb5e 100644
--- a/site/src/content/api/progress-bar.json
+++ b/site/src/content/api/progress-bar.json
@@ -1,16 +1,16 @@
 {
   "title": "ProgressBar",
-  "description": "Horizontal progress / health bar. ProgressBar.value is the fill fraction in `[0, 1]`; setting it redraws only the fill.",
+  "description": "Horizontal progress / health bar. ProgressBar.value is the fill fraction in `[0, 1]`; setting it redraws only the bar. The two surfaces are themed independently: the groove paints the `progressBarTrack` role, the bar `progressBarFill`.",
   "symbol": "ProgressBar",
   "kind": "class",
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 106,
+  "memberCount": 124,
   "counts": {
     "constructors": 1,
-    "methods": 46,
-    "properties": 45,
+    "methods": 59,
+    "properties": 50,
     "events": 14
   },
   "sections": [
@@ -19,7 +19,8 @@
       "title": "Import",
       "members": [],
       "paragraphs": [
-        "Horizontal progress / health bar. ProgressBar.value is the fill fraction in `[0, 1]`; setting it redraws only the fill."
+        "Horizontal progress / health bar. ProgressBar.value is the fill fraction in `[0, 1]`; setting it redraws only the bar.",
+        "The two surfaces are themed independently: the groove paints the `progressBarTrack` role, the bar `progressBarFill`."
       ],
       "importLine": "import { ProgressBar } from '@codexo/exojs'",
       "sourceLink": null
@@ -152,6 +153,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(_effectiveEnabled: boolean): void",
@@ -199,6 +287,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -226,7 +343,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -1670,11 +1939,11 @@
           "description": ""
         },
         {
-          "name": "setChildIndex",
-          "signature": "setChildIndex(child: RenderNode, index: number): this",
+          "name": "setBarBackground",
+          "signature": "setBarBackground(background: UIBackground | null): this",
           "signatureTokens": [
             {
-              "text": "setChildIndex",
+              "text": "setBarBackground",
               "kind": "name"
             },
             {
@@ -1682,7 +1951,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "child",
+              "text": "background",
               "kind": "param"
             },
             {
@@ -1690,23 +1959,15 @@
               "kind": "punctuation"
             },
             {
-              "text": "RenderNode",
+              "text": "UIBackground",
               "kind": "type"
             },
             {
-              "text": ", ",
-              "kind": "punctuation"
-            },
-            {
-              "text": "index",
-              "kind": "param"
-            },
-            {
-              "text": ": ",
+              "text": " | ",
               "kind": "punctuation"
             },
             {
-              "text": "number",
+              "text": "null",
               "kind": "keyword"
             },
             {
@@ -1724,25 +1985,20 @@
           ],
           "params": [
             {
-              "name": "child",
-              "type": "RenderNode",
-              "optional": false
-            },
-            {
-              "name": "index",
-              "type": "number",
+              "name": "background",
+              "type": "UIBackground | null",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Replace the bar's whole background descriptor; null restores the skin's."
         },
         {
-          "name": "setOrigin",
-          "signature": "setOrigin(x: number, y: number): this",
+          "name": "setBarFill",
+          "signature": "setBarFill(patch: UIFillPatch | null): this",
           "signatureTokens": [
             {
-              "text": "setOrigin",
+              "text": "setBarFill",
               "kind": "name"
             },
             {
@@ -1750,7 +2006,7 @@
               "kind": "punctuation"
             },
             {
-              "text": "x",
+              "text": "patch",
               "kind": "param"
             },
             {
@@ -1758,8 +2014,131 @@
               "kind": "punctuation"
             },
             {
-              "text": "number",
-              "kind": "keyword"
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "UIFillPatch | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override fill properties of the bar on top of its skin; null drops them."
+        },
+        {
+          "name": "setChildIndex",
+          "signature": "setChildIndex(child: RenderNode, index: number): this",
+          "signatureTokens": [
+            {
+              "text": "setChildIndex",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setOrigin",
+          "signature": "setOrigin(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "setOrigin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
             },
             {
               "text": ", ",
@@ -2085,7 +2464,269 @@
               "kind": "punctuation"
             },
             {
-              "text": "y",
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
+        },
+        {
+          "name": "setTrackBackground",
+          "signature": "setTrackBackground(background: UIBackground | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTrackBackground",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "background",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "background",
+              "type": "UIBackground | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Replace the track's whole background descriptor; null restores the skin's."
+        },
+        {
+          "name": "setTrackFill",
+          "signature": "setTrackFill(patch: UIFillPatch | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTrackFill",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
               "kind": "param"
             },
             {
@@ -2093,7 +2734,15 @@
               "kind": "punctuation"
             },
             {
-              "text": "number",
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
               "kind": "keyword"
             },
             {
@@ -2111,18 +2760,13 @@
           ],
           "params": [
             {
-              "name": "x",
-              "type": "number",
-              "optional": false
-            },
-            {
-              "name": "y",
-              "type": "number",
+              "name": "patch",
+              "type": "UIFillPatch | null",
               "optional": false
             }
           ],
           "returnType": "this",
-          "description": ""
+          "description": "Override fill properties of the track on top of its skin; null drops them."
         },
         {
           "name": "swapChildren",
@@ -2526,6 +3170,27 @@
           "returnType": null,
           "description": "Tab-traversal order among focusable nodes in the same focus scope. Lower values are visited first; equal values keep document (tree) order."
         },
+        {
+          "name": "barBackground",
+          "signature": "barBackground: UIBackground",
+          "signatureTokens": [
+            {
+              "text": "barBackground",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The background painted for the filled portion."
+        },
         {
           "name": "bottom",
           "signature": "bottom: number",
@@ -2699,7 +3364,7 @@
           ],
           "params": [],
           "returnType": null,
-          "description": "Corner radius in pixels."
+          "description": "Corner radius in pixels of the track; 0 when it paints no fill."
         },
         {
           "name": "cullable",
@@ -2816,7 +3481,7 @@
         },
         {
           "name": "fillColor",
-          "signature": "fillColor: Color",
+          "signature": "fillColor: Color | null",
           "signatureTokens": [
             {
               "text": "fillColor",
@@ -2829,11 +3494,88 @@
             {
               "text": "Color",
               "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Bar colour, or null when the bar does not paint a fill."
+        },
+        {
+          "name": "fillOverrides",
+          "signature": "fillOverrides: { bar: UIFillPatch | null; track: UIFillPatch | null }",
+          "signatureTokens": [
+            {
+              "text": "fillOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "{ ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "bar",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": "; ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "track",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIFillPatch",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": " }",
+              "kind": "punctuation"
             }
           ],
           "params": [],
           "returnType": null,
-          "description": "Fill (foreground) colour."
+          "description": "The fill overrides carried by the track and the bar, null where none."
         },
         {
           "name": "filters",
@@ -3170,6 +3912,156 @@
           "returnType": null,
           "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
         },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
@@ -3191,9 +4083,30 @@
           "returnType": null,
           "description": "Topmost edge of the subtree - see left."
         },
+        {
+          "name": "trackBackground",
+          "signature": "trackBackground: UIBackground",
+          "signatureTokens": [
+            {
+              "text": "trackBackground",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The background painted behind the bar."
+        },
         {
           "name": "trackColor",
-          "signature": "trackColor: Color",
+          "signature": "trackColor: Color | null",
           "signatureTokens": [
             {
               "text": "trackColor",
@@ -3206,11 +4119,19 @@
             {
               "text": "Color",
               "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
             }
           ],
           "params": [],
           "returnType": null,
-          "description": "Track (background) colour."
+          "description": "Track colour, or null when the track does not paint a fill."
         },
         {
           "name": "uiHeight",
diff --git a/site/src/content/api/scroll-container.json b/site/src/content/api/scroll-container.json
index cb6fac942..c23ead804 100644
--- a/site/src/content/api/scroll-container.json
+++ b/site/src/content/api/scroll-container.json
@@ -6,11 +6,11 @@
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 108,
+  "memberCount": 119,
   "counts": {
     "constructors": 1,
-    "methods": 48,
-    "properties": 45,
+    "methods": 57,
+    "properties": 47,
     "events": 14
   },
   "sections": [
@@ -154,6 +154,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(_effectiveEnabled: boolean): void",
@@ -201,6 +288,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -228,7 +344,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -2262,6 +2530,161 @@
           "returnType": "this",
           "description": ""
         },
+        {
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
+        },
         {
           "name": "swapChildren",
           "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
@@ -3350,6 +3773,156 @@
           "returnType": null,
           "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
         },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/site/src/content/api/stack.json b/site/src/content/api/stack.json
index da5a6fdef..9b31fabe5 100644
--- a/site/src/content/api/stack.json
+++ b/site/src/content/api/stack.json
@@ -6,11 +6,11 @@
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 107,
+  "memberCount": 118,
   "counts": {
     "constructors": 1,
-    "methods": 48,
-    "properties": 44,
+    "methods": 57,
+    "properties": 46,
     "events": 14
   },
   "sections": [
@@ -152,6 +152,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(_effectiveEnabled: boolean): void",
@@ -199,6 +286,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -226,7 +342,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -2200,6 +2468,161 @@
           "returnType": "this",
           "description": ""
         },
+        {
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
+        },
         {
           "name": "swapChildren",
           "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
@@ -3267,6 +3690,156 @@
           "returnType": null,
           "description": "Gap between items in pixels."
         },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/site/src/content/api/themed-container.json b/site/src/content/api/themed-container.json
new file mode 100644
index 000000000..d1cc81cc2
--- /dev/null
+++ b/site/src/content/api/themed-container.json
@@ -0,0 +1,3556 @@
+{
+  "title": "ThemedContainer",
+  "description": "A container that carries a UITheme for the subtree below it. Widgets resolve their skins from the nearest themed ancestor, which is how a theme assigned on a UIRoot reaches every widget in that layer without a global registry.",
+  "symbol": "ThemedContainer",
+  "kind": "class",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 96,
+  "counts": {
+    "constructors": 1,
+    "methods": 43,
+    "properties": 38,
+    "events": 14
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "A container that carries a UITheme for the subtree below it. Widgets resolve their skins from the nearest themed ancestor, which is how a theme assigned on a UIRoot reaches every widget in that layer without a global registry."
+      ],
+      "importLine": "import { ThemedContainer } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "constructors",
+      "title": "Constructors",
+      "members": [
+        {
+          "name": "new",
+          "signature": "new(): ThemedContainer",
+          "signatureTokens": [
+            {
+              "text": "new",
+              "kind": "keyword"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "ThemedContainer",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "ThemedContainer",
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "methods",
+      "title": "Methods",
+      "members": [
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "[iterator]",
+          "signature": "[iterator](): IterableIterator<RenderNode>",
+          "signatureTokens": [
+            {
+              "text": "[iterator]",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "IterableIterator",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": "IterableIterator<RenderNode>",
+          "description": "Iterate the same frozen, cached document-order snapshot children returns - mutating the container after obtaining this iterator does not change what it yields (see children's doc comment for the full snapshot/invalidation contract)."
+        },
+        {
+          "name": "addChild",
+          "signature": "addChild(children: RenderNode[]): this",
+          "signatureTokens": [
+            {
+              "text": "addChild",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "children",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": "[]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "children",
+              "type": "RenderNode[]",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Append one or more children to the end of the child list. Each child is detached from its previous parent (if any) before being added."
+        },
+        {
+          "name": "addChildAt",
+          "signature": "addChildAt(child: RenderNode, index: number): this",
+          "signatureTokens": [
+            {
+              "text": "addChildAt",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Insert child at index in the child list. The child is detached from any previous parent first. Throws if index is out of bounds, if child has already been destroy()ed, or if child is an ancestor of this container (would create a cycle). Self-as-child is a no-op. When child already belongs to this container the call is a pure reorder: the node keeps its parent, its stage and its keyboard focus."
+        },
+        {
+          "name": "addFilter",
+          "signature": "addFilter(filter: Filter): this",
+          "signatureTokens": [
+            {
+              "text": "addFilter",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "filter",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Filter",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "filter",
+              "type": "Filter",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "blur",
+          "signature": "blur(): this",
+          "signatureTokens": [
+            {
+              "text": "blur",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": "Release keyboard focus from this node if it currently holds it."
+        },
+        {
+          "name": "clearFilters",
+          "signature": "clearFilters(): this",
+          "signatureTokens": [
+            {
+              "text": "clearFilters",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "collidesWith",
+          "signature": "collidesWith(target: Collidable): CollisionResponse | null",
+          "signatureTokens": [
+            {
+              "text": "collidesWith",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "target",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Collidable",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "CollisionResponse",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "target",
+              "type": "Collidable",
+              "optional": false
+            }
+          ],
+          "returnType": "CollisionResponse | null",
+          "description": "Compute a full CollisionResponse between this shape and target. Returns null in two cases: - the shapes do not overlap, **or** - the specific shape-pair combination does not support response generation (e.g. Line against any shape, Ellipse against Ellipse or Polygon). Use intersectsWith for a universal boolean overlap check that works across all supported shape pairs."
+        },
+        {
+          "name": "contains",
+          "signature": "contains(x: number, y: number): boolean",
+          "signatureTokens": [
+            {
+              "text": "contains",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "boolean",
+          "description": "Hit-test the world-space point (x, y) against this node. For world-axis-aligned nodes (own and inherited rotation a multiple of 90° and no skew) the AABB equals the oriented box, so the cheap getBounds test is exact. For rotated or skewed nodes the point is mapped back into local space with the inverse of the global transform and tested against the untransformed getLocalBounds - i.e. a true oriented-box test. This is the exact inverse of the forward map that getBounds and the renderer use to place the node's corners, so picking matches the rendered quad instead of over-reporting hits in the empty AABB corners of a rotated node."
+        },
+        {
+          "name": "destroy",
+          "signature": "destroy(): void",
+          "signatureTokens": [
+            {
+              "text": "destroy",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Destroy this container and every node beneath it. Ownership is by containment: detaching a subtree only unlinks it, so the descendants' GPU-backed resources (cached textures, filters, render textures) and signal listeners would outlive the tree that owned them and leak on every scene change."
+        },
+        {
+          "name": "focus",
+          "signature": "focus(): this",
+          "signatureTokens": [
+            {
+              "text": "focus",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": "Request keyboard focus for this node through its owning focus service."
+        },
+        {
+          "name": "getBounds",
+          "signature": "getBounds(out?: Rectangle): Rectangle",
+          "signatureTokens": [
+            {
+              "text": "getBounds",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "out",
+              "kind": "param"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Rectangle",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Rectangle",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "out",
+              "type": "Rectangle",
+              "optional": true
+            }
+          ],
+          "returnType": "Rectangle",
+          "description": "Axis-aligned bounding box of this node in its GLOBAL-transform space. That is world space for ordinary nodes, but GROUP-LOCAL space for nodes inside an engaged RetainedContainer transform group (the group matrix is applied on the GPU, not here) - this is deliberate and matches the rendering convention. For a true world-space extent of such a node, lift this rect by the group's getWorldTransform matrix. Pass out to receive a copy you own. Without it the return value is this node's **cached** rectangle, rebuilt in place whenever the transform or the local extent changes - retaining it across frames hands you a value that silently moves. The cache is why the no-arg form does not allocate: this runs per node per frame for culling and hit-testing."
+        },
+        {
+          "name": "getChildAt",
+          "signature": "getChildAt(index: number): RenderNode",
+          "signatureTokens": [
+            {
+              "text": "getChildAt",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "RenderNode",
+          "description": ""
+        },
+        {
+          "name": "getChildIndex",
+          "signature": "getChildIndex(child: RenderNode): number",
+          "signatureTokens": [
+            {
+              "text": "getChildIndex",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            }
+          ],
+          "returnType": "number",
+          "description": ""
+        },
+        {
+          "name": "getGlobalTransform",
+          "signature": "getGlobalTransform(): Matrix",
+          "signatureTokens": [
+            {
+              "text": "getGlobalTransform",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Matrix",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "Matrix",
+          "description": ""
+        },
+        {
+          "name": "getLocalBounds",
+          "signature": "getLocalBounds(): ReadonlyRectangle",
+          "signatureTokens": [
+            {
+              "text": "getLocalBounds",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "ReadonlyRectangle",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "ReadonlyRectangle",
+          "description": "This node's untransformed extent in its own local coordinate space. Returns the LIVE internal rectangle, not a copy: it is read on hot paths (updateBounds re-reads it on every transform-dirty recompute, i.e. potentially every frame for a moving node), so copying it here would add a per-frame allocation. It is therefore typed as a ReadonlyRectangle - reads are unchanged, writes are rejected at compile time. Writing to it directly would skip the bounds/content invalidation the engine needs, leaving culling, hit-testing and retained render fragments on a stale extent. A custom Drawable that owns its own size sets it through _setLocalBounds, which writes and invalidates in one step."
+        },
+        {
+          "name": "getNormals",
+          "signature": "getNormals(): Vector[]",
+          "signatureTokens": [
+            {
+              "text": "getNormals",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Vector",
+              "kind": "type"
+            },
+            {
+              "text": "[]",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": "Vector[]",
+          "description": "Return the outward-facing edge normals used by the SAT solver. The array should be cached and reused across calls."
+        },
+        {
+          "name": "getTransform",
+          "signature": "getTransform(): Matrix",
+          "signatureTokens": [
+            {
+              "text": "getTransform",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Matrix",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "Matrix",
+          "description": ""
+        },
+        {
+          "name": "getWorldTransform",
+          "signature": "getWorldTransform(): Matrix",
+          "signatureTokens": [
+            {
+              "text": "getWorldTransform",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Matrix",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "Matrix",
+          "description": "The node's TRUE world-space transform, composed through every transform-group boundary (RetainedContainer) in the ancestor chain. getGlobalTransform deliberately stops at the nearest engaged boundary (descendants resolve group-RELATIVE transforms; the renderer multiplies the group matrix back in on the GPU), so it is the right space for rendering but the wrong one for spatial queries. Use THIS accessor whenever a real world position/orientation is needed - picking, spatial audio, physics, world-space math against nodes outside the group. Without any engaged boundary ancestor it returns the exact getGlobalTransform matrix (same instance, no extra work). With one, it lazily caches groupLocal × groupWorld and revalidates on read via version/stamp compares - including runtime space flips such as RetainedContainer's deep-barrier sub-branch escape."
+        },
+        {
+          "name": "intersectsWith",
+          "signature": "intersectsWith(target: Collidable): boolean",
+          "signatureTokens": [
+            {
+              "text": "intersectsWith",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "target",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Collidable",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "target",
+              "type": "Collidable",
+              "optional": false
+            }
+          ],
+          "returnType": "boolean",
+          "description": "Test whether this shape overlaps target using a fast boolean algorithm (no penetration depth or normal computed). Prefer this over collidesWith when only the yes/no result is needed."
+        },
+        {
+          "name": "invalidateCache",
+          "signature": "invalidateCache(): this",
+          "signatureTokens": [
+            {
+              "text": "invalidateCache",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "invalidateContent",
+          "signature": "invalidateContent(): this",
+          "signatureTokens": [
+            {
+              "text": "invalidateContent",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": "Mark this node's visual content dirty without going through a standard setter - e.g. a custom Drawable subclass backed by externally mutable data (the pattern TileChunkNode in @codexo/exojs-tilemap already uses via its own _chunk.revision compare). Call this after mutating such state so the Track-B retained-plan skip does not serve a stale frame for this node."
+        },
+        {
+          "name": "inView",
+          "signature": "inView(view: View): boolean",
+          "signatureTokens": [
+            {
+              "text": "inView",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "view",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "View",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "view",
+              "type": "View",
+              "optional": false
+            }
+          ],
+          "returnType": "boolean",
+          "description": ""
+        },
+        {
+          "name": "move",
+          "signature": "move(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "move",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "project",
+          "signature": "project(axis: Vector, result: Interval): Interval",
+          "signatureTokens": [
+            {
+              "text": "project",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "axis",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Vector",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "result",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Interval",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Interval",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "axis",
+              "type": "Vector",
+              "optional": false
+            },
+            {
+              "name": "result",
+              "type": "Interval",
+              "optional": false
+            }
+          ],
+          "returnType": "Interval",
+          "description": "Project this shape onto axis and write the scalar min/max into interval. Used internally by the SAT solver."
+        },
+        {
+          "name": "removeChild",
+          "signature": "removeChild(child: RenderNode): this",
+          "signatureTokens": [
+            {
+              "text": "removeChild",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Remove child from this container. No-op if not present."
+        },
+        {
+          "name": "removeChildAt",
+          "signature": "removeChildAt(index: number): this",
+          "signatureTokens": [
+            {
+              "text": "removeChildAt",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "removeChildren",
+          "signature": "removeChildren(begin: number, end: number): this",
+          "signatureTokens": [
+            {
+              "text": "removeChildren",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "begin",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "end",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "begin",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "end",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Remove children in the half-open range [begin, end). Defaults to the entire child list. Throws if the range is invalid."
+        },
+        {
+          "name": "removeFilter",
+          "signature": "removeFilter(filter: Filter): this",
+          "signatureTokens": [
+            {
+              "text": "removeFilter",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "filter",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Filter",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "filter",
+              "type": "Filter",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "render",
+          "signature": "render(backend: RenderBackend): this",
+          "signatureTokens": [
+            {
+              "text": "render",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "backend",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderBackend",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "backend",
+              "type": "RenderBackend",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Raw rendering entry point. Direct backend access - bypasses the RenderPlan pipeline machinery. Prefer the high-level RenderingContext.render path via the owning RenderingContext wherever possible."
+        },
+        {
+          "name": "rotate",
+          "signature": "rotate(degrees: number): this",
+          "signatureTokens": [
+            {
+              "text": "rotate",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "degrees",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "degrees",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setChildIndex",
+          "signature": "setChildIndex(child: RenderNode, index: number): this",
+          "signatureTokens": [
+            {
+              "text": "setChildIndex",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "child",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "index",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "child",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "index",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setOrigin",
+          "signature": "setOrigin(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "setOrigin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setPosition",
+          "signature": "setPosition(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "setPosition",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setRotation",
+          "signature": "setRotation(degrees: number): this",
+          "signatureTokens": [
+            {
+              "text": "setRotation",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "degrees",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "degrees",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setScale",
+          "signature": "setScale(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "setScale",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setSkew",
+          "signature": "setSkew(x: number, y: number): this",
+          "signatureTokens": [
+            {
+              "text": "setSkew",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "x",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "y",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "swapChildren",
+          "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
+          "signatureTokens": [
+            {
+              "text": "swapChildren",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "firstChild",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "secondChild",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "firstChild",
+              "type": "RenderNode",
+              "optional": false
+            },
+            {
+              "name": "secondChild",
+              "type": "RenderNode",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "updateBounds",
+          "signature": "updateBounds(): this",
+          "signatureTokens": [
+            {
+              "text": "updateBounds",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "updateParentTransform",
+          "signature": "updateParentTransform(): this",
+          "signatureTokens": [
+            {
+              "text": "updateParentTransform",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "updateTransform",
+          "signature": "updateTransform(): this",
+          "signatureTokens": [
+            {
+              "text": "updateTransform",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "this",
+          "description": ""
+        },
+        {
+          "name": "setInternalSpriteFactory",
+          "signature": "setInternalSpriteFactory(factory: () => RenderNodeSpriteLike | null): void",
+          "signatureTokens": [
+            {
+              "text": "setInternalSpriteFactory",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "factory",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ") => ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNodeSpriteLike",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "factory",
+              "type": "() => RenderNodeSpriteLike | null",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "collisionType",
+          "signature": "collisionType: CollisionType",
+          "signatureTokens": [
+            {
+              "text": "collisionType",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "CollisionType",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "cursor",
+          "signature": "cursor: null | string",
+          "signatureTokens": [
+            {
+              "text": "cursor",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "string",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "draggable",
+          "signature": "draggable: boolean",
+          "signatureTokens": [
+            {
+              "text": "draggable",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "When true and interactive is also true, this node will be automatically repositioned to follow the pointer during a drag gesture. The framework captures the pointer offset at drag-start so the node doesn't snap to the cursor position. Both interactive and draggable must be set for dragging to work - a draggable but non-interactive node will never receive pointerdown and therefore cannot start a drag."
+        },
+        {
+          "name": "flags",
+          "signature": "flags: Flags<SceneNodeTransformFlags>",
+          "signatureTokens": [
+            {
+              "text": "flags",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Flags",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "SceneNodeTransformFlags",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "focusable",
+          "signature": "focusable: boolean",
+          "signatureTokens": [
+            {
+              "text": "focusable",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "When true, this node can receive keyboard focus - via focus, Tab traversal, or app.interaction.focus(node) - and is delivered key events through onKeyDown / onKeyUp while focused, or while any of its descendants holds focus (key events bubble up the parent chain like pointer InteractionEvents do). A Widget additionally has to be enabled: disabling one takes it out of the Tab order and rejects programmatic focus, without touching this flag."
+        },
+        {
+          "name": "name",
+          "signature": "name: null | string",
+          "signatureTokens": [
+            {
+              "text": "name",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "string",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Optional human-readable identity for this node. Defaults to null. Purely a label the engine never interprets: useful for debugging, find-by-name lookups, prefab references, and as a stable key when merging serialized state back onto an existing tree. Not required to be unique."
+        },
+        {
+          "name": "tabIndex",
+          "signature": "tabIndex: number",
+          "signatureTokens": [
+            {
+              "text": "tabIndex",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Tab-traversal order among focusable nodes in the same focus scope. Lower values are visited first; equal values keep document (tree) order."
+        },
+        {
+          "name": "bottom",
+          "signature": "bottom: number",
+          "signatureTokens": [
+            {
+              "text": "bottom",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Bottommost edge of the subtree - see left."
+        },
+        {
+          "name": "cacheAsTexture",
+          "signature": "cacheAsTexture: boolean",
+          "signatureTokens": [
+            {
+              "text": "cacheAsTexture",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Bake this node's subtree into a RenderTexture once and replay that texture until the subtree changes, instead of walking and drawing it every frame. Worth it for a subtree that is expensive to draw and rarely changes. The cache is invalidated by anything that moves the node's world bounds - the node's own transform included - so a node that animates re-bakes every frame and is strictly slower than not caching it at all. Setting it to false frees the texture immediately."
+        },
+        {
+          "name": "cacheResolution",
+          "signature": "cacheResolution: TargetResolution",
+          "signatureTokens": [
+            {
+              "text": "cacheResolution",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "TargetResolution",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Resolution the cacheAsTexture texture is baked at, in device pixels per logical unit. 'inherit' (the default) matches the surface the cache is composited into, so enabling the cache does not soften the picture on a HiDPI display. Pin it to a number to trade sharpness for memory and bake cost - a cache is resolution² texels, so 1 on a DPR-3 phone is a ninth of the VRAM and a ninth of the fill per re-bake. Changing it invalidates the cache."
+        },
+        {
+          "name": "children",
+          "signature": "children: readonly RenderNode[]",
+          "signatureTokens": [
+            {
+              "text": "children",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "readonly",
+              "kind": "keyword"
+            },
+            {
+              "text": " ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": "[]",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Snapshot of the current children in document order. Frozen and cached - repeated reads return the same array reference until the next structural change (addChild/removeChild/setChildIndex/ swapChildren/etc.), which invalidates it. A reference to a previous snapshot is unaffected by later changes - it keeps reflecting the child list as it was at the time of the read. Mutating methods (push, splice, ...) throw in normal (strict-mode) usage; go through addChild/removeChild instead so parent linkage, stage propagation, and bounds invalidation stay consistent."
+        },
+        {
+          "name": "clip",
+          "signature": "clip: boolean",
+          "signatureTokens": [
+            {
+              "text": "clip",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "When true, descendants are geometrically clipped to clipShape. Unlike mask (which is alpha/visibility masking), clip is a hard geometric boundary: - clipShape === null - clip to this node's world-space bounds (getBounds), using the GPU scissor fast path. - clipShape is a Rectangle - clip to that world-space rectangle via scissor. - clipShape is a Geometry - clip to the geometry's silhouette via the stencil buffer (WebGL2). Only fragments inside the shape survive. Clipping wraps the node's final (filtered/masked) output and acts as a render barrier: draw commands are never reordered or batched across the clip boundary."
+        },
+        {
+          "name": "clipShape",
+          "signature": "clipShape: Geometry | Rectangle | null",
+          "signatureTokens": [
+            {
+              "text": "clipShape",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Geometry",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Rectangle",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Clip region used when clip is true. A Rectangle (or null for the node's bounds) maps to the scissor fast path; a Geometry maps to the stencil path. Has no effect while clip is false."
+        },
+        {
+          "name": "cullable",
+          "signature": "cullable: boolean",
+          "signatureTokens": [
+            {
+              "text": "cullable",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "When false, this node is never culled by the viewport check and is always considered in-view. Defaults to true."
+        },
+        {
+          "name": "cullArea",
+          "signature": "cullArea: Rectangle | null",
+          "signatureTokens": [
+            {
+              "text": "cullArea",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Rectangle",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Custom rectangle used for viewport cull intersection test. When set, replaces the default node bounds in cull checks. Set to null to restore default bounds-based culling."
+        },
+        {
+          "name": "destroyed",
+          "signature": "destroyed: boolean",
+          "signatureTokens": [
+            {
+              "text": "destroyed",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "true once destroy has run on this node. A destroyed node has released its pooled resources (transform/bounds), has been unlinked from its parent, renders nothing, and must not be reused or re-attached. The render plan skips a destroyed node, so even one handed straight to a renderer as a detached root contributes nothing."
+        },
+        {
+          "name": "filters",
+          "signature": "filters: readonly Filter[]",
+          "signatureTokens": [
+            {
+              "text": "filters",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "readonly",
+              "kind": "keyword"
+            },
+            {
+              "text": " ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Filter",
+              "kind": "type"
+            },
+            {
+              "text": "[]",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "height",
+          "signature": "height: number",
+          "signatureTokens": [
+            {
+              "text": "height",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Rendered height of the whole subtree - see width."
+        },
+        {
+          "name": "interactive",
+          "signature": "interactive: boolean",
+          "signatureTokens": [
+            {
+              "text": "interactive",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "isAlignedBox",
+          "signature": "isAlignedBox: boolean",
+          "signatureTokens": [
+            {
+              "text": "isAlignedBox",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "left",
+          "signature": "left: number",
+          "signatureTokens": [
+            {
+              "text": "left",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Leftmost edge of the subtree in the node's global-transform space. These four edges are read straight off the aggregate bounds so they always span exactly width/height and agree with each other. They cannot be reconstructed from position and origin: origin is in local pixels and a container's own local bounds are empty, so the rendered extent comes entirely from the children."
+        },
+        {
+          "name": "mask",
+          "signature": "mask: MaskSource",
+          "signatureTokens": [
+            {
+              "text": "mask",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "MaskSource",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The mask source that controls visibility of this node's render output. See MaskSource for accepted source types and their semantics. Setting to null removes any active mask. Setting a RenderNode that is this is rejected (a node cannot mask itself). Indirect cycles (a.mask = b; b.mask = a) are rejected as well: the candidate's mask chain is walked and any cycle - whether it closes on this or was already present in the chain - fails the assignment."
+        },
+        {
+          "name": "origin",
+          "signature": "origin: ObservableVector",
+          "signatureTokens": [
+            {
+              "text": "origin",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "ObservableVector",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "parent",
+          "signature": "parent: Container | null",
+          "signatureTokens": [
+            {
+              "text": "parent",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Container",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "position",
+          "signature": "position: ObservableVector",
+          "signatureTokens": [
+            {
+              "text": "position",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "ObservableVector",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "preserveDrawOrder",
+          "signature": "preserveDrawOrder: boolean",
+          "signatureTokens": [
+            {
+              "text": "preserveDrawOrder",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "When true, material-aware overlap reordering is disabled for this node's draw-order scope. Draw commands are submitted in exact document order (after scope-local z-sorting), preserving the painter's guarantee irrespective of material compatibility or AABB safety analysis. Adjacency coalescing of consecutive same-material draws still applies; it does not change visual output order."
+        },
+        {
+          "name": "right",
+          "signature": "right: number",
+          "signatureTokens": [
+            {
+              "text": "right",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Rightmost edge of the subtree - see left."
+        },
+        {
+          "name": "rotation",
+          "signature": "rotation: number",
+          "signatureTokens": [
+            {
+              "text": "rotation",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Rotation angle in degrees. Wraps via trimRotation on assignment."
+        },
+        {
+          "name": "scale",
+          "signature": "scale: ObservableVector",
+          "signatureTokens": [
+            {
+              "text": "scale",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "ObservableVector",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "skewX",
+          "signature": "skewX: number",
+          "signatureTokens": [
+            {
+              "text": "skewX",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Horizontal skew angle in degrees. Shears the node along the X axis (positive values lean the top edge right). Combines correctly with rotation and scale."
+        },
+        {
+          "name": "skewY",
+          "signature": "skewY: number",
+          "signatureTokens": [
+            {
+              "text": "skewY",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
+        },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "top",
+          "signature": "top: number",
+          "signatureTokens": [
+            {
+              "text": "top",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Topmost edge of the subtree - see left."
+        },
+        {
+          "name": "visible",
+          "signature": "visible: boolean",
+          "signatureTokens": [
+            {
+              "text": "visible",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "boolean",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "width",
+          "signature": "width: number",
+          "signatureTokens": [
+            {
+              "text": "width",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Rendered width of the whole subtree, in the node's global-transform space. Unlike Sprite.width - which scales an unscaled texture frame - a container has no intrinsic local size, so this reads the aggregate bounds directly. Those are already scaled, so multiplying by scale again would count it twice. Writing rescales scale.x to make the subtree render at the requested width."
+        },
+        {
+          "name": "x",
+          "signature": "x: number",
+          "signatureTokens": [
+            {
+              "text": "x",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "y",
+          "signature": "y: number",
+          "signatureTokens": [
+            {
+              "text": "y",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "zIndex",
+          "signature": "zIndex: number",
+          "signatureTokens": [
+            {
+              "text": "zIndex",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "events",
+      "title": "Events",
+      "members": [
+        {
+          "name": "onBlur",
+          "signature": "onBlur: Signal<[RenderNode]>",
+          "signatureTokens": [
+            {
+              "text": "onBlur",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired when this node loses keyboard focus."
+        },
+        {
+          "name": "onContextMenu",
+          "signature": "onContextMenu: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onContextMenu",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired when a pointer requests a context menu over this node - right-click, or a long-press/touch gesture that has an attributable pointer. Bubbles like the other pointer events, so a scene-wide fallback can listen on an ancestor. Carries no native event - whether the browser's own menu appears is decided by ApplicationOptions.input.allowNativeContextMenu, independently of this. Requires an attributable pointer: a pointerless keyboard-only request (the context-menu key, or Shift+F10, with no pointer ever having touched the surface - see ContextMenuRequest's doc comment) has nothing to hit-test or bubble with, so it never reaches this per-node event. It only ever reaches the engine-wide, scene-graph-independent app.input.onContextMenu."
+        },
+        {
+          "name": "onDrag",
+          "signature": "onDrag: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onDrag",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired on every pointer-move while this node is being dragged. Does not bubble."
+        },
+        {
+          "name": "onDragEnd",
+          "signature": "onDragEnd: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onDragEnd",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired when the drag gesture ends (pointer-up or cancel). Does not bubble."
+        },
+        {
+          "name": "onDragStart",
+          "signature": "onDragStart: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onDragStart",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired once when a drag gesture begins on this node. Does not bubble."
+        },
+        {
+          "name": "onFocus",
+          "signature": "onFocus: Signal<[RenderNode]>",
+          "signatureTokens": [
+            {
+              "text": "onFocus",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "RenderNode",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired when this node gains keyboard focus."
+        },
+        {
+          "name": "onKeyDown",
+          "signature": "onKeyDown: Signal<[KeyEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onKeyDown",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "KeyEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired for each key pressed while this node - or a descendant of it - holds focus. Bubbles; see KeyEvent."
+        },
+        {
+          "name": "onKeyUp",
+          "signature": "onKeyUp: Signal<[KeyEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onKeyUp",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "KeyEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Fired for each key released while this node - or a descendant of it - holds focus. Bubbles; see KeyEvent."
+        },
+        {
+          "name": "onPointerDown",
+          "signature": "onPointerDown: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onPointerDown",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "onPointerMove",
+          "signature": "onPointerMove: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onPointerMove",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "onPointerOut",
+          "signature": "onPointerOut: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onPointerOut",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "onPointerOver",
+          "signature": "onPointerOver: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onPointerOver",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "onPointerTap",
+          "signature": "onPointerTap: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onPointerTap",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "onPointerUp",
+          "signature": "onPointerUp: Signal<[InteractionEvent]>",
+          "signatureTokens": [
+            {
+              "text": "onPointerUp",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Signal",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "[",
+              "kind": "punctuation"
+            },
+            {
+              "text": "InteractionEvent",
+              "kind": "type"
+            },
+            {
+              "text": "]",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/ThemedContainer.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/ThemedContainer.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/ThemedContainer.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/ThemedContainer.ts"
+}
diff --git a/site/src/content/api/uibackground.json b/site/src/content/api/uibackground.json
new file mode 100644
index 000000000..256609483
--- /dev/null
+++ b/site/src/content/api/uibackground.json
@@ -0,0 +1,79 @@
+{
+  "title": "UIBackground",
+  "description": "How a widget paints its body.",
+  "symbol": "UIBackground",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "How a widget paints its body."
+      ],
+      "importLine": "import { UIBackground } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UIBackground",
+          "signature": "UIFillBackground | UINineSliceBackground | UINoBackground",
+          "signatureTokens": [
+            {
+              "text": "UIFillBackground",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UINineSliceBackground",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UINoBackground",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uifill-background.json b/site/src/content/api/uifill-background.json
new file mode 100644
index 000000000..92c5971be
--- /dev/null
+++ b/site/src/content/api/uifill-background.json
@@ -0,0 +1,155 @@
+{
+  "title": "UIFillBackground",
+  "description": "Vector background: a rounded rectangle with an optional stroked border.",
+  "symbol": "UIFillBackground",
+  "kind": "interface",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 5,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 5,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Vector background: a rounded rectangle with an optional stroked border."
+      ],
+      "importLine": "import { UIFillBackground } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "borderColor",
+          "signature": "borderColor: Color",
+          "signatureTokens": [
+            {
+              "text": "borderColor",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Color",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "borderWidth",
+          "signature": "borderWidth: number",
+          "signatureTokens": [
+            {
+              "text": "borderWidth",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Border thickness in pixels; 0 draws no border."
+        },
+        {
+          "name": "color",
+          "signature": "color: Color",
+          "signatureTokens": [
+            {
+              "text": "color",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Color",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "cornerRadius",
+          "signature": "cornerRadius: number",
+          "signatureTokens": [
+            {
+              "text": "cornerRadius",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Corner radius in pixels, clamped to half the widget's smaller side."
+        },
+        {
+          "name": "kind",
+          "signature": "kind: \"fill\"",
+          "signatureTokens": [
+            {
+              "text": "kind",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"fill\"",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uifill-patch.json b/site/src/content/api/uifill-patch.json
new file mode 100644
index 000000000..97789582d
--- /dev/null
+++ b/site/src/content/api/uifill-patch.json
@@ -0,0 +1,150 @@
+{
+  "title": "UIFillPatch",
+  "description": "Fill properties to override on a widget's background; omitted ones keep the skin's value.",
+  "symbol": "UIFillPatch",
+  "kind": "interface",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 4,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 4,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Fill properties to override on a widget's background; omitted ones keep the skin's value."
+      ],
+      "importLine": "import { UIFillPatch } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "borderColor",
+          "signature": "borderColor?: Color",
+          "signatureTokens": [
+            {
+              "text": "borderColor",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Color",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "borderWidth",
+          "signature": "borderWidth?: number",
+          "signatureTokens": [
+            {
+              "text": "borderWidth",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "color",
+          "signature": "color?: Color",
+          "signatureTokens": [
+            {
+              "text": "color",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Color",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "cornerRadius",
+          "signature": "cornerRadius?: number",
+          "signatureTokens": [
+            {
+              "text": "cornerRadius",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uiinsets.json b/site/src/content/api/uiinsets.json
new file mode 100644
index 000000000..f37ce9344
--- /dev/null
+++ b/site/src/content/api/uiinsets.json
@@ -0,0 +1,134 @@
+{
+  "title": "UIInsets",
+  "description": "Per-edge pixel insets. A skin's insets are layout input, not decoration: they describe the content box a widget positions its content in, so changing them re-lays out the widget rather than only repainting it.",
+  "symbol": "UIInsets",
+  "kind": "interface",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 4,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 4,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Per-edge pixel insets. A skin's insets are layout input, not decoration: they describe the content box a widget positions its content in, so changing them re-lays out the widget rather than only repainting it."
+      ],
+      "importLine": "import { UIInsets } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "bottom",
+          "signature": "bottom: number",
+          "signatureTokens": [
+            {
+              "text": "bottom",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "left",
+          "signature": "left: number",
+          "signatureTokens": [
+            {
+              "text": "left",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "right",
+          "signature": "right: number",
+          "signatureTokens": [
+            {
+              "text": "right",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "top",
+          "signature": "top: number",
+          "signatureTokens": [
+            {
+              "text": "top",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uinine-slice-background.json b/site/src/content/api/uinine-slice-background.json
new file mode 100644
index 000000000..75a8e03d1
--- /dev/null
+++ b/site/src/content/api/uinine-slice-background.json
@@ -0,0 +1,211 @@
+{
+  "title": "UINineSliceBackground",
+  "description": "Textured background drawn as a nine-slice, so corners stay pixel-perfect while edges and center fill the widget's layout size.",
+  "symbol": "UINineSliceBackground",
+  "kind": "interface",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 5,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 5,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Textured background drawn as a nine-slice, so corners stay pixel-perfect while edges and center fill the widget's layout size."
+      ],
+      "importLine": "import { UINineSliceBackground } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "border",
+          "signature": "border?: Partial<NineSliceInsets> | number",
+          "signatureTokens": [
+            {
+              "text": "border",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "NineSliceInsets",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Destination border widths; defaults to slices (1:1 corners)."
+        },
+        {
+          "name": "kind",
+          "signature": "kind: \"nineSlice\"",
+          "signatureTokens": [
+            {
+              "text": "kind",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"nineSlice\"",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "modes",
+          "signature": "modes?: NineSliceModes",
+          "signatureTokens": [
+            {
+              "text": "modes",
+              "kind": "name"
+            },
+            {
+              "text": "?",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "NineSliceModes",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "slices",
+          "signature": "slices: Partial<NineSliceInsets> | number",
+          "signatureTokens": [
+            {
+              "text": "slices",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "NineSliceInsets",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "number",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Source-texture slice widths, in texels."
+        },
+        {
+          "name": "texture",
+          "signature": "texture: Texture | TextureRegion",
+          "signatureTokens": [
+            {
+              "text": "texture",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Texture",
+              "kind": "type"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "TextureRegion",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uino-background.json b/site/src/content/api/uino-background.json
new file mode 100644
index 000000000..48601d5b7
--- /dev/null
+++ b/site/src/content/api/uino-background.json
@@ -0,0 +1,71 @@
+{
+  "title": "UINoBackground",
+  "description": "Widget surface that paints nothing - the whole node is its content.",
+  "symbol": "UINoBackground",
+  "kind": "interface",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 1,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 1,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Widget surface that paints nothing - the whole node is its content."
+      ],
+      "importLine": "import { UINoBackground } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "kind",
+          "signature": "kind: \"none\"",
+          "signatureTokens": [
+            {
+              "text": "kind",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"none\"",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uiroot.json b/site/src/content/api/uiroot.json
index 58c1de693..d6e9d41ca 100644
--- a/site/src/content/api/uiroot.json
+++ b/site/src/content/api/uiroot.json
@@ -1,16 +1,16 @@
 {
   "title": "UIRoot",
-  "description": "Root of a scene's screen-fixed UI layer. Reached through Scene.ui; you do not construct it directly. Unlike Scene.root, the UI layer is **auto-rendered** by the SceneDirector after `Scene.draw()`, through the RenderingContext.screenView - so its children live in screen space (origin top-left, `0..width` × `0..height`) and never scroll with the camera. Pointer hit-testing and keyboard focus are routed to UI nodes in that same screen space, ahead of the world layer. Add widgets with `scene.ui.addChild(...)`. The UIRoot.onResize signal fires whenever the screen size changes, so anchored widgets can re-layout.",
+  "description": "Root of a scene's screen-fixed UI layer. Reached through Scene.ui; you do not construct it directly. Unlike Scene.root, the UI layer is **auto-rendered** by the SceneDirector after `Scene.draw()`, through the RenderingContext.screenView - so its children live in screen space (origin top-left, `0..width` × `0..height`) and never scroll with the camera. Pointer hit-testing and keyboard focus are routed to UI nodes in that same screen space, ahead of the world layer. Add widgets with `scene.ui.addChild(...)`. The UIRoot.onResize signal fires whenever the screen size changes, so anchored widgets can re-layout. The root also carries the layer's UIRoot.theme: widgets resolve their skins from the nearest themed ancestor, so assigning a theme here restyles every widget below that does not override it.",
   "symbol": "UIRoot",
   "kind": "class",
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 96,
+  "memberCount": 99,
   "counts": {
     "constructors": 1,
-    "methods": 41,
-    "properties": 39,
+    "methods": 43,
+    "properties": 40,
     "events": 15
   },
   "sections": [
@@ -21,7 +21,8 @@
       "paragraphs": [
         "Root of a scene's screen-fixed UI layer. Reached through Scene.ui; you do not construct it directly.",
         "Unlike Scene.root, the UI layer is **auto-rendered** by the SceneDirector after `Scene.draw()`, through the RenderingContext.screenView - so its children live in screen space (origin top-left, `0..width` × `0..height`) and never scroll with the camera. Pointer hit-testing and keyboard focus are routed to UI nodes in that same screen space, ahead of the world layer.",
-        "Add widgets with `scene.ui.addChild(...)`. The UIRoot.onResize signal fires whenever the screen size changes, so anchored widgets can re-layout."
+        "Add widgets with `scene.ui.addChild(...)`. The UIRoot.onResize signal fires whenever the screen size changes, so anchored widgets can re-layout.",
+        "The root also carries the layer's UIRoot.theme: widgets resolve their skins from the nearest themed ancestor, so assigning a theme here restyles every widget below that does not override it."
       ],
       "importLine": "import { UIRoot } from '@codexo/exojs'",
       "sourceLink": null
@@ -68,6 +69,64 @@
       "id": "methods",
       "title": "Methods",
       "members": [
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
         {
           "name": "[iterator]",
           "signature": "[iterator](): IterableIterator<RenderNode>",
@@ -2790,6 +2849,27 @@
           "returnType": null,
           "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
         },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "Base theme for every widget in this layer. Widgets override parts of it per subtree with Widget.setTheme; there is no global theme, so two UI layers can carry different ones. Assigning restyles the whole layer at once - every widget below repaints and re-lays out."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/site/src/content/api/uiskin-patch.json b/site/src/content/api/uiskin-patch.json
new file mode 100644
index 000000000..c5d49d2e0
--- /dev/null
+++ b/site/src/content/api/uiskin-patch.json
@@ -0,0 +1,75 @@
+{
+  "title": "UISkinPatch",
+  "description": "Skin fields to override; an omitted field keeps the inherited one.",
+  "symbol": "UISkinPatch",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Skin fields to override; an omitted field keeps the inherited one."
+      ],
+      "importLine": "import { UISkinPatch } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UISkinPatch",
+          "signature": "Partial<UISkin>",
+          "signatureTokens": [
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uiskin-set-patch.json b/site/src/content/api/uiskin-set-patch.json
new file mode 100644
index 000000000..f980f80d3
--- /dev/null
+++ b/site/src/content/api/uiskin-set-patch.json
@@ -0,0 +1,107 @@
+{
+  "title": "UISkinSetPatch",
+  "description": "Per-state skin overrides.",
+  "symbol": "UISkinSetPatch",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Per-state skin overrides."
+      ],
+      "importLine": "import { UISkinSetPatch } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UISkinSetPatch",
+          "signature": "Partial<Readonly<Record<UIWidgetState, UISkinPatch>>>",
+          "signatureTokens": [
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkinPatch",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uiskin-set.json b/site/src/content/api/uiskin-set.json
new file mode 100644
index 000000000..94862baa9
--- /dev/null
+++ b/site/src/content/api/uiskin-set.json
@@ -0,0 +1,151 @@
+{
+  "title": "UISkinSet",
+  "description": "One skin per state. Only `normal` is required - resolveUISkin falls back to it for every state a set does not define.",
+  "symbol": "UISkinSet",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "One skin per state. Only `normal` is required - resolveUISkin falls back to it for every state a set does not define."
+      ],
+      "importLine": "import { UISkinSet } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UISkinSet",
+          "signature": "{ normal: UISkin } & Partial<Readonly<Record<Exclude<UIWidgetState, \"normal\">, UISkin>>>",
+          "signatureTokens": [
+            {
+              "text": "{ ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "normal",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": " }",
+              "kind": "punctuation"
+            },
+            {
+              "text": " & ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Exclude",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"normal\"",
+              "kind": "keyword"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uiskin.json b/site/src/content/api/uiskin.json
new file mode 100644
index 000000000..e096d66c0
--- /dev/null
+++ b/site/src/content/api/uiskin.json
@@ -0,0 +1,113 @@
+{
+  "title": "UISkin",
+  "description": "The look of one widget surface in one state: what it paints, how its text is styled, and the content box its layout works against.",
+  "symbol": "UISkin",
+  "kind": "interface",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 3,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 3,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "The look of one widget surface in one state: what it paints, how its text is styled, and the content box its layout works against."
+      ],
+      "importLine": "import { UISkin } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "properties",
+      "title": "Properties",
+      "members": [
+        {
+          "name": "background",
+          "signature": "background: UIBackground",
+          "signatureTokens": [
+            {
+              "text": "background",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIBackground",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "insets",
+          "signature": "insets: UIInsets",
+          "signatureTokens": [
+            {
+              "text": "insets",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIInsets",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        },
+        {
+          "name": "text",
+          "signature": "text: TextStyleOptions",
+          "signatureTokens": [
+            {
+              "text": "text",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "TextStyleOptions",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uitheme-patch.json b/site/src/content/api/uitheme-patch.json
new file mode 100644
index 000000000..4c5fdabac
--- /dev/null
+++ b/site/src/content/api/uitheme-patch.json
@@ -0,0 +1,107 @@
+{
+  "title": "UIThemePatch",
+  "description": "Theme overrides applied on top of an inherited theme. Fields are replaced whole: naming `background` replaces the entire descriptor, since blending half a fill into a nine-slice has no meaning. Single-property tweaks belong on the widget (`panel.setFill({ color })`), not in a theme patch.",
+  "symbol": "UIThemePatch",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Theme overrides applied on top of an inherited theme. Fields are replaced whole: naming `background` replaces the entire descriptor, since blending half a fill into a nine-slice has no meaning. Single-property tweaks belong on the widget (`panel.setFill({ color })`), not in a theme patch."
+      ],
+      "importLine": "import { UIThemePatch } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UIThemePatch",
+          "signature": "Partial<Readonly<Record<UIThemeRole, UISkinSetPatch>>>",
+          "signatureTokens": [
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkinSetPatch",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uitheme-role.json b/site/src/content/api/uitheme-role.json
new file mode 100644
index 000000000..acccc724a
--- /dev/null
+++ b/site/src/content/api/uitheme-role.json
@@ -0,0 +1,95 @@
+{
+  "title": "UIThemeRole",
+  "description": "A themed surface. Roles are per painted surface, not per widget class: a progress bar draws its track and its fill from two independent roles.",
+  "symbol": "UIThemeRole",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "A themed surface. Roles are per painted surface, not per widget class: a progress bar draws its track and its fill from two independent roles."
+      ],
+      "importLine": "import { UIThemeRole } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UIThemeRole",
+          "signature": "\"button\" | \"label\" | \"panel\" | \"progressBarFill\" | \"progressBarTrack\"",
+          "signatureTokens": [
+            {
+              "text": "\"button\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"label\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"panel\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"progressBarFill\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"progressBarTrack\"",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uitheme.json b/site/src/content/api/uitheme.json
new file mode 100644
index 000000000..155a118b9
--- /dev/null
+++ b/site/src/content/api/uitheme.json
@@ -0,0 +1,95 @@
+{
+  "title": "UITheme",
+  "description": "Skins for every role, as resolved for a widget.",
+  "symbol": "UITheme",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Skins for every role, as resolved for a widget."
+      ],
+      "importLine": "import { UITheme } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UITheme",
+          "signature": "Readonly<Record<UIThemeRole, UISkinSet>>",
+          "signatureTokens": [
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkinSet",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/uiwidget-state.json b/site/src/content/api/uiwidget-state.json
new file mode 100644
index 000000000..a5cd461ea
--- /dev/null
+++ b/site/src/content/api/uiwidget-state.json
@@ -0,0 +1,95 @@
+{
+  "title": "UIWidgetState",
+  "description": "Visual state a widget paints in. A widget that tracks no interaction stays on `'normal'`; states a skin set leaves undefined fall back to `'normal'`.",
+  "symbol": "UIWidgetState",
+  "kind": "type",
+  "subsystem": "ui",
+  "importPath": "@codexo/exojs",
+  "tier": "stable",
+  "memberCount": 0,
+  "counts": {
+    "constructors": 0,
+    "methods": 0,
+    "properties": 0,
+    "events": 0
+  },
+  "sections": [
+    {
+      "id": "import",
+      "title": "Import",
+      "members": [],
+      "paragraphs": [
+        "Visual state a widget paints in. A widget that tracks no interaction stays on `'normal'`; states a skin set leaves undefined fall back to `'normal'`."
+      ],
+      "importLine": "import { UIWidgetState } from '@codexo/exojs'",
+      "sourceLink": null
+    },
+    {
+      "id": "definition",
+      "title": "Definition",
+      "members": [
+        {
+          "name": "UIWidgetState",
+          "signature": "\"disabled\" | \"focused\" | \"hover\" | \"normal\" | \"pressed\"",
+          "signatureTokens": [
+            {
+              "text": "\"disabled\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"focused\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"hover\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"normal\"",
+              "kind": "keyword"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "\"pressed\"",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": ""
+        }
+      ],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": null
+    },
+    {
+      "id": "source",
+      "title": "Source",
+      "members": [],
+      "paragraphs": [],
+      "importLine": null,
+      "sourceLink": {
+        "label": "src/ui/theme.ts",
+        "href": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+      }
+    }
+  ],
+  "sourcePath": "src/ui/theme.ts",
+  "sourceUrl": "https://github.com/Exoridus/ExoJS/blob/main/src/ui/theme.ts"
+}
diff --git a/site/src/content/api/widget.json b/site/src/content/api/widget.json
index 4e633ebfd..2cbf283d8 100644
--- a/site/src/content/api/widget.json
+++ b/site/src/content/api/widget.json
@@ -1,16 +1,16 @@
 {
   "title": "Widget",
-  "description": "Base class for UI widgets - a Container with an explicit layout size (independent of child bounds / scale), an `enabled` flag, and optional screen-edge anchoring that re-applies on resize. Subclasses redraw size-dependent content in Widget._relayout and react to enable/disable in Widget._onEnabledChanged.",
+  "description": "Base class for UI widgets - a Container with an explicit layout size (independent of child bounds / scale), an `enabled` flag, and optional screen-edge anchoring that re-applies on resize. Widgets read their look from the theme of the nearest themed ancestor - the layer's UIRoot, or any widget above them that set overrides with Widget.setTheme. Subclasses paint in Widget._repaint, place size-dependent content in Widget._relayout, and react to enable/disable in Widget._onEnabledChanged.",
   "symbol": "Widget",
   "kind": "class",
   "subsystem": "ui",
   "importPath": "@codexo/exojs",
   "tier": "stable",
-  "memberCount": 102,
+  "memberCount": 113,
   "counts": {
     "constructors": 1,
-    "methods": 46,
-    "properties": 41,
+    "methods": 55,
+    "properties": 43,
     "events": 14
   },
   "sections": [
@@ -20,7 +20,8 @@
       "members": [],
       "paragraphs": [
         "Base class for UI widgets - a Container with an explicit layout size (independent of child bounds / scale), an `enabled` flag, and optional screen-edge anchoring that re-applies on resize.",
-        "Subclasses redraw size-dependent content in Widget._relayout and react to enable/disable in Widget._onEnabledChanged."
+        "Widgets read their look from the theme of the nearest themed ancestor - the layer's UIRoot, or any widget above them that set overrides with Widget.setTheme.",
+        "Subclasses paint in Widget._repaint, place size-dependent content in Widget._relayout, and react to enable/disable in Widget._onEnabledChanged."
       ],
       "importLine": "import { Widget } from '@codexo/exojs'",
       "sourceLink": null
@@ -135,6 +136,93 @@
           "returnType": "void",
           "description": ""
         },
+        {
+          "name": "_cascadeTheme",
+          "signature": "_cascadeTheme(): void",
+          "signatureTokens": [
+            {
+              "text": "_cascadeTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Push a theme refresh into every themed descendant."
+        },
+        {
+          "name": "_invalidateLayout",
+          "signature": "_invalidateLayout(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidateLayout",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Re-lay out and repaint, then re-apply screen anchoring. This is the right invalidation for anything a skin's insets or a font size can move, and for every size change."
+        },
+        {
+          "name": "_invalidatePaint",
+          "signature": "_invalidatePaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_invalidatePaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Repaint without re-laying out - for a change that cannot move anything, such as a colour or a state flip. Applied immediately, not batched."
+        },
         {
           "name": "_onEnabledChanged",
           "signature": "_onEnabledChanged(_effectiveEnabled: boolean): void",
@@ -182,6 +270,35 @@
           "returnType": "void",
           "description": "React to an effectiveEnabled change - fired whenever it flips, whether the widget's own enabled flag changed or an ancestor widget's did. Override in subclasses."
         },
+        {
+          "name": "_onThemeChanged",
+          "signature": "_onThemeChanged(): void",
+          "signatureTokens": [
+            {
+              "text": "_onThemeChanged",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "React to a resolved-theme change. The default re-lays out and repaints; override to re-read skin values that are cached elsewhere first, then call super._onThemeChanged()."
+        },
         {
           "name": "_relayout",
           "signature": "_relayout(): void",
@@ -209,7 +326,159 @@
           ],
           "params": [],
           "returnType": "void",
-          "description": "Redraw size-dependent content (background, child positions). Override in subclasses."
+          "description": "Re-place size-dependent content and repaint. Override in subclasses that position children; call super._relayout() to keep the repaint."
+        },
+        {
+          "name": "_repaint",
+          "signature": "_repaint(): void",
+          "signatureTokens": [
+            {
+              "text": "_repaint",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": "void",
+          "description": "Redraw this widget's own painted surfaces for the current size and skin. Override in subclasses that draw a background."
+        },
+        {
+          "name": "_resolveInheritedTheme",
+          "signature": "_resolveInheritedTheme(): UITheme",
+          "signatureTokens": [
+            {
+              "text": "_resolveInheritedTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": "UITheme",
+          "description": "The nearest themed ancestor's theme, or the built-in default when this node has none."
+        },
+        {
+          "name": "_setSkinState",
+          "signature": "_setSkinState(state: UIWidgetState): void",
+          "signatureTokens": [
+            {
+              "text": "_setSkinState",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "state",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "void",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "state",
+              "type": "UIWidgetState",
+              "optional": false
+            }
+          ],
+          "returnType": "void",
+          "description": "Switch the state skins resolve for, repainting when it actually changes."
+        },
+        {
+          "name": "_skin",
+          "signature": "_skin(role: UIThemeRole): UISkin",
+          "signatureTokens": [
+            {
+              "text": "_skin",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "role",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            }
+          ],
+          "params": [
+            {
+              "name": "role",
+              "type": "UIThemeRole",
+              "optional": false
+            }
+          ],
+          "returnType": "UISkin",
+          "description": "The skin role paints with in this widget's current state."
         },
         {
           "name": "[iterator]",
@@ -2107,6 +2376,161 @@
           "returnType": "this",
           "description": ""
         },
+        {
+          "name": "setTheme",
+          "signature": "setTheme(patch: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null): this",
+          "signatureTokens": [
+            {
+              "text": "setTheme",
+              "kind": "name"
+            },
+            {
+              "text": "(",
+              "kind": "punctuation"
+            },
+            {
+              "text": "patch",
+              "kind": "param"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            },
+            {
+              "text": ")",
+              "kind": "punctuation"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "this",
+              "kind": "keyword"
+            }
+          ],
+          "params": [
+            {
+              "name": "patch",
+              "type": "Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+              "optional": false
+            }
+          ],
+          "returnType": "this",
+          "description": "Override parts of the inherited theme for this widget and its descendants. null clears the override. Repaints and re-lays out every widget in the subtree that the change reaches - skin insets are layout input, so a theme change is never paint-only."
+        },
         {
           "name": "swapChildren",
           "signature": "swapChildren(firstChild: RenderNode, secondChild: RenderNode): this",
@@ -3111,6 +3535,156 @@
           "returnType": null,
           "description": "Vertical skew angle in degrees. Shears the node along the Y axis (positive values lean the left edge downward). Combines correctly with rotation and scale."
         },
+        {
+          "name": "theme",
+          "signature": "theme: UITheme",
+          "signatureTokens": [
+            {
+              "text": "theme",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UITheme",
+              "kind": "type"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "The theme in effect for this node and everything below it."
+        },
+        {
+          "name": "themeOverrides",
+          "signature": "themeOverrides: Partial<Readonly<Record<UIThemeRole, Partial<Readonly<Record<UIWidgetState, Partial<UISkin>>>>>>> | null",
+          "signatureTokens": [
+            {
+              "text": "themeOverrides",
+              "kind": "name"
+            },
+            {
+              "text": ": ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIThemeRole",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Readonly",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Record",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UIWidgetState",
+              "kind": "type"
+            },
+            {
+              "text": ", ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "Partial",
+              "kind": "type"
+            },
+            {
+              "text": "<",
+              "kind": "punctuation"
+            },
+            {
+              "text": "UISkin",
+              "kind": "type"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": ">",
+              "kind": "punctuation"
+            },
+            {
+              "text": " | ",
+              "kind": "punctuation"
+            },
+            {
+              "text": "null",
+              "kind": "keyword"
+            }
+          ],
+          "params": [],
+          "returnType": null,
+          "description": "This widget's own theme overrides, or null when it purely inherits."
+        },
         {
           "name": "top",
           "signature": "top: number",
diff --git a/test/core/__snapshots__/root-index-snapshot.test.ts.snap b/test/core/__snapshots__/root-index-snapshot.test.ts.snap
index 37a5d9b67..fc2a45984 100644
--- a/test/core/__snapshots__/root-index-snapshot.test.ts.snap
+++ b/test/core/__snapshots__/root-index-snapshot.test.ts.snap
@@ -225,6 +225,7 @@ exports[`root index export surface snapshot > sorted runtime export names match
   "TextureAssetType",
   "TextureFormat",
   "TextureRegion",
+  "ThemedContainer",
   "Time",
   "Timer",
   "Tooltip",
@@ -268,10 +269,12 @@ exports[`root index export surface snapshot > sorted runtime export names match
   "createSteamControllerGamepadMapping",
   "createSteamDeckGamepadMapping",
   "createSwitchProGamepadMapping",
+  "createUITheme",
   "createXboxGamepadMapping",
   "crossFade",
   "csvType",
   "decodeAudioData",
+  "defaultUITheme",
   "fontType",
   "formatShaderError",
   "getAudioContext",
@@ -296,6 +299,7 @@ exports[`root index export surface snapshot > sorted runtime export names match
   "registerAudioWorkletProcessor",
   "registerSerializer",
   "resetRenderStats",
+  "resolveUISkin",
   "serializeCacheRecordKey",
   "sign",
   "soundType",
diff --git a/test/core/__snapshots__/root-index-type-inventory.test.ts.snap b/test/core/__snapshots__/root-index-type-inventory.test.ts.snap
index 124ecc41b..cd2b0dd84 100644
--- a/test/core/__snapshots__/root-index-type-inventory.test.ts.snap
+++ b/test/core/__snapshots__/root-index-type-inventory.test.ts.snap
@@ -106,6 +106,7 @@ exports[`root index type-level export inventory > all exported symbols with kind
   "ButtonBinding: type alias",
   "ButtonLikeAction: class",
   "ButtonOptions: interface",
+  "ButtonState: type alias",
   "CacheContext: interface",
   "CacheFirstPolicy: class",
   "CacheLayout: interface",
@@ -559,6 +560,7 @@ exports[`root index type-level export inventory > all exported symbols with kind
   "TextureRegionOptions: interface",
   "TextureSource: type alias",
   "TextureUploadOptions: interface",
+  "ThemedContainer: class",
   "Time: variable",
   "TimeSource: interface",
   "Timer: class",
@@ -574,7 +576,21 @@ exports[`root index type-level export inventory > all exported symbols with kind
   "TweenUpdateCallback: type alias",
   "TypedArray: type alias",
   "TypedEnum: type alias",
+  "UIBackground: type alias",
+  "UIFillBackground: interface",
+  "UIFillPatch: interface",
+  "UIInsets: interface",
+  "UINineSliceBackground: interface",
+  "UINoBackground: interface",
   "UIRoot: class",
+  "UISkin: interface",
+  "UISkinPatch: type alias",
+  "UISkinSet: type alias",
+  "UISkinSetPatch: type alias",
+  "UITheme: type alias",
+  "UIThemePatch: type alias",
+  "UIThemeRole: type alias",
+  "UIWidgetState: type alias",
   "UniformValue: type alias",
   "UnloadOptions: interface",
   "UnregisteredSceneError: class",
@@ -627,10 +643,12 @@ exports[`root index type-level export inventory > all exported symbols with kind
   "createSteamControllerGamepadMapping: variable",
   "createSteamDeckGamepadMapping: variable",
   "createSwitchProGamepadMapping: variable",
+  "createUITheme: variable",
   "createXboxGamepadMapping: variable",
   "crossFade: variable",
   "csvType: variable",
   "decodeAudioData: variable",
+  "defaultUITheme: variable",
   "fontType: variable",
   "formatShaderError: variable",
   "getAudioContext: variable",
@@ -655,6 +673,7 @@ exports[`root index type-level export inventory > all exported symbols with kind
   "registerAudioWorkletProcessor: variable",
   "registerSerializer: variable",
   "resetRenderStats: variable",
+  "resolveUISkin: variable",
   "serializeCacheRecordKey: variable",
   "sign: variable",
   "soundType: variable",

From f6ef32165c5a4e8d6e8197923ada0f61b0ce0544 Mon Sep 17 00:00:00 2001
From: Exoridus <github@codexo.de>
Date: Thu, 27 Aug 2026 21:36:04 +0200
Subject: [PATCH 5/6] docs(guide): document UI theming and the widget style
 setters

Adds a Theming section to the UI chapter: where a widget's skin comes
from, what a background descriptor can be, and why style goes through a
setter instead of a mutable style object.
---
 .../content/guide/runtime/ui-and-widgets.mdx  | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/site/src/content/guide/runtime/ui-and-widgets.mdx b/site/src/content/guide/runtime/ui-and-widgets.mdx
index 68751e380..f97728e96 100644
--- a/site/src/content/guide/runtime/ui-and-widgets.mdx
+++ b/site/src/content/guide/runtime/ui-and-widgets.mdx
@@ -35,6 +35,38 @@ start.onClick.add(() => console.log('clicked'));
 
 A `Label` wraps a runtime [`Text`](/ExoJS/en/api/text/), so it accepts the same style options (`fontSize`, `fillColor`, `align`, …). A `Panel` is a rounded background you can add children to. A `Button` is a clickable panel with a centered label and hover / pressed / disabled states.
 
+## Theming
+
+A widget does not carry its own colours: it paints a **skin** it resolves from the theme of the nearest themed ancestor — the layer's [`UIRoot`](/ExoJS/en/api/uiroot/), or any widget above it that set overrides. A [`UITheme`](/ExoJS/en/api/uitheme/) holds one [`UISkinSet`](/ExoJS/en/api/uiskin-set/) per role (`panel`, `button`, `label`, `progressBarTrack`, `progressBarFill`), and each skin carries a [`UIBackground`](/ExoJS/en/api/uibackground/) descriptor, a text style, and insets. Insets are layout input, so a theme change re-lays out as well as repaints.
+
+`createUITheme` resolves a patch against the built-in default, which reproduces the widgets' stock look. Assign the result to `scene.ui.theme` to restyle a whole layer, or call `widget.setTheme(patch)` to restyle one subtree:
+
+```ts
+import { Color, createUITheme, Panel } from '@codexo/exojs';
+
+const dark = createUITheme({
+  panel: {
+    normal: {
+      background: { kind: 'fill', color: new Color(18, 20, 28, 1), borderColor: new Color(255, 255, 255, 0.08), borderWidth: 1, cornerRadius: 12 },
+    },
+  },
+  button: {
+    hover: {
+      background: { kind: 'fill', color: new Color(90, 160, 250, 1), borderColor: Color.transparent, borderWidth: 0, cornerRadius: 8 },
+    },
+  },
+});
+
+const dialog = new Panel({ width: 280, height: 160 });
+
+dialog.setTheme({ panel: { normal: { background: dark.panel.normal.background } } });
+dialog.setFill({ color: new Color(40, 44, 60, 1) }); // this panel only, on top of its skin
+```
+
+A background descriptor is either a fill (the rounded rectangle above), `{ kind: 'none' }`, or a nine-slice: `{ kind: 'nineSlice', texture, slices: 8 }` paints a texture that stretches without distorting its corners.
+
+Per-widget style always goes through a setter — `setFill`, `setBackground`, `setTextStyle` — so a change repaints (and re-lays out where it can move something) immediately. Reading `panel.color` gives the value in effect, including the theme's; `panel.fillOverrides` gives only what this panel overrides.
+
 ## Anchoring to the screen
 
 Widgets extend [`Widget`](/ExoJS/en/api/widget/), which adds an explicit layout size and screen-edge anchoring. `widget.anchorIn(scene.ui, anchor, offsetX, offsetY)` pins a widget to a corner or edge and re-applies the position whenever the canvas resizes:

From 58c61fe1d5356191e27c8e64ff7e6554de756dd4 Mon Sep 17 00:00:00 2001
From: Exoridus <github@codexo.de>
Date: Thu, 27 Aug 2026 21:42:24 +0200
Subject: [PATCH 6/6] test(ui): follow the nullable style getters in the widget
 tests

A widget that paints a texture or nothing has no fill colour, so the
colour getters are nullable now.
---
 test/core/serialization.test.ts | 4 ++--
 test/ui/widgets.test.ts         | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/test/core/serialization.test.ts b/test/core/serialization.test.ts
index 1f7aaa820..f828d14b1 100644
--- a/test/core/serialization.test.ts
+++ b/test/core/serialization.test.ts
@@ -864,7 +864,7 @@ describe('serialization — UI widgets', () => {
     const restored = deserializeTree(data) as Button;
     expect(restored.label).toBe('Play');
     expect(restored.uiWidth).toBe(100);
-    expect(restored.colors.normal.r).toBe(10);
+    expect(restored.colors.normal?.r).toBe(10);
     expect(restored.enabled).toBe(false);
   });
 
@@ -877,7 +877,7 @@ describe('serialization — UI widgets', () => {
 
     const restored = deserializeTree(data) as ProgressBar;
     expect(restored.value).toBeCloseTo(0.42);
-    expect(restored.fillColor.g).toBe(2);
+    expect(restored.fillColor?.g).toBe(2);
   });
 
   it('round-trips a Stack (options + items)', () => {
diff --git a/test/ui/widgets.test.ts b/test/ui/widgets.test.ts
index bd66b5992..c4c809a47 100644
--- a/test/ui/widgets.test.ts
+++ b/test/ui/widgets.test.ts
@@ -265,8 +265,8 @@ describe('ProgressBar', () => {
   test('exposes trackColor, fillColor, cornerRadius getters', () => {
     const bar = new ProgressBar({ trackColor: new Color(1, 2, 3, 1), fillColor: new Color(4, 5, 6, 1), cornerRadius: 6 });
 
-    expect(bar.trackColor.r).toBe(1);
-    expect(bar.fillColor.r).toBe(4);
+    expect(bar.trackColor?.r).toBe(1);
+    expect(bar.fillColor?.r).toBe(4);
     expect(bar.cornerRadius).toBe(6);
   });