@wyndlass/app-sdk 0.0.0 → 1.1.0

package/protocol/samples/weather.json

@@ -0,0 +1,59 @@
+{
+  "place": {
+    "lat": 49.9,
+    "lon": -97.1
+  },
+  "units": "metric",
+  "timeZone": "America/Winnipeg",
+  "current": {
+    "at": "2026-10-03T22:30:00-05:00",
+    "temperature": 9.9,
+    "apparentTemperature": 7.8,
+    "condition": "clear",
+    "code": 0,
+    "isDay": false,
+    "humidity": 79,
+    "windSpeed": 8.2,
+    "windDirection": 308,
+    "precipitationProbability": 0
+  },
+  "daily": [
+    {
+      "date": "2026-10-03",
+      "high": 17.1,
+      "low": 9.5,
+      "condition": "drizzle",
+      "code": 51,
+      "precipitationProbability": 34,
+      "sunrise": "2026-10-03T07:31:00-05:00",
+      "sunset": "2026-10-03T19:01:00-05:00"
+    },
+    {
+      "date": "2026-10-04",
+      "high": 16.5,
+      "low": 5.1,
+      "condition": "mostly-clear",
+      "code": 1,
+      "precipitationProbability": 0,
+      "sunrise": "2026-10-04T07:33:00-05:00",
+      "sunset": "2026-10-04T18:59:00-05:00"
+    },
+    {
+      "date": "2026-10-05",
+      "high": 17.9,
+      "low": 3.9,
+      "condition": "cloudy",
+      "code": 3,
+      "precipitationProbability": 1,
+      "sunrise": "2026-10-05T07:34:00-05:00",
+      "sunset": "2026-10-05T18:57:00-05:00"
+    }
+  ],
+  "facts": {
+    "temperatureC": 9.9,
+    "condition": "clear",
+    "precipitationProbability": 0,
+    "windKph": 8.2,
+    "alertActive": false
+  }
+}

package/skill/wyndlass-app/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: wyndlass-app
+description: Build an app for Wyndlass's digital signage screens with @wyndlass/app-sdk, preview it, check and pack it, then import, place and schedule it through the Wyndlass MCP. Use when the person wants their own app, widget or live element on their Wyndlass screens, or wants to change one built with @wyndlass/app-sdk.
+---
+
+# Build a Wyndlass app
+
+An app is a web component that Wyndlass's screens run inside a layout: one ES2020 module and its definition, `app.json`. You build it on this computer with `@wyndlass/app-sdk`, the person's organization imports it, and a person reviews it before screens play it.
+
+Work through the steps in order. Ask before anything that changes Wyndlass: importing, placing in a layout, scheduling.
+
+## 1. Ask
+
+Before writing code, ask the person, in one message:
+- **What it shows, and to whom:** the content, and who reads it from how far away (a queue board read from across a room needs large type).
+- **The screens' orientation:** landscape (1920 × 1080), portrait (1080 × 1920), or both.
+- **The data it needs, and where from:** the weather, news feeds, pictures or calendars (data sources Wyndlass gives apps); a data table in Wyndlass; or the organization's own HTTPS service.
+- **Its name, and an id in their own domain,** such as `com.example.queue-board`. Ids under `com.wyndlass.` are Wyndlass's own, and are refused.
+
+## 2. Scaffold
+
+```sh
+npx @wyndlass/app-sdk create <folder> --template react --id <id> --name "<name>"
+cd <folder>
+npm install
+```
+
+Use the `react` template unless the person asks for plain TypeScript (`vanilla`). Read [references/templates.md](references/templates.md) for what each file is, and [references/contract.md](references/contract.md) before you change the code.
+
+## 3. Build and preview
+
+- Change `app.json` (its params, the data it reads, what it asks for) and `src/` to do what the person asked. Keep the rules below.
+- 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.
+- **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.
+
+## 4. Pack and check
+
+```sh
+npm run pack
+```
+
+It runs `check` first and writes `dist/<id>-<version>.zip` only when Wyndlass would take it. Its first line gives the zip's size in bytes, which the import asks for. Fix every refusal; heed the warnings (a module over 1 MiB, no `ready()`).
+
+## 5. Import, with the Wyndlass MCP
+
+Follow [references/mcp.md](references/mcp.md):
+1. `whoami`: who you act as, and in which organization. Ask the person **where** to import it (a place, from `node.list`).
+2. `app.prepareImport` with the place, the zip's file name and its size. It answers an address and headers, open for an hour.
+3. `npx wyndlass-app upload "<address>" dist/<zip> --header "<name>: <value>"`, once per header it gave, `Content-Type` included. Never pass the file's bytes through the conversation.
+4. `app.import` with the same place and the upload's id.
+5. `app.list` until the version is checked: approved, held for review, refused or rejected.
+
+- **Refused:** fix the cause in the source, raise `version` in `app.json`, pack and import again.
+- **Held:** give the person the CMS link `app.import` answered, say why it is held, and wait. A person who may approve media approves it in the CMS. You never approve.
+- **The same bytes again** are answered with the version the organization has; other bytes need a new `version`.
+
+## 6. Place it
+
+Read `guide.read` with topic `layouts`, sections `elements` and `apps`. Then, at a place the person names:
+- `layout.save` with the app's item from `app.list` (`{"type": "app", "id": …, "frame": …, "app": {"id": "med_…"}, "props": …}`), in a new layout or one they choose (`layout.get` first);
+- `layout.check`, and tell them what it says.
+
+A held version can be placed and previewed. Screens play it only once it is approved and checked.
+
+## 7. Schedule, only with the person's yes
+
+Ask what should play where, and when. Then `campaign.save` at the place and times they gave, and show them the draft. `campaign.publish` previews first: tell them what goes live where, and confirm only once they agree. Never schedule at the organization's top place unless they say so.
+
+## 8. A new version
+
+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.
+
+## Rules every app keeps
+
+Screens or the CMS enforce each of these:
+- **Time from the layout's clock:** `now()`, `draw(epochMs)` or `useNow()`, never `Date.now()`, so a seek or a pause draws the right moment.
+- **`ready()` within 5 s** of the app's start, or the screen reports it late.
+- **ES2020, one module:** `pack` takes care of it. Don't import from a CDN at run time.
+- **No `localStorage`** for anything that matters: in the CMS the app has none.
+- **No secrets** in params or the bundle: anyone who can read the layout or the app can read both.
+- **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.
+
+## 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**.
+- **A screen doesn't show the app:** `device.explainPlay` for that screen. A screen whose player is too old for imported apps leaves it out, and plays the rest of the layout.
+- **More detail:** [references/contract.md](references/contract.md) (the runtime, the definition, the limits, what screens do) and [references/mcp.md](references/mcp.md) (each tool's answer and what to do next).

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

@@ -0,0 +1,91 @@
+# The contract: the module, the definition, the limits
+
+## The module
+
+- **One ES2020 module,** whose default export is the element's class. `pack` bundles and minifies it into `app.js`.
+- **The host defines the class under a tag of its own** (the definition's `element`, a hyphen and a suffix) and hands it its context once, before it joins the page. Never call `customElements.define` or the SDK's `define()`: the host does it.
+- **It imports nothing at run time.** `pack` bundles everything the source imports.
+
+## The runtime (`@wyndlass/app-sdk`)
+
+`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.
+
+It gives the element:
+- `prop(name, default)`: a param's value, or the default when it is absent or empty;
+- `now()`, `startedAt()`, `timeZone`, `locale`;
+- `css(text)`: styles for the shadow root, as a constructable stylesheet. Call it from `mount()`;
+- `font()`: the `font` param as CSS;
+- `ready()`: the app may be shown. Once, within 5 s of its start;
+- `--w` and `--h`: CSS properties with the box's size, for `fit()`;
+- the enter and exit presets the layout gives (fade, scale, slide-up, slide-left). Return the items to stagger from `staggered()`.
+
+A paged app also defines `paging()`, returning `{count, ms}`, so the layout can turn its enter and exit with the pages.
+
+**What reads or acts for the app is a function that takes it,** so another app on the page can't use it:
+- `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)`: a data table's rows, as the layout's binding chooses them, or `null`;
+- `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`).
+
+**Helpers:** `fit(ofHeight, ofWidth)` (a CSS size fitted to the box), `typographyCss(value)`, `color(value, fallback)`, `escape(text)`, and the presets' curves `easingOf`, `cubicBezier`, `staggerTimes`. `@wyndlass/app-sdk/qr` has `qrModules(text)`, a QR code drawn without the network.
+
+**Types:** `AppContext`, `DataAnswer<T>`, `HookOptions`, `AppDefinition`, and each data source's answer as a namespace: `weather.Weather`, `news`, `calendar`, `tables`.
+
+## React (`@wyndlass/app-sdk/react`)
+
+`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;
+- `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.
+
+## The definition, `app.json`
+
+Valid against `node_modules/@wyndlass/app-sdk/protocol/app-definition.schema.json`.
+- **Required:** `id` (reverse-domain, in the organization's own domain, never `com.wyndlass.`), `version` (semver), `name`, `element` (lowercase, with a hyphen).
+- `description`.
+- **`params`:** what a person sets in the designer. Each has a `type` (`string`, `text`, `number`, `boolean`, `enum`, `color`, `font`, `media`, `location`, `datetime`, `duration`, `url`, `datatable`, `column`, `json`), and may have a `label`, `default`, `values` (an enum's choices, or suggestions), `group`, `required`, `min`, `max`, `step`, `help`, `advanced` and `when` (the params it depends on). A `url` param's values and default must be `https`.
+- **`data`:** the data sources it reads: `weather`, `news`, `image`, `calendar`. Imported apps may read no others.
+- **`capabilities`:**
+  - `player`: `read` (the default) or `control` (playback, audio and display commands);
+  - `sensors`: `["impressions"]` for the people at the screen;
+  - `audio`: true if it plays sound;
+  - `network`: every host it fetches from, such as `api.example.com`. A person sees them when approving it.
+
+  Asking for more than the approved version (control, a new sensor, audio, a new host) holds the new version for review.
+- **`slots`** (the fields a table's row fills, bound by the layout) and **`animation`** (the presets its enter and exit take).
+
+## Limits
+
+- The zip: at most 6 MiB, holding exactly `app.json` (at most 256 KiB) and `app.js` (at most 5 MiB).
+- `check` warns, refusing nothing, of a module over 1 MiB (screens load it at every start) and of no `ready()` in the sources.
+
+`check` and `pack` refuse with a code, the same as Wyndlass's import:
+
+| Code | Fix |
+|---|---|
+| `too-large` | Shrink the module: drop unused dependencies and large inlined images. |
+| `not-a-zip`, `encrypted`, `folder`, `path`, `entries`, `size-mismatch` | The zip wasn't made by `pack`: make it with `npm run pack`. |
+| `definition-json`, `definition-schema` | Fix `app.json`; the schema errors say where. |
+| `definition-id` | Use the organization's own domain, not `com.wyndlass.`. |
+| `definition-when` | A param's `when` names itself, or a param that doesn't exist. |
+| `definition-url` | A `url` param's values and default must be `https` addresses. |
+| `definition-peers` | Remove `capabilities.peers`: apps can't have it yet. |
+| `definition-data` | `data` lists a source apps may not read. |
+| `module-syntax`, `module-import`, `module-default` | The source doesn't build to one ES2020 module with a default export: check the default export and remove any run-time `import()`. |
+
+## What screens do
+
+- **They draw on the layout's clock:** a seek or a pause draws that moment.
+- **An app not ready within 5 s** is shown as it is, and reported late.
+- **They catch every hook.** An app that throws three times in a minute is stopped and its box emptied. The screen reports why (`load`, `shape`, `unsupported`, `error`, `late` or `overran`) with the name of what was thrown, never its message.
+- **Each app paints only in its box.** What it adds outside is removed; a dialog opens inside the box; `alert`, `confirm`, `prompt`, `print` and `window.open` do nothing.
+- **A version that hangs the page twice in an hour** is held back on that screen until its content next changes.
+- **Offline,** the app gets the answers the screen kept.
+- **In the CMS,** the app runs in a sandboxed frame of its own, with no storage, cookies or parent page, and no controller or people. `npm run preview -- --frame` shows it so.

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

@@ -0,0 +1,79 @@
+# Importing, placing and scheduling through the Wyndlass MCP
+
+Everything that touches Wyndlass goes through the person's own MCP connection, as them, with their permissions, approvals and audit. The `wyndlass-app` command signs in to nothing: `upload` only PUTs to an address the MCP gives.
+
+Tool names below are the MCP's. A client may show them with a prefix of its own (such as `mcp__wyndlass__app_import`).
+
+## Before importing
+
+- **`whoami`:** who you act as, the organization, and which toolsets this connection has. If `app.prepareImport` is missing: the import tools are listed only while imported apps are on at the organization's top place. An Owner or Admin turns them on in the CMS, under **Settings**, **Imported apps**. Tell the person; don't look for another way in.
+- **The place:** ask the person where the app goes. `node.list` with `search` finds a place's id (`node_…`). The app's item is made there on its first import, and layouts at and below it can place it. Importing needs a role that may add media at the place (Editor, Publisher, Admin or Owner). A later version goes to the app's item where it already is, and needs that role there.
+
+## 1. `app.prepareImport`
+
+`{node, fileName, bytes}`: the place, the zip's file name (`com.example.queue-board-1.0.0.zip`), and its size in bytes, which `npm run pack` printed (at most 6 MiB).
+
+It answers an upload id (`upl_…`), an HTTPS address open for an hour, and the headers to send: `Content-Type: application/zip` and the signed ones.
+
+## 2. `npx wyndlass-app upload`
+
+From the project's folder, with the address and every header the answer gave:
+
+```sh
+npx wyndlass-app upload "<address>" dist/<id>-<version>.zip --header "Content-Type: application/zip" --header "<name>: <value>"
+```
+
+It answers `<zip>: uploaded (<n> bytes). Import it with app.import.` Never read the zip into the conversation or pass its bytes to a tool. A refused PUT (an expired address, a header left out): call `app.prepareImport` again.
+
+## 3. `app.import`
+
+`{node, upload}`: the same place, and the upload's id. It answers one of:
+- **"Imported <id> <version> as med_…, version <n>."** `med_…` is the app's item, and `<n>` the item's version. Then what is next:
+  - "It is approved with its import": a later version that asks for nothing more than the approved one before it. Screens play it once its checks pass;
+  - "It is held for review": an app's first version, a version that asks for more (player control, a new sensor, audio, a new network host), or one the place's media review holds. It gives the CMS link to the app.
+- **"The workspace has <id> <version> already, with these bytes":** nothing new was made. It says where that version stands.
+- **A refusal:**
+  - "… was imported already, with other bytes. A version never changes": raise `version` in `app.json`, pack, and start again at step 1;
+  - "… is under com.wyndlass., which is Wyndlass's own": change the id;
+  - "… a new version of it needs media_item.edit on it": the person lacks the role where the app is. Tell them;
+  - "The file has not finished uploading": the PUT did not complete. Upload again.
+
+## 4. `app.list`
+
+Lists Wyndlass's apps, then the organization's own: each with its item (`med_…`), 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;
+- **"approved":** screens may play it;
+- **"rejected in review: <reason>":** tell the person the reason. Change what it says, raise `version`, and import again.
+
+## 5. Place it: `layout.save` and `layout.check`
+
+First `guide.read` with topic `layouts`, sections `elements` and `apps`: the layout document, the app element, and its props.
+
+- **An app element:** `{"type": "app", "id": "queue", "frame": {…}, "app": {"id": "med_…"}, "props": {…}}`, with the item from `app.list`. `props` are the definition's params; leave one out for its default. An imported app needs no `app.use`.
+- **A new layout:** `layout.save` with `node` (a place the person names), `name` and `document`.
+- **A change to a layout:** `layout.get`, then `layout.save` with `media`, the whole document and `expectedVersion`.
+- **`dryRun: true`** checks a document without saving it.
+- **`layout.check`** gives its load against each screen type's budget and its timeline. Tell the person what it says.
+
+A held version can be placed, and previewed in the designer, which runs it in its frame. Screens play it once it is approved and checked; until then they play the newest version before it that can play, or leave the app out.
+
+## 6. Schedule it, only with the person's yes: `campaign.save` and `campaign.publish`
+
+Ask what should play where, and when. Never at the organization's top place unless the person says so.
+
+- **`campaign.save`:** `node`, `name`, `tier` (`STANDARD` for most content), `items` (the layout's `med_…`), and the person's times: `flightStart`, `flightEnd`, and a `when`. Screens keep playing what they had until it is published.
+- **`campaign.publish`:** the first call only previews: how many screens it reaches, and a `previewHash`. Tell the person what goes live where. Call it again with `confirm: true` and that `previewHash` only once they agree. An approval policy may hold it for a person.
+- **To stop it:** `campaign.pause`.
+
+## A new version
+
+1. Raise `version` in `app.json` (semver: 1.0.0 to 1.1.0), then `npm run pack`.
+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.
+
+## When a screen doesn't show it
+
+`device.explainPlay` for the screen says what it plays and why, with notes such as a held version and the one playing for it, or "this screen's player is too old for apps you imported". Such a screen leaves imported apps out, and plays the rest of the layout, until its player is updated.

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

@@ -0,0 +1,38 @@
+# The templates and the project
+
+`npx @wyndlass/app-sdk create <folder> --template react|vanilla --id <id> --name "<name>"` makes a working app. Without `--template` it is `vanilla`; without `--id`, `com.example.<folder>`; without `--name`, a name made from the id. The element's name is the id's last part, with `-app` added when that part has no hyphen.
+
+## The project
+
+| File | What it is |
+|---|---|
+| `app.json` | The definition: `id`, `version` (starts at 0.1.0), `name`, `element`, `description`, `params`, `data`, and, when it asks for more, `capabilities`. [contract.md](contract.md) lists every field. |
+| `src/app.tsx` (react) or `src/app.ts` (vanilla) | The module. Its default export is the element's class. |
+| `src/app.css` | The app's styles. They apply only inside the app's shadow root. |
+| `src/env.d.ts` | Types for what the source imports: CSS as text, images as data URLs. |
+| `package.json` | The scripts `preview`, `check`, `pack` and `typecheck`, and `@wyndlass/app-sdk`. |
+| `tsconfig.json` | TypeScript's options: ES2020, strict. |
+| `README.md`, `AGENTS.md` | The commands, and the rules screens hold the app to. |
+| `.gitignore` | Leaves out `node_modules/` and `dist/`. |
+
+`npm run pack` writes `dist/<id>-<version>.zip` and its source map, `dist/<id>-<version>.js.map`, beside it. Only the zip is imported.
+
+## What the template app does
+
+Two pages, eight seconds each: a heading and the time, then the weather for the screen's place. Its params are one of each of four kinds: `heading` (string), `accent` (color), `units` (enum: metric or imperial) and `seconds` (boolean). It reads one data source, `weather`.
+
+- **react:** `function Board()` renders both pages and hides the one not showing. `useNow()` gives the time, `usePaging(2, 8000)` the page, `useData("weather", …)` the weather (the kept answer at once, then the service's), and `useApp()` the props, the locale and the time zone. `ready()` is called once there is an answer or an error.
+- **vanilla:** `class App extends WyndlassApp`. `mount()` builds the shadow DOM once and calls `ready()` when the screen kept a weather answer. `draw(epochMs)` shows the page for that moment, asks for the weather every ten minutes, then calls `ready()`. `paging()` says the two pages.
+
+## Making it the person's app
+
+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.
+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.
+
+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

@@ -0,0 +1,17 @@
+# Agent instructions: __APP_NAME__
+
+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.
+- **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.
+- **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.
+- **Placing:** read `guide.read` (topic `layouts`, sections `elements` and `apps`), then `layout.save` with the app's item from `app.list`, and `layout.check`, at a place the person names.
+- **Scheduling, only with the person's yes:** `campaign.save` at the place and times they give, then `campaign.publish`, which previews first: confirm only once they agree. Never at the organization's top place unless they say so.
+- **Every step in detail** is in the skill: `npx wyndlass-app skill install` puts it in `.claude/skills/wyndlass-app/`.

package/templates/react/README.md

@@ -0,0 +1,23 @@
+# __APP_NAME__
+
+An app for Wyndlass's screens (`__APP_ID__`), built on [`@wyndlass/app-sdk`](https://www.npmjs.com/package/@wyndlass/app-sdk).
+
+- `app.json` is its definition: its id, version, name, element, params and the data it reads.
+- `src/app.tsx` is its module: a React component, made the element's class by `reactApp()`, the default export. `src/app.css` is its styles.
+
+## Commands
+
+- `npm run preview`: the app as screens run it, at http://127.0.0.1:5199/, drawn again as you change it. Its controls set the screen's size, the params, the clock, enter and exit, the time zone, the screen's facts and each data source's answer, and give the app tables from CSV or JSON, the people at the screen and the player's events where it uses them. `npm run preview -- --frame` runs it in the frame the CMS gives apps, where it has no storage.
+- `npm run check`: the checks Wyndlass makes when you import it.
+- `npm run pack`: `dist/__APP_ID__-<version>.zip`, the package to import, after the checks.
+- `npm run typecheck`: TypeScript's check.
+- `npx wyndlass-app skill install`: the skill for a coding agent such as Claude Code, in `.claude/skills/`. It builds, previews, packs, imports and schedules the app with you.
+
+Import the package through the Wyndlass MCP (`app.prepareImport`, `npx wyndlass-app upload`, then `app.import`) or in the CMS (Content, Library, Import an app). A person who may approve media there reviews the app's first version, and any that asks for more than the one before it, before screens play it. Raise `version` in `app.json` for each new one.
+
+## What screens enforce
+
+- The time comes from `useNow()`, the layout's clock, never `Date.now()`.
+- `ready()` within 5 s of the app's start.
+- No `localStorage` for anything that matters, and no secrets in params or the module: both are readable.
+- Data only from the sources `app.json` declares (`weather`, `news`, `image` or `calendar`), and the network hosts declared truthfully in `capabilities.network`: a person approves them.

package/templates/react/app.json

@@ -0,0 +1,14 @@
+{
+  "id": "__APP_ID__",
+  "version": "0.1.0",
+  "name": "__APP_NAME__",
+  "element": "__ELEMENT__",
+  "description": "A heading and the time on one page, the weather on the next.",
+  "params": {
+    "heading": { "type": "string", "default": "Good morning", "label": "Heading" },
+    "accent": { "type": "color", "default": "#4f8cff", "label": "Accent" },
+    "units": { "type": "enum", "values": ["metric", "imperial"], "default": "metric", "label": "Units" },
+    "seconds": { "type": "boolean", "default": false, "label": "Show seconds" }
+  },
+  "data": ["weather"]
+}

package/templates/react/gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

package/templates/react/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__PACKAGE__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "preview": "wyndlass-app preview",
+    "check": "wyndlass-app check",
+    "pack": "wyndlass-app pack",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@wyndlass/app-sdk": "__SDK__",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/react/src/app.css

@@ -0,0 +1,7 @@
+:host { display: block; width: 100%; height: 100%; color: #ffffff; font-family: system-ui, sans-serif; }
+.page { width: 100%; height: 100%; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: calc(var(--h) * .04); }
+.page[hidden] { display: none; }
+h1 { margin: 0; font-size: min(calc(var(--h) * .14), calc(var(--w) * .08)); font-weight: 600; color: var(--accent); }
+time { font-size: min(calc(var(--h) * .3), calc(var(--w) * .16)); font-variant-numeric: tabular-nums; }
+.temperature { font-size: min(calc(var(--h) * .3), calc(var(--w) * .16)); }
+.condition, .none { font-size: min(calc(var(--h) * .1), calc(var(--w) * .05)); opacity: .85; }

package/templates/react/src/app.tsx

@@ -0,0 +1,39 @@
+// __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.
+import { useEffect, useMemo } from "react";
+import { color, type weather } from "@wyndlass/app-sdk";
+import { reactApp, useApp, useData, useNow, usePaging } from "@wyndlass/app-sdk/react";
+import css from "./app.css";
+
+/** How long each of the two pages shows. */
+const PAGE_MS = 8_000;
+
+function Board() {
+  const app = useApp();
+  const now = useNow();
+  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") });
+  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.
+  useEffect(() => { if (answer || error) app.ready(); }, [app, answer, error]);
+  const w = answer?.data;
+  return (
+    <div style={{ width: "100%", height: "100%", ["--accent" as string]: color(app.prop("accent", "#4f8cff"), "#4f8cff") }}>
+      <section className="page" hidden={page !== 0}>
+        <h1>{app.prop("heading", "Good morning")}</h1>
+        <time>{time.format(now)}</time>
+      </section>
+      <section className="page" hidden={page !== 1}>
+        {w ? <>
+          <div className="temperature">{Math.round(w.current.temperature)}°{w.units === "imperial" ? "F" : "C"}</div>
+          <div className="condition">{w.current.condition.replace(/-/g, " ")}</div>
+        </> : <div className="none">The weather is on its way.</div>}
+      </section>
+    </div>
+  );
+}
+
+export default reactApp(Board, { css });

package/templates/react/src/env.d.ts

@@ -0,0 +1,13 @@
+// A CSS file the source imports is its text, for css(): pack bundles it so.
+declare module "*.css" {
+  const css: string;
+  export default css;
+}
+
+// An image the source imports is a data URL, inlined by pack: for an <img>'s src or a style set from code.
+declare module "*.png" { const url: string; export default url; }
+declare module "*.jpg" { const url: string; export default url; }
+declare module "*.jpeg" { const url: string; export default url; }
+declare module "*.gif" { const url: string; export default url; }
+declare module "*.webp" { const url: string; export default url; }
+declare module "*.svg" { const url: string; export default url; }

package/templates/react/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/templates/vanilla/AGENTS.md

@@ -0,0 +1,17 @@
+# Agent instructions: __APP_NAME__
+
+An app for Wyndlass's screens, on `@wyndlass/app-sdk`. Its README says what it is; these are the rules.
+
+- **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.
+- **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.
+- **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.
+- **Placing:** read `guide.read` (topic `layouts`, sections `elements` and `apps`), then `layout.save` with the app's item from `app.list`, and `layout.check`, at a place the person names.
+- **Scheduling, only with the person's yes:** `campaign.save` at the place and times they give, then `campaign.publish`, which previews first: confirm only once they agree. Never at the organization's top place unless they say so.
+- **Every step in detail** is in the skill: `npx wyndlass-app skill install` puts it in `.claude/skills/wyndlass-app/`.

package/templates/vanilla/README.md

@@ -0,0 +1,23 @@
+# __APP_NAME__
+
+An app for Wyndlass's screens (`__APP_ID__`), built on [`@wyndlass/app-sdk`](https://www.npmjs.com/package/@wyndlass/app-sdk).
+
+- `app.json` is its definition: its id, version, name, element, params and the data it reads.
+- `src/app.ts` is its module: the element's class, the default export. `src/app.css` is its styles.
+
+## Commands
+
+- `npm run preview`: the app as screens run it, at http://127.0.0.1:5199/, drawn again as you change it. Its controls set the screen's size, the params, the clock, enter and exit, the time zone, the screen's facts and each data source's answer, and give the app tables from CSV or JSON, the people at the screen and the player's events where it uses them. `npm run preview -- --frame` runs it in the frame the CMS gives apps, where it has no storage.
+- `npm run check`: the checks Wyndlass makes when you import it.
+- `npm run pack`: `dist/__APP_ID__-<version>.zip`, the package to import, after the checks.
+- `npm run typecheck`: TypeScript's check.
+- `npx wyndlass-app skill install`: the skill for a coding agent such as Claude Code, in `.claude/skills/`. It builds, previews, packs, imports and schedules the app with you.
+
+Import the package through the Wyndlass MCP (`app.prepareImport`, `npx wyndlass-app upload`, then `app.import`) or in the CMS (Content, Library, Import an app). A person who may approve media there reviews the app's first version, and any that asks for more than the one before it, before screens play it. Raise `version` in `app.json` for each new one.
+
+## What screens enforce
+
+- The time comes from `now()` (the `epochMs` `draw` is given), never `Date.now()`.
+- `ready()` within 5 s of the app's start.
+- No `localStorage` for anything that matters, and no secrets in params or the module: both are readable.
+- Data only from the sources `app.json` declares (`weather`, `news`, `image` or `calendar`), and the network hosts declared truthfully in `capabilities.network`: a person approves them.

package/templates/vanilla/app.json

@@ -0,0 +1,14 @@
+{
+  "id": "__APP_ID__",
+  "version": "0.1.0",
+  "name": "__APP_NAME__",
+  "element": "__ELEMENT__",
+  "description": "A heading and the time on one page, the weather on the next.",
+  "params": {
+    "heading": { "type": "string", "default": "Good morning", "label": "Heading" },
+    "accent": { "type": "color", "default": "#4f8cff", "label": "Accent" },
+    "units": { "type": "enum", "values": ["metric", "imperial"], "default": "metric", "label": "Units" },
+    "seconds": { "type": "boolean", "default": false, "label": "Show seconds" }
+  },
+  "data": ["weather"]
+}

package/templates/vanilla/gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

package/templates/vanilla/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "__PACKAGE__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "preview": "wyndlass-app preview",
+    "check": "wyndlass-app check",
+    "pack": "wyndlass-app pack",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@wyndlass/app-sdk": "__SDK__"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/templates/vanilla/src/app.css

@@ -0,0 +1,7 @@
+:host { display: block; width: 100%; height: 100%; color: #ffffff; font-family: system-ui, sans-serif; }
+.page { width: 100%; height: 100%; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: calc(var(--h) * .04); }
+.page[hidden] { display: none; }
+h1 { margin: 0; font-size: min(calc(var(--h) * .14), calc(var(--w) * .08)); font-weight: 600; color: var(--accent); }
+time { font-size: min(calc(var(--h) * .3), calc(var(--w) * .16)); font-variant-numeric: tabular-nums; }
+.temperature { font-size: min(calc(var(--h) * .3), calc(var(--w) * .16)); }
+.condition, .none { font-size: min(calc(var(--h) * .1), calc(var(--w) * .05)); opacity: .85; }