@nebulahome/package-sdk 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 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.6.0
+
+- **The background.** `ui.background: defineBackground({ component, description })` is a
+  component the interface draws on every page, out of sight, for as long as somebody is signed in
+  and the package runs - for what must outlive a page, sound playing in the browser above all. It
+  is unmounted when the package stops, is turned off or removed, and mounted afresh by an update,
+  so what it starts belongs in effects. Its `description` (1-256 characters) is shown on the
+  package's page; the manifest records it as `ui.background`.
+- **`<Floating open label onClose?>`** draws a window of the package over the interface's pages,
+  from its background, page or card: in a corner of the page beside the rail, thrown from corner to
+  corner with a small bounce, one a package, hidden on the package's own page and on a phone.
+  `onClose` gives it a close button and says what closing does.
+
+## 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,75 @@ 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`.
+
+## The background and floating windows
+
+A component drawn on every page for as long as somebody is signed in and the package runs, for
+what must outlive a page, and a window floating over the pages (since 1.6):
+
+```ts
+// nebula.config.ts
+ui: {
+  background: defineBackground({
+    component: () => import('./src/ui/background.js'),
+    description: 'Keeps music playing in this browser when you leave the Music page.',
+  }),
+}
+```
+
+```tsx
+// src/ui/background.tsx: every hook works here; start things in effects, the unmount stops them
+export default function Background() {
+  const { t } = useTranslation();
+
+  return (
+    <Floating open={isPlaying} label={t('mini.label', 'Now playing')}>
+      <MiniPlayer />
+    </Floating>
+  );
+}
+```
+
+The window rests in a corner of the page beside the rail and is thrown from corner to corner; it is
+hidden on the package's own page and on a phone. `onClose` gives it a close button.
+
 ## 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`, `defineBackground`, `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 background, a card and an entity view; `Floating`; 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.6.0";
 //#endregion
 //#region src/vite/catalogues.ts
 /**
@@ -12911,6 +12911,7 @@ function uiEntryCode(configPath, catalogues) {
 		"  kind: 'nebula.ui',",
 		`  sdk: ${JSON.stringify(SDK_VERSION)},`,
 		"  page: ui.page?.component,",
+		"  background: ui.background?.component,",
 		"  cards: ui.cards ?? {},",
 		"  entityViews: ui.entityViews ?? {},",
 		"  locales: {",

package/dist/chunks/node-config.js

@@ -6313,7 +6313,12 @@ const packageUiSchema = strictObject({
 	/** The cards it adds to the dashboard editor. */
 	cards: array(packageCardSchema).max(16).default([]),
 	/** Which of its entity types it draws itself, on an entity's page. */
-	entityViews: array(localIdSchema).max(16).default([])
+	entityViews: array(localIdSchema).max(16).default([]),
+	/**
+	* A component it draws on every page, for as long as somebody is signed in, and what it does in
+	* a sentence its page shows. Since package SDK 1.6.
+	*/
+	background: strictObject({ description: string().min(1).max(256) }).nullable().default(null)
 });
 /**
 * The words that appear more than once in a list.
@@ -6736,15 +6741,18 @@ function containersOf(containers, found) {
 * @param cardIds - The ids of the declared cards.
 * @param typeIds - The ids of the declared entity types.
 * @param found - Where problems go.
-* @returns Whether it has a page, its sidebar entry, and the types it draws.
+* @returns Whether it has a page, its sidebar entry, its background, and the types it draws.
 */
 function boundUi(ui, cardIds, typeIds, found) {
 	const bound = isRecord(ui) ? ui : {};
 	const page = bound["page"];
+	const background = bound["background"];
 	const cards = isRecord(bound["cards"]) ? bound["cards"] : {};
 	const views = isRecord(bound["entityViews"]) ? bound["entityViews"] : {};
 	if (page !== void 0 && (!isRecord(page) || page["kind"] !== "page")) found.add("ui.page", "must be a page, declared with definePage");
 	if (isRecord(page) && typeof page["component"] !== "function") found.add("ui.page.component", "must load the page's component: () => import('./page.js')");
+	if (background !== void 0 && (!isRecord(background) || background["kind"] !== "background")) found.add("ui.background", "must be a background, declared with defineBackground");
+	if (isRecord(background) && typeof background["component"] !== "function") found.add("ui.background.component", "must load the background's component: () => import('./background.js')");
 	for (const id of cardIds) if (typeof cards[id] !== "function") found.add(`ui.cards.${id}`, "the card has no component: () => import('./card.js')");
 	for (const id of Object.keys(cards).filter((each) => !cardIds.includes(each))) found.add(`ui.cards.${id}`, "is not one of the declared cards");
 	for (const [id, loader] of Object.entries(views)) if (!typeIds.includes(id)) found.add(`ui.entityViews.${id}`, "is not one of the declared entity types");
@@ -6753,8 +6761,9 @@ function boundUi(ui, cardIds, typeIds, found) {
 	return {
 		page: isRecord(page),
 		sidebar: isRecord(page) ? page["sidebar"] : void 0,
+		background: isRecord(background) ? { description: background["description"] } : null,
 		entityViews,
-		hasUi: isRecord(page) || cardIds.length > 0 || entityViews.length > 0
+		hasUi: isRecord(page) || isRecord(background) || cardIds.length > 0 || entityViews.length > 0
 	};
 }
 /**
@@ -6821,7 +6830,8 @@ function generatePackage(definition, options) {
 			page: ui.page,
 			...ui.sidebar === void 0 ? {} : { sidebar: ui.sidebar },
 			cards,
-			entityViews: ui.entityViews
+			entityViews: ui.entityViews,
+			...ui.background === null ? {} : { background: ui.background }
 		} } : {},
 		...settingFields.length > 0 ? { setup: releasePath(RELEASE_PATHS.setup) } : {},
 		containers,

package/dist/chunks/props.d.ts

@@ -43,6 +43,10 @@ type Loader<TProps> = () => Promise<PackageComponent<TProps> | {
 type PageProps = {
   readonly packageId: string;
 };
+/** What the package's background is given. Since 1.6. */
+type BackgroundProps = {
+  readonly packageId: string;
+};
 /** What a card is given. */
 type CardProps<TCard extends CardDefinition = CardDefinition> = {
   readonly packageId: string;
@@ -65,4 +69,4 @@ type EntityViewProps<TType extends EntityTypeDefinition = EntityTypeDefinition>
   readonly type: TType['id'];
 };
 //#endregion
-export { PageProps as a, CardSize as c, defineCard as d, PackageComponent as i, OptionsOf as l, EntityViewProps as n, CardDefinition as o, Loader as r, CardPadding as s, CardProps as t, SizeOf as u };
+export { PackageComponent as a, CardPadding as c, SizeOf as d, defineCard as f, Loader as i, CardSize as l, CardProps as n, PageProps as o, EntityViewProps as r, CardDefinition as s, BackgroundProps as t, OptionsOf as u };

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.6.0";
 //#endregion
 export { SDK_VERSION as t };

package/dist/index.d.ts

@@ -1,5 +1,22 @@
 import { $ as PlaybackState, A as SecretOptions, B as field, C as ListField, D as NumberOptions, E as NumberField, F as TextOptions, G as CapabilityState, H as CapabilityCommands, I as TimestampField, J as CustomValue, K as CapabilityStates, L as TimestampOptions, M as ShownWhen, N as Simplify, O as OptionField, P as TextField, Q as LawnMowerActivity, R as ValueField, S as FormValues, T as NoFields, U as CapabilityName, V as CapabilityCommand, W as CapabilityParams, X as EntityStateClass, Y as DeclaredCapabilities, Z as ImageContentType, _ as ChoiceOption, a as SettingsOf, at as VacuumActivity, b as Field, c as CommandDeclaration, ct as EntityDomain, d as EntityTypeDefinition, dt as isEntityId, et as ReportedCapabilityState, f as ValuesOf, ft as parseEntityId, g as ChoiceField, h as BooleanOptions, i as SettingsDefinition, it as ThermostatMode, j as SettingField, k as SecretField, l as CommandDeclarations, lt as EntityId, m as BooleanField, n as JsonPrimitive, nt as SelectOption, o as defineSettings, ot as VacuumRoom, p as defineEntityType, q as CommandableCapability, r as JsonValue, rt as ThermostatAction, s as ArgsOf, st as ENTITY_DOMAINS, t as JsonObject, tt as ReportedStates, u as CommandsOf, ut as ParsedEntityId, v as ChoiceOptions, w as ListOptions, x as Fields, y as EntityValues, z as ValueOfField } from "./chunks/json.js";
-import { a as PageProps, c as CardSize, d as defineCard, i as PackageComponent, l as OptionsOf, n as EntityViewProps, o as CardDefinition, r as Loader, s as CardPadding, t as CardProps, u as SizeOf } from "./chunks/props.js";
+import { a as PackageComponent, c as CardPadding, d as SizeOf, f as defineCard, i as Loader, l as CardSize, n as CardProps, o as PageProps, r as EntityViewProps, s as CardDefinition, t as BackgroundProps, u as OptionsOf } from "./chunks/props.js";
+//#region src/definitions/background.d.ts
+/** The package's background, as declared. */
+type BackgroundDefinition = {
+  readonly kind: 'background';
+  readonly component: Loader<BackgroundProps>;
+  /** What it does, in a sentence the package's page shows. At most 256 characters. */
+  readonly description: string;
+};
+/**
+ * Declares the package's background. A package has at most one: `ui.background` is a single
+ * field.
+ *
+ * @param background - Its component's loader, and what it does.
+ * @returns The background, for `definePackage`'s `ui.background`.
+ */
+export declare function defineBackground(background: Omit<BackgroundDefinition, 'kind'>): BackgroundDefinition;
+//#endregion
 //#region src/definitions/containers.d.ts
 /**
  * `defineContainer` and `defineCompose`: what a package runs beside or instead of its process
@@ -145,6 +162,8 @@ type PackageRequires = {
 type PackageUi<TCards extends readonly CardDefinition[], TTypes extends readonly EntityTypeDefinition[]> = {
   /** Its own page. */
   readonly page?: PageDefinition;
+  /** What it draws on every page, for as long as somebody is signed in. Since 1.6. */
+  readonly background?: BackgroundDefinition;
   /** A component for every declared card, by its id. */
   readonly cards?: { readonly [TId in TCards[number]['id']]: Loader<CardPropsFor<TCards, TId>>; };
   /** Views of the entity types it draws itself, by their ids. */
@@ -202,4 +221,4 @@ export declare function definePackage<const TCards extends readonly CardDefiniti
 /** The SDK's own version, `1.0.0`. */
 export declare const SDK_VERSION: string;
 //#endregion
-export { type ArgsOf, type BooleanField, type BooleanOptions, type CapabilityCommand, type CapabilityCommands, type CapabilityName, type CapabilityParams, type CapabilityState, type CapabilityStates, type CardDefinition, type CardPadding, type CardProps, type CardSize, type ChoiceField, type ChoiceOption, type ChoiceOptions, type CommandDeclaration, type CommandDeclarations, type CommandableCapability, type CommandsOf, type ComposeDefinition, type ContainerCondition, type ContainerDefinition, type ContainerPort, type CustomValue, type DeclaredCapabilities, ENTITY_DOMAINS, type EntityDomain, type EntityId, type EntityStateClass, type EntityTypeDefinition, type EntityValues, type EntityViewProps, type Field, type Fields, type FormValues, type ImageContentType, type JsonObject, type JsonPrimitive, type JsonValue, type LawnMowerActivity, type ListField, type ListOptions, type Loader, type NoFields, type NumberField, type NumberOptions, type OptionField, type OptionsOf, type PackageCategory, type PackageComponent, type PackageConfig, type PackageDefinition, type PackageRequires, type PackageUi, type PageDefinition, type PageProps, type ParsedEntityId, type PlaybackState, type ReportedCapabilityState, type ReportedStates, type SecretField, type SecretOptions, type SelectOption, type SettingField, type SettingPlaceholder, type SettingsDefinition, type SettingsOf, type ShownWhen, type SidebarEntry, type Simplify, type SizeOf, type TextField, type TextOptions, type ThermostatAction, type ThermostatMode, type TimestampField, type TimestampOptions, type VacuumActivity, type VacuumRoom, type ValueField, type ValueOfField, type ValuesOf, type When, defineCard, defineEntityType, defineSettings, field, isEntityId, parseEntityId };
+export { type ArgsOf, type BackgroundDefinition, type BackgroundProps, type BooleanField, type BooleanOptions, type CapabilityCommand, type CapabilityCommands, type CapabilityName, type CapabilityParams, type CapabilityState, type CapabilityStates, type CardDefinition, type CardPadding, type CardProps, type CardSize, type ChoiceField, type ChoiceOption, type ChoiceOptions, type CommandDeclaration, type CommandDeclarations, type CommandableCapability, type CommandsOf, type ComposeDefinition, type ContainerCondition, type ContainerDefinition, type ContainerPort, type CustomValue, type DeclaredCapabilities, ENTITY_DOMAINS, type EntityDomain, type EntityId, type EntityStateClass, type EntityTypeDefinition, type EntityValues, type EntityViewProps, type Field, type Fields, type FormValues, type ImageContentType, type JsonObject, type JsonPrimitive, type JsonValue, type LawnMowerActivity, type ListField, type ListOptions, type Loader, type NoFields, type NumberField, type NumberOptions, type OptionField, type OptionsOf, type PackageCategory, type PackageComponent, type PackageConfig, type PackageDefinition, type PackageRequires, type PackageUi, type PageDefinition, type PageProps, type ParsedEntityId, type PlaybackState, type ReportedCapabilityState, type ReportedStates, type SecretField, type SecretOptions, type SelectOption, type SettingField, type SettingPlaceholder, type SettingsDefinition, type SettingsOf, type ShownWhen, type SidebarEntry, type Simplify, type SizeOf, type TextField, type TextOptions, type ThermostatAction, type ThermostatMode, type TimestampField, type TimestampOptions, type VacuumActivity, type VacuumRoom, type ValueField, type ValueOfField, type ValuesOf, type When, defineCard, defineEntityType, defineSettings, field, isEntityId, parseEntityId };

package/dist/index.js

@@ -1,4 +1,20 @@
 import { t as SDK_VERSION } from "./chunks/version.js";
+//#region src/definitions/background.ts
+/**
+* Declares the package's background. A package has at most one: `ui.background` is a single
+* field.
+*
+* @param background - Its component's loader, and what it does.
+* @returns The background, for `definePackage`'s `ui.background`.
+*/
+/* @__NO_SIDE_EFFECTS__ */
+function defineBackground(background) {
+	return {
+		...background,
+		kind: "background"
+	};
+}
+//#endregion
 //#region src/definitions/card.ts
 /**
 * Declares a card.
@@ -240,4 +256,4 @@ const field = {
 	})
 };
 //#endregion
-export { ENTITY_DOMAINS, SDK_VERSION, defineCard, defineCompose, defineContainer, defineEntityType, definePackage, definePage, defineSettings, field, isEntityId, parseEntityId };
+export { ENTITY_DOMAINS, SDK_VERSION, defineBackground, defineCard, defineCompose, defineContainer, defineEntityType, definePackage, definePage, defineSettings, field, isEntityId, parseEntityId };

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

@@ -1,5 +1,5 @@
 import { G as CapabilityState, H as CapabilityCommands, S as FormValues, Y as DeclaredCapabilities, ct as EntityDomain, d as EntityTypeDefinition, f as ValuesOf, i as SettingsDefinition, lt as EntityId, q as CommandableCapability, r as JsonValue, s as ArgsOf, t as JsonObject, u as CommandsOf, z as ValueOfField } from "./chunks/json.js";
-import { a as PageProps, n as EntityViewProps, t as CardProps } from "./chunks/props.js";
+import { n as CardProps, o as PageProps, r as EntityViewProps, t as BackgroundProps } from "./chunks/props.js";
 import { a as TelemetryResolution, i as TelemetryPoint, n as HistorySeries, r as StateHistoryPoint, t as ChangeCause } from "./chunks/history.js";
 import { AnchorHTMLAttributes, ComponentType, ReactElement, ReactNode } from "react";
 //#region src/ui/types.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. */
@@ -298,6 +315,20 @@ type PlatformLinkProps = LinkAttributes & {
 type PageActionsProps = {
   readonly children?: ReactNode;
 };
+/**
+ * A window of the package floating over the interface's pages, in a corner of the page beside the
+ * rail: one a package, thrown from corner to corner, hidden on the package's own page and on a
+ * phone. Since 1.6.
+ */
+type FloatingProps = {
+  /** Whether it is shown. */
+  readonly open: boolean;
+  /** What a screen reader calls it, in the viewer's language. */
+  readonly label: string;
+  /** What closing it does; without it the window has no close button. */
+  readonly onClose?: () => void;
+  readonly children?: ReactNode;
+};
 /** What a toast says. Since 1.4. */
 type ToastMessage = {
   /** A few words, no full stop. */
@@ -360,6 +391,12 @@ 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;
+  /** Since 1.6. */
+  readonly Floating: ComponentType<FloatingProps>;
 };
 //#endregion
 //#region src/ui/index.d.ts
@@ -489,6 +526,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.
@@ -550,5 +604,15 @@ export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
  * @returns The actions.
  */
 export declare function PageActions(props: PageActionsProps): ReactElement;
+/**
+ * A window floating over the interface's pages, from the package's background, page or card -
+ * drawn while the component that draws it is, so a background's outlives every page. The
+ * interface gives the frame, the throwing from corner to corner and the close button; what is
+ * inside is the package's own. Since 1.6.
+ *
+ * @param props - Whether it is shown, what it is called, what closing it does, and what it holds.
+ * @returns The window.
+ */
+export declare function Floating(props: FloatingProps): 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, BackgroundProps, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, FloatingProps, 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.
 *
@@ -299,5 +320,17 @@ function PlatformLink(props) {
 function PageActions(props) {
 	return createElement(ui("PageActions", "1.3"), props);
 }
+/**
+* A window floating over the interface's pages, from the package's background, page or card -
+* drawn while the component that draws it is, so a background's outlives every page. The
+* interface gives the frame, the throwing from corner to corner and the close button; what is
+* inside is the package's own. Since 1.6.
+*
+* @param props - Whether it is shown, what it is called, what closing it does, and what it holds.
+* @returns The window.
+*/
+function Floating(props) {
+	return createElement(ui("Floating", "1.6"), 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 { Floating, 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.6.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -100,10 +100,10 @@
     "vitest": "^4.1.11",
     "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/tsconfig": "2026.10.0-alpha.32",
+    "@nebulahome/contracts": "2026.10.0-alpha.32",
+    "@nebulahome/eslint-config": "2026.10.0-alpha.32",
+    "@nebulahome/ui": "2026.10.0-alpha.32"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",