@nebulahome/package-sdk 1.0.1 → 1.2.0

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.0.1";
+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.
    *