@tilewise/workbench-client 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 · 2026-11-03 17:34 +04:00
+
+- Start keeping versions and this changelog

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beka Bendeliani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# @tilewise/workbench-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connects a React prototype to the workbench's Proto viewer. The viewer shows
+the prototype in a frame, draws a device round it, lists its screens and
+states, and draws a form of controls beside it for the page on screen. This
+package holds everything the prototype needs for that; the prototype only
+declares what it has.
+
+```bash
+pnpm add @tilewise/workbench-client
+```
+
+React 19 is a peer dependency, so the app's own React is the one used.
+
+## Controls
+
+A control is one value a reviewer can change from the viewer. There are five
+types, and the viewer draws one fixed row for each:
+
+| Type | For | Its own fields | Value |
+| --- | --- | --- | --- |
+| `variant` | Another version of a screen or of one part of it | `options`, each `{ value, label }` | One of the values |
+| `boolean` | Show or hide one thing | None | `true` or `false` |
+| `number` | A count between a min and a max | `min`, `max`, `step` | A number in range |
+| `color` | A color from the app's tokens, never a free hex | `options`, each `{ token, label }` | One of the tokens |
+| `text` | One line of text, to try other wording | `maxLength` | A string |
+
+Every control also has an `id` (unique across the app, never renamed), a
+`label`, a `default`, and an optional `note`, shown quietly under its row.
+
+### Declaring
+
+Every component lives in a folder named after it, beside its test. A
+component with controls holds its part there too, a `.workbench.ts` file:
+
+```ts
+// HomeScreen/HomeScreen.workbench.ts
+import { defineScreen } from '@tilewise/workbench-client';
+
+export const home = defineScreen({
+  screen: 'home',
+  controls: [
+    {
+      id: 'homepage',
+      type: 'variant',
+      label: 'Page',
+      options: [
+        { value: 'today', label: 'Original design' },
+        { value: 'feed', label: 'Feed (old)' },
+      ],
+      default: 'today',
+    },
+    { id: 'bottom', type: 'boolean', label: 'Bottom section', default: true },
+  ],
+});
+```
+
+| Level | Declared with | Shows in the form |
+| --- | --- | --- |
+| Global | `defineApp`, beside the app's root component | On every page |
+| Screen | `defineScreen({ screen, controls })` | On that screen |
+| Block | `defineBlock({ block, label, controls })` | On any screen, while the block is drawn there |
+
+Each returns one handle per control, under its id: `home.homepage`. The
+values' types come from the declaration, so `home.homepage` reads as
+`'today' | 'feed'` with no `as const`.
+
+The app has exactly one `defineApp`, beside its root component:
+
+```ts
+// App/App.workbench.ts
+import { defineApp } from '@tilewise/workbench-client';
+
+export const app = defineApp({
+  app: 'aitems',
+  screens: allScreens(), // every screen and its states, each state with its jump
+  useNavigation, // a hook: { go(state), at: { screen, state } }
+  parts: import.meta.glob(['../**/*.workbench.ts', '!./App.workbench.ts'], { eager: true }),
+  controls: [{ id: 'seeall', type: 'variant', label: 'See all', options: [/* … */], default: 'ink' }],
+});
+```
+
+`parts` loads every part as the app starts. As it starts, the app throws on
+two controls with one id, two blocks with one name, a screen id that isn't in
+`screens`, a default that isn't one of the options or is outside `min` and
+`max`, and a second `defineApp`.
+
+### Values
+
+A value comes from `?<id>=<value>` in the address first (and is stored, so a
+link can hand a variant round), then from `control:<id>` in the browser's
+storage, then from the default. Every value is checked against its
+declaration: one that doesn't fit falls back to the default, a number is
+clamped and text is cut at `maxLength`. Only a picked value is stored, so a
+new default reaches everyone who left that control alone. Another tab of the
+app follows a change through storage.
+
+## In components
+
+```tsx
+// HomeScreen/HomeScreen.tsx
+import { boolean, ScreenScope, useControl, variant } from '@tilewise/workbench-client';
+import { home } from './HomeScreen.workbench';
+
+export function HomeScreen() {
+  const page = useControl(home.homepage);
+  const bottom = useControl(home.bottom);
+
+  return (
+    <ScreenScope screen="home">
+      <StatusRow />
+      {variant(page, { today: <TodayPage />, feed: null })}
+      {boolean(bottom, { on: <BelowFeed />, off: null })}
+    </ScreenScope>
+  );
+}
+```
+
+- `useControl(handle)` reads a value and draws again when it changes;
+  `setControl(handle, value)` and `resetControl(handle)` change it. A test
+  sets the values it needs with `setControl` before it renders.
+- A component never compares a value to choose what to draw. It hands the
+  value to the helper for its type, so the type checker sees every case:
+
+  | Helper | Cases |
+  | --- | --- |
+  | `variant(value, cases)` | Every option, or some and `other` for the rest |
+  | `boolean(value, { on, off })` | Both |
+  | `number(value, cases)` | Any exact numbers, and `other` |
+  | `text(value, cases)` | Any exact lines, and `other` |
+  | `color(token)` | None: `color('lime')` is `'var(--lime)'` |
+
+  A case is something to draw, or a function that gets the value. `other`'s
+  function gets it typed without the options listed beside it. The helpers
+  take values, not handles, so they work anywhere.
+- A block's `useControl` reports the block as drawn on the screen of the
+  nearest `<ScreenScope>`, until it unmounts, so the form shows a section for
+  it. Wrap each screen's content in one. A control that decides whether a
+  block is mounted at all lives with the parent that mounts it.
+- Global values are written to the root as `html[data-<id>]`, and a number or
+  color also as `--tweak-<id>`, for pure-CSS tweaks. A screen's or block's
+  value goes on the component's own root, as `data-<id>`, for its CSS.
+- Mark the part a control changes `data-control="<id> …"`: after the viewer
+  sets or resets it, the screen scrolls there.
+- Mark each screen's scrolling body `data-workbench-body` while it is the open
+  one: on Full page, the app reports how tall the open screen is laid out
+  whole from it.
+
+## The bridge
+
+Mount `<Bridge />` once at the app's root. In the viewer's frame it says
+`hello` with the manifest, sends where the app is, the blocks drawn on each
+screen and every value as they change, and does what the viewer asks. It lays
+the app out for the device the viewer draws round it: `--safe-top`,
+`--safe-bottom` and `html[data-platform]`; until a device arrives, the app's
+own CSS holds the first phone's. Outside a frame it only opens the state
+`?at=` names. [docs/protocol.md](docs/protocol.md) has the protocol.
+
+## Local builds
+
+```ts
+// vite.config.ts
+import { workbenchLocal } from '@tilewise/workbench-client/vite';
+
+export default defineConfig({ plugins: [react(), workbenchLocal({ base: 'develop' })] });
+```
+
+With it, the app's dev server also answers the viewer's Local source: it
+lists this machine's branches and commits against `base` (the repository's
+default branch unless set), builds any commit in a git worktree into the
+git-ignored `.builds/<sha>/`, and checks a branch out, refused while
+anything is uncommitted. Builds are served under `/__workbench/b/<sha>/`, so
+the app's router takes `basepath: import.meta.env.BASE_URL`.
+
+Only the viewer may ask: from its origin (`WORKBENCH_URL`, or a viewer on
+localhost) with the token in the link the dev server logs. `pnpm dev` opens
+that link; without `WORKBENCH_URL` the dev server opens no viewer.

package/dist/blocks/ScreenScope.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+/**
+ * Tells the blocks inside it which screen they are on. Each screen component
+ * wraps its content in one, so a block counts for the screen it sits in: tab
+ * roots stay mounted while hidden, and a block in a hidden tab never counts
+ * for the screen on show.
+ */
+export declare function ScreenScope({ screen, children }: {
+    screen: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/blocks/ScreenScope.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ScreenContext } from './screenContext.js';
+/**
+ * Tells the blocks inside it which screen they are on. Each screen component
+ * wraps its content in one, so a block counts for the screen it sits in: tab
+ * roots stay mounted while hidden, and a block in a hidden tab never counts
+ * for the screen on show.
+ */
+export function ScreenScope({ screen, children }) {
+    return _jsx(ScreenContext, { value: screen, children: children });
+}

package/dist/blocks/drawnBlocks.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Which blocks are drawn on which screen now. A block's `useControl` reports
+ * it while mounted, and the bridge tells the viewer, so the form shows a
+ * section for each. A block drawn twice on one screen counts once; a screen
+ * keeps its blocks in the order they were first reported.
+ */
+/** Reports a block as drawn on a screen; the returned function takes it out. */
+export declare function reportBlock(screen: string, block: string): () => void;
+/** Every screen that has had blocks, with the ones drawn there now. The same object until one changes. */
+export declare const blocksNow: () => ReadonlyMap<string, readonly string[]>;
+export declare function subscribeBlocks(listener: () => void): () => void;

package/dist/blocks/drawnBlocks.js

@@ -0,0 +1,47 @@
+/**
+ * Which blocks are drawn on which screen now. A block's `useControl` reports
+ * it while mounted, and the bridge tells the viewer, so the form shows a
+ * section for each. A block drawn twice on one screen counts once; a screen
+ * keeps its blocks in the order they were first reported.
+ */
+const drawn = new Map();
+const listeners = new Set();
+let snapshot = new Map();
+function changed() {
+    snapshot = new Map([...drawn].map(([screen, blocks]) => [screen, [...blocks.keys()]]));
+    for (const listener of listeners) {
+        listener();
+    }
+}
+/** Reports a block as drawn on a screen; the returned function takes it out. */
+export function reportBlock(screen, block) {
+    let blocks = drawn.get(screen);
+    if (!blocks) {
+        blocks = new Map();
+        drawn.set(screen, blocks);
+    }
+    const count = blocks.get(block) ?? 0;
+    blocks.set(block, count + 1);
+    if (count === 0) {
+        changed();
+    }
+    const on = blocks;
+    return () => {
+        const now = on.get(block) ?? 0;
+        if (now > 1) {
+            on.set(block, now - 1);
+        }
+        else if (now === 1) {
+            on.delete(block);
+            changed();
+        }
+    };
+}
+/** Every screen that has had blocks, with the ones drawn there now. The same object until one changes. */
+export const blocksNow = () => snapshot;
+export function subscribeBlocks(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/blocks/screenContext.d.ts

@@ -0,0 +1,2 @@
+/** The screen a component is drawn on, from the nearest `<ScreenScope>`. */
+export declare const ScreenContext: import("react").Context<string | null>;

package/dist/blocks/screenContext.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+/** The screen a component is drawn on, from the nearest `<ScreenScope>`. */
+export const ScreenContext = createContext(null);

package/dist/bridge/Bridge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Talks to the viewer; mounted once at the app's root. In the viewer's frame
+ * it says `hello` with the manifest, and again whenever asked; sends `at`,
+ * `blocks` and `values` as they change, and `tone` and `height`; does what
+ * the viewer asks (`go`, `set`, `reset`), scrolling to the marked part after
+ * `set` or `reset`; and lays the app out for the `device`. Outside a frame it
+ * only takes `?at=` from the address.
+ */
+export declare function Bridge(): null;

package/dist/bridge/Bridge.js

@@ -0,0 +1,120 @@
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+import { blocksNow, subscribeBlocks } from '../blocks/drawnBlocks.js';
+import { resetAll, resetValue, setValue, subscribeValues, valuesNow } from '../controls/store.js';
+import { registeredApp } from '../define/registeredApp.js';
+import { PROTOCOL } from '../protocol/protocol.js';
+import { applyDevice } from './device.js';
+import { isFramed, post } from './post.js';
+import { readViewerMessage } from './readViewerMessage.js';
+import { revealControl } from './revealControl.js';
+import { watchScreen } from './watchScreen.js';
+const nothingSent = () => ({ at: null, values: null, blocks: new Map() });
+/** Tells the viewer what changed since it was last told; `answer` sends `values` even when it didn't. */
+function sync(sent, now, answer = false) {
+    const at = JSON.stringify([now.at.screen, now.at.state]);
+    if (at !== sent.at) {
+        sent.at = at;
+        post({ type: 'at', screen: now.at.screen, state: now.at.state });
+    }
+    const values = JSON.stringify(now.values);
+    if (answer || values !== sent.values) {
+        sent.values = values;
+        post({ type: 'values', values: { ...now.values } });
+    }
+    for (const [screen, blocks] of now.blocks) {
+        const list = JSON.stringify(blocks);
+        if (list !== sent.blocks.get(screen)) {
+            sent.blocks.set(screen, list);
+            post({ type: 'blocks', screen, blocks: [...blocks] });
+        }
+    }
+}
+function useApp() {
+    const app = registeredApp();
+    if (!app) {
+        throw new Error('workbench-client: <Bridge /> needs the app declared with defineApp first.');
+    }
+    return app;
+}
+/**
+ * Talks to the viewer; mounted once at the app's root. In the viewer's frame
+ * it says `hello` with the manifest, and again whenever asked; sends `at`,
+ * `blocks` and `values` as they change, and `tone` and `height`; does what
+ * the viewer asks (`go`, `set`, `reset`), scrolling to the marked part after
+ * `set` or `reset`; and lays the app out for the `device`. Outside a frame it
+ * only takes `?at=` from the address.
+ */
+export function Bridge() {
+    const app = useApp();
+    const navigation = app.useNavigation();
+    const latest = useRef(navigation);
+    const values = useSyncExternalStore(subscribeValues, valuesNow, valuesNow);
+    const blocks = useSyncExternalStore(subscribeBlocks, blocksNow, blocksNow);
+    const sent = useRef(nothingSent());
+    const { screen, state } = navigation.at;
+    useEffect(() => {
+        latest.current = navigation;
+    });
+    useEffect(() => {
+        const at = new URLSearchParams(window.location.search).get('at');
+        if (at) {
+            latest.current.go(at);
+        }
+    }, []);
+    useEffect(() => {
+        if (!isFramed()) {
+            return;
+        }
+        const now = () => ({ at: latest.current.at, values: valuesNow(), blocks: blocksNow() });
+        const hello = () => {
+            post({ type: 'hello', protocol: PROTOCOL, manifest: app.manifest });
+            sent.current = nothingSent();
+            sync(sent.current, now());
+        };
+        const onMessage = (event) => {
+            if (event.source !== window.parent) {
+                return;
+            }
+            const message = readViewerMessage(event.data);
+            switch (message?.type) {
+                case 'hello':
+                    hello();
+                    break;
+                case 'go':
+                    latest.current.go(message.state);
+                    break;
+                case 'set':
+                    if (setValue(message.id, message.value)) {
+                        sync(sent.current, now(), true);
+                        revealControl(message.id);
+                    }
+                    break;
+                case 'reset':
+                    if (message.id === undefined) {
+                        resetAll();
+                        sync(sent.current, now(), true);
+                    }
+                    else if (resetValue(message.id)) {
+                        sync(sent.current, now(), true);
+                        revealControl(message.id);
+                    }
+                    break;
+                case 'device':
+                    applyDevice(message);
+                    break;
+            }
+        };
+        window.addEventListener('message', onMessage);
+        hello();
+        return () => {
+            window.removeEventListener('message', onMessage);
+        };
+    }, [app]);
+    useEffect(() => {
+        if (isFramed()) {
+            sync(sent.current, { at: { screen, state }, values, blocks });
+        }
+    }, [screen, state, values, blocks]);
+    useEffect(() => (isFramed() ? watchScreen(post) : undefined), []);
+    return null;
+}

package/dist/bridge/device.d.ts

@@ -0,0 +1,6 @@
+import type { DeviceMessage } from '../protocol/types.js';
+export declare function applyDevice(message: DeviceMessage): void;
+/** Whether the viewer shows the app on Full page. */
+export declare const isWhole: () => boolean;
+/** Who hears that the device changed: the screen watcher, while the bridge runs. */
+export declare function onDeviceChange(listener: (() => void) | null): void;

package/dist/bridge/device.js

@@ -0,0 +1,28 @@
+/**
+ * The device the viewer draws round the app. Its insets become
+ * `--safe-top` and `--safe-bottom` in px; until a `device` arrives, the
+ * app's own CSS holds the first phone's. Its platform becomes
+ * `html[data-platform]`. On Full page (`whole`) there is no device, and the
+ * app reports how tall the open screen is laid out whole.
+ */
+let whole = false;
+let onChange = null;
+export function applyDevice(message) {
+    const root = document.documentElement;
+    root.style.setProperty('--safe-top', `${Math.max(0, message.insets.top)}px`);
+    root.style.setProperty('--safe-bottom', `${Math.max(0, message.insets.bottom)}px`);
+    if (message.platform) {
+        root.setAttribute('data-platform', message.platform);
+    }
+    else {
+        root.removeAttribute('data-platform');
+    }
+    whole = message.whole;
+    onChange?.();
+}
+/** Whether the viewer shows the app on Full page. */
+export const isWhole = () => whole;
+/** Who hears that the device changed: the screen watcher, while the bridge runs. */
+export function onDeviceChange(listener) {
+    onChange = listener;
+}

package/dist/bridge/post.d.ts

@@ -0,0 +1,5 @@
+import type { AppSays } from '../protocol/types.js';
+/** Says something to the viewer around the frame, tagged as the app's. */
+export declare function post(message: AppSays): void;
+/** Whether the app is in the viewer's frame, rather than a page of its own. */
+export declare const isFramed: () => boolean;

package/dist/bridge/post.js

@@ -0,0 +1,8 @@
+import { FROM_APP } from '../protocol/protocol.js';
+/** Says something to the viewer around the frame, tagged as the app's. */
+export function post(message) {
+    const tagged = { source: FROM_APP, ...message };
+    window.parent.postMessage(tagged, '*');
+}
+/** Whether the app is in the viewer's frame, rather than a page of its own. */
+export const isFramed = () => window.parent !== window;

package/dist/bridge/readViewerMessage.d.ts

@@ -0,0 +1,3 @@
+import type { ViewerSays } from '../protocol/types.js';
+/** What the viewer said, or null for anything else posted to the window. */
+export declare function readViewerMessage(data: unknown): ViewerSays | null;

package/dist/bridge/readViewerMessage.js

@@ -0,0 +1,44 @@
+import { FROM_VIEWER } from '../protocol/protocol.js';
+const isValue = (value) => ['string', 'number', 'boolean'].includes(typeof value);
+/** What the viewer said, or null for anything else posted to the window. */
+export function readViewerMessage(data) {
+    if (typeof data !== 'object' || data === null) {
+        return null;
+    }
+    const message = data;
+    if (message['source'] !== FROM_VIEWER) {
+        return null;
+    }
+    switch (message['type']) {
+        case 'hello':
+            return { type: 'hello' };
+        case 'go':
+            return typeof message['state'] === 'string' ? { type: 'go', state: message['state'] } : null;
+        case 'set':
+            return typeof message['id'] === 'string' && isValue(message['value'])
+                ? { type: 'set', id: message['id'], value: message['value'] }
+                : null;
+        case 'reset':
+            if (message['id'] === undefined) {
+                return { type: 'reset' };
+            }
+            return typeof message['id'] === 'string' ? { type: 'reset', id: message['id'] } : null;
+        case 'device':
+            return readDevice(message);
+        default:
+            return null;
+    }
+}
+function readDevice(message) {
+    const insets = message['insets'];
+    const platform = message['platform'];
+    if (typeof insets?.top !== 'number' || typeof insets.bottom !== 'number') {
+        return null;
+    }
+    return {
+        type: 'device',
+        insets: { top: insets.top, bottom: insets.bottom },
+        platform: platform === 'ios' || platform === 'android' ? platform : null,
+        whole: message['whole'] === true,
+    };
+}

package/dist/bridge/revealControl.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shows what a control changes: after the viewer sets or resets one, the
+ * screen scrolls to the first part on show marked with it
+ * (`data-control="<id> …"`). A control with no marked part scrolls nothing.
+ * A mark may sit on a `display: contents` wrapper; then its first child with
+ * a box is what is shown.
+ */
+/** The first part marked with the control that is on show; a hidden tab's has no box. */
+export declare function firstShown(id: string): HTMLElement | null;
+export declare function revealControl(id: string): void;

package/dist/bridge/revealControl.js

@@ -0,0 +1,62 @@
+/**
+ * Shows what a control changes: after the viewer sets or resets one, the
+ * screen scrolls to the first part on show marked with it
+ * (`data-control="<id> …"`). A control with no marked part scrolls nothing.
+ * A mark may sit on a `display: contents` wrapper; then its first child with
+ * a box is what is shown.
+ */
+const ROOM = 72;
+function boxOf(element) {
+    if (getComputedStyle(element).display !== 'contents') {
+        return element.getClientRects().length > 0 ? element : null;
+    }
+    for (const child of Array.from(element.children)) {
+        const box = boxOf(child);
+        if (box) {
+            return box;
+        }
+    }
+    return null;
+}
+/** The first part marked with the control that is on show; a hidden tab's has no box. */
+export function firstShown(id) {
+    for (const element of document.querySelectorAll(`[data-control~="${CSS.escape(id)}"]`)) {
+        const box = boxOf(element);
+        if (box) {
+            return box;
+        }
+    }
+    return null;
+}
+function scrollerOf(element) {
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        const { overflowY } = getComputedStyle(parent);
+        if ((overflowY === 'auto' || overflowY === 'scroll') &&
+            parent.scrollHeight > parent.clientHeight) {
+            return parent;
+        }
+    }
+    return null;
+}
+/** A part can ask for more room above it with CSS `scroll-margin-top`. */
+function bring(scroller, target) {
+    const room = Math.max(ROOM, parseFloat(getComputedStyle(target).scrollMarginTop) || 0);
+    const top = scroller.scrollTop +
+        target.getBoundingClientRect().top -
+        scroller.getBoundingClientRect().top -
+        room;
+    const behavior = matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';
+    scroller.scrollTo({ top: Math.max(0, top), behavior });
+}
+export function revealControl(id) {
+    // Two frames: the change draws first, and a block may only now exist.
+    requestAnimationFrame(() => {
+        return requestAnimationFrame(() => {
+            const part = firstShown(id);
+            const scroller = part && scrollerOf(part);
+            if (part && scroller) {
+                bring(scroller, part);
+            }
+        });
+    });
+}

package/dist/bridge/toneAtTop.d.ts

@@ -0,0 +1,3 @@
+import type { Tone } from '../protocol/types.js';
+/** Light or dark: the first solid colour under where the status bar's clock sits. */
+export declare function toneAtTop(): Tone;

package/dist/bridge/toneAtTop.js

@@ -0,0 +1,23 @@
+/** The red, green and blue of a computed colour, when it is mostly opaque. */
+function solid(colour) {
+    const parts = colour.match(/[\d.]+/g);
+    if (!parts || (parts.length >= 4 && Number(parts[3]) <= 0.5)) {
+        return null;
+    }
+    return parts.slice(0, 3).map(Number);
+}
+/** Light or dark: the first solid colour under where the status bar's clock sits. */
+export function toneAtTop() {
+    if (typeof document.elementsFromPoint !== 'function') {
+        return 'light';
+    }
+    const top = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--safe-top')) || 20;
+    for (const element of document.elementsFromPoint(24, top / 2)) {
+        const rgb = solid(getComputedStyle(element).backgroundColor);
+        if (rgb) {
+            const [red = 0, green = 0, blue = 0] = rgb;
+            return (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255 < 0.5 ? 'dark' : 'light';
+        }
+    }
+    return 'light';
+}

package/dist/bridge/watchScreen.d.ts

@@ -0,0 +1,10 @@
+import type { AppSays } from '../protocol/types.js';
+type Report = (message: Extract<AppSays, {
+    type: 'tone' | 'height';
+}>) => void;
+/**
+ * Tells the viewer the tone at the top of the screen and, on Full page, the
+ * screen's height, whenever either changes. Returns how to stop.
+ */
+export declare function watchScreen(report: Report): () => void;
+export {};