zx-kit 0.3.0 → 0.4.0

package/README.md

@@ -344,6 +344,131 @@ resetInput()  // discard any queued keypresses from the previous phase
 
 ---
 
+### `ui.ts` — ZX-style UI primitives
+
+High-level drawing helpers and a stateful widget system for HUD elements.
+All primitives operate in game pixels and enforce the Spectrum palette via `SpectrumColor`.
+
+#### Types
+
+**`BorderOptions`**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Set to `false` to suppress the border without removing the object |
+| `thickness` | `number` | `1` | Border thickness in pixels |
+| `color` | `SpectrumColor` | same as ink/color | Overrides the parent function's foreground color |
+| `style` | `'solid' \| 'dashed'` | `'solid'` | Solid = continuous lines; dashed = 2 px on / 2 px off |
+
+**`DrawProgressBarOptions`**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `id` | `string` | `"${x},${y}"` | Stable key for managed redraws |
+| `x` | `number` | — | Left edge in game pixels |
+| `y` | `number` | — | Top edge in game pixels |
+| `width` | `number` | — | Total width in game pixels (multiples of `CELL = 8` recommended) |
+| `value` | `number` | — | Current value |
+| `min` | `number` | `0` | Value at the left (empty) edge |
+| `max` | `number` | `1` | Value at the right (full) edge |
+| `ink` | `SpectrumColor` | `C.B_WHITE` | Filled-block color |
+| `paper` | `SpectrumColor` | `C.BLACK` | Empty-block background |
+| `border` | `BorderOptions` | — | Optional border around the bar |
+| `visibilityLength` | `number` | `500` | Ms to stay visible after last call; `0` = permanent |
+
+#### Stateless primitives
+
+##### `drawBox(ctx, options): void`
+
+Fills a rectangle with `paper` and draws an optional border.
+
+```ts
+drawBox(ctx, {
+  x: 8, y: 8, width: 112, height: 40,
+  paper: C.BLACK, ink: C.B_WHITE,
+  border: { style: 'solid', thickness: 1 },
+})
+```
+
+##### `drawFrame(ctx, options): void`
+
+Draws a border only — no background fill.
+
+```ts
+drawFrame(ctx, { x: 0, y: 0, width: 256, height: 176, color: C.B_CYAN })
+drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
+  border: { style: 'dashed' } })
+```
+
+##### `drawPanelTitle(ctx, options): void`
+
+Renders a text strip (height = `CELL + padding * 2`) with optional background fill.
+Does NOT draw the surrounding container — use `drawBox` / `drawFrame` separately.
+
+```ts
+drawBox(ctx, { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
+drawPanelTitle(ctx, {
+  text: 'OPTIONS', x: 8, y: 24,
+  ink: C.B_YELLOW, paper: C.BLACK,
+  centered: true, width: 128,
+})
+```
+
+#### Stateful widget — progress bar
+
+The progress bar is a managed widget: after a `drawProgressBar` call, the bar is
+re-rendered automatically on subsequent frames by `renderUI` until `visibilityLength`
+milliseconds have elapsed. Calling `drawProgressBar` again resets the timer.
+
+##### `drawProgressBar(ctx, options): void`
+
+Draws the bar immediately **and** registers it for managed redraws.
+
+```ts
+// On value change:
+drawProgressBar(ctx, {
+  id: 'volume', x: 88, y: 88, width: 80,
+  value: getMasterVolume(),
+  ink: C.B_GREEN, paper: C.BLACK,
+  border: { style: 'solid' },
+  visibilityLength: 1500,
+})
+
+// Permanent HUD element:
+drawProgressBar(ctx, {
+  id: 'health', x: 0, y: 184, width: 40,
+  value: lives, min: 0, max: 3,
+  ink: C.B_GREEN, paper: C.BLACK,
+  visibilityLength: 0,
+})
+```
+
+##### `tickUI(dtMs): void`
+
+Advances all managed bar timers. Expired bars are removed. Call once per frame.
+
+##### `renderUI(ctx): void`
+
+Redraws all currently visible bars. Call every frame **after** the game world render.
+
+##### `resetUI(): void`
+
+Clears all managed state. Call alongside `resetInput()` on phase transitions.
+
+```ts
+// Typical game loop:
+renderFrame(ctx, state)
+tickUI(dt)
+renderUI(ctx)
+
+// Phase transition:
+resetInput()
+resetUI()
+appPhase = 'intro'
+```
+
+---
+
 ## File structure
 
 ```
@@ -361,8 +486,11 @@ zx-kit/
 │   │                    # getAudioContext, getMasterGain,
 │   │                    # getMasterVolume, setMasterVolume,
 │   │                    # increaseVolume, decreaseVolume
-│   └── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
-│                        # isHeld, resetInput, Direction
+│   ├── input.ts         # initInput, tickMovement, consumeFlag/Debug/Pause/AnyKey,
+│   │                    # isHeld, resetInput, Direction
+│   └── ui.ts            # drawBox, drawFrame, drawPanelTitle,
+│                        # drawProgressBar, tickUI, renderUI, resetUI,
+│                        # BorderOptions, DrawProgressBarOptions
 └── dist/                # compiled output (generated by npm run build)
     ├── index.js / .d.ts
     └── ...

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './font.js';
 export * from './renderer.js';
 export * from './audio.js';
 export * from './input.js';
+export * from './ui.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA"}

package/dist/index.js

@@ -3,4 +3,5 @@ export * from './font.js';
 export * from './renderer.js';
 export * from './audio.js';
 export * from './input.js';
+export * from './ui.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA"}

package/dist/ui.d.ts

@@ -0,0 +1,231 @@
+import type { SpectrumColor } from './palette.js';
+/**
+ * Border configuration for UI primitives.
+ * When the `border` object is present on a parent option, a border is rendered.
+ * `enabled` defaults to `true` — set it to `false` to suppress the border
+ * while keeping the object in place for future toggling.
+ */
+export type BorderOptions = {
+    /** Enable/disable border rendering. Default: `true` */
+    enabled?: boolean;
+    /** Border thickness in pixels. Default: `1` */
+    thickness?: number;
+    /**
+     * Border color. Default: same as the primary `ink` / `color` of the parent function.
+     * Accepts any {@link SpectrumColor} value.
+     */
+    color?: SpectrumColor;
+    /**
+     * Border style.
+     * - `'solid'`  — continuous lines (default)
+     * - `'dashed'` — alternating 2 px on / 2 px off segments
+     */
+    style?: 'solid' | 'dashed';
+};
+/**
+ * Options for {@link drawProgressBar}.
+ */
+export type DrawProgressBarOptions = {
+    /**
+     * Stable key for managed-visibility mode.
+     * The bar's last-drawn state is registered under this key so `renderUI` can
+     * redraw it on subsequent frames. Defaults to `"${x},${y}"` when omitted.
+     */
+    id?: string;
+    /** Left edge of the bar in game pixels. */
+    x: number;
+    /** Top edge of the bar in game pixels. */
+    y: number;
+    /**
+     * Total width of the bar in game pixels.
+     * Should be a multiple of `CELL` (8) — any remainder is left blank.
+     */
+    width: number;
+    /** Current value to represent. */
+    value: number;
+    /** Minimum value (left edge = empty). Default: `0` */
+    min?: number;
+    /** Maximum value (right edge = full). Default: `1` */
+    max?: number;
+    /** Filled-block foreground color. Default: `C.B_WHITE` */
+    ink?: SpectrumColor;
+    /** Empty-block background color. Default: `C.BLACK` */
+    paper?: SpectrumColor;
+    /** Optional border around the entire bar. */
+    border?: BorderOptions;
+    /**
+     * How long the bar stays visible after the last `drawProgressBar` call (ms).
+     * - `> 0` — auto-hides after this many milliseconds.
+     * - `0`   — permanent; only cleared by `resetUI()`.
+     * Default: `500`
+     */
+    visibilityLength?: number;
+};
+/**
+ * Draws a filled rectangular box using ZX-style rendering.
+ *
+ * Renders a solid background (`paper`) and an optional border.
+ * Coordinates are in game pixels (already scaled by `setupCanvas`).
+ * Does NOT render text — use `drawPanelTitle` for labelled panels.
+ *
+ * @example
+ * drawBox(ctx, {
+ *   x: 8, y: 8, width: 112, height: 40,
+ *   paper: C.BLACK, ink: C.B_WHITE,
+ *   border: { style: 'solid', thickness: 1 },
+ * })
+ */
+export declare function drawBox(ctx: CanvasRenderingContext2D, options: {
+    /** Left edge in game pixels */
+    x: number;
+    /** Top edge in game pixels */
+    y: number;
+    /** Width in game pixels */
+    width: number;
+    /** Height in game pixels */
+    height: number;
+    /** Background fill color */
+    paper: SpectrumColor;
+    /** Foreground color — used as default border color when `border.color` is omitted */
+    ink?: SpectrumColor;
+    /** Optional border */
+    border?: BorderOptions;
+}): void;
+/**
+ * Draws a rectangular frame — border only, no background fill.
+ *
+ * Unlike `drawBox`, the inside area is left untouched.
+ * Useful for selection highlights, overlays, and ZX-style panels
+ * where the background is already painted.
+ *
+ * @example
+ * drawFrame(ctx, { x: 0, y: 0, width: 256, height: 176, color: C.B_CYAN })
+ * drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
+ *   border: { style: 'dashed', thickness: 1 } })
+ */
+export declare function drawFrame(ctx: CanvasRenderingContext2D, options: {
+    /** Left edge in game pixels */
+    x: number;
+    /** Top edge in game pixels */
+    y: number;
+    /** Width in game pixels */
+    width: number;
+    /** Height in game pixels */
+    height: number;
+    /** Frame color */
+    color: SpectrumColor;
+    /** Border configuration — `color` here overrides the top-level `color` */
+    border?: BorderOptions;
+}): void;
+/**
+ * Draws a ZX-style panel title — a text strip with an optional background fill.
+ *
+ * Does NOT draw the surrounding container (`drawBox` / `drawFrame` are separate).
+ * The strip height is always `CELL + padding * 2` pixels.
+ *
+ * @example
+ * // Labelled panel:
+ * drawBox(ctx,   { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
+ * drawPanelTitle(ctx, { text: 'OPTIONS', x: 8, y: 24, ink: C.B_YELLOW,
+ *   paper: C.BLACK, centered: true, width: 128 })
+ *
+ * // No background — ink only:
+ * drawPanelTitle(ctx, { text: 'DEBUG', x: 0, y: 0, ink: C.B_CYAN })
+ */
+export declare function drawPanelTitle(ctx: CanvasRenderingContext2D, options: {
+    /** Title text (ASCII — rendered via ZX ROM font) */
+    text: string;
+    /** Left edge in game pixels */
+    x: number;
+    /** Top edge of the title strip in game pixels */
+    y: number;
+    /** Text color */
+    ink: SpectrumColor;
+    /** Background behind the title strip. Omit for transparent (ink-only rendering) */
+    paper?: SpectrumColor;
+    /** Padding inside the strip in pixels. Default: `2` */
+    padding?: number;
+    /**
+     * Center the title horizontally within `width`.
+     * Requires `width` to be provided; ignored otherwise.
+     */
+    centered?: boolean;
+    /** Width used for centering (game pixels). Required when `centered: true`. */
+    width?: number;
+}): void;
+/**
+ * Draws a ZX-style progress / value bar and registers it for managed redraws.
+ *
+ * The bar is drawn **immediately** on every call. Additionally, the options are
+ * stored internally so `renderUI` can repaint the bar each frame for
+ * `visibilityLength` ms without requiring the caller to supply the state again.
+ *
+ * Calling `drawProgressBar` again with the same `id` **resets the timer** — use
+ * this to refresh the display when the value changes.
+ *
+ * **Typical pattern:**
+ * ```ts
+ * // On value change only:
+ * if (consumeVolUp()) {
+ *   increaseVolume()
+ *   drawProgressBar(ctx, { id: 'volume', x: 88, y: 88, width: 80,
+ *     value: getMasterVolume(), visibilityLength: 1500 })
+ * }
+ *
+ * // Every frame (after game world render):
+ * tickUI(dt)
+ * renderUI(ctx)
+ * ```
+ *
+ * @example
+ * // Permanent HUD health bar:
+ * drawProgressBar(ctx, {
+ *   id: 'health', x: 0, y: 184, width: 40, value: lives, min: 0, max: 3,
+ *   ink: C.B_GREEN, paper: C.BLACK, visibilityLength: 0,
+ * })
+ *
+ * // Temporary volume indicator (auto-hides after 1.5 s):
+ * drawProgressBar(ctx, {
+ *   id: 'volume', x: 88, y: 88, width: 80, value: getMasterVolume(),
+ *   ink: C.B_GREEN, paper: C.BLACK,
+ *   border: { style: 'solid' },
+ *   visibilityLength: 1500,
+ * })
+ */
+export declare function drawProgressBar(ctx: CanvasRenderingContext2D, options: DrawProgressBarOptions): void;
+/**
+ * Advances all managed bar timers by `dtMs` milliseconds.
+ * Bars whose timer reaches zero are removed and will no longer appear in `renderUI`.
+ * Call once per frame, typically just before `renderUI`.
+ *
+ * @param dtMs - Frame delta in milliseconds
+ *
+ * @example
+ * // End of game loop:
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export declare function tickUI(dtMs: number): void;
+/**
+ * Redraws all currently visible managed bars (timer > 0 or permanent).
+ * Call every frame **after** the game world has been rendered so bars appear on top.
+ *
+ * @param ctx - Canvas 2D rendering context
+ *
+ * @example
+ * renderFrame(ctx, state)
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export declare function renderUI(ctx: CanvasRenderingContext2D): void;
+/**
+ * Clears all managed UI state — removes every active bar timer and its stored options.
+ * Call alongside `resetInput()` when transitioning between major game phases.
+ *
+ * @example
+ * resetInput()
+ * resetUI()
+ * appPhase = 'intro'
+ */
+export declare function resetUI(): void;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

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

package/dist/ui.js

@@ -0,0 +1,210 @@
+import { C, CELL } from './palette.js';
+import { drawChar, drawText } from './renderer.js';
+const _bars = new Map();
+// ─── Private helpers ──────────────────────────────────────────────────────────
+function _drawBorder(ctx, x, y, width, height, border, fallbackColor) {
+    if (border.enabled === false)
+        return;
+    const color = border.color ?? fallbackColor;
+    const t = border.thickness ?? 1;
+    ctx.fillStyle = color;
+    if (border.style !== 'dashed') {
+        ctx.fillRect(x, y, width, t); // top
+        ctx.fillRect(x, y + height - t, width, t); // bottom
+        ctx.fillRect(x, y, t, height); // left
+        ctx.fillRect(x + width - t, y, t, height); // right
+    }
+    else {
+        const d = 2; // dash length in pixels
+        for (let i = 0; i < width; i += d * 2) {
+            ctx.fillRect(x + i, y, Math.min(d, width - i), t); // top
+            ctx.fillRect(x + i, y + height - t, Math.min(d, width - i), t); // bottom
+        }
+        for (let i = 0; i < height; i += d * 2) {
+            ctx.fillRect(x, y + i, t, Math.min(d, height - i)); // left
+            ctx.fillRect(x + width - t, y + i, t, Math.min(d, height - i)); // right
+        }
+    }
+}
+function _renderBar(ctx, o) {
+    const min = o.min ?? 0;
+    const max = o.max ?? 1;
+    const ink = o.ink ?? C.B_WHITE;
+    const paper = o.paper ?? C.BLACK;
+    const chars = Math.floor(o.width / CELL);
+    const ratio = Math.max(0, Math.min(1, (o.value - min) / (max - min)));
+    const filled = Math.round(ratio * chars);
+    ctx.fillStyle = paper;
+    ctx.fillRect(o.x, o.y, chars * CELL, CELL);
+    for (let i = 0; i < filled; i++) {
+        drawChar(ctx, 127, o.x + i * CELL, o.y, ink, paper); // 127 = solid block █
+    }
+    if (o.border)
+        _drawBorder(ctx, o.x, o.y, chars * CELL, CELL, o.border, ink);
+}
+// ─── Public API — stateless primitives ───────────────────────────────────────
+/**
+ * Draws a filled rectangular box using ZX-style rendering.
+ *
+ * Renders a solid background (`paper`) and an optional border.
+ * Coordinates are in game pixels (already scaled by `setupCanvas`).
+ * Does NOT render text — use `drawPanelTitle` for labelled panels.
+ *
+ * @example
+ * drawBox(ctx, {
+ *   x: 8, y: 8, width: 112, height: 40,
+ *   paper: C.BLACK, ink: C.B_WHITE,
+ *   border: { style: 'solid', thickness: 1 },
+ * })
+ */
+export function drawBox(ctx, options) {
+    const { x, y, width, height, paper, ink, border } = options;
+    ctx.fillStyle = paper;
+    ctx.fillRect(x, y, width, height);
+    if (border)
+        _drawBorder(ctx, x, y, width, height, border, ink ?? paper);
+}
+/**
+ * Draws a rectangular frame — border only, no background fill.
+ *
+ * Unlike `drawBox`, the inside area is left untouched.
+ * Useful for selection highlights, overlays, and ZX-style panels
+ * where the background is already painted.
+ *
+ * @example
+ * drawFrame(ctx, { x: 0, y: 0, width: 256, height: 176, color: C.B_CYAN })
+ * drawFrame(ctx, { x: 16, y: 16, width: 64, height: 32, color: C.B_RED,
+ *   border: { style: 'dashed', thickness: 1 } })
+ */
+export function drawFrame(ctx, options) {
+    const { x, y, width, height, color, border = {} } = options;
+    _drawBorder(ctx, x, y, width, height, { ...border, color }, color);
+}
+/**
+ * Draws a ZX-style panel title — a text strip with an optional background fill.
+ *
+ * Does NOT draw the surrounding container (`drawBox` / `drawFrame` are separate).
+ * The strip height is always `CELL + padding * 2` pixels.
+ *
+ * @example
+ * // Labelled panel:
+ * drawBox(ctx,   { x: 8, y: 24, width: 128, height: 56, paper: C.BLACK })
+ * drawPanelTitle(ctx, { text: 'OPTIONS', x: 8, y: 24, ink: C.B_YELLOW,
+ *   paper: C.BLACK, centered: true, width: 128 })
+ *
+ * // No background — ink only:
+ * drawPanelTitle(ctx, { text: 'DEBUG', x: 0, y: 0, ink: C.B_CYAN })
+ */
+export function drawPanelTitle(ctx, options) {
+    const { text, x, y, ink, paper, padding = 2, centered, width } = options;
+    const textW = text.length * CELL;
+    const stripW = centered && width !== undefined ? width : textW + padding * 2;
+    if (paper !== undefined) {
+        ctx.fillStyle = paper;
+        ctx.fillRect(x, y, stripW, CELL + padding * 2);
+    }
+    const tx = centered && width !== undefined
+        ? x + Math.floor((width - textW) / 2)
+        : x + padding;
+    drawText(ctx, text, tx, y + padding, ink, paper);
+}
+// ─── Public API — stateful widget ────────────────────────────────────────────
+/**
+ * Draws a ZX-style progress / value bar and registers it for managed redraws.
+ *
+ * The bar is drawn **immediately** on every call. Additionally, the options are
+ * stored internally so `renderUI` can repaint the bar each frame for
+ * `visibilityLength` ms without requiring the caller to supply the state again.
+ *
+ * Calling `drawProgressBar` again with the same `id` **resets the timer** — use
+ * this to refresh the display when the value changes.
+ *
+ * **Typical pattern:**
+ * ```ts
+ * // On value change only:
+ * if (consumeVolUp()) {
+ *   increaseVolume()
+ *   drawProgressBar(ctx, { id: 'volume', x: 88, y: 88, width: 80,
+ *     value: getMasterVolume(), visibilityLength: 1500 })
+ * }
+ *
+ * // Every frame (after game world render):
+ * tickUI(dt)
+ * renderUI(ctx)
+ * ```
+ *
+ * @example
+ * // Permanent HUD health bar:
+ * drawProgressBar(ctx, {
+ *   id: 'health', x: 0, y: 184, width: 40, value: lives, min: 0, max: 3,
+ *   ink: C.B_GREEN, paper: C.BLACK, visibilityLength: 0,
+ * })
+ *
+ * // Temporary volume indicator (auto-hides after 1.5 s):
+ * drawProgressBar(ctx, {
+ *   id: 'volume', x: 88, y: 88, width: 80, value: getMasterVolume(),
+ *   ink: C.B_GREEN, paper: C.BLACK,
+ *   border: { style: 'solid' },
+ *   visibilityLength: 1500,
+ * })
+ */
+export function drawProgressBar(ctx, options) {
+    _renderBar(ctx, options);
+    const id = options.id ?? `${options.x},${options.y}`;
+    const visibilityLength = options.visibilityLength ?? 500;
+    _bars.set(id, {
+        options,
+        timer: visibilityLength,
+        permanent: visibilityLength === 0,
+    });
+}
+/**
+ * Advances all managed bar timers by `dtMs` milliseconds.
+ * Bars whose timer reaches zero are removed and will no longer appear in `renderUI`.
+ * Call once per frame, typically just before `renderUI`.
+ *
+ * @param dtMs - Frame delta in milliseconds
+ *
+ * @example
+ * // End of game loop:
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export function tickUI(dtMs) {
+    for (const [id, bar] of _bars) {
+        if (bar.permanent)
+            continue;
+        bar.timer -= dtMs;
+        if (bar.timer <= 0)
+            _bars.delete(id);
+    }
+}
+/**
+ * Redraws all currently visible managed bars (timer > 0 or permanent).
+ * Call every frame **after** the game world has been rendered so bars appear on top.
+ *
+ * @param ctx - Canvas 2D rendering context
+ *
+ * @example
+ * renderFrame(ctx, state)
+ * tickUI(dt)
+ * renderUI(ctx)
+ */
+export function renderUI(ctx) {
+    for (const bar of _bars.values()) {
+        _renderBar(ctx, bar.options);
+    }
+}
+/**
+ * Clears all managed UI state — removes every active bar timer and its stored options.
+ * Call alongside `resetInput()` when transitioning between major game phases.
+ *
+ * @example
+ * resetInput()
+ * resetUI()
+ * appPhase = 'intro'
+ */
+export function resetUI() {
+    _bars.clear();
+}
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zx-kit",
-  "version": "0.3.0",
-  "description": "Reusable ZX Spectrum primitives: font, palette, renderer, audio, input",
+  "version": "0.4.0",
+  "description": "Reusable ZX Spectrum primitives: font, palette, renderer, audio, input, ui",
   "type": "module",
   "exports": {
     ".": {