feat: harness time-lapse GIF capture for the sky-compass card (#114)

Add an npm run capture:timelapse script that drives the dev harness through a simulated day with Playwright and encodes the sky-compass card to an auto-looping GIF via ffmpeg, for the README and HACS panel (which strips <video>, so GIF auto-loops inline everywhere).

- harness: ?capture-gated window.__acpCapture bridge to step time deterministically
- script: scenario/time-span/format flags, compass-only framing, fixed-clip frames
- defaults: north-window preset, Sun Today chart, moon overlay, wide legend-right layout
- README: embed images/sky-compass-timelapse.gif + dev note

Author: jrhubott

.gitignore

@@ -2,6 +2,7 @@
 node_modules/
 *.tsbuildinfo
 harness/dist/
+.timelapse-frames/
 
 # editor / OS
 .vscode/*

README.md

@@ -96,6 +96,10 @@ Find your `entry_id` on the integration's URL:
 
 ## Screenshots
 
+**Sky compass — a full day in motion.** The standalone sky compass card across a simulated day: the sun rises, arcs through the window's field of view, and sets, while the cover-closure wedge tracks it. The dimmed disc is the sun below the horizon at night.
+
+![Sky compass — a day in motion](https://raw.githubusercontent.com/jrhubott/adaptive-cover-pro-card/main/images/sky-compass-timelapse.gif)
+
 **Tile card — five configurations stacked.** Same `custom:adaptive-cover-pro-tile-card` type; each tile reflects a different combination of `show_position`, `show_controls`, `show_badge`, and `show_resume`, plus the live winner-driven badge state (Auto / Manual countdown / etc.):
 
 ![Tile card configurations](https://raw.githubusercontent.com/jrhubott/adaptive-cover-pro-card/main/images/tile-card-variants.png)
@@ -115,6 +119,9 @@ npm run test      # vitest
 npm run lint
 ```
 
+The sky-compass demo GIF above is regenerated from the dev harness with
+`npm run capture:timelapse` (needs `npx playwright install chromium` once and `ffmpeg` on PATH; run `npm run capture:timelapse -- --help` for scenario/time-span/format options).
+
 ## Support
 
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/jrhubott)

harness/src/harness-app.ts

@@ -2,9 +2,11 @@ import { LitElement, css, html, type TemplateResult } from 'lit';
 import { customElement, state } from 'lit/decorators.js';
 import type { HomeAssistant } from 'custom-card-helpers';
 
+import type { LitElement as LitElementType } from 'lit';
+import { SKY_COMPASS_CARD_NAME } from '../../src/const';
 import { buildMockHass, type ServiceCallEvent } from './mock/hass';
 import { applyService, type ServiceCall } from './mock/services';
-import { defaultScenarioConfig, normalizeConfig } from './scenarios';
+import { defaultScenarioConfig, findScenario, normalizeConfig, SCENARIOS } from './scenarios';
 import { loadConfig, saveConfig } from './persistence';
 import { setFakeNow } from './fake-clock';
 import { zoneForLongitude, zonedNowMs } from './zone';
@@ -14,12 +16,46 @@ import {
   readStateFromUrl,
   writeStateToUrl,
 } from './share-state';
-import type { HarnessConfig } from './types';
+import type {
+  HarnessConfig,
+  RootCardOptions,
+  SkyCompassCardOptions,
+  TileCardOptions,
+} from './types';
 import type { ConfigChangeDetail } from './control-panel';
 import './control-panel';
 import './card-stage';
 import './service-log';
 
+/** A shallow-by-section partial of {@link HarnessConfig} accepted by the capture bridge. */
+export type CapturePartial = Partial<Omit<HarnessConfig, 'root' | 'compass' | 'tile'>> & {
+  root?: Partial<RootCardOptions>;
+  compass?: Partial<SkyCompassCardOptions>;
+  tile?: Partial<TileCardOptions>;
+};
+
+/**
+ * Programmatic hook the time-lapse capture script drives via Playwright. Only
+ * attached when the page URL carries a `?capture` param, so normal harness runs
+ * are untouched. See `scripts/capture-timelapse.mjs`.
+ */
+export interface CaptureBridge {
+  listScenarios(): { id: string; label: string }[];
+  loadScenario(id: string): Promise<void>;
+  setConfig(partial: CapturePartial): Promise<void>;
+  setMinutes(minutes: number): Promise<void>;
+}
+
+function mergeCaptureConfig(base: HarnessConfig, p: CapturePartial): HarnessConfig {
+  return {
+    ...base,
+    ...p,
+    root: { ...base.root, ...(p.root ?? {}) },
+    compass: { ...base.compass, ...(p.compass ?? {}) },
+    tile: { ...base.tile, ...(p.tile ?? {}) },
+  };
+}
+
 const MAX_LOG_ENTRIES = 200;
 
 @customElement('acp-harness-app')
@@ -40,6 +76,7 @@ export class AcpHarnessApp extends LitElement {
     super.connectedCallback();
     this._rebuildHass();
     this._applyTheme();
+    if (new URLSearchParams(location.search).has('capture')) this._installCaptureBridge();
   }
 
   disconnectedCallback(): void {
@@ -99,6 +136,50 @@ export class AcpHarnessApp extends LitElement {
     }
   }
 
+  /** Expose `window.__acpCapture` so the time-lapse script can step time deterministically. */
+  private _installCaptureBridge(): void {
+    this._clearPlayInterval();
+    const bridge: CaptureBridge = {
+      listScenarios: () => SCENARIOS.map((s) => ({ id: s.id, label: s.label })),
+      loadScenario: async (id) => {
+        const sc = findScenario(id);
+        if (!sc) throw new Error(`unknown scenario: ${id}`);
+        this._config = normalizeConfig({ ...sc.build(), playing: false });
+        await this._settle();
+      },
+      setConfig: async (partial) => {
+        this._config = mergeCaptureConfig(this._config, { ...partial, playing: false });
+        await this._settle();
+      },
+      setMinutes: async (minutes) => {
+        this._config = { ...this._config, timeOfDayMinutes: minutes, playing: false };
+        await this._settle();
+      },
+    };
+    (window as unknown as { __acpCapture: CaptureBridge }).__acpCapture = bridge;
+  }
+
+  /**
+   * Wait for the full render chain to settle. Setting `_config` triggers a hass
+   * rebuild in `updated()`, which schedules a *second* update — `updateComplete`
+   * resolves `false` while another update is pending, so drain those first, then
+   * await the nested card-stage and compass card, and finally a paint frame.
+   */
+  private async _settle(): Promise<void> {
+    for (let i = 0; i < 5; i++) {
+      if (await this.updateComplete) break;
+    }
+    const stage = this.renderRoot.querySelector('acp-harness-card-stage') as LitElementType | null;
+    if (stage) await stage.updateComplete;
+    const compass = stage?.renderRoot?.querySelector(
+      SKY_COMPASS_CARD_NAME,
+    ) as LitElementType | null;
+    if (compass?.updateComplete) await compass.updateComplete;
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+  }
+
   private _onServiceCall = (e: ServiceCallEvent): void => {
     const { next, applied } = applyService(this._config, e.domain, e.service, e.data, e.target);
     const entry: ServiceCall = {

images/sky-compass-timelapse.gif

@@ -31,7 +31,8 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"harness/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "capture:timelapse": "node scripts/capture-timelapse.mjs"
   },
   "dependencies": {
     "custom-card-helpers": "^2.0.0",
@@ -50,6 +51,7 @@
     "@typescript-eslint/parser": "^8.59.0",
     "eslint": "^10.2.1",
     "happy-dom": "^20.9.0",
+    "playwright": "^1.49.0",
     "prettier": "^3.3.2",
     "rollup": "^4.18.0",
     "rollup-plugin-livereload": "^2.0.5",