@nebulahome/package-sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 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.3.0
+
+- **The page's actions in its header.** `<PageActions>` from `@nebulahome/package-sdk/ui` draws
+  its children in the header of the package's page, beside the title, in place of the platform's
+  own "Details": the buttons a page would otherwise give a row of their own. On a card or an
+  entity view it draws nothing.
+- **Changing the areas.** `useAreaActions()` adds a floor or a room to the house, renames one,
+  moves a floor to another storey or removes an area, with the viewer's permissions (`area:write`,
+  which `canEdit` says): a package that draws the house keeps its floors and rooms the house's own.
+
+## 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.3.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.3.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

@@ -116,9 +116,12 @@
   /** Scenes, aliases and computed things; the If lane of an automation. */
   --color-violet: #a78bfa;
 
-  /** Sensors, charts, live scanning; the When lane of an automation. */
+  /** Sensors, charts, live scanning; the When lane of an automation. Wi-Fi on a network map. */
   --color-cyan: #4fd0ee;
 
+  /** Thread, on a network map: its links, its routers. */
+  --color-thread: #e879f9;
+
   /* --- states ------------------------------------------------------------------------------ */
 
   --color-success: #52cd86;
@@ -258,6 +261,16 @@
   --text-headline--line-height: 1.25;
   --text-headline--letter-spacing: -0.02em;
 
+  /** A settings page's own title, beside its icon chip under the breadcrumb. */
+  --text-headline-lg: 24px;
+  --text-headline-lg--line-height: 1.2;
+  --text-headline-lg--letter-spacing: -0.02em;
+
+  /** The title of a section with its own column of pages, such as Settings. */
+  --text-display-sm: 28px;
+  --text-display-sm--line-height: 1.15;
+  --text-display-sm--letter-spacing: -0.03em;
+
   /** The page title, one per screen, with its meta beside it in `mono-ui`. */
   --text-display: 30px;
   --text-display--line-height: 1.15;
@@ -329,14 +342,15 @@
   /* --- depth -------------------------------------------------------------------------------- */
   /*
    * Flat. A panel has no resting shadow; an entity card has the faint lit top edge of `edge`. A
-   * dialog and the sign-in card take `dialog`, a menu and a dragged card `float`, a focused
-   * field `focus`.
+   * dialog and the sign-in card take `dialog`, a menu and a dragged card `float`, a popover
+   * (search results, the icon picker) `popover`, a focused field `focus`.
    */
 
   --shadow-edge: inset 0 1px 0 rgb(255 255 255 / 0.04);
   --shadow-focus: 0 0 0 3px rgb(124 134 255 / 0.25);
   --shadow-float: 0 24px 48px -12px rgb(0 0 0 / 0.7);
   --shadow-dialog: 0 30px 80px -20px rgb(0 0 0 / 0.9);
+  --shadow-popover: 0 28px 60px -20px rgb(0 0 0 / 0.95);
 
   /* --- motion ---------------------------------------------------------------------------- */
 
@@ -547,3 +561,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