busybar-kit 1.1.0 → 2.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 viirtualp1
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 viirtualp1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,148 +1,148 @@
-# busybar-kit
-
-> [!IMPORTANT]
-> **Unofficial community project.** Built and maintained by [@viirtualp1](https://github.com/viirtualp1), **not** an official Flipper Devices / BUSY product, and not affiliated with, endorsed by, or supported by them. "BUSY Bar" remains their trademark. For the real hardware and official apps, visit **[busy.app](https://busy.app/)**.
-
-Shared building blocks for [BUSY Bar](https://busy.bar) apps. Everything here is
-app-agnostic: screen geometry, the palette neutrals, formatters, ticker text,
-the Bar's error taxonomy, the connection half of a config, and an offline PNG
-renderer that draws the same elements the device does.
-
-It is the common half of [busybar-dota](https://github.com/viirtualp1/busybar-dota),
-[busybar-mydota](https://github.com/viirtualp1/busybar-mydota) and
-[busybar-livesplit](https://github.com/viirtualp1/busybar-livesplit).
-
-```bash
-npm install busybar-kit
-```
-
-`@busy-app/busy-lib` is a peer dependency — the app owns that version.
-
-## What is in it
-
-| Import                                                                    | What it gives you                                                                                              |
-| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `busybar-kit/device`                                                      | `FRONT` / `BACK` screen sizes, `FONT_WIDTH`, `textWidth`, `clipToWidth`, `fittingChars`, `rowY`, `backRowGrid` |
-| `busybar-kit/colors`                                                      | `BASE_COLORS` — neutrals, chrome, and the transparent value that hides an element                              |
-| `busybar-kit/format`                                                      | `formatClock`, `formatGold`, `formatCountdown`, `formatStartTime`, `formatKda`, `formatPercent`, …             |
-| `busybar-kit/elements`                                                    | `AnyElement`, `band()`, `fillWidth()`                                                                          |
-| `busybar-kit/ticker`                                                      | `paginate` / `pageAt` / `scrollAt` / `tickerLine`, and `EventTicker`                                           |
-| `busybar-kit/errors`                                                      | `BarApiError`, `toBarError`, `isLowPriority`, `isClientError`, `isForbidden`                                   |
-| `busybar-kit/config`                                                      | `loadEnvFile`, `envReader`, `loadBarConfig`                                                                    |
-| `busybar-kit/image`                                                       | `ditherToPanel` — a picture, in the back panel's 16 greys                                                      |
-| `busybar-kit/preview`                                                     | `renderFront` / `renderBack` / `Bitmap` — device-accurate PNGs with no hardware                                |
-| `busybar-kit/tsconfig.json`, `busybar-kit/eslint`, `busybar-kit/prettier` | the shared toolchain                                                                                           |
-| `busybar-fix-esm` (bin)                                                   | rewrites relative imports in `dist/` to carry `.js`, for Node ESM                                              |
-
-## Geometry is hardware, not layout
-
-`FRONT` (72×16) and `BACK` (160×80, with its header rows and 12px grid) are
-facts about the device. An app spreads its own named slots on top:
-
-```ts
-import { FRONT as DEVICE, BACK as DEVICE_BACK } from 'busybar-kit/device';
-
-export const FRONT = {
-  ...DEVICE,
-  topY: 0,
-  bottomY: 11,
-  clockWidth: 24,
-} as const;
-```
-
-An app whose header is a different height lays out its own row grid, and reads
-rows off that instead of the default:
-
-```ts
-import { backRowGrid, rowY as gridRowY } from 'busybar-kit/device';
-
-export const BACK = { ...DEVICE_BACK, ...backRowGrid(16), nameX: 8 } as const;
-
-export const rowY = (index: number) => gridRowY(index, BACK);
-```
-
-`clipToWidth` takes the truncation mark as a fourth argument (`'.'` by
-default, `'..'` where names are cut often enough to want the emphasis).
-
-Colours work the same way — `BASE_COLORS` holds what every app needs, and the
-app adds its own semantics:
-
-```ts
-import { BASE_COLORS } from 'busybar-kit/colors';
-
-export const COLORS = {
-  ...BASE_COLORS,
-  radiant: '#3FBF5FFF',
-  dire: '#E14B3AFF',
-} as const;
-```
-
-## Config
-
-`loadBarConfig` resolves which Bar to talk to and over which transport, and
-warns about credentials that transport will ignore. That is all it covers —
-render cadence and request timeouts are the app's own tempo (a speedrun timer
-wants 60ms frames where a match ticker is happy at 200), so they stay in the
-app's config with `DEFAULTS` / `LIMITS` as the values worth starting from.
-
-It hands back the same env reader, so an app's own settings collect their
-warnings into one list:
-
-```ts
-import { loadBarConfig, loadEnvFile } from 'busybar-kit/config';
-
-loadEnvFile();
-
-export function loadConfig(env = process.env) {
-  const warnings: string[] = [];
-  const { bar, env: read } = loadBarConfig(env, warnings);
-
-  return {
-    warnings,
-    config: {
-      ...bar,
-      gsiPort: read.number('GSI_PORT', 3080, { min: 1024, max: 65_535 }),
-    },
-  };
-}
-```
-
-## Pictures
-
-The back panel has 16 greys and quantises whatever you upload to them, so a
-photo sent as-is comes back in bands. `ditherToPanel` does the quantising here,
-with error diffusion, which leaves every pixel already sitting on a level:
-
-```ts
-import { ditherToPanel } from 'busybar-kit/image';
-
-const cover = ditherToPanel(decodedRgba); // 80x80 Bitmap, panel-ready
-await bar.AssetsUpload({ application_name: 'app', file: 'art.png', data: cover.toPng() });
-```
-
-It takes pixels, not files. Which image decoder to pay for is the app's
-choice — the kit stays dependency-free.
-
-`Bitmap.fromRgba` wraps pixels from anywhere, and `bitmap.blit(other, x, y)`
-draws one into another: the raster below cannot follow an image element's path,
-so a preview composites the picture itself.
-
-## Preview
-
-`renderFront` / `renderBack` rasterise the very element list you send to the
-device — a 3×5 pixel font, the same anchoring rules, and the back panel
-flattened to the 16 greys the real OLED shows. Useful for screenshots in a
-README and for asserting a layout in tests without a Bar on the desk.
-
-```ts
-import { renderFront } from 'busybar-kit/preview';
-
-writeFileSync('front.png', renderFront(frontElements(frame)).scale(8).toPng());
-```
-
-## Scripts
-
-```bash
-npm run check   # lint + typecheck + test
-npm run build   # tsc + .js extension fixup
-```
+# busybar-kit
+
+> [!IMPORTANT]
+> **Unofficial community project.** Built and maintained by [@viirtualp1](https://github.com/viirtualp1), **not** an official Flipper Devices / BUSY product, and not affiliated with, endorsed by, or supported by them. "BUSY Bar" remains their trademark. For the real hardware and official apps, visit **[busy.app](https://busy.app/)**.
+
+Shared building blocks for [BUSY Bar](https://busy.bar) apps. Everything here is
+app-agnostic: screen geometry, the palette neutrals, formatters, ticker text,
+the Bar's error taxonomy, the connection half of a config, and an offline PNG
+renderer that draws the same elements the device does.
+
+It is the common half of [busybar-dota](https://github.com/viirtualp1/busybar-dota),
+[busybar-mydota](https://github.com/viirtualp1/busybar-mydota) and
+[busybar-livesplit](https://github.com/viirtualp1/busybar-livesplit).
+
+```bash
+npm install busybar-kit
+```
+
+`@busy-app/busy-lib` is a peer dependency — the app owns that version.
+
+## What is in it
+
+| Import                                                                    | What it gives you                                                                                              |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `busybar-kit/device`                                                      | `FRONT` / `BACK` screen sizes, `FONT_WIDTH`, `textWidth`, `clipToWidth`, `fittingChars`, `rowY`, `backRowGrid` |
+| `busybar-kit/colors`                                                      | `BASE_COLORS` — neutrals, chrome, and the transparent value that hides an element                              |
+| `busybar-kit/format`                                                      | `formatClock`, `formatGold`, `formatCountdown`, `formatStartTime`, `formatKda`, `formatPercent`, …             |
+| `busybar-kit/elements`                                                    | `AnyElement`, `band()`, `fillWidth()`                                                                          |
+| `busybar-kit/ticker`                                                      | `paginate` / `pageAt` / `scrollAt` / `tickerLine`, and `EventTicker`                                           |
+| `busybar-kit/errors`                                                      | `BarApiError`, `toBarError`, `isLowPriority`, `isClientError`, `isForbidden`                                   |
+| `busybar-kit/config`                                                      | `loadEnvFile`, `envReader`, `loadBarConfig`                                                                    |
+| `busybar-kit/image`                                                       | `ditherToPanel` — a picture, in the back panel's 16 greys                                                      |
+| `busybar-kit/preview`                                                     | `renderFront` / `renderBack` / `Bitmap` — device-accurate PNGs with no hardware                                |
+| `busybar-kit/tsconfig.json`, `busybar-kit/eslint`, `busybar-kit/prettier` | the shared toolchain                                                                                           |
+| `busybar-fix-esm` (bin)                                                   | rewrites relative imports in `dist/` to carry `.js`, for Node ESM                                              |
+
+## Geometry is hardware, not layout
+
+`FRONT` (72×16) and `BACK` (160×80, with its header rows and 12px grid) are
+facts about the device. An app spreads its own named slots on top:
+
+```ts
+import { FRONT as DEVICE, BACK as DEVICE_BACK } from 'busybar-kit/device';
+
+export const FRONT = {
+  ...DEVICE,
+  topY: 0,
+  bottomY: 11,
+  clockWidth: 24,
+} as const;
+```
+
+An app whose header is a different height lays out its own row grid, and reads
+rows off that instead of the default:
+
+```ts
+import { backRowGrid, rowY as gridRowY } from 'busybar-kit/device';
+
+export const BACK = { ...DEVICE_BACK, ...backRowGrid(16), nameX: 8 } as const;
+
+export const rowY = (index: number) => gridRowY(index, BACK);
+```
+
+`clipToWidth` takes the truncation mark as a fourth argument (`'.'` by
+default, `'..'` where names are cut often enough to want the emphasis).
+
+Colours work the same way — `BASE_COLORS` holds what every app needs, and the
+app adds its own semantics:
+
+```ts
+import { BASE_COLORS } from 'busybar-kit/colors';
+
+export const COLORS = {
+  ...BASE_COLORS,
+  radiant: '#3FBF5FFF',
+  dire: '#E14B3AFF',
+} as const;
+```
+
+## Config
+
+`loadBarConfig` resolves which Bar to talk to and over which transport, and
+warns about credentials that transport will ignore. That is all it covers —
+render cadence and request timeouts are the app's own tempo (a speedrun timer
+wants 60ms frames where a match ticker is happy at 200), so they stay in the
+app's config with `DEFAULTS` / `LIMITS` as the values worth starting from.
+
+It hands back the same env reader, so an app's own settings collect their
+warnings into one list:
+
+```ts
+import { loadBarConfig, loadEnvFile } from 'busybar-kit/config';
+
+loadEnvFile();
+
+export function loadConfig(env = process.env) {
+  const warnings: string[] = [];
+  const { bar, env: read } = loadBarConfig(env, warnings);
+
+  return {
+    warnings,
+    config: {
+      ...bar,
+      gsiPort: read.number('GSI_PORT', 3080, { min: 1024, max: 65_535 }),
+    },
+  };
+}
+```
+
+## Pictures
+
+The back panel has 16 greys and quantises whatever you upload to them, so a
+photo sent as-is comes back in bands. `ditherToPanel` does the quantising here,
+with error diffusion, which leaves every pixel already sitting on a level:
+
+```ts
+import { ditherToPanel } from 'busybar-kit/image';
+
+const cover = ditherToPanel(decodedRgba); // 80x80 Bitmap, panel-ready
+await bar.AssetsUpload({ application_name: 'app', file: 'art.png', data: cover.toPng() });
+```
+
+It takes pixels, not files. Which image decoder to pay for is the app's
+choice — the kit stays dependency-free.
+
+`Bitmap.fromRgba` wraps pixels from anywhere, and `bitmap.blit(other, x, y)`
+draws one into another: the raster below cannot follow an image element's path,
+so a preview composites the picture itself.
+
+## Preview
+
+`renderFront` / `renderBack` rasterise the very element list you send to the
+device — a 3×5 pixel font, the same anchoring rules, and the back panel
+flattened to the 16 greys the real OLED shows. Useful for screenshots in a
+README and for asserting a layout in tests without a Bar on the desk.
+
+```ts
+import { renderFront } from 'busybar-kit/preview';
+
+writeFileSync('front.png', renderFront(frontElements(frame)).scale(8).toPng());
+```
+
+## Scripts
+
+```bash
+npm run check   # lint + typecheck + test
+npm run build   # tsc + .js extension fixup
+```

package/dist/config-spec.d.ts

@@ -1,16 +1,20 @@
 /**
- * How an app describes its own settings, so something else can ask about them.
+ * How an app describes its own settings — as data, so anything can read it.
  *
- * The point is that the app owns the description. `busybar-flights` knows that
- * a route reads `SVO-JFK` and that a departure is a local time without a zone;
- * an editor that had to know those things for every app would need editing
- * every time a new app appeared. With a spec, installing a package is enough.
+ * The app owns the description. `busybar-flights` knows that a route reads
+ * `SVO-JFK` and that a departure is a local time with no zone; an editor that
+ * had to know that for every app would need editing every time a new app
+ * appeared. With a spec, installing a package is enough.
  *
- * Specs are modules rather than JSON because the useful parts — how one entry
- * reads in a picker, whether a value is acceptable — are functions. An app
- * points at its own with a `busybar.config` field in package.json:
+ * Everything here is JSON. Checks are rules rather than functions and a list
+ * entry's one-line summary is a template rather than a callback, so a browser
+ * or a Dart client can interpret a spec without running the app's JavaScript.
+ * An app points at its own from package.json:
  *
- *     "busybar": { "config": "./dist/config-spec.js" }
+ *     "busybar": {
+ *       "config": "./dist/config-spec.js",
+ *       "configJson": "./dist/config-spec.json"
+ *     }
  */
 export type FieldType = 'text' | 'secret' | 'number' | 'boolean' | 'select' | 'datetime' | 'path';
 export type FieldOption = {
@@ -18,6 +22,24 @@ export type FieldOption = {
     label: string;
     hint?: string;
 };
+/** Checks a client interprets. Never code — see `validateValue`. */
+export type ValidationRule = {
+    kind: 'required';
+    message?: string;
+} | {
+    kind: 'pattern';
+    pattern: string;
+    message: string;
+} | {
+    kind: 'integer';
+    min: number;
+    max: number;
+    message?: string;
+} | {
+    kind: 'datetime';
+    format: 'local';
+    message?: string;
+};
 export type ConfigField = {
     /** The env variable, or the key inside a record. */
     key: string;
@@ -34,9 +56,14 @@ export type ConfigField = {
     options?: readonly FieldOption[];
     /** What the app itself would do with the setting left out. */
     fallback?: string;
-    /** A message when the answer will not do, or nothing when it will. */
-    validate?: (value: string) => string | undefined;
+    rules?: ValidationRule[];
 };
+/**
+ * Whether a change lands without help. Declared by the app because only the
+ * app knows: dota re-reads its schedule on every poll, everything else reads
+ * its settings once, at startup.
+ */
+export type Reloads = 'live' | 'restart';
 /** A file of records you add to, edit and remove — flights, fixtures. */
 export type ListSection = {
     kind: 'list';
@@ -51,11 +78,12 @@ export type ListSection = {
     at?: string;
     /** Settings that live beside the array in the same file, not in `.env`. */
     header?: ConfigField[];
-    /** What one entry looks like in the picker. */
-    summary: (entry: Record<string, string>) => string;
+    /** How one entry reads in a picker. See `renderSummary` for the syntax. */
+    summary: string;
     fields: ConfigField[];
     /** Shown instead of the picker when the file has nothing in it yet. */
     empty?: string;
+    reloads?: Reloads;
 };
 /** Plain settings, one key to a line. */
 export type EnvSection = {
@@ -63,19 +91,35 @@ export type EnvSection = {
     file: string;
     title: string;
     fields: ConfigField[];
+    reloads?: Reloads;
 };
 export type ConfigSection = ListSection | EnvSection;
 export type AppConfigSpec = {
+    /** The contract version. A client refuses one it does not know. */
+    specVersion: number;
     /** The `application_name` the app draws with — the join with everything else. */
     name: string;
     /** One line about what the app is, for the app picker. */
     summary?: string;
     sections: ConfigSection[];
 };
-/** Identity, for the types. Specs are data; this only saves the annotation. */
-export declare function defineConfigSpec(spec: AppConfigSpec): AppConfigSpec;
-export declare function required(label: string): (value: string) => string | undefined;
-export declare function integerIn(min: number, max: number): (value: string) => string | undefined;
-export declare function matching(pattern: RegExp, message: string): (value: string) => string | undefined;
-export declare function localDateTime(value: string): "YYYY-MM-DD HH:MM" | "that is not a real date" | undefined;
+export declare const SPEC_VERSION = 1;
+/**
+ * Stamps the current version onto a spec, so an author cannot get it wrong and
+ * a client always has one to check.
+ */
+export declare function defineConfigSpec(spec: Omit<AppConfigSpec, 'specVersion'>): AppConfigSpec;
+/**
+ * Reads a spec that came from outside — a file, a package, an HTTP response.
+ * The version check is the whole point: once something else reads these, the
+ * shape is a contract, and a client that guesses at an unknown one is worse
+ * than a client that says which package needs updating.
+ */
+export declare function parseSpecJson(text: string, source?: string): AppConfigSpec;
+export declare function parseSpec(raw: unknown, source?: string): AppConfigSpec;
+export declare function required(label?: string): ValidationRule;
+export declare function integerIn(min: number, max: number, message?: string): ValidationRule;
+export declare function matching(pattern: RegExp | string, message: string): ValidationRule;
+/** `2026-09-08 19:30` — a local time at the airport, with no zone on it. */
+export declare const localDateTime: ValidationRule;
 //# sourceMappingURL=config-spec.d.ts.map

package/dist/config-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-spec.d.ts","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,SAAS,GACnB,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5E,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,MAAM,MAAM,WAAW,GAAG;IACxB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oBAAoB;IACpB,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAClD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,+CAA+C;IAC/C,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;IACnD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAC1B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAEnE;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,IAC5B,OAAO,MAAM,wBACtB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,IACxC,OAAO,MAAM,wBAWtB;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAC/C,OAAO,MAAM,wBAEtB;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,8DAW1C"}
+{"version":3,"file":"config-spec.d.ts","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"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"}

package/dist/config-spec.js

@@ -1,54 +1,77 @@
 /**
- * How an app describes its own settings, so something else can ask about them.
+ * How an app describes its own settings — as data, so anything can read it.
  *
- * The point is that the app owns the description. `busybar-flights` knows that
- * a route reads `SVO-JFK` and that a departure is a local time without a zone;
- * an editor that had to know those things for every app would need editing
- * every time a new app appeared. With a spec, installing a package is enough.
+ * The app owns the description. `busybar-flights` knows that a route reads
+ * `SVO-JFK` and that a departure is a local time with no zone; an editor that
+ * had to know that for every app would need editing every time a new app
+ * appeared. With a spec, installing a package is enough.
  *
- * Specs are modules rather than JSON because the useful parts — how one entry
- * reads in a picker, whether a value is acceptable — are functions. An app
- * points at its own with a `busybar.config` field in package.json:
+ * Everything here is JSON. Checks are rules rather than functions and a list
+ * entry's one-line summary is a template rather than a callback, so a browser
+ * or a Dart client can interpret a spec without running the app's JavaScript.
+ * An app points at its own from package.json:
  *
- *     "busybar": { "config": "./dist/config-spec.js" }
+ *     "busybar": {
+ *       "config": "./dist/config-spec.js",
+ *       "configJson": "./dist/config-spec.json"
+ *     }
+ */
+export const SPEC_VERSION = 1;
+/**
+ * Stamps the current version onto a spec, so an author cannot get it wrong and
+ * a client always has one to check.
  */
-/** Identity, for the types. Specs are data; this only saves the annotation. */
 export function defineConfigSpec(spec) {
-    return spec;
-}
-// --- Validators the apps kept writing for themselves -------------------------
-export function required(label) {
-    return (value) => (value.trim() ? undefined : `${label} is needed`);
-}
-export function integerIn(min, max) {
-    return (value) => {
-        if (!value.trim()) {
-            return undefined;
-        }
-        const parsed = Number(value);
-        if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
-            return 'a whole number, please';
-        }
-        return parsed < min || parsed > max ? `between ${min} and ${max}` : undefined;
-    };
-}
-export function matching(pattern, message) {
-    return (value) => !value.trim() || pattern.test(value.trim()) ? undefined : message;
+    return { specVersion: SPEC_VERSION, ...spec };
 }
 /**
- * `2026-09-08 19:30` — a local time at the airport, with no zone on it, which
- * is how departure boards and boarding passes are written.
+ * Reads a spec that came from outside — a file, a package, an HTTP response.
+ * The version check is the whole point: once something else reads these, the
+ * shape is a contract, and a client that guesses at an unknown one is worse
+ * than a client that says which package needs updating.
  */
-const LOCAL_DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{1,2}:\d{2}$/;
-export function localDateTime(value) {
-    if (!value.trim()) {
-        return undefined;
+export function parseSpecJson(text, source = 'spec') {
+    let raw;
+    try {
+        raw = JSON.parse(text);
     }
-    if (!LOCAL_DATETIME.test(value.trim())) {
-        return 'YYYY-MM-DD HH:MM';
+    catch (error) {
+        throw new Error(`${source}: not valid JSON`, { cause: error });
+    }
+    return parseSpec(raw, source);
+}
+export function parseSpec(raw, source = 'spec') {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`${source}: a spec must be an object`);
     }
-    return Number.isNaN(Date.parse(value.trim().replace(' ', 'T')))
-        ? 'that is not a real date'
-        : undefined;
+    const candidate = raw;
+    if (candidate.specVersion !== SPEC_VERSION) {
+        throw new Error(`${source}: specVersion ${String(candidate.specVersion)} is not ${SPEC_VERSION} — update whichever side is older`);
+    }
+    if (typeof candidate.name !== 'string' || !candidate.name.trim()) {
+        throw new Error(`${source}: a spec needs the application name it configures`);
+    }
+    if (!Array.isArray(candidate.sections)) {
+        throw new Error(`${source}: a spec needs a sections array`);
+    }
+    return candidate;
+}
+// --- Rules, written as data ---------------------------------------------------
+export function required(label) {
+    return label
+        ? { kind: 'required', message: `${label} is needed` }
+        : { kind: 'required' };
+}
+export function integerIn(min, max, message) {
+    return message ? { kind: 'integer', min, max, message } : { kind: 'integer', min, max };
+}
+export function matching(pattern, message) {
+    return {
+        kind: 'pattern',
+        pattern: typeof pattern === 'string' ? pattern : pattern.source,
+        message,
+    };
 }
+/** `2026-09-08 19:30` — a local time at the airport, with no zone on it. */
+export const localDateTime = { kind: 'datetime', format: 'local' };
 //# sourceMappingURL=config-spec.js.map

package/dist/config-spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-spec.js","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkEH,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,IAAmB;IAClD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAEhF,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,GAAW;IAChD,OAAO,CAAC,KAAa,EAAE,EAAE;QACvB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAClB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,OAAO,wBAAwB,CAAC;QAClC,CAAC;QAED,OAAO,MAAM,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,OAAe;IACvD,OAAO,CAAC,KAAa,EAAE,EAAE,CACvB,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,cAAc,GAAG,sCAAsC,CAAC;AAE9D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACvC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC,yBAAyB;QAC3B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}
+{"version":3,"file":"config-spec.js","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmFH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAwC;IAExC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,MAAM,GAAG,MAAM;IACzD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,kBAAkB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAY,EAAE,MAAM,GAAG,MAAM;IACrD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,4BAA4B,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,SAAS,GAAG,GAA6B,CAAC;IAEhD,IAAI,SAAS,CAAC,WAAW,KAAK,YAAY,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,iBAAiB,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,WAAW,YAAY,mCAAmC,CAClH,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,mDAAmD,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,iCAAiC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,SAA0B,CAAC;AACpC,CAAC;AAED,iFAAiF;AAEjF,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK;QACV,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,KAAK,YAAY,EAAE;QACrD,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,GAAW,EAAE,OAAgB;IAClE,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAwB,EAAE,OAAe;IAChE,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM;QAC/D,OAAO;KACR,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAmB,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './colors.js';
 export * from './config/index.js';
 export * from './config-spec.js';
+export * from './rules.js';
+export * from './summary.js';
 export * from './device.js';
 export * from './elements.js';
 export * from './errors.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './colors.js';
 export * from './config/index.js';
 export * from './config-spec.js';
+export * from './rules.js';
+export * from './summary.js';
 export * from './device.js';
 export * from './elements.js';
 export * from './errors.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}

package/dist/rules.d.ts

@@ -0,0 +1,7 @@
+import type { ConfigField, ValidationRule } from './config-spec.js';
+/**
+ * One interpreter for every client — CLI, daemon, and the browser.
+ * Empty values are fine unless a `required` rule (or the field flag) says otherwise.
+ */
+export declare function validateValue(rules: readonly ValidationRule[] | undefined, value: string, field?: Pick<ConfigField, 'label' | 'required' | 'type'>, current?: string): string | undefined;
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIjE;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EAC5C,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC,EACxD,OAAO,SAAK,GACX,MAAM,GAAG,SAAS,CAmBpB"}

package/dist/rules.js

@@ -0,0 +1,71 @@
+const LOCAL_DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{1,2}:\d{2}$/;
+/**
+ * One interpreter for every client — CLI, daemon, and the browser.
+ * Empty values are fine unless a `required` rule (or the field flag) says otherwise.
+ */
+export function validateValue(rules, value, field, current = '') {
+    const trimmed = value.trim();
+    if (field?.required && !trimmed && !(field.type === 'secret' && current)) {
+        return `${field.label} is needed`;
+    }
+    if (!rules?.length) {
+        return undefined;
+    }
+    for (const rule of rules) {
+        const error = checkRule(rule, trimmed, field?.label);
+        if (error) {
+            return error;
+        }
+    }
+    return undefined;
+}
+function checkRule(rule, value, label) {
+    switch (rule.kind) {
+        case 'required':
+            return value
+                ? undefined
+                : (rule.message ?? (label ? `${label} is needed` : 'this is needed'));
+        case 'pattern': {
+            if (!value) {
+                return undefined;
+            }
+            try {
+                return new RegExp(rule.pattern).test(value) ? undefined : rule.message;
+            }
+            catch {
+                return rule.message;
+            }
+        }
+        case 'integer': {
+            if (!value) {
+                return undefined;
+            }
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+                return rule.message ?? 'a whole number, please';
+            }
+            return parsed < rule.min || parsed > rule.max
+                ? (rule.message ?? `between ${rule.min} and ${rule.max}`)
+                : undefined;
+        }
+        case 'datetime': {
+            if (!value) {
+                return undefined;
+            }
+            if (rule.format !== 'local') {
+                return rule.message ?? 'unsupported datetime format';
+            }
+            if (!LOCAL_DATETIME.test(value)) {
+                return rule.message ?? 'YYYY-MM-DD HH:MM';
+            }
+            return Number.isNaN(Date.parse(value.replace(' ', 'T')))
+                ? (rule.message ?? 'that is not a real date')
+                : undefined;
+        }
+        default: {
+            const _exhaustive = rule;
+            return `unknown rule ${JSON.stringify(_exhaustive)}`;
+        }
+    }
+}
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

package/dist/summary.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The one line that stands for a record in a picker.
+ *
+ * A template rather than a function, because every client has to render it and
+ * only one of them can run JavaScript. Deliberately small — anything that needs
+ * more than this is a sign the app should be storing a different shape:
+ *
+ *     {key}      the value, or nothing
+ *     {a|b}      a if it has a value, else b — `{route|from-to}`
+ *     {a-b}      both joined by what sits between them, or nothing if either
+ *                is missing, so a half-filled route is not rendered as `SVO-`
+ *     BO{bo}     a literal glued to a token goes when the token does
+ *
+ * Whitespace left behind by a missing value collapses; whitespace you put
+ * between two values that are both there is kept, so columns still line up.
+ */
+export declare function renderSummary(template: string, entry: Record<string, string>): string;
+//# sourceMappingURL=summary.d.ts.map

package/dist/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA6BrF"}

package/dist/summary.js

@@ -0,0 +1,63 @@
+/**
+ * The one line that stands for a record in a picker.
+ *
+ * A template rather than a function, because every client has to render it and
+ * only one of them can run JavaScript. Deliberately small — anything that needs
+ * more than this is a sign the app should be storing a different shape:
+ *
+ *     {key}      the value, or nothing
+ *     {a|b}      a if it has a value, else b — `{route|from-to}`
+ *     {a-b}      both joined by what sits between them, or nothing if either
+ *                is missing, so a half-filled route is not rendered as `SVO-`
+ *     BO{bo}     a literal glued to a token goes when the token does
+ *
+ * Whitespace left behind by a missing value collapses; whitespace you put
+ * between two values that are both there is kept, so columns still line up.
+ */
+export function renderSummary(template, entry) {
+    const parts = [];
+    let carry = '';
+    // One pass: a token plus whatever literal is glued to its left, so the
+    // literal can leave with it.
+    const pattern = /([^\s{}]*)\{([^{}]+)\}/g;
+    let at = 0;
+    for (let match = pattern.exec(template); match; match = pattern.exec(template)) {
+        carry += template.slice(at, match.index);
+        at = match.index + match[0].length;
+        const value = resolve(match[2] ?? '', entry);
+        if (value) {
+            parts.push(`${carry}${match[1] ?? ''}${value}`);
+            carry = '';
+        }
+        else {
+            // The token and its glued prefix are dropped; the separator before them
+            // is dropped with them rather than doubling up.
+            carry = carry.trimEnd() ? carry : '';
+        }
+    }
+    const tail = `${carry}${template.slice(at)}`;
+    if (tail.trim()) {
+        parts.push(tail);
+    }
+    return parts.join('').replace(/^\s+|\s+$/g, '');
+}
+function resolve(token, entry) {
+    const bar = token.indexOf('|');
+    if (bar !== -1) {
+        const left = resolve(token.slice(0, bar), entry);
+        return left || resolve(token.slice(bar + 1), entry);
+    }
+    // `{from-to}` and friends: two keys with a literal between them, present only
+    // when both sides are.
+    const joined = /^([A-Za-z_]\w*)(\W+)([A-Za-z_]\w*)$/.exec(token);
+    if (joined) {
+        const left = value(entry, joined[1]);
+        const right = value(entry, joined[3]);
+        return left && right ? `${left}${joined[2] ?? ''}${right}` : '';
+    }
+    return value(entry, token);
+}
+function value(entry, key) {
+    return key ? (entry[key] ?? '').trim() : '';
+}
+//# sourceMappingURL=summary.js.map

package/dist/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busybar-kit",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Shared building blocks for BUSY Bar apps: device geometry, colours, formatters, ticker text, error taxonomy and an offline PNG preview renderer",
   "author": "viirtualp1",
   "license": "MIT",
@@ -20,6 +20,8 @@
     "./colors": "./dist/colors.js",
     "./config": "./dist/config/index.js",
     "./config-spec": "./dist/config-spec.js",
+    "./rules": "./dist/rules.js",
+    "./summary": "./dist/summary.js",
     "./device": "./dist/device.js",
     "./elements": "./dist/elements.js",
     "./errors": "./dist/errors.js",
@@ -34,7 +36,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "busybar-fix-esm": "scripts/fix-esm-extensions.mjs"
+    "busybar-fix-esm": "scripts/fix-esm-extensions.mjs",
+    "busybar-emit-spec": "scripts/emit-config-spec.mjs"
   },
   "files": [
     "dist",

package/scripts/emit-config-spec.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Writes `dist/config-spec.json` from the built `dist/config-spec.js`.
+//
+// Specs are authored in TypeScript for the types and the autocompletion, but a
+// browser or a Dart client cannot import a JS module out of node_modules. The
+// JSON beside it is what makes the spec readable by anything at all — and
+// emitting it from the built module rather than hand-maintaining a second copy
+// is what keeps the two from drifting.
+import { existsSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const argument = process.argv[2] ?? 'dist/config-spec.js';
+const source = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
+
+if (!existsSync(source)) {
+  console.error(`busybar-emit-spec: ${source} is not there — build first`);
+  process.exit(1);
+}
+
+const module = await import(pathToFileURL(source).href);
+const spec = module.default;
+
+if (!spec || typeof spec !== 'object' || typeof spec.name !== 'string') {
+  console.error(`busybar-emit-spec: ${source} has no config spec as its default export`);
+  process.exit(1);
+}
+
+const target = source.replace(/\.js$/, '.json');
+writeFileSync(target, `${JSON.stringify(spec, null, 2)}\n`);
+console.log(`busybar-emit-spec: wrote ${target}`);

package/scripts/fix-esm-extensions.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-
-// Node's ESM loader wants a real file name; tsc leaves extensionless specifiers.
-const argument = process.argv[2] ?? 'dist';
-const dist = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
-const EXTENSIONS = /\.(?:js|json|mjs|cjs|node)$/;
-
-function walk(dir) {
-  for (const name of readdirSync(dir)) {
-    const path = join(dir, name);
-    if (statSync(path).isDirectory()) {
-      walk(path);
-      continue;
-    }
-    if (!/\.(?:js|d\.ts)$/.test(name)) {
-      continue;
-    }
-
-    const source = readFileSync(path, 'utf8');
-    const next = source.replace(
-      /(from\s+|import\s*\()(['"])(\.[^'"]+)\2/g,
-      (match, prefix, quote, spec) =>
-        EXTENSIONS.test(spec) ? match : `${prefix}${quote}${spec}.js${quote}`,
-    );
-    if (next !== source) {
-      writeFileSync(path, next);
-    }
-  }
-}
-
-walk(dist);
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+// Node's ESM loader wants a real file name; tsc leaves extensionless specifiers.
+const argument = process.argv[2] ?? 'dist';
+const dist = isAbsolute(argument) ? argument : resolve(process.cwd(), argument);
+const EXTENSIONS = /\.(?:js|json|mjs|cjs|node)$/;
+
+function walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      walk(path);
+      continue;
+    }
+    if (!/\.(?:js|d\.ts)$/.test(name)) {
+      continue;
+    }
+
+    const source = readFileSync(path, 'utf8');
+    const next = source.replace(
+      /(from\s+|import\s*\()(['"])(\.[^'"]+)\2/g,
+      (match, prefix, quote, spec) =>
+        EXTENSIONS.test(spec) ? match : `${prefix}${quote}${spec}.js${quote}`,
+    );
+    if (next !== source) {
+      writeFileSync(path, next);
+    }
+  }
+}
+
+walk(dist);