fuzzyworld

north-star / main_old / files / src / features / compass / compass.ts

Branch main_old · default branch · all branches

compass.ts

Blame: the commit that last changed each line · file · history

f32f5e95 2026-03-16 Pavel Safronov1import { normalizeAngle, normalizeSignedAngle } from '../../core/utils';
32796e53 2026-03-16 Pavel Safronov2import { PUBLIC_SETTINGS } from '../../public_settings';
f32f5e95 2026-03-16 Pavel Safronov3import { createToast } from '../../core/toast';
36d64b37 2026-03-15 Pavel Safronov4
b4e7f682 2026-03-16 Pavel Safronov5type CompassControllerOptions = {
6 calibrateHeadingLink: HTMLElement | null;
7 initialHeadingCorrectionDeg: number;
8 onHeadingCorrectionDegChange: (next: number) => void;
9 requestRender: () => void;
10};
11
12type CompassPermissionState = 'granted' | 'denied';
13
36d64b37 2026-03-15 Pavel Safronov14export const initCompassController = ({
15 calibrateHeadingLink,
16 initialHeadingCorrectionDeg,
17 onHeadingCorrectionDegChange,
18 requestRender
b4e7f682 2026-03-16 Pavel Safronov19}: CompassControllerOptions) => {
e790982a 2026-03-16 Pavel Safronov20 const HEADING_CORRECTION_STORAGE_KEY = 'friend-compass-heading-correction-deg';
f495a654 2026-03-16 Pavel Safronov21 const compassToast = createToast({ className: 'wake-lock-toast' });
92f24c4e 2026-03-16 Pavel Safronov22 const deviceOrientationCtor =
23 typeof DeviceOrientationEvent !== 'undefined'
b4e7f682 2026-03-16 Pavel Safronov24 ? (DeviceOrientationEvent as unknown as { requestPermission?: () => Promise<CompassPermissionState> })
92f24c4e 2026-03-16 Pavel Safronov25 : null;
36d64b37 2026-03-15 Pavel Safronov26
27 const requiresExplicitCompassPermission =
92f24c4e 2026-03-16 Pavel Safronov28 typeof deviceOrientationCtor?.requestPermission === 'function';
36d64b37 2026-03-15 Pavel Safronov29 const hasDeviceOrientationSupport = typeof DeviceOrientationEvent !== 'undefined';
30 const compassDefinitelyUnsupported = !hasDeviceOrientationSupport;
31
32 let headingCorrectionDeg = initialHeadingCorrectionDeg;
33 let selfHeading = 0;
b4e7f682 2026-03-16 Pavel Safronov34 let lastRawHeading: number | null = null;
36d64b37 2026-03-15 Pavel Safronov35
36 let compassEnabled = !requiresExplicitCompassPermission;
37 let hasSeenOrientationEvent = false;
38 let hasSeenHeadingValue = false;
39 let compassButtonStatusLabel = '';
40 let compassButtonStatusTitle = '';
41 let compassButtonStatusError = false;
b4e7f682 2026-03-16 Pavel Safronov42 let compassStatusTimer: number | null = null;
43 let compassProbeTimer: number | null = null;
36d64b37 2026-03-15 Pavel Safronov44 let hasAbsoluteOrientation = false;
45
46 const getHeadingUnavailableMessage = () => {
47 if (compassDefinitelyUnsupported) {
48 return 'This browser/device does not expose orientation sensors, so a compass is unavailable here.';
49 }
50
51 if (requiresExplicitCompassPermission && !compassEnabled) {
52 return 'Compass access is not enabled yet. Tap Enable Compass first.';
53 }
54
55 if (!hasSeenOrientationEvent) {
56 return 'No orientation sensor data has been detected on this device. This setup likely has no compass/motion sensor available (common on desktop/laptop hardware).';
57 }
58
59 if (!hasSeenHeadingValue) {
60 return 'Orientation events are arriving, but compass heading is unavailable in this browser/device context.';
61 }
62
63 return 'Heading sensor data is not ready yet. Try again in a moment.';
64 };
65
66 const getHeadingUnavailableStatus = () => {
67 if (compassDefinitelyUnsupported) {
68 return {
69 label: 'Compass Unavailable',
70 title: 'This browser/device does not expose orientation sensors, so a compass is unavailable here.',
71 isError: true
72 };
73 }
74
75 if (requiresExplicitCompassPermission && !compassEnabled) {
76 return {
77 label: 'Enable Compass First',
78 title: 'Compass access is not enabled yet. Tap Enable Compass first.',
79 isError: true
80 };
81 }
82
83 if (!hasSeenOrientationEvent) {
84 return {
85 label: 'No Sensor Data',
86 title: 'No orientation sensor data has been detected on this device. This setup likely has no compass/motion sensor available (common on desktop/laptop hardware).',
87 isError: true
88 };
89 }
90
91 if (!hasSeenHeadingValue) {
92 return {
93 label: 'Heading Unavailable',
94 title: 'Orientation events are arriving, but compass heading is unavailable in this browser/device context.',
95 isError: true
96 };
97 }
98
99 return {
100 label: 'Sensor Warming Up',
101 title: 'Heading sensor data is not ready yet. Try again in a moment.',
102 isError: false
103 };
104 };
105
106 const clearCompassButtonStatus = () => {
107 if (compassStatusTimer) {
108 clearTimeout(compassStatusTimer);
109 compassStatusTimer = null;
110 }
111
112 compassButtonStatusLabel = '';
113 compassButtonStatusTitle = '';
114 compassButtonStatusError = false;
115 };
116
117 const clearCompassProbeTimer = () => {
118 if (!compassProbeTimer) return;
119 clearTimeout(compassProbeTimer);
120 compassProbeTimer = null;
121 };
122
b4e7f682 2026-03-16 Pavel Safronov123 const showCompassButtonStatus = ({
124 label,
125 title = '',
126 isError = false,
127 durationMs = 0
128 }: {
129 label: string;
130 title?: string;
131 isError?: boolean;
132 durationMs?: number;
133 }) => {
36d64b37 2026-03-15 Pavel Safronov134 if (compassStatusTimer) {
135 clearTimeout(compassStatusTimer);
136 compassStatusTimer = null;
137 }
138
139 compassButtonStatusLabel = label;
140 compassButtonStatusTitle = title;
141 compassButtonStatusError = isError;
142
143 if (durationMs > 0) {
b4e7f682 2026-03-16 Pavel Safronov144 compassStatusTimer = window.setTimeout(() => {
36d64b37 2026-03-15 Pavel Safronov145 clearCompassButtonStatus();
146 updateCompassButtonState();
147 }, durationMs);
148 }
149
150 updateCompassButtonState();
151 };
152
153 const updateCompassButtonState = () => {
154 if (!calibrateHeadingLink) return;
155
156 if (compassDefinitelyUnsupported) {
157 calibrateHeadingLink.textContent = 'Compass Unavailable';
158 calibrateHeadingLink.classList.add('compass-required');
159 calibrateHeadingLink.classList.remove('compass-error');
160 calibrateHeadingLink.title = getHeadingUnavailableMessage();
b4e7f682 2026-03-16 Pavel Safronov161 (calibrateHeadingLink as HTMLButtonElement).disabled = true;
36d64b37 2026-03-15 Pavel Safronov162 return;
163 }
164
b4e7f682 2026-03-16 Pavel Safronov165 (calibrateHeadingLink as HTMLButtonElement).disabled = false;
36d64b37 2026-03-15 Pavel Safronov166 calibrateHeadingLink.textContent = compassButtonStatusLabel || (compassEnabled ? 'Calibrate North' : 'Enable Compass');
167 calibrateHeadingLink.title = compassButtonStatusTitle;
168 calibrateHeadingLink.classList.toggle('compass-required', !compassEnabled);
169 calibrateHeadingLink.classList.toggle('compass-error', compassButtonStatusError);
170 };
171
172 const scheduleCompassProbe = () => {
173 clearCompassProbeTimer();
174
175 if (compassDefinitelyUnsupported) return;
176 if (!compassEnabled) return;
177 if (hasSeenOrientationEvent || hasSeenHeadingValue) return;
178
b4e7f682 2026-03-16 Pavel Safronov179 compassProbeTimer = window.setTimeout(() => {
36d64b37 2026-03-15 Pavel Safronov180 if (hasSeenOrientationEvent || hasSeenHeadingValue) return;
181
182 const status = getHeadingUnavailableStatus();
183 showCompassButtonStatus({
184 label: status.label,
185 title: status.title,
186 isError: status.isError
187 });
9fda5271 2026-03-16 Pavel Safronov188 }, PUBLIC_SETTINGS.compass.probeTimeoutMs);
36d64b37 2026-03-15 Pavel Safronov189 };
190
191 const requestCompassPermission = async () => {
192 if (!requiresExplicitCompassPermission) {
193 return true;
194 }
195
196 try {
92f24c4e 2026-03-16 Pavel Safronov197 const permissionState = await deviceOrientationCtor?.requestPermission?.();
36d64b37 2026-03-15 Pavel Safronov198 return permissionState === 'granted';
199 } catch (err) {
200 console.error('Failed to request compass permission', err);
201 return false;
202 }
203 };
204
205 const getScreenOrientationAngle = () => {
206 if (window.screen?.orientation && typeof window.screen.orientation.angle === 'number') {
207 return window.screen.orientation.angle;
208 }
b4e7f682 2026-03-16 Pavel Safronov209 if (typeof (window as any).orientation === 'number') {
210 return (window as any).orientation as number;
36d64b37 2026-03-15 Pavel Safronov211 }
212 return 0;
213 };
214
b4e7f682 2026-03-16 Pavel Safronov215 const getHeadingFromEvent = (orientationEvent: DeviceOrientationEvent) => {
216 const webkitEvent = orientationEvent as DeviceOrientationEvent & { webkitCompassHeading?: number };
217 if (typeof webkitEvent.webkitCompassHeading === 'number') {
218 return normalizeAngle(webkitEvent.webkitCompassHeading);
36d64b37 2026-03-15 Pavel Safronov219 }
220
221 if (orientationEvent.alpha === null) {
222 return null;
223 }
224
225 const alphaHeading = normalizeAngle(360 - orientationEvent.alpha);
226 return normalizeAngle(alphaHeading + getScreenOrientationAngle());
227 };
228
229 updateCompassButtonState();
230 scheduleCompassProbe();
231
232 if (calibrateHeadingLink) {
b4e7f682 2026-03-16 Pavel Safronov233 calibrateHeadingLink.addEventListener('click', async (event: Event) => {
36d64b37 2026-03-15 Pavel Safronov234 event.preventDefault();
235
236 if (!compassEnabled) {
237 const granted = await requestCompassPermission();
238 if (!granted) {
239 showCompassButtonStatus({
240 label: 'Compass Denied',
241 title: 'Compass permission was denied. Enable Motion & Orientation Access in Safari settings and try again.',
242 isError: true
243 });
f495a654 2026-03-16 Pavel Safronov244 compassToast.show('Compass permission denied. Enable Motion & Orientation Access in browser settings.');
36d64b37 2026-03-15 Pavel Safronov245 return;
246 }
247
248 compassEnabled = true;
249 clearCompassButtonStatus();
250 updateCompassButtonState();
251 scheduleCompassProbe();
252 showCompassButtonStatus({
253 label: 'Compass Enabled',
254 title: 'Compass access is active. You can now calibrate north.',
255 durationMs: 1500
256 });
f495a654 2026-03-16 Pavel Safronov257 compassToast.show('Compass enabled. You can calibrate north now.');
36d64b37 2026-03-15 Pavel Safronov258 return;
259 }
260
261 if (lastRawHeading === null) {
262 const status = getHeadingUnavailableStatus();
263 showCompassButtonStatus({
264 label: status.label,
265 title: status.title,
266 isError: status.isError,
267 durationMs: status.isError ? 0 : 1500
268 });
f495a654 2026-03-16 Pavel Safronov269 compassToast.show(status.label);
36d64b37 2026-03-15 Pavel Safronov270 return;
271 }
272
273 headingCorrectionDeg = normalizeSignedAngle(-lastRawHeading);
274 localStorage.setItem(HEADING_CORRECTION_STORAGE_KEY, String(headingCorrectionDeg));
275 onHeadingCorrectionDegChange(headingCorrectionDeg);
276 selfHeading = normalizeAngle(lastRawHeading + headingCorrectionDeg);
277
278 showCompassButtonStatus({
279 label: 'North Calibrated',
280 title: 'Calibration applied.',
281 durationMs: 1500
282 });
f495a654 2026-03-16 Pavel Safronov283 compassToast.show('North calibrated.');
36d64b37 2026-03-15 Pavel Safronov284 requestRender();
285 });
286 }
287
b4e7f682 2026-03-16 Pavel Safronov288 window.addEventListener('deviceorientationabsolute', (event: DeviceOrientationEvent) => {
36d64b37 2026-03-15 Pavel Safronov289 clearCompassProbeTimer();
290 hasSeenOrientationEvent = true;
291 const heading = getHeadingFromEvent(event);
292 if (heading === null) return;
293
294 if (!compassEnabled) {
295 compassEnabled = true;
296 updateCompassButtonState();
297 }
298
299 hasSeenHeadingValue = true;
300 if (compassButtonStatusError) {
301 clearCompassButtonStatus();
302 updateCompassButtonState();
303 }
304
305 hasAbsoluteOrientation = true;
306 lastRawHeading = heading;
307 selfHeading = normalizeAngle(heading + headingCorrectionDeg);
308 requestRender();
309 });
310
b4e7f682 2026-03-16 Pavel Safronov311 window.addEventListener('deviceorientation', (event: DeviceOrientationEvent) => {
36d64b37 2026-03-15 Pavel Safronov312 if (hasAbsoluteOrientation) return;
313
314 clearCompassProbeTimer();
315 hasSeenOrientationEvent = true;
316
317 const heading = getHeadingFromEvent(event);
318 if (heading === null) return;
319
320 if (!compassEnabled) {
321 compassEnabled = true;
322 updateCompassButtonState();
323 }
324
325 hasSeenHeadingValue = true;
326 if (compassButtonStatusError) {
327 clearCompassButtonStatus();
328 updateCompassButtonState();
329 }
330
331 lastRawHeading = heading;
332 selfHeading = normalizeAngle(heading + headingCorrectionDeg);
333 requestRender();
334 });
335
336 return {
337 getSelfHeading: () => selfHeading,
338 scheduleCompassProbe
339 };
340};