@wyndlass/app-sdk 1.1.1 → 1.1.3

package/README.md

@@ -135,7 +135,7 @@ export default class QueueBoard extends WyndlassApp {
 }
 ```
 
-- **`WyndlassApp`:** extend it, and write `mount()` (build the shadow DOM, once) and `draw(epochMs)` (draw that moment of the layout's clock). It gives:
+- **`WyndlassApp`:** extend it, and write `mount()` (build the shadow DOM, once) and `draw(epochMs)` (draw that moment of the layout's clock, at every frame: make formatters and other objects in `mount()`, never in `draw`). It gives:
   - `prop(name, default)`, `font()` (the font param as CSS), `now()`, `startedAt()`, `timeZone` and `locale`;
   - `css(text)`: styles for the shadow root, as a constructable stylesheet;
   - `ready()`: says the app may be shown, once, within 5 s of its start;
@@ -177,7 +177,7 @@ export default reactApp(Board, { css });
 
 - **`reactApp(Component, { css })`** makes the element's class, the module's default export. The component renders in the app's shadow root, with `css` as its styles. React is a peer dependency, and `pack` bundles it.
 - **`useApp()`:** `prop(name, default)`, `ready()`, `timeZone`, `locale`, the screen's `place` and `screen`, and `preview`.
-- **`useNow()`:** the layout's clock, drawn again at each of its frames.
+- **`useNow()`:** the layout's clock, drawn again at each of its frames. The component renders at each one, many times a second: make formatters (`Intl.DateTimeFormat`, `Intl.NumberFormat`) and other objects with `useMemo`, 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.
 - **`usePaging(count, ms)`:** the page showing now. It also tells the host the pages.
 - **`useData(source, params)`:** at once the answer the screen kept, then the service's, asked again every 10 minutes. `error` is set once an ask fails with nothing to show.
 - **`useSnapshot(table)`:** a data table's snapshot.

package/dist/index.d.ts

@@ -72,7 +72,10 @@ export declare abstract class WyndlassApp extends HTMLElement {
     protected ready(): void;
     /** Builds the app's shadow DOM, once. */
     protected abstract mount(): void;
-    /** Draws the moment `epochMs` on the layout's clock. */
+    /**
+     * Draws the moment `epochMs` on the layout's clock, at every frame: make formatters and other objects in `mount()`,
+     * never here. One made per frame holds memory a screen does not free in time.
+     */
     protected abstract draw(epochMs: number): void;
     update(epochMs: number): void;
     enter(o: HookOptions): void;

package/dist/react.d.ts

@@ -32,7 +32,11 @@ export declare function useApp(): {
     screen: ScreenFacts | null;
     preview: boolean;
 };
-/** The layout's clock, drawn again at each of its frames: seeking and pausing show the right moment. */
+/**
+ * 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.
+ */
 export declare function useNow(): number;
 /**
  * Which of `count` pages shows now, each `ms` long from the layout's start, and the pages said to the host, so a layout

package/dist/react.js

@@ -104,7 +104,11 @@ export function useApp() {
         };
     }, [app, bridge]);
 }
-/** The layout's clock, drawn again at each of its frames: seeking and pausing show the right moment. */
+/**
+ * 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.
+ */
 export function useNow() {
     const [, bridge] = useBridge();
     return useSyncExternalStore(bridge.subscribe, bridge.time, bridge.time);

package/package.json

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

@@ -75,6 +75,8 @@ Ask what should play where, and when. Then `campaign.save` at the place and time
 
 Raise `version` in `app.json`, then pack and import again (steps 4 and 5). Layouts that name no version take the new one once it is approved and checked. A layout whose app element pins a `version` (the item's) moves only when you save it with the new one: show the person first.
 
+**Where it is placed comes from `app.list`, never a guess.** Each of the organization's apps says which layouts place it and how many screens show it now. Tell the person: those layouts and screens take the new version by themselves. Asked to place or schedule it again, say where it is already, and make another layout or campaign only if they want one.
+
 ## Rules every app keeps
 
 Screens or the CMS enforce each of these:
@@ -86,6 +88,8 @@ Screens or the CMS enforce each of these:
 - **Data only from the sources `app.json` declares,** and only those apps may read: `weather`, `news`, `image`, `calendar`.
 - **Network hosts declared truthfully** in `capabilities.network`: a person approves them.
 
+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.
+
 ## 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

@@ -10,7 +10,7 @@
 
 `class X extends WyndlassApp` (vanilla). Write two methods:
 - `mount()`: build the shadow DOM in `this.root`, once.
-- `draw(epochMs)`: show that moment of the layout's clock. The host calls it on every frame it needs, seeking and pausing included.
+- `draw(epochMs)`: show that moment of the layout's clock. The host calls it on every frame it needs, seeking and pausing included. So it runs many times a second: make formatters and other objects in `mount()`, never here.
 
 It gives the element:
 - `prop(name, default)`: a param's value, or the default when it is absent or empty;
@@ -40,7 +40,7 @@ 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;
+- `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;
 - `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.

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

@@ -42,7 +42,7 @@ It answers `<zip>: uploaded (<n> bytes). Import it with app.import.` Never read
 
 ## 4. `app.list`
 
-Lists Wyndlass's apps, then the organization's own: each with its item (`med_…`), and its newest versions, each:
+Lists Wyndlass's apps, then the organization's own: each with its item (`med_…`), the layouts that place it ("Placed in 1 layout: Lobby (med_…)", or "Placed in no layout you may read"), how many screens show it now, and its newest versions, each:
 - **"being checked, then approved with its import"** or **"…, then held for review":** Wyndlass is scanning and checking it. Call `app.list` again in a little while;
 - **"refused by its checks: <reason>":** fix the cause ([contract.md](contract.md), Limits), raise `version`, pack and import again;
 - **"held for review: a person approves it in the CMS":** give the person the link `app.import` gave, and say why it is held. Wait for them; never approve it yourself;
@@ -80,6 +80,7 @@ Ask what should play where, and when. Never at the organization's top place unle
 2. Import it: steps 1 to 4.
 3. **Layouts that name no version** (`app: {"id": "med_…"}`) take the new one once it is approved and checked.
 4. **A layout that pins one** (`app: {"id": "med_…", "version": <n>}`, the item's version) keeps it. To move it, `layout.save` with the new item version, after showing the person the change.
+5. **Say where it plays from `app.list`:** its layouts and its screens now. They need no new layout or campaign. Make one only when the person asks for another, after telling them where the app is already.
 
 ## When a screen doesn't show it
 

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

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

package/templates/react/AGENTS.md

@@ -4,6 +4,7 @@ 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; 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.
 - **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/react/src/app.tsx

@@ -15,6 +15,7 @@ function Board() {
   // 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).
   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

@@ -4,6 +4,7 @@ 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.
 - **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.