@wyndlass/app-sdk 0.0.0-stage → 1.0.0

package/cli/preview.mjs

@@ -0,0 +1,142 @@
+// preview (WP-0101 decision 7): the app run as screens run it, on 127.0.0.1 only. The page is player-core's host, compiled
+// into the package when the SDK is built (dist/preview/); this server gives it the project's module, rebuilt with the
+// SDK's own esbuild whenever a source or app.json changes, the definition, and sample answers for the data the app
+// declares: the protocol's fixtures, or a folder of the developer's own. The page reloads the app on each rebuild.
+// With --frame (part c2), the app runs in WP-0100's frame on an origin of its own, as in the CMS: a second server, on
+// 127.0.0.1 too, serves the frame's page and runtime under the frames' own policy.
+import { existsSync, readdirSync, readFileSync, watch } from "node:fs";
+import { createServer } from "node:http";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { context } from "esbuild";
+import { CliError, definitionOf, entryOf } from "./package.mjs";
+
+const sdk = join(dirname(fileURLToPath(import.meta.url)), "..");
+const page = join(sdk, "dist", "preview");
+const SOURCES = ["weather", "news", "calendar"];
+const TYPES = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".json": "application/json; charset=utf-8" };
+
+/** A sample answer's data for a source: the folder's <source>.json (its data, or a whole answer), else the protocol's. */
+function sample(dataDir, source) {
+  const own = dataDir && join(dataDir, `${source}.json`);
+  const file = own && existsSync(own) ? own : join(sdk, "protocol", "samples", `${source}.json`);
+  if (!existsSync(file)) return null;
+  const read = JSON.parse(readFileSync(file, "utf8"));
+  return read && typeof read === "object" && "source" in read && "data" in read ? read.data : read;
+}
+
+/** The tables in the data folder's tables/: each .json or .csv file's text, by its name; the page reads them. */
+function tables(dataDir) {
+  const dir = dataDir && join(dataDir, "tables");
+  if (!dir || !existsSync(dir)) return {};
+  return Object.fromEntries(readdirSync(dir).filter(n => /.(json|csv)$/i.test(n)).map(n => [n, readFileSync(join(dir, n), "utf8")]));
+}
+
+/** The player's status and the events the controller can be sent, as the Player API's fixtures give them. */
+function controllerSamples() {
+  const samples = join(sdk, "protocol", "samples");
+  const events = join(samples, "events");
+  return {
+    status: JSON.parse(readFileSync(join(samples, "player-status.json"), "utf8")),
+    events: existsSync(events) ? Object.fromEntries(readdirSync(events).map(n => [n.replace(/.json$/, ""), JSON.parse(readFileSync(join(events, n), "utf8"))])) : {},
+  };
+}
+
+/** The frames' own policy (WP-0124's frames row), with the preview's page the one that may frame them. */
+const framePolicy = (frames, page) => [
+  "default-src 'none'", `script-src ${frames} blob:`, "style-src 'unsafe-inline'", "img-src blob: data:", "font-src blob: data:", "media-src blob:",
+  "connect-src https:", `frame-ancestors ${page}`, "base-uri 'none'", "form-action 'none'",
+].join("; ");
+
+/** A small picture for any image a data answer names: the preview fetches nothing from the network. */
+const PICTURE = Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="320" height="180" viewBox="0 0 320 180"><rect width="320" height="180" fill="#5a6b7d"/><path d="M0 180 L110 80 L180 140 L230 100 L320 180Z" fill="#8fa3b8"/><circle cx="250" cy="50" r="22" fill="#d9e2ec"/></svg>`);
+
+/**
+ * Serves the preview of the project at `dir` on 127.0.0.1:`port` (0: any free port), and with `frame`, the frames on
+ * the next port (any free one where `port` is 0). Resolves once it listens, with its address and a way to stop it.
+ */
+export async function preview(dir = ".", { port = 5199, data: dataDir, frame = false } = {}) {
+  const root = resolve(dir);
+  definitionOf(root);
+  const entry = entryOf(root);
+  if (!existsSync(join(page, "index.html"))) throw new CliError("this copy of @wyndlass/app-sdk has no preview page (dist/preview): build the SDK first");
+  let frames = null, framesOrigin = "", pageOrigin = "";
+  const clients = new Set();
+  const tell = () => { for (const c of clients) c.write("event: reload\ndata: {}\n\n"); };
+  let built = { code: "", error: "the module has not been built yet" }, version = 0, first;
+  const firstBuilt = new Promise(r => { first = r; });
+  const builder = await context({
+    entryPoints: [entry], absWorkingDir: root, bundle: true, format: "esm", target: "es2020", platform: "browser", write: false, sourcemap: "inline",
+    jsx: "automatic", logLevel: "silent", define: { "process.env.NODE_ENV": "\"development\"" }, outfile: join(root, "dist", "preview.js"),
+    loader: { ".css": "text", ".png": "dataurl", ".jpg": "dataurl", ".jpeg": "dataurl", ".gif": "dataurl", ".webp": "dataurl", ".svg": "dataurl", ".woff2": "dataurl", ".woff": "dataurl" },
+    plugins: [{ name: "wyndlass-preview", setup(b) {
+      b.onEnd(r => {
+        built = r.errors.length ? { code: "", error: r.errors.map(e => `${e.location ? `${e.location.file}:${e.location.line}: ` : ""}${e.text}`).join("\n") }
+          : { code: r.outputFiles.find(f => f.path.endsWith(".js")).text, error: null };
+        version++;
+        tell();
+        first();
+      });
+    } }],
+  });
+  await builder.watch();
+  // The first build done before anyone is told where the preview is: a page loaded sooner would find no module.
+  await firstBuilt;
+  // The definition is not a source esbuild follows.
+  const definitionWatch = watch(join(root, "app.json"), () => { version++; tell(); });
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    const send = (status, type, body, more = {}) => res.writeHead(status, { "content-type": type, "cache-control": "no-store", ...more }).end(body);
+    switch (url.pathname) {
+      case "/": return send(200, TYPES[".html"], readFileSync(join(page, "index.html")));
+      case "/page.js": return send(200, TYPES[".js"], readFileSync(join(page, "page.js")));
+      // Its version with it, so a page that connects to /events after a change knows it loaded an older one.
+      case "/app.js": return built.error ? send(500, "text/plain; charset=utf-8", built.error, { "x-preview-version": String(version) })
+        : send(200, TYPES[".js"], built.code, { "x-preview-version": String(version) });
+      case "/app.json": return send(200, TYPES[".json"], readFileSync(join(root, "app.json")));
+      case "/samples.json": {
+        const declared = (definitionOf(root).read?.data ?? []).filter(s => SOURCES.includes(s));
+        return send(200, TYPES[".json"], JSON.stringify(Object.fromEntries(declared.map(s => [s, sample(dataDir && resolve(dataDir), s)]))));
+      }
+      case "/config.json": return send(200, TYPES[".json"], JSON.stringify({ frames: framesOrigin, tables: tables(dataDir && resolve(dataDir)), controller: controllerSamples() }));
+      case "/picture.svg": return send(200, "image/svg+xml", PICTURE);
+      case "/favicon.ico": return res.writeHead(204).end();
+      case "/events": {
+        res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+        res.write(`event: hello\ndata: ${JSON.stringify({ version })}\n\n`);
+        clients.add(res);
+        req.on("close", () => clients.delete(res));
+        return;
+      }
+      default: return send(404, "text/plain; charset=utf-8", "not found");
+    }
+  });
+  await new Promise((ok, fail) => { server.once("error", fail); server.listen(port, "127.0.0.1", ok); })
+    .catch(e => { void builder.dispose(); definitionWatch.close(); throw new CliError(e.code === "EADDRINUSE" ? `port ${port} is taken: give another with --port` : e.message); });
+  const { address, port: bound } = server.address();
+  pageOrigin = `http://${address}:${bound}`;
+  if (frame) {
+    // The frame's page and runtime only, nothing else, under the frames' policy: the app's document there is opaque.
+    frames = createServer((req, res) => {
+      const path = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+      const file = path === "/" ? "index.html" : path === "/frame.js" ? "frame.js" : null;
+      if (!file) return res.writeHead(404).end();
+      res.writeHead(200, { "content-type": TYPES[file.endsWith(".js") ? ".js" : ".html"], "cache-control": "no-store", "content-security-policy": framePolicy(framesOrigin, pageOrigin) })
+        .end(readFileSync(join(page, "frame", file)));
+    });
+    await new Promise((ok, fail) => { frames.once("error", fail); frames.listen(port === 0 ? 0 : port + 1, "127.0.0.1", ok); })
+      .catch(async e => { await builder.dispose(); definitionWatch.close(); server.close(); throw new CliError(e.code === "EADDRINUSE" ? `port ${port + 1}, for the frames, is taken: give another with --port` : e.message); });
+    framesOrigin = `http://127.0.0.1:${frames.address().port}`;
+  }
+  return {
+    url: `http://${address}:${bound}/`, address, port: bound, frames: framesOrigin || null,
+    async close() {
+      definitionWatch.close();
+      if (frames) await new Promise(r => frames.close(r));
+      for (const c of clients) c.end();
+      await builder.dispose();
+      await new Promise(r => server.close(r));
+    },
+  };
+}

package/cli/zip.mjs

@@ -0,0 +1,63 @@
+// The package's zip (WP-0101 decision 8): the same entries give the same bytes, so importing a version again is a no-op,
+// not a refusal (WP-0100 decision 4). The entries in the order given, each deflated at level 9, dated 1 January 1980
+// (the DOS epoch), named in UTF-8, with no extra fields or comments.
+import { deflateRawSync } from "node:zlib";
+
+const TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+
+/** CRC-32 (ISO 3309), as zip records it; node:zlib's own is not in every Node 20. */
+export function crc32(bytes) {
+  let c = 0xffffffff;
+  for (const b of bytes) c = TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+const DOS_TIME = 0, DOS_DATE = (0 << 9) | (1 << 5) | 1;
+
+/** A zip of `entries`, each [name, bytes], in that order. */
+export function zip(entries) {
+  const locals = [], central = [];
+  let offset = 0;
+  for (const [entryName, data] of entries) {
+    const raw = Buffer.from(data), body = deflateRawSync(raw, { level: 9 }), name = Buffer.from(entryName, "utf8"), crc = crc32(raw);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6);
+    local.writeUInt16LE(8, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    const head = Buffer.alloc(46);
+    head.writeUInt32LE(0x02014b50, 0);
+    head.writeUInt16LE(20, 4);
+    head.writeUInt16LE(20, 6);
+    head.writeUInt16LE(0x0800, 8);
+    head.writeUInt16LE(8, 10);
+    head.writeUInt16LE(DOS_TIME, 12);
+    head.writeUInt16LE(DOS_DATE, 14);
+    head.writeUInt32LE(crc, 16);
+    head.writeUInt32LE(body.length, 20);
+    head.writeUInt32LE(raw.length, 24);
+    head.writeUInt16LE(name.length, 28);
+    head.writeUInt32LE(offset, 42);
+    locals.push(local, name, body);
+    central.push(head, name);
+    offset += local.length + name.length + body.length;
+  }
+  const directory = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, directory, end]);
+}

package/dist/contract/app-contract.d.ts

@@ -0,0 +1,221 @@
+import type { PlayerAPIEvent } from "./player-api-event.js";
+import type { PlayerAPIStatus } from "./player-api-status.js";
+/**
+ * How the host hands an element its context (Player API 2): `element[ATTACH](context)`, once, after it makes the element
+ * and before the element joins the document. The element keeps the context where nothing else can reach it, and ignores a
+ * second call.
+ */
+export declare const ATTACH: unique symbol;
+/**
+ * What an app's enter and exit hooks are given (ADR 0053, decision 8; ADR 0071): when on the player's clock (the clip's
+ * delay is in startAt, so delayMs is 0), how, and how long; the stagger between its items, and for a paged app the page it
+ * is for.
+ */
+export interface HookOptions {
+    startAt: number;
+    preset: string;
+    durationMs: number;
+    easing?: string;
+    delayMs?: number;
+    staggerMs?: number;
+    page?: number;
+    reducedMotion: boolean;
+}
+/** The data service's answer (data-answer.schema.json), with whether it came from this screen's own store, and its age. */
+export interface DataAnswer<T = unknown> {
+    source: string;
+    params: Record<string, unknown>;
+    fetchedAt: string;
+    expiresAt: string;
+    stale: boolean;
+    attribution?: {
+        text: string;
+        url?: string;
+    };
+    data: T;
+    /** True when the service could not be reached and this is the last answer the screen kept. */
+    offline: boolean;
+    /** How old the data is, from fetchedAt to now. */
+    ageMs: number;
+}
+/** The screen's facts (WP-0068 part g): its name, type, tags and node path, for what an app draws itself. */
+export interface ScreenFacts {
+    name: string;
+    type?: string;
+    tags?: string[];
+    /** Its node and the nodes above it, from the organization down. */
+    path: {
+        name: string;
+        kind: string;
+    }[];
+    /** The workspace's own fields (WP-0068 part h): its value, else the nearest node's. */
+    fields?: Record<string, string>;
+}
+/** A rule a table's row must meet to be shown (WP-0137, ADR 0125): against a value, or the screen's own. */
+export interface TableRule {
+    column: string;
+    op: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "contains";
+    value: string | number | boolean | null | {
+        screen: "name" | "location" | "site" | "fields";
+        key?: string;
+    };
+}
+/** An app's table binding (DES-DB-12): its table, each slot's column, and which rows it shows, in what order, how many. */
+export interface TableBinding {
+    table: string;
+    fields?: Record<string, string>;
+    filter?: TableRule[];
+    sort?: {
+        column: string;
+        order: "asc" | "desc";
+    };
+    limit?: number;
+}
+/** An anonymous event at the screen (WP-0105): someone came into view, looked, or left after a while. */
+export type ImpressionEvent = {
+    type: "enter";
+    source: string;
+} | {
+    type: "look";
+    source: string;
+} | {
+    type: "leave";
+    source: string;
+    dwellS: number;
+    attentionS?: number;
+};
+/** Each kind of sensor's people in view now, the longest any has stayed and, where faces are seen, looked. */
+export interface ImpressionsNow {
+    source: string;
+    present: number;
+    longestDwellS: number;
+    longestAttentionS?: number;
+}
+/** What an app that declares the `impressions` sensor gets as context.impressions. */
+export interface ImpressionsFeed {
+    now(): ImpressionsNow[];
+    /** Hears batches of events, at most four times a second; returns how to stop. */
+    on(listener: (events: ImpressionEvent[]) => void): () => void;
+}
+/** What an app may do with the player's controller: its definition's capabilities.player (ADR 0050, decision 3). */
+export type AppCapability = "read" | "control";
+/** In the designer or a preview, commands change nothing. */
+export interface NotApplied {
+    applied: false;
+    reason: "preview";
+}
+/** The player's time (time.now). */
+export interface TimeNow {
+    iso: string;
+    epochMs: number;
+    timeZone: string;
+    utcOffsetMinutes: number;
+    synced: boolean;
+}
+/**
+ * An app's own view of the player's controller (ADR 0050, decision 3): properties and events with capabilities.player
+ * "read" (the default), commands as well with "control". Its listeners go when the app does.
+ */
+export interface AppController {
+    readonly app: string;
+    readonly instance: string;
+    readonly capability: AppCapability;
+    /** Everything the controller knows now (the same as player.status). */
+    status(): PlayerAPIStatus;
+    get<K extends keyof PlayerAPIStatus>(property: K): PlayerAPIStatus[K];
+    /** Listens for an event, or every event with "*"; returns how to stop. */
+    on(event: PlayerAPIEvent["type"] | "*", listener: (event: PlayerAPIEvent) => void): () => void;
+    time(): Promise<TimeNow>;
+    /** A command by its Player API name, e.g. call("player.pause"); throws when refused, with the Player API's code. */
+    call(command: string, args?: Record<string, unknown>): Promise<unknown | NotApplied>;
+    play(): Promise<unknown | NotApplied>;
+    pause(): Promise<unknown | NotApplied>;
+    stop(): Promise<unknown | NotApplied>;
+    next(): Promise<unknown | NotApplied>;
+    previous(): Promise<unknown | NotApplied>;
+    /** Ends this app's slot now: its item ends as finished and the loop moves on. */
+    finish(): Promise<unknown | NotApplied>;
+    /** Removes every listener; the host calls it when the app goes. */
+    dispose(): void;
+}
+/** What an app is given: through ATTACH (Player API 2), or as `element.wyndlass` by a player older than that. */
+export interface AppContext {
+    /** The app's id (app-definition), or its item's id where the layout does not say. */
+    app: string;
+    /** The tag the host defined its element under. */
+    element: string;
+    props: Record<string, unknown>;
+    /** The screen's place (the manifest's), for "the screen's place" defaults. */
+    place?: {
+        lat: number;
+        lon: number;
+    };
+    /** The screen's facts (WP-0068 part g), for what an app draws itself. */
+    screen?: ScreenFacts | null;
+    timeZone: string;
+    locale: string;
+    /** True in the CMS's previews. */
+    preview: boolean;
+    /** The layout's clock: now, or the moment it is held at when seeked or paused. */
+    now(): number;
+    /** When the layout started, on the same clock. */
+    startedAt(): number;
+    /** Says the app is drawn and may be shown. One that has not by the deadline is reported late. */
+    ready(): void;
+    data<T = unknown>(source: string, params: Record<string, string | number | boolean>): Promise<DataAnswer<T>>;
+    /**
+     * The answer this screen last kept for a request, however old, at once; nothing before the first (WP-0111). An app draws
+     * it while `data` asks again, so it is ready without waiting for the network. Absent on players older than WP-0111 part
+     * b, so apps check for it.
+     */
+    kept?<T = unknown>(source: string, params: Record<string, string | number | boolean>): DataAnswer<T> | undefined;
+    /** An image a data answer names (a data service path), as a blob URL the app can draw. */
+    image(path: string): Promise<string>;
+    /**
+     * The layout's table binding for this app (DES-DB-12): its table, each slot's column, and which of its rows it shows,
+     * in what order and how many (WP-0137, ADR 0125).
+     */
+    binding?: TableBinding;
+    /**
+     * A data table's snapshot, as the manifest carries it; null without one. The bound table's comes with only the rows the
+     * binding chooses, chosen at each read on the layout's clock with the screen's facts (WP-0137).
+     */
+    snapshot(table: string): unknown | null;
+    /** The app's view of the player's controller, on screens (WP-0100); absent in the designer and previews. */
+    controller?: AppController;
+    /**
+     * The people at the screen (WP-0105), for an app whose definition declares `capabilities.sensors: ["impressions"]`,
+     * where the site measures them. Absent otherwise.
+     */
+    impressions?: ImpressionsFeed;
+}
+/**
+ * An app's element: an HTMLElement (a host types it as both), with the hooks the host calls, each optional, and how it
+ * takes its context. Written without the DOM's types, so the contract checks wherever it is read, a Worker included.
+ */
+export interface AppElement {
+    /** Player API 2: takes the context, once. */
+    [ATTACH]?(context: AppContext): void;
+    /** The context as players older than Player API 2 give it, and Wyndlass's apps of the old shape read it. */
+    wyndlass?: AppContext;
+    /** Draws the app at a moment on the layout's clock; called each frame while it plays, and once when held. */
+    update?(epochMs: number): void;
+    enter?(o: HookOptions): Promise<void> | void;
+    exit?(o: HookOptions): Promise<void> | void;
+    /** A paged app's pages (ADR 0071, decision 5): how many, and how long each shows, from the data it started with. */
+    paging?(): {
+        count: number;
+        ms: number;
+    } | null;
+    /** Forgets every enter and exit given so far: the designer's canvas gives them again after the clips change (WP-0069). */
+    reset?(): void;
+}
+/**
+ * An app's module (ADR 0099 decision 2; Player API 2): its default export is its element's class, which the host defines
+ * under a tag of its choosing; its class extends HTMLElement. The old shape, for Wyndlass's own apps on older players
+ * only, defines its element itself and exports its tag as `element`; a module of Wyndlass's may have both.
+ */
+export interface AppModule {
+    default?: new () => AppElement;
+    element?: string;
+}

package/dist/contract/app-contract.js

@@ -0,0 +1,6 @@
+/**
+ * How the host hands an element its context (Player API 2): `element[ATTACH](context)`, once, after it makes the element
+ * and before the element joins the document. The element keeps the context where nothing else can reach it, and ignores a
+ * second call.
+ */
+export const ATTACH = Symbol.for("wyndlass.app.attach");

package/dist/contract/app-definition.d.ts

@@ -0,0 +1,155 @@
+export type CommonSemver = string;
+/**
+ * BCP 47 language tag.
+ */
+export type CommonLocale = string;
+/**
+ * The YAML definition of a web component app (scoping doc 7.8). Drives the designer's property panel, the catalog and the MCP tools.
+ */
+export interface AppDefinition {
+    /**
+     * Reverse-domain id, e.g. com.wyndlass.weather. com.wyndlass. is Wyndlass's own: an app an organization imports may not use it (WP-0100).
+     */
+    id: string;
+    version: CommonSemver;
+    name: string;
+    description?: string;
+    /**
+     * The element's name. From Player API 2 (WP-0100) the host defines the module's default export under this name, a hyphen and a suffix of its own, so it is the readable part of the tag. Wyndlass's apps also define it themselves, for players older than that.
+     */
+    element: string;
+    params?: {
+        [k: string]: Param | undefined;
+    };
+    properties?: {
+        resizable?: boolean;
+        minDuration?: string;
+        offline?: boolean;
+        transparent?: boolean;
+        aspectRatio?: string;
+    };
+    capabilities?: {
+        network?: string[];
+        /**
+         * Sensors the app reads on the screen. `impressions`: the live, anonymous feed of the people at the screen, where its site measures them (WP-0105): context.impressions.
+         */
+        sensors?: string[];
+        audio?: boolean;
+        peers?: boolean;
+        /**
+         * What the app may do with the player's controller (ADR 0050): read its properties and events (read, the default), or also command playback, audio and display (control). The CMS shows it when the app is added.
+         */
+        player?: "read" | "control";
+    };
+    bindings?: string[];
+    /**
+     * Named binding slots (ADR 0053, decision 8; DES-AP-01): each a field the app shows, mapped to a table column in a layout's binding. A layout's binding.fields names these.
+     */
+    slots?: {
+        [k: string]: {
+            label: string;
+            /**
+             * What the column must hold.
+             */
+            type: "text" | "number" | "currency" | "date" | "datetime" | "image" | "url" | "boolean";
+            required?: boolean;
+            help?: string;
+        } | undefined;
+    };
+    /**
+     * The presets the app's enter and exit hooks take (ADR 0053, decision 8; DES-AH-01 to 07). An app without them is animated as one box.
+     */
+    animation?: {
+        /**
+         * Presets its enter hook plays (fade, slide, typewriter...).
+         */
+        enter?: string[];
+        /**
+         * Presets its exit hook plays.
+         */
+        exit?: string[];
+        /**
+         * Its items can enter one after another (DES-AN-06).
+         */
+        stagger?: boolean;
+        /**
+         * It pages through its items, playing exit and enter at each page (DES-DB-13): its page count comes from the snapshot the layout started with.
+         */
+        pages?: boolean;
+    };
+    /**
+     * The data service's sources it reads (ADR 0069): weather, news.
+     */
+    data?: string[];
+    events?: {
+        emits?: string[];
+        consumes?: string[];
+    };
+    mobile?: {
+        mode?: "render" | "snapshot" | "hidden";
+    };
+    locales?: CommonLocale[];
+}
+export interface Param {
+    /**
+     * A param's kind. A font param's value is a typography object (layout.schema.json#/$defs/typography): a family with its weight, style, decoration, letter case and spacing, line height, shadow and scale.
+     */
+    type: "string" | "text" | "number" | "boolean" | "enum" | "color" | "font" | "media" | "location" | "datetime" | "duration" | "url" | "datatable" | "column" | "secret" | "json";
+    label?: string;
+    default?: unknown;
+    /**
+     * On an enum, its choices. On any other type, suggestions the designer offers, while any valid value is still allowed (WP-0098). Each is a plain value, or labeled: shown by its label, under its group.
+     *
+     * @minItems 1
+     */
+    values?: [ParamValue, ...ParamValue[]];
+    group?: string;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    help?: string;
+    advanced?: boolean;
+    /**
+     * When the param applies (WP-0068 part f, after gadget.yaml's depends): each key names another param of this app, and its test must hold. A param that does not apply is not shown in the designer and is not required; its value is kept.
+     */
+    when?: {
+        [k: string]: ParamTest | undefined;
+    };
+}
+/**
+ * A value as a param's values list it (WP-0098): a string, number or boolean, or labeled ({ value, label, group }) for the designer to show by its label, under its group.
+ */
+export interface ParamValue {
+    [k: string]: unknown | undefined;
+}
+/**
+ * A test of another param's value (WP-0068 part f): every one given must hold. Values compare as text.
+ */
+export interface ParamTest {
+    /**
+     * Its value is one of these.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    anyOf?: [string | number | boolean, ...(string | number | boolean)[]];
+    /**
+     * Its value, a list, holds every one of these.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    allOf?: [string | number | boolean, ...(string | number | boolean)[]];
+    /**
+     * Its value is none of these.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    noneOf?: [string | number | boolean, ...(string | number | boolean)[]];
+    /**
+     * true: it has a value; false: it has none (absent, empty text, or an empty list).
+     */
+    set?: boolean;
+}

package/dist/contract/app-definition.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/app-definition.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-answer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What the data service answers for any source (ADR 0069): GET /v0/{source}. data is the source's normalized form (data-weather, data-news, data-quotes, data-series, data-calendar). Players keep the last answer and show it offline with its age.
+ */
+export interface DataServiceAnswer {
+    /**
+     * The source asked: weather, news, quotes, series, calendar.
+     */
+    source: string;
+    /**
+     * The parameters the answer is for, as the service normalized them (a place rounded to 0.1°, a feed's URL). A calendar's address is left out: it often works as a password (WP-0111).
+     */
+    params: {
+        [k: string]: (string | number | boolean) | undefined;
+    };
+    /**
+     * When the provider answered.
+     */
+    fetchedAt: string;
+    /**
+     * When to ask again.
+     */
+    expiresAt: string;
+    /**
+     * True when the provider failed and this is the last answer it gave, kept for up to a day past expiresAt.
+     */
+    stale: boolean;
+    /**
+     * Credit the source requires wherever its data is shown (Open-Meteo: CC BY 4.0).
+     */
+    attribution?: {
+        text: string;
+        url?: string;
+    };
+    /**
+     * The source's normalized data.
+     */
+    data: {
+        [k: string]: unknown | undefined;
+    };
+}

package/dist/contract/data-answer.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-answer.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};