@wyndlass/app-sdk 1.1.3 → 1.3.0

package/dist/react.js

@@ -17,7 +17,7 @@ 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, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
 import { createRoot } from "react-dom/client";
 import { contextOf, data, kept, snapshot, WyndlassApp } from "./index.js";
 const bridges = new WeakMap();
@@ -105,23 +105,27 @@ export function useApp() {
     }, [app, bridge]);
 }
 /**
- * The layout's clock, drawn again at each of its frames: seeking and pausing show the right moment. The component renders
- * at each one, so make formatters and other objects with `useMemo`, never in the render: one made per frame holds memory a
- * screen does not free in time.
+ * The layout's clock: seeking and pausing show the right moment. Without `everyMs`, the component renders again at each
+ * of the layout's frames, 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, as a seek to another moment does (WP-0147 decision 2).
+ * Take the coarsest the app shows. Either way, make formatters and other objects with `useMemo`, never in the render: one
+ * made per frame holds memory a screen does not free in time.
  */
-export function useNow() {
+export function useNow(everyMs) {
     const [, bridge] = useBridge();
-    return useSyncExternalStore(bridge.subscribe, bridge.time, bridge.time);
+    const step = everyMs !== undefined && everyMs > 0 ? everyMs : 0;
+    const read = useCallback(() => step ? Math.floor(bridge.time() / step) * step : bridge.time(), [bridge, step]);
+    return useSyncExternalStore(bridge.subscribe, read, read);
 }
 /**
  * Which of `count` pages shows now, each `ms` long from the layout's start, and the pages said to the host, so a layout
- * can turn its enter and exit with them (ADR 0071, decision 5).
+ * can turn its enter and exit with them (ADR 0071, decision 5). The component renders when the page turns (WP-0147).
  */
 export function usePaging(count, ms) {
     const [, bridge] = useBridge();
-    const now = useNow();
+    const read = useCallback(() => count > 1 && ms > 0 ? Math.floor(Math.max(0, bridge.time() - bridge.startedAt()) / ms) % count : 0, [bridge, count, ms]);
     useEffect(() => { bridge.setPaging(count > 1 && ms > 0 ? { count, ms } : null); }, [bridge, count, ms]);
-    return count > 1 && ms > 0 ? Math.floor(Math.max(0, now - bridge.startedAt()) / ms) % count : 0;
+    return useSyncExternalStore(bridge.subscribe, read, read);
 }
 /**
  * A data source's answer (one the definition declares): the one the screen kept, at once, then the service's; asked
@@ -145,9 +149,23 @@ 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);
 }

package/dist/signals.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+import { type ReadonlySignal } from "@preact/signals-core";
+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>;

package/dist/signals.js

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+import { computed, signal } from "@preact/signals-core";
+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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyndlass/app-sdk",
-  "version": "1.1.3",
+  "version": "1.3.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

@@ -33,6 +33,7 @@ Use the `react` template unless the person asks for plain TypeScript (`vanilla`)
 - Run `npm run typecheck` and `npm run check` after each change, and fix what they say.
 - Start `npm run preview` in the background. It serves `http://127.0.0.1:5199/` on this computer only, and draws the app again on every save.
 - **Ask the person to look,** at the screen size they gave and at the other orientation: under **Screen**, set **Size** to 1920 × 1080, then 1080 × 1920. Ask them to play the clock and to pause it. Change what they ask for.
+- **Read what it makes while it plays,** the line below the report. If it says the app makes something at every frame (a formatter, a canvas, an object URL, a listener), fix it as it says before you pack: one made at every frame can run a screen out of memory.
 - **Before importing,** run `npm run preview -- --frame` once and ask them to look again. In the CMS an app runs in a sandboxed frame with no storage, cookies or parent page. An app that fails there works on screens but not in the designer. The frame is served from a second port: use a regular browser for this check, since a browser built into an agent's app may block that port (`net::ERR_BLOCKED_BY_CLIENT`), and the app then reports `app.failed: load`.
 - **Tables in the preview** are keyed as Wyndlass keys a table's columns: from their labels, lowercased, with underscores (a CSV header `Now serving` is the column `now_serving`). A `column` param holds that key, as it will on screens.
 
@@ -90,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,7 +27,7 @@ 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;
+- `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;
 - `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`).
@@ -40,10 +40,18 @@ A paged app also defines `paging()`, returning `{count, ms}`, so the layout can
 
 `export default reactApp(Component, { css })`: the element's class. The component renders in the app's shadow root, with `css` as its styles. Hooks:
 - `useApp()`: `prop(name, default)`, `ready()`, `timeZone`, `locale`, `place`, `screen`, `preview`;
-- `useNow()`: the layout's clock, drawn again at each of its frames, so the component renders many times a second: make formatters and other objects with `useMemo`, never in the render;
-- `usePaging(count, ms)`: the page showing now. It also tells the host the pages;
+- `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.
+
+## Signals (`@wyndlass/app-sdk/signals`)
+
+For a vanilla app that updates its DOM when its rows 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;
+- `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

@@ -28,11 +28,12 @@ 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. 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.
+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. **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

@@ -3,13 +3,14 @@
 An app for Wyndlass's screens, on `@wyndlass/app-sdk` and React. Its README says what it is; these are the rules.
 
 - **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; never `Date.now()`, so a seek or a pause shows the right moment.
+- **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.
 - **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>`.
 - **No `localStorage`** for anything that matters, **no secrets** in params or the module, and **network hosts declared** in `capabilities.network`.
-- **Look at it:** `npm run preview` (http://127.0.0.1:5199/), in both orientations, with the clock played and held, and once with `npm run preview -- --frame`, as the CMS runs it.
+- **Look at it:** `npm run preview` (http://127.0.0.1:5199/), in both orientations, with the clock played and held, and once with `npm run preview -- --frame`, as the CMS runs it. Below the report, it says what the app makes at every frame: fix that before packing.
 - **Before importing:** `npm run check`, then `npm run pack`. Raise `version` in `app.json` for each new version.
 - **Importing and scheduling** go through the Wyndlass MCP, with the person's approval: `app.prepareImport`, `npx wyndlass-app upload <url> dist/<zip> --header "name: value"`, `app.import`, then `app.list` until the version is ready or held. A held version waits for a person who may approve media.
 - **Never approve a version:** a person who may approve media does, in the CMS. Give them the link `app.import` answers, and say why it is held.

package/templates/react/src/app.tsx

@@ -1,5 +1,6 @@
 // __APP_NAME__: a heading and the time on one page, the weather on the next, a React component on Wyndlass's app SDK.
 // Everything it draws comes from the layout's clock (useNow()), so the designer's seek and pause show the right moment.
+// It shows whole seconds at most, so it renders once a second (useNow(1000)), not at every frame.
 import { useEffect, useMemo } from "react";
 import { color, type weather } from "@wyndlass/app-sdk";
 import { reactApp, useApp, useData, useNow, usePaging } from "@wyndlass/app-sdk/react";
@@ -10,12 +11,12 @@ const PAGE_MS = 8_000;
 
 function Board() {
   const app = useApp();
-  const now = useNow();
+  const now = useNow(1000);
   const page = usePaging(2, PAGE_MS);
   // The weather for the screen's place, or Winnipeg's where there is none (the designer's sample).
   const place = app.place ?? { lat: 49.9, lon: -97.14 };
   const { answer, error } = useData<weather.Weather>("weather", { lat: place.lat, lon: place.lon, units: app.prop("units", "metric") });
-  // Made once: the component renders at every frame, and a formatter made in each render holds memory (AGENTS.md).
+  // Made once, not in each render: a formatter made in each render holds memory (AGENTS.md).
   const time = useMemo(() => new Intl.DateTimeFormat(app.locale, { timeZone: app.timeZone, hour: "numeric", minute: "2-digit",
     ...(app.prop("seconds", false) ? { second: "2-digit" } : {}) }), [app]);
   // Ready once there is something to show: the kept answer at once, else the service's answer or its failure.

package/templates/vanilla/AGENTS.md

@@ -5,11 +5,12 @@ 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.
 - **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.
 - **No `localStorage`** for anything that matters, **no secrets** in params or the module, and **network hosts declared** in `capabilities.network`.
-- **Look at it:** `npm run preview` (http://127.0.0.1:5199/), in both orientations, with the clock played and held, and once with `npm run preview -- --frame`, as the CMS runs it.
+- **Look at it:** `npm run preview` (http://127.0.0.1:5199/), in both orientations, with the clock played and held, and once with `npm run preview -- --frame`, as the CMS runs it. Below the report, it says what the app makes at every frame: fix that before packing.
 - **Before importing:** `npm run check`, then `npm run pack`. Raise `version` in `app.json` for each new version.
 - **Importing and scheduling** go through the Wyndlass MCP, with the person's approval: `app.prepareImport`, `npx wyndlass-app upload <url> dist/<zip> --header "name: value"`, `app.import`, then `app.list` until the version is ready or held. A held version waits for a person who may approve media.
 - **Never approve a version:** a person who may approve media does, in the CMS. Give them the link `app.import` answers, and say why it is held.