@stridge/noctis-theme-engine 1.0.0-beta.0

package/dist/ssr/ssr.js

@@ -0,0 +1,167 @@
+import { ENGINE_LAYER } from "../generate/tokens.js";
+import { generateTheme, isSafeCssValue } from "../generate/theme.js";
+//#region src/ssr/ssr.ts
+/**
+* SSR + persistence helpers — the no-FOUC story.
+*
+* The default theme is emitted as static CSS at build time (first paint is correct with
+* zero JS). A persisted custom theme rides in a cookie (SSR-readable) and in localStorage;
+* a tiny blocking `<script>` applies the persisted variables before first paint, and the
+* React provider takes over on hydration.
+*/
+/** Cookie + localStorage key under which the active theme is persisted. */
+const THEME_COOKIE_NAME = "stridge-theme";
+const THEME_STORAGE_KEY = "stridge-theme";
+/** Serialize a theme map into a CSS declaration body (`--k:v;…`). */
+function declarationsFor(map) {
+	let out = "";
+	for (const key in map) out += `${key}:${map[key]};`;
+	return out;
+}
+/**
+* Build-time static CSS for a theme — the default brand theme shipped on `:root` so the first
+* paint is correct without any JavaScript. The rule is wrapped in `@layer noctis.engine`, the
+* same layer the runtime sheet declares into, so SSR and CSR emission carry identical names,
+* values, and cascade position — and any unlayered author rule beats both.
+*/
+function emitStaticCss(input, selector = ":root", options) {
+	return `@layer ${ENGINE_LAYER}{${selector}{${declarationsFor(generateTheme(input, options))}}}`;
+}
+/** Encode an input (plus any generation-time overrides) for cookie/storage transport (compact, URL-safe). */
+function encodeThemeInput(input, overrides) {
+	const payload = overrides && Object.keys(overrides).length > 0 ? {
+		...input,
+		overrides
+	} : input;
+	return encodeURIComponent(JSON.stringify(payload));
+}
+/**
+* Whether `value` is a valid override map shape: a plain object of emission-safe string values.
+* Cookie/storage payloads are attacker-influenceable and feed SSR `<style>` text, so any entry
+* carrying a rule-delimiting character fails the WHOLE record closed (overrides drop to none)
+* rather than throwing during SSR.
+*/
+function isOverrideRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return Object.values(value).every((entry) => typeof entry === "string" && isSafeCssValue(entry));
+}
+/** Decode a cookie/storage value back into an input (with its overrides), or `null` if malformed. */
+function decodeThemeInput(value) {
+	try {
+		const parsed = JSON.parse(decodeURIComponent(value));
+		if (typeof parsed.background !== "string" || typeof parsed.accent !== "string") return null;
+		if (typeof parsed.contrast !== "number") return null;
+		const input = {
+			background: parsed.background,
+			accent: parsed.accent,
+			contrast: parsed.contrast,
+			mode: parsed.mode
+		};
+		if (isOverrideRecord(parsed.overrides)) input.overrides = parsed.overrides;
+		return input;
+	} catch {
+		return null;
+	}
+}
+/** Read the persisted theme input (with its overrides) from a raw `Cookie` header string (server-side). */
+function readThemeCookie(cookieHeader, name = THEME_COOKIE_NAME) {
+	if (!cookieHeader) return null;
+	for (const part of cookieHeader.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() === name) return decodeThemeInput(part.slice(eq + 1).trim());
+	}
+	return null;
+}
+const ONE_YEAR = 3600 * 24 * 365;
+/**
+* Browsers silently drop a `Set-Cookie` near 4096 bytes; URL-encoding inflates oklch values, so
+* a large override set can cross it (≈86 overrides). Warn below the cap with headroom for the
+* attribute suffix.
+*/
+const COOKIE_WARN_BYTES = 4e3;
+/**
+* Build a `Set-Cookie` value for the persisted theme (for server responses). The cookie carries
+* the seed plus the override delta, not the generated vars — but a large enough override set can
+* still exceed the ~4096-byte cookie cap, where browsers silently drop the write and SSR falls
+* back to the default theme; a dev-time warning fires as the encoded value approaches it.
+*/
+function serializeThemeCookie(input, options = {}) {
+	const { name = THEME_COOKIE_NAME, maxAge = ONE_YEAR, path = "/", sameSite = "Lax", overrides } = options;
+	const secure = sameSite === "None" ? "; Secure" : "";
+	const cookie = `${name}=${encodeThemeInput(input, overrides)}; Path=${path}; Max-Age=${maxAge}; SameSite=${sameSite}${secure}`;
+	if (cookie.length > COOKIE_WARN_BYTES && typeof process !== "undefined" && process?.env?.NODE_ENV !== "production") console.warn(`theme-engine: the persisted theme cookie is ${cookie.length} bytes — browsers silently drop cookies near 4096 bytes, so SSR would fall back to the default theme. Trim the override set.`);
+	return cookie;
+}
+/** Write the theme cookie from the browser (`document.cookie`). */
+function writeThemeCookie(input, options = {}) {
+	if (typeof document === "undefined") return;
+	document.cookie = serializeThemeCookie(input, options);
+}
+function isValidInput(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const input = value;
+	return typeof input.background === "string" && typeof input.accent === "string" && typeof input.contrast === "number";
+}
+/**
+* Persist the active theme (input + computed vars + any generation-time overrides) to
+* localStorage for instant pre-paint apply. The vars are the resolved output, so the blocking
+* script replays an overridden theme without engine code. Storage access can throw (privacy
+* settings, quota, opaque origins), so failures are swallowed.
+*/
+function persistTheme(input, vars, overrides, key = THEME_STORAGE_KEY) {
+	if (typeof localStorage === "undefined") return;
+	const payload = overrides && Object.keys(overrides).length > 0 ? {
+		input,
+		vars,
+		overrides
+	} : {
+		input,
+		vars
+	};
+	try {
+		localStorage.setItem(key, JSON.stringify(payload));
+	} catch {}
+}
+/** Read the persisted input back (for the React layer's initial state). Validated; never throws. */
+function readPersistedInput(key = THEME_STORAGE_KEY) {
+	if (typeof localStorage === "undefined") return null;
+	try {
+		const raw = localStorage.getItem(key);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		return isValidInput(parsed.input) ? parsed.input : null;
+	} catch {
+		return null;
+	}
+}
+/** Read the persisted generation-time overrides back, or `null` when none were stored. Never throws. */
+function readPersistedOverrides(key = THEME_STORAGE_KEY) {
+	if (typeof localStorage === "undefined") return null;
+	try {
+		const raw = localStorage.getItem(key);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		return isOverrideRecord(parsed.overrides) ? parsed.overrides : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Generate the body of a blocking inline `<script>` for `<head>`: it reads the persisted
+* variables from localStorage and replays them in a `<style>` rule — `@layer noctis.engine`,
+* `:root` — before first paint, killing the flash for client-persisted custom themes. Ships no
+* engine code — it only replays stored vars.
+*
+* The replay lands in the SAME layer the runtime sheet declares into, so the provider's
+* hydration emission (later in the layer by source order) supersedes it and post-hydration theme
+* changes paint normally. The persisted payload carries the ROOT var map only, so the
+* `el`/`su`/`mn` scope sets keep the build-time default until hydration — a custom-scope theme
+* shows default scope surfaces for that window. localStorage is same-origin: the replayed values
+* are the ones {@link persistTheme} wrote, validated at generation time.
+*/
+function themeBlockingScript(key = THEME_STORAGE_KEY) {
+	return `(function(){try{var s=localStorage.getItem(${JSON.stringify(key)});if(!s)return;var v=(JSON.parse(s)||{}).vars;if(!v)return;var b="";for(var k in v)b+=k+":"+v[k]+";";var t=document.createElement("style");t.setAttribute("data-noctis-engine-blocking","");t.textContent="@layer ${ENGINE_LAYER}{:root{"+b+"}}";(document.head||document.documentElement).appendChild(t);}catch(e){}})();`;
+}
+//#endregion
+export { THEME_COOKIE_NAME, THEME_STORAGE_KEY, declarationsFor, decodeThemeInput, emitStaticCss, encodeThemeInput, persistTheme, readPersistedInput, readPersistedOverrides, readThemeCookie, serializeThemeCookie, themeBlockingScript, writeThemeCookie };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@stridge/noctis-theme-engine",
+  "version": "1.0.0-beta.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "culori": "4.0.2"
+  },
+  "peerDependencies": {
+    "react": "19.2.7"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@types/culori": "4.0.1",
+    "@types/react": "19.2.16",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "6.0.2",
+    "jsdom": "29.1.1",
+    "publint": "0.3.20",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "tsdown": "0.21.10",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8",
+    "@stridge/noctis-typescript": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check:publint": "publint",
+    "check:publish": "pnpm run check:publint",
+    "check:types": "tsc --noEmit",
+    "test": "vitest --run"
+  }
+}