Merge pull request #87 from jbeshir/agent/astrolabe-optional-sun-assist

Correct the historical front and rete orientation

Author: jbeshir

widgets/astrolabe-simulator/journey.json

@@ -8,7 +8,7 @@
       "label": "initial",
       "steps": [
         {
-          "eval": "(() => { const eclipticTicks = document.querySelectorAll('.astro-ecliptic-tick'); const limbTicks = document.querySelectorAll('.astro-limb-tick'); if (eclipticTicks.length !== 720 || !document.querySelector('[data-ecliptic-longitude=\"0.5\"]')) throw new Error(`front ecliptic is not graduated by half degrees (${eclipticTicks.length} ticks)`); if (document.querySelector('.astro-zodiac-label')) throw new Error('zodiac abbreviations remain on the front'); if (limbTicks.length !== 360 || !document.querySelector('[data-limb-degree=\"1\"]')) throw new Error(`front limb is not graduated by degrees (${limbTicks.length} ticks)`); const texture = document.querySelector('.astro-rete-edge-texture'); const filter = document.querySelector('#rete-edge-texture'); const textureStyle = texture && getComputedStyle(texture); if (!document.querySelector('.astro-rete-outer-rim') || !texture || !filter?.querySelector('feTurbulence') || textureStyle?.filter === 'none' || parseFloat(textureStyle?.strokeWidth || '0') < 18 || parseFloat(textureStyle?.opacity || '0') < 0.5) throw new Error('visible procedural rotating rete texture is missing'); })()"
+          "eval": "(() => { const eclipticTicks = document.querySelectorAll('.astro-ecliptic-tick'); const limbTicks = document.querySelectorAll('.astro-limb-tick'); if (eclipticTicks.length !== 720 || !document.querySelector('[data-ecliptic-longitude=\"0.5\"]')) throw new Error(`front ecliptic is not graduated by half degrees (${eclipticTicks.length} ticks)`); if (document.querySelector('.astro-zodiac-label')) throw new Error('zodiac abbreviations remain on the front'); if (limbTicks.length !== 360 || !document.querySelector('[data-limb-degree=\"1\"]')) throw new Error(`front limb is not graduated by degrees (${limbTicks.length} ticks)`); const texture = document.querySelector('.astro-rete-edge-texture'); const filter = document.querySelector('#rete-edge-texture'); const textureStyle = texture && getComputedStyle(texture); if (!document.querySelector('.astro-rete-outer-rim') || !texture || !filter?.querySelector('feTurbulence') || textureStyle?.filter === 'none' || parseFloat(textureStyle?.strokeWidth || '0') < 18 || parseFloat(textureStyle?.opacity || '0') < 0.5) throw new Error('visible procedural rotating rete texture is missing'); const assists = document.querySelector('[data-testid=layer-artificialAssists]'); if (!assists || assists.checked || document.querySelector('.astro-sun')) throw new Error('artificial Sun assist is not off by default'); })()"
         }
       ],
       "expect": { "state": "ready" }
@@ -25,7 +25,17 @@
           "eval": "new Promise((resolve) => { window.astrolabe.setRete(47); requestAnimationFrame(() => requestAnimationFrame(resolve)); })"
         },
         {
-          "eval": "(() => { const rete = document.querySelector('[aria-label=\"Rete rotation\"]'); const texture = document.querySelector('.astro-rete-edge-texture'); if (rete?.getAttribute('transform') !== 'rotate(47)' || !texture) throw new Error('rete texture did not rotate with the star-map layer'); })()"
+          "eval": "(() => { const rete = document.querySelector('[aria-label=\"Rete rotation\"]'); const texture = document.querySelector('.astro-rete-edge-texture'); if (rete?.getAttribute('aria-valuenow') !== '47' || !rete?.getAttribute('transform')?.startsWith('matrix(') || !texture) throw new Error('rete texture did not rotate with the star-map layer'); })()"
+        }
+      ],
+      "expect": { "state": "ready" }
+    },
+    {
+      "label": "enable-artificial-assists",
+      "steps": [
+        { "click": "[data-testid=layer-artificialAssists]" },
+        {
+          "eval": "(() => { if (!document.querySelector('.astro-sun')) throw new Error('calculated Sun assist did not appear'); if (new URLSearchParams(location.search).get('show') !== 'artificialAssists') throw new Error('enabled artificial assist was not preserved in the URL'); })()"
         }
       ],
       "expect": { "state": "ready" }
@@ -107,7 +117,7 @@
         },
         { "eval": "new Promise((resolve) => setTimeout(resolve, 900))" },
         {
-          "eval": "(() => { const heading = document.querySelector('#lesson-step-heading'); if (heading?.textContent !== 'Set the sky') throw new Error('sky-setting step missing before star reading'); if (document.body.textContent.includes('Locate Sirius')) throw new Error('star reading appeared before sky setting completed'); if (heading.hasAttribute('tabindex')) throw new Error('non-interactive lesson heading is focusable'); if (document.activeElement === heading) throw new Error('lesson heading received focus'); })()"
+          "eval": "(() => { const heading = document.querySelector('#lesson-step-heading'); if (heading?.textContent !== 'Set the sky') throw new Error('sky-setting step missing before star reading'); if (document.body.textContent.includes('Locate Sirius')) throw new Error('star reading appeared before sky setting completed'); if (document.body.textContent.includes('Sirius pointer')) throw new Error('lesson still calls Sirius a pointer'); if (heading.hasAttribute('tabindex')) throw new Error('non-interactive lesson heading is focusable'); if (document.activeElement === heading) throw new Error('lesson heading received focus'); const sirius = document.querySelector('[data-tutorial-target=\"front.star.sirius\"] .astro-star-dot'); const svg = sirius?.ownerSVGElement; if (!sirius || !svg) throw new Error('Sirius render target missing'); const star = new DOMPoint(Number(sirius.getAttribute('cx')), Number(sirius.getAttribute('cy'))).matrixTransform(sirius.getCTM()); const center = new DOMPoint(0, 0).matrixTransform(svg.getCTM()); if (star.x <= center.x) throw new Error(`Sirius rendered east of south instead of at azimuth about 191° (${star.x} <= ${center.x})`); })()"
         }
       ],
       "expect": { "state": "ready" }

widgets/astrolabe-simulator/src/components/Controls.tsx

@@ -7,6 +7,7 @@ type LayerControl = { key: keyof Visibility; label: string; description?: string
 const FRONT_LAYERS: LayerControl[] = [
   { key: 'almucantars', label: 'Altitude circles' }, { key: 'azimuths', label: 'Azimuths' },
   { key: 'unequalHours', label: 'Unequal hours' }, { key: 'ecliptic', label: 'Ecliptic' },
+  { key: 'artificialAssists', label: 'Artificial assists', description: 'Shows calculated markers that are not part of a historical astrolabe.' },
   { key: 'stars', label: 'Stars' }, { key: 'rule', label: 'Rule' },
 ];
 const BACK_LAYERS: LayerControl[] = [

widgets/astrolabe-simulator/src/components/Rete.tsx

@@ -2,7 +2,7 @@ import type { JSX } from 'preact';
 import { useRef, useState } from 'preact/hooks';
 import { solarLongitude } from '../astro';
 import { STARS } from '../data/stars';
-import { capricornRadius, eclipticCircle, eclipticPoint, project } from '../geometry';
+import { capricornRadius, eclipticCircle, eclipticPoint, project, reteOrientationMatrix } from '../geometry';
 import { setRete, useStore, type Visibility } from '../store';
 import { angleFromPointer, keyRotate, rotationDelta } from '../interaction';
 import { ASTROLABE_R } from './Plate';
@@ -21,8 +21,12 @@ const ECLIPTIC_LABELS = eclipticLabels().map((longitude) => ({
 }));
 const RETE_RIM = capricornRadius(ASTROLABE_R);
 
+function matrixTransform(rotation: number): string {
+  return `matrix(${reteOrientationMatrix(rotation).join(' ')} 0 0)`;
+}
+
 function uprightTransform(x: number, y: number, rotation: number): string {
-  return `translate(${x} ${y}) rotate(${-rotation}) scale(1,-1)`;
+  return `translate(${x} ${y}) ${matrixTransform(rotation)} scale(1,-1)`;
 }
 
 export function Rete({ reteRotation, visibility }: ReteProps): JSX.Element {
@@ -44,7 +48,7 @@ export function Rete({ reteRotation, visibility }: ReteProps): JSX.Element {
     <g
       data-tutorial-target="front.rete"
       className={`astro-rotary${dragging ? ' is-dragging' : ''}`}
-      transform={`rotate(${reteRotation})`}
+      transform={matrixTransform(reteRotation)}
       tabIndex={0}
       role="slider"
       aria-label="Rete rotation"
@@ -64,7 +68,7 @@ export function Rete({ reteRotation, visibility }: ReteProps): JSX.Element {
         const start = drag.current;
         const svg = event.currentTarget.ownerSVGElement;
         if (!start || start.pointerId !== event.pointerId || !svg) return;
-        setRete(start.rotation + rotationDelta(start.pointerAngle, angleFromPointer(svg, event.clientX, event.clientY)));
+        setRete(start.rotation - rotationDelta(start.pointerAngle, angleFromPointer(svg, event.clientX, event.clientY)));
       }}
       onPointerUp={endDrag}
       onPointerCancel={endDrag}
@@ -101,7 +105,7 @@ export function Rete({ reteRotation, visibility }: ReteProps): JSX.Element {
       <circle className="astro-rotary-hit" r={rim} />
       <circle className="astro-rete-outer-rim" r={RETE_RIM} aria-label="Outer frame of the rete" />
       <circle className="astro-rete-edge-texture" r={RETE_RIM - 10} aria-hidden="true" />
-      {visibility.ecliptic && <g clip-path="url(#plate-clip)" aria-label="Ecliptic longitude scale, graduated every half degree">
+      {visibility.ecliptic && <g clip-path="url(#plate-clip)" aria-label="Ecliptic longitude scale, graduated every half degree" data-tutorial-target="front.ecliptic">
         <circle className="astro-rete-ring" cx={ecliptic.cx} cy={ecliptic.cy} r={ecliptic.r} />
         <circle className="astro-rete-thin" cx={ecliptic.cx} cy={ecliptic.cy} r={ecliptic.r - 14} />
         {ECLIPTIC_TICKS.map((tick) =>
@@ -112,10 +116,10 @@ export function Rete({ reteRotation, visibility }: ReteProps): JSX.Element {
             <text className="astro-ecliptic-degree-label" text-anchor="middle" dominant-baseline="middle">{longitude}°</text>
           </g>;
         })}
-        <g data-tutorial-target="front.sun">
-          <circle className="astro-sun" cx={sun.x} cy={sun.y} r={9} />
-          <circle cx={sun.x} cy={sun.y} r={3} fill="var(--astro-mater-fill)" />
-        </g>
+      </g>}
+      {visibility.artificialAssists && <g clip-path="url(#plate-clip)" aria-label="Artificial calculated assists">
+        <circle className="astro-sun" cx={sun.x} cy={sun.y} r={9} aria-label="Calculated Sun position" />
+        <circle cx={sun.x} cy={sun.y} r={3} fill="var(--astro-mater-fill)" />
       </g>}
 
       {visibility.stars && <g clip-path="url(#plate-clip)">

widgets/astrolabe-simulator/src/geometry.ts

@@ -180,6 +180,26 @@ export function project(angleDeg: number, decDeg: number, R: number): ProjectedP
   };
 }
 
+/**
+ * Orient a catalogue point on the rete for local sidereal angle θ.
+ *
+ * The engraved catalogue angle is right ascension α, while the fixed plate
+ * reads local hour angle H = θ − α. This is a reflection followed by a
+ * rotation, not an ordinary rotation of the SVG's RA coordinates.
+ */
+export function orientRetePoint(point: Point, siderealDeg: number): Point {
+  const sidereal = deg2rad(siderealDeg);
+  return {
+    x: -Math.cos(sidereal) * point.x + Math.sin(sidereal) * point.y,
+    y: Math.sin(sidereal) * point.x + Math.cos(sidereal) * point.y,
+  };
+}
+
+export function reteOrientationMatrix(siderealDeg: number): [number, number, number, number] {
+  const sidereal = deg2rad(siderealDeg);
+  return [-Math.cos(sidereal), Math.sin(sidereal), Math.sin(sidereal), Math.cos(sidereal)];
+}
+
 /**
  * Project a local horizontal-coordinate point onto the plate. Azimuth is
  * measured conventionally clockwise from north. This is useful for locating

widgets/astrolabe-simulator/src/knownObservation.test.ts

@@ -2,10 +2,11 @@ import { describe, expect, it } from 'vitest';
 import {
   equatorialToHorizontal,
   greenwichSiderealTime,
+  localSiderealTime,
   raDegFromHMS,
   solarLongitude,
 } from './astro';
-import { project, projectHorizontal, rOfDec } from './geometry';
+import { orientRetePoint, project, projectHorizontal, rOfDec } from './geometry';
 import { STARS } from './data/stars';
 
 /**
@@ -77,3 +78,52 @@ describe('externally verified Aldebaran observation', () => {
     expect(platePoint.y).toBeCloseTo(retePoint.y, 9);
   });
 });
+
+/**
+ * Sirius reference:
+ *   SIMBAD ICRS/J2000: 06 45 08.91728, −16 42 58.0171
+ *   https://simbad.u-strasbg.fr/simbad/sim-basic?Ident=sirius
+ *
+ * Astropy 8.0.1 ICRS → AltAz at 2026-07-14T12:00:00Z for
+ * 51.5° N, 0.12° W, pressure=0 gives altitude 21.1228204159° and
+ * azimuth 190.9588941942° clockwise from north:
+ * https://docs.astropy.org/en/stable/coordinates/index.html
+ *
+ * This astrolabe intentionally holds J2000 catalogue coordinates fixed, so
+ * its simpler result differs by about 0.30° in azimuth at this date.
+ */
+describe('externally verified Sirius lesson observation', () => {
+  const date = new Date('2026-07-14T12:00:00Z');
+  const latitude = 51.5;
+  const longitude = -0.12;
+  const sirius = {
+    ra: raDegFromHMS(6, 45, 8.91728),
+    dec: -(16 + 42 / 60 + 58.0171 / 3600),
+  };
+  const astropy = { altitude: 21.1228204159, azimuth: 190.9588941942 };
+
+  it('keeps the rete catalogue consistent with SIMBAD', () => {
+    const catalogue = STARS.find((star) => star.name === 'Sirius');
+    expect(catalogue).toBeDefined();
+    expect(catalogue!.raDeg).toBeCloseTo(sirius.ra, 3);
+    expect(catalogue!.decDeg).toBeCloseTo(sirius.dec, 3);
+  });
+
+  it('agrees with the trusted apparent AltAz calculation within fixed-J2000 model accuracy', () => {
+    const sidereal = localSiderealTime(date, longitude);
+    const observation = equatorialToHorizontal(sirius.ra, sirius.dec, latitude, sidereal);
+    expect(observation.altitude).toBeCloseTo(astropy.altitude, 1);
+    expect(Math.abs(observation.azimuth - astropy.azimuth)).toBeLessThan(0.35);
+    expect(observation.azimuth).toBeGreaterThan(180);
+  });
+
+  it('renders Sirius at the same altitude and azimuth grid intersection', () => {
+    const sidereal = localSiderealTime(date, longitude);
+    const observation = equatorialToHorizontal(sirius.ra, sirius.dec, latitude, sidereal);
+    const renderedStar = orientRetePoint(project(sirius.ra, sirius.dec, RADIUS), sidereal);
+    const platePoint = projectHorizontal(latitude, observation.altitude, observation.azimuth, RADIUS);
+
+    expect(renderedStar.x).toBeCloseTo(platePoint.x, 9);
+    expect(renderedStar.y).toBeCloseTo(platePoint.y, 9);
+  });
+});

widgets/astrolabe-simulator/src/store.ts

@@ -24,6 +24,7 @@ export interface Visibility {
   azimuths: boolean;
   unequalHours: boolean;
   ecliptic: boolean;
+  artificialAssists: boolean;
   stars: boolean;
   rule: boolean;
   tropics: boolean;
@@ -77,6 +78,7 @@ function defaultState(): AstrolabeState {
       azimuths: true,
       unequalHours: true,
       ecliptic: true,
+      artificialAssists: false,
       stars: true,
       rule: true,
       tropics: true,

widgets/astrolabe-simulator/src/tutorial/catalog.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { eclipticPoint, project } from '../geometry';
+import { eclipticPoint, orientRetePoint, project } from '../geometry';
 import { alidadeLineCross, backLongitudePoint } from '../backGeometry';
 import { FUTURE_TOPICS, LESSONS, SIRIUS_FIXTURE, SUN_FIXTURE, validateCatalog } from './catalog';
 
@@ -20,29 +20,23 @@ describe('tutorial catalog', () => {
   });
   it('derives a Sirius fixture whose rule, rete, and altitude agree', () => {
     const star = project(SIRIUS_FIXTURE.star.raDeg, SIRIUS_FIXTURE.star.decDeg, 380);
-    const rete = SIRIUS_FIXTURE.reteRotation * Math.PI / 180;
-    const transformed = {
-      x: star.x * Math.cos(rete) - star.y * Math.sin(rete),
-      y: star.x * Math.sin(rete) + star.y * Math.cos(rete),
-    };
+    const transformed = orientRetePoint(star, SIRIUS_FIXTURE.reteRotation);
     const rule = SIRIUS_FIXTURE.ruleRotation * Math.PI / 180;
     expect(transformed.x * Math.cos(rule) + transformed.y * Math.sin(rule)).toBeCloseTo(0, 8);
     expect(SIRIUS_FIXTURE.altitude).toBeCloseTo(21.1142782184, 8);
     expect(LESSONS[1].steps.at(-1)?.result).toContain(`approximately ${SIRIUS_FIXTURE.altitude.toFixed(1)}°`);
   });
   it('sets the sky by aligning the dated Sun point with the time rule', () => {
     const sun = eclipticPoint(SUN_FIXTURE.eclipticLongitude, 380);
-    const rete = SUN_FIXTURE.reteRotation * Math.PI / 180;
-    const transformed = {
-      x: sun.x * Math.cos(rete) - sun.y * Math.sin(rete),
-      y: sun.x * Math.sin(rete) + sun.y * Math.cos(rete),
-    };
+    const transformed = orientRetePoint(sun, SUN_FIXTURE.reteRotation);
     const rule = SUN_FIXTURE.ruleRotation * Math.PI / 180;
     expect(transformed.x * Math.cos(rule) + transformed.y * Math.sin(rule)).toBeCloseTo(0, 8);
     const lessonCopy = LESSONS[1].steps.map((item) => `${item.title} ${item.body}`).join(' ');
     expect(lessonCopy).not.toMatch(/prepared/i);
+    expect(lessonCopy).not.toMatch(/Sun marker|Sirius pointer|pointer shows/i);
     expect(lessonCopy).toMatch(/calendar.+ecliptic longitude.+rule.+rotate the rete/is);
     expect(lessonCopy).toMatch(/inner edge.+across the zodiac-sign band.+outer side/is);
+    expect(LESSONS[1].steps.every((step) => !step.snapshot.visibility.artificialAssists)).toBe(true);
   });
   it('aligns the lesson alidade with the dated back-scale radial', () => {
     const datePoint = backLongitudePoint(456, SUN_FIXTURE.eclipticLongitude);