@wyndlass/app-sdk 1.3.0 → 1.5.0

package/dist/react.d.ts

@@ -8,6 +8,7 @@
  */
 import { type ComponentType } from "react";
 import type { DataAnswer, ScreenFacts } from "./contract/app-contract.js";
+import { type Followed } from "./following.js";
 type Params = Record<string, string | number | boolean>;
 /**
  * An element class for a component, the module's default export: `export default reactApp(Board, { css })`. `css` is
@@ -60,4 +61,23 @@ export declare function useData<T = unknown>(source: string, params: Params, eve
  * every frame, as before.
  */
 export declare function useSnapshot(table: string): unknown | null;
+/** The player's state: starting, playing, paused, stopped, idle or error. Null where the app has no controller (the designer). */
+export declare function usePlayback(): Followed<"playback">;
+/** Whether the screen is online or offline; null without a controller. */
+export declare function useConnection(): Followed<"connection">;
+/** The screen's volume and whether it is muted; null without a controller, or where the host sets no audio. */
+export declare function useAudio(): Followed<"audio">;
+/** The items playing (the status's `now`); null without a controller. */
+export declare function usePlaying(): Followed<"now">;
+/**
+ * Calls `handler` with the argument of each command of this name sent to the screen's apps (`apps.sendCommand`,
+ * WP-0150 decision 3), from mount until the component goes. The handler may change between renders: the latest is called.
+ */
+export declare function useCommand(name: string, handler: (argument: Record<string, unknown> | undefined) => void): void;
+/**
+ * Emergency messages at the screen (WP-0150 decision 5): what shows (`none`, `banner` or `takeover`) and each message's
+ * facts, never its words; the component renders when they change. Null without a controller, or before the screen has
+ * said what it holds. Under a banner the app plays on below it: it may lower its sound or pause what calls for attention.
+ */
+export declare function useEmergency(): Followed<"emergency">;
 export {};

package/dist/react.js

@@ -17,8 +17,10 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
  * React's tree (which hangs off the shadow root's nodes) holds nothing another app could use: data, images and the
  * rest go through the SDK's functions, as for any app.
  */
-import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { createRoot } from "react-dom/client";
+import { follow } from "./following.js";
+import { onCommand } from "./commands.js";
 import { contextOf, data, kept, snapshot, WyndlassApp } from "./index.js";
 const bridges = new WeakMap();
 const App = createContext(null);
@@ -169,3 +171,33 @@ export function useSnapshot(table) {
     useSyncExternalStore(subscribe, read, read);
     return snapshot(app, table);
 }
+/** A field of the player's status (WP-0150 decision 2): the component renders when its value changes, not at frames. */
+function useFollowed(field) {
+    const [app] = useBridge();
+    const f = useMemo(() => follow(app, field), [app, field]);
+    return useSyncExternalStore(f.subscribe, f.get, f.get);
+}
+/** The player's state: starting, playing, paused, stopped, idle or error. Null where the app has no controller (the designer). */
+export function usePlayback() { return useFollowed("playback"); }
+/** Whether the screen is online or offline; null without a controller. */
+export function useConnection() { return useFollowed("connection"); }
+/** The screen's volume and whether it is muted; null without a controller, or where the host sets no audio. */
+export function useAudio() { return useFollowed("audio"); }
+/** The items playing (the status's `now`); null without a controller. */
+export function usePlaying() { return useFollowed("now"); }
+/**
+ * Calls `handler` with the argument of each command of this name sent to the screen's apps (`apps.sendCommand`,
+ * WP-0150 decision 3), from mount until the component goes. The handler may change between renders: the latest is called.
+ */
+export function useCommand(name, handler) {
+    const [app] = useBridge();
+    const latest = useRef(handler);
+    latest.current = handler;
+    useEffect(() => onCommand(app, name, argument => latest.current(argument)), [app, name]);
+}
+/**
+ * Emergency messages at the screen (WP-0150 decision 5): what shows (`none`, `banner` or `takeover`) and each message's
+ * facts, never its words; the component renders when they change. Null without a controller, or before the screen has
+ * said what it holds. Under a banner the app plays on below it: it may lower its sound or pause what calls for attention.
+ */
+export function useEmergency() { return useFollowed("emergency"); }

package/dist/signals.d.ts

@@ -1,10 +1,12 @@
 /**
- * Table rows as Preact signals (WP-0149 decision 5, `@wyndlass/app-sdk/signals`): for an app that updates its DOM when its
- * rows change, in an effect, rather than at every frame. An entry of its own, so an app that does not import it does not
- * bundle it. Its signals are this copy of `@preact/signals-core`'s: take effect, computed and the rest from here too, as
- * an effect from another copy does not see them.
+ * Table rows and the player's state as Preact signals (WP-0149 decision 5, WP-0150 decision 1;
+ * `@wyndlass/app-sdk/signals`): for an app that updates its DOM when they change, in an effect, rather than at every
+ * frame. An entry of its own, so an app that does not import it does not bundle it. Its signals are this copy of
+ * `@preact/signals-core`'s: take effect, computed and the rest from here too, as an effect from another copy does not
+ * see them.
  */
 import { type ReadonlySignal } from "@preact/signals-core";
+import type { PlayerAPIStatus } from "./contract/player-api-status.js";
 import { type WyndlassApp } from "./index.js";
 export { batch, computed, effect, signal, untracked, type ReadonlySignal, type Signal } from "@preact/signals-core";
 /**
@@ -15,3 +17,25 @@ export { batch, computed, effect, signal, untracked, type ReadonlySignal, type S
  * On a player before WP-0149, which makes the app again when a table changes, it keeps the rows the app was made with.
  */
 export declare function tableSignal(app: WyndlassApp, table: string): ReadonlySignal<unknown | null>;
+/**
+ * The player's state as a read-only signal: starting, playing, paused, stopped, idle or error, set on each
+ * `state.changed`. Null where the app has no controller (the designer). Make it in mount(), where the app has its context.
+ */
+export declare function playbackSignal(app: WyndlassApp): ReadonlySignal<PlayerAPIStatus["state"] | null>;
+/** Whether the screen is online or offline, as a read-only signal set on each `connection.changed`; null without a controller. */
+export declare function connectionSignal(app: WyndlassApp): ReadonlySignal<PlayerAPIStatus["connection"] | null>;
+/**
+ * The screen's volume and whether it is muted, as a read-only signal set on each `audio.changed`. Null without a
+ * controller, or on a screen whose host sets no audio.
+ */
+export declare function audioSignal(app: WyndlassApp): ReadonlySignal<NonNullable<PlayerAPIStatus["audio"]> | null>;
+/** The items playing (the status's `now`), as a read-only signal read again on each `item.start` and `item.end`; null without a controller. */
+export declare function nowSignal(app: WyndlassApp): ReadonlySignal<PlayerAPIStatus["now"] | null>;
+/**
+ * Emergency messages at the screen, as a read-only signal set on each `emergency.changed` (WP-0150 decision 5): what
+ * shows (`none`, `banner` or `takeover`), and of each message in force its source, severity, presentation, event,
+ * categories and whether it is a test. Never its words: the screen shows them, over the app. Null without a controller,
+ * or before the screen has said what it holds. Under a banner the app plays on below it: it may lower its sound, pause
+ * what calls for attention, or show the way out. It cannot move or cover the emergency layer.
+ */
+export declare function emergencySignal(app: WyndlassApp): ReadonlySignal<NonNullable<PlayerAPIStatus["emergency"]> | null>;

package/dist/signals.js

@@ -1,10 +1,12 @@
 /**
- * Table rows as Preact signals (WP-0149 decision 5, `@wyndlass/app-sdk/signals`): for an app that updates its DOM when its
- * rows change, in an effect, rather than at every frame. An entry of its own, so an app that does not import it does not
- * bundle it. Its signals are this copy of `@preact/signals-core`'s: take effect, computed and the rest from here too, as
- * an effect from another copy does not see them.
+ * Table rows and the player's state as Preact signals (WP-0149 decision 5, WP-0150 decision 1;
+ * `@wyndlass/app-sdk/signals`): for an app that updates its DOM when they change, in an effect, rather than at every
+ * frame. An entry of its own, so an app that does not import it does not bundle it. Its signals are this copy of
+ * `@preact/signals-core`'s: take effect, computed and the rest from here too, as an effect from another copy does not
+ * see them.
  */
 import { computed, signal } from "@preact/signals-core";
+import { follow } from "./following.js";
 import { eachFrame } from "./frames.js";
 import { contextOf, snapshot } from "./index.js";
 export { batch, computed, effect, signal, untracked } from "@preact/signals-core";
@@ -28,3 +30,42 @@ export function tableSignal(app, table) {
     }
     return computed(() => rows.value);
 }
+/** A field of the player's status as a read-only signal (WP-0150 decision 1): set only when its value changes. */
+function followed(app, field) {
+    const f = follow(app, field);
+    const value = signal(f.get());
+    f.subscribe(() => { value.value = f.get(); });
+    return computed(() => value.value);
+}
+/**
+ * The player's state as a read-only signal: starting, playing, paused, stopped, idle or error, set on each
+ * `state.changed`. Null where the app has no controller (the designer). Make it in mount(), where the app has its context.
+ */
+export function playbackSignal(app) {
+    return followed(app, "playback");
+}
+/** Whether the screen is online or offline, as a read-only signal set on each `connection.changed`; null without a controller. */
+export function connectionSignal(app) {
+    return followed(app, "connection");
+}
+/**
+ * The screen's volume and whether it is muted, as a read-only signal set on each `audio.changed`. Null without a
+ * controller, or on a screen whose host sets no audio.
+ */
+export function audioSignal(app) {
+    return followed(app, "audio");
+}
+/** The items playing (the status's `now`), as a read-only signal read again on each `item.start` and `item.end`; null without a controller. */
+export function nowSignal(app) {
+    return followed(app, "now");
+}
+/**
+ * Emergency messages at the screen, as a read-only signal set on each `emergency.changed` (WP-0150 decision 5): what
+ * shows (`none`, `banner` or `takeover`), and of each message in force its source, severity, presentation, event,
+ * categories and whether it is a test. Never its words: the screen shows them, over the app. Null without a controller,
+ * or before the screen has said what it holds. Under a banner the app plays on below it: it may lower its sound, pause
+ * what calls for attention, or show the way out. It cannot move or cover the emergency layer.
+ */
+export function emergencySignal(app) {
+    return followed(app, "emergency");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyndlass/app-sdk",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Build apps for Wyndlass's screens: web components on the app contract (Player API 2), with the runtime Wyndlass's own apps use.",
   "keywords": [
     "wyndlass",

package/skill/wyndlass-app/references/contract.md

@@ -28,7 +28,8 @@ A paged app also defines `paging()`, returning `{count, ms}`, so the layout can
 - `kept(this, source, params)`: the answer the screen last kept for the same request, at once, or `undefined`. Draw it while `data` asks again, so the app is ready without the network;
 - `image(this, path)`: a picture a data answer names, as a URL the app can draw;
 - `snapshot(this, table)`: the rows of a table the layout names, in a `datatable` param or in the element's `binding`. Where a binding chooses rows (a filter, a sort, a limit), only those. `null` when the screen has no snapshot of that table. A `datatable` param needs no binding. A screen gives the app a table's new rows while it plays: read them where you draw (in `draw()`, `useSnapshot` or `tableSignal`), never once in `mount()`. They are the same object until they change, and frozen: copy rows before you sort or change them;
-- `controllerOf(this)`: the player's controller, as `capabilities.player` allows; absent in the designer and previews;
+- `controllerOf(this)`: the player's controller, as `capabilities.player` allows; absent in the designer and the CMS's previews (`wyndlass-app preview` gives a stand-in). Follow its state with the signals or hooks below, never by reading `status()` at each frame;
+- `onCommand(this, name, handler)`: each command of that name sent to the screen's apps (`apps.sendCommand`), with its argument; returns how to stop. A command is an event: the same one sent twice runs twice. Apps cannot answer one;
 - `impressionsOf(this)`: the people at the screen, for an app whose definition declares the `impressions` sensor;
 - `contextOf(this)`: the rest of the context (the screen's `place` and facts, `preview`).
 
@@ -43,16 +44,29 @@ A paged app also defines `paging()`, returning `{count, ms}`, so the layout can
 - `useNow(everyMs?)`: the layout's clock. Without `everyMs`, drawn again at each of its frames, so the component renders many times a second. With it, the time is a multiple of `everyMs` (`useNow(1000)`: whole seconds), and the component renders only when that changes: take the coarsest the app shows. Either way, make formatters and other objects with `useMemo`, never in the render;
 - `usePaging(count, ms)`: the page showing now, rendering when it turns. It also tells the host the pages;
 - `useData(source, params)`: `{answer, error}`. The kept answer at once, then the service's, asked again every 10 minutes;
-- `useSnapshot(table)`: a data table's rows, as `snapshot` gives them. The component renders when they change.
+- `useSnapshot(table)`: a data table's rows, as `snapshot` gives them. The component renders when they change;
+- `usePlayback()`, `useConnection()`, `useAudio()`, `usePlaying()`: the player's state (starting, playing, paused, stopped, idle, error), online or offline, `{volume, muted}`, and the items playing. Each renders only when its value changes; `null` without a controller;
+- `useCommand(name, handler)`: each command of that name, with its argument, while the component is mounted;
+- `useEmergency()`: emergency messages at the screen (below).
 
 ## Signals (`@wyndlass/app-sdk/signals`)
 
-For a vanilla app that updates its DOM when its rows change, rather than at every frame:
+For a vanilla app that updates its DOM when its rows or the player's state change, rather than at every frame:
 - `tableSignal(this, table)`: a read-only Preact signal of the table's snapshot, made in `mount()`. Its value changes when the rows do;
+- `playbackSignal(this)`, `connectionSignal(this)`, `audioSignal(this)`, `nowSignal(this)`: the player's state, online or offline, `{volume, muted}`, and the items playing, as read-only signals made in `mount()`. Each is set only when its value changes; `null` without a controller;
 - `effect`, `computed`, `batch`, `signal`, `untracked`: Preact's, from the same copy. Import them from here, never from `@preact/signals-core`, whose effects would not see these signals.
 
+- `emergencySignal(this)`: emergency messages at the screen (below), as a read-only signal.
+
 Draw in an `effect(() => { … rows.value … })` made in `mount()`, and leave `draw()` empty.
 
+## Emergency messages
+
+The screen shows them itself, over every app: a takeover over all of it, a banner over its bottom 14% while the app plays on above. `emergencySignal(this)` and `useEmergency()` give `{ showing, messages }`: `showing` is `none`, `banner` or `takeover`, and each message gives `source`, `severity`, `presentation`, `event` and `category` where it has them, and `test`. `null` without a controller or before the screen has said what it holds, which is not `none`.
+- **Under a banner,** lower the app's sound, stop calling numbers or pause what calls for attention, or show the way out.
+- **Never draw an alert's words,** and never try to move, cover or hide the emergency layer: the screen shows the words in one design, and the layer stays on top.
+- **Try it in the preview:** the controller's panel shows a Test banner or takeover over the app.
+
 ## The definition, `app.json`
 
 Valid against `node_modules/@wyndlass/app-sdk/protocol/app-definition.schema.json`.

package/templates/react/AGENTS.md

@@ -6,6 +6,8 @@ An app for Wyndlass's screens, on `@wyndlass/app-sdk` and React. Its README says
 - **Time:** `useNow()` gives the layout's clock, drawn again at each of its frames, and `useNow(1000)` whole seconds, rendering once a second: take the coarsest the app shows; never `Date.now()`, so a seek or a pause shows the right moment.
 - **Nothing made in a render:** the component renders at every frame, many times a second. Make formatters (`Intl.DateTimeFormat`, `Intl.NumberFormat`) and other objects with `useMemo` on what they depend on, never in the render. One made in each draw holds memory a screen does not free in time: an app that did so ran a 4 GB screen out of memory within an hour.
 - **A table's rows from `useSnapshot(table)`:** a screen gives the app a table's new rows while it plays, and the component renders when they change. Never keep a copy made once. They are frozen: copy before you sort or change them.
+- **The player's state** (playing or paused, online or offline, its sound): `usePlayback()`, `useConnection()` and `useAudio()`, which render only when it changes. **Commands** sent to the screen's apps: `useCommand(name, handler)`. A command is an event, and the app cannot answer it.
+- **Emergency messages:** the screen shows them over the app itself. `useEmergency()` says what shows: under a banner the app plays on, so lower its sound or pause what calls for attention. Never draw an alert's words, and never try to move, cover or hide the emergency layer. Try it in the preview's controller panel.
 - **Ready:** call `useApp().ready()` once drawn, within 5 s, or the screen reports the app late. `useData()` gives the answer the screen kept at once, then the service's.
 - **Data:** only through `useData(source, params)`, and only the sources `app.json`'s `data` lists. Pages: `usePaging(count, ms)`.
 - **Styles:** `src/app.css`, passed as `css`, never a `<style>`.

package/templates/vanilla/AGENTS.md

@@ -6,6 +6,8 @@ An app for Wyndlass's screens, on `@wyndlass/app-sdk`. Its README says what it i
 - **Time:** from `now()` or `draw`'s `epochMs`, never `Date.now()`, so a seek or a pause shows the right moment.
 - **Nothing made in `draw`:** it runs at every frame, many times a second. Make formatters (`Intl.DateTimeFormat`, `Intl.NumberFormat`) and other objects in `mount()`, never in `draw`. One made in each draw holds memory a screen does not free in time: an app that did so ran a 4 GB screen out of memory within an hour.
 - **A table's rows where you draw:** a screen gives the app a table's new rows while it plays. Read them with `snapshot(this, table)` in `draw`, or with `tableSignal(this, table)` and an `effect` from `@wyndlass/app-sdk/signals`, made in `mount()`. Never read them once in `mount()` and keep them. They are frozen: copy before you sort or change them.
+- **The player's state** (playing or paused, online or offline, its sound): `playbackSignal(this)`, `connectionSignal(this)` and `audioSignal(this)` from `@wyndlass/app-sdk/signals`, made in `mount()`, never `status()` read at each frame. **Commands** sent to the screen's apps: `onCommand(this, name, handler)`. A command is an event, and the app cannot answer it.
+- **Emergency messages:** the screen shows them over the app itself. `emergencySignal(this)` says what shows: under a banner the app plays on, so lower its sound or pause what calls for attention. Never draw an alert's words, and never try to move, cover or hide the emergency layer. Try it in the preview's controller panel.
 - **Ready:** call `ready()` once drawn, within 5 s, or the screen reports the app late. Draw the answer `kept()` gives at once, then ask `data()`.
 - **Data:** only through `data(this, source, params)`, and only the sources `app.json`'s `data` lists. Images a data answer names through `image(this, path)`.
 - **Styles:** `this.css(text)`, never a `<style>`. A CSS file the source imports is its text.