@mitcsutt/kiln-ui 0.1.0 → 0.2.1

package/dist/theme/ThemeProvider.d.ts

@@ -18,6 +18,12 @@ export interface ThemeProviderProps {
     onModeChange?: (mode: ColorMode) => void;
     /** Persist the user's mode choice in localStorage. Default `true`. */
     persistMode?: boolean;
+    /**
+     * The localStorage key the mode is stored under (default `kiln-color-mode`). Give each
+     * app on one origin its own key, or keep an existing one so readers' choices carry over.
+     * Pass the same key to `themeScript`.
+     */
+    storageKey?: string;
     /**
      * Where to write `data-theme` / `data-mode`. `document` (default) targets `<html>`,
      * which is what an app wants. Use `<ThemeScope>` for nested, local themes.
@@ -32,7 +38,7 @@ export interface ThemeProviderProps {
  * For SSR without a flash, also render `<script dangerouslySetInnerHTML={{ __html: themeScript() }} />`
  * in the document head (see `themeScript`).
  */
-export declare function ThemeProvider({ theme: themeProp, mode: modeProp, defaultMode, onThemeChange, onModeChange, persistMode, target, children, }: ThemeProviderProps): import("react").JSX.Element;
+export declare function ThemeProvider({ theme: themeProp, mode: modeProp, defaultMode, onThemeChange, onModeChange, persistMode, storageKey, target, children, }: ThemeProviderProps): import("react").JSX.Element;
 export interface ThemeScopeProps extends HTMLAttributes<HTMLDivElement> {
     theme: ThemeName;
     /** Omit to inherit the surrounding colour mode (the usual case). */

package/dist/theme/ThemeProvider.js

@@ -1,13 +1,14 @@
 import { DEFAULT_THEME as e } from "./themes.js";
-import { STORAGE_KEY as t, ThemeContext as n } from "./context.js";
+import { ThemeContext as t } from "./context.js";
+import { DEFAULT_STORAGE_KEY as n } from "./script.js";
 import { forwardRef as r, useCallback as i, useEffect as a, useMemo as o, useState as s, useSyncExternalStore as c } from "react";
 import { jsx as l } from "react/jsx-runtime";
 //#region src/theme/ThemeProvider.tsx
 var u = "(prefers-color-scheme: dark)";
-function d() {
+function d(e) {
 	try {
-		let e = typeof localStorage > "u" ? null : localStorage.getItem(t);
-		return e === "light" || e === "dark" || e === "system" ? e : void 0;
+		let t = typeof localStorage > "u" ? null : localStorage.getItem(e);
+		return t === "light" || t === "dark" || t === "system" ? t : void 0;
 	} catch {
 		return;
 	}
@@ -17,8 +18,8 @@ function f(e) {
 		window.removeEventListener("storage", e);
 	};
 }
-function p(e) {
-	return c(f, () => e ? d() : void 0, () => void 0);
+function p(e, t) {
+	return c(f, () => e ? d(t) : void 0, () => void 0);
 }
 function m(e) {
 	if (typeof matchMedia > "u") return () => void 0;
@@ -30,44 +31,48 @@ function m(e) {
 function h() {
 	return c(m, () => typeof matchMedia < "u" && matchMedia(u).matches, () => !1);
 }
-function g({ theme: r = e, mode: c, defaultMode: u = "system", onThemeChange: d, onModeChange: f, persistMode: m = !0, target: g = "document", children: _ }) {
-	let [v, y] = s(r), [b, x] = s(r);
-	r !== b && (x(r), y(r));
-	let [S, C] = s(c), [w, T] = s(c);
-	c !== w && (T(c), c && C(c));
-	let E = p(m && !c), D = S ?? E ?? u;
+function g({ theme: r = e, mode: c, defaultMode: u = "system", onThemeChange: d, onModeChange: f, persistMode: m = !0, storageKey: g = n, target: _ = "document", children: v }) {
+	let [y, b] = s(r), [x, S] = s(r);
+	r !== x && (S(r), b(r));
+	let [C, w] = s(c), [T, E] = s(c);
+	c !== T && (E(c), c && w(c));
+	let D = p(m && !c, g), O = C ?? D ?? u;
 	a(() => {
-		if (g !== "document" || typeof document > "u") return;
+		if (_ !== "document" || typeof document > "u") return;
 		let e = document.documentElement;
-		e.dataset.theme = v, e.dataset.mode = D;
+		e.dataset.theme = y, e.dataset.mode = O;
 	}, [
-		g,
-		v,
-		D
+		_,
+		y,
+		O
 	]);
-	let O = h(), k = D === "system" ? O ? "dark" : "light" : D, A = i((e) => {
-		y(e), d?.(e);
-	}, [d]), j = i((e) => {
-		if (C(e), m && typeof localStorage < "u") try {
-			localStorage.setItem(t, e);
+	let k = h(), A = O === "system" ? k ? "dark" : "light" : O, j = i((e) => {
+		b(e), d?.(e);
+	}, [d]), M = i((e) => {
+		if (w(e), m && typeof localStorage < "u") try {
+			localStorage.setItem(g, e);
 		} catch {}
 		f?.(e);
-	}, [f, m]), M = o(() => ({
-		theme: v,
-		mode: D,
-		resolvedMode: k,
-		setTheme: A,
-		setMode: j
+	}, [
+		f,
+		m,
+		g
+	]), N = o(() => ({
+		theme: y,
+		mode: O,
+		resolvedMode: A,
+		setTheme: j,
+		setMode: M
 	}), [
-		v,
-		D,
-		k,
+		y,
+		O,
 		A,
-		j
+		j,
+		M
 	]);
-	return /* @__PURE__ */ l(n.Provider, {
-		value: M,
-		children: _
+	return /* @__PURE__ */ l(t.Provider, {
+		value: N,
+		children: v
 	});
 }
 var _ = r(function({ theme: e, mode: t, paint: n = !0, ...r }, i) {

package/dist/theme/ThemeProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"ThemeProvider.js","names":["DARK_QUERY","readStoredMode","v","STORAGE_KEY","subscribeToStorage","onChange","useStoredMode","useSyncExternalStore","enabled","subscribeToSystemDark","mq","useSystemDark","ThemeProvider","themeProp","DEFAULT_THEME","modeProp","themeState","setThemeState","useState","prevThemeProp","setPrevThemeProp","chosenMode","setChosenMode","prevModeProp","setPrevModeProp","storedMode","persistMode","modeState","defaultMode","target","el","systemDark","resolvedMode","setTheme","useCallback","t","onThemeChange","setMode","m","onModeChange","value","useMemo","ThemeContext","ThemeScope","forwardRef","rest","theme","mode","paint"],"sources":["../../src/theme/ThemeProvider.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useCallback,\n  useEffect,\n  useMemo,\n  useState,\n  useSyncExternalStore,\n  type HTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { DEFAULT_THEME } from './themes'\nimport type { ColorMode, ThemeName } from './themes'\nimport type { ThemeContextValue } from './context'\n\nimport { ThemeContext, STORAGE_KEY } from './context'\n\nconst DARK_QUERY = '(prefers-color-scheme: dark)'\n\nfunction readStoredMode(): ColorMode | undefined {\n  try {\n    const v = typeof localStorage === 'undefined' ? null : localStorage.getItem(STORAGE_KEY)\n    return v === 'light' || v === 'dark' || v === 'system' ? v : undefined\n  } catch {\n    return undefined\n  }\n}\n\nfunction subscribeToStorage(onChange: () => void): () => void {\n  window.addEventListener('storage', onChange)\n  return () => {\n    window.removeEventListener('storage', onChange)\n  }\n}\n\n/**\n * The mode stored by an earlier visit, read only on the client (`undefined` while\n * rendering on the server and during hydration, so markup always matches).\n */\nfunction useStoredMode(enabled: boolean): ColorMode | undefined {\n  return useSyncExternalStore(\n    subscribeToStorage,\n    () => (enabled ? readStoredMode() : undefined),\n    () => undefined,\n  )\n}\n\nfunction subscribeToSystemDark(onChange: () => void): () => void {\n  if (typeof matchMedia === 'undefined') return () => undefined\n  const mq = matchMedia(DARK_QUERY)\n  mq.addEventListener('change', onChange)\n  return () => {\n    mq.removeEventListener('change', onChange)\n  }\n}\n\nfunction useSystemDark(): boolean {\n  return useSyncExternalStore(\n    subscribeToSystemDark,\n    () => typeof matchMedia !== 'undefined' && matchMedia(DARK_QUERY).matches,\n    () => false,\n  )\n}\n\nexport interface ThemeProviderProps {\n  /**\n   * Which theme to render (default `paper`). A built-in name, or any name your own\n   * `[data-theme='<name>']` stylesheet defines. Controlled if `onThemeChange` is also supplied.\n   */\n  theme?: ThemeName\n  /** Initial/controlled colour mode. `system` follows the OS via CSS alone — no flash. */\n  mode?: ColorMode\n  /**\n   * Uncontrolled starting mode when the user hasn't chosen one yet (default `system`).\n   * A stored choice (see `persistMode`) always wins. Monograph is dark-first, so apps\n   * using it usually pass `defaultMode=\"dark\"`. Pair with `themeScript(theme, defaultMode)`.\n   */\n  defaultMode?: ColorMode\n  onThemeChange?: (theme: ThemeName) => void\n  onModeChange?: (mode: ColorMode) => void\n  /** Persist the user's mode choice in localStorage. Default `true`. */\n  persistMode?: boolean\n  /**\n   * Where to write `data-theme` / `data-mode`. `document` (default) targets `<html>`,\n   * which is what an app wants. Use `<ThemeScope>` for nested, local themes.\n   */\n  target?: 'document' | 'none'\n  children: ReactNode\n}\n\n/**\n * App-level theme state. Writes `data-theme` + `data-mode` to `<html>` and exposes\n * `useTheme()`. All visual work happens in CSS; this component only flips attributes.\n *\n * For SSR without a flash, also render `<script dangerouslySetInnerHTML={{ __html: themeScript() }} />`\n * in the document head (see `themeScript`).\n */\nexport function ThemeProvider({\n  theme: themeProp = DEFAULT_THEME,\n  mode: modeProp,\n  defaultMode = 'system',\n  onThemeChange,\n  onModeChange,\n  persistMode = true,\n  target = 'document',\n  children,\n}: ThemeProviderProps) {\n  const [themeState, setThemeState] = useState<ThemeName>(themeProp)\n  const [prevThemeProp, setPrevThemeProp] = useState(themeProp)\n  // Follow the prop when it changes (React's \"adjust state on a prop change\" pattern).\n  if (themeProp !== prevThemeProp) {\n    setPrevThemeProp(themeProp)\n    setThemeState(themeProp)\n  }\n\n  // The latest explicit choice: a `mode` prop, or a `setMode` call. Unset until one happens.\n  const [chosenMode, setChosenMode] = useState<ColorMode | undefined>(modeProp)\n  const [prevModeProp, setPrevModeProp] = useState(modeProp)\n  if (modeProp !== prevModeProp) {\n    setPrevModeProp(modeProp)\n    if (modeProp) setChosenMode(modeProp)\n  }\n  // A stored choice wins over `defaultMode`, uncontrolled only.\n  const storedMode = useStoredMode(persistMode && !modeProp)\n  const modeState = chosenMode ?? storedMode ?? defaultMode\n\n  useEffect(() => {\n    if (target !== 'document' || typeof document === 'undefined') return\n    const el = document.documentElement\n    el.dataset.theme = themeState\n    el.dataset.mode = modeState\n  }, [target, themeState, modeState])\n\n  const systemDark = useSystemDark()\n  const resolvedMode = modeState === 'system' ? (systemDark ? 'dark' : 'light') : modeState\n\n  const setTheme = useCallback(\n    (t: ThemeName) => {\n      setThemeState(t)\n      onThemeChange?.(t)\n    },\n    [onThemeChange],\n  )\n\n  const setMode = useCallback(\n    (m: ColorMode) => {\n      setChosenMode(m)\n      if (persistMode && typeof localStorage !== 'undefined') {\n        try {\n          localStorage.setItem(STORAGE_KEY, m)\n        } catch {\n          /* storage unavailable — ignore */\n        }\n      }\n      onModeChange?.(m)\n    },\n    [onModeChange, persistMode],\n  )\n\n  const value = useMemo<ThemeContextValue>(\n    () => ({ theme: themeState, mode: modeState, resolvedMode, setTheme, setMode }),\n    [themeState, modeState, resolvedMode, setTheme, setMode],\n  )\n\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>\n}\n\nexport interface ThemeScopeProps extends HTMLAttributes<HTMLDivElement> {\n  theme: ThemeName\n  /** Omit to inherit the surrounding colour mode (the usual case). */\n  mode?: ColorMode\n  /**\n   * Paint the theme's canvas (background, text colour, base type) on the scope.\n   * Default `true`. Set `false` to drop a themed component into a rounded frame or\n   * a surface without a square background.\n   */\n  paint?: boolean\n}\n\n/**\n * Renders a subtree in a different theme (and optionally mode). Themes are plain CSS\n * scoped to `[data-theme]`, so scopes nest freely — e.g. a Fiesta card previewed on a\n * Monograph page. Also paints the theme's page background and text colour.\n */\nexport const ThemeScope = forwardRef<HTMLDivElement, ThemeScopeProps>(function ThemeScope(\n  { theme, mode, paint = true, ...rest },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      data-theme={theme}\n      data-mode={mode}\n      data-kiln-scope={paint ? '' : undefined}\n      data-kiln-scope-bare={paint ? undefined : ''}\n      {...rest}\n    />\n  )\n})\n"],"mappings":";;;;;AAgBA,IAAMA,IAAa;AAEnB,SAASC,IAAwC;CAC/C,IAAI;EACF,IAAMC,IAAI,OAAO,eAAiB,MAAc,OAAO,aAAa,QAAQC,CAAW;EACvF,OAAOD,MAAM,WAAWA,MAAM,UAAUA,MAAM,WAAWA,IAAI,KAAA;CAC/D,QAAQ;EACN;CACF;AACF;AAEA,SAASE,EAAmB,GAAkC;CAE5D,OADA,OAAO,iBAAiB,WAAWC,CAAQ,SAC9B;EACX,OAAO,oBAAoB,WAAWA,CAAQ;CAChD;AACF;AAMA,SAASC,EAAc,GAAyC;CAC9D,OAAOC,EACLH,SACOI,IAAUP,EAAe,IAAI,KAAA,SAC9B,KAAA,CACR;AACF;AAEA,SAASQ,EAAsB,GAAkC;CAC/D,IAAI,OAAO,aAAe,KAAa,aAAa,KAAA;CACpD,IAAMC,IAAK,WAAWV,CAAU;CAEhC,OADAU,EAAG,iBAAiB,UAAUL,CAAQ,SACzB;EACX,EAAG,oBAAoB,UAAUA,CAAQ;CAC3C;AACF;AAEA,SAASM,IAAyB;CAChC,OAAOJ,EACLE,SACM,OAAO,aAAe,OAAe,WAAWT,CAAU,CAAC,CAAC,eAC5D,EACR;AACF;AAmCA,SAAgBY,EAAc,EAC5B,OAAOC,IAAYC,GACnB,MAAMC,GACN,iBAAc,UACd,kBACA,iBACA,iBAAc,IACd,YAAS,YACT,eACqB;CACrB,IAAM,CAACC,GAAYC,KAAiBC,EAAoBL,CAAS,GAC3D,CAACM,GAAeC,KAAoBF,EAASL,CAAS;CAE5D,AAAIA,MAAcM,MAChBC,EAAiBP,CAAS,GAC1BI,EAAcJ,CAAS;CAIzB,IAAM,CAACQ,GAAYC,KAAiBJ,EAAgCH,CAAQ,GACtE,CAACQ,GAAcC,KAAmBN,EAASH,CAAQ;CACzD,AAAIA,MAAaQ,MACfC,EAAgBT,CAAQ,GACpBA,KAAUO,EAAcP,CAAQ;CAGtC,IAAMU,IAAanB,EAAcoB,KAAe,CAACX,CAAQ,GACnDY,IAAYN,KAAcI,KAAcG;CAE9C,QAAgB;EACd,IAAIC,MAAW,cAAc,OAAO,WAAa,KAAa;EAC9D,IAAMC,IAAK,SAAS;EAEpB,AADA,EAAG,QAAQ,QAAQd,GACnB,EAAG,QAAQ,OAAOW;CACpB,GAAG;EAACE;EAAQb;EAAYW;CAAS,CAAC;CAElC,IAAMI,IAAapB,EAAc,GAC3BqB,IAAeL,MAAc,WAAYI,IAAa,SAAS,UAAWJ,GAE1EM,IAAWC,GACd,MAAiB;EAEhB,AADAjB,EAAckB,CAAC,GACfC,IAAgBD,CAAC;CACnB,GACA,CAACC,CAAa,CAChB,GAEMC,IAAUH,GACb,MAAiB;EAEhB,IADAZ,EAAcgB,CAAC,GACXZ,KAAe,OAAO,eAAiB,KACzC,IAAI;GACF,aAAa,QAAQvB,GAAamC,CAAC;EACrC,QAAQ,CAER;EAEF,IAAeA,CAAC;CAClB,GACA,CAACC,GAAcb,CAAW,CAC5B,GAEMc,IAAQC,SACL;EAAE,OAAOzB;EAAY,MAAMW;EAAW;EAAc;EAAU;CAAQ,IAC7E;EAACX;EAAYW;EAAWK;EAAcC;EAAUI;CAAO,CACzD;CAEA,OAAO,kBAACK,EAAa,UAAd;EAA8B;EAAQ;CAAgC,CAAA;AAC/E;AAmBA,IAAaC,IAAaC,EAA4C,SACpE,EAAE,UAAO,SAAM,WAAQ,IAAM,GAAGC,KAChC,GACA;CACA,OACE,kBAAC,OAAD;EACO;EACL,cAAYC;EACZ,aAAWC;EACX,mBAAiBC,IAAQ,KAAK,KAAA;EAC9B,wBAAsBA,IAAQ,KAAA,IAAY;EAC1C,GAAIH;CACL,CAAA;AAEL,CAAC"}
+{"version":3,"file":"ThemeProvider.js","names":["DARK_QUERY","readStoredMode","v","storageKey","subscribeToStorage","onChange","useStoredMode","useSyncExternalStore","enabled","subscribeToSystemDark","mq","useSystemDark","ThemeProvider","themeProp","DEFAULT_THEME","modeProp","DEFAULT_STORAGE_KEY","themeState","setThemeState","useState","prevThemeProp","setPrevThemeProp","chosenMode","setChosenMode","prevModeProp","setPrevModeProp","storedMode","persistMode","modeState","defaultMode","target","el","systemDark","resolvedMode","setTheme","useCallback","t","onThemeChange","setMode","m","onModeChange","value","useMemo","ThemeContext","ThemeScope","forwardRef","rest","theme","mode","paint"],"sources":["../../src/theme/ThemeProvider.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useCallback,\n  useEffect,\n  useMemo,\n  useState,\n  useSyncExternalStore,\n  type HTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { DEFAULT_THEME } from './themes'\nimport type { ColorMode, ThemeName } from './themes'\nimport type { ThemeContextValue } from './context'\n\nimport { ThemeContext } from './context'\nimport { DEFAULT_STORAGE_KEY } from './script'\n\nconst DARK_QUERY = '(prefers-color-scheme: dark)'\n\nfunction readStoredMode(storageKey: string): ColorMode | undefined {\n  try {\n    const v = typeof localStorage === 'undefined' ? null : localStorage.getItem(storageKey)\n    return v === 'light' || v === 'dark' || v === 'system' ? v : undefined\n  } catch {\n    return undefined\n  }\n}\n\nfunction subscribeToStorage(onChange: () => void): () => void {\n  window.addEventListener('storage', onChange)\n  return () => {\n    window.removeEventListener('storage', onChange)\n  }\n}\n\n/**\n * The mode stored by an earlier visit, read only on the client (`undefined` while\n * rendering on the server and during hydration, so markup always matches).\n */\nfunction useStoredMode(enabled: boolean, storageKey: string): ColorMode | undefined {\n  return useSyncExternalStore(\n    subscribeToStorage,\n    () => (enabled ? readStoredMode(storageKey) : undefined),\n    () => undefined,\n  )\n}\n\nfunction subscribeToSystemDark(onChange: () => void): () => void {\n  if (typeof matchMedia === 'undefined') return () => undefined\n  const mq = matchMedia(DARK_QUERY)\n  mq.addEventListener('change', onChange)\n  return () => {\n    mq.removeEventListener('change', onChange)\n  }\n}\n\nfunction useSystemDark(): boolean {\n  return useSyncExternalStore(\n    subscribeToSystemDark,\n    () => typeof matchMedia !== 'undefined' && matchMedia(DARK_QUERY).matches,\n    () => false,\n  )\n}\n\nexport interface ThemeProviderProps {\n  /**\n   * Which theme to render (default `paper`). A built-in name, or any name your own\n   * `[data-theme='<name>']` stylesheet defines. Controlled if `onThemeChange` is also supplied.\n   */\n  theme?: ThemeName\n  /** Initial/controlled colour mode. `system` follows the OS via CSS alone — no flash. */\n  mode?: ColorMode\n  /**\n   * Uncontrolled starting mode when the user hasn't chosen one yet (default `system`).\n   * A stored choice (see `persistMode`) always wins. Monograph is dark-first, so apps\n   * using it usually pass `defaultMode=\"dark\"`. Pair with `themeScript(theme, defaultMode)`.\n   */\n  defaultMode?: ColorMode\n  onThemeChange?: (theme: ThemeName) => void\n  onModeChange?: (mode: ColorMode) => void\n  /** Persist the user's mode choice in localStorage. Default `true`. */\n  persistMode?: boolean\n  /**\n   * The localStorage key the mode is stored under (default `kiln-color-mode`). Give each\n   * app on one origin its own key, or keep an existing one so readers' choices carry over.\n   * Pass the same key to `themeScript`.\n   */\n  storageKey?: string\n  /**\n   * Where to write `data-theme` / `data-mode`. `document` (default) targets `<html>`,\n   * which is what an app wants. Use `<ThemeScope>` for nested, local themes.\n   */\n  target?: 'document' | 'none'\n  children: ReactNode\n}\n\n/**\n * App-level theme state. Writes `data-theme` + `data-mode` to `<html>` and exposes\n * `useTheme()`. All visual work happens in CSS; this component only flips attributes.\n *\n * For SSR without a flash, also render `<script dangerouslySetInnerHTML={{ __html: themeScript() }} />`\n * in the document head (see `themeScript`).\n */\nexport function ThemeProvider({\n  theme: themeProp = DEFAULT_THEME,\n  mode: modeProp,\n  defaultMode = 'system',\n  onThemeChange,\n  onModeChange,\n  persistMode = true,\n  storageKey = DEFAULT_STORAGE_KEY,\n  target = 'document',\n  children,\n}: ThemeProviderProps) {\n  const [themeState, setThemeState] = useState<ThemeName>(themeProp)\n  const [prevThemeProp, setPrevThemeProp] = useState(themeProp)\n  // Follow the prop when it changes (React's \"adjust state on a prop change\" pattern).\n  if (themeProp !== prevThemeProp) {\n    setPrevThemeProp(themeProp)\n    setThemeState(themeProp)\n  }\n\n  // The latest explicit choice: a `mode` prop, or a `setMode` call. Unset until one happens.\n  const [chosenMode, setChosenMode] = useState<ColorMode | undefined>(modeProp)\n  const [prevModeProp, setPrevModeProp] = useState(modeProp)\n  if (modeProp !== prevModeProp) {\n    setPrevModeProp(modeProp)\n    if (modeProp) setChosenMode(modeProp)\n  }\n  // A stored choice wins over `defaultMode`, uncontrolled only.\n  const storedMode = useStoredMode(persistMode && !modeProp, storageKey)\n  const modeState = chosenMode ?? storedMode ?? defaultMode\n\n  useEffect(() => {\n    if (target !== 'document' || typeof document === 'undefined') return\n    const el = document.documentElement\n    el.dataset.theme = themeState\n    el.dataset.mode = modeState\n  }, [target, themeState, modeState])\n\n  const systemDark = useSystemDark()\n  const resolvedMode = modeState === 'system' ? (systemDark ? 'dark' : 'light') : modeState\n\n  const setTheme = useCallback(\n    (t: ThemeName) => {\n      setThemeState(t)\n      onThemeChange?.(t)\n    },\n    [onThemeChange],\n  )\n\n  const setMode = useCallback(\n    (m: ColorMode) => {\n      setChosenMode(m)\n      if (persistMode && typeof localStorage !== 'undefined') {\n        try {\n          localStorage.setItem(storageKey, m)\n        } catch {\n          /* storage unavailable — ignore */\n        }\n      }\n      onModeChange?.(m)\n    },\n    [onModeChange, persistMode, storageKey],\n  )\n\n  const value = useMemo<ThemeContextValue>(\n    () => ({ theme: themeState, mode: modeState, resolvedMode, setTheme, setMode }),\n    [themeState, modeState, resolvedMode, setTheme, setMode],\n  )\n\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>\n}\n\nexport interface ThemeScopeProps extends HTMLAttributes<HTMLDivElement> {\n  theme: ThemeName\n  /** Omit to inherit the surrounding colour mode (the usual case). */\n  mode?: ColorMode\n  /**\n   * Paint the theme's canvas (background, text colour, base type) on the scope.\n   * Default `true`. Set `false` to drop a themed component into a rounded frame or\n   * a surface without a square background.\n   */\n  paint?: boolean\n}\n\n/**\n * Renders a subtree in a different theme (and optionally mode). Themes are plain CSS\n * scoped to `[data-theme]`, so scopes nest freely — e.g. a Fiesta card previewed on a\n * Monograph page. Also paints the theme's page background and text colour.\n */\nexport const ThemeScope = forwardRef<HTMLDivElement, ThemeScopeProps>(function ThemeScope(\n  { theme, mode, paint = true, ...rest },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      data-theme={theme}\n      data-mode={mode}\n      data-kiln-scope={paint ? '' : undefined}\n      data-kiln-scope-bare={paint ? undefined : ''}\n      {...rest}\n    />\n  )\n})\n"],"mappings":";;;;;;AAiBA,IAAMA,IAAa;AAEnB,SAASC,EAAe,GAA2C;CACjE,IAAI;EACF,IAAMC,IAAI,OAAO,eAAiB,MAAc,OAAO,aAAa,QAAQC,CAAU;EACtF,OAAOD,MAAM,WAAWA,MAAM,UAAUA,MAAM,WAAWA,IAAI,KAAA;CAC/D,QAAQ;EACN;CACF;AACF;AAEA,SAASE,EAAmB,GAAkC;CAE5D,OADA,OAAO,iBAAiB,WAAWC,CAAQ,SAC9B;EACX,OAAO,oBAAoB,WAAWA,CAAQ;CAChD;AACF;AAMA,SAASC,EAAc,GAAkB,GAA2C;CAClF,OAAOC,EACLH,SACOI,IAAUP,EAAeE,CAAU,IAAI,KAAA,SACxC,KAAA,CACR;AACF;AAEA,SAASM,EAAsB,GAAkC;CAC/D,IAAI,OAAO,aAAe,KAAa,aAAa,KAAA;CACpD,IAAMC,IAAK,WAAWV,CAAU;CAEhC,OADAU,EAAG,iBAAiB,UAAUL,CAAQ,SACzB;EACX,EAAG,oBAAoB,UAAUA,CAAQ;CAC3C;AACF;AAEA,SAASM,IAAyB;CAChC,OAAOJ,EACLE,SACM,OAAO,aAAe,OAAe,WAAWT,CAAU,CAAC,CAAC,eAC5D,EACR;AACF;AAyCA,SAAgBY,EAAc,EAC5B,OAAOC,IAAYC,GACnB,MAAMC,GACN,iBAAc,UACd,kBACA,iBACA,iBAAc,IACd,gBAAaC,GACb,YAAS,YACT,eACqB;CACrB,IAAM,CAACC,GAAYC,KAAiBC,EAAoBN,CAAS,GAC3D,CAACO,GAAeC,KAAoBF,EAASN,CAAS;CAE5D,AAAIA,MAAcO,MAChBC,EAAiBR,CAAS,GAC1BK,EAAcL,CAAS;CAIzB,IAAM,CAACS,GAAYC,KAAiBJ,EAAgCJ,CAAQ,GACtE,CAACS,GAAcC,KAAmBN,EAASJ,CAAQ;CACzD,AAAIA,MAAaS,MACfC,EAAgBV,CAAQ,GACpBA,KAAUQ,EAAcR,CAAQ;CAGtC,IAAMW,IAAapB,EAAcqB,KAAe,CAACZ,GAAUZ,CAAU,GAC/DyB,IAAYN,KAAcI,KAAcG;CAE9C,QAAgB;EACd,IAAIC,MAAW,cAAc,OAAO,WAAa,KAAa;EAC9D,IAAMC,IAAK,SAAS;EAEpB,AADA,EAAG,QAAQ,QAAQd,GACnB,EAAG,QAAQ,OAAOW;CACpB,GAAG;EAACE;EAAQb;EAAYW;CAAS,CAAC;CAElC,IAAMI,IAAarB,EAAc,GAC3BsB,IAAeL,MAAc,WAAYI,IAAa,SAAS,UAAWJ,GAE1EM,IAAWC,GACd,MAAiB;EAEhB,AADAjB,EAAckB,CAAC,GACfC,IAAgBD,CAAC;CACnB,GACA,CAACC,CAAa,CAChB,GAEMC,IAAUH,GACb,MAAiB;EAEhB,IADAZ,EAAcgB,CAAC,GACXZ,KAAe,OAAO,eAAiB,KACzC,IAAI;GACF,aAAa,QAAQxB,GAAYoC,CAAC;EACpC,QAAQ,CAER;EAEF,IAAeA,CAAC;CAClB,GACA;EAACC;EAAcb;EAAaxB;CAAU,CACxC,GAEMsC,IAAQC,SACL;EAAE,OAAOzB;EAAY,MAAMW;EAAW;EAAc;EAAU;CAAQ,IAC7E;EAACX;EAAYW;EAAWK;EAAcC;EAAUI;CAAO,CACzD;CAEA,OAAO,kBAACK,EAAa,UAAd;EAA8B;EAAQ;CAAgC,CAAA;AAC/E;AAmBA,IAAaC,IAAaC,EAA4C,SACpE,EAAE,UAAO,SAAM,WAAQ,IAAM,GAAGC,KAChC,GACA;CACA,OACE,kBAAC,OAAD;EACO;EACL,cAAYC;EACZ,aAAWC;EACX,mBAAiBC,IAAQ,KAAK,KAAA;EAC9B,wBAAsBA,IAAQ,KAAA,IAAY;EAC1C,GAAIH;CACL,CAAA;AAEL,CAAC"}

package/dist/theme/context.d.ts

@@ -8,13 +8,5 @@ export interface ThemeContextValue {
     setMode: (mode: ColorMode) => void;
 }
 export declare const ThemeContext: import("react").Context<ThemeContextValue | null>;
-export declare const STORAGE_KEY = "kiln-color-mode";
 /** Read and change the current theme/mode. Must be inside `<ThemeProvider>`. */
 export declare function useTheme(): ThemeContextValue;
-/**
- * Inline script for the document `<head>` that applies the theme and the stored colour
- * mode (or `defaultMode` when nothing is stored) before first paint. Use the same `theme`
- * and `defaultMode` as `<ThemeProvider>`. Only needed with SSR + a user-selectable mode.
- * Any theme name works, built-in or your own.
- */
-export declare function themeScript(theme?: ThemeName, defaultMode?: ColorMode): string;

package/dist/theme/context.js

@@ -1,19 +1,12 @@
-import { DEFAULT_THEME as e } from "./themes.js";
-import { createContext as t, useContext as n } from "react";
+import { createContext as e, useContext as t } from "react";
 //#region src/theme/context.ts
-var r = t(null), i = "kiln-color-mode";
-function a() {
-	let e = n(r);
+var n = e(null);
+function r() {
+	let e = t(n);
 	if (!e) throw Error("useTheme() must be used inside <ThemeProvider>.");
 	return e;
 }
-function o(e) {
-	return JSON.stringify(e).replace(/</g, "\\u003c");
-}
-function s(t = e, n = "system") {
-	return `(function(){try{var d=document.documentElement;d.dataset.theme=${o(t)};var m=localStorage.getItem(${o(i)});d.dataset.mode=(m==='light'||m==='dark'||m==='system')?m:${o(n)};}catch(e){}})();`;
-}
 //#endregion
-export { i as STORAGE_KEY, r as ThemeContext, s as themeScript, a as useTheme };
+export { n as ThemeContext, r as useTheme };
 
 //# sourceMappingURL=context.js.map

package/dist/theme/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":["ThemeContext","createContext","STORAGE_KEY","useTheme","ctx","useContext","scriptLiteral","value","themeScript","DEFAULT_THEME","theme","defaultMode"],"sources":["../../src/theme/context.ts"],"sourcesContent":["import { createContext, useContext } from 'react'\nimport { DEFAULT_THEME } from './themes'\nimport type { ColorMode, ThemeName } from './themes'\n\nexport interface ThemeContextValue {\n  theme: ThemeName\n  mode: ColorMode\n  /** The mode actually rendered once `system` is resolved (`light` during SSR). */\n  resolvedMode: 'light' | 'dark'\n  setTheme: (theme: ThemeName) => void\n  setMode: (mode: ColorMode) => void\n}\n\nexport const ThemeContext = createContext<ThemeContextValue | null>(null)\n\nexport const STORAGE_KEY = 'kiln-color-mode'\n\n/** Read and change the current theme/mode. Must be inside `<ThemeProvider>`. */\nexport function useTheme(): ThemeContextValue {\n  const ctx = useContext(ThemeContext)\n  if (!ctx) throw new Error('useTheme() must be used inside <ThemeProvider>.')\n  return ctx\n}\n\n/** JSON for an inline `<script>`: `<` is escaped so a name can never close the tag. */\nfunction scriptLiteral(value: string): string {\n  return JSON.stringify(value).replace(/</g, '\\\\u003c')\n}\n\n/**\n * Inline script for the document `<head>` that applies the theme and the stored colour\n * mode (or `defaultMode` when nothing is stored) before first paint. Use the same `theme`\n * and `defaultMode` as `<ThemeProvider>`. Only needed with SSR + a user-selectable mode.\n * Any theme name works, built-in or your own.\n */\nexport function themeScript(\n  theme: ThemeName = DEFAULT_THEME,\n  defaultMode: ColorMode = 'system',\n): string {\n  return `(function(){try{var d=document.documentElement;d.dataset.theme=${scriptLiteral(\n    theme,\n  )};var m=localStorage.getItem(${scriptLiteral(STORAGE_KEY)});d.dataset.mode=(m==='light'||m==='dark'||m==='system')?m:${scriptLiteral(\n    defaultMode,\n  )};}catch(e){}})();`\n}\n"],"mappings":";;;AAaA,IAAaA,IAAeC,EAAwC,IAAI,GAE3DC,IAAc;AAG3B,SAAgBC,IAA8B;CAC5C,IAAMC,IAAMC,EAAWL,CAAY;CACnC,IAAI,CAACI,GAAK,MAAU,MAAM,iDAAiD;CAC3E,OAAOA;AACT;AAGA,SAASE,EAAc,GAAuB;CAC5C,OAAO,KAAK,UAAUC,CAAK,CAAC,CAAC,QAAQ,MAAM,SAAS;AACtD;AAQA,SAAgBC,EACd,IAAmBC,GACnB,IAAyB,UACjB;CACR,OAAO,kEAAkEH,EACvEI,CACF,EAAE,8BAA8BJ,EAAcJ,CAAW,EAAE,6DAA6DI,EACtHK,CACF,EAAE;AACJ"}
+{"version":3,"file":"context.js","names":["ThemeContext","createContext","useTheme","ctx","useContext"],"sources":["../../src/theme/context.ts"],"sourcesContent":["import { createContext, useContext } from 'react'\nimport type { ColorMode, ThemeName } from './themes'\n\nexport interface ThemeContextValue {\n  theme: ThemeName\n  mode: ColorMode\n  /** The mode actually rendered once `system` is resolved (`light` during SSR). */\n  resolvedMode: 'light' | 'dark'\n  setTheme: (theme: ThemeName) => void\n  setMode: (mode: ColorMode) => void\n}\n\nexport const ThemeContext = createContext<ThemeContextValue | null>(null)\n\n/** Read and change the current theme/mode. Must be inside `<ThemeProvider>`. */\nexport function useTheme(): ThemeContextValue {\n  const ctx = useContext(ThemeContext)\n  if (!ctx) throw new Error('useTheme() must be used inside <ThemeProvider>.')\n  return ctx\n}\n"],"mappings":";;AAYA,IAAaA,IAAeC,EAAwC,IAAI;AAGxE,SAAgBC,IAA8B;CAC5C,IAAMC,IAAMC,EAAWJ,CAAY;CACnC,IAAI,CAACG,GAAK,MAAU,MAAM,iDAAiD;CAC3E,OAAOA;AACT"}

package/dist/theme/index.d.ts

@@ -1,6 +1,8 @@
 export { ThemeProvider, ThemeScope } from './ThemeProvider.js';
 export type { ThemeProviderProps, ThemeScopeProps } from './ThemeProvider.js';
-export { useTheme, themeScript } from './context.js';
+export { useTheme } from './context.js';
 export type { ThemeContextValue } from './context.js';
+export { themeScript } from './script.js';
+export type { ThemeScriptOptions } from './script.js';
 export { THEMES, THEME_META, MODES, DEFAULT_THEME } from './themes.js';
 export type { ThemeName, BuiltInThemeName, ThemeMeta, ColorMode } from './themes.js';

package/dist/theme/script.d.ts

@@ -0,0 +1,14 @@
+import type { ColorMode, ThemeName } from './themes.js';
+/** The localStorage key for the reader's colour mode, unless `storageKey` names another. */
+export declare const DEFAULT_STORAGE_KEY = "kiln-color-mode";
+export interface ThemeScriptOptions {
+    /** The localStorage key the mode is read from. Use the same key as `<ThemeProvider>`. */
+    storageKey?: string;
+}
+/**
+ * Inline script for the document `<head>` that applies the theme and the stored colour
+ * mode (or `defaultMode` when nothing is stored) before first paint. Use the same `theme`,
+ * `defaultMode` and `storageKey` as `<ThemeProvider>`. Only needed with SSR (or a static
+ * `index.html`) + a user-selectable mode. Any theme name works, built-in or your own.
+ */
+export declare function themeScript(theme?: ThemeName, defaultMode?: ColorMode, { storageKey }?: ThemeScriptOptions): string;

package/dist/theme/script.js

@@ -0,0 +1,13 @@
+import { DEFAULT_THEME as e } from "./themes.js";
+//#region src/theme/script.ts
+var t = "kiln-color-mode";
+function n(e) {
+	return JSON.stringify(e).replace(/</g, "\\u003c");
+}
+function r(r = e, i = "system", { storageKey: a = t } = {}) {
+	return `(function(){try{var d=document.documentElement;d.dataset.theme=${n(r)};var m=localStorage.getItem(${n(a)});d.dataset.mode=(m==='light'||m==='dark'||m==='system')?m:${n(i)};}catch(e){}})();`;
+}
+//#endregion
+export { t as DEFAULT_STORAGE_KEY, r as themeScript };
+
+//# sourceMappingURL=script.js.map

package/dist/theme/script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.js","names":["DEFAULT_STORAGE_KEY","scriptLiteral","value","themeScript","DEFAULT_THEME","theme","storageKey","defaultMode"],"sources":["../../src/theme/script.ts"],"sourcesContent":["/**\n * `themeScript`, on its own so it can load without React: the root entry re-exports it, and\n * `@mitcsutt/kiln-ui/theme-script` serves it to Node-side tooling, such as a Vite config that\n * writes it into a static `index.html` (ADR 0023).\n */\nimport { DEFAULT_THEME } from './themes'\nimport type { ColorMode, ThemeName } from './themes'\n\n/** The localStorage key for the reader's colour mode, unless `storageKey` names another. */\nexport const DEFAULT_STORAGE_KEY = 'kiln-color-mode'\n\n/** JSON for an inline `<script>`: `<` is escaped so a name can never close the tag. */\nfunction scriptLiteral(value: string): string {\n  return JSON.stringify(value).replace(/</g, '\\\\u003c')\n}\n\nexport interface ThemeScriptOptions {\n  /** The localStorage key the mode is read from. Use the same key as `<ThemeProvider>`. */\n  storageKey?: string\n}\n\n/**\n * Inline script for the document `<head>` that applies the theme and the stored colour\n * mode (or `defaultMode` when nothing is stored) before first paint. Use the same `theme`,\n * `defaultMode` and `storageKey` as `<ThemeProvider>`. Only needed with SSR (or a static\n * `index.html`) + a user-selectable mode. Any theme name works, built-in or your own.\n */\nexport function themeScript(\n  theme: ThemeName = DEFAULT_THEME,\n  defaultMode: ColorMode = 'system',\n  { storageKey = DEFAULT_STORAGE_KEY }: ThemeScriptOptions = {},\n): string {\n  return `(function(){try{var d=document.documentElement;d.dataset.theme=${scriptLiteral(\n    theme,\n  )};var m=localStorage.getItem(${scriptLiteral(storageKey)});d.dataset.mode=(m==='light'||m==='dark'||m==='system')?m:${scriptLiteral(\n    defaultMode,\n  )};}catch(e){}})();`\n}\n"],"mappings":";;AASA,IAAaA,IAAsB;AAGnC,SAASC,EAAc,GAAuB;CAC5C,OAAO,KAAK,UAAUC,CAAK,CAAC,CAAC,QAAQ,MAAM,SAAS;AACtD;AAaA,SAAgBC,EACd,IAAmBC,GACnB,IAAyB,UACzB,EAAE,gBAAaJ,MAA4C,CAAC,GACpD;CACR,OAAO,kEAAkEC,EACvEI,CACF,EAAE,8BAA8BJ,EAAcK,CAAU,EAAE,6DAA6DL,EACrHM,CACF,EAAE;AACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitcsutt/kiln-ui",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Kiln: a themeable React design system on Radix primitives, plain CSS and design tokens",
   "keywords": [
     "kiln",
@@ -32,6 +32,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./theme-script": {
+      "types": "./dist/theme/script.d.ts",
+      "default": "./dist/theme/script.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./themes/monograph.css": "./dist/themes/monograph.css",
     "./themes/ledger.css": "./dist/themes/ledger.css",
@@ -80,7 +84,8 @@
   },
   "scripts": {
     "build": "vite build",
-    "check:package": "pnpm pack --out node_modules/.cache/kiln-pack/package.tgz > /dev/null && publint --pack pnpm --strict && attw node_modules/.cache/kiln-pack/package.tgz --profile esm-only --exclude-entrypoints ./styles.css ./themes/monograph.css ./themes/ledger.css ./themes/fiesta.css",
+    "build:watch": "vite build --watch",
+    "check:package": "pnpm pack --out node_modules/.cache/kiln-pack/package.tgz > /dev/null && publint --pack pnpm --strict && attw node_modules/.cache/kiln-pack/package.tgz --profile esm-only --exclude-entrypoints ./styles.css ./themes/monograph.css ./themes/ledger.css ./themes/fiesta.css && node scripts/check-theme-script-entry.ts node_modules/.cache/kiln-pack/package.tgz",
     "check:skills": "intent validate",
     "lint": "eslint --max-warnings=0 .",
     "size": "node ../../size-report.ts",

package/skills/custom-theme/SKILL.md

@@ -24,7 +24,7 @@ A Kiln theme is one CSS file. It sets the tokens in the [contract](references/to
 ```tsx
 import { Box, Button, Heading, Inline, Stack, Text, ThemeScope } from '@mitcsutt/kiln-ui'
 
-export default function CustomTheme() {
+export function Usage() {
   return (
     <ThemeScope theme="harbour">
       <Box padding={6}>

package/skills/layout-composition/SKILL.md

@@ -50,7 +50,7 @@ Vary the rhythm. Adjacent sections shouldn't share a `space` step, and a page us
 ```tsx
 import { Button, Inline, Stack, Text, TextField } from '@mitcsutt/kiln-ui'
 
-export default function Density() {
+export function Density() {
   return (
     <Inline gap={7} align="start">
       {(['compact', undefined, 'comfortable'] as const).map((density) => (
@@ -96,7 +96,7 @@ import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
 const STOPS = ['Harbour', 'Northpoint', 'Kelso Bay', 'Ferry Lane', 'Old Quay', 'Marram Point']
 
-export default function ResponsiveProps() {
+export function ResponsiveProps() {
   return (
     <Grid columns={{ base: 1, sm: 2, lg: 3 }} gap={{ base: 3, md: 5 }}>
       {STOPS.map((stop) => (
@@ -124,7 +124,7 @@ A column of things with consistent space between them. The layout you'll reach f
 ```tsx
 import { Button, Heading, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4} align="start">
       <Heading level={3} size="xl">
@@ -152,7 +152,7 @@ const STOPS = [
   { name: 'Kelso Bay Pier', time: '23:31' },
 ]
 
-export default function Dividers() {
+export function Dividers() {
   return (
     <Stack gap={{ base: 3, md: 4 }} dividers>
       {STOPS.map((stop) => (
@@ -196,7 +196,7 @@ Things in a row that wrap when they run out of room. Button rows, tag lists, too
 ```tsx
 import { Badge, Button, Inline, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Inline gap={3} justify={{ base: 'start', md: 'between' }}>
       <Inline gap={2}>
@@ -244,7 +244,7 @@ import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
 const LINES = ['Red', 'Harbour', 'Coastal', 'Night', 'Airport', 'Orbital', 'Market', 'University']
 
-export default function Columns() {
+export function Columns() {
   return (
     <Grid columns={{ base: 1, sm: 2, lg: 4 }} gap={4}>
       {LINES.map((line) => (
@@ -266,7 +266,7 @@ import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
 const PIERS = ['North pier', 'South pier', 'Ferry terminal', 'Lifeboat station', 'Fish market']
 
-export default function AutoFill() {
+export function AutoFill() {
   return (
     <Grid minItemWidth="xs" gap={4}>
       {PIERS.map((pier) => (
@@ -286,7 +286,7 @@ export default function AutoFill() {
 ```tsx
 import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
-export default function Items() {
+export function Items() {
   return (
     <Grid columns={{ base: 1, md: 3 }} gap={4}>
       <Grid.Item span={{ base: 1, md: 2 }}>
@@ -357,7 +357,7 @@ const CHANGES = [
   'Kelso Bay Pier reopens on 3 November.',
 ]
 
-export default function Usage() {
+export function Usage() {
   return (
     <Split ratio="5/7" gap={{ base: 5, md: 7 }}>
       <Heading level={3} size="2xl">
@@ -380,7 +380,7 @@ export default function Usage() {
 ```tsx
 import { Box, Split, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Ratios() {
+export function Ratios() {
   return (
     <Stack gap={4}>
       {(['1/1', '1/2', '1/3', '5/7'] as const).map((ratio) => (
@@ -425,7 +425,7 @@ A full-bleed band of vertical space, with an optional surface and rules. Put a C
 ```tsx
 import { Button, Container, Heading, Section, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <>
       <Section space={7}>

package/skills/layout-composition/references/action-bar.md

@@ -11,7 +11,7 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/action-bar
 ```tsx
 import { ActionBar, Button, Stack, TextField } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={5}>
       <TextField label="Route name" defaultValue="Morning commute" />

package/skills/layout-composition/references/app-shell.md

@@ -32,7 +32,7 @@ const ICONS = [
   <SystemIcon key="a" />,
 ]
 
-export default function Usage() {
+export function Usage() {
   return (
     <AppShell navBreakpoint="md">
       <AppShell.Header>

package/skills/layout-composition/references/aspect-ratio.md

@@ -25,7 +25,7 @@ function Chart({ label }: { label: string }) {
   )
 }
 
-export default function Usage() {
+export function Usage() {
   return (
     <Grid columns={{ base: 1, sm: 3 }} gap={4}>
       {(['16/9', '4/3', '1/1'] as const).map((ratio) => (

package/skills/layout-composition/references/box.md

@@ -11,7 +11,7 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/box
 ```tsx
 import { Box, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4}>
       <Box padding={{ base: 4, md: 5 }} surface="sunken" radius="surface">

package/skills/layout-composition/references/checkout.md

@@ -33,7 +33,7 @@ const BASKET = [
 
 const subtotal = BASKET.reduce((sum, item) => sum + item.price, 0)
 
-export default function Checkout() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="content">

package/skills/layout-composition/references/container.md

@@ -11,7 +11,7 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/container
 ```tsx
 import { Container, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4}>
       {(['narrow', 'text', 'content'] as const).map((width) => (

package/skills/layout-composition/references/dashboard.md

@@ -41,7 +41,7 @@ const STATUS = {
   empty: { tone: 'critical', label: 'Empty' },
 } as const
 
-export default function Dashboard() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="wide">

package/skills/layout-composition/references/divider.md

@@ -11,7 +11,7 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/divider
 ```tsx
 import { Divider, Inline, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4}>
       <Text>Morning departures</Text>

package/skills/layout-composition/references/settings.md

@@ -28,7 +28,7 @@ import {
   TextField,
 } from '@mitcsutt/kiln-ui'
 
-export default function Settings() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="content">

package/skills/layout-composition/references/visually-hidden.md

@@ -11,7 +11,7 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/visually-hidden
 ```tsx
 import { Inline, Text, VisuallyHidden } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Inline gap={2}>
       <Text numeric weight="strong">

package/skills/setup-and-theming/SKILL.md

@@ -70,7 +70,7 @@ Screens are built from layout primitives and typed props, never utility classes
 ```tsx
 import { Button, Container, Heading, Inline, Section, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function FirstScreen() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="text">
@@ -121,6 +121,44 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 `suppressHydrationWarning` on `<html>` is needed because the script changes its attributes before React hydrates.
 
+### Name the storage key
+
+The reader's mode is stored in `localStorage` under `kiln-color-mode`. Every app on one origin shares that key, so a choice made in one carries into the next. Give each app its own key with `storageKey`, or keep a key the app already used so returning readers keep their choice. Pass the same key to `themeScript`:
+
+```tsx
+;<ThemeProvider theme="ledger" defaultMode="light" storageKey="budget:color-mode">
+  …
+</ThemeProvider>
+
+themeScript('ledger', 'light', { storageKey: 'budget:color-mode' })
+```
+
+### Without server rendering
+
+A single-page app served from a static `index.html` still paints before React loads, so it needs the script too. Generate it at build time instead of copying it by hand. The config runs in Node, so import `themeScript` from `@mitcsutt/kiln-ui/theme-script`: that entry has no React and nothing else to load. With Vite, a small plugin in the config puts it at the top of `<head>`:
+
+```ts title="vite.config.ts"
+import { themeScript } from '@mitcsutt/kiln-ui/theme-script'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    {
+      name: 'kiln-theme-script',
+      transformIndexHtml: () => [
+        {
+          tag: 'script',
+          children: themeScript('ledger', 'light', { storageKey: 'budget:color-mode' }),
+          injectTo: 'head-prepend',
+        },
+      ],
+    },
+  ],
+})
+```
+
 ### With the Next.js App Router
 
 Kiln's components use React state and context, so they render in client components. Put `ThemeProvider` in a file marked `'use client'`, and import Kiln components from client components: