@wyndlass/app-sdk 1.2.0 → 1.4.0

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);
@@ -149,9 +151,47 @@ export function useData(source, params, everyMs = 10 * 60000) {
     }, [app, key, everyMs]);
     return state.key === key ? { answer: state.answer, error: state.error } : { answer: kept(app, source, params) };
 }
-/** A data table's snapshot, as snapshot() gives it (null when the screen has none), read again each frame the layout draws: a bound table's rows change with time. */
+/**
+ * A data table's snapshot, as snapshot() gives it (null when the screen has none). On a player that says when a table
+ * changes (onSnapshot, WP-0149), it renders when the rows do: when the screen says so, or when a binding's rows, chosen
+ * on the layout's clock, change. On an older player, which makes the app again when a table changes, it reads them at
+ * every frame, as before.
+ */
 export function useSnapshot(table) {
-    const [app] = useBridge();
-    useNow();
+    const [app, bridge] = useBridge();
+    const live = typeof contextOf(app)?.onSnapshot === "function";
+    // Each frame, and each change the screen says (it may come while the layout is held).
+    const subscribe = useCallback((listener) => {
+        const off = bridge.subscribe(listener);
+        const unheard = contextOf(app)?.onSnapshot?.(() => listener());
+        return () => { off(); unheard?.(); };
+    }, [app, bridge]);
+    // Live, the rows are the same object until they change; an older player's are a new object at each read, so its frames decide.
+    const read = useCallback(() => live ? snapshot(app, table) : bridge.time(), [app, bridge, live, 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]);
+}

package/dist/signals.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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";
+/**
+ * A data table's snapshot, as snapshot() gives it, as a read-only signal: its value changes when the rows do, and is the
+ * same object until then. Read again when the screen says the table changed, and at each frame, since a binding's rows
+ * are chosen on the layout's clock (WP-0137). Make it in mount(), where the app has its context.
+ *
+ * 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>;

package/dist/signals.js

@@ -0,0 +1,61 @@
+/**
+ * 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";
+/**
+ * A data table's snapshot, as snapshot() gives it, as a read-only signal: its value changes when the rows do, and is the
+ * same object until then. Read again when the screen says the table changed, and at each frame, since a binding's rows
+ * are chosen on the layout's clock (WP-0137). Make it in mount(), where the app has its context.
+ *
+ * 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 function tableSignal(app, table) {
+    const rows = signal(snapshot(app, table));
+    const context = contextOf(app);
+    if (context?.onSnapshot) {
+        // The same object while the rows are the same: set only when another comes.
+        const read = () => { const next = snapshot(app, table); if (next !== rows.peek())
+            rows.value = next; };
+        context.onSnapshot(changed => { if (changed === table)
+            read(); });
+        eachFrame(app, read);
+    }
+    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");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyndlass/app-sdk",
-  "version": "1.2.0",
+  "version": "1.4.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",
@@ -33,6 +33,10 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
     },
+    "./signals": {
+      "types": "./dist/signals.d.ts",
+      "import": "./dist/signals.js"
+    },
     "./app-definition.schema.json": "./protocol/app-definition.schema.json",
     "./common.schema.json": "./protocol/common.schema.json"
   },
@@ -49,6 +53,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@preact/signals-core": "1.14.5",
     "acorn": "8.19.0",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1",

package/skill/wyndlass-app/SKILL.md

@@ -91,6 +91,8 @@ Screens or the CMS enforce each of these:
 
 One more, which nothing enforces: **make nothing in a draw.** `draw(epochMs)` and a React component run again at every frame, many times a second. Make formatters (`Intl.DateTimeFormat`, `Intl.NumberFormat`) and other objects once: in `mount()`, or with `useMemo` on what they depend on. 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.
 
+And **read a table's rows where you draw,** never once in `mount()`: a screen gives the app a table's new rows while it plays, within about a second of the save. Use `snapshot(this, table)` in `draw()`, `useSnapshot(table)` in a component, or `tableSignal(this, table)` with an `effect` (`@wyndlass/app-sdk/signals`). The rows are frozen: copy them before you sort or change them.
+
 ## When something goes wrong
 
 - **A tool you need is missing:** call `whoami`. The import tools are listed only while the organization has imported apps turned on at its top place. An Owner or Admin turns them on in the CMS, under **Settings**, **Imported apps**.

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

@@ -27,8 +27,9 @@ A paged app also defines `paging()`, returning `{count, ms}`, so the layout can
 - `data(this, source, params)`: the data service's answer, a promise. Only for sources `app.json`'s `data` lists;
 - `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;
-- `controllerOf(this)`: the player's controller, as `capabilities.player` allows; absent in the designer and previews;
+- `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 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,7 +44,18 @@ 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, read again each frame.
+- `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.
+
+## Signals (`@wyndlass/app-sdk/signals`)
+
+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.
+
+Draw in an `effect(() => { … rows.value … })` made in `mount()`, and leave `draw()` empty.
 
 ## The definition, `app.json`
 

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

@@ -29,10 +29,11 @@ Two pages, eight seconds each: a heading and the time, then the weather for the
 1. **Change `app.json` first:** the `params` people set in the designer (each with a `label` and a `default`), the `data` sources it reads, and `capabilities` if it asks for more.
 2. **Read each param** with `prop(name, default)` (vanilla) or `useApp().prop(name, default)` (react), with the same default as `app.json`.
 3. **Draw from the layout's clock:** vanilla's `draw(epochMs)` gets the moment; react's `useNow()` gives it, and `useNow(1000)` gives whole seconds, rendering once a second. Work out what changes with time (a page, a countdown, a clock) from that number, never from a timer of your own. Both run at every frame: make a formatter once, as the templates do (`#format` in `mount()`, `useMemo` in react), never in the draw.
-4. **Say `ready()`** as soon as the app has something to show, within 5 s: the kept answer, a default, or the failure.
-5. **Styles** go in `src/app.css`. Size text to the box with `fit()` or the `--w` and `--h` properties ([contract.md](contract.md)), since screens run from 1080p to 4K.
-6. **Images:** import them from `src/` (`import logo from "./logo.png"`: PNG, JPEG, GIF, WebP or SVG), and `pack` inlines each as a data URL, for an `<img>`'s `src` or a style set from code. A `url()` inside `src/app.css` is not bundled.
-7. **Fonts:** give the app a param named `font`, of the kind `font`, so the person picks a font in the designer. Apply it as CSS with `font()` (vanilla), or `typographyCss(app.prop("font", null))` (react) ([contract.md](contract.md)).
-8. **Delete what the template drew** that the person did not ask for, its weather included, and its `data` entry with it.
+4. **Read a table's rows where you draw,** for an app with a `datatable` param: `snapshot(this, table)` in `draw()`, `tableSignal(this, table)` with an `effect` (vanilla, `@wyndlass/app-sdk/signals`), or `useSnapshot(table)` (react). A screen gives the app a table's new rows while it plays, so a copy kept from `mount()` goes stale. The rows are frozen: copy before you sort them. In the preview, edit a table's rows and check the app follows without being made again.
+5. **Say `ready()`** as soon as the app has something to show, within 5 s: the kept answer, a default, or the failure.
+6. **Styles** go in `src/app.css`. Size text to the box with `fit()` or the `--w` and `--h` properties ([contract.md](contract.md)), since screens run from 1080p to 4K.
+7. **Images:** import them from `src/` (`import logo from "./logo.png"`: PNG, JPEG, GIF, WebP or SVG), and `pack` inlines each as a data URL, for an `<img>`'s `src` or a style set from code. A `url()` inside `src/app.css` is not bundled.
+8. **Fonts:** give the app a param named `font`, of the kind `font`, so the person picks a font in the designer. Apply it as CSS with `font()` (vanilla), or `typographyCss(app.prop("font", null))` (react) ([contract.md](contract.md)).
+9. **Delete what the template drew** that the person did not ask for, its weather included, and its `data` entry with it.
 
 Each source change redraws the preview. `npm run typecheck` and `npm run check` find mistakes before the person sees them.

package/templates/react/AGENTS.md

@@ -5,6 +5,8 @@ An app for Wyndlass's screens, on `@wyndlass/app-sdk` and React. Its README says
 - **The module is `src/app.tsx`;** its default export is `reactApp(Component, { css })`, the element's class. The component renders in the app's shadow root.
 - **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.
 - **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

@@ -5,6 +5,8 @@ An app for Wyndlass's screens, on `@wyndlass/app-sdk`. Its README says what it i
 - **The module is `src/app.ts`;** its default export is the element's class, extending `WyndlassApp`. `mount()` builds the shadow DOM once; `draw(epochMs)` draws that moment of the layout's clock.
 - **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.
 - **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.