@nebulahome/package-sdk 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 The SDK's version is the version of the package API the platform implements: a minor version adds
 to it, a major one breaks it, and a patch leaves it as it is.
 
+## 1.5.0
+
+- **The live channel.** A package's server and its open interfaces talk over the interface's own
+  socket, both ways, with no polling and no HTTP rate limit. On the server
+  `ctx.live.publish(topic, data, { isRetained })` sends to every interface following the topic -
+  a retained message is handed at once to whoever follows it later - and
+  `ctx.live.onMessage(topic, { input }, handler)` hears what they send, with who sent it. In the
+  interface `usePackageLive(topic)` follows a topic (one subscription however many components
+  follow it) and `usePackageSend()` sends. Whoever may read packages may follow and send. Topics
+  are a letter, then letters, digits and `.`, `_`, `:`, `-`; a message is at most 1 MB from the
+  server, 64 KB from an interface, which sends at most 50 a second.
+- `createTestContext()` records what is published (`published`) and sends a message as the
+  interface would (`sendLive`).
+
 ## 1.4.0
 
 - **Toasts.** `useToast()` from `@nebulahome/package-sdk/ui` shows the interface's own toasts -

package/README.md

@@ -156,18 +156,44 @@ try {
 }
 ```
 
+## The live channel
+
+Messages between the server and its open interfaces over the interface's own socket, both ways,
+with no polling and no HTTP rate limit (since 1.5). Whoever may read packages follows and sends.
+
+```ts
+// on the server: what every page and card draws, kept for whoever opens one later
+ctx.live.publish('overview', overviewOf(), { isRetained: true });
+
+// and what the interface sends, with who sent it
+ctx.live.onMessage('player.report', { input: reportSchema }, (report, { caller }) => {
+  ctx.live.publish(`player.${report.playerId}`, orderFor(report));
+});
+```
+
+```tsx
+const { data, isConnected } = usePackageLive<Overview>('overview'); // one subscription per page
+const send = usePackageSend();
+
+send('player.report', { playerId, position });
+```
+
+A topic is a letter, then letters, digits and `.`, `_`, `:`, `-`; a message from the server is at
+most 1 MB as JSON, one from the interface 64 KB, and an interface sends at most 50 a second.
+Nothing answers a message: a call that wants an answer or an error stays `usePackageCall`.
+
 ## Entry points
 
-| Import                    | What                                                                                                                                                                                                                                            |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@nebulahome/package-sdk` | `definePackage`, `defineSettings`, `defineCard`, `defineEntityType`, `definePage`, `defineContainer`, `defineCompose`, `field`, entity id helpers, `SDK_VERSION`, the value types.                                                              |
-| `/server`                 | `defineServer`, and the context `start` is given: settings (live or restart), devices and entities, typed custom entities, the rest of the house and its past, methods for the interface, services between packages.                            |
-| `/ui`                     | The props of a page, a card and an entity view; hooks for the package, its methods, its settings, the house, its areas, its past and its pictures, the viewer, the theme, its strings; navigation inside the package's page and the platform's. |
-| `/sun`                    | Where the sun is at any moment, by the platform's own formulas.                                                                                                                                                                                 |
-| `/components`             | The part of the interface's design system a package may draw with.                                                                                                                                                                              |
-| `/vite`                   | `nebula()`, the Vite plugin that builds both halves: the interface in chunks with its CSS scoped to the package, the server bundled whole.                                                                                                      |
-| `/testing`                | `createTestContext()`: run `start` in a unit test, every effect recorded.                                                                                                                                                                       |
-| `/styles.css`             | The interface's Tailwind tokens, to `@reference`.                                                                                                                                                                                               |
+| Import                    | What                                                                                                                                                                                                                                                            |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nebulahome/package-sdk` | `definePackage`, `defineSettings`, `defineCard`, `defineEntityType`, `definePage`, `defineContainer`, `defineCompose`, `field`, entity id helpers, `SDK_VERSION`, the value types.                                                                              |
+| `/server`                 | `defineServer`, and the context `start` is given: settings (live or restart), devices and entities, typed custom entities, the rest of the house and its past, methods and the live channel for the interface, services between packages.                       |
+| `/ui`                     | The props of a page, a card and an entity view; hooks for the package, its methods and live topics, its settings, the house, its areas, its past and its pictures, the viewer, the theme, its strings; navigation inside the package's page and the platform's. |
+| `/sun`                    | Where the sun is at any moment, by the platform's own formulas.                                                                                                                                                                                                 |
+| `/components`             | The part of the interface's design system a package may draw with.                                                                                                                                                                                              |
+| `/vite`                   | `nebula()`, the Vite plugin that builds both halves: the interface in chunks with its CSS scoped to the package, the server bundled whole.                                                                                                                      |
+| `/testing`                | `createTestContext()`: run `start` in a unit test, every effect recorded.                                                                                                                                                                                       |
+| `/styles.css`             | The interface's Tailwind tokens, to `@reference`.                                                                                                                                                                                                               |
 
 The `nebulahome-package` command checks, builds and packs a package:
 

package/dist/chunks/context.d.ts

@@ -255,6 +255,25 @@ type RpcMethod = {
     readonly input: Schema<TInput>;
   }, handler: (input: TInput, call: RpcCall) => Awaitable<JsonValue | undefined>): void;
 };
+/** How a live message is sent. Since 1.5. */
+type LivePublishOptions = {
+  /**
+   * Kept by the platform, and handed at once to an interface that follows the topic later, until
+   * the next retained message on it replaces it: for the state a page draws. Off by default.
+   */
+  readonly isRetained?: boolean;
+};
+/** What a live message's handler is told besides the message: who sent it. Since 1.5. */
+type LiveCall = {
+  readonly caller: RpcCaller;
+};
+/** Hearing one topic of the package's interfaces' live messages. Since 1.5. */
+type LiveOnMessage = {
+  (topic: string, handler: (data: JsonValue, call: LiveCall) => Awaitable<void>): Unsubscribe;
+  <TInput>(topic: string, options: {
+    readonly input: Schema<TInput>;
+  }, handler: (data: TInput, call: LiveCall) => Awaitable<void>): Unsubscribe;
+};
 /** Offering a service. */
 type ServiceProvide = {
   (name: string, handler: (input: unknown, call: ServiceCall) => Awaitable<JsonValue | undefined>): void;
@@ -403,6 +422,23 @@ type ServerContext<TSettings = undefined> = {
     /** Registers a method its interface calls; a name registered twice throws. */
     readonly method: RpcMethod;
   };
+  /**
+   * The live channel to its open interfaces, over the interface's own socket: no polling, no
+   * HTTP rate limit. Whoever may read packages hears it and may send to it. Since 1.5.
+   */
+  readonly live: {
+    /**
+     * Sends a message to every open interface following the topic. A topic is a letter, then
+     * letters, digits and `.`, `_`, `:`, `-` (128 at most); a message is at most 1 MB as JSON.
+     * One that is not is logged, not sent.
+     */
+    readonly publish: (topic: string, data: JsonValue, options?: LivePublishOptions) => void;
+    /**
+     * Hears what its interfaces send on a topic (`usePackageSend`); a topic heard twice throws.
+     * A message its schema refuses is logged and dropped: nobody waits for an answer.
+     */
+    readonly onMessage: LiveOnMessage;
+  };
   readonly services: {
     /** Answers a service other packages call; a name provided twice, or reserved, throws. */
     readonly provide: ServiceProvide;
@@ -411,4 +447,4 @@ type ServerContext<TSettings = undefined> = {
   };
 };
 //#endregion
-export { Schema as A, ServiceProvide as C, TelemetryRead as D, SyncResult as E, StandardResult as M, StandardSchemaV1 as N, Unsubscribe as O, ServiceCallFunction as S, StateChange as T, RpcCaller as _, CustomEntityInput as a, ServerSettings as b, EntityInput as c, HistoryRead as d, LogMethod as f, RpcCall as g, RpcAccess as h, CustomEntities as i, SchemaIssue as j, SafeParser as k, EntitySnapshot as l, ReportOptions as m, CapabilityEntityInput as n, DeviceInput as o, Logger as p, CustomCommand as r, EntityFilter as s, Awaitable as t, HistoryAnswer as u, RpcMethod as v, SettingsChange as w, ServiceCall as x, ServerContext as y };
+export { TelemetryRead as A, ServerSettings as C, SettingsChange as D, ServiceProvide as E, StandardResult as F, StandardSchemaV1 as I, SafeParser as M, Schema as N, StateChange as O, SchemaIssue as P, ServerContext as S, ServiceCallFunction as T, ReportOptions as _, CustomEntityInput as a, RpcCaller as b, EntityInput as c, HistoryRead as d, LiveCall as f, Logger as g, LogMethod as h, CustomEntities as i, Unsubscribe as j, SyncResult as k, EntitySnapshot as l, LivePublishOptions as m, CapabilityEntityInput as n, DeviceInput as o, LiveOnMessage as p, CustomCommand as r, EntityFilter as s, Awaitable as t, HistoryAnswer as u, RpcAccess as v, ServiceCall as w, RpcMethod as x, RpcCall as y };

package/dist/chunks/node-build.js

@@ -6850,7 +6850,7 @@ function composeFileProblems(text, settingKeys) {
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.4.0";
+const SDK_VERSION = "1.5.0";
 //#endregion
 //#region src/vite/catalogues.ts
 /**

package/dist/chunks/version.js

@@ -7,6 +7,6 @@
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.4.0";
+const SDK_VERSION = "1.5.0";
 //#endregion
 export { SDK_VERSION as t };

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { i as SettingsDefinition } from "./chunks/json.js";
 import { a as TelemetryResolution, i as TelemetryPoint, n as HistorySeries, r as StateHistoryPoint, t as ChangeCause } from "./chunks/history.js";
-import { A as Schema, C as ServiceProvide, D as TelemetryRead, E as SyncResult, M as StandardResult, N as StandardSchemaV1, O as Unsubscribe, S as ServiceCallFunction, T as StateChange, _ as RpcCaller, a as CustomEntityInput, b as ServerSettings, c as EntityInput, d as HistoryRead, f as LogMethod, g as RpcCall, h as RpcAccess, i as CustomEntities, j as SchemaIssue, k as SafeParser, l as EntitySnapshot, m as ReportOptions, n as CapabilityEntityInput, o as DeviceInput, p as Logger, r as CustomCommand, s as EntityFilter, t as Awaitable, u as HistoryAnswer, v as RpcMethod, w as SettingsChange, x as ServiceCall, y as ServerContext } from "./chunks/context.js";
+import { A as TelemetryRead, C as ServerSettings, D as SettingsChange, E as ServiceProvide, F as StandardResult, I as StandardSchemaV1, M as SafeParser, N as Schema, O as StateChange, P as SchemaIssue, S as ServerContext, T as ServiceCallFunction, _ as ReportOptions, a as CustomEntityInput, b as RpcCaller, c as EntityInput, d as HistoryRead, f as LiveCall, g as Logger, h as LogMethod, i as CustomEntities, j as Unsubscribe, k as SyncResult, l as EntitySnapshot, m as LivePublishOptions, n as CapabilityEntityInput, o as DeviceInput, p as LiveOnMessage, r as CustomCommand, s as EntityFilter, t as Awaitable, u as HistoryAnswer, v as RpcAccess, w as ServiceCall, x as RpcMethod, y as RpcCall } from "./chunks/context.js";
 //#region src/server/index.d.ts
 /** What stops what `start` opened. */
 export type Stop = () => Awaitable<void>;
@@ -28,4 +28,4 @@ export type ServerDefinition<TSettings extends SettingsDefinition | undefined =
  */
 export declare function defineServer<TSettings extends SettingsDefinition | undefined = undefined>(server: Omit<ServerDefinition<TSettings>, 'kind' | 'sdk'>): ServerDefinition<TSettings>;
 //#endregion
-export type { Awaitable, CapabilityEntityInput, ChangeCause, CustomCommand, CustomEntities, CustomEntityInput, DeviceInput, EntityFilter, EntityInput, EntitySnapshot, HistoryAnswer, HistoryRead, HistorySeries, LogMethod, Logger, ReportOptions, RpcAccess, RpcCall, RpcCaller, RpcMethod, SafeParser, Schema, SchemaIssue, ServerContext, ServerSettings, ServiceCall, ServiceCallFunction, ServiceProvide, SettingsChange, StandardResult, StandardSchemaV1, StateChange, StateHistoryPoint, SyncResult, TelemetryPoint, TelemetryRead, TelemetryResolution, Unsubscribe };
+export type { Awaitable, CapabilityEntityInput, ChangeCause, CustomCommand, CustomEntities, CustomEntityInput, DeviceInput, EntityFilter, EntityInput, EntitySnapshot, HistoryAnswer, HistoryRead, HistorySeries, LiveCall, LiveOnMessage, LivePublishOptions, LogMethod, Logger, ReportOptions, RpcAccess, RpcCall, RpcCaller, RpcMethod, SafeParser, Schema, SchemaIssue, ServerContext, ServerSettings, ServiceCall, ServiceCallFunction, ServiceProvide, SettingsChange, StandardResult, StandardSchemaV1, StateChange, StateHistoryPoint, SyncResult, TelemetryPoint, TelemetryRead, TelemetryResolution, Unsubscribe };

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
 import { V as CapabilityCommand, et as ReportedCapabilityState, i as SettingsDefinition, lt as EntityId, r as JsonValue, t as JsonObject } from "./chunks/json.js";
 import { i as TelemetryPoint, r as StateHistoryPoint } from "./chunks/history.js";
-import { T as StateChange, _ as RpcCaller, l as EntitySnapshot, m as ReportOptions, o as DeviceInput, t as Awaitable, y as ServerContext } from "./chunks/context.js";
+import { O as StateChange, S as ServerContext, _ as ReportOptions, b as RpcCaller, l as EntitySnapshot, o as DeviceInput, t as Awaitable } from "./chunks/context.js";
 //#region src/testing/index.d.ts
 /** What a test context starts with. */
 export type TestContextOptions<TSettings extends SettingsDefinition | undefined> = {
@@ -30,6 +30,12 @@ export type RecordedReport = {
   readonly state: ReportedCapabilityState;
   readonly options?: ReportOptions;
 };
+/** One live message the package sent its interfaces. */
+export type RecordedLiveMessage = {
+  readonly topic: string;
+  readonly data: JsonValue;
+  readonly isRetained: boolean;
+};
 /** One line the package logged. */
 export type RecordedLog = {
   readonly level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
@@ -55,6 +61,17 @@ export type TestContext<TSettings extends SettingsDefinition | undefined> = {
   };
   /** Every line logged. */
   readonly logs: readonly RecordedLog[];
+  /** Every live message published and sent, in order. */
+  readonly published: readonly RecordedLiveMessage[];
+  /**
+   * Sends the package a live message as its interface would, through the topic's schema.
+   *
+   * @param topic - The topic.
+   * @param data - The message.
+   * @param caller - Who sends; a test user when not said.
+   * @returns Once handled; rejects when nothing hears the topic or its schema refuses it.
+   */
+  readonly sendLive: (topic: string, data: JsonValue, caller?: RpcCaller) => Promise<void>;
   /**
    * Routes a command as the platform would: to the entity type's handler for a custom one, to
    * `devices.onCommand` otherwise.

package/dist/testing.js

@@ -99,6 +99,9 @@ const TEST_CALLER = {
 	username: "test",
 	role: "owner"
 };
+/** A live topic, and the most a live message may carry as JSON, as the platform has them. */
+const LIVE_TOPIC_PATTERN = /^[a-z][a-zA-Z0-9._:-]{0,127}$/;
+const LIVE_MAX_BYTES = 1e6;
 /**
 * Says whether a value is a record.
 *
@@ -149,6 +152,8 @@ function createTestContext(options = {}) {
 	const methods = /* @__PURE__ */ new Map();
 	const services = /* @__PURE__ */ new Map();
 	const answers = /* @__PURE__ */ new Map();
+	const published = [];
+	const liveHandlers = /* @__PURE__ */ new Map();
 	const customHandlers = /* @__PURE__ */ new Map();
 	const settingsHandlers = /* @__PURE__ */ new Set();
 	const subscriptions = /* @__PURE__ */ new Set();
@@ -309,6 +314,68 @@ function createTestContext(options = {}) {
 		});
 	}
 	/**
+	* Hears a live topic.
+	*
+	* @param topic - The topic.
+	* @param optionsOrHandler - What a message takes, or what to do with one.
+	* @param handler - What to do with one, after its schema.
+	* @returns What stops it hearing.
+	* @throws {Error} When the topic is not one, is heard already, or there is no handler.
+	*/
+	function onLiveMessage(topic, optionsOrHandler, handler) {
+		/**
+		* Says whether a message is the topic's: its schema checked it, or it takes any.
+		*
+		* @param data - The message.
+		* @returns True.
+		*/
+		const isInput = (data) => data === data;
+		const hear = typeof optionsOrHandler === "function" ? optionsOrHandler : handler;
+		if (!LIVE_TOPIC_PATTERN.test(topic)) throw new Error(`${topic} is not a live topic: a letter first, then letters, digits, .:_-`);
+		if (liveHandlers.has(topic)) throw new Error(`The live topic ${topic} is heard already`);
+		if (hear === void 0) throw new Error(`The live topic ${topic} has no handler`);
+		liveHandlers.set(topic, {
+			input: typeof optionsOrHandler === "function" ? void 0 : optionsOrHandler.input,
+			/**
+			* Hands the handler the message, once checked.
+			*
+			* @param data - The message.
+			* @param call - Who sent it.
+			* @returns Once handled.
+			* @throws {Error} Never: every message is the topic's.
+			*/
+			handler: (data, call) => {
+				if (!isInput(data)) throw new Error(`${topic} was handed what it does not take`);
+				return hear(data, call);
+			}
+		});
+		return () => {
+			liveHandlers.delete(topic);
+		};
+	}
+	/**
+	* Publishes a live message, or logs why it cannot, as the platform does.
+	*
+	* @param topic - The topic.
+	* @param data - The message.
+	* @param options - Whether it is retained.
+	*/
+	const publishLive = (topic, data, options = {}) => {
+		if (!LIVE_TOPIC_PATTERN.test(topic)) {
+			ctx.logger.error({ topic }, "A live message was not sent: that is not a topic");
+			return;
+		}
+		if (new TextEncoder().encode(JSON.stringify(data)).length > LIVE_MAX_BYTES) {
+			ctx.logger.error({ topic }, "A live message was not sent: it is larger than 1 MB");
+			return;
+		}
+		published.push({
+			topic,
+			data,
+			isRetained: options.isRetained === true
+		});
+	};
+	/**
 	* Calls a service.
 	*
 	* @param target - The package or service.
@@ -329,215 +396,220 @@ function createTestContext(options = {}) {
 		if (!checked.isValid) throw new Error(`${target}.${name} answered what was not asked: ${checked.message}`);
 		return checked.value;
 	}
-	return {
-		ctx: {
-			id,
-			version: options.version ?? "0.0.0",
-			platform: { version: "0.0.0-test" },
-			sdk: { version: SDK_VERSION },
+	const ctx = {
+		id,
+		version: options.version ?? "0.0.0",
+		platform: { version: "0.0.0-test" },
+		sdk: { version: SDK_VERSION },
+		/**
+		* The settings as they stand.
+		*
+		* @returns Them.
+		*/
+		get settings() {
+			return settingsNow();
+		},
+		/**
+		* Hears live changes of the settings.
+		*
+		* @param handler - What hears them.
+		* @returns What stops it hearing.
+		*/
+		onSettingsChange: (handler) => {
+			settingsHandlers.add(handler);
+			return () => {
+				settingsHandlers.delete(handler);
+			};
+		},
+		dataDir: options.dataDir ?? `/tmp/${id}/data`,
+		cacheDir: options.cacheDir ?? `/tmp/${id}/cache`,
+		signal: abort.signal,
+		logger: loggerWith({}),
+		/**
+		* One of the package's entities' ids.
+		*
+		* @param domain - Its domain.
+		* @param objectId - What follows the prefix.
+		* @returns The id.
+		*/
+		entityId: (domain, objectId) => `${domain}.${prefix}${objectId}`,
+		objectIdOf,
+		devices: {
 			/**
-			* The settings as they stand.
+			* Records the devices, and answers as the platform would.
 			*
-			* @returns Them.
+			* @param devices - Every device.
+			* @returns What was written.
 			*/
-			get settings() {
-				return settingsNow();
+			sync: async (devices) => {
+				synced = devices;
+				return Promise.resolve({
+					devices: devices.map((device) => ({
+						deviceId: `device-${device.externalId}`,
+						externalId: device.externalId,
+						entityIds: device.entities.map((entity) => `${"type" in entity ? "custom" : entity.domain}.${prefix}${entity.objectId}`)
+					})),
+					refused: [],
+					kept: []
+				});
 			},
 			/**
-			* Hears live changes of the settings.
+			* Records a report.
 			*
-			* @param handler - What hears them.
-			* @returns What stops it hearing.
+			* @param entityId - The entity.
+			* @param state - Its state.
+			* @param reportOptions - Its attributes and availability.
+			*/
+			report: (entityId, state, reportOptions) => {
+				reports.push({
+					entityId,
+					state,
+					...reportOptions === void 0 ? {} : { options: reportOptions }
+				});
+			},
+			/**
+			* Takes the handler of commands.
+			*
+			* @param handler - The handler.
+			* @returns What removes it.
+			* @throws {Error} When there is one already.
 			*/
-			onSettingsChange: (handler) => {
-				settingsHandlers.add(handler);
+			onCommand: (handler) => {
+				if (commandHandler !== void 0) throw new Error("devices.onCommand has a handler already");
+				commandHandler = handler;
 				return () => {
-					settingsHandlers.delete(handler);
+					commandHandler = void 0;
 				};
-			},
-			dataDir: options.dataDir ?? `/tmp/${id}/data`,
-			cacheDir: options.cacheDir ?? `/tmp/${id}/cache`,
-			signal: abort.signal,
-			logger: loggerWith({}),
+			}
+		},
+		/**
+		* The entities of one of the package's entity types.
+		*
+		* @param type - The entity type.
+		* @returns Their ids, reports and commands.
+		*/
+		custom: (type) => ({
 			/**
-			* One of the package's entities' ids.
+			* The id of one of its entities of this type.
 			*
-			* @param domain - Its domain.
 			* @param objectId - What follows the prefix.
 			* @returns The id.
 			*/
-			entityId: (domain, objectId) => `${domain}.${prefix}${objectId}`,
-			objectIdOf,
-			devices: {
-				/**
-				* Records the devices, and answers as the platform would.
-				*
-				* @param devices - Every device.
-				* @returns What was written.
-				*/
-				sync: async (devices) => {
-					synced = devices;
-					return Promise.resolve({
-						devices: devices.map((device) => ({
-							deviceId: `device-${device.externalId}`,
-							externalId: device.externalId,
-							entityIds: device.entities.map((entity) => `${"type" in entity ? "custom" : entity.domain}.${prefix}${entity.objectId}`)
-						})),
-						refused: [],
-						kept: []
-					});
-				},
-				/**
-				* Records a report.
-				*
-				* @param entityId - The entity.
-				* @param state - Its state.
-				* @param reportOptions - Its attributes and availability.
-				*/
-				report: (entityId, state, reportOptions) => {
-					reports.push({
-						entityId,
-						state,
-						...reportOptions === void 0 ? {} : { options: reportOptions }
-					});
-				},
-				/**
-				* Takes the handler of commands.
-				*
-				* @param handler - The handler.
-				* @returns What removes it.
-				* @throws {Error} When there is one already.
-				*/
-				onCommand: (handler) => {
-					if (commandHandler !== void 0) throw new Error("devices.onCommand has a handler already");
-					commandHandler = handler;
-					return () => {
-						commandHandler = void 0;
-					};
-				}
-			},
+			entityId: (objectId) => `custom.${prefix}${objectId}`,
 			/**
-			* The entities of one of the package's entity types.
+			* Records a report of an entity's values.
 			*
-			* @param type - The entity type.
-			* @returns Their ids, reports and commands.
+			* @param entityId - The entity.
+			* @param entityValues - Its values.
+			* @param reportOptions - Its attributes and availability.
 			*/
-			custom: (type) => ({
-				/**
-				* The id of one of its entities of this type.
-				*
-				* @param objectId - What follows the prefix.
-				* @returns The id.
-				*/
-				entityId: (objectId) => `custom.${prefix}${objectId}`,
-				/**
-				* Records a report of an entity's values.
-				*
-				* @param entityId - The entity.
-				* @param entityValues - Its values.
-				* @param reportOptions - Its attributes and availability.
-				*/
-				report: (entityId, entityValues, reportOptions) => {
-					reports.push({
-						entityId,
-						state: { custom: { values: Object.fromEntries(Object.entries(entityValues).filter((entry) => isCustomValue(entry[1]))) } },
-						...reportOptions === void 0 ? {} : { options: reportOptions }
-					});
-				},
-				/**
-				* Takes the handler of one of the type's commands.
-				*
-				* @param command - The command's id.
-				* @param handler - The handler.
-				* @returns What removes it.
-				* @throws {Error} When the command has one already.
-				*/
-				onCommand: (command, handler) => {
-					const key = `${type.id}:${command}`;
-					/**
-					* Says whether a command's arguments are its own: the platform checked them against
-					* the entity type before routing it.
-					*
-					* @param args - The arguments.
-					* @returns True for a record.
-					*/
-					const isArgs = (args) => isRecord(args);
-					if (customHandlers.has(key)) throw new Error(`${type.id} has a handler for ${command} already`);
-					customHandlers.set(key, (call) => {
-						if (!isArgs(call.args)) throw new Error(`${command} was sent without arguments`);
-						return handler({
-							entityId: call.entityId,
-							objectId: call.objectId,
-							args: call.args
-						});
-					});
-					return () => {
-						customHandlers.delete(key);
-					};
-				}
-			}),
-			entities: {
-				/**
-				* One entity of the house.
-				*
-				* @param entityId - The entity.
-				* @returns It, or undefined.
-				*/
-				get: async (entityId) => Promise.resolve(entities.get(entityId)),
-				/**
-				* The entities a filter names.
-				*
-				* @param filter - Which.
-				* @returns Them.
-				*/
-				list: async (filter = {}) => Promise.resolve([...entities.values()].filter((each) => matches(filter, each.entityId))),
-				/**
-				* Hears changes of the entities a filter names.
-				*
-				* @param filter - Which.
-				* @param handler - What hears them.
-				* @returns What stops it hearing.
-				*/
-				subscribe: (filter, handler) => {
-					const subscription = {
-						filter,
-						handler
-					};
-					subscriptions.add(subscription);
-					return () => {
-						subscriptions.delete(subscription);
-					};
-				}
+			report: (entityId, entityValues, reportOptions) => {
+				reports.push({
+					entityId,
+					state: { custom: { values: Object.fromEntries(Object.entries(entityValues).filter((entry) => isCustomValue(entry[1]))) } },
+					...reportOptions === void 0 ? {} : { options: reportOptions }
+				});
 			},
-			history: {
-				/**
-				* The changes of some entities in a window.
-				*
-				* @param read - Which, when, how many.
-				* @returns Them, oldest first.
-				*/
-				states: async (read) => Promise.resolve(readWindow(read, (entityId) => histories.get(entityId)?.states ?? [])),
+			/**
+			* Takes the handler of one of the type's commands.
+			*
+			* @param command - The command's id.
+			* @param handler - The handler.
+			* @returns What removes it.
+			* @throws {Error} When the command has one already.
+			*/
+			onCommand: (command, handler) => {
+				const key = `${type.id}:${command}`;
 				/**
-				* The readings of some entities in a window, as given: a test gives the buckets it wants.
+				* Says whether a command's arguments are its own: the platform checked them against
+				* the entity type before routing it.
 				*
-				* @param read - Which, when, how many, at which resolution.
-				* @returns Them, oldest first, and the resolution.
+				* @param args - The arguments.
+				* @returns True for a record.
 				*/
-				telemetry: async (read) => {
-					const span = new Date(read.to).getTime() - new Date(read.from).getTime();
-					const resolution = read.resolution === void 0 || read.resolution === "auto" ? resolutionFor(span) : read.resolution;
-					return Promise.resolve({
-						...readWindow(read, (entityId) => histories.get(entityId)?.telemetry ?? []),
-						resolution
+				const isArgs = (args) => isRecord(args);
+				if (customHandlers.has(key)) throw new Error(`${type.id} has a handler for ${command} already`);
+				customHandlers.set(key, (call) => {
+					if (!isArgs(call.args)) throw new Error(`${command} was sent without arguments`);
+					return handler({
+						entityId: call.entityId,
+						objectId: call.objectId,
+						args: call.args
 					});
-				}
-			},
-			rpc: { method: rpcMethod },
-			services: {
-				provide,
-				call: callService
+				});
+				return () => {
+					customHandlers.delete(key);
+				};
 			}
+		}),
+		entities: {
+			/**
+			* One entity of the house.
+			*
+			* @param entityId - The entity.
+			* @returns It, or undefined.
+			*/
+			get: async (entityId) => Promise.resolve(entities.get(entityId)),
+			/**
+			* The entities a filter names.
+			*
+			* @param filter - Which.
+			* @returns Them.
+			*/
+			list: async (filter = {}) => Promise.resolve([...entities.values()].filter((each) => matches(filter, each.entityId))),
+			/**
+			* Hears changes of the entities a filter names.
+			*
+			* @param filter - Which.
+			* @param handler - What hears them.
+			* @returns What stops it hearing.
+			*/
+			subscribe: (filter, handler) => {
+				const subscription = {
+					filter,
+					handler
+				};
+				subscriptions.add(subscription);
+				return () => {
+					subscriptions.delete(subscription);
+				};
+			}
+		},
+		history: {
+			/**
+			* The changes of some entities in a window.
+			*
+			* @param read - Which, when, how many.
+			* @returns Them, oldest first.
+			*/
+			states: async (read) => Promise.resolve(readWindow(read, (entityId) => histories.get(entityId)?.states ?? [])),
+			/**
+			* The readings of some entities in a window, as given: a test gives the buckets it wants.
+			*
+			* @param read - Which, when, how many, at which resolution.
+			* @returns Them, oldest first, and the resolution.
+			*/
+			telemetry: async (read) => {
+				const span = new Date(read.to).getTime() - new Date(read.from).getTime();
+				const resolution = read.resolution === void 0 || read.resolution === "auto" ? resolutionFor(span) : read.resolution;
+				return Promise.resolve({
+					...readWindow(read, (entityId) => histories.get(entityId)?.telemetry ?? []),
+					resolution
+				});
+			}
+		},
+		rpc: { method: rpcMethod },
+		live: {
+			publish: publishLive,
+			onMessage: onLiveMessage
 		},
+		services: {
+			provide,
+			call: callService
+		}
+	};
+	return {
+		ctx,
 		/**
 		* The last list of devices.
 		*
@@ -555,6 +627,26 @@ function createTestContext(options = {}) {
 			last: (entityId) => reports.findLast((each) => each.entityId === entityId)?.state
 		},
 		logs,
+		published,
+		/**
+		* Sends the package a live message.
+		*
+		* @param topic - The topic.
+		* @param data - The message.
+		* @param caller - Who sends.
+		* @throws {Error} When nothing hears the topic, or its schema refuses the message.
+		*/
+		sendLive: async (topic, data, caller = TEST_CALLER) => {
+			const heard = liveHandlers.get(topic);
+			if (heard === void 0) throw new Error(`Nothing hears the live topic ${topic}`);
+			if (heard.input === void 0) {
+				await heard.handler(data, { caller });
+				return;
+			}
+			const checked = await check(heard.input, data);
+			if (!checked.isValid) throw new Error(`${topic} refused its message: ${checked.message}`);
+			await heard.handler(checked.value, { caller });
+		},
 		/**
 		* Routes a command.
 		*

package/dist/ui.d.ts

@@ -164,6 +164,23 @@ type RpcOptions = {
   /** False holds the read back. */
   readonly isEnabled?: boolean;
 };
+/** How a live topic is followed. Since 1.5. */
+type LiveOptions = {
+  /** False stops following it. */
+  readonly isEnabled?: boolean;
+};
+/** A live topic of the package's server, as it stands. Since 1.5. */
+type LiveState<TData> = {
+  /** The last message on it: the retained one at first, if there is one; undefined until then. */
+  readonly data: TData | undefined;
+  /** Whether the interface's socket is open: messages sent while it is not are lost. */
+  readonly isConnected: boolean;
+};
+/**
+ * Sends the package's server a message on a topic (`ctx.live.onMessage`), over the interface's
+ * socket; nothing answers it. Since 1.5.
+ */
+type PackageSend = (topic: string, data: JsonValue) => void;
 /** A call of one of the package's methods, on demand. */
 type PackageCall = <TData = JsonValue>(method: string, input?: JsonValue) => Promise<TData>;
 /** How a mutation is made. */
@@ -360,6 +377,10 @@ type UiHost = {
   readonly useAreaActions: () => AreaActions;
   /** Since 1.4. */
   readonly useToast: () => Toasts;
+  /** Since 1.5. */
+  readonly usePackageLive: <TData = JsonValue>(topic: string, options?: LiveOptions) => LiveState<TData>;
+  /** Since 1.5. */
+  readonly usePackageSend: () => PackageSend;
 };
 //#endregion
 //#region src/ui/index.d.ts
@@ -489,6 +510,23 @@ export declare function useAreaActions(): AreaActions;
  * @returns One function per kind: `success`, `warning`, `error`, `info`.
  */
 export declare function useToast(): Toasts;
+/**
+ * Follows a live topic of the package's server (`ctx.live.publish`), over the interface's own
+ * socket: the retained message at once, then every message as it is sent, with no polling and
+ * no HTTP rate limit. Every component following one topic shares one subscription. Since 1.5.
+ *
+ * @param topic - The topic.
+ * @param options - Whether to follow it.
+ * @returns The last message, and whether the socket is open.
+ */
+export declare function usePackageLive<TData = JsonValue>(topic: string, options?: LiveOptions): LiveState<TData>;
+/**
+ * Sends the package's server messages over the interface's socket (`ctx.live.onMessage`): for
+ * what goes often and wants no answer. A call that wants one stays `usePackageCall`. Since 1.5.
+ *
+ * @returns What sends one.
+ */
+export declare function usePackageSend(): PackageSend;
 /**
  * A camera's latest still, fetched again every so often, or an image entity's picture, fetched
  * again when it changes: an address an `<img>` shows, let go of when a newer one replaces it.
@@ -551,4 +589,4 @@ export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
  */
 export declare function PageActions(props: PageActionsProps): ReactElement;
 //#endregion
-export type { AreaActions, AreaDraft, AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageActionsProps, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, ToastMessage, Toasts, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };
+export type { AreaActions, AreaDraft, AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, LiveOptions, LiveState, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSend, PackageSettings, PageActionsProps, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, ToastMessage, Toasts, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -221,6 +221,27 @@ function useToast() {
 	return ui("useToast", "1.4")();
 }
 /**
+* Follows a live topic of the package's server (`ctx.live.publish`), over the interface's own
+* socket: the retained message at once, then every message as it is sent, with no polling and
+* no HTTP rate limit. Every component following one topic shares one subscription. Since 1.5.
+*
+* @param topic - The topic.
+* @param options - Whether to follow it.
+* @returns The last message, and whether the socket is open.
+*/
+function usePackageLive(topic, options) {
+	return ui("usePackageLive", "1.5")(topic, options);
+}
+/**
+* Sends the package's server messages over the interface's socket (`ctx.live.onMessage`): for
+* what goes often and wants no answer. A call that wants one stays `usePackageCall`. Since 1.5.
+*
+* @returns What sends one.
+*/
+function usePackageSend() {
+	return ui("usePackageSend", "1.5")();
+}
+/**
 * A camera's latest still, fetched again every so often, or an image entity's picture, fetched
 * again when it changes: an address an `<img>` shows, let go of when a newer one replaces it.
 *
@@ -300,4 +321,4 @@ function PageActions(props) {
 	return createElement(ui("PageActions", "1.3"), props);
 }
 //#endregion
-export { PackageLink, PageActions, PlatformLink, useAreaActions, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useToast, useTranslation, useViewer };
+export { PackageLink, PageActions, PlatformLink, useAreaActions, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageLive, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSend, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useToast, useTranslation, useViewer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -101,9 +101,9 @@
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
     "@nebulahome/contracts": "2026.10.0-alpha.23",
-    "@nebulahome/tsconfig": "2026.10.0-alpha.23",
     "@nebulahome/eslint-config": "2026.10.0-alpha.23",
-    "@nebulahome/ui": "2026.10.0-alpha.23"
+    "@nebulahome/ui": "2026.10.0-alpha.23",
+    "@nebulahome/tsconfig": "2026.10.0-alpha.23"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",