@kaptive/widget-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 state systems gmbh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @kaptive/widget-api
+
+The runtime SDK and manifest schema for [Kaptive](https://kaptive.ch) custom widgets.
+
+A Kaptive custom widget is a small web app — built with `@kaptive/create-widget` and `@kaptive/cli` — that a workspace admin uploads as a bundle and drops into any project. This package is what a widget's own code imports at runtime to receive its parameters and learn about the screen it's running on.
+
+## Install
+
+```bash
+npm install @kaptive/widget-api
+```
+
+If you scaffolded your widget with `npm create @kaptive/widget`, this is already a dependency.
+
+## Usage
+
+```ts
+import { kaptive } from "@kaptive/widget-api";
+
+const { parameters, player } = await kaptive.ready();
+
+document.title = parameters.title;
+```
+
+`ready()` resolves once the widget's parameters and player information are known, whichever of three places they come from:
+
+1. `kaptive widget dev` — from `kaptive.dev.json`, while you're developing.
+2. A real Kaptive player — from the on-device player agent, over a local WebSocket.
+3. Anywhere else (deployed standalone, opened directly) — from `kaptive.prod.json` if you built one in, otherwise the manifest's own defaults.
+
+Your widget code never needs to know which of the three it's in.
+
+## Subpaths
+
+- `@kaptive/widget-api` — the runtime above (`kaptive.ready()`).
+- `@kaptive/widget-api/manifest` — the `kaptive.manifest.json` schema and parameter-value reconciliation. Used by `@kaptive/cli` and the Kaptive manager; most widget authors never import this directly.
+- `@kaptive/widget-api/bundle` — the size/entry-count/path rules a packaged bundle must satisfy, shared by the CLI, the Kaptive manager's upload validation, and the on-device player agent.
+- `@kaptive/widget-api/protocol` — the wire protocol between a widget and the player agent's local WebSocket.
+
+## Learn more
+
+See the [`@kaptive/create-widget`](https://www.npmjs.com/package/@kaptive/create-widget) README for how to scaffold, build, and ship a widget, including the full list of parameter types.

package/dist/bundle.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Rules a widget bundle (the zip a widget author uploads) has to satisfy.
+ *
+ * These are enforced three times over, on purpose: by `kaptive widget pack` so
+ * an author finds out at build time, by the Kaptive manager at upload so a
+ * hand-made zip cannot get in, and by the player agent at extraction so a
+ * device never trusts that the two checks upstream actually ran.
+ *
+ * Two tiers, not one:
+ *
+ * - {@link WIDGET_BUNDLE_HARD_LIMITS} is an absolute ceiling nothing may ever
+ *   exceed, on any workspace, at any point in the pipeline. The player agent
+ *   and `kaptive widget pack` enforce exactly this tier — a device has no
+ *   notion of a workspace's plan, and a bundle built to ship at all must pass
+ *   on every plan.
+ * - A **compressed-size cap** narrower than the hard ceiling is a per-workspace
+ *   plan setting (`WorkspacePlan.widgetBundleLimit` in the Kaptive manager,
+ *   defaulting to {@link DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES}), which an
+ *   admin can raise per workspace up to the hard ceiling. {@link
+ *   bundleLimitsForCompressedCap} turns that one number into the full set of
+ *   limits the manager's upload validation enforces.
+ */
+export interface WidgetBundleLimits {
+    /** Size of the uploaded zip itself. */
+    maxCompressedBytes: number;
+    /** Total size of everything inside it. */
+    maxUncompressedBytes: number;
+    maxEntries: number;
+    /**
+     * Guards against zip bombs: a single entry may not expand by more than this
+     * factor. Text assets compress well, so the bar is deliberately generous.
+     */
+    maxCompressionRatio: number;
+    /** The one entry actually decompressed before the rest is even listed. */
+    maxManifestBytes: number;
+}
+export declare const WIDGET_BUNDLE_HARD_LIMITS: WidgetBundleLimits;
+/** @deprecated Use {@link WIDGET_BUNDLE_HARD_LIMITS}. Kept for existing callers. */
+export declare const WIDGET_BUNDLE_LIMITS: WidgetBundleLimits;
+/** A workspace plan's `widgetBundleLimit` when nothing else has been set. */
+export declare const DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES: number;
+/**
+ * Turns one workspace plan setting — the compressed bundle size it allows —
+ * into the full set of limits `validateWidgetBundle` checks against. Both the
+ * compressed cap and its derived uncompressed cap are clamped to {@link
+ * WIDGET_BUNDLE_HARD_LIMITS}, so a plan can never authorize more than the
+ * device and the CLI would accept regardless.
+ */
+export declare function bundleLimitsForCompressedCap(compressedCap: number): WidgetBundleLimits;
+/**
+ * File types a bundle may contain. Anything else — executables, archives,
+ * shell scripts — is rejected rather than silently served to the kiosk browser.
+ */
+export declare const ALLOWED_BUNDLE_EXTENSIONS: ReadonlySet<string>;
+export declare function bundleEntryExtension(path: string): string;
+/**
+ * True for OS/archive litter: `.DS_Store` (and its AppleDouble `._*` sibling
+ * files), Windows' `Thumbs.db`/`desktop.ini`, KDE's `.directory`, and anything
+ * macOS's Archive Utility drops into a `__MACOSX/` directory when zipping.
+ */
+export declare function isIgnoredBundleEntry(path: string): boolean;
+/**
+ * Validates one entry path from a bundle. Returns `null` when the path is fine,
+ * or a human-readable reason when it is not.
+ */
+export declare function checkBundleEntryPath(path: string): string | null;
+export interface BundleEntry {
+    /** Bundle-relative path, `/`-separated. */
+    path: string;
+    /** Uncompressed size in bytes. */
+    size: number;
+    /** Compressed size in bytes, when the source knows it. */
+    compressedSize?: number;
+}
+/**
+ * Validates a whole bundle listing against `limits` (a workspace's own, via
+ * {@link bundleLimitsForCompressedCap}, or {@link WIDGET_BUNDLE_HARD_LIMITS}
+ * by default — what the CLI and the device use, since neither knows about a
+ * workspace plan). Returns every problem found rather than only the first, so
+ * an author fixing a bundle sees the full list in one go.
+ */
+export declare function checkBundleEntries(entries: readonly BundleEntry[], limits?: WidgetBundleLimits): string[];
+export declare function formatBytes(bytes: number): string;

package/dist/bundle.js

@@ -0,0 +1,158 @@
+//#region src/bundle.ts
+var WIDGET_BUNDLE_HARD_LIMITS = {
+	maxCompressedBytes: 524288e3,
+	maxUncompressedBytes: 1073741824,
+	maxEntries: 2e3,
+	maxCompressionRatio: 100,
+	maxManifestBytes: 262144
+};
+/** @deprecated Use {@link WIDGET_BUNDLE_HARD_LIMITS}. Kept for existing callers. */
+var WIDGET_BUNDLE_LIMITS = WIDGET_BUNDLE_HARD_LIMITS;
+/** A workspace plan's `widgetBundleLimit` when nothing else has been set. */
+var DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES = 52428800;
+/**
+* How generous the derived uncompressed cap is relative to a plan's
+* compressed-size cap. A widget bundle is mostly JS/CSS/HTML plus already-
+* compressed media (images, fonts, video), so real bundles land well under
+* this even before the hard ceiling would clip it.
+*/
+var UNCOMPRESSED_CAP_MULTIPLIER = 5;
+/**
+* Turns one workspace plan setting — the compressed bundle size it allows —
+* into the full set of limits `validateWidgetBundle` checks against. Both the
+* compressed cap and its derived uncompressed cap are clamped to {@link
+* WIDGET_BUNDLE_HARD_LIMITS}, so a plan can never authorize more than the
+* device and the CLI would accept regardless.
+*/
+function bundleLimitsForCompressedCap(compressedCap) {
+	const maxCompressedBytes = Math.min(Math.max(compressedCap, 0), WIDGET_BUNDLE_HARD_LIMITS.maxCompressedBytes);
+	const maxUncompressedBytes = Math.min(maxCompressedBytes * UNCOMPRESSED_CAP_MULTIPLIER, WIDGET_BUNDLE_HARD_LIMITS.maxUncompressedBytes);
+	return {
+		...WIDGET_BUNDLE_HARD_LIMITS,
+		maxCompressedBytes,
+		maxUncompressedBytes
+	};
+}
+/**
+* File types a bundle may contain. Anything else — executables, archives,
+* shell scripts — is rejected rather than silently served to the kiosk browser.
+*/
+var ALLOWED_BUNDLE_EXTENSIONS = /* @__PURE__ */ new Set([
+	"html",
+	"js",
+	"mjs",
+	"cjs",
+	"css",
+	"json",
+	"map",
+	"wasm",
+	"txt",
+	"csv",
+	"xml",
+	"svg",
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"webp",
+	"avif",
+	"ico",
+	"bmp",
+	"woff",
+	"woff2",
+	"ttf",
+	"otf",
+	"eot",
+	"mp4",
+	"webm",
+	"ogg",
+	"mp3",
+	"wav"
+]);
+function bundleEntryExtension(path) {
+	const base = path.slice(path.lastIndexOf("/") + 1);
+	const dot = base.lastIndexOf(".");
+	return dot <= 0 ? "" : base.slice(dot + 1).toLowerCase();
+}
+/**
+* Filenames that turn up in a bundle by accident of the operating system or
+* archive tool, never by the widget author's intent — most commonly
+* `.DS_Store`, copied in verbatim when a Vite `public/` directory is copied to
+* `dist/`. These are skipped everywhere a bundle is read, rather than treated
+* as a reason to reject it: `kaptive widget pack` leaves them out of a fresh
+* zip, and this same check tolerates one already baked into a hand-made or
+* pre-existing bundle at validate/upload time and at device extraction.
+*/
+var IGNORED_BUNDLE_BASENAMES = /* @__PURE__ */ new Set([
+	".DS_Store",
+	"Thumbs.db",
+	"desktop.ini",
+	".directory"
+]);
+/**
+* True for OS/archive litter: `.DS_Store` (and its AppleDouble `._*` sibling
+* files), Windows' `Thumbs.db`/`desktop.ini`, KDE's `.directory`, and anything
+* macOS's Archive Utility drops into a `__MACOSX/` directory when zipping.
+*/
+function isIgnoredBundleEntry(path) {
+	const segments = path.split("/");
+	const basename = segments[segments.length - 1] ?? path;
+	return IGNORED_BUNDLE_BASENAMES.has(basename) || basename.startsWith("._") || segments.includes("__MACOSX");
+}
+/** Linux (and the device's filesystem) limits a single path component to this
+* many *bytes*, not characters — a distinction that matters once a segment
+* holds multibyte UTF-8. */
+var MAX_PATH_SEGMENT_BYTES = 255;
+var textEncoder = new TextEncoder();
+/**
+* Validates one entry path from a bundle. Returns `null` when the path is fine,
+* or a human-readable reason when it is not.
+*/
+function checkBundleEntryPath(path) {
+	if (path.length === 0) return "Empty entry path";
+	if (path.length > 255) return `Entry path is too long: ${path}`;
+	if (path.includes("\\")) return `Entry path contains a backslash: ${path}`;
+	if (path.includes("\0")) return `Entry path contains a null byte`;
+	if (path.startsWith("/")) return `Entry path is absolute: ${path}`;
+	if (/^[A-Za-z]:/.test(path)) return `Entry path is absolute: ${path}`;
+	const segments = path.split("/");
+	for (const segment of segments) {
+		if (segment === "" || segment === "." || segment === "..") return `Entry path escapes the bundle: ${path}`;
+		if (textEncoder.encode(segment).length > MAX_PATH_SEGMENT_BYTES) return `Path segment is too long: ${segment}`;
+	}
+	const extension = bundleEntryExtension(path);
+	if (!ALLOWED_BUNDLE_EXTENSIONS.has(extension)) return extension ? `Unsupported file type ".${extension}": ${path}` : `File without an extension: ${path}`;
+	return null;
+}
+/**
+* Validates a whole bundle listing against `limits` (a workspace's own, via
+* {@link bundleLimitsForCompressedCap}, or {@link WIDGET_BUNDLE_HARD_LIMITS}
+* by default — what the CLI and the device use, since neither knows about a
+* workspace plan). Returns every problem found rather than only the first, so
+* an author fixing a bundle sees the full list in one go.
+*/
+function checkBundleEntries(entries, limits = WIDGET_BUNDLE_HARD_LIMITS) {
+	const problems = [];
+	const relevant = entries.filter((entry) => !isIgnoredBundleEntry(entry.path));
+	if (relevant.length > limits.maxEntries) problems.push(`Bundle has ${relevant.length} files, the limit is ${limits.maxEntries}`);
+	let total = 0;
+	const seenPaths = /* @__PURE__ */ new Set();
+	for (const entry of relevant) {
+		const problem = checkBundleEntryPath(entry.path);
+		if (problem) problems.push(problem);
+		if (seenPaths.has(entry.path)) problems.push(`Duplicate bundle entry: ${entry.path}`);
+		seenPaths.add(entry.path);
+		total += entry.size;
+		if (entry.compressedSize !== void 0 && entry.compressedSize > 0 && entry.size / entry.compressedSize > limits.maxCompressionRatio) problems.push(`"${entry.path}" expands more than ${limits.maxCompressionRatio}x and looks like a zip bomb`);
+	}
+	if (total > limits.maxUncompressedBytes) problems.push(`Bundle contents total ${formatBytes(total)}, the limit is ${formatBytes(limits.maxUncompressedBytes)}`);
+	return problems;
+}
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1073741824) return `${(bytes / 1048576).toFixed(1)} MB`;
+	return `${(bytes / 1073741824).toFixed(1)} GB`;
+}
+//#endregion
+export { ALLOWED_BUNDLE_EXTENSIONS, DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES, WIDGET_BUNDLE_HARD_LIMITS, WIDGET_BUNDLE_LIMITS, bundleEntryExtension, bundleLimitsForCompressedCap, checkBundleEntries, checkBundleEntryPath, formatBytes, isIgnoredBundleEntry };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import type { WidgetManifest } from "./manifest.js";
+import { type WireWidgetBlockInfo, type WireWidgetPlayerInfo } from "./protocol.js";
+export type { ResolvedParameterValue, ResolvedParameterValues, WidgetAssetValue, WidgetParameterValue, WidgetParameterValues, } from "./values.js";
+export type { WidgetManifest, WidgetParameter } from "./manifest.js";
+/**
+ * The parameters declared by this widget's manifest.
+ *
+ * Empty here on purpose: `kaptive widget dev` and `kaptive widget build`
+ * generate `src/kaptive-env.d.ts`, which augments this interface with one
+ * property per manifest parameter. That is what makes `parameters.city` a
+ * `string` rather than `unknown`.
+ */
+export interface KaptiveParameters {
+}
+/** Information about the screen the widget is running on. */
+export interface KaptivePlayerInfo {
+    deviceId: string;
+    deviceName: string;
+    orientation: 0 | 90 | 180 | 270;
+    /** IANA zone of the workspace, e.g. `"Europe/Zurich"`. */
+    timezone: string;
+    /** Project resolution in CSS pixels, before the page's fit-to-screen scale. */
+    resolution: {
+        width: number;
+        height: number;
+    };
+}
+/** The content block this widget instance was placed in. */
+export interface KaptiveBlockInfo {
+    id: string;
+    width: number;
+    height: number;
+}
+export interface KaptiveContext {
+    parameters: KaptiveParameters;
+    player: KaptivePlayerInfo;
+    block: KaptiveBlockInfo;
+}
+/**
+ * A context built server-side by `kaptive widget` (from `kaptive.dev.json` or
+ * `kaptive.prod.json`) and injected into the page. Its `parameters` are
+ * already resolved — plain values, assets already turned into URLs — unlike
+ * the raw `WidgetParameterValues` the WebSocket path sends.
+ */
+interface InjectedFileContext {
+    parameters?: Record<string, unknown>;
+    player?: Partial<WireWidgetPlayerInfo>;
+    block?: Partial<WireWidgetBlockInfo>;
+}
+/** Values injected into the page by the `kaptiveWidget()` Vite plugin. */
+interface KaptiveInjected {
+    manifest?: WidgetManifest;
+    devContext?: InjectedFileContext;
+    prodContext?: InjectedFileContext;
+}
+declare global {
+    interface Window {
+        __KAPTIVE__?: KaptiveInjected;
+    }
+}
+declare class WidgetClient {
+    #private;
+    constructor();
+    /**
+     * Resolves once the widget's parameters and player information are known.
+     * Safe to call more than once — every caller gets the same context. Always
+     * resolves — a widget with nowhere to get real values from still gets its
+     * manifest's defaults, so it renders standalone rather than hang, and so
+     * does one running on a real player whose agent never answers: after
+     * {@link READY_TIMEOUT_MS} with no reply, `ready()` falls back to those same
+     * defaults rather than waiting forever.
+     */
+    ready(): Promise<KaptiveContext>;
+    /** The resolved context, or `null` before {@link ready} has resolved. */
+    getContext(): KaptiveContext | null;
+    /** Closes the connection to the player agent. Rarely needed. */
+    disconnect(): void;
+}
+/** The widget runtime. One instance per page. */
+export declare const kaptive: WidgetClient;

package/dist/index.js

@@ -0,0 +1,250 @@
+import { i as resolveParameterValues } from "./values-BygiDSdW.js";
+import { BLOCK_ID_QUERY_PARAM, PLAYER_AGENT_URL, parseServerMessage } from "./protocol.js";
+//#region src/index.ts
+/**
+* `@kaptive/widget-api` — the runtime a Kaptive custom widget uses to receive
+* its parameters and learn about the screen it is running on.
+*
+* ```ts
+* import { kaptive } from "@kaptive/widget-api";
+*
+* const { parameters, player } = await kaptive.ready();
+* ```
+*
+* A widget runs in a sandboxed iframe on its own origin. Depending on where
+* it's running, `ready()` gets its context from one of three places, in order:
+*
+* 1. `kaptive widget dev` — from `kaptive.dev.json`.
+* 2. A real Kaptive player — from the player agent's local WebSocket.
+* 3. Anywhere else (deployed standalone, opened directly) — from
+*    `kaptive.prod.json` if the build had one, else the manifest's defaults.
+*
+* A widget never needs to know which one it's in — `ready()` always resolves.
+*
+* Parameters are read once, at start-up. Editing a parameter or uploading a new
+* bundle remounts the iframe, so the widget simply starts again with the new
+* values — there is nothing to subscribe to.
+*/
+var RECONNECT_DELAY_MS = 2e3;
+/**
+* How long to wait before asking again when the agent reports the block is not
+* in the content currently on screen. The iframe only exists because the player
+* rendered it, so this is a narrow race — the content changed between mount and
+* the request — and one that resolves itself.
+*/
+var RETRY_DELAY_MS = 1e3;
+/**
+* How long `ready()` waits for the player agent before giving up on it and
+* falling back to the manifest's defaults. Without this, a widget on a device
+* whose agent never answers — down, mid-restart, a bug on its end — would
+* never resolve at all, contradicting {@link WidgetClient.ready}'s own
+* contract that it always does. Generous: a real agent typically replies in
+* well under a second, so this only ever matters when something is actually
+* wrong on the other end.
+*/
+var READY_TIMEOUT_MS = 15e3;
+var DEFAULT_PLAYER = {
+	deviceId: "dev-device",
+	deviceName: "Development",
+	orientation: 0,
+	timezone: "Europe/Zurich",
+	resolution: {
+		width: 1920,
+		height: 1080
+	}
+};
+function toOrientation(value) {
+	return value === 90 || value === 180 || value === 270 ? value : 0;
+}
+function toPlayerInfo(wire) {
+	return {
+		deviceId: wire?.device_id ?? DEFAULT_PLAYER.deviceId,
+		deviceName: wire?.device_name ?? DEFAULT_PLAYER.deviceName,
+		orientation: toOrientation(wire?.orientation ?? 0),
+		timezone: wire?.timezone ?? DEFAULT_PLAYER.timezone,
+		resolution: wire?.resolution ?? DEFAULT_PLAYER.resolution
+	};
+}
+var WidgetClient = class {
+	#injected;
+	#socket = null;
+	#reconnectTimer = null;
+	#closed = false;
+	#blockId;
+	#context = null;
+	#readyPromise = null;
+	#resolveReady = null;
+	#retryTimer = null;
+	#readyTimeoutTimer = null;
+	constructor() {
+		this.#injected = typeof window === "undefined" ? {} : window.__KAPTIVE__ ?? {};
+		this.#blockId = typeof window === "undefined" ? null : new URLSearchParams(window.location.search).get(BLOCK_ID_QUERY_PARAM);
+	}
+	/**
+	* Resolves once the widget's parameters and player information are known.
+	* Safe to call more than once — every caller gets the same context. Always
+	* resolves — a widget with nowhere to get real values from still gets its
+	* manifest's defaults, so it renders standalone rather than hang, and so
+	* does one running on a real player whose agent never answers: after
+	* {@link READY_TIMEOUT_MS} with no reply, `ready()` falls back to those same
+	* defaults rather than waiting forever.
+	*/
+	ready() {
+		if (this.#readyPromise) return this.#readyPromise;
+		this.#readyPromise = new Promise((resolve) => {
+			this.#resolveReady = resolve;
+			if (this.#injected.devContext) {
+				this.#applyContext(this.#fileContext(this.#injected.devContext));
+				return;
+			}
+			if (this.#blockId) {
+				this.#connect();
+				this.#readyTimeoutTimer = setTimeout(() => {
+					this.#readyTimeoutTimer = null;
+					if (this.#context !== null) return;
+					console.warn(`[kaptive] no response from the player agent after ${READY_TIMEOUT_MS}ms; falling back to the manifest's default parameters.`);
+					this.#applyContext(this.#defaultContext());
+				}, READY_TIMEOUT_MS);
+				return;
+			}
+			const prod = this.#injected.prodContext;
+			this.#applyContext(prod ? this.#fileContext(prod) : this.#defaultContext());
+		});
+		return this.#readyPromise;
+	}
+	/** The resolved context, or `null` before {@link ready} has resolved. */
+	getContext() {
+		return this.#context;
+	}
+	/** Closes the connection to the player agent. Rarely needed. */
+	disconnect() {
+		this.#closed = true;
+		if (this.#reconnectTimer !== null) clearTimeout(this.#reconnectTimer);
+		if (this.#retryTimer !== null) clearTimeout(this.#retryTimer);
+		if (this.#readyTimeoutTimer !== null) clearTimeout(this.#readyTimeoutTimer);
+		this.#reconnectTimer = null;
+		this.#retryTimer = null;
+		this.#readyTimeoutTimer = null;
+		this.#socket?.close();
+		this.#socket = null;
+	}
+	/**
+	* Turns an already-resolved file context (`kaptive.dev.json` /
+	* `kaptive.prod.json`, loaded server-side) into a `KaptiveContext`. Never
+	* routes through `#buildContext()`: that resolves raw values, and these are
+	* already resolved — doing it twice turns an asset URL back into `null`.
+	*/
+	#fileContext(file) {
+		return {
+			parameters: file.parameters ?? {},
+			player: toPlayerInfo(file.player),
+			block: {
+				id: file.block?.id ?? "standalone",
+				width: file.block?.width ?? window.innerWidth,
+				height: file.block?.height ?? window.innerHeight
+			}
+		};
+	}
+	/** Manifest defaults only — used when there is no player and no config file. */
+	#defaultContext() {
+		const manifest = this.#injected.manifest;
+		return {
+			parameters: manifest ? resolveParameterValues(manifest, {}) : {},
+			player: DEFAULT_PLAYER,
+			block: {
+				id: "standalone",
+				width: window.innerWidth,
+				height: window.innerHeight
+			}
+		};
+	}
+	#buildContext(rawParameters, player, block) {
+		const manifest = this.#injected.manifest;
+		return {
+			parameters: manifest ? resolveParameterValues(manifest, rawParameters) : rawParameters,
+			player,
+			block
+		};
+	}
+	#applyContext(next) {
+		if (this.#readyTimeoutTimer !== null) {
+			clearTimeout(this.#readyTimeoutTimer);
+			this.#readyTimeoutTimer = null;
+		}
+		this.#context = next;
+		if (this.#resolveReady) {
+			this.#resolveReady(next);
+			this.#resolveReady = null;
+		}
+		this.#closed = true;
+		this.#socket?.close();
+		this.#socket = null;
+	}
+	#send(socket, message) {
+		socket.send(JSON.stringify(message));
+	}
+	#connect() {
+		if (this.#closed) return;
+		const socket = new WebSocket(PLAYER_AGENT_URL);
+		this.#socket = socket;
+		socket.addEventListener("open", () => {
+			this.#send(socket, {
+				type: "identify",
+				client_type: "widget",
+				version: this.#injected.manifest?.version ?? null
+			});
+			this.#requestContext(socket);
+		});
+		socket.addEventListener("message", (event) => {
+			const message = parseServerMessage(event.data);
+			if (!message) return;
+			switch (message.type) {
+				case "widget_context":
+					if (message.block_id !== this.#blockId) return;
+					this.#applyContext(this.#buildContext(message.parameters, toPlayerInfo(message.player), {
+						id: message.block.id,
+						width: message.block.width,
+						height: message.block.height
+					}));
+					break;
+				case "widget_unavailable":
+					this.#scheduleRetry();
+					break;
+				case "error": console.error("[kaptive] player agent error:", message.message);
+			}
+		});
+		socket.addEventListener("close", () => {
+			this.#socket = null;
+			this.#scheduleReconnect();
+		});
+		socket.addEventListener("error", () => {
+			socket.close();
+		});
+	}
+	#requestContext(socket) {
+		if (!this.#blockId) return;
+		this.#send(socket, {
+			type: "widget_request_context",
+			block_id: this.#blockId
+		});
+	}
+	#scheduleRetry() {
+		if (this.#closed || this.#retryTimer !== null) return;
+		this.#retryTimer = setTimeout(() => {
+			this.#retryTimer = null;
+			const socket = this.#socket;
+			if (socket && socket.readyState === WebSocket.OPEN) this.#requestContext(socket);
+		}, RETRY_DELAY_MS);
+	}
+	#scheduleReconnect() {
+		if (this.#closed || this.#reconnectTimer !== null) return;
+		this.#reconnectTimer = setTimeout(() => {
+			this.#reconnectTimer = null;
+			this.#connect();
+		}, RECONNECT_DELAY_MS);
+	}
+};
+/** The widget runtime. One instance per page. */
+var kaptive = new WidgetClient();
+//#endregion
+export { kaptive };

package/dist/manifest.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The Kaptive widget manifest — the contract between a widget author, the
+ * Kaptive manager (which renders the parameters as a properties panel) and the
+ * player (which feeds the values back to the running widget).
+ *
+ * This module is the single definition of that contract. It is imported by the
+ * `kaptive widget` CLI commands, by the Kaptive manager's upload validation, and by the
+ * player's host bridge, so it must stay free of any DOM or Node dependency.
+ */
+import { z } from "zod";
+/**
+ * Version of the widget runtime contract. A bundle declaring a different
+ * `apiVersion` is rejected at upload rather than silently half-working.
+ */
+export declare const WIDGET_API_VERSION = 1;
+/** The manifest file a widget bundle must carry at its root. */
+export declare const WIDGET_MANIFEST_FILENAME = "kaptive.manifest.json";
+export declare const textParameterSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"text">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const numberParameterSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"number">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodNumber>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const booleanParameterSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"boolean">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const colorParameterSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"color">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Media kinds an asset parameter's picker will offer. These match the pages of
+ * the editor's media library, so the picker is the same one used everywhere
+ * else — full library, upload button and all.
+ */
+export declare const assetKindSchema: z.ZodEnum<{
+    image: "image";
+    video: "video";
+    pdf: "pdf";
+    model: "model";
+}>;
+export type WidgetAssetKind = z.infer<typeof assetKindSchema>;
+export declare const assetParameterSchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"asset">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    accept: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        image: "image";
+        video: "video";
+        pdf: "pdf";
+        model: "model";
+    }>>>;
+}, z.core.$strip>;
+export declare const widgetParameterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"text">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"number">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodNumber>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"boolean">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"color">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"asset">;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    accept: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        image: "image";
+        video: "video";
+        pdf: "pdf";
+        model: "model";
+    }>>>;
+}, z.core.$strip>], "type">;
+/**
+ * Stable identity of a widget, chosen by its author. Re-uploading a bundle with
+ * the same id creates a new version of the same widget rather than a second
+ * entry, so it must never change once published.
+ *
+ * This is the manifest's own `id`, distinct from the database row's `Widget.id`
+ * (a cuid2) — it is that row id, not this one, that the device actually uses as
+ * a DNS label and filesystem directory name (`w-<rowId>.widget.kaptive.localhost`,
+ * see `apps/device-player/nginx.conf` and `is_safe_widget_id` in the player
+ * agent). The restrictive character set here is only for a stable, readable,
+ * URL-safe author-chosen key — dashes are fine in an `id`, unlike in the row id
+ * that ends up as a DNS label.
+ */
+export declare const widgetIdSchema: z.ZodString;
+export declare const widgetManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    apiVersion: z.ZodLiteral<1>;
+    description: z.ZodOptional<z.ZodString>;
+    entry: z.ZodDefault<z.ZodString>;
+    parameters: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodLiteral<"text">;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        multiline: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodLiteral<"number">;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodNumber>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodLiteral<"boolean">;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodLiteral<"color">;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodLiteral<"asset">;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        accept: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            image: "image";
+            video: "video";
+            pdf: "pdf";
+            model: "model";
+        }>>>;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>;
+export type WidgetTextParameter = z.infer<typeof textParameterSchema>;
+export type WidgetNumberParameter = z.infer<typeof numberParameterSchema>;
+export type WidgetBooleanParameter = z.infer<typeof booleanParameterSchema>;
+export type WidgetColorParameter = z.infer<typeof colorParameterSchema>;
+export type WidgetAssetParameter = z.infer<typeof assetParameterSchema>;
+export type WidgetParameter = z.infer<typeof widgetParameterSchema>;
+export type WidgetParameterType = WidgetParameter["type"];
+export type WidgetManifest = z.infer<typeof widgetManifestSchema>;
+export { LOCAL_MEDIA_BASE_URL, isWidgetAssetValue, defaultParameterValue, resolveParameterValues, type WidgetAssetValue, type WidgetParameterValue, type WidgetParameterValues, type ResolvedParameterValue, type ResolvedParameterValues, } from "./values.js";
+/**
+ * Parses and validates an unknown value as a widget manifest.
+ * Returns a flat list of human-readable problems instead of a zod error tree,
+ * because every caller surfaces these straight to a widget author or an admin.
+ */
+export declare function parseWidgetManifest(input: unknown): {
+    ok: true;
+    manifest: WidgetManifest;
+} | {
+    ok: false;
+    errors: string[];
+};

package/dist/manifest.js

@@ -0,0 +1,152 @@
+import { i as resolveParameterValues, n as defaultParameterValue, r as isWidgetAssetValue, t as LOCAL_MEDIA_BASE_URL } from "./values-BygiDSdW.js";
+import { z } from "zod";
+//#region src/manifest.ts
+/**
+* The Kaptive widget manifest — the contract between a widget author, the
+* Kaptive manager (which renders the parameters as a properties panel) and the
+* player (which feeds the values back to the running widget).
+*
+* This module is the single definition of that contract. It is imported by the
+* `kaptive widget` CLI commands, by the Kaptive manager's upload validation, and by the
+* player's host bridge, so it must stay free of any DOM or Node dependency.
+*/
+/**
+* Version of the widget runtime contract. A bundle declaring a different
+* `apiVersion` is rejected at upload rather than silently half-working.
+*/
+var WIDGET_API_VERSION = 1;
+/** The manifest file a widget bundle must carry at its root. */
+var WIDGET_MANIFEST_FILENAME = "kaptive.manifest.json";
+var SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+/**
+* Parameter keys double as property names on the generated `KaptiveParameters`
+* interface, so they are restricted to plain JS identifiers — that keeps the
+* codegen a straight `key: type` line with no quoting rules to get wrong.
+*/
+var parameterKey = z.string().min(1).max(40).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Parameter keys must be valid identifiers (letters, digits and underscore, not starting with a digit)");
+var label = z.string().min(1).max(60);
+var description = z.string().max(200).optional();
+var textParameterSchema = z.object({
+	key: parameterKey,
+	type: z.literal("text"),
+	label,
+	description,
+	default: z.string().optional(),
+	required: z.boolean().optional(),
+	maxLength: z.number().int().positive().max(4096).optional(),
+	multiline: z.boolean().optional()
+});
+var numberParameterSchema = z.object({
+	key: parameterKey,
+	type: z.literal("number"),
+	label,
+	description,
+	default: z.number().finite().optional(),
+	required: z.boolean().optional(),
+	min: z.number().finite().optional(),
+	max: z.number().finite().optional(),
+	step: z.number().finite().positive().optional()
+});
+var booleanParameterSchema = z.object({
+	key: parameterKey,
+	type: z.literal("boolean"),
+	label,
+	description,
+	default: z.boolean().optional()
+});
+var colorParameterSchema = z.object({
+	key: parameterKey,
+	type: z.literal("color"),
+	label,
+	description,
+	default: z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Default colour must be a hex value like #1f2937").optional()
+});
+/**
+* Media kinds an asset parameter's picker will offer. These match the pages of
+* the editor's media library, so the picker is the same one used everywhere
+* else — full library, upload button and all.
+*/
+var assetKindSchema = z.enum([
+	"image",
+	"video",
+	"pdf",
+	"model"
+]);
+var assetParameterSchema = z.object({
+	key: parameterKey,
+	type: z.literal("asset"),
+	label,
+	description,
+	/**
+	* Which kinds of workspace media the editor offers. Defaults to images.
+	* Assets have no default value — a manifest cannot name a file that lives in
+	* someone else's workspace — so an unset asset reaches the widget as `null`.
+	*/
+	accept: z.array(assetKindSchema).nonempty().default(["image"])
+});
+var widgetParameterSchema = z.discriminatedUnion("type", [
+	textParameterSchema,
+	numberParameterSchema,
+	booleanParameterSchema,
+	colorParameterSchema,
+	assetParameterSchema
+]);
+/**
+* Stable identity of a widget, chosen by its author. Re-uploading a bundle with
+* the same id creates a new version of the same widget rather than a second
+* entry, so it must never change once published.
+*
+* This is the manifest's own `id`, distinct from the database row's `Widget.id`
+* (a cuid2) — it is that row id, not this one, that the device actually uses as
+* a DNS label and filesystem directory name (`w-<rowId>.widget.kaptive.localhost`,
+* see `apps/device-player/nginx.conf` and `is_safe_widget_id` in the player
+* agent). The restrictive character set here is only for a stable, readable,
+* URL-safe author-chosen key — dashes are fine in an `id`, unlike in the row id
+* that ends up as a DNS label.
+*/
+var widgetIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{2,63}$/, "Widget id must be 3-64 lowercase letters, digits or dashes and start with a letter or digit");
+var widgetManifestSchema = z.object({
+	id: widgetIdSchema,
+	name: z.string().min(1).max(60),
+	version: z.string().regex(SEMVER, "Version must be valid semver"),
+	apiVersion: z.literal(1),
+	description: z.string().max(200).optional(),
+	/** Bundle-relative HTML file the player loads. */
+	entry: z.string().max(200).regex(/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\.html$/, "Entry must be a relative path to an .html file inside the bundle").refine((entry) => entry.split("/").every((segment) => segment !== "." && segment !== ".."), "Entry must not contain '.' or '..' path segments").default("index.html"),
+	parameters: z.array(widgetParameterSchema).max(32).default([])
+}).superRefine((manifest, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, parameter] of manifest.parameters.entries()) {
+		if (seen.has(parameter.key)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"parameters",
+				index,
+				"key"
+			],
+			message: `Duplicate parameter key "${parameter.key}"`
+		});
+		seen.add(parameter.key);
+	}
+});
+/**
+* Parses and validates an unknown value as a widget manifest.
+* Returns a flat list of human-readable problems instead of a zod error tree,
+* because every caller surfaces these straight to a widget author or an admin.
+*/
+function parseWidgetManifest(input) {
+	const result = widgetManifestSchema.safeParse(input);
+	if (result.success) return {
+		ok: true,
+		manifest: result.data
+	};
+	return {
+		ok: false,
+		errors: result.error.issues.map((issue) => {
+			const path = issue.path.join(".");
+			return path ? `${path}: ${issue.message}` : issue.message;
+		})
+	};
+}
+//#endregion
+export { LOCAL_MEDIA_BASE_URL, WIDGET_API_VERSION, WIDGET_MANIFEST_FILENAME, assetKindSchema, assetParameterSchema, booleanParameterSchema, colorParameterSchema, defaultParameterValue, isWidgetAssetValue, numberParameterSchema, parseWidgetManifest, resolveParameterValues, textParameterSchema, widgetIdSchema, widgetManifestSchema, widgetParameterSchema };

package/dist/protocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Wire protocol between a Kaptive widget and the player agent.
+ *
+ * A widget runs in a sandboxed iframe on its own origin and talks to the player
+ * agent over the same local WebSocket the device player uses
+ * (`ws://127.0.0.1:3511`), identifying itself as a `widget` client. The agent
+ * only accepts loopback peers, so this channel never leaves the device.
+ *
+ * `identify` is not what actually makes the agent treat a connection as a
+ * widget: the agent classifies every connection by its `Origin` header first
+ * — a widget's iframe origin (`w-<id>.widget.kaptive.localhost`) forces
+ * `Widget` regardless of what `identify` claims, since a page cannot forge
+ * the `Origin` its own `WebSocket` calls carry. `identify` only matters for
+ * connections whose origin doesn't settle it (the device player itself, the
+ * launcher). See `classify_origin` in
+ * `apps/player-agent/src/servers/player/protocol.rs`.
+ *
+ * A widget connection is deliberately starved either way: it never receives
+ * `Welcome` or `StateUpdate` (which carry the whole project, every other
+ * widget's parameters included), and the only thing it can ask for is the
+ * context of the one block id it already knows — which reaches it as a query
+ * parameter on its own iframe URL, not something it discovers over this
+ * socket. There is nothing to guess into and no other block's context to
+ * request.
+ *
+ * These types mirror `apps/player-agent/src/servers/player/protocol.rs` and use
+ * its snake_case field names verbatim. The camelCase shapes a widget author
+ * actually sees are built from these in `index.ts`.
+ */
+/** Default address of the player agent's WebSocket server. */
+export declare const PLAYER_AGENT_URL = "ws://127.0.0.1:3511";
+/**
+ * Query parameter the player puts on a widget's iframe URL to tell it which
+ * content block it is rendering.
+ */
+export declare const BLOCK_ID_QUERY_PARAM = "kaptiveBlockId";
+/** Widget → agent. */
+export type WidgetClientMessage = {
+    type: "identify";
+    client_type: "widget";
+    version: string | null;
+} | {
+    type: "widget_request_context";
+    block_id: string;
+};
+/** Screen information, as the agent sends it. */
+export interface WireWidgetPlayerInfo {
+    device_id: string;
+    device_name: string;
+    orientation: number;
+    timezone: string;
+    resolution: {
+        width: number;
+        height: number;
+    };
+}
+/** The content block a widget instance occupies, as the agent sends it. */
+export interface WireWidgetBlockInfo {
+    id: string;
+    width: number;
+    height: number;
+}
+/** Agent → widget. */
+export type WidgetServerMessage = {
+    type: "widget_context";
+    block_id: string;
+    parameters: Record<string, unknown>;
+    player: WireWidgetPlayerInfo;
+    block: WireWidgetBlockInfo;
+} | {
+    type: "widget_unavailable";
+    block_id: string;
+} | {
+    type: "error";
+    message: string;
+};
+export declare function parseServerMessage(data: unknown): WidgetServerMessage | null;

package/dist/protocol.js

@@ -0,0 +1,52 @@
+//#region src/protocol.ts
+/**
+* Wire protocol between a Kaptive widget and the player agent.
+*
+* A widget runs in a sandboxed iframe on its own origin and talks to the player
+* agent over the same local WebSocket the device player uses
+* (`ws://127.0.0.1:3511`), identifying itself as a `widget` client. The agent
+* only accepts loopback peers, so this channel never leaves the device.
+*
+* `identify` is not what actually makes the agent treat a connection as a
+* widget: the agent classifies every connection by its `Origin` header first
+* — a widget's iframe origin (`w-<id>.widget.kaptive.localhost`) forces
+* `Widget` regardless of what `identify` claims, since a page cannot forge
+* the `Origin` its own `WebSocket` calls carry. `identify` only matters for
+* connections whose origin doesn't settle it (the device player itself, the
+* launcher). See `classify_origin` in
+* `apps/player-agent/src/servers/player/protocol.rs`.
+*
+* A widget connection is deliberately starved either way: it never receives
+* `Welcome` or `StateUpdate` (which carry the whole project, every other
+* widget's parameters included), and the only thing it can ask for is the
+* context of the one block id it already knows — which reaches it as a query
+* parameter on its own iframe URL, not something it discovers over this
+* socket. There is nothing to guess into and no other block's context to
+* request.
+*
+* These types mirror `apps/player-agent/src/servers/player/protocol.rs` and use
+* its snake_case field names verbatim. The camelCase shapes a widget author
+* actually sees are built from these in `index.ts`.
+*/
+/** Default address of the player agent's WebSocket server. */
+var PLAYER_AGENT_URL = "ws://127.0.0.1:3511";
+/**
+* Query parameter the player puts on a widget's iframe URL to tell it which
+* content block it is rendering.
+*/
+var BLOCK_ID_QUERY_PARAM = "kaptiveBlockId";
+function parseServerMessage(data) {
+	if (typeof data !== "string") return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || !("type" in parsed)) return null;
+	const { type } = parsed;
+	if (type === "widget_context" || type === "widget_unavailable" || type === "error") return parsed;
+	return null;
+}
+//#endregion
+export { BLOCK_ID_QUERY_PARAM, PLAYER_AGENT_URL, parseServerMessage };

package/dist/values-BygiDSdW.js

@@ -0,0 +1,60 @@
+//#region src/values.ts
+/**
+* Where a player reads media that lives on its own attached storage rather than
+* in the workspace library. Matches the `source: "local"` video block, which is
+* the only other thing that plays files off a stick.
+*/
+var LOCAL_MEDIA_BASE_URL = "http://127.0.0.1:8000";
+function isWidgetAssetValue(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return candidate.source === "local" ? typeof candidate.localFilePath === "string" && candidate.localFilePath.length > 0 : typeof candidate.assetId === "string" && candidate.assetId.length > 0;
+}
+function defaultParameterValue(parameter) {
+	if (parameter.type === "asset") return void 0;
+	if (parameter.default !== void 0) return parameter.default;
+	switch (parameter.type) {
+		case "text": return "";
+		case "number": return parameter.min ?? 0;
+		case "boolean": return false;
+		case "color": return "#000000";
+	}
+}
+function coerce(parameter, value) {
+	if (parameter.type === "asset") {
+		if (!isWidgetAssetValue(value)) return null;
+		return value.source === "local" ? `${LOCAL_MEDIA_BASE_URL}/${value.localFilePath}` : value.assetUrl ?? null;
+	}
+	const fallback = defaultParameterValue(parameter);
+	if (value === void 0) return fallback;
+	switch (parameter.type) {
+		case "text":
+			if (typeof value !== "string") return fallback;
+			return parameter.maxLength !== void 0 ? value.slice(0, parameter.maxLength) : value;
+		case "number": {
+			if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+			let next = value;
+			if (parameter.min !== void 0) next = Math.max(parameter.min, next);
+			if (parameter.max !== void 0) next = Math.min(parameter.max, next);
+			return next;
+		}
+		case "boolean": return typeof value === "boolean" ? value : fallback;
+		case "color": return typeof value === "string" ? value : fallback;
+	}
+}
+/**
+* Reconciles the values stored on a content block against the manifest of the
+* version that is about to run: fills in defaults, clamps out-of-range values
+* and drops keys the manifest no longer declares.
+*
+* This is what makes promoting a widget version safe — a version that adds,
+* removes or retypes a parameter can never hand a widget a value it did not
+* declare, and never leaves a declared parameter undefined.
+*/
+function resolveParameterValues(manifest, stored) {
+	const resolved = {};
+	for (const parameter of manifest.parameters) resolved[parameter.key] = coerce(parameter, stored?.[parameter.key]);
+	return resolved;
+}
+//#endregion
+export { resolveParameterValues as i, defaultParameterValue as n, isWidgetAssetValue as r, LOCAL_MEDIA_BASE_URL as t };

package/dist/values.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Reconciling a widget's stored parameter values against its manifest.
+ *
+ * Split out of `manifest.ts` on purpose: this file has no zod dependency and
+ * none of its own imports are runtime ones — `manifest.ts`'s types are
+ * referenced only via `import type`, which TypeScript erases entirely. That
+ * is what lets `index.ts` (the runtime a widget actually ships) import from
+ * here instead of from `manifest.ts` and never pull zod into a widget's own
+ * bundle, while `@kaptive/widget-api/manifest` (validation, used server-side
+ * and by the CLI, where zod is already a cost being paid) re-exports
+ * everything below unchanged.
+ */
+import type { WidgetAssetParameter, WidgetManifest, WidgetParameter } from "./manifest.js";
+/**
+ * Where a player reads media that lives on its own attached storage rather than
+ * in the workspace library. Matches the `source: "local"` video block, which is
+ * the only other thing that plays files off a stick.
+ */
+export declare const LOCAL_MEDIA_BASE_URL = "http://127.0.0.1:8000";
+/**
+ * An asset parameter as stored on a content block.
+ *
+ * Either a workspace library asset — where only `assetId` is persisted and
+ * `assetUrl` is filled in on the way to a screen, signed by the API and then
+ * rewritten to the device's local cache — or a file on the player's attached
+ * storage, named by a path relative to its media root.
+ */
+export type WidgetAssetValue = {
+    source?: "upload";
+    assetId: string;
+    assetUrl?: string;
+} | {
+    source: "local";
+    localFilePath: string;
+};
+export declare function isWidgetAssetValue(value: unknown): value is WidgetAssetValue;
+/** A parameter value as stored on a content block. */
+export type WidgetParameterValue = string | number | boolean | WidgetAssetValue;
+export type WidgetParameterValues = Record<string, WidgetParameterValue>;
+/**
+ * A parameter value as a widget receives it. Assets arrive as a URL the widget
+ * can put straight in an `<img>` or `fetch`, or `null` when none is chosen.
+ */
+export type ResolvedParameterValue = string | number | boolean | null;
+export type ResolvedParameterValues = Record<string, ResolvedParameterValue>;
+/**
+ * The value a parameter takes when the project has not set one, or `undefined`
+ * for an asset — there is nothing sensible to point at until someone picks a
+ * file, so the key is simply left off the block.
+ */
+export declare function defaultParameterValue(parameter: Exclude<WidgetParameter, WidgetAssetParameter>): Exclude<WidgetParameterValue, WidgetAssetValue>;
+export declare function defaultParameterValue(parameter: WidgetParameter): WidgetParameterValue | undefined;
+/**
+ * Reconciles the values stored on a content block against the manifest of the
+ * version that is about to run: fills in defaults, clamps out-of-range values
+ * and drops keys the manifest no longer declares.
+ *
+ * This is what makes promoting a widget version safe — a version that adds,
+ * removes or retypes a parameter can never hand a widget a value it did not
+ * declare, and never leaves a declared parameter undefined.
+ */
+export declare function resolveParameterValues(manifest: Pick<WidgetManifest, "parameters">, stored: Readonly<Partial<WidgetParameterValues>> | undefined): ResolvedParameterValues;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@kaptive/widget-api",
+  "version": "0.1.0",
+  "description": "Runtime SDK and manifest schema for Kaptive custom widgets.",
+  "keywords": [
+    "kaptive",
+    "widget",
+    "digital-signage"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "homepage": "https://kaptive.ch",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    },
+    "./bundle": {
+      "types": "./dist/bundle.d.ts",
+      "import": "./dist/bundle.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "^10.0.0",
+    "prettier": "^3.8.1",
+    "typescript": "6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "lint": "eslint . --max-warnings 0 --cache --cache-location node_modules/.cache/eslint/",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}