@nanisoft/prism-ui 0.5.0 → 0.6.0

package/dist/pages/not-found-page/index.d.ts

@@ -0,0 +1,112 @@
+import type { ReactNode } from 'react';
+/**
+ * One way out of a page that was not found.
+ *
+ * A destination, and the words for it. Both are required, because a not-found
+ * page with no way out is a dead end with a message on it, and a link with no
+ * words is a shape a reader has to guess at.
+ */
+export type NotFoundLink = {
+    /** The words of the link. */
+    label: string;
+    /** Where it goes. */
+    href: string;
+    /**
+     * Opens the destination in a new browsing context, which defaults the link
+     * relationship to `noopener noreferrer`. Almost never right here: a reader who
+     * followed a broken link and is sent to a new tab has to find their way back.
+     */
+    newTab?: boolean;
+};
+/**
+ * The props a NotFoundPage takes.
+ *
+ * Every string is a prop and the Page ships none. There is no "404", no "this
+ * page does not exist", no product name and no default set of links: a not-found
+ * page that hardcoded any of them would be a page that made a claim about a
+ * product it knows nothing about, and the one page on a site that every reader
+ * and no crawler will see is the worst place to hardcode a sentence.
+ */
+export type NotFoundPageProps = {
+    /**
+     * The status code, shown as the page's own `h1`. Required, and a string rather
+     * than a number because it is displayed, not computed: a Page never decides
+     * what code it is answering.
+     */
+    code: string;
+    /**
+     * The headline under the code: the sentence that says what happened. It is the
+     * part a reader actually reads, and it is the caller's because every product
+     * says it differently - "No node here", "This page does not exist (yet)".
+     */
+    title: string;
+    /**
+     * One or two sentences under the headline, for anything a reader should know
+     * before they follow one of the links: that the URL may be mistyped, that the
+     * page is planned, that a search would find it.
+     */
+    description?: string;
+    /**
+     * The ways out, in the order a reader should see them. Put the destination
+     * most likely to help first; a not-found page that offers a homepage link
+     * before the documentation sends a reader further from what they wanted.
+     */
+    links: readonly NotFoundLink[];
+    /**
+     * The accessible name of the row of ways out. It is required, because it is a
+     * word a reader hears and a Page that ships no copy ships no reader-facing copy
+     * either. "Ways out" is the Page's own phrasing; a site that files its
+     * destinations differently names the same landmark differently.
+     */
+    linksLabel: string;
+    /**
+     * A slot for whatever else the site wants to say here: a search box, a list of
+     * recent posts, a contact address.
+     */
+    children?: ReactNode;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A complete not-found screen: the code, what happened, and the ways out.
+ *
+ * All four NaniSoft sites compose one, each in its own `not-found` route, and
+ * three of them are the same six lines with a different product name on it: a
+ * display title carrying the code, one muted sentence, and two or three links.
+ * The fourth wrote the same thing in its own markup. Four hand-written screens
+ * for one shape.
+ *
+ * It is a Page rather than a Block because it is a whole screen: it owns the
+ * document's `h1`, it is what a router renders when a route does not resolve, and
+ * it composes `Section`, `Heading`, `Text`, `Prose` and `CtaLink` into the one
+ * arrangement of them that answers "this is not here". A Block would be a band
+ * of that arrangement, and the band's job is not separable from the screen's:
+ * there is one correct page here and it is short.
+ *
+ * **The code is the `h1` and the sentence is not.** A not-found page whose
+ * `h1` is "Page not found" gives a search engine and a screen reader nothing
+ * distinct to index, and the code is the one string on the page that is the same
+ * for every broken URL. The code takes the display step and the sentence takes
+ * the muted one, which is the reverse of what a reader sees first and the right
+ * way round for anything that reads the outline.
+ *
+ * The links are `CtaLink`, so each one is a native anchor with a destination a
+ * browser can show, copy and open in a new tab. A not-found page is the one place
+ * on a site where a reader most wants to see where a link goes before following
+ * it, because they have just followed one that went nowhere.
+ *
+ * The page carries no `noindex` and no `robots` directive, because this is a
+ * component and not a route: what a not-found response is indexed as is the
+ * consumer's server's decision, and a Page that declared it would be a Page
+ * making a claim about a deployment it cannot see.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, which is what lets a consumer render it from whichever not-found
+ * route their framework names.
+ */
+export declare function NotFoundPage({ code, title, description, links, linksLabel, children, className, }: NotFoundPageProps): import("react").JSX.Element;
+export default NotFoundPage;
+//# sourceMappingURL=index.d.ts.map

package/dist/pages/not-found-page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/not-found-page/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOtC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,EACL,UAAU,EACV,QAAQ,EACR,SAAS,GACV,EAAE,iBAAiB,+BA+BnB;AAED,eAAe,YAAY,CAAA"}

package/dist/pages/not-found-page/index.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CtaLink } from '../../components/ui/cta-link';
+import { Heading, Text } from '../../components/ui/typography';
+import { Prose } from '../../components/ui/prose';
+import { Section } from '../../components/ui/section';
+/**
+ * A complete not-found screen: the code, what happened, and the ways out.
+ *
+ * All four NaniSoft sites compose one, each in its own `not-found` route, and
+ * three of them are the same six lines with a different product name on it: a
+ * display title carrying the code, one muted sentence, and two or three links.
+ * The fourth wrote the same thing in its own markup. Four hand-written screens
+ * for one shape.
+ *
+ * It is a Page rather than a Block because it is a whole screen: it owns the
+ * document's `h1`, it is what a router renders when a route does not resolve, and
+ * it composes `Section`, `Heading`, `Text`, `Prose` and `CtaLink` into the one
+ * arrangement of them that answers "this is not here". A Block would be a band
+ * of that arrangement, and the band's job is not separable from the screen's:
+ * there is one correct page here and it is short.
+ *
+ * **The code is the `h1` and the sentence is not.** A not-found page whose
+ * `h1` is "Page not found" gives a search engine and a screen reader nothing
+ * distinct to index, and the code is the one string on the page that is the same
+ * for every broken URL. The code takes the display step and the sentence takes
+ * the muted one, which is the reverse of what a reader sees first and the right
+ * way round for anything that reads the outline.
+ *
+ * The links are `CtaLink`, so each one is a native anchor with a destination a
+ * browser can show, copy and open in a new tab. A not-found page is the one place
+ * on a site where a reader most wants to see where a link goes before following
+ * it, because they have just followed one that went nowhere.
+ *
+ * The page carries no `noindex` and no `robots` directive, because this is a
+ * component and not a route: what a not-found response is indexed as is the
+ * consumer's server's decision, and a Page that declared it would be a Page
+ * making a claim about a deployment it cannot see.
+ *
+ * It is a server Component. It fetches nothing, it holds no state and it imports
+ * no router, which is what lets a consumer render it from whichever not-found
+ * route their framework names.
+ */
+export function NotFoundPage({ code, title, description, links, linksLabel, children, className, }) {
+    return (_jsx(Section, { className: className, children: _jsxs("div", { className: "flex flex-col items-start gap-6", children: [_jsx(Heading, { as: "h1", size: "4xl", className: "text-muted-foreground font-mono", children: code }), _jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h2", size: "2xl", children: title }), description ? _jsx(Text, { size: "lg", children: description }) : null] }), links.length > 0 ? (_jsx("nav", { "aria-label": linksLabel, className: "flex flex-wrap items-center gap-3", children: links.map((link, index) => (_jsx(CtaLink, { href: link.href, newTab: link.newTab, variant: index === 0 ? 'default' : 'outline', children: link.label }, link.href))) })) : null, children ? _jsx(Prose, { className: "mt-2", children: children }) : null] }) }));
+}
+export default NotFoundPage;

package/dist/pages/settings-page/index.d.ts

@@ -0,0 +1,47 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { AppShell01 } from '../../blocks/app-shell-01';
+import { PageHeader01 } from '../../blocks/page-header-01';
+import { SettingsPanel01 } from '../../blocks/settings-panel-01';
+export type SettingsPageTab = {
+    /** The value shared by the trigger and its panel. */
+    value: string;
+    /** The trigger label. */
+    label: string;
+    /**
+     * A saved settings form for this tab. Rendered through `SettingsPanel01`, so
+     * the tab inherits the grouped sections, the field kinds and the save footer.
+     */
+    panel?: ComponentProps<typeof SettingsPanel01>;
+    /** Content for a tab that is not a saved form, such as a read-only summary. */
+    content?: ReactNode;
+};
+export type SettingsPageProps = {
+    /** The frame: rail, top bar and mobile navigation sheet. */
+    shell: Omit<ComponentProps<typeof AppShell01>, 'children'>;
+    /** The page title band. */
+    header: ComponentProps<typeof PageHeader01>;
+    /** The tabs, in order. At least one is required. */
+    tabs: SettingsPageTab[];
+    /** The tab shown first, for uncontrolled tabs. Defaults to the first tab. */
+    defaultValue?: string;
+    /** The controlled active tab. */
+    value?: string;
+    onValueChange?: (value: string) => void;
+};
+/**
+ * A complete settings screen.
+ *
+ * It composes `AppShell01`, `PageHeader01`, `Tabs` and `SettingsPanel01`: the
+ * shell provides the frame, the header names the screen, and each tab is a
+ * saved settings form or a read-only panel. The page owns the sequence and the
+ * tab wiring only. Every section, field, option and label is a prop, and the
+ * page fetches nothing.
+ *
+ * A tab that carries a `panel` renders `SettingsPanel01`, so a settings screen
+ * is a set of grouped forms rather than one long page. A tab that carries
+ * `content` instead renders the node as-is. Both are optional, so a caller can
+ * mix forms and read-only views in one screen.
+ */
+export declare function SettingsPage({ shell, header, tabs, defaultValue, value, onValueChange, }: SettingsPageProps): import("react").JSX.Element;
+export default SettingsPage;
+//# sourceMappingURL=index.d.ts.map

package/dist/pages/settings-page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/settings-page/index.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAGhE,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAA;IACb,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,eAAe,CAAC,CAAA;IAC9C,+EAA+E;IAC/E,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4DAA4D;IAC5D,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,UAAU,CAAC,EAAE,UAAU,CAAC,CAAA;IAC1D,2BAA2B;IAC3B,MAAM,EAAE,cAAc,CAAC,OAAO,YAAY,CAAC,CAAA;IAC3C,oDAAoD;IACpD,IAAI,EAAE,eAAe,EAAE,CAAA;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,MAAM,EACN,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,aAAa,GACd,EAAE,iBAAiB,+BA4BnB;AAED,eAAe,YAAY,CAAA"}

package/dist/pages/settings-page/index.js

@@ -0,0 +1,24 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AppShell01 } from '../../blocks/app-shell-01';
+import { PageHeader01 } from '../../blocks/page-header-01';
+import { SettingsPanel01 } from '../../blocks/settings-panel-01';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../../components/ui/tabs';
+/**
+ * A complete settings screen.
+ *
+ * It composes `AppShell01`, `PageHeader01`, `Tabs` and `SettingsPanel01`: the
+ * shell provides the frame, the header names the screen, and each tab is a
+ * saved settings form or a read-only panel. The page owns the sequence and the
+ * tab wiring only. Every section, field, option and label is a prop, and the
+ * page fetches nothing.
+ *
+ * A tab that carries a `panel` renders `SettingsPanel01`, so a settings screen
+ * is a set of grouped forms rather than one long page. A tab that carries
+ * `content` instead renders the node as-is. Both are optional, so a caller can
+ * mix forms and read-only views in one screen.
+ */
+export function SettingsPage({ shell, header, tabs, defaultValue, value, onValueChange, }) {
+    return (_jsx(AppShell01, { ...shell, children: _jsxs("div", { className: "mx-auto flex w-full max-w-page flex-col gap-8", children: [_jsx(PageHeader01, { ...header, headingLevel: header.headingLevel ?? 'h1' }), _jsxs(Tabs, { defaultValue: defaultValue ?? tabs[0]?.value, value: value, onValueChange: onValueChange, children: [_jsx(TabsList, { children: tabs.map((tab) => (_jsx(TabsTrigger, { value: tab.value, children: tab.label }, tab.value))) }), tabs.map((tab) => (_jsx(TabsContent, { value: tab.value, children: tab.panel ? _jsx(SettingsPanel01, { ...tab.panel }) : tab.content }, tab.value)))] })] }) }));
+}
+export default SettingsPage;

package/dist/provider/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Prism provider entry.
+ *
+ * `PrismProvider` and `usePrismTheme` are the optional programmatic path;
+ * `PrismThemeScript` is the optional pre-hydration script. The declarative
+ * `data-pack` and `.dark` attributes are the default and need none of this.
+ */
+export { PrismProvider, usePrismTheme } from './provider';
+export type { PrismProviderProps, PrismTheme } from './provider';
+export { PrismThemeScript } from './theme-script';
+export type { PrismThemeScriptProps } from './theme-script';
+//# sourceMappingURL=index.d.ts.map

package/dist/provider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACzD,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/provider/index.js

@@ -0,0 +1,9 @@
+/**
+ * The Prism provider entry.
+ *
+ * `PrismProvider` and `usePrismTheme` are the optional programmatic path;
+ * `PrismThemeScript` is the optional pre-hydration script. The declarative
+ * `data-pack` and `.dark` attributes are the default and need none of this.
+ */
+export { PrismProvider, usePrismTheme } from './provider';
+export { PrismThemeScript } from './theme-script';

package/dist/provider/provider.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The optional client runtime for programmatic theme switching.
+ *
+ * The provider is strictly additive: a consumer who puts `data-pack` and
+ * `.dark` on `<html>` never needs it, and a consumer who wants no client
+ * JavaScript omits it. It carries the pack and mode through context and writes
+ * the same two markup attributes the declarative form uses. There is no
+ * override, merge, token, className or style prop: the provider's only outputs
+ * are the document-element attributes and context (ticket 07).
+ *
+ * It resolves through `resolveTheme`, the one rule the boot script also
+ * implements, and it never writes `THEME_ORIGIN_ATTRIBUTE`: the script is that
+ * attribute's only writer, and two writers would turn a record of the origin
+ * into a race.
+ */
+import { type ReactNode } from 'react';
+import { type Mode, type PackId } from '../theming';
+export type PrismTheme = {
+    pack: PackId;
+    mode: Mode;
+    setPack: (pack: PackId) => void;
+    setMode: (mode: Mode) => void;
+    toggleMode: () => void;
+};
+export type PrismProviderProps = {
+    /** Pack used when nothing is stored and no pack attribute is present. */
+    defaultPack?: PackId;
+    /** Mode used in the same fallback. */
+    defaultMode?: Mode;
+    /** localStorage key for the persisted `{ pack, mode }` object. */
+    storageKey?: string;
+    children?: ReactNode;
+};
+export declare function PrismProvider({ defaultPack, defaultMode, storageKey, children, }: PrismProviderProps): import("react").JSX.Element;
+/**
+ * Reads and mutates the active pack and mode.
+ *
+ * Throws outside a `PrismProvider`. The provider is optional, so a consumer
+ * that does not mount it simply does not call this hook.
+ */
+export declare function usePrismTheme(): PrismTheme;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/provider/provider.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAEd,OAAO,EAML,KAAK,IAAI,EACT,KAAK,MAAM,EAEZ,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;IACV,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IAC7B,UAAU,EAAE,MAAM,IAAI,CAAA;CACvB,CAAA;AAID,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sCAAsC;IACtC,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAyCD,wBAAgB,aAAa,CAAC,EAC5B,WAAuB,EACvB,WAAqB,EACrB,UAAgC,EAChC,QAAQ,GACT,EAAE,kBAAkB,+BAuHpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAM1C"}

package/dist/provider/provider.js

@@ -0,0 +1,178 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The optional client runtime for programmatic theme switching.
+ *
+ * The provider is strictly additive: a consumer who puts `data-pack` and
+ * `.dark` on `<html>` never needs it, and a consumer who wants no client
+ * JavaScript omits it. It carries the pack and mode through context and writes
+ * the same two markup attributes the declarative form uses. There is no
+ * override, merge, token, className or style prop: the provider's only outputs
+ * are the document-element attributes and context (ticket 07).
+ *
+ * It resolves through `resolveTheme`, the one rule the boot script also
+ * implements, and it never writes `THEME_ORIGIN_ATTRIBUTE`: the script is that
+ * attribute's only writer, and two writers would turn a record of the origin
+ * into a race.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { DEFAULT_STORAGE_KEY, PACK_ATTRIBUTE, readLegacyMode, resolveTheme, themeAttributes, } from '../theming';
+const PrismThemeContext = createContext(null);
+function applyDocumentAttributes(pack, mode) {
+    const root = document.documentElement;
+    const { 'data-pack': packAttribute, className } = themeAttributes({ pack, mode });
+    if (packAttribute)
+        root.setAttribute(PACK_ATTRIBUTE, packAttribute);
+    else
+        root.removeAttribute(PACK_ATTRIBUTE);
+    if (className)
+        root.classList.add('dark');
+    else
+        root.classList.remove('dark');
+}
+/** One guarded read. A blocked or full store must not break the page. */
+function read(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/** One guarded write. The attributes are already applied when this fails. */
+function persist(key, pack, mode) {
+    try {
+        localStorage.setItem(key, JSON.stringify({ pack, mode }));
+    }
+    catch {
+        // A blocked or full localStorage must not break theme switching. The
+        // attributes are already applied, so the visible behaviour is unchanged.
+    }
+}
+function retire(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch {
+        // Nothing to do: a key that cannot be removed is read again next load,
+        // recovers the same decision, and writes the same pair.
+    }
+}
+export function PrismProvider({ defaultPack = 'default', defaultMode = 'light', storageKey = DEFAULT_STORAGE_KEY, children, }) {
+    /*
+     * The resolution, and whether a decision has been made. Two pieces of state
+     * for two different questions, which is why the old `resolved` flag was not
+     * enough on its own:
+     *
+     *   - `theme` is null until the store has been read. It gates APPLY, because
+     *     applying the default over a server-rendered pack before resolution is
+     *     the flash the resolution order exists to prevent. It carries the
+     *     origin, so the recovery below can read it without a second lookup.
+     *   - `decided` is a ref, not state, because it must be readable by the write
+     *     effect without causing a render, and settable synchronously by a caller
+     *     whose state update has not been committed yet. It gates WRITE.
+     *
+     * A ref also cannot be re-rendered into an extra effect pass, which is what
+     * would have made the write fire once for the flag and once for the value.
+     */
+    const [theme, setTheme] = useState(null);
+    const decided = useRef(false);
+    /*
+     * Resolution on mount, through the one shared rule: the stored value, then a
+     * key this line no longer writes, then what the server rendered, then the
+     * defaults. A server-rendered pack therefore survives hydration.
+     */
+    useEffect(() => {
+        const recovered = readLegacyMode(read);
+        const next = resolveTheme({
+            stored: read(storageKey),
+            legacy: recovered?.mode ?? null,
+            documentPack: document.documentElement.getAttribute(PACK_ATTRIBUTE),
+            documentDark: document.documentElement.classList.contains('dark'),
+            defaultPack,
+            defaultMode,
+        });
+        if (next.origin === 'legacy' && recovered) {
+            /*
+             * The recovery write. A decision taken from a key this line no longer
+             * writes is put in the key it does write, and the old key is retired in
+             * the same breath, which is what makes the clause self-disabling: the
+             * next load finds nothing to recover, so a reader is migrated once and
+             * the population the clause can still reach only ever shrinks.
+             */
+            persist(storageKey, next.pack, next.mode);
+            retire(recovered.key);
+        }
+        // A caller that decided in a layout effect before this ran keeps its value.
+        if (!decided.current)
+            setTheme(next);
+    }, [storageKey, defaultPack, defaultMode]);
+    /*
+     * Apply always, once there is a resolution; persist only on a decision.
+     *
+     * The first resolution from the document or the defaults writes nothing, so a
+     * visitor who never touched the toggle ends the load with an empty store and
+     * a site that changes its default reaches everyone who has not chosen.
+     */
+    useEffect(() => {
+        if (!theme)
+            return;
+        applyDocumentAttributes(theme.pack, theme.mode);
+        if (decided.current)
+            persist(storageKey, theme.pack, theme.mode);
+    }, [theme, storageKey]);
+    const setPack = useCallback((next) => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: next,
+            mode: current?.mode ?? defaultMode,
+            origin: 'stored',
+        }));
+    }, [defaultMode]);
+    const setMode = useCallback((next) => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: current?.pack ?? defaultPack,
+            mode: next,
+            origin: 'stored',
+        }));
+    }, [defaultPack]);
+    /*
+     * The pair is a closed union of two members, so the other one is the other
+     * member. Spelling it out costs nothing and does not hide the coupling behind
+     * an index into a list this file does not otherwise need.
+     *
+     * The three setters all fall back to the consumer's own default rather than
+     * to the neutral one, so a decision taken before the store has been read
+     * pairs the chosen axis with the site's default and not with a guess.
+     */
+    const toggleMode = useCallback(() => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: current?.pack ?? defaultPack,
+            mode: current?.mode === 'dark' ? 'light' : 'dark',
+            origin: 'stored',
+        }));
+    }, [defaultPack]);
+    const value = useMemo(() => ({
+        pack: theme?.pack ?? defaultPack,
+        mode: theme?.mode ?? defaultMode,
+        setPack,
+        setMode,
+        toggleMode,
+    }), [theme, defaultPack, defaultMode, setPack, setMode, toggleMode]);
+    return _jsx(PrismThemeContext.Provider, { value: value, children: children });
+}
+/**
+ * Reads and mutates the active pack and mode.
+ *
+ * Throws outside a `PrismProvider`. The provider is optional, so a consumer
+ * that does not mount it simply does not call this hook.
+ */
+export function usePrismTheme() {
+    const value = useContext(PrismThemeContext);
+    if (!value) {
+        throw new Error('usePrismTheme must be used within a PrismProvider');
+    }
+    return value;
+}

package/dist/provider/theme-script.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The optional pre-hydration theme script.
+ *
+ * A Server Component that renders one blocking script. Placed in `<head>`, it
+ * applies the stored pack and mode before React hydrates, so the first paint is
+ * already correct. It is safe to omit; a consumer who renders the attributes on
+ * `<html>` needs no client runtime at all.
+ *
+ * It is the only writer of `THEME_ORIGIN_ATTRIBUTE`, and it writes that
+ * attribute on every path it reaches, so the origin of the active theme is
+ * always readable and never merely absent.
+ *
+ * The string below is a second implementation of `resolveTheme`, not a copy of
+ * it that has been kept in step. A function cannot be shared with a string that
+ * a minifier rewrites: a renamed identifier inside the script's own `try` throws
+ * there, the catch swallows it, and the theme silently stops applying on every
+ * page. So the string implements the rule and
+ * `scripts/check-theme-resolution.mjs` runs BOTH over one table of stored
+ * values, which is the only thing that can hold them together.
+ *
+ * Its price is a separate ceiling, `scripts/check-boot-budget.mjs`, because this
+ * string runs before paint on every page and adding it to a table of component
+ * bundle sizes would corrupt the unit that table exists to measure.
+ */
+import { type Mode, type PackId } from '../theming';
+/**
+ * The first half of the storage-migration clause: read one key this line no
+ * longer writes.
+ *
+ * Exported because `check-boot-budget.mjs` prices the clause rather than
+ * guessing at it. The emitted string contains this fragment verbatim, so its
+ * byte count is the clause's cost and not an estimate of it.
+ */
+export declare const THEME_MIGRATION_READ: string;
+/**
+ * The second half: the clause retires itself.
+ *
+ * The recovery is the only write this string performs, and it writes the
+ * recovered pair into the key this line does write and removes the key it came
+ * from, in one guarded step. That is the clause's expiry by rule rather than by
+ * number: it fires only while a retired key still holds a mode, it fires at
+ * most once per reader because its own write is what makes the second load find
+ * nothing, and it is retired for good by deleting the last entry of
+ * `LEGACY_MODE_STORAGE_KEYS`. There is no date and no version constant in it,
+ * and the gate reports how many keys are still live so the number is visible
+ * rather than remembered.
+ */
+export declare const THEME_MIGRATION_RETIRE = "if(G===\"legacy\"){try{localStorage.setItem(K,JSON.stringify({pack:pack,mode:m}));localStorage.removeItem(LK);}catch(e){}}";
+export type PrismThemeScriptProps = {
+    storageKey?: string;
+    defaultPack?: PackId;
+    defaultMode?: Mode;
+};
+export declare function PrismThemeScript({ storageKey, defaultPack, defaultMode, }: PrismThemeScriptProps): import("react").JSX.Element;
+//# sourceMappingURL=theme-script.d.ts.map

package/dist/provider/theme-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-script.d.ts","sourceRoot":"","sources":["../../src/provider/theme-script.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAOL,KAAK,IAAI,EACT,KAAK,MAAM,EACZ,MAAM,YAAY,CAAA;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAEvB,CAAA;AAEV;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,+HACyF,CAAA;AAE5H,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,IAAI,CAAA;CACnB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,UAAgC,EAChC,WAAuB,EACvB,WAAqB,GACtB,EAAE,qBAAqB,+BA+BvB"}

package/dist/provider/theme-script.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The optional pre-hydration theme script.
+ *
+ * A Server Component that renders one blocking script. Placed in `<head>`, it
+ * applies the stored pack and mode before React hydrates, so the first paint is
+ * already correct. It is safe to omit; a consumer who renders the attributes on
+ * `<html>` needs no client runtime at all.
+ *
+ * It is the only writer of `THEME_ORIGIN_ATTRIBUTE`, and it writes that
+ * attribute on every path it reaches, so the origin of the active theme is
+ * always readable and never merely absent.
+ *
+ * The string below is a second implementation of `resolveTheme`, not a copy of
+ * it that has been kept in step. A function cannot be shared with a string that
+ * a minifier rewrites: a renamed identifier inside the script's own `try` throws
+ * there, the catch swallows it, and the theme silently stops applying on every
+ * page. So the string implements the rule and
+ * `scripts/check-theme-resolution.mjs` runs BOTH over one table of stored
+ * values, which is the only thing that can hold them together.
+ *
+ * Its price is a separate ceiling, `scripts/check-boot-budget.mjs`, because this
+ * string runs before paint on every page and adding it to a table of component
+ * bundle sizes would corrupt the unit that table exists to measure.
+ */
+import { DEFAULT_STORAGE_KEY, LEGACY_MODE_STORAGE_KEYS, MODES, PACKS, PACK_ATTRIBUTE, THEME_ORIGIN_ATTRIBUTE, } from '../theming';
+/**
+ * The first half of the storage-migration clause: read one key this line no
+ * longer writes.
+ *
+ * Exported because `check-boot-budget.mjs` prices the clause rather than
+ * guessing at it. The emitted string contains this fragment verbatim, so its
+ * byte count is the clause's cost and not an estimate of it.
+ */
+export const THEME_MIGRATION_READ = LEGACY_MODE_STORAGE_KEYS.map((key) => `try{var g=localStorage.getItem(${JSON.stringify(key)});if(M.indexOf(g)>-1){L=g;LK=${JSON.stringify(key)};}}catch(e){}`).join('');
+/**
+ * The second half: the clause retires itself.
+ *
+ * The recovery is the only write this string performs, and it writes the
+ * recovered pair into the key this line does write and removes the key it came
+ * from, in one guarded step. That is the clause's expiry by rule rather than by
+ * number: it fires only while a retired key still holds a mode, it fires at
+ * most once per reader because its own write is what makes the second load find
+ * nothing, and it is retired for good by deleting the last entry of
+ * `LEGACY_MODE_STORAGE_KEYS`. There is no date and no version constant in it,
+ * and the gate reports how many keys are still live so the number is visible
+ * rather than remembered.
+ */
+export const THEME_MIGRATION_RETIRE = 'if(G==="legacy"){try{localStorage.setItem(K,JSON.stringify({pack:pack,mode:m}));localStorage.removeItem(LK);}catch(e){}}';
+export function PrismThemeScript({ storageKey = DEFAULT_STORAGE_KEY, defaultPack = 'default', defaultMode = 'light', }) {
+    const script = '(function(){try{' +
+        'var r=document.documentElement,' +
+        `P=${JSON.stringify(PACKS)},` +
+        `M=${JSON.stringify(MODES)},` +
+        `K=${JSON.stringify(storageKey)},` +
+        `A=${JSON.stringify(PACK_ATTRIBUTE)},` +
+        `O=${JSON.stringify(THEME_ORIGIN_ATTRIBUTE)},` +
+        `DP=${JSON.stringify(defaultPack)},` +
+        `DM=${JSON.stringify(defaultMode)},` +
+        'L=null,LK=null,S=null,T=null;' +
+        'try{var t=localStorage.getItem(K);if(t){T=t;S=JSON.parse(t);}}catch(e){}' +
+        THEME_MIGRATION_READ +
+        'var a=r.getAttribute(A),' +
+        'DPK=P.indexOf(a)>-1?a:null,' +
+        'DK=r.classList.contains("dark")?"dark":null,' +
+        'U=S&&typeof S=="object"&&P.indexOf(S.pack)>-1&&M.indexOf(S.mode)>-1,' +
+        'pack,m,G;' +
+        'if(U){pack=S.pack;m=S.mode;G="stored";}' +
+        'else if(T){pack=DPK||DP;m=DK||DM;G="unparsed";}' +
+        'else if(L){pack=DP;m=L;G="legacy";}' +
+        'else if(DPK||DK){pack=DPK||DP;m=DK||DM;G="document";}' +
+        'else{pack=DP;m=DM;G="default";}' +
+        THEME_MIGRATION_RETIRE +
+        'if(pack!=="default"){r.setAttribute(A,pack);}else{r.removeAttribute(A);}' +
+        'r.classList.toggle("dark",m==="dark");' +
+        'r.setAttribute(O,G);' +
+        '}catch(e){}})();';
+    return _jsx("script", { dangerouslySetInnerHTML: { __html: script } });
+}