@plitzi/sdk-shared 0.33.2 → 0.34.0

package/dist/style/fontsFromCss.d.ts

@@ -0,0 +1,27 @@
+import { FontStyle, SpaceFont } from '../types/StyleTypes';
+/**
+ * What a deployment knows about a family it did not declare — the Google catalog, usually.
+ *
+ * Optional everywhere it is taken: without it every unknown family is declared as a system stack, which renders
+ * exactly as it would have anyway and shows up in the Fonts panel for somebody to convert on purpose.
+ */
+export type FontCatalogLookup = (family: string) => {
+    weights: number[];
+    styles: FontStyle[];
+    category?: string;
+} | undefined;
+/** A guess from the name, for a family nothing can identify: a licensed face, a foundry kit, a typo. */
+export declare const fallbackForFamily: (family: string, category?: string) => string;
+/**
+ * The manifest a stylesheet implies.
+ *
+ * Used wherever CSS arrives from outside and has to become a space: an import from HTML, Tailwind or Webflow, and
+ * the one-shot migration that gave the first manifests to spaces written before there were any. Both face the same
+ * problem — a `font-family` names a family and says nothing about where it comes from — and the answer is the same
+ * guess, so it lives once.
+ *
+ * A family the catalog knows is declared as a Google font at the weights the CSS actually uses. Anything else is
+ * declared as a system stack: it renders exactly as it does now, and it is visible in the panel rather than being
+ * a name in a stylesheet that nobody can see is unloadable.
+ */
+export declare const fontsFromCss: (css: string, lookup?: FontCatalogLookup) => SpaceFont[];

package/dist/style/fontsFromCss.mjs

@@ -0,0 +1,43 @@
+import { SYSTEM_FONTS as e, familiesInCss as t } from "./fonts.mjs";
+//#region src/style/fontsFromCss.ts
+var n = {
+	serif: "Georgia, serif",
+	"sans-serif": "system-ui, sans-serif",
+	display: "system-ui, sans-serif",
+	handwriting: "cursive",
+	monospace: "ui-monospace, monospace"
+}, r = (e) => {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of e.matchAll(/font-weight\s*:\s*(\d{3})/g)) t.add(Number(n[1]));
+	return [...t].sort((e, t) => e - t);
+}, i = (e, t) => {
+	if (t && n[t]) return n[t];
+	let r = e.toLowerCase();
+	return r.includes("mono") || r.includes("code") || r.includes("courier") ? "ui-monospace, monospace" : r.includes("serif") && !r.includes("sans") ? "Georgia, serif" : "system-ui, sans-serif";
+}, a = (n, a) => {
+	let o = new Set(e.map((e) => e.family.toLowerCase())), s = r(n);
+	return t(n).filter((e) => !o.has(e.toLowerCase())).map((e) => {
+		let t = a?.(e);
+		if (!t) return {
+			source: "system",
+			family: e,
+			fallback: i(e),
+			weights: [400, 700],
+			styles: ["normal", "italic"]
+		};
+		let n = t.weights.filter((e) => s.includes(e));
+		return {
+			source: "google",
+			family: e,
+			fallback: i(e, t.category),
+			weights: n.length > 0 ? n : t.weights.filter((e) => e === 400 || e === 700),
+			styles: t.styles,
+			display: "swap"
+		};
+	}).map((e) => e.weights.length > 0 ? e : {
+		...e,
+		weights: [400]
+	});
+};
+//#endregion
+export { i as fallbackForFamily, a as fontsFromCss };

package/dist/style/index.d.ts

@@ -1,3 +1,7 @@
 import { default as styleConstants } from './styleConstants';
+export * from './fontAssets';
+export * from './fontValidation';
+export * from './fonts';
+export * from './fontsFromCss';
 export * from './styleConstants';
 export { styleConstants };

package/dist/style/index.mjs

@@ -1,2 +1,6 @@
 import e, { EMPTY_STYLE_SCHEMA as t, StyleBindingsAllowed as n, baseDefaultValue as r, inheritableAttributesBase as i } from "./styleConstants.mjs";
-export { t as EMPTY_STYLE_SCHEMA, n as StyleBindingsAllowed, r as baseDefaultValue, i as inheritableAttributesBase, e as styleConstants };
+import { fontLinkAssets as a } from "./fontAssets.mjs";
+import { SYSTEM_FONTS as o, availableFonts as s, familiesInCss as c, fontFamilyStack as l, fontUrlResolver as u, fontsToHead as d, googleCss2Url as f, googleTextSubsetUrl as p, isSafeFontUrl as m, primaryFamily as h } from "./fonts.mjs";
+import { FontValidationError as g, parseSpaceFont as _ } from "./fontValidation.mjs";
+import { fallbackForFamily as v, fontsFromCss as y } from "./fontsFromCss.mjs";
+export { t as EMPTY_STYLE_SCHEMA, g as FontValidationError, o as SYSTEM_FONTS, n as StyleBindingsAllowed, s as availableFonts, r as baseDefaultValue, v as fallbackForFamily, c as familiesInCss, l as fontFamilyStack, a as fontLinkAssets, u as fontUrlResolver, y as fontsFromCss, d as fontsToHead, f as googleCss2Url, p as googleTextSubsetUrl, i as inheritableAttributesBase, m as isSafeFontUrl, _ as parseSpaceFont, h as primaryFamily, e as styleConstants };

package/dist/style/styleConstants.d.ts

@@ -169,8 +169,8 @@ declare const styleConstants: {
 };
 export declare const inheritableAttributesBase: StyleCategory[];
 export declare const StyleBindingsAllowed: {
-    path: "display" | "flex-wrap" | "flex-direction" | "align-items" | "justify-items" | "justify-content" | "align-content" | "row-gap" | "column-gap" | "grid-row-gap" | "grid-column-gap" | "grid-template-areas" | "grid-template-columns" | "grid-template-rows" | "grid-auto-flow" | "grid-auto-rows" | "grid-auto-columns" | "grid-row-start" | "grid-column-start" | "grid-row-end" | "grid-column-end" | "align-self" | "justify-self" | "order" | "flex-grow" | "flex-shrink" | "flex-basis" | "list-style" | "list-style-type" | "list-style-position" | "list-style-image" | "background-color" | "background-image" | "background-position" | "background-size" | "background-repeat" | "background-origin" | "background-clip" | "background-attachment" | "background-blend-mode" | "mask-image" | "border-top-style" | "border-top-width" | "border-top-color" | "border-bottom-style" | "border-bottom-width" | "border-bottom-color" | "border-left-style" | "border-left-width" | "border-left-color" | "border-right-style" | "border-right-width" | "border-right-color" | "border-top-left-radius" | "border-top-right-radius" | "border-bottom-left-radius" | "border-bottom-right-radius" | "border-collapse" | "border-spacing" | "table-layout" | "opacity" | "visibility" | "cursor" | "transition" | "transition-property" | "transition-duration" | "transition-timing-function" | "transition-delay" | "animation" | "animation-name" | "animation-duration" | "animation-timing-function" | "animation-delay" | "animation-iteration-count" | "animation-direction" | "animation-fill-mode" | "animation-play-state" | "box-shadow" | "filter" | "backdrop-filter" | "mix-blend-mode" | "isolation" | "clip-path" | "transform" | "transform-origin" | "perspective" | "will-change" | "outline-width" | "outline-style" | "outline-color" | "outline-offset" | "pointer-events" | "user-select" | "touch-action" | "resize" | "appearance" | "scroll-behavior" | "overscroll-behavior" | "accent-color" | "caret-color" | "color-scheme" | "position" | "float" | "clear" | "z-index" | "top" | "bottom" | "left" | "right" | "box-sizing" | "aspect-ratio" | "width" | "height" | "min-width" | "min-height" | "max-width" | "max-height" | "overflow" | "overflow-x" | "overflow-y" | "object-fit" | "object-position" | "column-width" | "column-count" | "margin-top" | "margin-bottom" | "margin-left" | "margin-right" | "padding-top" | "padding-bottom" | "padding-left" | "padding-right" | "font-family" | "font-weight" | "font-size" | "line-height" | "color" | "text-align" | "font-style" | "font-variant" | "text-decoration" | "text-decoration-line" | "text-decoration-color" | "text-decoration-style" | "text-decoration-thickness" | "text-underline-offset" | "letter-spacing" | "word-spacing" | "text-indent" | "text-transform" | "direction" | "white-space" | "text-wrap" | "word-break" | "overflow-wrap" | "hyphens" | "vertical-align" | "text-overflow" | "text-shadow" | "line-clamp" | "-webkit-line-clamp" | "-webkit-box-orient" | "fill" | "stroke" | "stroke-width";
-    label: "display" | "flex-wrap" | "flex-direction" | "align-items" | "justify-items" | "justify-content" | "align-content" | "row-gap" | "column-gap" | "grid-row-gap" | "grid-column-gap" | "grid-template-areas" | "grid-template-columns" | "grid-template-rows" | "grid-auto-flow" | "grid-auto-rows" | "grid-auto-columns" | "grid-row-start" | "grid-column-start" | "grid-row-end" | "grid-column-end" | "align-self" | "justify-self" | "order" | "flex-grow" | "flex-shrink" | "flex-basis" | "list-style" | "list-style-type" | "list-style-position" | "list-style-image" | "background-color" | "background-image" | "background-position" | "background-size" | "background-repeat" | "background-origin" | "background-clip" | "background-attachment" | "background-blend-mode" | "mask-image" | "border-top-style" | "border-top-width" | "border-top-color" | "border-bottom-style" | "border-bottom-width" | "border-bottom-color" | "border-left-style" | "border-left-width" | "border-left-color" | "border-right-style" | "border-right-width" | "border-right-color" | "border-top-left-radius" | "border-top-right-radius" | "border-bottom-left-radius" | "border-bottom-right-radius" | "border-collapse" | "border-spacing" | "table-layout" | "opacity" | "visibility" | "cursor" | "transition" | "transition-property" | "transition-duration" | "transition-timing-function" | "transition-delay" | "animation" | "animation-name" | "animation-duration" | "animation-timing-function" | "animation-delay" | "animation-iteration-count" | "animation-direction" | "animation-fill-mode" | "animation-play-state" | "box-shadow" | "filter" | "backdrop-filter" | "mix-blend-mode" | "isolation" | "clip-path" | "transform" | "transform-origin" | "perspective" | "will-change" | "outline-width" | "outline-style" | "outline-color" | "outline-offset" | "pointer-events" | "user-select" | "touch-action" | "resize" | "appearance" | "scroll-behavior" | "overscroll-behavior" | "accent-color" | "caret-color" | "color-scheme" | "position" | "float" | "clear" | "z-index" | "top" | "bottom" | "left" | "right" | "box-sizing" | "aspect-ratio" | "width" | "height" | "min-width" | "min-height" | "max-width" | "max-height" | "overflow" | "overflow-x" | "overflow-y" | "object-fit" | "object-position" | "column-width" | "column-count" | "margin-top" | "margin-bottom" | "margin-left" | "margin-right" | "padding-top" | "padding-bottom" | "padding-left" | "padding-right" | "font-family" | "font-weight" | "font-size" | "line-height" | "color" | "text-align" | "font-style" | "font-variant" | "text-decoration" | "text-decoration-line" | "text-decoration-color" | "text-decoration-style" | "text-decoration-thickness" | "text-underline-offset" | "letter-spacing" | "word-spacing" | "text-indent" | "text-transform" | "direction" | "white-space" | "text-wrap" | "word-break" | "overflow-wrap" | "hyphens" | "vertical-align" | "text-overflow" | "text-shadow" | "line-clamp" | "-webkit-line-clamp" | "-webkit-box-orient" | "fill" | "stroke" | "stroke-width";
+    path: "filter" | "fill" | "display" | "flex-wrap" | "flex-direction" | "align-items" | "justify-items" | "justify-content" | "align-content" | "row-gap" | "column-gap" | "grid-row-gap" | "grid-column-gap" | "grid-template-areas" | "grid-template-columns" | "grid-template-rows" | "grid-auto-flow" | "grid-auto-rows" | "grid-auto-columns" | "grid-row-start" | "grid-column-start" | "grid-row-end" | "grid-column-end" | "align-self" | "justify-self" | "order" | "flex-grow" | "flex-shrink" | "flex-basis" | "list-style" | "list-style-type" | "list-style-position" | "list-style-image" | "background-color" | "background-image" | "background-position" | "background-size" | "background-repeat" | "background-origin" | "background-clip" | "background-attachment" | "background-blend-mode" | "mask-image" | "border-top-style" | "border-top-width" | "border-top-color" | "border-bottom-style" | "border-bottom-width" | "border-bottom-color" | "border-left-style" | "border-left-width" | "border-left-color" | "border-right-style" | "border-right-width" | "border-right-color" | "border-top-left-radius" | "border-top-right-radius" | "border-bottom-left-radius" | "border-bottom-right-radius" | "border-collapse" | "border-spacing" | "table-layout" | "opacity" | "visibility" | "cursor" | "transition" | "transition-property" | "transition-duration" | "transition-timing-function" | "transition-delay" | "animation" | "animation-name" | "animation-duration" | "animation-timing-function" | "animation-delay" | "animation-iteration-count" | "animation-direction" | "animation-fill-mode" | "animation-play-state" | "box-shadow" | "backdrop-filter" | "mix-blend-mode" | "isolation" | "clip-path" | "transform" | "transform-origin" | "perspective" | "will-change" | "outline-width" | "outline-style" | "outline-color" | "outline-offset" | "pointer-events" | "user-select" | "touch-action" | "resize" | "appearance" | "scroll-behavior" | "overscroll-behavior" | "accent-color" | "caret-color" | "color-scheme" | "position" | "float" | "clear" | "z-index" | "top" | "bottom" | "left" | "right" | "box-sizing" | "aspect-ratio" | "width" | "height" | "min-width" | "min-height" | "max-width" | "max-height" | "overflow" | "overflow-x" | "overflow-y" | "object-fit" | "object-position" | "column-width" | "column-count" | "margin-top" | "margin-bottom" | "margin-left" | "margin-right" | "padding-top" | "padding-bottom" | "padding-left" | "padding-right" | "font-family" | "font-weight" | "font-size" | "line-height" | "color" | "text-align" | "font-style" | "font-variant" | "text-decoration" | "text-decoration-line" | "text-decoration-color" | "text-decoration-style" | "text-decoration-thickness" | "text-underline-offset" | "letter-spacing" | "word-spacing" | "text-indent" | "text-transform" | "direction" | "white-space" | "text-wrap" | "word-break" | "overflow-wrap" | "hyphens" | "vertical-align" | "text-overflow" | "text-shadow" | "line-clamp" | "-webkit-line-clamp" | "-webkit-box-orient" | "stroke" | "stroke-width";
+    label: "filter" | "fill" | "display" | "flex-wrap" | "flex-direction" | "align-items" | "justify-items" | "justify-content" | "align-content" | "row-gap" | "column-gap" | "grid-row-gap" | "grid-column-gap" | "grid-template-areas" | "grid-template-columns" | "grid-template-rows" | "grid-auto-flow" | "grid-auto-rows" | "grid-auto-columns" | "grid-row-start" | "grid-column-start" | "grid-row-end" | "grid-column-end" | "align-self" | "justify-self" | "order" | "flex-grow" | "flex-shrink" | "flex-basis" | "list-style" | "list-style-type" | "list-style-position" | "list-style-image" | "background-color" | "background-image" | "background-position" | "background-size" | "background-repeat" | "background-origin" | "background-clip" | "background-attachment" | "background-blend-mode" | "mask-image" | "border-top-style" | "border-top-width" | "border-top-color" | "border-bottom-style" | "border-bottom-width" | "border-bottom-color" | "border-left-style" | "border-left-width" | "border-left-color" | "border-right-style" | "border-right-width" | "border-right-color" | "border-top-left-radius" | "border-top-right-radius" | "border-bottom-left-radius" | "border-bottom-right-radius" | "border-collapse" | "border-spacing" | "table-layout" | "opacity" | "visibility" | "cursor" | "transition" | "transition-property" | "transition-duration" | "transition-timing-function" | "transition-delay" | "animation" | "animation-name" | "animation-duration" | "animation-timing-function" | "animation-delay" | "animation-iteration-count" | "animation-direction" | "animation-fill-mode" | "animation-play-state" | "box-shadow" | "backdrop-filter" | "mix-blend-mode" | "isolation" | "clip-path" | "transform" | "transform-origin" | "perspective" | "will-change" | "outline-width" | "outline-style" | "outline-color" | "outline-offset" | "pointer-events" | "user-select" | "touch-action" | "resize" | "appearance" | "scroll-behavior" | "overscroll-behavior" | "accent-color" | "caret-color" | "color-scheme" | "position" | "float" | "clear" | "z-index" | "top" | "bottom" | "left" | "right" | "box-sizing" | "aspect-ratio" | "width" | "height" | "min-width" | "min-height" | "max-width" | "max-height" | "overflow" | "overflow-x" | "overflow-y" | "object-fit" | "object-position" | "column-width" | "column-count" | "margin-top" | "margin-bottom" | "margin-left" | "margin-right" | "padding-top" | "padding-bottom" | "padding-left" | "padding-right" | "font-family" | "font-weight" | "font-size" | "line-height" | "color" | "text-align" | "font-style" | "font-variant" | "text-decoration" | "text-decoration-line" | "text-decoration-color" | "text-decoration-style" | "text-decoration-thickness" | "text-underline-offset" | "letter-spacing" | "word-spacing" | "text-indent" | "text-transform" | "direction" | "white-space" | "text-wrap" | "word-break" | "overflow-wrap" | "hyphens" | "vertical-align" | "text-overflow" | "text-shadow" | "line-clamp" | "-webkit-line-clamp" | "-webkit-box-orient" | "stroke" | "stroke-width";
 }[];
 export declare const baseDefaultValue: Record<StyleCategory, StyleValue>;
 export default styleConstants;

package/dist/style/styleConstants.mjs

@@ -11,6 +11,7 @@ var e = {
 		schemes: ["light", "dark"]
 	},
 	variables: {},
+	fonts: [],
 	cache: ""
 }, t = {
 	DISPLAY: "display",

package/dist/theme/ThemeProvider.d.ts

@@ -1,12 +1,42 @@
-import { Theme, ThemeContextValue } from '../types';
+import { Theme } from '../types';
 import { ReactNode } from 'react';
-declare const ThemeContext: import('react').Context<ThemeContextValue>;
+/**
+ * Whose theme this provider is running.
+ *
+ * `document` — the default — is a surface that IS the page: it stamps the class on `<html>`, and everything in the
+ * document follows it. `container` is the SDK EMBEDDED in an application that has a theme of its own: it touches
+ * nothing outside itself, gets a theme store of its own, and hands the class back through `useTheme` for the app's
+ * own root element to wear.
+ *
+ * The desktop window is why this exists. It renders its chrome in Tailwind's `dark:` variants off the document
+ * class and mounts the SDK twice inside it — once for the rail, once for the space the visitor opened — so a
+ * visitor toggling the theme of THEIR space was repainting the application around it.
+ */
+export type ThemeScope = 'document' | 'container';
 export type ThemeProviderProps = {
     defaultTheme?: Theme;
-    storageKey?: string;
-    storageType?: 'localStorage' | 'sessionStorage';
+    /**
+     * The theme the host already knows.
+     *
+     * The server-rendered case: the choice is in the cookie, the server read it, rendered the class and passes the
+     * value here — so the document arrives correct and the provider agrees with it from its first render. Left out,
+     * the cookie is read here instead, which is what a surface no server rendered does.
+     */
+    theme?: Theme;
+    scope?: ThemeScope;
+    /** The cookie the choice lives in. Named per surface where two share an origin — the builder and a space do. */
+    cookieName?: string;
     children?: ReactNode;
 };
-declare const ThemeProvider: ({ defaultTheme, storageKey, storageType, children }: ThemeProviderProps) => import("react").JSX.Element;
-export { ThemeContext };
+/**
+ * Drives the theme store: what was chosen, what the machine is asking for, and what the document says.
+ *
+ * It provides no VALUE. The theme lives in a store and every consumer reads it with `useTheme`, so a panel in a
+ * shadow root or an editor in a portal gets the same answer as a component under this element. What is left here is
+ * the three things only a mounted component can do — read the cookie once, subscribe to `matchMedia`, and stamp the
+ * root — and doing them in ONE place is the point: a component running its own `matchMedia` gets a value that stops
+ * updating the moment the visitor changes their system setting, which is how a panel ends up dark inside a page
+ * that is still light.
+ */
+declare const ThemeProvider: ({ defaultTheme, theme, scope, cookieName, children }: ThemeProviderProps) => import("react").JSX.Element;
 export default ThemeProvider;

package/dist/theme/ThemeProvider.mjs

@@ -1,40 +1,54 @@
-import { createContext as e, useCallback as t, useEffect as n, useMemo as r } from "react";
-import { jsx as i } from "react/jsx-runtime";
-import a from "@plitzi/plitzi-ui/hooks/useStorage";
+import { THEME_COOKIE_NAME as e, applyThemeClass as t, readThemeCookie as n, writeThemeCookie as r } from "./themeCookie.mjs";
+import i, { createThemeStore as a, resolveScheme as o, setMachineScheme as s, setThemeMode as c } from "./themeStore.mjs";
+import l from "./ThemeScope.mjs";
+import { useCommonStoreSync as u } from "../store/index.mjs";
+import { use as d, useEffect as f, useId as p, useState as m, useSyncExternalStore as h } from "react";
+import { StoreContext as g, useIsomorphicLayoutEffect as _ } from "@plitzi/nexus/react";
+import { Fragment as v, jsx as y, jsxs as b } from "react/jsx-runtime";
 //#region src/theme/ThemeProvider.tsx
-var o = e({
-	theme: "dark",
-	toggleTheme: () => {}
-});
-o.displayName = "ThemeContext";
-var s = ({ defaultTheme: e = "dark", storageKey: s = "theme", storageType: c = "localStorage", children: l }) => {
-	let [u, d] = a(s, e, c);
-	n(() => {
-		if (typeof document > "u" || typeof window > "u") return;
-		let e = new MutationObserver(() => d(document.documentElement.classList.contains("dark") ? "dark" : "light"));
-		e.observe(document.documentElement, {
-			attributes: !0,
-			attributeFilter: ["class"]
+var x = "(prefers-color-scheme: dark)", S = () => window.matchMedia(x).matches ? "dark" : "light", C = ({ state: e }) => (u([
+	"theme.mode",
+	"theme.resolved",
+	"theme.areas"
+], [
+	e.mode,
+	o(e.mode, e.scheme),
+	e.areas
+]), null), w = ({ defaultTheme: o = "system", theme: u, scope: w = "document", cookieName: T = e, children: E }) => {
+	let D = w === "container", O = p(), [k] = m(() => D ? a(`theme${O}`) : void 0), A = k ?? i;
+	_(() => {
+		let e = D ? void 0 : n(T);
+		A.batch(() => {
+			s(S(), A), c(u ?? e ?? o, A);
 		});
-		let t = window.matchMedia("(prefers-color-scheme: dark)"), n = (e) => d(e.matches ? "dark" : "light");
-		return t.addEventListener("change", n), () => {
-			e.disconnect(), t.removeEventListener("change", n);
+	}, [
+		o,
+		u,
+		T,
+		D,
+		A
+	]);
+	let j = h(A.subscribe, A.getState, A.getState), M = d(g) !== void 0;
+	f(() => {
+		let e = window.matchMedia(x), t = () => s(e.matches ? "dark" : "light", A);
+		return e.addEventListener("change", t), t(), () => e.removeEventListener("change", t);
+	}, [A]), f(() => {
+		if (D) return;
+		let e = () => {
+			let { mode: e } = A.getState();
+			r(e, T), t(e, document.documentElement);
 		};
-	}, []), n(() => {
-		if (typeof document > "u") return;
-		let e = document.documentElement;
-		u === "dark" ? e.classList.add("dark") : e.classList.remove("dark");
-	}, [u]);
-	let f = t(() => {
-		d((e) => e === "dark" ? "light" : "dark");
-	}, [d]), p = r(() => ({
-		theme: u,
-		toggleTheme: f
-	}), [u, f]);
-	return /* @__PURE__ */ i(o, {
-		value: p,
-		children: l
-	});
+		return e(), A.subscribe(e);
+	}, [
+		T,
+		D,
+		A
+	]);
+	let N = M ? /* @__PURE__ */ y(C, { state: j }) : null;
+	return D ? /* @__PURE__ */ b(l, {
+		value: k,
+		children: [N, E]
+	}) : /* @__PURE__ */ b(v, { children: [N, E] });
 };
 //#endregion
-export { o as ThemeContext, s as default };
+export { w as default };

package/dist/theme/ThemeScope.d.ts

@@ -0,0 +1,16 @@
+import { ThemeStoreInstance } from './themeStore';
+/**
+ * Which theme store the tree under here reads.
+ *
+ * Absent — the ordinary case — means the surface's own, the module-level singleton. It is only ever provided by a
+ * `ThemeProvider` running in `container` scope: an SDK embedded in an application that has a theme of its own, where
+ * "the surface" is the application and not the space inside it. Two SDK instances in one document (the desktop
+ * window renders its shell as a space AND the space the visitor opened) is exactly the case the singleton cannot
+ * serve on its own — whichever mounted last would be answering for both.
+ *
+ * Deliberately NOT the way ordinary consumers reach the theme: a panel in a shadow root and an editor in a portal
+ * are under no provider at all, and they still have to get an answer. That is what the fall-through is for.
+ */
+declare const ThemeScopeContext: import('react').Context<import('@plitzi/nexus').StoreApi<import('..').ThemeState> | undefined>;
+export declare const useThemeStore: () => ThemeStoreInstance;
+export default ThemeScopeContext;

package/dist/theme/ThemeScope.mjs

@@ -0,0 +1,6 @@
+import e from "./themeStore.mjs";
+import { createContext as t, use as n } from "react";
+//#region src/theme/ThemeScope.ts
+var r = t(void 0), i = () => n(r) ?? e;
+//#endregion
+export { r as default, i as useThemeStore };

package/dist/theme/index.d.ts

@@ -1,3 +1,9 @@
 import { default as ThemeProvider } from './ThemeProvider';
+import { default as useTheme } from './useTheme';
 export * from './ThemeProvider';
-export { ThemeProvider };
+export * from './ThemeScope';
+export * from './themeCookie';
+export * from './themeStore';
+export * from './useTheme';
+export { default as themeStore } from './themeStore';
+export { ThemeProvider, useTheme };

package/dist/theme/index.mjs

@@ -1,2 +1,6 @@
-import e, { ThemeContext as t } from "./ThemeProvider.mjs";
-export { t as ThemeContext, e as ThemeProvider };
+import { THEME_CLASSES as e, THEME_COOKIE_NAME as t, applyThemeClass as n, isTheme as r, readThemeCookie as i, themeFromCookies as a, writeThemeCookie as o } from "./themeCookie.mjs";
+import s, { createThemeState as c, createThemeStore as l, resolveScheme as u, setAreaTheme as d, setMachineScheme as f, setThemeMode as p, themeFor as m } from "./themeStore.mjs";
+import { useThemeStore as h } from "./ThemeScope.mjs";
+import g from "./ThemeProvider.mjs";
+import _, { SPACE_THEME_AREA as v } from "./useTheme.mjs";
+export { v as SPACE_THEME_AREA, e as THEME_CLASSES, t as THEME_COOKIE_NAME, g as ThemeProvider, n as applyThemeClass, c as createThemeState, l as createThemeStore, r as isTheme, i as readThemeCookie, u as resolveScheme, d as setAreaTheme, f as setMachineScheme, p as setThemeMode, m as themeFor, a as themeFromCookies, s as themeStore, _ as useTheme, h as useThemeStore, o as writeThemeCookie };

package/dist/theme/themeCookie.d.ts

@@ -0,0 +1,30 @@
+import { Theme } from '../types';
+/** The name the choice is kept under, and the one a server reads it back with. */
+export declare const THEME_COOKIE_NAME = "theme";
+/** The two a document may WEAR. `system` writes nothing — the absence is what lets the media queries answer. */
+export declare const THEME_CLASSES: Theme[];
+export declare const isTheme: (value: unknown) => value is Theme;
+/**
+ * Applies a theme to an element — the chosen class on, the other off, so a change is never additive.
+ *
+ * Removing a class cannot express "I want light on a machine set to dark", which is why `light` is written as
+ * explicitly as `dark` is, and why only `system` leaves the element bare.
+ */
+export declare const applyThemeClass: (mode: Theme, root: HTMLElement) => void;
+/**
+ * Reads the theme out of a `Cookie` header, or out of `document.cookie`.
+ *
+ * A cookie and not web storage, and that is the whole design: it is the only place a browser keeps a preference
+ * that the SERVER can also read. So the document arrives with the class already on `<html>` — no blocking script
+ * in the head to beat the first paint, no four hundred milliseconds of the other theme for the SDK to correct,
+ * and no second copy of these rules written in another language for a template to get subtly wrong.
+ *
+ * One function for both sides for the same reason: the server parsing the header with its own regex is that copy.
+ */
+export declare const themeFromCookies: (cookies: string | undefined, name?: string) => Theme | undefined;
+/**
+ * Every accessor is guarded: a sandboxed iframe and a browser set to block site data both answer by throwing
+ * rather than by returning nothing. The theme still works there; it just stops being remembered.
+ */
+export declare const readThemeCookie: (name?: string) => Theme | undefined;
+export declare const writeThemeCookie: (mode: Theme, name?: string) => void;

package/dist/theme/themeCookie.mjs

@@ -0,0 +1,24 @@
+//#region src/theme/themeCookie.ts
+var e = "theme", t = ["dark", "light"], n = [...t, "system"], r = 31536e3, i = (e) => n.includes(e), a = (e, n) => {
+	for (let r of t) n.classList.toggle(r, e === r);
+}, o = (t, n = e) => {
+	if (t) for (let e of t.split(";")) {
+		let t = e.indexOf("=");
+		if (t > -1 && e.slice(0, t).trim() === n) {
+			let n = decodeURIComponent(e.slice(t + 1).trim());
+			return i(n) ? n : void 0;
+		}
+	}
+}, s = (t = e) => {
+	try {
+		return o(document.cookie, t);
+	} catch {
+		return;
+	}
+}, c = (t, n = e) => {
+	try {
+		document.cookie = `${n}=${encodeURIComponent(t)};path=/;max-age=${r};SameSite=Lax`;
+	} catch {}
+};
+//#endregion
+export { t as THEME_CLASSES, e as THEME_COOKIE_NAME, a as applyThemeClass, i as isTheme, s as readThemeCookie, o as themeFromCookies, c as writeThemeCookie };

package/dist/theme/themeStore.d.ts

@@ -0,0 +1,40 @@
+import { ColorScheme, Theme, ThemeState } from '../types';
+export declare const createThemeState: () => ThemeState;
+/**
+ * The theme, as a store rather than a context.
+ *
+ * It is read by things that render outside the app's provider tree — the dev-tools panel in its shadow root, an
+ * editor mounted into a portal — and by the odd module that has no component around it at all. A context could
+ * serve neither, and every consumer that wanted the answer had to be under the one provider that held it.
+ *
+ * What varies WITHIN a surface is `areas`, which is a map rather than a second store for the same reason — two
+ * stores would need somebody to keep them in step, and "keeping them in step" is the whole of what an area's rule
+ * is.
+ */
+export declare const createThemeStore: (id?: string) => import('@plitzi/nexus').StoreApi<ThemeState>;
+export type ThemeStoreInstance = ReturnType<typeof createThemeStore>;
+/**
+ * The surface's theme.
+ *
+ * A browser tab usually paints one surface, and this is it — what the dev-tools panel and anything else outside a
+ * provider tree reads. It stops being the only one when a page EMBEDS the SDK in an application that has a theme of
+ * its own (the desktop window, a space mounted in a host): there the embedded surface gets a store of its own from
+ * {@link createThemeStore} and this one keeps belonging to the application around it. See `ThemeProvider`'s `scope`.
+ */
+declare const themeStore: import('@plitzi/nexus').StoreApi<ThemeState>;
+export declare const resolveScheme: (mode: Theme, scheme: ColorScheme) => ColorScheme;
+/** The theme of one area, or of the surface when the area has made no choice of its own. */
+export declare const themeFor: (state: ThemeState, area?: string) => Theme;
+/**
+ * The surface's own choice — and, with it, every area's.
+ *
+ * Clearing `areas` IS the sync rule: an area's theme is an override of what the surface is currently showing, so
+ * the moment the surface changes its mind there is nothing left to override. Without this an author who darkened
+ * the preview pane once would find it stuck there for good, deaf to the editor's toggle, which is the complaint
+ * that a separate per-area setting always produces.
+ */
+export declare const setThemeMode: (mode: Theme, store?: ThemeStoreInstance) => void;
+export declare const setAreaTheme: (area: string, mode: Theme, store?: ThemeStoreInstance) => void;
+/** What the machine is asking for. Written only by `ThemeProvider`, which is the one subscriber to it. */
+export declare const setMachineScheme: (scheme: ColorScheme, store?: ThemeStoreInstance) => void;
+export default themeStore;

package/dist/theme/themeStore.mjs

@@ -0,0 +1,17 @@
+import { createStore as e } from "@plitzi/nexus";
+//#region src/theme/themeStore.ts
+var t = () => ({
+	mode: "system",
+	scheme: "light",
+	areas: {}
+}), n = (n = "theme") => e(t(), { id: n }), r = n(), i = (e, t) => e === "system" ? t : e, a = (e, t) => (t ? e.areas[t] : void 0) ?? e.mode, o = (e, t = r) => {
+	t.batch(() => {
+		t.setState("mode", e), t.setState("areas", {});
+	});
+}, s = (e, t, n = r) => {
+	n.setState(`areas.${e}`, t);
+}, c = (e, t = r) => {
+	t.setState("scheme", e);
+};
+//#endregion
+export { t as createThemeState, n as createThemeStore, r as default, i as resolveScheme, s as setAreaTheme, c as setMachineScheme, o as setThemeMode, a as themeFor };

package/dist/theme/useTheme.d.ts

@@ -0,0 +1,29 @@
+import { ThemeValue } from '../types';
+/**
+ * The area every surface that paints the SPACE uses — the builder's canvas, and every `BuilderAreaPreview`: the
+ * page thumbnails, a template preview, what the agent renders in the chat.
+ *
+ * ONE area and not one per surface, on purpose. They are all showing the same thing, and a preview of a page that
+ * paints in a different scheme from the canvas beside it is not a preview of anything. What the split is actually
+ * for is the EDITOR versus the space it is editing: the panels, menus and dialogs follow the surface theme, and
+ * this follows whichever scheme the author wants to look at their page in.
+ *
+ * Named rather than typed at each call site so there is one string to change and nowhere for a typo to hide — a
+ * misspelled area does not fail, it silently makes a second one that follows the surface.
+ */
+export declare const SPACE_THEME_AREA = "canvas";
+/**
+ * The theme, for whoever is asking.
+ *
+ * Called bare it answers the surface's; called with an `area` it answers that area's, falling back to the surface
+ * while the area has made no choice of its own. `setTheme` writes wherever it read, so a control never has to know
+ * which of the two it is wired to — the builder's header toggle and the canvas's own are the same component with a
+ * different argument.
+ *
+ * `resolvedTheme` is always a colour: `system` is resolved against the machine's live answer, which `ThemeProvider`
+ * keeps in the store. Anything that PAINTS wants that one — a code editor, a chart, a canvas — because `system`
+ * cannot be compared against a colour, and resolving it to `light` (the usual shortcut) makes a dark-set machine
+ * render the light thing.
+ */
+declare const useTheme: (area?: string) => ThemeValue;
+export default useTheme;

package/dist/theme/useTheme.mjs

@@ -0,0 +1,20 @@
+import { resolveScheme as e, setAreaTheme as t, setThemeMode as n, themeFor as r } from "./themeStore.mjs";
+import { useThemeStore as i } from "./ThemeScope.mjs";
+import { useCallback as a, useMemo as o, useSyncExternalStore as s } from "react";
+//#region src/theme/useTheme.ts
+var c = "canvas", l = (c) => {
+	let l = i(), u = s(l.subscribe, l.getState, l.getState), d = r(u, c), f = e(d, u.scheme), p = a((e) => c ? t(c, e, l) : n(e, l), [c, l]), m = a(() => p(f === "dark" ? "light" : "dark"), [f, p]);
+	return o(() => ({
+		theme: d,
+		resolvedTheme: f,
+		setTheme: p,
+		toggleTheme: m
+	}), [
+		d,
+		f,
+		p,
+		m
+	]);
+};
+//#endregion
+export { c as SPACE_THEME_AREA, l as default };