@nebulahome/package-sdk 1.1.0 → 1.3.0

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,100 @@ 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;
+};
+/** A floor or a room to add to the house. Since 1.3. */
+type AreaDraft = {
+  readonly kind: 'floor' | 'room';
+  readonly name: string;
+  /** The house a floor is in, the floor a room is on. */
+  readonly parentKey: string;
+  /** A floor's storey: 0 the ground floor, -1 the one below. */
+  readonly level?: number;
+};
+/** Changes to the house's areas, with the viewer's permissions. Since 1.3. */
+type AreaActions = {
+  /** Whether the viewer may change the areas (`area:write`). */
+  readonly canEdit: boolean;
+  /** Adds a floor or a room; its key comes from its name. */
+  readonly create: (draft: AreaDraft) => Promise<AreaView>;
+  readonly rename: (key: string, name: string) => Promise<void>;
+  /** Moves a floor to another storey. */
+  readonly setLevel: (key: string, level: number) => Promise<void>;
+  /** Removes an area and everything under it. */
+  readonly remove: (key: string) => Promise<void>;
+};
+/** 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. */
@@ -193,6 +294,10 @@ type PackageLinkProps = LinkAttributes & {
 type PlatformLinkProps = LinkAttributes & {
   readonly to: PlatformTarget;
 };
+/** What the header of the package's page shows. Since 1.3. */
+type PageActionsProps = {
+  readonly children?: ReactNode;
+};
 /** What the interface lends to implement `/ui`. */
 type UiHost = {
   readonly usePackage: () => PackageInfo;
@@ -208,6 +313,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;
@@ -215,6 +328,10 @@ type UiHost = {
   readonly usePlatformNavigate: () => PlatformNavigate;
   readonly PackageLink: ComponentType<PackageLinkProps>;
   readonly PlatformLink: ComponentType<PlatformLinkProps>;
+  /** Since 1.3. */
+  readonly PageActions: ComponentType<PageActionsProps>;
+  /** Since 1.3. */
+  readonly useAreaActions: () => AreaActions;
 };
 //#endregion
 //#region src/ui/index.d.ts
@@ -306,6 +423,46 @@ 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[];
+/**
+ * Adds, renames and removes the house's floors and rooms, as the platform's areas page does, with
+ * the viewer's permissions: `canEdit` says whether they hold them. Since 1.3.
+ *
+ * @returns What changes the areas.
+ */
+export declare function useAreaActions(): AreaActions;
+/**
+ * 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.
  *
@@ -350,5 +507,13 @@ export declare function PackageLink(props: PackageLinkProps): ReactElement;
  * @returns The link.
  */
 export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
+/**
+ * Buttons and links drawn in the header of the package's page, in place of the platform's own:
+ * the page's actions, beside its title. On a card or a view it draws nothing. Since 1.3.
+ *
+ * @param props - What the header shows.
+ * @returns The actions.
+ */
+export declare function PageActions(props: PageActionsProps): 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 { AreaActions, AreaDraft, AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageActionsProps, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };