@wyndlass/app-sdk 0.0.0 → 1.1.0

package/cli/package.mjs

@@ -0,0 +1,119 @@
+// What `check` and `pack` share (WP-0101 decisions 5 and 8): a project's definition and module, built as core takes them,
+// and the verdict core's checks give, from the reference reader the protocol holds core to (app-package.mjs, a copy).
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { build } from "esbuild";
+import { checkAppPackage, DATA_SOURCES, LIMITS } from "./app-package.mjs";
+import { zip } from "./zip.mjs";
+
+const sdk = join(dirname(fileURLToPath(import.meta.url)), "..");
+/** The SDK's own version, which a module's first line names. */
+export const SDK_VERSION = JSON.parse(readFileSync(join(sdk, "package.json"), "utf8")).version;
+
+/** A refusal the CLI says in words and exits 1 on. */
+export class CliError extends Error {}
+
+let validator;
+/** app-definition.schema.json, compiled as the protocol's own check compiles it. */
+export function definitionValidator() {
+  if (validator) return validator;
+  const ajv = new Ajv2020({ strict: true, allErrors: true, strictRequired: false });
+  addFormats(ajv);
+  ajv.addSchema(JSON.parse(readFileSync(join(sdk, "protocol", "common.schema.json"), "utf8")));
+  validator = ajv.compile(JSON.parse(readFileSync(join(sdk, "protocol", "app-definition.schema.json"), "utf8")));
+  return validator;
+}
+
+/** Core's verdict on a package's bytes: "valid", or the code of the first check that fails. */
+export function verdict(bytes) { return checkAppPackage(bytes, definitionValidator()); }
+
+/** Each code in words, as `check` and `pack` say them. */
+export const MEANING = {
+  "too-large": `it is over a limit: the zip at most ${LIMITS.zip / 1048576} MiB, app.json ${LIMITS.definition / 1024} KiB, app.js ${LIMITS.module / 1048576} MiB`,
+  "not-a-zip": "it is not a zip Wyndlass can read",
+  encrypted: "an entry is encrypted",
+  folder: "it holds a folder",
+  path: "an entry's name has a / or \\ in it",
+  entries: "a package holds exactly app.json and app.js",
+  "size-mismatch": "an entry unpacks to another size than it says",
+  "definition-json": "app.json is not a JSON object in UTF-8",
+  "definition-schema": "app.json does not match app-definition.schema.json",
+  "definition-id": "its id is under com.wyndlass., which is Wyndlass's own: use your organization's own domain",
+  "definition-when": "a param's when names itself, or a param there is not",
+  "definition-url": "a url param's values and default must be https addresses",
+  "definition-peers": "capabilities.peers is not open to apps yet",
+  "definition-data": `data names a source apps may not read: only ${DATA_SOURCES.join(", ")}`,
+  "module-syntax": "the module is not an ES2020 module",
+  "module-import": "the module imports something: an app's module brings everything it needs",
+  "module-default": "the module has no default export: export the element's class as the default",
+};
+
+/** The project's source of the module: src/app.tsx, .ts, .jsx or .js. */
+export function entryOf(dir) {
+  const entry = ["app.tsx", "app.ts", "app.jsx", "app.js"].map(n => join(dir, "src", n)).find(p => existsSync(p));
+  if (!entry) throw new CliError(`${dir} has no src/app.ts (or .tsx, .js, .jsx): the module's source`);
+  return entry;
+}
+
+/** The project's definition, as text and as read (null when it is not JSON). */
+export function definitionOf(dir) {
+  const path = join(dir, "app.json");
+  if (!existsSync(path)) throw new CliError(`${dir} has no app.json: the app's definition`);
+  const text = readFileSync(path, "utf8");
+  let read = null;
+  try { read = JSON.parse(text); } catch { /* the check says so */ }
+  return { text, read };
+}
+
+/**
+ * The module as core takes it: one ES2020 file, minified, its first line naming the app and the SDK. CSS a source
+ * imports becomes text, for css(); images and fonts are inlined. The source map goes beside it, never into it.
+ */
+export async function bundle(dir, id, version) {
+  const outfile = join(dir, "dist", `${id}-${version}.js`);
+  const result = await build({
+    entryPoints: [entryOf(dir)], absWorkingDir: dir, outfile, bundle: true, format: "esm", target: "es2020", platform: "browser", minify: true,
+    write: false, legalComments: "none", charset: "utf8", sourcemap: "external", jsx: "automatic", logLevel: "silent",
+    define: { "process.env.NODE_ENV": "\"production\"" },
+    banner: { js: `/* ${id} ${version}, @wyndlass/app-sdk ${SDK_VERSION} */` },
+    loader: { ".css": "text", ".png": "dataurl", ".jpg": "dataurl", ".jpeg": "dataurl", ".gif": "dataurl", ".webp": "dataurl", ".svg": "dataurl", ".woff2": "dataurl", ".woff": "dataurl" },
+  }).catch(e => { throw new CliError(`the module does not build: ${e.errors?.[0]?.text ?? e.message}`); });
+  const code = result.outputFiles.find(f => f.path.endsWith(".js")).contents;
+  const map = result.outputFiles.find(f => f.path.endsWith(".js.map")).contents;
+  return { code, map };
+}
+
+/** Every source file of the project, for the warnings. */
+function sources(dir) {
+  return readdirSync(dir).flatMap(n => {
+    const p = join(dir, n);
+    return statSync(p).isDirectory() ? sources(p) : /\.[jt]sx?$/.test(n) ? [p] : [];
+  });
+}
+
+/**
+ * A project's package, built and checked: its id and version, the zip and the map, core's verdict on the zip, and
+ * warnings, which refuse nothing: a module over 1 MiB, which a screen loads at every start; no ready() in the sources.
+ */
+export async function packageOf(dir) {
+  const definition = definitionOf(dir);
+  const id = typeof definition.read?.id === "string" ? definition.read.id : "app";
+  const version = typeof definition.read?.version === "string" ? definition.read.version : "0.0.0";
+  const { code, map } = await bundle(dir, id, version);
+  const bytes = zip([["app.json", Buffer.from(definition.text, "utf8")], ["app.js", code]]);
+  const warnings = [];
+  if (code.length > 1024 * 1024) warnings.push(`the module is ${(code.length / 1048576).toFixed(1)} MiB: a screen loads it at every start`);
+  if (!sources(join(dir, "src")).some(f => /\bready\s*\(/.test(readFileSync(f, "utf8"))))
+    warnings.push("no call to ready() found: a screen reports an app late that has not said it is ready within 5 s");
+  return { id, version, bytes, map, code: verdict(bytes), warnings, definition: definition.read };
+}
+
+/** Why a definition fails its schema, in Ajv's words, for definition-schema. */
+export function schemaErrors(definition) {
+  const validate = definitionValidator();
+  validate(definition);
+  return (validate.errors ?? []).slice(0, 5).map(e => `${e.instancePath || "app.json"} ${e.message}`);
+}

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");