busybar-kit 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# busybar-kit
+
+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/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 }),
+    },
+  };
+}
+```
+
+## 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/configs/eslint.config.js

@@ -0,0 +1,58 @@
+import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import tseslint from 'typescript-eslint';
+
+/**
+ * The lint rules every BUSY Bar app shares. `rootDir` is the app's own
+ * directory, so type-aware rules read that app's tsconfig:
+ *
+ *     import { barEslintConfig } from 'busybar-kit/eslint';
+ *     export default barEslintConfig(import.meta.dirname);
+ */
+export function barEslintConfig(rootDir, ...extra) {
+  return tseslint.config(
+    { ignores: ['dist/**', 'node_modules/**', 'scripts/**'] },
+    js.configs.recommended,
+    ...tseslint.configs.recommendedTypeChecked,
+    {
+      languageOptions: {
+        parserOptions: {
+          project: ['./tsconfig.json'],
+          tsconfigRootDir: rootDir,
+        },
+      },
+      rules: {
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+        ],
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          { fixStyle: 'inline-type-imports' },
+        ],
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/switch-exhaustiveness-check': 'error',
+        eqeqeq: ['error', 'always'],
+        'no-console': 'off',
+        'prefer-const': 'error',
+      },
+    },
+    {
+      files: ['test/**/*.ts'],
+      rules: {
+        '@typescript-eslint/no-non-null-assertion': 'off',
+        // node:test returns a promise that is meant to be left alone
+        '@typescript-eslint/no-floating-promises': 'off',
+        '@typescript-eslint/require-await': 'off',
+      },
+    },
+    {
+      files: ['**/*.js'],
+      extends: [tseslint.configs.disableTypeChecked],
+    },
+    prettier,
+    ...extra,
+  );
+}
+
+export default barEslintConfig(import.meta.dirname);

package/configs/prettier.json

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 90
+}

package/configs/tsconfig.base.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  }
+}

package/dist/colors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The palette every app shares: neutrals, chrome and the transparent value the
+ * Bar uses to hide an element. App-specific semantics (team colours, ahead/
+ * behind, gold) are spread on top of this in the app's own colours module.
+ */
+export declare const BASE_COLORS: {
+    readonly white: "#FFFFFFFF";
+    readonly transparent: "#00000000";
+    readonly muted: "#9AA0A6FF";
+    readonly dim: "#6B7075FF";
+    readonly backText: "#E6E6E6FF";
+    readonly backDivider: "#5A5A5AFF";
+    readonly clock: "#D8DCE0FF";
+    readonly ticker: "#FFFFFFFF";
+    readonly panelDark: "#000000FF";
+};
+export type BaseColor = keyof typeof BASE_COLORS;
+//# sourceMappingURL=colors.d.ts.map

package/dist/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;CAUd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC"}

package/dist/colors.js

@@ -0,0 +1,17 @@
+/**
+ * The palette every app shares: neutrals, chrome and the transparent value the
+ * Bar uses to hide an element. App-specific semantics (team colours, ahead/
+ * behind, gold) are spread on top of this in the app's own colours module.
+ */
+export const BASE_COLORS = {
+    white: '#FFFFFFFF',
+    transparent: '#00000000',
+    muted: '#9AA0A6FF',
+    dim: '#6B7075FF',
+    backText: '#E6E6E6FF',
+    backDivider: '#5A5A5AFF',
+    clock: '#D8DCE0FF',
+    ticker: '#FFFFFFFF',
+    panelDark: '#000000FF',
+};
+//# sourceMappingURL=colors.js.map

package/dist/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE,WAAW;IAClB,GAAG,EAAE,WAAW;IAChB,QAAQ,EAAE,WAAW;IACrB,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE,WAAW;IAClB,MAAM,EAAE,WAAW;IACnB,SAAS,EAAE,WAAW;CACd,CAAC"}

package/dist/config/bar.d.ts

@@ -0,0 +1,51 @@
+import { type EnvReader } from './env.js';
+export declare const DEFAULTS: {
+    readonly usbAddr: "10.0.4.20";
+    readonly cloudAddr: "https://api.busy.app";
+    readonly drawPriority: 40;
+    readonly frameMs: 200;
+    readonly requestTimeoutMs: 10000;
+};
+export declare const LIMITS: {
+    readonly drawPriority: {
+        readonly min: 0;
+        readonly max: 100;
+    };
+    readonly frameMs: {
+        readonly min: 50;
+        readonly max: 2000;
+    };
+    readonly requestTimeoutMs: {
+        readonly min: 1000;
+        readonly max: 30000;
+    };
+};
+/**
+ * How an app reaches the Bar, and nothing else. 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` here as the values worth starting from.
+ */
+export type BarConfig = {
+    busyAddr: string;
+    isCloud: boolean;
+    isUsb: boolean;
+    busyToken: string;
+    busyHttpPassword: string;
+    drawPriority: number;
+};
+export declare function isCloudAddr(addr: string): boolean;
+export declare function isUsbAddr(addr: string): boolean;
+export type LoadedBarConfig = {
+    bar: BarConfig;
+    warnings: string[];
+    env: EnvReader;
+};
+/**
+ * Resolves the connection half of an app's config: which Bar, over which
+ * transport, with which credential — and warns about credentials that will be
+ * ignored on the transport in use. Apps build their own config on top, reusing
+ * the returned reader so their warnings land in the same list.
+ */
+export declare function loadBarConfig(env?: NodeJS.ProcessEnv, warnings?: string[]): LoadedBarConfig;
+//# sourceMappingURL=bar.d.ts.map

package/dist/config/bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar.d.ts","sourceRoot":"","sources":["../../src/config/bar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElD,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;;;;;CAIT,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,WAEvC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,WAOrC;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,EAAE,SAAS,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,MAAM,EAAO,GACtB,eAAe,CA0CjB"}

package/dist/config/bar.js

@@ -0,0 +1,65 @@
+import { envReader } from './env.js';
+export const DEFAULTS = {
+    usbAddr: '10.0.4.20',
+    cloudAddr: 'https://api.busy.app',
+    drawPriority: 40,
+    frameMs: 200,
+    requestTimeoutMs: 10_000,
+};
+export const LIMITS = {
+    drawPriority: { min: 0, max: 100 },
+    frameMs: { min: 50, max: 2000 },
+    requestTimeoutMs: { min: 1000, max: 30_000 },
+};
+export function isCloudAddr(addr) {
+    return /api(?:\.(?:dev|test|stage))?\.busy\.app/i.test(addr);
+}
+export function isUsbAddr(addr) {
+    try {
+        const url = /^https?:\/\//i.test(addr) ? new URL(addr) : new URL(`http://${addr}`);
+        return url.hostname === DEFAULTS.usbAddr;
+    }
+    catch {
+        return addr.includes(DEFAULTS.usbAddr);
+    }
+}
+/**
+ * Resolves the connection half of an app's config: which Bar, over which
+ * transport, with which credential — and warns about credentials that will be
+ * ignored on the transport in use. Apps build their own config on top, reusing
+ * the returned reader so their warnings land in the same list.
+ */
+export function loadBarConfig(env = process.env, warnings = []) {
+    const reader = envReader(env, warnings);
+    const { read, number } = reader;
+    const token = read('BUSY_TOKEN');
+    const httpPassword = read('BUSY_HTTP_PASSWORD');
+    const busyAddr = read('BUSY_ADDR') || (token ? DEFAULTS.cloudAddr : DEFAULTS.usbAddr);
+    const cloud = isCloudAddr(busyAddr);
+    const usb = isUsbAddr(busyAddr);
+    if (cloud && httpPassword) {
+        warnings.push('BUSY_HTTP_PASSWORD is ignored on cloud, only BUSY_TOKEN is used');
+    }
+    if (!cloud && token) {
+        warnings.push(`BUSY_TOKEN is ignored for ${busyAddr}, that token only works on cloud`);
+    }
+    if (usb && httpPassword) {
+        warnings.push('BUSY_HTTP_PASSWORD is ignored over USB, no auth is required there');
+    }
+    if (!cloud && !usb && !httpPassword) {
+        warnings.push('Wi-Fi needs BUSY_HTTP_PASSWORD (Bar web UI → Network → HTTP API access)');
+    }
+    return {
+        warnings,
+        env: reader,
+        bar: {
+            busyAddr,
+            isCloud: cloud,
+            isUsb: usb,
+            busyToken: cloud ? token : '',
+            busyHttpPassword: cloud || usb ? '' : httpPassword,
+            drawPriority: number('DRAW_PRIORITY', DEFAULTS.drawPriority, LIMITS.drawPriority),
+        },
+    };
+}
+//# sourceMappingURL=bar.js.map

package/dist/config/bar.js.map

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

package/dist/config/env.d.ts

@@ -0,0 +1,15 @@
+export type Limits = {
+    min: number;
+    max: number;
+};
+export declare function loadEnvFile(cwd?: string): void;
+export type EnvReader = {
+    read: (name: string) => string;
+    number: (name: string, fallback: number, limits: Limits, round?: boolean) => number;
+};
+/**
+ * Reads settings out of the environment, clamping numbers into range and
+ * collecting a human-readable warning for anything it had to correct.
+ */
+export declare function envReader(env: NodeJS.ProcessEnv, warnings: string[]): EnvReader;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,wBAAgB,WAAW,CAAC,GAAG,SAAgB,QAO9C;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;CACrF,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAwB/E"}

package/dist/config/env.js

@@ -0,0 +1,36 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function loadEnvFile(cwd = process.cwd()) {
+    const path = resolve(cwd, '.env');
+    if (!existsSync(path)) {
+        return;
+    }
+    // Real environment variables win over the file, same as `node --env-file`.
+    process.loadEnvFile(path);
+}
+/**
+ * Reads settings out of the environment, clamping numbers into range and
+ * collecting a human-readable warning for anything it had to correct.
+ */
+export function envReader(env, warnings) {
+    const read = (name) => env[name]?.trim() ?? '';
+    const number = (name, fallback, limits, round = true) => {
+        const raw = read(name);
+        if (!raw) {
+            return fallback;
+        }
+        const value = Number(raw);
+        if (!Number.isFinite(value)) {
+            warnings.push(`${name}=${raw} is not a number, using ${fallback}`);
+            return fallback;
+        }
+        const wanted = round ? Math.round(value) : value;
+        const clamped = Math.min(limits.max, Math.max(limits.min, wanted));
+        if (clamped !== value) {
+            warnings.push(`${name}=${raw} is out of range ${limits.min}..${limits.max}, using ${clamped}`);
+        }
+        return clamped;
+    };
+    return { read, number };
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,UAAU,WAAW,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IACD,2EAA2E;IAC3E,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAsB,EAAE,QAAkB;IAClE,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEvD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAE,MAAc,EAAE,KAAK,GAAG,IAAI,EAAE,EAAE;QAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,GAAG,2BAA2B,QAAQ,EAAE,CAAC,CAAC;YACnE,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QACnE,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,IAAI,GAAG,oBAAoB,MAAM,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,WAAW,OAAO,EAAE,CAChF,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export * from './env.js';
+export * from './bar.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,3 @@
+export * from './env.js';
+export * from './bar.js';
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC"}

package/dist/device.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Physical facts about the BUSY Bar screens. These are hardware, not app
+ * choices: every app draws into the same 72x16 front strip and 160x80 back
+ * panel. Per-app named slots (where the clock sits, how wide a hero column is)
+ * belong in the app's own layout module, spread on top of these.
+ */
+export declare const FRONT: {
+    readonly width: 72;
+    readonly height: 16;
+};
+export declare const BACK: {
+    readonly width: 160;
+    readonly height: 80;
+    readonly headerY: 2;
+    readonly subHeaderY: 9;
+    readonly firstRowY: 18;
+    readonly rowHeight: 12;
+    readonly maxRows: number;
+    readonly leftX: 2;
+    readonly rightX: 82;
+    readonly columnWidth: 76;
+};
+export type BarFont = 'tiny' | 'small' | 'bold';
+/**
+ * Upper bound per glyph. The device fonts may be narrower, so clipping is
+ * conservative: text can come out shorter than strictly necessary, never wider
+ * than its box.
+ */
+export declare const FONT_WIDTH: Record<BarFont, number>;
+export declare function textWidth(text: string, font: BarFont): number;
+export declare function clipToWidth(text: string, widthPx: number, font: BarFont, ellipsis?: string): string;
+export declare function fittingChars(widthPx: number, glyphWidth: number): number;
+export type RowGeometry = {
+    firstRowY: number;
+    rowHeight: number;
+};
+/** Top edge of back-panel row `index`. Apps with a different grid pass their own. */
+export declare function rowY(index: number, geometry?: RowGeometry): number;
+/**
+ * A back-panel row grid: how many rows of `rowHeight` fit below `firstRowY`.
+ * An app with a taller header (or none) starts its rows somewhere else.
+ */
+export declare function backRowGrid(firstRowY: number, rowHeight?: number, height?: number): {
+    readonly firstRowY: number;
+    readonly rowHeight: number;
+    readonly maxRows: number;
+};
+//# sourceMappingURL=device.d.ts.map

package/dist/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;CAGR,CAAC;AAMX,eAAO,MAAM,IAAI;;;;;;;;;;;CAWP,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAI9C,CAAC;AAEF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,UAEpD;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,QAAQ,SAAM,UAYf;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,UAE/D;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,qFAAqF;AACrF,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,WAAkB,UAE/D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAuB,EAClC,MAAM,GAAE,MAAoB;;;;EAO7B"}

package/dist/device.js

@@ -0,0 +1,67 @@
+/**
+ * Physical facts about the BUSY Bar screens. These are hardware, not app
+ * choices: every app draws into the same 72x16 front strip and 160x80 back
+ * panel. Per-app named slots (where the clock sits, how wide a hero column is)
+ * belong in the app's own layout module, spread on top of these.
+ */
+export const FRONT = {
+    width: 72,
+    height: 16,
+};
+const BACK_HEIGHT = 80;
+const BACK_FIRST_ROW_Y = 18;
+const BACK_ROW_HEIGHT = 12;
+export const BACK = {
+    width: 160,
+    height: BACK_HEIGHT,
+    headerY: 2,
+    subHeaderY: 9,
+    firstRowY: BACK_FIRST_ROW_Y,
+    rowHeight: BACK_ROW_HEIGHT,
+    maxRows: Math.floor((BACK_HEIGHT - BACK_FIRST_ROW_Y) / BACK_ROW_HEIGHT),
+    leftX: 2,
+    rightX: 82,
+    columnWidth: 76,
+};
+/**
+ * Upper bound per glyph. The device fonts may be narrower, so clipping is
+ * conservative: text can come out shorter than strictly necessary, never wider
+ * than its box.
+ */
+export const FONT_WIDTH = {
+    tiny: 4,
+    small: 4,
+    bold: 8,
+};
+export function textWidth(text, font) {
+    return text.length * FONT_WIDTH[font];
+}
+export function clipToWidth(text, widthPx, font, ellipsis = '.') {
+    const maxChars = Math.max(1, Math.floor(widthPx / FONT_WIDTH[font]));
+    if (text.length <= maxChars) {
+        return text;
+    }
+    if (maxChars <= 2 || maxChars <= ellipsis.length) {
+        return text.slice(0, maxChars);
+    }
+    return `${text.slice(0, maxChars - ellipsis.length)}${ellipsis}`;
+}
+export function fittingChars(widthPx, glyphWidth) {
+    return Math.max(0, Math.floor(widthPx / glyphWidth));
+}
+/** Top edge of back-panel row `index`. Apps with a different grid pass their own. */
+export function rowY(index, geometry = BACK) {
+    return geometry.firstRowY + index * geometry.rowHeight;
+}
+/**
+ * A back-panel row grid: how many rows of `rowHeight` fit below `firstRowY`.
+ * An app with a taller header (or none) starts its rows somewhere else.
+ */
+export function backRowGrid(firstRowY, rowHeight = BACK.rowHeight, height = BACK.height) {
+    return {
+        firstRowY,
+        rowHeight,
+        maxRows: Math.floor((height - firstRowY) / rowHeight),
+    };
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE;CACF,CAAC;AAEX,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,gBAAgB;IAC3B,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,GAAG,gBAAgB,CAAC,GAAG,eAAe,CAAC;IACvE,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,EAAE;IACV,WAAW,EAAE,EAAE;CACP,CAAC;AAIX;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAA4B;IACjD,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAa;IACnD,OAAO,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,OAAe,EACf,IAAa,EACb,QAAQ,GAAG,GAAG;IAEd,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrE,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,EAAE,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,UAAkB;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC;AACvD,CAAC;AAID,qFAAqF;AACrF,MAAM,UAAU,IAAI,CAAC,KAAa,EAAE,WAAwB,IAAI;IAC9D,OAAO,QAAQ,CAAC,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,SAAiB,EACjB,YAAoB,IAAI,CAAC,SAAS,EAClC,SAAiB,IAAI,CAAC,MAAM;IAE5B,OAAO;QACL,SAAS;QACT,SAAS;QACT,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;KAC7C,CAAC;AACb,CAAC"}

package/dist/elements.d.ts

@@ -0,0 +1,14 @@
+import type { RectangleElement, TextElement } from '@busy-app/busy-lib';
+export type AnyElement = TextElement | RectangleElement;
+/**
+ * A full-height coloured band across part of the front strip. Both Dota apps
+ * use one pair of these to show who is ahead.
+ */
+export declare function band(id: string, x: number, width: number, color: string, height?: number): RectangleElement;
+export declare const MIN_FILL = 6;
+/**
+ * Split a strip between two sides by `share` (0..1), always leaving both
+ * colours visible so the bar never reads as a single solid block.
+ */
+export declare function fillWidth(share: number, width?: number): number;
+//# sourceMappingURL=elements.d.ts.map

package/dist/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../src/elements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIxE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAExD;;;GAGG;AACH,wBAAgB,IAAI,CAClB,EAAE,EAAE,MAAM,EACV,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAqB,GAC5B,gBAAgB,CAgBlB;AAED,eAAO,MAAM,QAAQ,IAAI,CAAC;AAE1B;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAoB,UAInE"}

package/dist/elements.js

@@ -0,0 +1,33 @@
+import { BASE_COLORS } from './colors.js';
+import { FRONT } from './device.js';
+/**
+ * A full-height coloured band across part of the front strip. Both Dota apps
+ * use one pair of these to show who is ahead.
+ */
+export function band(id, x, width, color, height = FRONT.height) {
+    return {
+        id,
+        type: 'rectangle',
+        display: 'front',
+        align: 'top_left',
+        x,
+        y: 0,
+        width: Math.max(1, width),
+        height,
+        fill: 'solid',
+        fill_colors: [color],
+        border_width: 0,
+        border_color: BASE_COLORS.transparent,
+        timeout: 0,
+    };
+}
+export const MIN_FILL = 6;
+/**
+ * Split a strip between two sides by `share` (0..1), always leaving both
+ * colours visible so the bar never reads as a single solid block.
+ */
+export function fillWidth(share, width = FRONT.width) {
+    const raw = Math.round(Math.max(0, Math.min(1, share)) * width);
+    return Math.max(MIN_FILL, Math.min(width - MIN_FILL, raw));
+}
+//# sourceMappingURL=elements.js.map

package/dist/elements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.js","sourceRoot":"","sources":["../src/elements.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAIjC;;;GAGG;AACH,MAAM,UAAU,IAAI,CAClB,EAAU,EACV,CAAS,EACT,KAAa,EACb,KAAa,EACb,SAAiB,KAAK,CAAC,MAAM;IAE7B,OAAO;QACL,EAAE;QACF,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,UAAU;QACjB,CAAC;QACD,CAAC,EAAE,CAAC;QACJ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC;QACzB,MAAM;QACN,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,CAAC,KAAK,CAAC;QACpB,YAAY,EAAE,CAAC;QACf,YAAY,EAAE,WAAW,CAAC,WAAW;QACrC,OAAO,EAAE,CAAC;KACX,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC;AAE1B;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,QAAgB,KAAK,CAAC,KAAK;IAClE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IAEhE,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7D,CAAC"}