@wyndlass/app-sdk 0.0.0-stage → 1.0.0

package/protocol/common.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.wyndlass.ai/protocol/v0/common.schema.json",
+  "title": "Common definitions",
+  "description": "Shared identifiers and value types used by every protocol message.",
+  "$defs": {
+    "tenantId": {
+      "type": "string",
+      "pattern": "^ten_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Tenant id: type prefix plus a base32-encoded UUIDv7."
+    },
+    "nodeId": {
+      "type": "string",
+      "pattern": "^node_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Org-tree node id."
+    },
+    "deviceId": {
+      "type": "string",
+      "pattern": "^dev_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Device id."
+    },
+    "mediaId": {
+      "type": "string",
+      "pattern": "^med_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Media item id (asset, app, composition, playlist or live source)."
+    },
+    "campaignId": {
+      "type": "string",
+      "pattern": "^cmp_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Campaign id."
+    },
+    "adCampaignId": {
+      "type": "string",
+      "pattern": "^adc_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Ad campaign id (WP-0075): a campaign sold to an advertiser."
+    },
+    "adDecisionId": {
+      "type": "string",
+      "pattern": "^add_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Ad decision id (ADR 0075): the broker's answer for one ad slot."
+    },
+    "audienceId": {
+      "type": "string",
+      "pattern": "^aud_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Audience id (saved targeting)."
+    },
+    "groupId": {
+      "type": "string",
+      "pattern": "^grp_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Device group id."
+    },
+    "emergencyId": {
+      "type": "string",
+      "pattern": "^emg_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Emergency message id."
+    },
+    "emergencySourceId": {
+      "type": "string",
+      "pattern": "^esr_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Emergency source id: a CAP feed, the National Weather Service or IPAWS at a node (ADR 0127)."
+    },
+    "changeSetId": {
+      "type": "string",
+      "pattern": "^chg_[0-9a-hjkmnp-tv-z]{26}$",
+      "description": "Change set id."
+    },
+    "principalRef": {
+      "type": "string",
+      "pattern": "^(user|agent|device|client|system):[A-Za-z0-9_.:-]{1,128}$",
+      "description": "A principal, e.g. user:u_123, agent:fleet-guardian, device:dev_..."
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "Lowercase hex SHA-256 digest."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 timestamp with offset."
+    },
+    "sourceKind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,31}$",
+      "description": "A kind of sensor that measures impressions (WP-0105, ADR 0105): camera, proximity (WP-0043), and later ble, rfid, lidar and others. A pattern, not an enum, so a new kind is never a breaking change for players in the field."
+    },
+    "inputName": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
+      "description": "A named input on a screen (WP-0043, ADR 0107), which a serial leaf's input names: a sensor map's, or one the player names itself from a sensor's family and channel, such as pickup-3, or button-2.1 for one button of several."
+    },
+    "sensorFamily": {
+      "enum": ["pickup", "presence", "lidar", "rfid", "button", "gesture", "motion", "light", "climate", "camera", "io"],
+      "description": "What a sensor on a controller's channel does (WP-0043, ADR 0107): pickup (a product lifted and put back), presence (a person's distance), lidar (people in zones), rfid (tags placed and lifted), button, gesture, motion, light, climate (temperature and humidity), camera (a person's presence, gaze and, where allowed, estimated age and gender) and io (an input that is on or off)."
+    },
+    "bleAddress": {
+      "type": "string",
+      "pattern": "^[0-9A-F]{2}(:[0-9A-F]{2}){5}$",
+      "description": "A Bluetooth device address (WP-0044, ADR 0108): six octets in upper-case hex, most significant first, such as 0C:F3:EE:00:12:34."
+    },
+    "beaconFrame": {
+      "enum": ["ibeacon", "eddystone-uid", "eddystone-url", "eddystone-tlm", "altbeacon"],
+      "description": "A beacon's advertisement as the player reads it (WP-0044, ADR 0108): iBeacon; Eddystone's UID, URL or TLM (telemetry: battery, temperature and counts); or AltBeacon."
+    },
+    "gpioPin": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 63,
+      "description": "A GPIO pin as the shell numbers it (WP-0044, ADR 0108): its line on the box's GPIO chip, as the gpio leaf's pin names it."
+    },
+    "demographics": {
+      "description": "Impressions by estimated gender and age group, counted only where a place allows it (WP-0043, ADR 0107): each presence counted once, by the estimate its sensor gave most often. Never anything about one person.",
+      "type": "object",
+      "required": ["female", "male", "genderUnknown", "age", "ageUnknown"],
+      "additionalProperties": false,
+      "properties": {
+        "female": { "type": "integer", "minimum": 0 },
+        "male": { "type": "integer", "minimum": 0 },
+        "genderUnknown": { "type": "integer", "minimum": 0, "description": "Presences whose gender the sensor did not estimate, or was unsure of." },
+        "age": {
+          "type": "array",
+          "minItems": 8,
+          "maxItems": 8,
+          "items": { "type": "integer", "minimum": 0 },
+          "description": "Presences by the sensor's age group: 0 to 11, 12 to 17, 18 to 24, 25 to 34, 35 to 44, 45 to 54, 55 to 64, and 65 or more."
+        },
+        "ageUnknown": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "date": {
+      "type": "string",
+      "format": "date"
+    },
+    "localTime": {
+      "type": "string",
+      "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+      "description": "Wall-clock time HH:MM in the device's time zone."
+    },
+    "timeZone": {
+      "type": "string",
+      "pattern": "^[A-Za-z_]+(/[A-Za-z0-9_+-]+){0,2}$|^UTC$",
+      "description": "IANA time zone name."
+    },
+    "locale": {
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2}|-[0-9]{3})?$",
+      "description": "BCP 47 language tag."
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?$"
+    },
+    "itemRef": {
+      "type": "object",
+      "description": "A pinned reference to a media item version.",
+      "required": [
+        "id",
+        "version"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "common.schema.json#/$defs/mediaId"
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "description": "Detached Ed25519 signature over the UTF-8 bytes of the RFC 8785 canonical JSON of the message without this field. keyId names a public key the verifier already trusts (distributed at enrollment); never fetch a key named by the message.",
+      "required": [
+        "alg",
+        "keyId",
+        "value"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "alg": {
+          "const": "ed25519"
+        },
+        "keyId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "value": {
+          "type": "string",
+          "contentEncoding": "base64",
+          "minLength": 16
+        }
+      }
+    }
+  }
+}

package/protocol/samples/calendar.json

@@ -0,0 +1,63 @@
+{
+  "calendar": {
+    "name": "Prairie Grocers"
+  },
+  "events": [
+    {
+      "id": "staff-meeting@prairie.test/20261012T133000Z",
+      "title": "Staff meeting, Store 12",
+      "location": "Back office; Store 12",
+      "start": "2026-10-12T13:30:00Z",
+      "end": "2026-10-12T14:00:00Z"
+    },
+    {
+      "id": "harvest@prairie.test",
+      "title": "Fall harvest sale",
+      "start": "2026-10-16",
+      "end": "2026-10-19",
+      "allDay": true
+    },
+    {
+      "id": "staff-meeting@prairie.test/20261019T133000Z",
+      "title": "Staff meeting, Store 12",
+      "location": "Back office; Store 12",
+      "start": "2026-10-19T13:30:00Z",
+      "end": "2026-10-19T14:00:00Z"
+    },
+    {
+      "id": "webinar@prairie.test",
+      "title": "Supplier webinar",
+      "start": "2026-10-20T15:00:00Z",
+      "end": "2026-10-20T15:45:00Z",
+      "tentative": true
+    },
+    {
+      "id": "staff-meeting@prairie.test/20261022T133000Z",
+      "title": "Staff meeting, Store 12",
+      "location": "Back office; Store 12",
+      "start": "2026-10-22T13:30:00Z",
+      "end": "2026-10-22T14:00:00Z"
+    },
+    {
+      "id": "staff-meeting@prairie.test/20261026T133000Z",
+      "title": "Staff meeting, Store 12",
+      "location": "Back office; Store 12",
+      "start": "2026-10-26T13:30:00Z",
+      "end": "2026-10-26T14:00:00Z"
+    },
+    {
+      "id": "staff-meeting@prairie.test/20261029T133000Z",
+      "title": "Staff meeting, Store 12",
+      "location": "Back office; Store 12",
+      "start": "2026-10-29T13:30:00Z",
+      "end": "2026-10-29T14:00:00Z"
+    },
+    {
+      "id": "staff-meeting@prairie.test/20261102T143000Z",
+      "title": "Staff meeting, Store 12",
+      "location": "Back office; Store 12",
+      "start": "2026-11-02T14:30:00Z",
+      "end": "2026-11-02T15:00:00Z"
+    }
+  ]
+}

package/protocol/samples/events/app.command.json

@@ -0,0 +1,14 @@
+{
+  "type": "app.command",
+  "seq": 42,
+  "at": "2026-10-01T14:01:00Z",
+  "name": "showSpecial",
+  "argument": {
+    "sku": "1234"
+  },
+  "by": {
+    "kind": "app",
+    "app": "com.wyndlass.menu",
+    "instance": "zone-main-1"
+  }
+}

package/protocol/samples/events/item.end.json

@@ -0,0 +1,13 @@
+{
+  "type": "item.end",
+  "seq": 40,
+  "at": "2026-10-01T13:59:50Z",
+  "zone": "main",
+  "item": {
+    "id": "med_01jc8x5s3h9k2m4n6p8q0r2t4v",
+    "version": 3
+  },
+  "blob": "3c8e1f5a9b2d6e0c4f7a1b5d8e2c6f9a3b7d0e4c8f1a5b9d2e6c0f3a7b1d4e8c",
+  "endedAt": "2026-10-01T13:59:50Z",
+  "reason": "finished"
+}

package/protocol/samples/events/item.start.json

@@ -0,0 +1,18 @@
+{
+  "type": "item.start",
+  "seq": 41,
+  "at": "2026-10-01T13:59:50Z",
+  "zone": "main",
+  "item": {
+    "id": "med_01jc8x5s3h9k2m4n6p8q0r2t4v",
+    "version": 3
+  },
+  "blob": "3c8e1f5a9b2d6e0c4f7a1b5d8e2c6f9a3b7d0e4c8f1a5b9d2e6c0f3a7b1d4e8c",
+  "contentType": "video/mp4",
+  "startedAt": "2026-10-01T13:59:50Z",
+  "durationMs": 8000,
+  "transition": {
+    "asked": "crossfade",
+    "played": "cut"
+  }
+}

package/protocol/samples/events/state.changed.json

@@ -0,0 +1,11 @@
+{
+  "type": "state.changed",
+  "seq": 41,
+  "at": "2026-10-01T14:00:00Z",
+  "state": "paused",
+  "previous": "playing",
+  "by": {
+    "kind": "remote",
+    "principal": "agent:fleet-guardian"
+  }
+}

package/protocol/samples/news.json

@@ -0,0 +1,37 @@
+{
+  "feed": {
+    "title": "Prairie Grocers News",
+    "url": "https://news.example.org/feed.xml",
+    "link": "https://news.example.org/",
+    "image": "https://news.example.org/logo.png"
+  },
+  "items": [
+    {
+      "id": "harvest-2026",
+      "title": "Fall harvest arrives & prices drop",
+      "link": "https://news.example.org/harvest",
+      "summary": "Squash, apples and more .",
+      "published": "2026-10-03T14:00:00.000Z",
+      "author": "Olive Owner",
+      "image": "/v0/image?url=https%3A%2F%2Fcdn.example.org%2Fharvest.jpg"
+    },
+    {
+      "title": "New bakery hours",
+      "link": "https://news.example.org/bakery",
+      "summary": "Open at 6 — every day.",
+      "published": "2026-10-02T14:30:00.000Z",
+      "image": "/v0/image?url=https%3A%2F%2Fcdn.example.org%2Fbakery.webp"
+    },
+    {
+      "title": "Meet our farmers",
+      "link": "https://news.example.org/farmers",
+      "summary": "Three families, one field.",
+      "image": "/v0/image?url=https%3A%2F%2Fcdn.example.org%2Ffarmers.png"
+    },
+    {
+      "title": "Store 12 reopens",
+      "link": "https://news.example.org/store-12",
+      "image": "/v0/image?url=https%3A%2F%2Fnews.example.org%2Fimg%2Fstore-12.jpg"
+    }
+  ]
+}

package/protocol/samples/player-status.json

@@ -0,0 +1,58 @@
+{
+  "apiVersion": 1,
+  "device": {
+    "id": "dev_01j9zq3k7m2p4r6t8v0w2x4y7a",
+    "type": "linux-player",
+    "shell": "universal-electron",
+    "shellVersion": "0.1.0",
+    "coreVersion": "0.1.0",
+    "model": "NUC 13 Pro",
+    "resolution": {
+      "width": 1920,
+      "height": 1080
+    },
+    "orientation": "landscape"
+  },
+  "mode": "player",
+  "timeZone": "America/Chicago",
+  "locale": "en-US",
+  "connection": "online",
+  "state": "paused",
+  "held": {
+    "by": {
+      "kind": "remote",
+      "principal": "agent:fleet-guardian"
+    },
+    "since": "2026-10-01T14:00:00Z"
+  },
+  "content": {
+    "manifest": "3c8e1f5a9b2d6e0c4f7a1b5d8e2c6f9a3b7d0e4c8f1a5b9d2e6c0f3a7b1d4e8c",
+    "issuedAt": "2026-10-01T13:00:00Z",
+    "switchedAt": "2026-10-01T13:00:04Z"
+  },
+  "now": [
+    {
+      "zone": "main",
+      "item": {
+        "id": "med_01jc8x5s3h9k2m4n6p8q0r2t4v",
+        "version": 3
+      },
+      "blob": "3c8e1f5a9b2d6e0c4f7a1b5d8e2c6f9a3b7d0e4c8f1a5b9d2e6c0f3a7b1d4e8c",
+      "contentType": "image/png",
+      "startedAt": "2026-10-01T13:59:50Z",
+      "durationMs": 10000,
+      "positionMs": 4200
+    }
+  ],
+  "audio": {
+    "volume": 40,
+    "muted": false
+  },
+  "capabilities": {
+    "audio": true,
+    "display": {
+      "power": false,
+      "brightness": false
+    }
+  }
+}

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/templates/react/AGENTS.md

@@ -0,0 +1,13 @@
+# 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.

package/templates/react/README.md

@@ -0,0 +1,22 @@
+# __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.
+
+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,5 @@
+// A CSS file the source imports is its text, for css(): pack bundles it so.
+declare module "*.css" {
+  const css: string;
+  export default css;
+}

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