@nebulahome/package-sdk 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.2.0
+
+- **The past of the house.** `ctx.history.states()` and `ctx.history.telemetry()` on the server
+  read the recorded changes and the numeric readings of up to 64 entities over a window, with the
+  house's authority as `ctx.entities` has; `useStateHistory()` and `useTelemetry()` in
+  `@nebulahome/package-sdk/ui` read them with the viewer's, for a chart, an activity list or a
+  replay. Each entity's points come oldest first; a window that holds more than a read returns
+  loses its oldest points and names the entity in `truncated`. A window is two moments, or in the
+  interface the last so many milliseconds, which moves with each read; telemetry is read raw, or
+  in buckets of a minute, an hour or a day, `auto` picking by the window's length.
+  `createTestContext({ history })` and `test.setHistory()` give a unit test a past.
+- **The areas.** `useAreas()` lists the house, its floors (with their storey) and its rooms, each
+  naming its parent by key - the key `EntityView.areaId` holds - and the house its position.
+- **What an entity can do.** `EntityView.capabilities` holds the capabilities an entity declares,
+  with the device's limits: a cover's tilt, a thermostat's range and modes, a select's options.
+- **Pictures.** `useEntityPicture()` gives a camera's latest still, fetched again every so often,
+  or an image entity's picture, as an address an `<img>` shows.
+- **The sun.** `@nebulahome/package-sdk/sun`: `sunPosition`, `sunTimes`, `sunState` and
+  `sunPhaseLabel`, the platform's own formulas, for a moment the sun entities did not report.
+- A package's id may start with a digit (`3d-home`); its entities' object ids then do too.
+- **The MQTT broker is the platform's.** The hub runs the house's broker: `requires.services:
+["mqtt-broker"]` is always met, `{platform.mqtt.*}` and `NEBULA_PLATFORM_MQTT_*` name it, and a
+  package that `provides` `mqtt-broker` is refused at install.
+
 ## 1.1.0
 
 - `useTranslation()` in `@nebulahome/package-sdk/ui`: a package's page, cards and entity views

package/README.md

@@ -116,17 +116,42 @@ A string a catalogue lacks is said in English, and `nebulahome-package build` li
 `nebula.config.ts` declares (the package's name, its cards' and settings' names, its entity types)
 stays English: the platform shows it the same way to everyone.
 
+## The past, the areas and the sun
+
+```tsx
+// a sensor's chart: the last 6 hours, in minutes
+const day = useTelemetry({ entityIds: [entityId], window: { lastMs: 6 * 3_600_000 } });
+const points = day.series[entityId] ?? []; // oldest first: { time, value, min, max }
+
+// what a door did today, and the rooms of the house
+const today = useStateHistory({ entityIds: [door], window: { from: midnight, to: now } });
+const rooms = useAreas().filter((area) => area.kind === 'room');
+```
+
+```ts
+// on the server, with the house's authority
+const { series } = await ctx.history.states({ entityIds, from: yesterday, to: new Date() });
+```
+
+```ts
+// where the sun was, for a moment the sun entities did not report
+import { sunPosition } from '@nebulahome/package-sdk/sun';
+
+const { elevation, azimuth } = sunPosition(at, { latitude, longitude });
+```
+
 ## 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, 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, the viewer, the theme, its strings; navigation inside the package's page and the platform's. |
-| `/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 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`.                                                                                                                                                                                               |
 
 The `nebulahome-package` command checks, builds and packs a package:
 

package/dist/chunks/context.d.ts

@@ -1,4 +1,5 @@
 import { G as CapabilityState, V as CapabilityCommand, X as EntityStateClass, Y as DeclaredCapabilities, a as SettingsOf, ct as EntityDomain, d as EntityTypeDefinition, et as ReportedCapabilityState, f as ValuesOf, i as SettingsDefinition, lt as EntityId, r as JsonValue, s as ArgsOf, t as JsonObject, u as CommandsOf } from "./json.js";
+import { a as TelemetryResolution, i as TelemetryPoint, n as HistorySeries, r as StateHistoryPoint } from "./history.js";
 //#region src/schema.d.ts
 /**
  * What checks a value that crosses into a package - a method's input, a service's answer: any
@@ -163,6 +164,28 @@ type EntityFilter = {
   readonly domain?: EntityDomain;
   readonly entityIds?: readonly EntityId[];
 };
+/** Which entities' past `ctx.history` reads, over which window. Since 1.2. */
+type HistoryRead = {
+  /** At most 64. */
+  readonly entityIds: readonly EntityId[];
+  /** Inclusive: a `Date` or ISO 8601. */
+  readonly from: Date | string;
+  /** Exclusive. */
+  readonly to: Date | string;
+  /** The most points of one entity, at most 10 000 (the default): the newest are kept. */
+  readonly limit?: number;
+};
+/** Which entities' readings `ctx.history.telemetry` reads: `auto` picks by the window's length. */
+type TelemetryRead = HistoryRead & {
+  readonly resolution?: TelemetryResolution | 'auto';
+};
+/** What a read of the past found. */
+type HistoryAnswer<TPoint> = {
+  /** Each entity's points, oldest first. */
+  readonly series: HistorySeries<TPoint>;
+  /** The entities whose window held more than the limit: their oldest points are gone. */
+  readonly truncated: readonly EntityId[];
+};
 /** Who may call a method: whoever may read packages, or whoever may configure them. */
 type RpcAccess = 'read' | 'configure';
 /** Who called a method of the package's interface. */
@@ -354,6 +377,28 @@ type ServerContext<TSettings = undefined> = {
      */
     readonly subscribe: (filter: EntityFilter, handler: (change: StateChange) => Awaitable<void>) => Unsubscribe;
   };
+  /**
+   * The past of the house's entities, read only, with the house's authority as `entities` has.
+   * Since 1.2.
+   */
+  readonly history: {
+    /**
+     * The recorded changes of some entities over a window.
+     *
+     * @param read - Which entities, which window, how many points each at most.
+     * @returns Each entity's changes, oldest first.
+     */
+    readonly states: (read: HistoryRead) => Promise<HistoryAnswer<StateHistoryPoint>>;
+    /**
+     * The numeric readings of some entities over a window, raw or in buckets.
+     *
+     * @param read - Which entities, which window, which resolution.
+     * @returns Each entity's readings, oldest first, and the resolution read.
+     */
+    readonly telemetry: (read: TelemetryRead) => Promise<HistoryAnswer<TelemetryPoint> & {
+      readonly resolution: TelemetryResolution;
+    }>;
+  };
   readonly rpc: {
     /** Registers a method its interface calls; a name registered twice throws. */
     readonly method: RpcMethod;
@@ -366,4 +411,4 @@ type ServerContext<TSettings = undefined> = {
   };
 };
 //#endregion
-export { StandardSchemaV1 as A, StateChange as C, Schema as D, SafeParser as E, SchemaIssue as O, SettingsChange as S, Unsubscribe as T, ServerContext as _, CustomEntityInput as a, ServiceCallFunction as b, EntityInput as c, Logger as d, ReportOptions as f, RpcMethod as g, RpcCaller as h, CustomEntities as i, StandardResult as k, EntitySnapshot as l, RpcCall as m, CapabilityEntityInput as n, DeviceInput as o, RpcAccess as p, CustomCommand as r, EntityFilter as s, Awaitable as t, LogMethod as u, ServerSettings as v, SyncResult as w, ServiceProvide as x, ServiceCall as y };
+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 };

package/dist/chunks/history.d.ts

@@ -0,0 +1,39 @@
+import { G as CapabilityState, lt as EntityId, t as JsonObject } from "./json.js";
+//#region src/history.d.ts
+/** How finely readings are read: every one, or a bucket of a minute, an hour or a day. */
+type TelemetryResolution = 'raw' | '1m' | '1h' | '1d';
+/** What caused a change, when the platform knows it. */
+type ChangeCause = {
+  readonly type: 'automation' | 'scene' | 'user' | 'device' | 'alias' | 'startup';
+  /** Which run, scene or person; absent for a device and at startup. */
+  readonly id?: string;
+};
+/** One change of an entity's state. */
+type StateHistoryPoint = {
+  /** When it changed, ISO 8601. */
+  readonly time: string;
+  /** What it became. */
+  readonly state: CapabilityState;
+  /** What it was; null for the first report the platform recorded. */
+  readonly previousState: CapabilityState | null;
+  readonly attributes: JsonObject;
+  readonly isAvailable: boolean;
+  /** Which package, integration or engine reported it. */
+  readonly source: string;
+  readonly cause?: ChangeCause;
+};
+/** One reading, or one bucket of readings. */
+type TelemetryPoint = {
+  /** The reading's time, or the bucket's start, ISO 8601. */
+  readonly time: string;
+  /** The reading, or the bucket's average. */
+  readonly value: number;
+  /** A bucket's lowest, highest and how many readings it holds; absent for raw readings. */
+  readonly min?: number;
+  readonly max?: number;
+  readonly count?: number;
+};
+/** Each entity's points, oldest first: an entity never recorded, or not readable, has none. */
+type HistorySeries<TPoint> = Readonly<Record<EntityId, readonly TPoint[]>>;
+//#endregion
+export { TelemetryResolution as a, TelemetryPoint as i, HistorySeries as n, StateHistoryPoint as r, ChangeCause as t };

package/dist/chunks/json.d.ts

@@ -33,7 +33,7 @@ declare function isEntityId(value: unknown): value is EntityId;
 //#region src/capabilities.d.ts
 /** Every capability an entity may declare. */
 type CapabilityName = 'on_off' | 'level' | 'color_hs' | 'color_temp' | 'cover' | 'lock' | 'thermostat' | 'sensor_numeric' | 'sensor_binary' | 'sensor_text' | 'media_player' | 'camera' | 'button' | 'update' | 'lawn_mower' | 'select' | 'number' | 'vacuum' | 'image' | 'custom';
-/** How a sensor's readings add up: Home Assistant's state classes, for statistics. */
+/** How a sensor's readings add up, for statistics: a reading, a running total, or a meter. */
 type EntityStateClass = 'measurement' | 'total' | 'total_increasing';
 /** The modes a thermostat may be set to. */
 type ThermostatMode = 'off' | 'heat' | 'cool' | 'auto' | 'fan_only' | 'dry';

package/dist/chunks/node-build.js

@@ -1,5 +1,5 @@
 import { t as PackageConfigError } from "./node-problems.js";
-import { a as isRecord$1, b as strictObject, i as generatePackage, l as packageIdSchema, n as keepingNodeEnv, r as RELEASE_PATHS, u as DEPENDENCY_ID_PATTERN, x as string, y as record } from "./node-config.js";
+import { a as isRecord$1, b as strictObject, i as generatePackage, l as DEPENDENCY_ID_PATTERN, n as keepingNodeEnv, p as packageIdSchema, r as RELEASE_PATHS, x as string, y as record } from "./node-config.js";
 import { createRequire } from "node:module";
 import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -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.1.0";
+const SDK_VERSION = "1.2.0";
 //#endregion
 //#region src/vite/catalogues.ts
 /**

package/dist/chunks/node-config.js

@@ -5594,6 +5594,39 @@ function superRefine(fn, params) {
 function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
+//#endregion
+//#region ../contracts/dist/package-id.js
+/**
+* A package's identifier, apart from the manifest: the integrations' instance ids share its
+* pattern, and the modules that need only the pattern must not pull the manifest's whole grammar
+* - and what that imports - in with it.
+*/
+/**
+* A package identifier: `mqtt`, `nvr`, `3d-home`. It may start with a digit; its entities' object
+* ids then do too (`sensor.3d_home_kitchen_temperature`).
+*
+* Mirrors `packages_id_format` in DATABASE.md. It shares one namespace with the integrations'
+* instance ids, since both answer `svc.<id>.command`.
+*/
+const PACKAGE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+/** The reserved ids, for a quick look-up. */
+const RESERVED = /* @__PURE__ */ new Set([
+	"api",
+	"backup",
+	"core",
+	"derived",
+	"hub",
+	"logger",
+	"nebula",
+	"packet-manager",
+	"platform",
+	"proxy",
+	"supervisor",
+	"system",
+	"web-ui"
+]);
+/** Validates a package identifier. */
+const packageIdSchema = string().regex(PACKAGE_ID_PATTERN, "Must be a package id").refine((id) => !RESERVED.has(id), { message: "Is the name of a part of the platform, which no package may take" });
 /** Validates an icon identifier. */
 const iconIdSchema = string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "Must be an icon id");
 /**
@@ -6102,38 +6135,6 @@ const integrationSetupSchema = strictObject({
 	});
 });
 //#endregion
-//#region ../contracts/dist/package-id.js
-/**
-* A package's identifier, apart from the manifest: the integrations' instance ids share its
-* pattern, and the modules that need only the pattern must not pull the manifest's whole grammar
-* - and what that imports - in with it.
-*/
-/**
-* A package identifier: `mqtt`, `nvr`.
-*
-* Mirrors `packages_id_format` in DATABASE.md. It shares one namespace with the integrations'
-* instance ids, since both answer `svc.<id>.command`.
-*/
-const PACKAGE_ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
-/** The reserved ids, for a quick look-up. */
-const RESERVED = /* @__PURE__ */ new Set([
-	"api",
-	"backup",
-	"core",
-	"derived",
-	"hub",
-	"logger",
-	"nebula",
-	"packet-manager",
-	"platform",
-	"proxy",
-	"supervisor",
-	"system",
-	"web-ui"
-]);
-/** Validates a package identifier. */
-const packageIdSchema = string().regex(PACKAGE_ID_PATTERN, "Must be a package id").refine((id) => !RESERVED.has(id), { message: "Is the name of a part of the platform, which no package may take" });
-//#endregion
 //#region ../contracts/dist/package-requires.js
 /**
 * What a package - or a vendor, in its `manifest.json` - needs besides itself (PACKAGES.md 7).
@@ -6141,7 +6142,7 @@ const packageIdSchema = string().regex(PACKAGE_ID_PATTERN, "Must be a package id
 * Apart from the manifest so that the vendors' grammar can name it without pulling the package
 * manifest's whole grammar - and what that imports - in with it.
 */
-/** A service a package provides and others require: `mqtt-broker`, `object-detection`. */
+/** A service others require: `object-detection`, or `mqtt-broker`, which the platform runs. */
 const packageServiceNameSchema = string().regex(/^[a-z][a-z0-9-]{1,63}$/, "Must be a lower-case service name");
 /**
 * What a package - or a vendor, in its `manifest.json` - needs besides itself: the platform, by
@@ -6173,8 +6174,9 @@ const packageRequiresSchema = strictObject({
 * - **`ui`** is what it adds to the interface: a page of its own, cards for the dashboard, views
 *   for its own kinds of entity - one ES module, served same-origin and loaded on demand.
 * - **`requires`** and **`provides`** are its dependencies: packages by id and version range, and
-*   services by name - `mqtt-broker` - that whichever package provides them satisfies. A vendor's
-*   `manifest.json` writes `requires` the same way.
+*   services by name - `object-detection` - that whichever package provides them satisfies, or
+*   that the platform runs itself (`mqtt-broker`). A vendor's `manifest.json` writes `requires`
+*   the same way.
 * - **`entityTypes`** are kinds of entity no capability describes - a recording, a playlist - with
 *   the fields of their state and the commands they take; an entity of one has the `custom`
 *   capability, and the package's `entityViews` draw it.
@@ -6883,4 +6885,4 @@ async function keepingNodeEnv(run) {
 	}
 }
 //#endregion
-export { url as C, union as S, date as _, isRecord as a, strictObject as b, packageServiceNameSchema as c, semverRangeSchema as d, semverSchema as f, array as g, _enum as h, generatePackage as i, packageIdSchema as l, ZodISODateTime as m, keepingNodeEnv as n, PACKAGE_CATEGORIES as o, iconIdSchema as p, RELEASE_PATHS as r, packageRequiresSchema as s, githubEnvironment as t, DEPENDENCY_ID_PATTERN as u, int as v, _isoDateTime as w, string as x, record as y };
+export { url as C, union as S, date as _, isRecord as a, strictObject as b, packageServiceNameSchema as c, semverSchema as d, iconIdSchema as f, array as g, _enum as h, generatePackage as i, DEPENDENCY_ID_PATTERN as l, ZodISODateTime as m, keepingNodeEnv as n, PACKAGE_CATEGORIES as o, packageIdSchema as p, RELEASE_PATHS as r, packageRequiresSchema as s, githubEnvironment as t, semverRangeSchema as u, int as v, _isoDateTime as w, string as x, record as y };

package/dist/chunks/node-pack.js

@@ -1,5 +1,5 @@
 import { t as PackageConfigError } from "./node-problems.js";
-import { C as url, S as union, _ as date, a as isRecord, b as strictObject, c as packageServiceNameSchema, d as semverRangeSchema, f as semverSchema, g as array, h as _enum, l as packageIdSchema, m as ZodISODateTime, o as PACKAGE_CATEGORIES, p as iconIdSchema, r as RELEASE_PATHS, s as packageRequiresSchema, t as githubEnvironment, v as int, w as _isoDateTime, x as string } from "./node-config.js";
+import { C as url, S as union, _ as date, a as isRecord, b as strictObject, c as packageServiceNameSchema, d as semverSchema, f as iconIdSchema, g as array, h as _enum, m as ZodISODateTime, o as PACKAGE_CATEGORIES, p as packageIdSchema, r as RELEASE_PATHS, s as packageRequiresSchema, t as githubEnvironment, u as semverRangeSchema, v as int, w as _isoDateTime, x as string } from "./node-config.js";
 import ro, { readFile, readdir, writeFile } from "node:fs/promises";
 import path, { basename, join, posix, win32 } from "node:path";
 import { Buffer as Buffer$1 } from "buffer";

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.1.0";
+const SDK_VERSION = "1.2.0";
 //#endregion
 export { SDK_VERSION as t };

package/dist/index.d.ts

@@ -152,7 +152,7 @@ type PackageUi<TCards extends readonly CardDefinition[], TTypes extends readonly
 };
 /** What every package says, whatever it runs. */
 type PackageBase<TCards extends readonly CardDefinition[], TTypes extends readonly EntityTypeDefinition[]> = {
-  /** `^[a-z][a-z0-9-]{1,63}$`, not one of the platform's names. */
+  /** `^[a-z0-9][a-z0-9-]{1,63}$`, not one of the platform's names. */
   readonly id: string;
   readonly name: string;
   readonly description: string;

package/dist/index.js

@@ -130,7 +130,7 @@ const ENTITY_DOMAINS = [
 	"alias"
 ];
 /** The shape of an entity identifier: a domain, a dot, an object id. */
-const ENTITY_ID_PATTERN = /^([a-z][a-z0-9_]{0,31})\.([a-z][a-z0-9_]{0,63})$/;
+const ENTITY_ID_PATTERN = /^([a-z][a-z0-9_]{0,31})\.([a-z0-9][a-z0-9_]{0,63})$/;
 /**
 * Says whether a word is one of the platform's domains.
 *

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { i as SettingsDefinition } from "./chunks/json.js";
-import { A as StandardSchemaV1, C as StateChange, D as Schema, E as SafeParser, O as SchemaIssue, S as SettingsChange, T as Unsubscribe, _ as ServerContext, a as CustomEntityInput, b as ServiceCallFunction, c as EntityInput, d as Logger, f as ReportOptions, g as RpcMethod, h as RpcCaller, i as CustomEntities, k as StandardResult, l as EntitySnapshot, m as RpcCall, n as CapabilityEntityInput, o as DeviceInput, p as RpcAccess, r as CustomCommand, s as EntityFilter, t as Awaitable, u as LogMethod, v as ServerSettings, w as SyncResult, x as ServiceProvide, y as ServiceCall } from "./chunks/context.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";
 //#region src/server/index.d.ts
 /** What stops what `start` opened. */
 export type Stop = () => Awaitable<void>;
@@ -27,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, CustomCommand, CustomEntities, CustomEntityInput, DeviceInput, EntityFilter, EntityInput, EntitySnapshot, LogMethod, Logger, ReportOptions, RpcAccess, RpcCall, RpcCaller, RpcMethod, SafeParser, Schema, SchemaIssue, ServerContext, ServerSettings, ServiceCall, ServiceCallFunction, ServiceProvide, SettingsChange, StandardResult, StandardSchemaV1, StateChange, SyncResult, Unsubscribe };
+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 };

package/dist/styles.css

@@ -547,3 +547,15 @@
 @utility tabular {
   font-variant-numeric: tabular-nums;
 }
+
+/*
+ * The Matter mark's square, lit violet from its top-left corner: the broker's hero and its
+ * dialogs' lead. Over the square's own ground, so it sits on `bg-surface-raised`.
+ */
+@utility matter-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, var(--color-violet) 22%, transparent),
+    transparent 60%
+  );
+}

package/dist/sun.d.ts

@@ -0,0 +1,62 @@
+//#region src/sun.d.ts
+/** A place on Earth, in degrees: north and east positive. */
+export type GeoPosition = {
+  readonly latitude: number;
+  readonly longitude: number;
+};
+/** Where the sun stands, in degrees. */
+export type SunPosition = {
+  /** Above the horizon, positive; below it, negative. */
+  readonly elevation: number;
+  /** Clockwise from true north: 90 east, 180 south. */
+  readonly azimuth: number;
+};
+/** A day's sunrise, solar noon and sunset; no rise or set on a polar day or night. */
+export type SunTimes = {
+  readonly sunrise: Date | null;
+  readonly solarNoon: Date;
+  readonly sunset: Date | null;
+};
+/** Where the sun stands, and which way it goes. */
+export type SunState = SunPosition & {
+  readonly isRising: boolean;
+  readonly isMidnightSun: boolean;
+  readonly isPolarNight: boolean;
+};
+/** The light the sun gives, in a word. */
+export type SunPhaseLabel = 'day' | 'golden_hour' | 'blue_hour' | 'night' | 'polar_night';
+/** The platform's sun entities, reported every minute while the house has a position. */
+export declare const SUN_ELEVATION_ENTITY_ID = "sensor.system_sun_elevation";
+export declare const SUN_AZIMUTH_ENTITY_ID = "sensor.system_sun_azimuth";
+/**
+ * Where the sun stands at a moment, seen from a place.
+ *
+ * @param at - The moment.
+ * @param position - The place.
+ * @returns Its elevation and azimuth, in degrees.
+ */
+export declare function sunPosition(at: Date, position: GeoPosition): SunPosition;
+/**
+ * The sunrise, solar noon and sunset of the day a moment falls in, at a place.
+ *
+ * @param at - A moment of the day.
+ * @param position - The place.
+ * @returns Them; no rise or set on a polar day or night.
+ */
+export declare function sunTimes(at: Date, position: GeoPosition): SunTimes;
+/**
+ * Where the sun stands at a moment, and whether it rises.
+ *
+ * @param at - The moment.
+ * @param position - The place.
+ * @returns Its position, and how its day goes.
+ */
+export declare function sunState(at: Date, position: GeoPosition): SunState;
+/**
+ * The light of a moment, in a word: day, golden hour, blue hour, night.
+ *
+ * @param state - Where the sun stands.
+ * @returns The word.
+ */
+export declare function sunPhaseLabel(state: SunState): SunPhaseLabel;
+//#endregion

package/dist/sun.js

@@ -0,0 +1,328 @@
+//#region ../contracts/dist/sun.js
+/**
+* Where the sun is, and when it gets somewhere, worked out on this machine.
+*
+* The house knows its latitude and longitude and nothing else is needed: the sun's height and
+* bearing at any instant follow from the date with a few lines of spherical astronomy, so there is
+* no service to call and nothing leaves the house. The formulas are the ones the widely used
+* `suncalc` library takes from the astronomy pages of aa.quae.nl, good to about a minute for any
+* date this platform will see.
+*
+* Shared by `core`, which wakes automations on sun events and publishes the sun's elevation and
+* azimuth as two entities of the system device, and by the web interface, which previews the next
+* event under a block and today's sunrise and sunset in the first-run setup. One implementation,
+* so the preview never disagrees with what the engine does.
+*
+* Elevations are geometric (no refraction); the horizon events use the standard -0.833°, which
+* includes refraction and the sun's half-width, so "sunrise" here is the moment almanacs print.
+*/
+/** The elevations the named sun events are defined by, in degrees. */
+const SUN_ANGLES = {
+	/** Sunrise and sunset: the top of the disc on the horizon, refraction included. */
+	horizon: -.833,
+	/** Civil dawn and dusk. */
+	civil: -6,
+	/** Where the blue hour gives way to the golden hour. */
+	blueToGolden: -4,
+	/** The upper edge of the golden hour. */
+	goldenTop: 6
+};
+const RAD = Math.PI / 180;
+const DAY_MS = 864e5;
+const J1970 = 2440588;
+const J2000 = 2451545;
+const J0 = 9e-4;
+const OBLIQUITY = RAD * 23.4397;
+/** How finely a crossing is pinned down: well under a second. */
+const BISECTION_STEPS = 32;
+/**
+* Days since the J2000 epoch.
+*
+* @param ms - An instant, in Unix milliseconds.
+* @returns The day number.
+*/
+function toDays(ms) {
+	return ms / DAY_MS - .5 + J1970 - J2000;
+}
+/**
+* An instant from a Julian date.
+*
+* @param julian - The Julian date.
+* @returns Unix milliseconds.
+*/
+function fromJulian(julian) {
+	return (julian + .5 - J1970) * DAY_MS;
+}
+/**
+* The sun's mean anomaly.
+*
+* @param days - Days since J2000.
+* @returns Radians.
+*/
+function meanAnomaly(days) {
+	return RAD * (357.5291 + .98560028 * days);
+}
+/**
+* The sun's ecliptic longitude.
+*
+* @param anomaly - Its mean anomaly.
+* @returns Radians.
+*/
+function eclipticLongitude(anomaly) {
+	return anomaly + RAD * (1.9148 * Math.sin(anomaly) + .02 * Math.sin(2 * anomaly) + 3e-4 * Math.sin(3 * anomaly)) + RAD * 102.9372 + Math.PI;
+}
+/**
+* The sun's height and bearing at an instant, in radians, with the bearing from the south.
+*
+* @param ms - The instant.
+* @param position - Where.
+* @returns Altitude and azimuth.
+*/
+function horizontal(ms, position) {
+	const lw = RAD * -position.longitude;
+	const phi = RAD * position.latitude;
+	const days = toDays(ms);
+	const longitude = eclipticLongitude(meanAnomaly(days));
+	const declination = Math.asin(Math.sin(OBLIQUITY) * Math.sin(longitude));
+	const ascension = Math.atan2(Math.sin(longitude) * Math.cos(OBLIQUITY), Math.cos(longitude));
+	const hourAngle = RAD * (280.16 + 360.9856235 * days) - lw - ascension;
+	return {
+		altitude: Math.asin(Math.sin(phi) * Math.sin(declination) + Math.cos(phi) * Math.cos(declination) * Math.cos(hourAngle)),
+		azimuth: Math.atan2(Math.sin(hourAngle), Math.cos(hourAngle) * Math.sin(phi) - Math.tan(declination) * Math.cos(phi))
+	};
+}
+/**
+* The sun's elevation at an instant.
+*
+* @param ms - The instant.
+* @param position - Where.
+* @returns Degrees above the horizon.
+*/
+function elevationAt(ms, position) {
+	return horizontal(ms, position).altitude / RAD;
+}
+/**
+* Where the sun stands at an instant.
+*
+* @param at - The instant.
+* @param position - Where.
+* @returns Its elevation and its azimuth from north, in degrees.
+*/
+function sunPosition$1(at, position) {
+	const { altitude, azimuth } = horizontal(at.getTime(), position);
+	const fromNorth = (azimuth / RAD + 180) % 360;
+	return {
+		elevation: altitude / RAD,
+		azimuth: fromNorth < 0 ? fromNorth + 360 : fromNorth
+	};
+}
+/**
+* Which solar day an instant falls in: the cycle whose noon is nearest.
+*
+* @param ms - The instant.
+* @param position - Where.
+* @returns The cycle number.
+*/
+function cycleOf(ms, position) {
+	const lw = RAD * -position.longitude;
+	return Math.round(toDays(ms) - J0 - lw / (2 * Math.PI));
+}
+/**
+* When the sun is highest in one solar day.
+*
+* @param cycle - The solar day.
+* @param position - Where.
+* @returns Unix milliseconds.
+*/
+function noonOf(cycle, position) {
+	const lw = RAD * -position.longitude;
+	const days = J0 + lw / (2 * Math.PI) + cycle;
+	const anomaly = meanAnomaly(days);
+	const longitude = eclipticLongitude(anomaly);
+	return fromJulian(J2000 + days + .0053 * Math.sin(anomaly) - .0069 * Math.sin(2 * longitude));
+}
+/**
+* Finds where the elevation reaches an angle between two instants it lies on either side of.
+*
+* @param from - One end.
+* @param to - The other end.
+* @param angle - The elevation sought.
+* @param position - Where.
+* @returns The instant, in Unix milliseconds.
+*/
+function bisect(from, to, angle, position) {
+	let low = from;
+	let high = to;
+	const isLowBelow = elevationAt(low, position) < angle;
+	for (let step = 0; step < BISECTION_STEPS; step += 1) {
+		const middle = (low + high) / 2;
+		if (elevationAt(middle, position) < angle === isLowBelow) low = middle;
+		else high = middle;
+	}
+	return Math.round((low + high) / 2);
+}
+/**
+* Reads one solar day.
+*
+* @param cycle - Which.
+* @param position - Where.
+* @returns Its noon and midnights.
+*/
+function solarDay(cycle, position) {
+	const noon = noonOf(cycle, position);
+	const midnightBefore = noon - DAY_MS / 2;
+	const midnightAfter = noon + DAY_MS / 2;
+	return {
+		noon,
+		midnightBefore,
+		midnightAfter,
+		noonElevation: elevationAt(noon, position),
+		beforeElevation: elevationAt(midnightBefore, position),
+		afterElevation: elevationAt(midnightAfter, position)
+	};
+}
+/**
+* When the sun rises through an angle in one solar day.
+*
+* @param day - The day.
+* @param angle - The elevation.
+* @param position - Where.
+* @returns The instant, or null when it does not cross that day.
+*/
+function risingThrough(day, angle, position) {
+	return day.beforeElevation < angle && day.noonElevation >= angle ? bisect(day.midnightBefore, day.noon, angle, position) : null;
+}
+/**
+* When the sun sets through an angle in one solar day.
+*
+* @param day - The day.
+* @param angle - The elevation.
+* @param position - Where.
+* @returns The instant, or null when it does not cross that day.
+*/
+function settingThrough(day, angle, position) {
+	return day.noonElevation >= angle && day.afterElevation < angle ? bisect(day.noon, day.midnightAfter, angle, position) : null;
+}
+/**
+* The sunrise, noon and sunset of the solar day an instant falls in.
+*
+* @param at - Any instant of the day.
+* @param position - Where.
+* @returns The three moments; sunrise or sunset is null on a day the sun does not cross the
+*   horizon.
+*/
+function sunTimes$1(at, position) {
+	const day = solarDay(cycleOf(at.getTime(), position), position);
+	const sunrise = risingThrough(day, SUN_ANGLES.horizon, position);
+	const sunset = settingThrough(day, SUN_ANGLES.horizon, position);
+	return {
+		sunrise: sunrise === null ? null : new Date(sunrise),
+		solarNoon: new Date(day.noon),
+		sunset: sunset === null ? null : new Date(sunset)
+	};
+}
+/**
+* What the sun is doing at an instant.
+*
+* @param at - The instant.
+* @param position - Where.
+* @returns Its position, whether it is rising, and whether today is a polar day or night.
+*/
+function sunState$1(at, position) {
+	const ms = at.getTime();
+	const day = solarDay(cycleOf(ms, position), position);
+	const { horizon } = SUN_ANGLES;
+	return {
+		...sunPosition$1(at, position),
+		isRising: ms < day.noon,
+		isMidnightSun: Math.min(day.beforeElevation, day.afterElevation) >= horizon,
+		isPolarNight: day.noonElevation < horizon
+	};
+}
+/**
+* The one word for what the sun is doing, for the sun entity's attributes.
+*
+* @param state - What the sun is doing.
+* @returns Day, golden hour, blue hour, night or polar night.
+*/
+function sunPhaseLabel$1(state) {
+	const { civil, blueToGolden, goldenTop } = SUN_ANGLES;
+	if (state.isPolarNight) return "polar_night";
+	if (state.elevation >= goldenTop) return "day";
+	if (state.elevation > blueToGolden) return "golden_hour";
+	return state.elevation > civil ? "blue_hour" : "night";
+}
+[{
+	reading: "elevation",
+	entityId: "sensor.system_sun_elevation",
+	name: "Sun elevation",
+	icon: "sun",
+	unitOfMeasurement: "°",
+	stateClass: "measurement",
+	displayPrecision: 1,
+	capabilities: { sensor_numeric: {} }
+}, {
+	reading: "azimuth",
+	entityId: "sensor.system_sun_azimuth",
+	name: "Sun azimuth",
+	icon: "compass",
+	unitOfMeasurement: "°",
+	stateClass: "measurement",
+	displayPrecision: 1,
+	capabilities: { sensor_numeric: {} }
+}].map((entity) => entity.entityId);
+//#endregion
+//#region src/sun.ts
+/**
+* `@nebulahome/package-sdk/sun`: where the sun is, for a package that draws or decides by it
+* (PACKAGES_DOCS.md 6.7). Since 1.2.
+*
+* The same formulas the platform runs for its sun entities and its sun triggers, so a package that
+* works out a past or a future day agrees with what the house said live: `sensor.system_sun_*`
+* for now, these for any other moment. The house's position is the house area's
+* (`useAreas()` on the interface).
+*/
+/** The platform's sun entities, reported every minute while the house has a position. */
+const SUN_ELEVATION_ENTITY_ID = "sensor.system_sun_elevation";
+const SUN_AZIMUTH_ENTITY_ID = "sensor.system_sun_azimuth";
+/**
+* Where the sun stands at a moment, seen from a place.
+*
+* @param at - The moment.
+* @param position - The place.
+* @returns Its elevation and azimuth, in degrees.
+*/
+function sunPosition(at, position) {
+	return sunPosition$1(at, position);
+}
+/**
+* The sunrise, solar noon and sunset of the day a moment falls in, at a place.
+*
+* @param at - A moment of the day.
+* @param position - The place.
+* @returns Them; no rise or set on a polar day or night.
+*/
+function sunTimes(at, position) {
+	return sunTimes$1(at, position);
+}
+/**
+* Where the sun stands at a moment, and whether it rises.
+*
+* @param at - The moment.
+* @param position - The place.
+* @returns Its position, and how its day goes.
+*/
+function sunState(at, position) {
+	return sunState$1(at, position);
+}
+/**
+* The light of a moment, in a word: day, golden hour, blue hour, night.
+*
+* @param state - Where the sun stands.
+* @returns The word.
+*/
+function sunPhaseLabel(state) {
+	return sunPhaseLabel$1(state);
+}
+//#endregion
+export { SUN_AZIMUTH_ENTITY_ID, SUN_ELEVATION_ENTITY_ID, sunPhaseLabel, sunPosition, sunState, sunTimes };

package/dist/testing.d.ts

@@ -1,5 +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 { C as StateChange, _ as ServerContext, f as ReportOptions, h as RpcCaller, l as EntitySnapshot, o as DeviceInput, t as Awaitable } from "./chunks/context.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";
 //#region src/testing/index.d.ts
 /** What a test context starts with. */
 export type TestContextOptions<TSettings extends SettingsDefinition | undefined> = {
@@ -13,9 +14,16 @@ export type TestContextOptions<TSettings extends SettingsDefinition | undefined>
   readonly settings?: JsonObject;
   /** Entities of the house `ctx.entities` reads. */
   readonly entities?: readonly EntitySnapshot[];
+  /** The past `ctx.history` reads, by entity: points in any order. */
+  readonly history?: Readonly<Record<string, RecordedHistory>>;
   readonly dataDir?: string;
   readonly cacheDir?: string;
 };
+/** One entity's past, as a test gives it. */
+export type RecordedHistory = {
+  readonly states?: readonly StateHistoryPoint[];
+  readonly telemetry?: readonly TelemetryPoint[];
+};
 /** One report the package made. */
 export type RecordedReport = {
   readonly entityId: EntityId;
@@ -96,6 +104,13 @@ export type TestContext<TSettings extends SettingsDefinition | undefined> = {
    * @returns Once every handler ran.
    */
   readonly emitStateChange: (change: StateChange) => Promise<void>;
+  /**
+   * Gives an entity a past, where `ctx.history` reads it.
+   *
+   * @param entityId - The entity.
+   * @param history - Its changes and readings, in any order.
+   */
+  readonly setHistory: (entityId: EntityId, history: RecordedHistory) => void;
   /**
    * Answers a service the package calls.
    *

package/dist/testing.js

@@ -38,6 +38,52 @@ async function check(schema, value) {
 }
 //#endregion
 //#region src/testing/index.ts
+/** The most entities and points one read of the past takes, as the platform has it. */
+const HISTORY_MAX_ENTITIES = 64;
+const HISTORY_MAX_POINTS = 1e4;
+/** An hour and a day, in milliseconds. */
+const HOUR_MS = 36e5;
+const DAY_MS = 24 * HOUR_MS;
+/**
+* The resolution the platform reads a window at when a read leaves it to it.
+*
+* @param spanMs - How long the window is.
+* @returns Raw up to an hour, minutes up to 30 hours, hours up to 80 days, days beyond.
+*/
+function resolutionFor(spanMs) {
+	if (spanMs <= HOUR_MS) return "raw";
+	if (spanMs <= 30 * HOUR_MS) return "1m";
+	return spanMs <= 80 * DAY_MS ? "1h" : "1d";
+}
+/**
+* Reads a window of points as the platform does: checked, oldest first, the newest kept.
+*
+* @param read - Which entities, which window, how many points each.
+* @param pointsOf - An entity's points, in any order.
+* @returns Each entity's points in the window, and which lost their oldest.
+* @throws {Error} When the read names no entity or too many, or its window is backwards.
+*/
+function readWindow(read, pointsOf) {
+	const from = new Date(read.from).getTime();
+	const to = new Date(read.to).getTime();
+	const limit = read.limit ?? HISTORY_MAX_POINTS;
+	if (read.entityIds.length === 0 || read.entityIds.length > HISTORY_MAX_ENTITIES) throw new Error(`A read of the past names 1 to ${String(HISTORY_MAX_ENTITIES)} entities`);
+	if (!(from < to)) throw new Error("The window starts at or after it ends");
+	const series = {};
+	const truncated = [];
+	for (const entityId of read.entityIds) {
+		const inWindow = pointsOf(entityId).filter((point) => {
+			const time = new Date(point.time).getTime();
+			return time >= from && time < to;
+		}).toSorted((a, b) => new Date(a.time).getTime() - new Date(b.time).getTime());
+		series[entityId] = inWindow.slice(Math.max(0, inWindow.length - limit));
+		if (inWindow.length > limit) truncated.push(entityId);
+	}
+	return {
+		series,
+		truncated
+	};
+}
 /** Service names the platform keeps for itself. */
 const RESERVED_SERVICES = /* @__PURE__ */ new Set([
 	"command",
@@ -99,6 +145,7 @@ function createTestContext(options = {}) {
 	const reports = [];
 	const logs = [];
 	const entities = new Map((options.entities ?? []).map((each) => [each.entityId, each]));
+	const histories = new Map(Object.entries(options.history ?? {}));
 	const methods = /* @__PURE__ */ new Map();
 	const services = /* @__PURE__ */ new Map();
 	const answers = /* @__PURE__ */ new Map();
@@ -462,6 +509,29 @@ function createTestContext(options = {}) {
 					};
 				}
 			},
+			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 },
 			services: {
 				provide,
@@ -578,6 +648,15 @@ function createTestContext(options = {}) {
 			entities.set(snapshot.entityId, snapshot);
 		},
 		/**
+		* Gives an entity a past.
+		*
+		* @param entityId - The entity.
+		* @param history - Its changes and readings.
+		*/
+		setHistory: (entityId, history) => {
+			histories.set(entityId, history);
+		},
+		/**
 		* Changes an entity of the house.
 		*
 		* @param change - The change.

package/dist/ui.d.ts

@@ -1,5 +1,6 @@
-import { G as CapabilityState, H as CapabilityCommands, S as FormValues, 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 { 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 { 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
 /** The package drawn. */
@@ -15,7 +16,13 @@ type EntityView = {
   readonly name: string;
   readonly icon: string | null;
   readonly deviceId: string | null;
+  /** Its area's key - the entity's own, else its device's - as {@link AreaView} `key` says it. */
   readonly areaId: string | null;
+  /**
+   * What it declares it can do, with the device's limits: a cover's tilt, a thermostat's range
+   * and modes, a select's options. Since 1.2.
+   */
+  readonly capabilities: DeclaredCapabilities;
   readonly state: CapabilityState;
   readonly attributes: JsonObject;
   readonly isAvailable: boolean;
@@ -24,6 +31,79 @@ type EntityView = {
   readonly deviceClass: string | null;
   readonly displayPrecision: number | null;
 };
+/** A window of the past: between two moments (ISO 8601), or the last so many milliseconds. */
+type HistoryWindow = {
+  readonly from: string;
+  readonly to: string;
+} | {
+  readonly lastMs: number;
+};
+/** Which entities' past `useStateHistory` reads, over which window. Since 1.2. */
+type HistoryQuery = {
+  /** At most 64. */
+  readonly entityIds: readonly EntityId[];
+  readonly window: HistoryWindow;
+  /** False holds the read back. */
+  readonly isEnabled?: boolean;
+  /** Reads it again every so often; a window of the last so many milliseconds moves with it. */
+  readonly refetchIntervalMs?: number;
+};
+/** Which entities' readings `useTelemetry` reads: `auto` picks the resolution by the window. */
+type TelemetryQuery = HistoryQuery & {
+  readonly resolution?: TelemetryResolution | 'auto';
+};
+/** A read of the past, as it stands. */
+type History<TPoint> = {
+  /** Each entity's points, oldest first; empty while it loads. */
+  readonly series: HistorySeries<TPoint>;
+  /** The window read, in milliseconds since the epoch; undefined before the first answer. */
+  readonly window: {
+    readonly from: number;
+    readonly to: number;
+  } | undefined;
+  /** The entities whose window held more than one read returns: their oldest points are gone. */
+  readonly truncated: readonly EntityId[];
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  /** Reads it again. */
+  readonly refetch: () => void;
+};
+/** A read of readings, and the resolution it was read at. */
+type Telemetry = History<TelemetryPoint> & {
+  readonly resolution: TelemetryResolution;
+};
+/** What kind of place an area is. */
+type AreaKind = 'house' | 'floor' | 'room';
+/** One area of the house: the house itself, a floor, a room. Since 1.2. */
+type AreaView = {
+  /** What `EntityView.areaId` names it by. */
+  readonly key: string;
+  readonly name: string;
+  readonly kind: AreaKind;
+  /** The floor a room is on, the house a floor is in; null for the house. */
+  readonly parentKey: string | null;
+  readonly icon: string | null;
+  readonly sortOrder: number;
+  /** A floor's storey: 0 the ground floor, -1 the one below; null for the rest. */
+  readonly level: number | null;
+  /** The house's position, when the owner has set it; null for the rest. */
+  readonly latitude: number | null;
+  readonly longitude: number | null;
+};
+/** How a picture is fetched. */
+type PictureOptions = {
+  /** A camera's still is fetched again this often; 15 seconds when not said, at least 2. */
+  readonly refreshMs?: number;
+  /** False holds it back. */
+  readonly isEnabled?: boolean;
+};
+/** A camera's latest still, or an image entity's picture, as an address an `<img>` shows. */
+type EntityPicture = {
+  /** Null before there is one, or when the entity has none. */
+  readonly url: string | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+};
 /** Which entities `useEntities` reads. */
 type EntitiesFilter = {
   /** Whose: the package's own (the default), anyone's, or another package's by id. */
@@ -208,6 +288,14 @@ type UiHost = {
   readonly useLocale: () => Locale;
   /** Since 1.1. */
   readonly useTranslation: () => Translation;
+  /** Since 1.2. */
+  readonly useStateHistory: (query: HistoryQuery) => History<StateHistoryPoint>;
+  /** Since 1.2. */
+  readonly useTelemetry: (query: TelemetryQuery) => Telemetry;
+  /** Since 1.2. */
+  readonly useAreas: () => readonly AreaView[];
+  /** Since 1.2. */
+  readonly useEntityPicture: (entityId: EntityId, options?: PictureOptions) => EntityPicture;
   readonly useTheme: () => Theme;
   readonly usePortalContainer: () => HTMLElement | null;
   readonly usePackageRoute: () => PackageRoute;
@@ -306,6 +394,39 @@ export declare function useLocale(): Locale;
  * @returns `t`, and the language it speaks.
  */
 export declare function useTranslation(): Translation;
+/**
+ * The recorded changes of some entities over a window, live as the window moves: what a chart of
+ * an on/off thing, an activity list or a replay of a day is drawn from. Read with the viewer's
+ * permissions: an entity they may not read has no points.
+ *
+ * @param query - Which entities (at most 64), which window, how often to read it again.
+ * @returns Each entity's changes, oldest first, and whether the read is still on its way.
+ */
+export declare function useStateHistory(query: HistoryQuery): History<StateHistoryPoint>;
+/**
+ * The numeric readings of some entities over a window: what a sensor's chart is drawn from. A
+ * long window is read in buckets of a minute, an hour or a day, each with its lowest and highest.
+ *
+ * @param query - Which entities (at most 64), which window, which resolution (`auto` by default).
+ * @returns Each entity's readings, oldest first, and the resolution they were read at.
+ */
+export declare function useTelemetry(query: TelemetryQuery): Telemetry;
+/**
+ * The areas of the house: the house itself (with its position, when set), its floors and its
+ * rooms, as the owner arranged them.
+ *
+ * @returns Them, in the owner's order.
+ */
+export declare function useAreas(): readonly AreaView[];
+/**
+ * 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.
+ *
+ * @param entityId - A `camera.*` or an `image.*` entity.
+ * @param options - How often a still is fetched again, and whether at all.
+ * @returns The address, or null before there is one.
+ */
+export declare function useEntityPicture(entityId: EntityId, options?: PictureOptions): EntityPicture;
 /**
  * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
  *
@@ -351,4 +472,4 @@ export declare function PackageLink(props: PackageLinkProps): ReactElement;
  */
 export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
 //#endregion
-export type { CardProps, CustomEntityState, EntitiesFilter, EntityView, EntityViewProps, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, Theme, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };
+export type { AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -173,6 +173,47 @@ function useTranslation() {
 	return lent === void 0 ? ENGLISH : lent();
 }
 /**
+* The recorded changes of some entities over a window, live as the window moves: what a chart of
+* an on/off thing, an activity list or a replay of a day is drawn from. Read with the viewer's
+* permissions: an entity they may not read has no points.
+*
+* @param query - Which entities (at most 64), which window, how often to read it again.
+* @returns Each entity's changes, oldest first, and whether the read is still on its way.
+*/
+function useStateHistory(query) {
+	return ui("useStateHistory", "1.2")(query);
+}
+/**
+* The numeric readings of some entities over a window: what a sensor's chart is drawn from. A
+* long window is read in buckets of a minute, an hour or a day, each with its lowest and highest.
+*
+* @param query - Which entities (at most 64), which window, which resolution (`auto` by default).
+* @returns Each entity's readings, oldest first, and the resolution they were read at.
+*/
+function useTelemetry(query) {
+	return ui("useTelemetry", "1.2")(query);
+}
+/**
+* The areas of the house: the house itself (with its position, when set), its floors and its
+* rooms, as the owner arranged them.
+*
+* @returns Them, in the owner's order.
+*/
+function useAreas() {
+	return ui("useAreas", "1.2")();
+}
+/**
+* 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.
+*
+* @param entityId - A `camera.*` or an `image.*` entity.
+* @param options - How often a still is fetched again, and whether at all.
+* @returns The address, or null before there is one.
+*/
+function useEntityPicture(entityId, options) {
+	return ui("useEntityPicture", "1.2")(entityId, options);
+}
+/**
 * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
 *
 * @returns Light or dark.
@@ -231,4 +272,4 @@ function PlatformLink(props) {
 	return createElement(ui("PlatformLink", "1.0"), props);
 }
 //#endregion
-export { PackageLink, PlatformLink, useCommand, useCustomEntity, useEntities, useEntity, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useTheme, useTranslation, useViewer };
+export { PackageLink, PlatformLink, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useTranslation, useViewer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,10 @@
       "types": "./dist/ui.d.ts",
       "default": "./dist/ui.js"
     },
+    "./sun": {
+      "types": "./dist/sun.d.ts",
+      "default": "./dist/sun.js"
+    },
     "./components": {
       "types": "./dist/components.d.ts",
       "default": "./dist/components.js"
@@ -96,10 +100,10 @@
     "vitest": "^4.1.11",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@nebulahome/contracts": "0.0.0",
-    "@nebulahome/tsconfig": "0.0.0",
+    "@nebulahome/eslint-config": "0.0.0",
     "@nebulahome/ui": "0.0.0",
-    "@nebulahome/eslint-config": "0.0.0"
+    "@nebulahome/tsconfig": "0.0.0",
+    "@nebulahome/contracts": "0.0.0"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",