keep-map-instrument-truthful

Fixes exception pulse parity and heading rendering bugs in MapLibre fleet map layers.

Updated Jul 9, 2026
One-click install
npx skills add https://github.com/shuddl/shuddl-os --skill keep-map-instrument-truthful-shuddl
Or copy as Structured Prompt for Agentâ–¼
Please help me install this Agent Skill.
Skill: keep-map-instrument-truthful
Source: https://github.com/shuddl/shuddl-os/tree/main/.claude/skills/keep-map-instrument-truthful
Command: npx skills add https://github.com/shuddl/shuddl-os --skill keep-map-instrument-truthful-shuddl

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? MapLibre fleet maps silently misrepresent ledger truth: exceptions on symbol-layer trucks never pulse, parked trucks snap to due-north headings, and high-latitude bearings skew east. This Skill encodes the laws and fixes that keep every rendered alarm and heading equal to the ledger record. ## Core Features & Use Cases - Exception-halo parity: Adds a kind-independent circle halo layer under every mark so exceptions throb on the 1.6s urgent sine whether the mark is a circle or a symbol. - Heading correctness: Prevents bearing overwrites from zero glide deltas and applies cos(latitude) correction to atan2 bearing math, with test vectors for regression. - Paint-only updates: Enforces setFeatureState/setPaintProperty for status changes instead of full setData re-renders, and routes cluster alarms through maxStatus properties. - Use Case: When adding a new EntityKind to entities.ts that can hold an exception, use this Skill to wire the halo filter, world-dim exemption, and reduced-motion frame so the new kind never renders dimmed-but-silent. ## Quick Start Ask the AI to review the truck exception pulse and heading logic in MapCanvas.tsx and entities.ts using this skill before editing the map layers.

Frequently Asked Questions about keep-map-instrument-truthful

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a MapLibre symbol layer pulse on exception status?â–¼

Feature-state is paint-only and cannot drive a symbol's icon-size layout property, so pulse a kind-independent circle halo layer drawn under every mark instead. Animate its circle-stroke-width and radius on the urgent sine in applyPulse.

Why does my MapLibre marker snap to north when it stops moving?â–¼

The animation loop recomputes bearing from the glide delta every frame, and a zero delta makes atan2(0,0) return 0, which is due north. Skip the bearing overwrite when the delta magnitude is below an epsilon so the ledger heading stays authoritative.

How do I calculate bearing correctly at high latitudes?â–¼

Scale the longitude delta by cos(latitude) before atan2: atan2(deltaLng * cos(lat), deltaLat). Omitting the correction overstates the east component, skewing a true 45-degree heading to about 63 degrees at 60 degrees north.

Can MapLibre feature-state drive layout properties like icon-rotate?â–¼

No. Feature-state only works with paint properties that support data-driven styling, not layout properties or filters. Mirror values like bearing and chip into feature properties and reference them with get expressions instead.

Why should status changes use setFeatureState instead of setData?â–¼

setData re-parses all geometry and drops feature-state, making a single status change O(all). setFeatureState is a paint-only O(1) update; reserve setData for throttled position and property flushes.

How do clusters show exception status without feature-state?â–¼

Clusters have no feature-state, so aggregate the alarm through a clusterProperties maxStatus property and gate paint with an equality expression on maxStatus. Leaves read a coalesce of feature-state and the statusStr property.