@hadoku/themes 0.0.0-stage → 5.12.16

package/dist/index.js

@@ -0,0 +1,169 @@
+/**
+ * Hadoku Theme System - Utilities
+ * Framework-agnostic theme management for Hadoku themes
+ * 18 beautiful themes across 9 theme families with light/dark variants
+ * Now with React integration support!
+ */
+export const THEMES = [
+    'light',
+    'dark',
+    'coffee-light',
+    'coffee-dark',
+    'nature-light',
+    'nature-dark',
+    'lavender-light',
+    'lavender-dark',
+    'strawberry-light',
+    'strawberry-dark',
+    'ocean-light',
+    'ocean-dark',
+    'cyberpunk-light',
+    'cyberpunk-dark',
+    'pink-light',
+    'pink-dark',
+    'izakaya-light',
+    'izakaya-dark'
+];
+/** Read the theme key from one storage, tolerating environments where the
+ *  storage object exists but throws on access (private mode, blocked cookies).
+ *  Returns null rather than throwing, so a blocked storage degrades to the
+ *  browser-preference fallback instead of breaking theme load entirely. */
+function readStored(which) {
+    try {
+        return window[which].getItem('hadoku-theme');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Set the active theme
+ * @param theme - Theme name
+ */
+export function setTheme(theme) {
+    if (theme === 'light') {
+        document.documentElement.removeAttribute('data-theme');
+    }
+    else {
+        document.documentElement.setAttribute('data-theme', theme);
+    }
+}
+/**
+ * Get the currently active theme
+ * @returns Current theme name
+ */
+export function getTheme() {
+    const attr = document.documentElement.getAttribute('data-theme');
+    return attr || 'light';
+}
+/**
+ * Persist the theme and apply it.
+ *
+ * BOTH storages, deliberately. sessionStorage is what the pre-paint inline
+ * `<head>` script reads within a tab, but it dies with the tab — so writing
+ * only there meant a browser restart came back with nothing persisted, the
+ * script fell through to the browser preference, and the app then swapped to
+ * the real theme once React mounted. A visible default-then-swap flash, and
+ * "my theme reset itself" for anyone whose theme wasn't the system default.
+ * localStorage is what survives, so it is what makes the next cold load paint
+ * correctly the first time.
+ */
+export function saveTheme(theme) {
+    try {
+        localStorage.setItem('hadoku-theme', theme);
+        sessionStorage.setItem('hadoku-theme', theme);
+    }
+    catch {
+        /* storage unavailable (private mode, blocked cookies) — the theme still
+           applies for this page, it just won't survive the navigation. */
+    }
+    setTheme(theme);
+}
+/**
+ * Load the saved theme.
+ * @returns Saved theme, or browser preference, or 'light' if none available
+ */
+export function loadTheme() {
+    // sessionStorage first — within a tab it is the freshest value (the FOUC
+    // script and same-tab writes both go there). localStorage is the fallback
+    // that carries a theme across a browser restart.
+    const saved = (readStored('sessionStorage') ?? readStored('localStorage'));
+    if (saved && THEMES.includes(saved)) {
+        setTheme(saved);
+        return saved;
+    }
+    // If no saved theme, respect browser's color scheme preference
+    if (typeof window !== 'undefined' && window.matchMedia) {
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        const browserTheme = prefersDark ? 'dark' : 'light';
+        setTheme(browserTheme);
+        return browserTheme;
+    }
+    // Final fallback to light
+    return 'light';
+}
+/**
+ * Initialize theme system on page load
+ * Loads saved theme, respects browser preference, or defaults to light
+ */
+export function initTheme() {
+    return loadTheme();
+}
+/**
+ * Clear saved theme (reset to light)
+ */
+export function clearTheme() {
+    // Both, to match saveTheme — clearing only sessionStorage left the
+    // localStorage copy to resurrect the theme on the next cold load.
+    try {
+        sessionStorage.removeItem('hadoku-theme');
+        localStorage.removeItem('hadoku-theme');
+    }
+    catch {
+        /* storage unavailable — nothing was persisted to clear */
+    }
+    setTheme('light');
+}
+/**
+ * Set the active theme mode (writes data-theme-mode on documentElement).
+ * 'advanced' renders the gradient + effects; 'simple' uses flat colors.
+ *
+ * Nothing calls this with 'advanced' any more: the Simple/Advanced toggle was
+ * removed from the picker, and `useTheme` pins the attribute to 'simple' on
+ * every theme apply. The mode is not persisted or read back for the same
+ * reason — there is no user choice left to remember. The advanced kit itself
+ * (advanced.css, THEME_EFFECTS, the hdk-advanced-* class hooks) is untouched
+ * and still keys off this attribute, so bringing advanced back means restoring
+ * the toggle, not rebuilding the visuals.
+ */
+export function setThemeMode(mode) {
+    document.documentElement.setAttribute('data-theme-mode', mode);
+}
+// Theme metadata and React integration (optional peer dependencies)
+export { THEME_FAMILIES, THEME_ICON_MAP } from './metadata.js';
+export { useTheme } from './useTheme.js';
+// The one thing a child app mounts, and the context it fills — deliberately in
+// the same package now (see HadokuThemeRoot.tsx).
+export { HadokuThemeRoot } from './HadokuThemeRoot.js';
+export { HadokuThemeProvider, useHadokuTheme, useHadokuThemeOptional } from './themeContext.js';
+// Theme-family icons — moved here from task-ui-components so this package
+// depends on nothing of ours.
+export { SunIcon, MoonIcon, StrawberryIcon, WaveIcon, ZapIcon, CoffeeIcon, FlowerIcon, HeartIcon, LeafIcon, LanternIcon } from './ThemeIcons.js';
+// Canonical theme prefs client — was copy-pasted into every child app.
+export { themePrefs, ThemePrefsSchema } from './themePrefs.js';
+// Shared by every prefs client in the ecosystem, so a dev/E2E stack can point
+// them all at a local prefs-api with one global instead of mocking the network.
+export { resolvePrefsApiBase, PREFS_API_BASE_GLOBAL } from './prefsApiBase.js';
+export { THEME_EFFECTS, hasAdvanced, getThemeEffects } from './effects.js';
+// Icon module — the enforced ecosystem icon set. Artwork is vendored from lucide
+// (ISC, see LICENSE-lucide) and generated into src/icons/registry.generated.ts, so
+// this package still ships with zero runtime dependencies and serves the Astro/Qwik
+// consumers that have no React at all.
+export { Icon } from './icons/Icon.js';
+export { ICON_MARKUP, ICON_NAMES, ICON_SOURCE_SLUGS, ICON_FAMILIES, LUCIDE_VERSION, getIconSvg, getIconTileClass, isIconName } from './icons/index.js';
+// Platform context — one device definition for the fleet, replacing six
+// hand-rolled `useIsMobile` implementations with four different thresholds.
+// Framework-free half is also published at `@wolffm/themes/platform` for the
+// plain-TS consumers, exactly as the icon module is.
+export { detectPlatform, createPlatform, stampPlatform, isSamePlatform, NARROW_BREAKPOINT, NARROW_QUERY, TOUCH_FIRST_QUERY } from './platform/index.js';
+export { usePlatform } from './platform/usePlatform.js';

package/dist/metadata.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Theme metadata - icon mappings and theme family configurations
+ * Icons and the ThemeFamily type are local to this package (see ThemeIcons.tsx).
+ */
+import React from 'react';
+import type { ThemeFamily } from './theme-types';
+/**
+ * Theme families configuration for all 9 theme pairs
+ * Each family has a light and dark variant with corresponding icons
+ */
+export declare const THEME_FAMILIES: ThemeFamily[];
+/**
+ * Theme icon mapping - maps each theme name to its icon component
+ * Useful for getting the icon for a specific theme
+ */
+export declare const THEME_ICON_MAP: {
+    readonly light: () => React.JSX.Element;
+    readonly dark: () => React.JSX.Element;
+    readonly 'strawberry-light': () => React.JSX.Element;
+    readonly 'strawberry-dark': () => React.JSX.Element;
+    readonly 'ocean-light': () => React.JSX.Element;
+    readonly 'ocean-dark': () => React.JSX.Element;
+    readonly 'cyberpunk-light': () => React.JSX.Element;
+    readonly 'cyberpunk-dark': () => React.JSX.Element;
+    readonly 'coffee-light': () => React.JSX.Element;
+    readonly 'coffee-dark': () => React.JSX.Element;
+    readonly 'lavender-light': () => React.JSX.Element;
+    readonly 'lavender-dark': () => React.JSX.Element;
+    readonly 'nature-light': () => React.JSX.Element;
+    readonly 'nature-dark': () => React.JSX.Element;
+    readonly 'pink-light': () => React.JSX.Element;
+    readonly 'pink-dark': () => React.JSX.Element;
+    readonly 'izakaya-light': () => React.JSX.Element;
+    readonly 'izakaya-dark': () => React.JSX.Element;
+};

package/dist/metadata.js

@@ -0,0 +1,108 @@
+/**
+ * Theme metadata - icon mappings and theme family configurations
+ * Icons and the ThemeFamily type are local to this package (see ThemeIcons.tsx).
+ */
+import React from 'react';
+import { SunIcon, MoonIcon, StrawberryIcon, WaveIcon, ZapIcon, CoffeeIcon, FlowerIcon, HeartIcon, LeafIcon, LanternIcon } from './ThemeIcons.js';
+/**
+ * Theme families configuration for all 9 theme pairs
+ * Each family has a light and dark variant with corresponding icons
+ */
+export const THEME_FAMILIES = [
+    {
+        lightTheme: 'light',
+        darkTheme: 'dark',
+        lightLabel: 'Sun',
+        darkLabel: 'Night',
+        lightIcon: React.createElement(SunIcon, null),
+        darkIcon: React.createElement(MoonIcon, null)
+    },
+    {
+        lightTheme: 'strawberry-light',
+        darkTheme: 'strawberry-dark',
+        lightLabel: 'Vine Light',
+        darkLabel: 'Vine Dark',
+        lightIcon: React.createElement(StrawberryIcon, null),
+        darkIcon: React.createElement(StrawberryIcon, null)
+    },
+    {
+        lightTheme: 'ocean-light',
+        darkTheme: 'ocean-dark',
+        lightLabel: 'Ocean Light',
+        darkLabel: 'Ocean Dark',
+        lightIcon: React.createElement(WaveIcon, null),
+        darkIcon: React.createElement(WaveIcon, null)
+    },
+    {
+        lightTheme: 'cyberpunk-light',
+        darkTheme: 'cyberpunk-dark',
+        lightLabel: 'Neon Light',
+        darkLabel: 'Neon Dark',
+        lightIcon: React.createElement(ZapIcon, null),
+        darkIcon: React.createElement(ZapIcon, null)
+    },
+    {
+        lightTheme: 'coffee-light',
+        darkTheme: 'coffee-dark',
+        lightLabel: 'Coffee Light',
+        darkLabel: 'Coffee Dark',
+        lightIcon: React.createElement(CoffeeIcon, null),
+        darkIcon: React.createElement(CoffeeIcon, null)
+    },
+    {
+        lightTheme: 'lavender-light',
+        darkTheme: 'lavender-dark',
+        lightLabel: 'Lavender Light',
+        darkLabel: 'Lavender Dark',
+        lightIcon: React.createElement(FlowerIcon, null),
+        darkIcon: React.createElement(FlowerIcon, null)
+    },
+    {
+        lightTheme: 'nature-light',
+        darkTheme: 'nature-dark',
+        lightLabel: 'Nature Light',
+        darkLabel: 'Nature Dark',
+        lightIcon: React.createElement(LeafIcon, null),
+        darkIcon: React.createElement(LeafIcon, null)
+    },
+    {
+        lightTheme: 'pink-light',
+        darkTheme: 'pink-dark',
+        lightLabel: 'Pink Light',
+        darkLabel: 'Pink Dark',
+        lightIcon: React.createElement(HeartIcon, null),
+        darkIcon: React.createElement(HeartIcon, null)
+    },
+    {
+        lightTheme: 'izakaya-light',
+        darkTheme: 'izakaya-dark',
+        lightLabel: 'Izakaya Light',
+        darkLabel: 'Izakaya Dark',
+        lightIcon: React.createElement(LanternIcon, null),
+        darkIcon: React.createElement(LanternIcon, null)
+    }
+];
+/**
+ * Theme icon mapping - maps each theme name to its icon component
+ * Useful for getting the icon for a specific theme
+ */
+export const THEME_ICON_MAP = {
+    light: SunIcon,
+    dark: MoonIcon,
+    'strawberry-light': StrawberryIcon,
+    'strawberry-dark': StrawberryIcon,
+    'ocean-light': WaveIcon,
+    'ocean-dark': WaveIcon,
+    'cyberpunk-light': ZapIcon,
+    'cyberpunk-dark': ZapIcon,
+    'coffee-light': CoffeeIcon,
+    'coffee-dark': CoffeeIcon,
+    'lavender-light': FlowerIcon,
+    'lavender-dark': FlowerIcon,
+    'nature-light': LeafIcon,
+    'nature-dark': LeafIcon,
+    'pink-light': HeartIcon,
+    'pink-dark': HeartIcon,
+    'izakaya-light': LanternIcon,
+    'izakaya-dark': LanternIcon
+};

package/dist/platform/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Platform context — the one device-detection module for the hadoku ecosystem.
+ *
+ * WHAT THIS REPLACES
+ * ------------------
+ * Six independent implementations across the fleet, using four different
+ * thresholds (768, 820, 900, 1000) to answer three different questions.
+ * `hadoku-task` asked about viewport WIDTH and `hadoku-dataplatform` about
+ * POINTER TYPE — the same "am I on mobile?" question, answered two ways, and
+ * neither app could tell you which one it meant from the name `useIsMobile`.
+ * Those two are what this replaces.
+ *
+ * (The other three turned out on inspection to be component CAPACITY
+ * thresholds, each already agreeing with its own stylesheet — pygmalion's 900
+ * is "room for three panes", merchant's 1000 is "room for a second column".
+ * Those are legitimately local and are NOT candidates for this module. An
+ * earlier draft catalogued them as drift; that was a bad read.)
+ *
+ * The failure this DOES fix is the same one as the eight hand-copied
+ * `useTheme.ts` files this package already absorbed — see the header of
+ * ../useTheme.tsx — so it gets the same fix: one definition here, a seed passed
+ * down by the host on mount, and a shared hook that owns the live value.
+ *
+ * TWO FLAGS, NOT ONE
+ * ------------------
+ * `touchFirst` and `narrow` are different questions and a single boolean makes
+ * one caller wrong: a phone in landscape is touch-first but not narrow, and a
+ * narrow desktop window is narrow but not touch-first. There is deliberately no
+ * `isMobile` convenience OR — it would become the default reach and put the
+ * fleet back on one blessed threshold under a new name.
+ *
+ * This module is framework-free (no React import) so plain-TS consumers like
+ * hadoku-merchant can use it. The React hook lives in ./usePlatform.
+ */
+export interface PlatformSeed {
+    /**
+     * Input is finger-first: `(pointer: coarse) and (hover: none)`.
+     *
+     * True on phones and tablets. False on desktops — INCLUDING touchscreen
+     * laptops, whose primary pointer is still a mouse. Keys off the primary
+     * INPUT rather than the user-agent string (UAs lie; iPadOS reports a desktop
+     * UA) or viewport width (a narrow desktop window is not a phone).
+     *
+     * Use for: tap targets, hover affordances, gesture vs. drag, control overlays.
+     */
+    touchFirst: boolean;
+    /**
+     * Viewport is narrow: `(max-width: 767px)`.
+     *
+     * Use for: column counts, stacking, lane caps, drawer-vs-pane.
+     */
+    narrow: boolean;
+}
+/** The width below which `narrow` is true. 767px is the boundary; this is the
+ *  Tailwind-style `md` breakpoint the fleet already uses most (hadoku_site
+ *  alone carries 67 `max-width: 768px` rules). */
+export declare const NARROW_BREAKPOINT = 768;
+export declare const TOUCH_FIRST_QUERY = "(pointer: coarse) and (hover: none)";
+export declare const NARROW_QUERY = "(max-width: 767px)";
+/**
+ * Read the platform straight from the media queries.
+ *
+ * Both flags come from `matchMedia`, deliberately: `hadoku-task`'s hook seeded
+ * from `window.innerWidth < 768` and then listened on `(max-width: 767px)` —
+ * two mechanisms for one boundary. They disagree under fractional zoom, and
+ * `innerWidth` reads stale during iOS `orientationchange`, which is exactly the
+ * rotation case the listener exists to catch.
+ */
+export declare function detectPlatform(): PlatformSeed;
+export declare function isSamePlatform(a: PlatformSeed, b: PlatformSeed): boolean;
+/**
+ * Mirror the flags onto an element as `data-touch-first` / `data-narrow`, so
+ * CSS keys off the IDENTICAL source the JS does.
+ *
+ * A stylesheet writing `[data-narrow] .lane { … }` cannot drift from the hook,
+ * because there is only one query left to keep in step. `hadoku-dataplatform`
+ * already did exactly this for itself with an `is-mobile` class it set from the
+ * same value it branched on — this is that idea with one fleet-wide name.
+ * Present/absent rather than `="true"`/`="false"` so the plain attribute
+ * selector works.
+ */
+export declare function stampPlatform(el: Element | null | undefined, platform: PlatformSeed): void;
+export interface PlatformStore {
+    get(): PlatformSeed;
+    /** Fires on every real change. Returns the unsubscribe. */
+    subscribe(listener: (platform: PlatformSeed) => void): () => void;
+}
+/**
+ * Framework-free equivalent of `usePlatform`, for consumers with no React
+ * (hadoku-merchant is plain TS). Attaches its listeners on the first
+ * `subscribe` and detaches when the last one unsubscribes, so an unused store
+ * costs nothing.
+ */
+export declare function createPlatform(): PlatformStore;

package/dist/platform/index.js

@@ -0,0 +1,149 @@
+/**
+ * Platform context — the one device-detection module for the hadoku ecosystem.
+ *
+ * WHAT THIS REPLACES
+ * ------------------
+ * Six independent implementations across the fleet, using four different
+ * thresholds (768, 820, 900, 1000) to answer three different questions.
+ * `hadoku-task` asked about viewport WIDTH and `hadoku-dataplatform` about
+ * POINTER TYPE — the same "am I on mobile?" question, answered two ways, and
+ * neither app could tell you which one it meant from the name `useIsMobile`.
+ * Those two are what this replaces.
+ *
+ * (The other three turned out on inspection to be component CAPACITY
+ * thresholds, each already agreeing with its own stylesheet — pygmalion's 900
+ * is "room for three panes", merchant's 1000 is "room for a second column".
+ * Those are legitimately local and are NOT candidates for this module. An
+ * earlier draft catalogued them as drift; that was a bad read.)
+ *
+ * The failure this DOES fix is the same one as the eight hand-copied
+ * `useTheme.ts` files this package already absorbed — see the header of
+ * ../useTheme.tsx — so it gets the same fix: one definition here, a seed passed
+ * down by the host on mount, and a shared hook that owns the live value.
+ *
+ * TWO FLAGS, NOT ONE
+ * ------------------
+ * `touchFirst` and `narrow` are different questions and a single boolean makes
+ * one caller wrong: a phone in landscape is touch-first but not narrow, and a
+ * narrow desktop window is narrow but not touch-first. There is deliberately no
+ * `isMobile` convenience OR — it would become the default reach and put the
+ * fleet back on one blessed threshold under a new name.
+ *
+ * This module is framework-free (no React import) so plain-TS consumers like
+ * hadoku-merchant can use it. The React hook lives in ./usePlatform.
+ */
+/** The width below which `narrow` is true. 767px is the boundary; this is the
+ *  Tailwind-style `md` breakpoint the fleet already uses most (hadoku_site
+ *  alone carries 67 `max-width: 768px` rules). */
+export const NARROW_BREAKPOINT = 768;
+export const TOUCH_FIRST_QUERY = '(pointer: coarse) and (hover: none)';
+export const NARROW_QUERY = `(max-width: ${NARROW_BREAKPOINT - 1}px)`;
+/** SSG prerender and jsdom-without-a-polyfill both land here. Never throws;
+ *  all-false means "assume desktop", which is the safe default because every
+ *  consumer's desktop branch is the unconstrained one. */
+function unsupported() {
+    return typeof window === 'undefined' || !window.matchMedia;
+}
+/**
+ * Read the platform straight from the media queries.
+ *
+ * Both flags come from `matchMedia`, deliberately: `hadoku-task`'s hook seeded
+ * from `window.innerWidth < 768` and then listened on `(max-width: 767px)` —
+ * two mechanisms for one boundary. They disagree under fractional zoom, and
+ * `innerWidth` reads stale during iOS `orientationchange`, which is exactly the
+ * rotation case the listener exists to catch.
+ */
+export function detectPlatform() {
+    if (unsupported())
+        return { touchFirst: false, narrow: false };
+    return {
+        touchFirst: window.matchMedia(TOUCH_FIRST_QUERY).matches,
+        narrow: window.matchMedia(NARROW_QUERY).matches
+    };
+}
+export function isSamePlatform(a, b) {
+    return a.touchFirst === b.touchFirst && a.narrow === b.narrow;
+}
+/**
+ * Mirror the flags onto an element as `data-touch-first` / `data-narrow`, so
+ * CSS keys off the IDENTICAL source the JS does.
+ *
+ * A stylesheet writing `[data-narrow] .lane { … }` cannot drift from the hook,
+ * because there is only one query left to keep in step. `hadoku-dataplatform`
+ * already did exactly this for itself with an `is-mobile` class it set from the
+ * same value it branched on — this is that idea with one fleet-wide name.
+ * Present/absent rather than `="true"`/`="false"` so the plain attribute
+ * selector works.
+ */
+export function stampPlatform(el, platform) {
+    if (!el)
+        return;
+    for (const [attr, on] of [
+        ['data-touch-first', platform.touchFirst],
+        ['data-narrow', platform.narrow]
+    ]) {
+        if (on)
+            el.setAttribute(attr, '');
+        else
+            el.removeAttribute(attr);
+    }
+}
+/**
+ * Framework-free equivalent of `usePlatform`, for consumers with no React
+ * (hadoku-merchant is plain TS). Attaches its listeners on the first
+ * `subscribe` and detaches when the last one unsubscribes, so an unused store
+ * costs nothing.
+ */
+export function createPlatform() {
+    let current = detectPlatform();
+    const listeners = new Set();
+    let queries = [];
+    const sync = () => {
+        const next = detectPlatform();
+        if (isSamePlatform(current, next))
+            return;
+        current = next;
+        for (const listener of listeners)
+            listener(current);
+    };
+    const attach = () => {
+        if (unsupported())
+            return;
+        queries = [window.matchMedia(TOUCH_FIRST_QUERY), window.matchMedia(NARROW_QUERY)];
+        for (const mq of queries) {
+            // Safari < 14 only exposes the deprecated addListener signature.
+            if (mq.addEventListener)
+                mq.addEventListener('change', sync);
+            else
+                mq.addListener(sync);
+        }
+        // Resync: the queries may have changed between construction and the first
+        // subscribe, and that change fired before anything was listening.
+        sync();
+    };
+    const detach = () => {
+        for (const mq of queries) {
+            if (mq.removeEventListener)
+                mq.removeEventListener('change', sync);
+            else
+                mq.removeListener(sync);
+        }
+        queries = [];
+    };
+    return {
+        get: () => current,
+        subscribe(listener) {
+            // Add BEFORE attaching: `attach` ends with a repair `sync()`, and a
+            // listener registered after it would miss the very change that sync
+            // exists to surface.
+            listeners.add(listener);
+            if (listeners.size === 1)
+                attach();
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0)
+                    detach();
+            };
+        }
+    };
+}

package/dist/platform/usePlatform.d.ts

@@ -0,0 +1,29 @@
+/**
+ * usePlatform — the React half of the platform contract. See ./index.ts for why
+ * this exists and what it replaces.
+ *
+ * Shape deliberately mirrors `useTheme`: a seed passed down by the host on
+ * mount, and a hook that owns every value after that.
+ */
+import { type RefObject } from 'react';
+import { type PlatformSeed } from './index';
+export interface UsePlatformOptions {
+    /**
+     * Platform seeded by a parent shell, from its mount props.
+     *
+     * A SEED, not an override — unlike `UseThemeOptions.propsTheme`, which wins
+     * over everything. The host and the app are in the same document looking at
+     * the same viewport, so the host has no privileged knowledge here; the seed
+     * only saves the first render from a flash of the wrong layout. The media
+     * queries take over from the first effect onward, which is what keeps a
+     * rotation from being lost.
+     */
+    propsPlatform?: PlatformSeed;
+    /**
+     * Mirror `data-touch-first` / `data-narrow` onto a container element, so this
+     * app's CSS can key off the same source as its JS. Same escape hatch
+     * `useTheme` gives micro-frontend mounts via `containerRef`.
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+}
+export declare function usePlatform(options?: UsePlatformOptions): PlatformSeed;

package/dist/platform/usePlatform.js

@@ -0,0 +1,65 @@
+/**
+ * usePlatform — the React half of the platform contract. See ./index.ts for why
+ * this exists and what it replaces.
+ *
+ * Shape deliberately mirrors `useTheme`: a seed passed down by the host on
+ * mount, and a hook that owns every value after that.
+ */
+import { useState, useEffect, useRef } from 'react';
+import { detectPlatform, isSamePlatform, stampPlatform, TOUCH_FIRST_QUERY, NARROW_QUERY } from './index.js';
+import { useRefElement } from '../useRefElement.js';
+export function usePlatform(options = {}) {
+    const { propsPlatform, containerRef } = options;
+    // The seed governs the first render only. When there is no seed — a
+    // standalone mount, a Capacitor shell, an older host that predates the prop —
+    // this detects for itself, so there is no "missing prop" branch for an app
+    // author to get wrong.
+    const [platform, setPlatform] = useState(() => propsPlatform ?? detectPlatform());
+    useEffect(() => {
+        if (typeof window === 'undefined' || !window.matchMedia)
+            return;
+        const queries = [window.matchMedia(TOUCH_FIRST_QUERY), window.matchMedia(NARROW_QUERY)];
+        const sync = () => {
+            const next = detectPlatform();
+            // Returning the previous object bails out of the re-render, so the
+            // resync below is free when the seed was already right.
+            setPlatform(prev => (isSamePlatform(prev, next) ? prev : next));
+        };
+        for (const mq of queries) {
+            // Safari < 14 only exposes the deprecated addListener signature.
+            if (mq.addEventListener)
+                mq.addEventListener('change', sync);
+            else
+                mq.addListener(sync);
+        }
+        // Repair a stale seed. The host computes it at DOMContentLoaded and the
+        // bundle is then imported dynamically, so a rotation inside that window
+        // fires its `change` event before anything is listening — without this the
+        // app would stay on the wrong value until the NEXT change.
+        sync();
+        return () => {
+            for (const mq of queries) {
+                if (mq.removeEventListener)
+                    mq.removeEventListener('change', sync);
+                else
+                    mq.removeListener(sync);
+            }
+        };
+    }, []);
+    // Stamp on every change. No cleanup here on purpose — clearing and
+    // re-setting on every flip would churn the attribute for no reason.
+    // State, not the ref: the container can attach after the first stamp (#102).
+    const container = useRefElement(containerRef);
+    const stampedRef = useRef(null);
+    useEffect(() => {
+        stampedRef.current = container;
+        stampPlatform(container, platform);
+    }, [container, platform]);
+    // Clear on unmount only. The host's mount root outlives the app it holds —
+    // mf-loader re-mounts watchparty into the same element — so leaving the
+    // attributes behind would hand the next tenant a stale value.
+    useEffect(() => () => {
+        stampPlatform(stampedRef.current, { touchFirst: false, narrow: false });
+    }, []);
+    return platform;
+}