test: regression tests for sky-compass N-wrap arc clamp (#89) (#95)

* test: regression tests for sky-compass N-wrap arc clamp (#89)

I confirmed v2.0.2's clampActiveArcToFov already handles the
wrap-through-north envelope with interior sunrise/sunset azimuths
correctly (the @an0Nym0us63 follow-up on #89 reads as a stale-client
issue, not a defect). These two tests lock the contract in place so
future refactors can't silently regress it.

Also includes a deterministic dist/ rebuild (56 bytes) — develop's
committed bundle was slightly out of sync with the source. Satisfies
the tests.yml dist-up-to-date gate.

* feat: add static-FOV underlay and developer test harness

Sky compass now renders a dimmed dashed wedge of the configured
windowAzi ± fov_left/right envelope beneath the active sun arc, so the
developer can see both at once. Skipped when the active arc already
covers the full envelope. Adds a committed harness/ workspace (lit + a
mock HomeAssistant layer driven by SunCalc) for reproducing card
renders without HA — including a share-state URL feature for handing
off broken states. CI now sanity-builds the harness and lint/format/
typecheck cover harness/ alongside src/ and tests/.

Author: jrhubott

.github/workflows/tests.yml

@@ -37,6 +37,12 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Build harness
+        # Sanity-build the developer test harness so the mock layer stays in
+        # sync with src/. Output (harness/dist/) is .gitignored — this step
+        # only verifies the build succeeds.
+        run: npm run build:harness
+
       - name: Verify dist/ is up to date
         run: |
           if [ -n "$(git status --porcelain dist/)" ]; then

.gitignore

@@ -1,6 +1,7 @@
 # build artifacts
 node_modules/
 *.tsbuildinfo
+harness/dist/
 
 # editor / OS
 .vscode/*

dist/adaptive-cover-pro-card.js

@@ -86,23 +86,27 @@ function e(e,t,s,o){var i,n=arguments.length,r=n<3?t:null===o?o=Object.getOwnPro
         ${this.showLegend?this._renderLegend(e,o):K}
         ${this.showStats?this._renderStats(e,o):K}
       </div>
-    `}_renderEntryLayers(e,t,s=0,o=[]){const i=Be(e.sun.window_azimuth),n=Be(i-e.sun.fov_left),r=Be(i+e.sun.fov_right),a=this._readActiveAzimuth(e.d.entities.start_sensor),l=this._readActiveAzimuth(e.d.entities.end_sensor),c=null!==a&&null!==l;let d,h;if(c)({wedgeStart:d,wedgeEnd:h}=function(e,t,s,o,i){const n=((s-o)%360+360)%360,r=o+i,a=((t-n)%360+360)%360,l=e=>e<=r?e:e-r<360-e?r:0,c=l(((e-n)%360+360)%360),d=l(a);return c===d?{wedgeStart:n,wedgeEnd:((n+r)%360+360)%360}:{wedgeStart:((n+Math.min(c,d))%360+360)%360,wedgeEnd:((n+Math.max(c,d))%360+360)%360}}(Be(a),Be(l),i,e.sun.fov_left,e.sun.fov_right));else{const t=function(e,t,s,o,i){if(void 0===i)return null;const n=Be(t-s),r=s+o,a=e.filter(e=>((e.azimuth-n)%360+360)%360<=r&&e.elevation>i);return 0===a.length?null:{wedgeStart:a[0].azimuth,wedgeEnd:a[a.length-1].azimuth}}(o,i,e.sun.fov_left,e.sun.fov_right,e.sun.min_elevation);d=t?t.wedgeStart:n,h=t?t.wedgeEnd:r}const p=je(i,ft,s),{outer:u,inner:_}=(m=e.sun.min_elevation,g=e.sun.max_elevation,v=ft,void 0!==m&&void 0!==g&&m>g?{outer:v,inner:0}:{outer:void 0!==m?v*He(m):v,inner:void 0!==g?v*He(g):0});var m,g,v;const f="cover_awning"===e.coverType?e.coverPos/100:1-e.coverPos/100,y=null!==e.coverPos?ft*f:null,b=null!==y?Math.min(y,u):null,$=e.sun.blind_spot_range?[Be((w=i)-(x=e.sun.blind_spot_range)[1]),Be(w-x[0])]:null;var w,x;const k=$?qe($[0],$[1],ft,0,s):null,C=qe(d,h,u,_,s),S=null!==b&&b>_?qe(d,h,b,_,s):"",A=t?`${e.d.entry_title}: `:"",E=void 0!==e.sun.min_elevation||void 0!==e.sun.max_elevation?De("compass.elev_suffix",this.hass,{min:ut(e.sun.min_elevation??0),max:ut(e.sun.max_elevation??90)}):"",z=c?`${A}${De("compass.active_sun_arc",this.hass,{from:ut(d),to:ut(h),elev:E})}`:`${A}${De("compass.fov_arc",this.hass,{left:ut(e.sun.fov_left),right:ut(e.sun.fov_right),elev:E})}`,P=`${A}${De("compass.window_normal_tooltip",this.hass,{bearing:ut(i)})}`,O=null!==e.coverPos?"cover_awning"===e.coverType?`${A}${De("compass.cover_extended",this.hass,{pct:e.coverPos})}`:`${A}${De("compass.cover_closed_tooltip",this.hass,{pct:e.coverPos})}`:"",T=$?`${A}${De("compass.blind_spot",this.hass,{from:ut($[0]),to:ut($[1])})}`:"",M=t||e.isOverride,I=M?`fill: ${e.color}; stroke: ${e.color};`:"",F=M?`fill: ${e.color}; stroke: ${e.color};`:"",N=M?`fill: ${e.color}; stroke: ${e.color};`:"",R=M?`stroke: ${e.color};`:"",D=M?`fill: ${e.color};`:"",L=this.showCoverFill&&""!==S,j=this.showBlindSpot&&!!k,H=this.showWindowArrow,q=`M 0 0 L ${p.x} ${p.y}`,U="display: none;";return W`<g class="entry-overlay">
-      <g data-tooltip=${z}>
-        <title>${z}</title>
-        <path class="fov" style=${I} d=${C}></path>
-      </g>
-      <g class="arrow-group" data-tooltip=${P} style=${H?"":U}>
-        <title>${P}</title>
-        <path class="window" style=${R} d=${q}></path>
-        <circle class="window-base" style=${D} cx="0" cy="0" r="4"></circle>
-      </g>
-      <g class="cover-group" data-tooltip=${O} style=${L?"":U}>
+    `}_renderEntryLayers(e,t,s=0,o=[]){const i=Be(e.sun.window_azimuth),n=Be(i-e.sun.fov_left),r=Be(i+e.sun.fov_right),a=this._readActiveAzimuth(e.d.entities.start_sensor),l=this._readActiveAzimuth(e.d.entities.end_sensor),c=null!==a&&null!==l;let d,h;if(c)({wedgeStart:d,wedgeEnd:h}=function(e,t,s,o,i){const n=((s-o)%360+360)%360,r=o+i,a=((t-n)%360+360)%360,l=e=>e<=r?e:e-r<360-e?r:0,c=l(((e-n)%360+360)%360),d=l(a);return c===d?{wedgeStart:n,wedgeEnd:((n+r)%360+360)%360}:{wedgeStart:((n+Math.min(c,d))%360+360)%360,wedgeEnd:((n+Math.max(c,d))%360+360)%360}}(Be(a),Be(l),i,e.sun.fov_left,e.sun.fov_right));else{const t=function(e,t,s,o,i){if(void 0===i)return null;const n=Be(t-s),r=s+o,a=e.filter(e=>((e.azimuth-n)%360+360)%360<=r&&e.elevation>i);return 0===a.length?null:{wedgeStart:a[0].azimuth,wedgeEnd:a[a.length-1].azimuth}}(o,i,e.sun.fov_left,e.sun.fov_right,e.sun.min_elevation);d=t?t.wedgeStart:n,h=t?t.wedgeEnd:r}const p=je(i,ft,s),{outer:u,inner:_}=(m=e.sun.min_elevation,g=e.sun.max_elevation,v=ft,void 0!==m&&void 0!==g&&m>g?{outer:v,inner:0}:{outer:void 0!==m?v*He(m):v,inner:void 0!==g?v*He(g):0});var m,g,v;const f="cover_awning"===e.coverType?e.coverPos/100:1-e.coverPos/100,y=null!==e.coverPos?ft*f:null,b=null!==y?Math.min(y,u):null,$=e.sun.blind_spot_range?[Be((w=i)-(x=e.sun.blind_spot_range)[1]),Be(w-x[0])]:null;var w,x;const k=$?qe($[0],$[1],ft,0,s):null,C=qe(d,h,u,_,s),S=c&&(d!==n||h!==r),A=S?qe(n,r,u,_,s):"",E=null!==b&&b>_?qe(d,h,b,_,s):"",z=t?`${e.d.entry_title}: `:"",P=void 0!==e.sun.min_elevation||void 0!==e.sun.max_elevation?De("compass.elev_suffix",this.hass,{min:ut(e.sun.min_elevation??0),max:ut(e.sun.max_elevation??90)}):"",O=c?`${z}${De("compass.active_sun_arc",this.hass,{from:ut(d),to:ut(h),elev:P})}`:`${z}${De("compass.fov_arc",this.hass,{left:ut(e.sun.fov_left),right:ut(e.sun.fov_right),elev:P})}`,T=`${z}${De("compass.window_normal_tooltip",this.hass,{bearing:ut(i)})}`,M=null!==e.coverPos?"cover_awning"===e.coverType?`${z}${De("compass.cover_extended",this.hass,{pct:e.coverPos})}`:`${z}${De("compass.cover_closed_tooltip",this.hass,{pct:e.coverPos})}`:"",I=$?`${z}${De("compass.blind_spot",this.hass,{from:ut($[0]),to:ut($[1])})}`:"",F=t||e.isOverride,N=F?`fill: ${e.color}; stroke: ${e.color};`:"",R=F?`fill: ${e.color}; stroke: ${e.color};`:"",D=F?`fill: ${e.color}; stroke: ${e.color};`:"",L=F?`stroke: ${e.color};`:"",j=F?`fill: ${e.color};`:"",H=this.showCoverFill&&""!==E,q=this.showBlindSpot&&!!k,U=this.showWindowArrow,B=`M 0 0 L ${p.x} ${p.y}`,V="display: none;",G=`${z}${De("compass.fov_arc",this.hass,{left:ut(e.sun.fov_left),right:ut(e.sun.fov_right),elev:P})}`;return W`<g class="entry-overlay">
+      ${S?W`<g data-tooltip=${G}>
+              <title>${G}</title>
+              <path class="fov fov-static" style=${N} d=${A}></path>
+            </g>`:K}
+      <g data-tooltip=${O}>
         <title>${O}</title>
-        <path class="cover-fill" style=${F} d=${S}></path>
+        <path class="fov" style=${N} d=${C}></path>
       </g>
-      <g class="blind-group" data-tooltip=${T} style=${j?"":U}>
+      <g class="arrow-group" data-tooltip=${T} style=${U?"":V}>
         <title>${T}</title>
-        <path class="blind-spot" style=${N} d=${k??""}></path>
+        <path class="window" style=${L} d=${B}></path>
+        <circle class="window-base" style=${j} cx="0" cy="0" r="4"></circle>
+      </g>
+      <g class="cover-group" data-tooltip=${M} style=${H?"":V}>
+        <title>${M}</title>
+        <path class="cover-fill" style=${R} d=${E}></path>
+      </g>
+      <g class="blind-group" data-tooltip=${I} style=${q?"":V}>
+        <title>${I}</title>
+        <path class="blind-spot" style=${D} d=${k??""}></path>
       </g>
     </g>`}_renderLegend(e,t){return t?B`
         <div class="legend">
@@ -232,6 +236,14 @@ function e(e,t,s,o){var i,n=arguments.length,r=n<3?t:null===o?o=Object.getOwnPro
       stroke-opacity: 0.7;
       transition: all 0.3s ease;
     }
+    /* Static FOV envelope shown dim beneath the active sun arc — lets the
+       reader see the configured ±fov_left/right span at the same time as
+       today's reachable sub-arc. */
+    .fov.fov-static {
+      fill-opacity: 0.07;
+      stroke-opacity: 0.25;
+      stroke-dasharray: 4 3;
+    }
     .cover-fill {
       fill: var(--primary-color);
       fill-opacity: 0.3;

eslint.config.js

@@ -1,10 +1,10 @@
 import tsPlugin from '@typescript-eslint/eslint-plugin';
 
 export default [
-  { ignores: ['dist/**', 'node_modules/**'] },
+  { ignores: ['dist/**', 'node_modules/**', 'harness/dist/**'] },
   ...tsPlugin.configs['flat/recommended'],
   {
-    files: ['src/**/*.ts', 'tests/**/*.ts'],
+    files: ['src/**/*.ts', 'tests/**/*.ts', 'harness/**/*.ts'],
     rules: {
       '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
       '@typescript-eslint/no-explicit-any': 'warn',

harness/harness.ts

@@ -0,0 +1,99 @@
+/**
+ * Harness entry point.
+ *
+ * 1. Defines minimal stubs for `ha-card`, `ha-icon`, `ha-svg-icon`, `ha-form`
+ *    so the cards' Lit templates can render outside Home Assistant.
+ * 2. Imports the cards from src/, which self-register their custom elements.
+ * 3. Imports the harness app shell.
+ *
+ * Order matters: define the polyfills BEFORE importing the cards so the
+ * cards see them at module-eval time.
+ */
+
+import * as mdi from '@mdi/js';
+
+// Build "mdi:foo" → SVG-path lookup from @mdi/js exports.
+const ICON_PATHS: Record<string, string> = {};
+for (const [k, v] of Object.entries(mdi)) {
+  if (k.startsWith('mdi') && typeof v === 'string') {
+    const slug = k
+      .replace(/^mdi/, '')
+      .replace(/([A-Z])/g, '-$1')
+      .toLowerCase()
+      .replace(/^-/, '');
+    ICON_PATHS[`mdi:${slug}`] = v;
+  }
+}
+
+class HaCard extends HTMLElement {
+  connectedCallback(): void {
+    this.style.display = 'block';
+  }
+}
+
+class HaIcon extends HTMLElement {
+  static observedAttributes = ['icon'];
+
+  attributeChangedCallback(): void {
+    this._render();
+  }
+
+  set icon(v: string) {
+    this.setAttribute('icon', v);
+  }
+  get icon(): string {
+    return this.getAttribute('icon') ?? '';
+  }
+
+  private _render(): void {
+    const name = this.getAttribute('icon') ?? '';
+    const path = ICON_PATHS[name];
+    if (!path) {
+      this.innerHTML = '';
+      return;
+    }
+    this.innerHTML = `<svg viewBox="0 0 24 24"><path d="${path}"></path></svg>`;
+  }
+}
+
+class HaSvgIcon extends HTMLElement {
+  static observedAttributes = ['path'];
+
+  attributeChangedCallback(): void {
+    this._render();
+  }
+
+  set path(v: string) {
+    this.setAttribute('path', v);
+  }
+  get path(): string {
+    return this.getAttribute('path') ?? '';
+  }
+
+  private _render(): void {
+    const path = this.getAttribute('path') ?? '';
+    if (!path) {
+      this.innerHTML = '';
+      return;
+    }
+    this.innerHTML = `<svg viewBox="0 0 24 24"><path d="${path}"></path></svg>`;
+  }
+}
+
+class HaFormStub extends HTMLElement {
+  // Editor cards aren't loaded in v1; this exists only so any incidental render
+  // doesn't blow up.
+}
+
+if (!customElements.get('ha-card')) customElements.define('ha-card', HaCard);
+if (!customElements.get('ha-icon')) customElements.define('ha-icon', HaIcon);
+if (!customElements.get('ha-svg-icon')) customElements.define('ha-svg-icon', HaSvgIcon);
+if (!customElements.get('ha-form')) customElements.define('ha-form', HaFormStub);
+
+// Cards self-register via @customElement decorator on import.
+import '../src/adaptive-cover-pro-card';
+import '../src/adaptive-cover-pro-sky-compass-card';
+import '../src/adaptive-cover-pro-tile-card';
+
+// Harness app shell.
+import './src/harness-app';

harness/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Adaptive Cover Pro — Card Test Harness</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <acp-harness-app></acp-harness-app>
+    <script type="module" src="./dist/harness.js"></script>
+  </body>
+</html>

harness/rollup.config.mjs

@@ -0,0 +1,25 @@
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import typescript from '@rollup/plugin-typescript';
+import serve from 'rollup-plugin-serve';
+import livereload from 'rollup-plugin-livereload';
+
+const watch = process.env.ROLLUP_WATCH === 'true';
+const port = parseInt(process.env.PORT ?? '8080', 10);
+
+export default {
+  input: 'harness/harness.ts',
+  output: {
+    file: 'harness/dist/harness.js',
+    format: 'es',
+    sourcemap: true,
+  },
+  moduleContext: (id) => (id.includes('@formatjs/intl-utils') ? 'window' : undefined),
+  plugins: [
+    resolve({ browser: true }),
+    commonjs(),
+    typescript({ tsconfig: './tsconfig.json', sourceMap: true, inlineSources: true }),
+    watch && serve({ contentBase: 'harness', port, host: '0.0.0.0' }),
+    watch && livereload({ watch: 'harness/dist' }),
+  ].filter(Boolean),
+};