@hashsome/ui 0.5.0 → 0.6.0

package/dist/layout/drawer-controls.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
 import { Box, Flex, Typography } from 'e-prim';
 import { motion } from 'motion/react';
 import { MarqueeText } from './marquee-text.js';
-import { useEffect, useRef } from 'react';
+import { useEffect, useId, useRef, } from 'react';
 import { Icon } from '../icon.js';
 import { FadeScroll } from './fade-scroll.js';
 import { RoundButton } from './round-button.js';
@@ -101,19 +101,31 @@ export const CHIP_HEIGHT = 28;
 /** A wrapping row of pill choices (modes, presets) with the selected one filled. With `tabs` it is
  * a tab list (the selected chip is the open tab) that never wraps: too many to fit scroll sideways. */
 export function ChipRow({ options, value, onChange, tabs = false, }) {
+    // The accent behind the selected chip is one pill that glides to the next; its own id, so two rows
+    // on a page do not share it.
+    const pill = useId();
     // Tabs scroll sideways when there are more than fit, and fade at the edge that has more.
     const Wrap = tabs ? FadeScroll : Flex;
     return (_jsx(Wrap, { gap: 2, ...(tabs ? { role: 'tablist' } : {}), css: tabs
-            ? { flexShrink: 0, scrollbarWidth: 'none', '&::-webkit-scrollbar': { display: 'none' } }
-            : { flexWrap: 'wrap' }, children: options.map((option) => {
+            ? {
+                flexShrink: 0,
+                isolation: 'isolate',
+                scrollbarWidth: 'none',
+                '&::-webkit-scrollbar': { display: 'none' },
+            }
+            : { flexWrap: 'wrap', isolation: 'isolate' }, children: options.map((option) => {
             const selected = option.value === value;
             return (_jsxs(Flex, { as: "button", type: "button", ...(tabs ? { role: 'tab', 'aria-selected': selected } : { 'aria-pressed': selected }), ...(option.ariaLabel ? { 'aria-label': option.ariaLabel } : {}), onClick: () => onChange(option.value), align: "center", gap: 1.5, radius: "full", cursor: "pointer", 
                 // A fixed height, not the text's: an emoji is drawn from another font with a taller line,
                 // which would make this one chip taller than the rest.
-                height: CHIP_HEIGHT, px: 3, background: selected ? 'accent' : 'surface', color: selected ? 'accentText' : 'text', css: {
+                height: CHIP_HEIGHT, px: 3, background: "surface", color: selected ? 'accentText' : 'text', css: {
                     flex: 'none',
+                    position: 'relative',
                     whiteSpace: 'nowrap',
-                    transition: 'background-color 160ms ease, color 160ms ease',
-                }, children: [option.icon ? _jsx(Icon, { name: option.icon, size: 14 }) : null, _jsx(Typography, { as: "span", variant: "body", css: { minWidth: 0, maxWidth: 220 }, children: _jsx(MarqueeText, { children: option.label }) })] }, option.value));
+                    transition: 'color 160ms ease',
+                }, children: [selected ? (_jsx(Box, { as: motion.span, layoutId: pill, position: "absolute", radius: "full", background: "accent", transition: { type: 'spring', duration: 0.32, bounce: 0.12 }, 
+                        // Above every chip's own background, whichever way it is going: a later chip paints over
+                        // an earlier one's pill otherwise.
+                        css: { inset: 0, zIndex: 1 } })) : null, _jsxs(Flex, { as: "span", align: "center", gap: 1.5, position: "relative", minWidth: 0, css: { zIndex: 2 }, children: [option.icon ? _jsx(Icon, { name: option.icon, size: 14 }) : null, _jsx(Typography, { as: "span", variant: "body", css: { minWidth: 0, maxWidth: 220 }, children: _jsx(MarqueeText, { children: option.label }) })] })] }, option.value));
         }) }));
 }

package/dist/layout/grid-overlay.d.ts

@@ -0,0 +1,6 @@
+/** Draws the grid over the page it sits in (the `Page`, when the debug menu has it on): a faint
+ * line at every module, a stronger one at every tile pitch, and a box round every card (anything
+ * marked `data-grid-card`) with its height in modules, green when its top and height are on the grid
+ * and red when they are not. For laying out a dashboard for one device: see where things fall, and
+ * what to change. Never takes a touch. */
+export declare function GridOverlay(): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/layout/grid-overlay.js

@@ -0,0 +1,143 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
+/** @jsxImportSource @emotion/react */
+import { useTheme } from '@emotion/react';
+import { Box } from 'e-prim';
+import { useLayoutEffect, useRef, useState } from 'react';
+import { gridMetrics, offGrid } from '../theme/grid.js';
+const SAME = (a, b) => a !== null && JSON.stringify(a) === JSON.stringify(b);
+/** The viewport the page has now (it is smaller than the screen while the browser shows bars), the
+ * screen, both in CSS px, and the pixel ratio: multiply by it for the panel's own pixels. */
+function describeDevice() {
+    const ratio = Math.round(window.devicePixelRatio * 100) / 100;
+    return `viewport ${window.innerWidth}×${window.innerHeight} · screen ${window.screen.width}×${window.screen.height} @${ratio}`;
+}
+/** Draws the grid over the page it sits in (the `Page`, when the debug menu has it on): a faint
+ * line at every module, a stronger one at every tile pitch, and a box round every card (anything
+ * marked `data-grid-card`) with its height in modules, green when its top and height are on the grid
+ * and red when they are not. For laying out a dashboard for one device: see where things fall, and
+ * what to change. Never takes a touch. */
+export function GridOverlay() {
+    const theme = useTheme();
+    const metrics = gridMetrics(theme.density.space);
+    const { module, tilePitch } = metrics;
+    const ref = useRef(null);
+    const [view, setView] = useState(null);
+    useLayoutEffect(() => {
+        const host = ref.current?.parentElement;
+        if (!host) {
+            return;
+        }
+        let frame = 0;
+        const measure = () => {
+            const style = getComputedStyle(host);
+            const centered = host.dataset['centered'] ?? '';
+            const [slack = 0, slackBelow = 0] = centered.split(' ').map(Number);
+            // The grid spans the whole page, its padding included: it starts at the page's edge, less the
+            // sliver centering left over, so the padding is its first modules and the cards start after it.
+            const top = slack;
+            const box = host.getBoundingClientRect();
+            const next = {
+                top,
+                width: host.scrollWidth,
+                height: host.scrollHeight - slack - slackBelow,
+                content: {
+                    left: parseFloat(style.paddingLeft),
+                    top: parseFloat(style.paddingTop) - slack,
+                    right: parseFloat(style.paddingRight),
+                    bottom: parseFloat(style.paddingBottom) - slackBelow,
+                },
+                centered,
+                device: describeDevice(),
+                cards: [...host.querySelectorAll('[data-grid-card]')].map((card) => {
+                    const rect = card.getBoundingClientRect();
+                    const x = rect.left - box.left + host.scrollLeft;
+                    const y = rect.top - box.top + host.scrollTop - top;
+                    return {
+                        x: Math.round(x * 10) / 10,
+                        y: Math.round(y * 10) / 10,
+                        width: Math.round(rect.width * 10) / 10,
+                        height: Math.round(rect.height * 10) / 10,
+                        off: offGrid(y, rect.height, module),
+                    };
+                }),
+            };
+            setView((current) => (SAME(current, next) ? current : next));
+        };
+        const schedule = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(measure);
+        };
+        schedule();
+        window.addEventListener('resize', schedule);
+        const resize = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(schedule);
+        resize?.observe(host);
+        // What the page is made of changing (a card appearing, a size changing): not this overlay's own.
+        const mutations = new MutationObserver((records) => {
+            if (records.some((record) => !ref.current?.contains(record.target))) {
+                schedule();
+            }
+        });
+        mutations.observe(host, { subtree: true, childList: true, attributes: true });
+        return () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener('resize', schedule);
+            resize?.disconnect();
+            mutations.disconnect();
+        };
+    }, [module]);
+    // A line every module, unless that is too fine to read, then every gap (3 modules).
+    const minor = module >= 3.5 ? module : module * 3;
+    const off = view?.cards.filter((card) => card.off).length ?? 0;
+    const [top = 0, bottom = 0] = (view?.centered ?? '').split(' ').map(Number);
+    return (_jsx(Box, { ref: ref, "data-grid-overlay": true, "aria-hidden": "true", css: { display: 'contents' }, children: view ? (_jsxs(_Fragment, { children: [_jsxs(Box, { position: "absolute", css: {
+                        left: 0,
+                        top: view.top,
+                        width: view.width,
+                        height: view.height,
+                        pointerEvents: 'none',
+                        zIndex: 4,
+                        backgroundImage: [
+                            `linear-gradient(to bottom, rgba(0, 150, 255, 0.5) 1px, transparent 1px)`,
+                            `linear-gradient(to right, rgba(0, 150, 255, 0.5) 1px, transparent 1px)`,
+                            `linear-gradient(to bottom, rgba(0, 150, 255, 0.12) 1px, transparent 1px)`,
+                            `linear-gradient(to right, rgba(0, 150, 255, 0.12) 1px, transparent 1px)`,
+                        ].join(', '),
+                        backgroundSize: [
+                            `100% ${tilePitch}px`,
+                            `${tilePitch}px 100%`,
+                            `100% ${minor}px`,
+                            `${minor}px 100%`,
+                        ].join(', '),
+                    }, children: [_jsx(Box, { position: "absolute", css: {
+                                left: view.content.left,
+                                top: view.content.top,
+                                right: view.content.right,
+                                bottom: view.content.bottom,
+                                outline: '1px dashed rgba(0, 150, 255, 0.9)',
+                            } }), view.cards.map((card) => (_jsx(Box, { position: "absolute", css: {
+                                left: card.x,
+                                top: card.y,
+                                width: card.width,
+                                height: card.height,
+                                boxSizing: 'border-box',
+                                outline: `1px solid ${card.off ? '#ef4444' : '#22c55e'}`,
+                                outlineOffset: -1,
+                                color: card.off ? '#ef4444' : '#22c55e',
+                                font: '600 9px/1 system-ui, sans-serif',
+                                padding: 2,
+                                overflow: 'hidden',
+                            }, children: card.height >= 14 ? `${Math.round((card.height / module) * 10) / 10}u` : null }, `${card.x}:${card.y}:${card.width}:${card.height}`)))] }), _jsx(Box, { position: "fixed", css: {
+                        // Clear of the debug menu's button, which is how the grid is turned on.
+                        left: 60,
+                        bottom: 8,
+                        zIndex: 100,
+                        pointerEvents: 'none',
+                        // On a narrow screen it wraps instead of running off the edge.
+                        maxWidth: 'calc(100vw - 68px)',
+                        background: 'rgba(0, 0, 0, 0.78)',
+                        color: '#fff',
+                        font: '600 11px/1.3 system-ui, sans-serif',
+                        padding: '4px 8px',
+                        borderRadius: 6,
+                    }, children: `grid · 1u = ${Math.round(module * 100) / 100}px · gap 3u · tile ${Math.round(metrics.tile / module)}u · ${off === 0 ? 'all on grid' : `${off} off grid`}${top + bottom > 0 ? ` · centered +${top}/${bottom}px` : ''}${view.device ? ` · ${view.device}` : ''}` })] })) : null }));
+}

package/dist/layout/page.d.ts

@@ -12,6 +12,12 @@ export interface PageProps {
 /** The page every dashboard renders into: padded by the density's spacing, a column with gaps,
  * exactly viewport height, and scrolling inside itself (the document never scrolls — the entity
  * drawer is `position: fixed` and relies on that). It pads further for a `NavRail` or `NavDock`
- * the dashboard includes. Render it once, in the app's root layout. */
+ * the dashboard includes. Render it once, in the app's root layout.
+ *
+ * The debug menu (`HASHSOME_DEBUG=1`) can draw the module grid over the page, spanning all of it (its
+ * padding is the grid's first three modules), with every card boxed green or red by whether it sits on
+ * the grid: for laying a dashboard out for one device. The height is rarely a whole number of grid
+ * modules; what is left over (under one module) is shared between the top and the bottom padding, so the
+ * content sits centered and the grid stays whole. */
 export declare function Page({ children, height }: PageProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export {};

package/dist/layout/page.js

@@ -1,7 +1,11 @@
-import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
 /** @jsxImportSource @emotion/react */
+import { useTheme } from '@emotion/react';
 import { Flex } from 'e-prim';
-import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useState, } from 'react';
+import { useDebug } from '../debug.js';
+import { centeringOffsets, gridMetrics } from '../theme/grid.js';
+import { GridOverlay } from './grid-overlay.js';
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 const InsetContext = createContext(null);
 /** Reserves `size` px of the surrounding `Page`'s edge for something fixed over it (`NavRail`,
  * `NavDock`), so content never sits under it. A no-op outside a `Page`. */
@@ -12,7 +16,13 @@ export function usePageInset(side, size) {
 /** The page every dashboard renders into: padded by the density's spacing, a column with gaps,
  * exactly viewport height, and scrolling inside itself (the document never scrolls — the entity
  * drawer is `position: fixed` and relies on that). It pads further for a `NavRail` or `NavDock`
- * the dashboard includes. Render it once, in the app's root layout. */
+ * the dashboard includes. Render it once, in the app's root layout.
+ *
+ * The debug menu (`HASHSOME_DEBUG=1`) can draw the module grid over the page, spanning all of it (its
+ * padding is the grid's first three modules), with every card boxed green or red by whether it sits on
+ * the grid: for laying a dashboard out for one device. The height is rarely a whole number of grid
+ * modules; what is left over (under one module) is shared between the top and the bottom padding, so the
+ * content sits centered and the grid stays whole. */
 export function Page({ children, height = '100dvh' }) {
     const [insets, setInsets] = useState({ left: 0, bottom: 0 });
     const reserve = useCallback((side, size) => {
@@ -20,10 +30,37 @@ export function Page({ children, height = '100dvh' }) {
         return () => setInsets((current) => ({ ...current, [side]: 0 }));
     }, []);
     const value = useMemo(() => reserve, [reserve]);
-    return (_jsx(InsetContext.Provider, { value: value, children: _jsx(Flex, { as: "main", direction: "column", height: height, overflow: "auto", gap: 3, p: 3, css: ({ spacing }) => ({
+    // The debug menu's "Show grid" draws the module grid over the page, for laying a dashboard out.
+    const showGrid = useDebug().grid;
+    // What is left of the height after whole modules goes half to the top padding and half to the
+    // bottom one (in whole pixels, so edges stay crisp).
+    const theme = useTheme();
+    const space = theme.density?.space;
+    const main = useRef(null);
+    const [centered, setCentered] = useState({ top: 0, bottom: 0 });
+    useLayoutEffect(() => {
+        const element = main.current;
+        if (!element || space === undefined) {
+            return;
+        }
+        const measure = () => {
+            const next = centeringOffsets(element.clientHeight - 2 * space - insets.bottom, gridMetrics(space).module);
+            setCentered((current) => current.top === next.top && current.bottom === next.bottom ? current : next);
+        };
+        measure();
+        window.addEventListener('resize', measure);
+        const resize = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(measure);
+        resize?.observe(element);
+        return () => {
+            window.removeEventListener('resize', measure);
+            resize?.disconnect();
+        };
+    }, [space, insets.bottom]);
+    return (_jsx(InsetContext.Provider, { value: value, children: _jsxs(Flex, { as: "main", ref: main, "data-centered": `${centered.top} ${centered.bottom}`, direction: "column", height: height, overflow: "auto", position: "relative", gap: 3, p: 3, css: ({ spacing }) => ({
                 // The padding of one space, plus room for a nav that is fixed over the page.
                 paddingLeft: `calc(${spacing(3)} + ${insets.left}px)`,
-                paddingBottom: `calc(${spacing(3)} + ${insets.bottom}px)`,
+                paddingTop: `calc(${spacing(3)} + ${centered.top}px)`,
+                paddingBottom: `calc(${spacing(3)} + ${insets.bottom + centered.bottom}px)`,
                 boxSizing: 'border-box',
-            }), children: children }) }));
+            }), children: [children, showGrid ? _jsx(GridOverlay, {}) : null] }) }));
 }

package/dist/layout/room-header.js

@@ -4,7 +4,7 @@ import { Box, Flex, Typography } from 'e-prim';
 import { Icon } from '../icon.js';
 /** The header that starts a room: muted icon and title, a hairline, and readouts on the right. Put it above a `Grid` (or any tiles); it adds its own space above, so consecutive rooms read as groups. */
 export function RoomHeader({ title, icon, readouts }) {
-    return (_jsxs(Flex, { as: "header", align: "center", color: "textMuted", minHeight: 32, mt: 3, gap: 3, 
+    return (_jsxs(Flex, { as: "header", "data-grid-card": true, align: "center", color: "textMuted", minHeight: 32, mt: 3, gap: 3, 
         // A header starts a new group: the extra space sits on top of the screen's own gap, so a
         // room reads as header + its tiles rather than as evenly spaced rows.
         css: { '&:first-child': { marginTop: 0 } }, children: [icon ? _jsx(Icon, { name: icon, size: 16 }) : null, _jsx(Typography, { as: "h2", variant: "roomTitle", color: "textMuted", css: { margin: 0 }, children: title }), _jsx(Box, { as: "span", background: "border", css: { flex: 1, height: 1 } }), readouts ? (_jsx(Flex, { align: "center", color: "textMuted", css: ({ density }) => ({ gap: density.space * 1.5 }), children: readouts })) : null] }));

package/dist/layout/tile.js

@@ -5,6 +5,7 @@ import { useEffect, useMemo, useRef, useState, } from 'react';
 import { Icon } from '../icon.js';
 import { RoundButton } from './round-button.js';
 import { statusLabels } from '../status.js';
+import { BADGE } from '../theme/grid.js';
 import { useDrawer } from './use-drawer.js';
 import { EnergyChart } from './energy-chart.js';
 import { HistorySection } from './history-section.js';
@@ -183,9 +184,16 @@ export function Tile({ label, icon, secondary, status = 'ready', active = false,
     const dimColorKey = ready ? 'line' : 'textMuted';
     const cardOpacity = !ready || feedback === 'pending' ? 0.7 : 1;
     const iconBadge = icon ? (_jsx(Flex, { as: motion.span, align: "center", justify: "center", position: "relative", radius: "full", width: 32, height: 32, initial: false, animate: { backgroundColor: iconBg, color: iconColor }, transition: COLOR_TRANSITION, css: { flex: 'none' }, children: _jsx(Icon, { name: icon, size: 16 }) })) : null;
-    return (_jsxs(Flex, { as: motion.div, radius: "card", position: "relative", align: "center", overflow: "hidden", minWidth: 0, "data-status": status, "data-active": accented, "data-solid-accent": solidAccent, "data-fill": fill !== undefined, "data-fill-visible": showFill, "data-overlay": overlay !== undefined, "data-pending": feedback === 'pending', "data-feedback": feedback === 'pending' ? undefined : feedback, 
+    return (_jsxs(Flex, { as: motion.div, radius: "card", position: "relative", align: "center", overflow: "hidden", minWidth: 0, "data-grid-card": true, "data-status": status, "data-active": accented, "data-solid-accent": solidAccent, "data-fill": fill !== undefined, "data-fill-visible": showFill, "data-overlay": overlay !== undefined, "data-pending": feedback === 'pending', "data-feedback": feedback === 'pending' ? undefined : feedback, 
         // A card that mounts (a page opened) is drawn as it is, not animated from nothing.
-        initial: false, animate: { backgroundColor: cardBg, color: cardColor, opacity: cardOpacity }, transition: COLOR_TRANSITION, css: ({ palette }) => feedback === 'error' ? { outline: `2px solid ${palette.danger}`, outlineOffset: -2 } : null, children: [hasFill ? (_jsx(Box, { as: motion.span, position: "absolute", background: "accent", 
+        initial: false, animate: { backgroundColor: cardBg, color: cardColor, opacity: cardOpacity }, transition: COLOR_TRANSITION, css: ({ palette, spacing }) => ({
+            // The badge between its padding, written down rather than left to the content, so a tile is a
+            // whole number of grid modules (12, in the comfortable density) whatever is in it.
+            minHeight: `calc(${spacing(4)} + ${BADGE}px)`,
+            ...(feedback === 'error'
+                ? { outline: `2px solid ${palette.danger}`, outlineOffset: -2 }
+                : {}),
+        }), children: [hasFill ? (_jsx(Box, { as: motion.span, position: "absolute", background: "accent", 
                 // Spans the whole card, including behind `trailing` (e.g. a color-capable light's
                 // picker button) — it's a sibling of the button and `trailing`, not nested inside the
                 // button, specifically so its width isn't capped at the button's own narrower bounds.

package/dist/layout/top-row.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+export interface TopRowProps {
+    /** What goes in the row: the date, the weather, the clock. */
+    children: ReactNode;
+}
+/** The row along the top of a page you build yourself instead of with `TopBar`: its pieces (`DateChip`,
+ * `WeatherChip`, `Clock`, `SystemStatus`) in a line at the right, in the height the grid gives the top
+ * row, with no padding of its own. */
+export declare function TopRow({ children }: TopRowProps): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/layout/top-row.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+/** @jsxImportSource @emotion/react */
+import { Flex } from 'e-prim';
+import { TOP_ROW } from '../theme/grid.js';
+/** The row along the top of a page you build yourself instead of with `TopBar`: its pieces (`DateChip`,
+ * `WeatherChip`, `Clock`, `SystemStatus`) in a line at the right, in the height the grid gives the top
+ * row, with no padding of its own. */
+export function TopRow({ children }) {
+    return (_jsx(Flex, { align: "center", justify: "flex-end", gap: 3, css: { minHeight: TOP_ROW }, children: children }));
+}

package/dist/provider.d.ts

@@ -1,4 +1,4 @@
-import { type Client, type RemoteClientOptions } from '@hashsome/core';
+import { type Client, type EntityRef, type RemoteClientOptions } from '@hashsome/core';
 import { type ReactNode } from 'react';
 import { type Density } from './theme/density.ts';
 import { type ThemeOverrides } from './theme/overrides.ts';
@@ -21,10 +21,14 @@ export interface HashsomeProviderProps {
     font?: string;
     /** `'compact'` for small square displays: tighter spacing, shorter tiles, smaller icon circles. Default `'comfortable'`. */
     density?: Density;
-    /** `'reduced'` turns animations and transitions off, for a slow display, `'full'` keeps them and `'auto'` (the default) leaves things as they are. A device can choose for itself with `?motion=reduced` (or `full`) on the address it opens: the choice is kept on the device, so reloads and links inside the app keep it, and `?motion=auto` forgets it. That wins over this prop. */
+    /** `'reduced'` turns animations and transitions off, for a slow display, `'full'` keeps them and `'auto'` (the default) leaves things as they are. A device can choose for itself with `?motion=reduced` (or `full`) on the address it opens, which wins over this prop. Nothing is kept: it holds while the app is open, moving between its pages, and a reload without the parameter goes back to this prop. */
     motion?: MotionPreference;
     /** Partial changes to the built-in theme — colors per light/dark, radii, typography, spacing, density sizes. Pass a constant defined outside the component: a new object each render rebuilds the theme each render. */
     overrides?: ThemeOverrides;
+    /** Shows the debug menu: a floating button at the bottom left whose popover shows the module grid, makes the page fullscreen and changes the theme, on the device, kept there. Default: on when `HASHSOME_DEBUG=1` (or `true`) was in the environment of `hashsome dev` or `build`. */
+    debug?: boolean;
+    /** The daylight sensor (`on` while the sun is up) the debug menu's Sun theme follows, when `theme` is not a sun schedule already (`theme={{ sun: … }}` names one). Without either, the menu has no Sun choice: Hashsome does not know which entity is the sun. */
+    sun?: EntityRef;
     /** The app. */
     children: ReactNode;
 }
@@ -40,5 +44,5 @@ export interface ThemeModeState {
  * Must be rendered inside `<HashsomeProvider>`. */
 export declare function useThemeToggle(): ThemeModeState;
 /** Connects the tree to the runtime proxy. Render only on the client. */
-export declare function HashsomeProvider({ url, client, clientOptions, theme, motion, font, density, overrides, children, }: HashsomeProviderProps): import("react").JSX.Element;
+export declare function HashsomeProvider({ url, client, clientOptions, theme, motion, font, density, overrides, debug, sun, children, }: HashsomeProviderProps): import("react").JSX.Element;
 export declare function useClient(): Client;

package/dist/provider.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { RemoteClient } from '@hashsome/core';
+import { RemoteClient, } from '@hashsome/core';
 import { Global, ThemeProvider as EmotionThemeProvider } from '@emotion/react';
 import { ThemeProvider } from 'e-prim';
 import { MotionGlobalConfig } from 'motion/react';
-import { createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from 'react';
+import { DebugContext, debugFromEnv, useDebugState, useFullscreenKept, } from './debug.js';
+import { DebugMenu } from './layout/debug-menu.js';
 import { DetailProvider } from './layout/detail-provider.js';
 import { EntityDrawer } from './layout/entity-drawer.js';
 import { UNITS_PER_SPACE } from './theme/density.js';
@@ -51,22 +53,13 @@ export function useThemeToggle() {
     }
     return value;
 }
-const MOTION_KEY = 'hashsome:motion';
-/** What this device chose for motion: `?motion=reduced` or `?motion=full` on the address (which is
- * also remembered), or what an earlier visit remembered. `?motion=auto` forgets it. */
-function motionFromDevice() {
+/** What the address asks for motion: `?motion=reduced` or `?motion=full`. Nothing is kept, and the
+ * app reads it once, when it starts, so moving between pages inside the app keeps it and a reload
+ * without it does not. `?motion=auto` (or anything else) leaves it to the prop. */
+function motionFromAddress() {
     try {
         const asked = new URLSearchParams(window.location.search).get('motion');
-        if (asked === 'reduced' || asked === 'full') {
-            localStorage.setItem(MOTION_KEY, asked);
-            return asked;
-        }
-        if (asked === 'auto') {
-            localStorage.removeItem(MOTION_KEY);
-            return undefined;
-        }
-        const kept = localStorage.getItem(MOTION_KEY);
-        return kept === 'reduced' || kept === 'full' ? kept : undefined;
+        return asked === 'reduced' || asked === 'full' ? asked : undefined;
     }
     catch {
         return undefined;
@@ -77,7 +70,7 @@ function motionFromDevice() {
  * transitions and animations too. */
 function useMotionMode(preference) {
     const [mode] = useState(() => {
-        const chosen = motionFromDevice() ?? preference;
+        const chosen = motionFromAddress() ?? preference;
         MotionGlobalConfig.skipAnimations = chosen === 'reduced';
         if (typeof document !== 'undefined') {
             if (chosen === 'reduced') {
@@ -102,6 +95,22 @@ function rememberedSun() {
         return undefined;
     }
 }
+/** The sun entity a theme follows, if it is a sun schedule. */
+function sunOf(mode) {
+    return typeof mode === 'object' && 'sun' in mode ? mode.sun : undefined;
+}
+/** The theme in effect: what the debug menu chose, if it chose, else what the project configured.
+ * The sun is the project's: the one its theme follows, or the `sun` it gave. Without one there is no
+ * sun to follow, so that choice (kept from a visit that had one) leaves the configured theme as it was. */
+function chosenTheme(configured, choice, sun) {
+    if (choice === null) {
+        return configured;
+    }
+    if (choice === 'sun') {
+        return sun === undefined ? configured : { sun };
+    }
+    return choice;
+}
 /** Resolves the configured mode: `'system'` against the live OS/browser preference (updating if it
  * changes while open — a kiosk tablet left running overnight should follow a scheduled OS-level dark
  * mode, for example), a time range against the clock (re-checked at each boundary and whenever the
@@ -151,7 +160,12 @@ function useThemeMode(mode, client) {
             document.removeEventListener('visibilitychange', onVisible);
         };
     }, [from, to]);
-    const sun = useSyncExternalStore((onChange) => (sunRef ? client.subscribe(sunRef, onChange) : () => undefined), () => (sunRef ? client.getEntity(sunRef) : undefined), () => undefined);
+    // Memoized, like every other `subscribe` given to `useSyncExternalStore` (see hooks.ts): a new
+    // function each render makes React resubscribe, which against a remote runtime is an unsubscribe and
+    // a subscribe whose reply is a new entity object, which renders again, without end.
+    const subscribeSun = useCallback((onChange) => (sunRef ? client.subscribe(sunRef, onChange) : () => undefined), [client, sunRef]);
+    const readSun = useCallback(() => (sunRef ? client.getEntity(sunRef) : undefined), [client, sunRef]);
+    const sun = useSyncExternalStore(subscribeSun, readSun, () => undefined);
     const sunDown = sunIsDown(sun);
     useEffect(() => {
         if (sunDown === undefined) {
@@ -181,10 +195,14 @@ function useThemeMode(mode, client) {
     return { resolved, toggle: () => setOverride(resolved === 'dark' ? 'light' : 'dark') };
 }
 /** Connects the tree to the runtime proxy. Render only on the client. */
-export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', motion = 'auto', font = DEFAULT_FONT, density = 'comfortable', overrides, children, }) {
+export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', motion = 'auto', font = DEFAULT_FONT, density = 'comfortable', overrides, debug = debugFromEnv(), sun, children, }) {
     const instance = useMemo(() => client ?? new RemoteClient({ url: url ?? defaultUrl(), ...clientOptions }), [client, url, clientOptions]);
     useMotionMode(motion);
-    const themeMode = useThemeMode(theme, instance);
+    const debugState = useDebugState();
+    useFullscreenKept(debugState.fullscreen, debugState.setFullscreen);
+    // The debug menu can choose a theme over the configured one; the sun is the project's own entity.
+    const sunEntity = sunOf(theme) ?? sun;
+    const themeMode = useThemeMode(chosenTheme(theme, debug ? debugState.themeChoice : null, sunEntity), instance);
     // Memoized: Emotion recomputes the merged theme (and every `css` prop) when the function changes.
     const withDensity = useMemo(() => (outer) => ({ ...outer, density: densityTokens(density, overrides) }), [density, overrides]);
     useGoogleFont(font);
@@ -197,7 +215,7 @@ export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', m
         instance.connect();
         return () => instance.close();
     }, [instance]);
-    return (_jsx(HashsomeContext.Provider, { value: instance, children: _jsx(ThemeModeContext.Provider, { value: themeMode, children: _jsx(ThemeProvider, { theme: resolvedTheme, children: _jsxs(EmotionThemeProvider, { theme: withDensity, children: [_jsx(Global, { styles: globalStyles }), _jsxs(DetailProvider, { children: [children, _jsx(EntityDrawer, {})] })] }) }) }) }));
+    return (_jsx(HashsomeContext.Provider, { value: instance, children: _jsx(ThemeModeContext.Provider, { value: themeMode, children: _jsx(ThemeProvider, { theme: resolvedTheme, children: _jsxs(EmotionThemeProvider, { theme: withDensity, children: [_jsx(Global, { styles: globalStyles }), _jsx(DebugContext.Provider, { value: debugState, children: _jsxs(DetailProvider, { children: [children, _jsx(EntityDrawer, {}), debug ? _jsx(DebugMenu, { configured: theme, sun: sunEntity }) : null] }) })] }) }) }) }));
 }
 export function useClient() {
     const client = useContext(HashsomeContext);

package/dist/theme/grid.d.ts

@@ -0,0 +1,30 @@
+/** The icon badge a tile starts with, in px: the one size in a tile that does not scale with density. */
+export declare const BADGE = 32;
+/** The height of a room header, in px. */
+export declare const HEADER = 32;
+/** The height of the top row, in px: the clock's line and the tallest things beside it (the switcher, the
+ * scene buttons), with no padding of its own, so its content sits as far from the page's edge as
+ * everything else does. Sizes that do not scale with density are multiples of 8, so they are whole
+ * modules in both (4px and 2.67px). */
+export declare const TOP_ROW = 40;
+/** The vertical grid every card sits on. The module is the theme's spacing unit (a third of a
+ * space: 4px in comfortable density, 2.67px in compact), so the gap between cards is always 3
+ * modules, and a tile and a header are whole numbers of them in either density. Sizes are in px;
+ * `pitch` is a card's height plus the gap that follows it, and a card spanning n pitches is n heights
+ * and n-1 gaps tall. */
+export interface GridMetrics {
+    module: number;
+    gap: number;
+    tile: number;
+    header: number;
+    tilePitch: number;
+    headerPitch: number;
+}
+export declare function gridMetrics(space: number): GridMetrics;
+/** Whether a box's top edge, measured from the grid's origin, or its height is off the module grid. Browsers round to the pixel, so a little under a pixel is still on it. */
+export declare function offGrid(top: number, height: number, module: number): boolean;
+/** How a height's leftover (what is under one module after as many whole ones as fit) is shared between the top and the bottom padding: half each, in whole pixels, the odd one to the bottom. `available` is the height inside the page's padding. */
+export declare function centeringOffsets(available: number, module: number): {
+    top: number;
+    bottom: number;
+};

package/dist/theme/grid.js

@@ -0,0 +1,38 @@
+import { UNITS_PER_SPACE } from './density.js';
+/** The icon badge a tile starts with, in px: the one size in a tile that does not scale with density. */
+export const BADGE = 32;
+/** The height of a room header, in px. */
+export const HEADER = 32;
+/** The height of the top row, in px: the clock's line and the tallest things beside it (the switcher, the
+ * scene buttons), with no padding of its own, so its content sits as far from the page's edge as
+ * everything else does. Sizes that do not scale with density are multiples of 8, so they are whole
+ * modules in both (4px and 2.67px). */
+export const TOP_ROW = 40;
+export function gridMetrics(space) {
+    const module = space / UNITS_PER_SPACE;
+    // A tile is its badge between two spacing-unit-2 paddings.
+    const tile = BADGE + 4 * module;
+    return {
+        module,
+        gap: space,
+        tile,
+        header: HEADER,
+        tilePitch: tile + space,
+        headerPitch: HEADER + space,
+    };
+}
+/** Whether a box's top edge, measured from the grid's origin, or its height is off the module grid. Browsers round to the pixel, so a little under a pixel is still on it. */
+export function offGrid(top, height, module) {
+    const tolerance = Math.max(0.5, module * 0.15);
+    const off = (value) => {
+        const rest = Math.abs(value) % module;
+        return Math.min(rest, module - rest) > tolerance;
+    };
+    return off(top) || off(height);
+}
+/** How a height's leftover (what is under one module after as many whole ones as fit) is shared between the top and the bottom padding: half each, in whole pixels, the odd one to the bottom. `available` is the height inside the page's padding. */
+export function centeringOffsets(available, module) {
+    const leftover = available > 0 ? Math.floor(available % module) : 0;
+    const top = Math.floor(leftover / 2);
+    return { top, bottom: leftover - top };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/ui",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Design system components and hooks",
   "type": "module",
   "exports": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@emotion/react": "11.14.0",
-    "@hashsome/core": "0.5.0",
+    "@hashsome/core": "0.6.0",
     "e-prim": "2.0.1",
     "motion": "13.4.5",
     "react": "19.3.0",