atc: How We Built a Live Air Traffic Map You Can Talk To

atc/
  shared/        Framework-free TypeScript used by both apps and the server
    src/aircraft.ts      adsb.lol to Aircraft (validation, privacy whitelist)
    src/store.ts         AtcState and pure reducers; the one source of truth
    src/tools.ts         The browser-side tools the model calls
    src/find-aircraft.ts The query behind the findAircraft tool
    src/contracts.ts     Component contracts (Skillet schemas) and the system prompt
    src/views.ts         Pure view models for the UI
    src/map/             Leaflet map, detail card, follow pill (no framework)
  angular/  react/       Thin shells: components and the core file
  server/                /api/run and /api/aircraft
  e2e/                   Playwright against both apps with a mocked model

/**
 * How long a fetched snapshot is served without calling adsb.lol again.
 * adsb.lol answers 429 to a 250 nm query every 3-5 s from one IP; every 10 s
 * is sustainable.
 */
const FRESH_MS = 10_000;
/** How old a snapshot may be and still stand in when adsb.lol fails. */
const STALE_LIMIT_MS = 60_000;
/** How long to leave adsb.lol alone after it answers 429. */
const COOLDOWN_MS = 15_000;
const CACHE_CONTROL = 'public, s-maxage=3, stale-while-revalidate=5';

/** What the handler remembers about one area. Replaced, never mutated. */
interface AreaCache {
  readonly last: {
    readonly snapshot: AircraftSnapshot;
    readonly at: number;
  } | null;
  readonly inFlight: Promise<AircraftSnapshot> | null;
  readonly coolUntil: number;
}

const load = async (
  area: AreaId,
): Promise<{ snapshot: AircraftSnapshot; stale: boolean } | null> => {
  const { last, coolUntil } = cacheFor(area);
  if (last && now() - last.at < FRESH_MS) {
    return { snapshot: last.snapshot, stale: false };
  }
  if (now() >= coolUntil) {
    try {
      return { snapshot: await refresh(area), stale: false };
    } catch {
      // Fall back to the last good snapshot below.
    }
  }
  const fallback = cacheFor(area).last;

  return fallback && now() - fallback.at <= STALE_LIMIT_MS
    ? { snapshot: fallback.snapshot, stale: true }
    : null;
};

// SECURITY INVARIANT: hex codes, labels and kinds are interpolated into
// marker innerHTML (map/plane-marker.ts planeIconHtml). Widening HEX or LABEL,
// or interpolating typeCode, description or registration there, is an XSS bug.
const HEX = /^[0-9a-f]{6}$/;
const AIRLINE_CALLSIGN = /^[A-Z]{3}\d[A-Z0-9]{0,4}$/;
const LABEL = /^[A-Z0-9]{1,8}$/;
const REGISTRATION = /^[A-Z0-9](?:[A-Z0-9-]{0,8}[A-Z0-9])?$/;

function normalizeEntry(entry: unknown): Aircraft | null {
  if (!isRecord(entry)) {
    return null;
  }
  const hex =
    typeof entry['hex'] === 'string' ? entry['hex'].toLowerCase() : '';
  const flight = upper(entry['flight']);
  const callsign = isLabel(flight) ? flight : null;
  const r = upper(entry['r']);
  const registration = isRegistration(r) ? r : null;
  const lat = numberOrNull(entry['lat']);
  const lon = numberOrNull(entry['lon']);
  if (!HEX.test(hex) || lat === null || lon === null) {
    return null;
  }
  // ...

  return {
    hex,
    label: displayLabel({ hex, callsign, registration }),
    callsign,
    registration,
    typeCode,
    category,
    kind: aircraftKind({ typeCode, category }),
    lat,
    lon,
    altitudeFt: typeof altitude === 'number' ? Math.round(altitude) : null,
    onGround: altitude === 'ground',
    groundSpeedKt: numberWhere(entry['gs'], isSpeed),
    trackDeg: numberWhere(entry['track'], isDegrees),
    // ...
  };
}

const tick = async () => {
  try {
    const { snapshot, stale } = await load();
    if (stopped) {
      return;
    }
    store.applySnapshot(snapshot);
    if (!stale) {
      lastSuccessAt = now();
    }
    store.setFeedStatus(stale ? 'delayed' : 'live');
  } catch {
    if (stopped) {
      return;
    }
    const silentFor = now() - (lastSuccessAt ?? startedAt);
    if (silentFor >= stalledAfterMs) {
      store.setFeedStatus('stalled');
    } else if (silentFor >= delayedAfterMs) {
      store.setFeedStatus('delayed');
    }
  }
  if (!stopped) {
    timer = setTimeout(() => void tick(), intervalMs);
  }
};

/** Everything the map, tools and components read. Treat as immutable. */
export interface AtcState {
  readonly aircraft: ReadonlyMap<string, Aircraft>;
  /** Aircraft that left the area in the last {@link DEPARTED_TTL_MS}. */
  readonly departed: ReadonlyMap<string, DepartedAircraft>;
  readonly routes: ReadonlyMap<string, Route | null>;
  readonly selectedHex: string | null;
  readonly highlighted: ReadonlySet<string>;
  readonly followingHex: string | null;
  readonly pulse: { readonly hex: string; readonly at: number } | null;
  readonly feedStatus: FeedStatus;
  readonly updatedAt: number | null;
  /** The area the map outlines, or null. */
  readonly shownArea: ShownArea | null;
  /** The newest map move, or null when there is nothing to do. */
  readonly viewRequest: ViewRequest | null;
  /** The last `seq` handed out. */
  readonly viewSeq: number;
}

export function applySnapshot(
  state: AtcState,
  snapshot: AircraftSnapshot,
): AtcState {
  if (state.updatedAt !== null && snapshot.at <= state.updatedAt) {
    return state;
  }
  const aircraft = new Map(
    snapshot.aircraft.map((entry) => [entry.hex, entry] as const),
  );
  const departed = new Map(
    [...state.departed].filter(
      ([hex, gone]) =>
        !aircraft.has(hex) && gone.lastSeenAt >= snapshot.at - DEPARTED_TTL_MS,
    ),
  );
  for (const [hex, previous] of state.aircraft) {
    if (!aircraft.has(hex)) {
      departed.set(hex, {
        aircraft: previous,
        lastSeenAt: state.updatedAt ?? snapshot.at,
      });
    }
  }

  return { ...state, aircraft, departed, updatedAt: snapshot.at };
}

/**
 * A pending map move: a highlight fit, an area, a reset to the home view,
 * or bringing one aircraft into view. Precedence: (1) follow mode always wins
 * and drops requests; (2) the newest request (highest `seq`) wins; (3) a user
 * drag or zoom cancels a pending one; (4) highlight and aircraft requests
 * wait for their markers to be drawn. The map applies each `seq` once.
 */
export type ViewRequest =
  | { readonly seq: number; readonly kind: 'highlight' }
  | { readonly seq: number; readonly kind: 'area'; readonly area: ShownArea }
  | { readonly seq: number; readonly kind: 'reset' }
  | { readonly seq: number; readonly kind: 'aircraft'; readonly hex: string };

export const ATC_STATE = new InjectionToken<Signal<AtcState>>('ATC_STATE', {
  providedIn: 'root',
  factory: () => {
    const store = inject(ATC_STORE);
    const state = signal(store.getState());
    inject(DestroyRef).onDestroy(
      store.subscribe(() => state.set(store.getState())),
    );

    return state.asReadonly();
  },
});

/** The current atc state as a signal. Call in an injection context. */
export function injectAtcState(): Signal<AtcState> {
  return inject(ATC_STATE);
}

/** The current atc state; re-renders on every store change. */
export function useAtcState(): AtcState {
  const store = useAtcStore();

  return useSyncExternalStore(store.subscribe, store.getState);
}

/**
 * Where a plane at `from` would be after `seconds` along `trackDeg` at
 * `speedKt`, on a flat-earth approximation that is exact enough for the few
 * nautical miles between snapshots.
 */
export function deadReckon(
  from: LatLon,
  trackDeg: number,
  speedKt: number,
  seconds: number,
): LatLon {
  const nm = (speedKt * seconds) / 3600;
  if (nm === 0) {
    return { lat: from.lat, lon: from.lon };
  }
  const track = (trackDeg * Math.PI) / 180;
  const lat = from.lat + (nm * Math.cos(track)) / 60;
  const lon =
    from.lon +
    (nm * Math.sin(track)) / (60 * Math.cos((from.lat * Math.PI) / 180));

  return { lat, lon };
}

/** How much of a correction started at `since` remains: 1, easing to 0. */
function remaining(since: number, now: number): number {
  const t = clamp((now - since) / CORRECTION_MS, 0, 1);

  return (1 - t) ** 3;
}

/** Where to draw the plane at `now`. */
export function motionPosition(motion: Motion, now: number): LatLon {
  const { base, velocity, offset } = motion;
  const seconds = clamp((now - motion.baseAt) / 1000, 0, MAX_DEAD_RECKON_S);
  const reckoned =
    velocity === null
      ? base
      : deadReckon(base, velocity.trackDeg, velocity.speedKt, seconds);
  const k = remaining(motion.offsetAt, now);

  return {
    lat: reckoned.lat + offset.lat * k,
    lon: reckoned.lon + offset.lon * k,
  };
}

/**
 * Where `position` falls in the map's layer, in unrounded pixels. Leaflet's
 * own `latLngToLayerPoint` rounds to whole pixels; at regional zooms a plane
 * moves well under a pixel a frame, so rounding makes it stand still and
 * then hop, each plane at a different moment.
 */
export function exactLayerPoint(map: LeafletMap, position: LatLon): Point {
  return map
    .project([position.lat, position.lon], map.getZoom())
    .subtract(map.getPixelOrigin());
}

/** Writes one plane's position and heading; transforms only, no reads. */
const draw = (hex: string, position: LatLon, heading: number | null) => {
  drawn.set(hex, position);
  const icon = markers.get(hex)?.getElement();
  if (!icon) {
    return;
  }
  L.DomUtil.setPosition(icon, exactLayerPoint(map, position));
  const body = bodyOf(icon);
  const rotation = heading === null ? null : planeRotation(heading);
  if (body && rotation !== null && body.style.transform !== rotation) {
    body.style.transform = rotation;
  }
};

// Hold-back: streamed props (s.streaming.*) render as they arrive; plain
// props (hex, airport) appear only once complete, and Hashbrown shows the
// fallback until then. Keep IDs non-streaming so a half-streamed "a1c" never
// resolves to another plane.

export const flightCardContract = {
  name: 'FlightCard',
  description:
    'One aircraft on the map, with live altitude, speed, heading and its scheduled route if looked up.',
  props: {
    note: s.streaming.string(
      'One or two sentences for the user about this flight',
    ),
    hex: s.string(
      'The aircraft hex code from a tool result. Never invent or shorten one.',
    ),
  },
};

export const arrivalsBoardContract = {
  name: 'ArrivalsBoard',
  description:
    'A live table of aircraft approaching or near an airport, nearest first.',
  props: {
    title: s.streaming.string(
      'A short label with no dashes, such as "Arrivals at Seattle" or "Near Bend"',
    ),
    airport: s.enumeration(
      'ICAO code of the airport the aircraft are approaching or near',
      [...AIRPORT_CODES],
    ),
    // The array streams row by row, but each s.string item is held back until
    // whole, so a row never points at a partial hex.
    hexes: s.streaming.array(
      'Aircraft hex codes from findAircraft, nearest first',
      s.string('Aircraft hex code'),
    ),
  },
};

// 1. Expose your components. The model can only render these, and Skillet
//    validates every input. IDs never stream, so a card never shows the wrong plane.
const components = [
  exposeMarkdown({ className: 'atc-prose' }),
  exposeComponent(FlightCard, {
    name: flightCardContract.name,
    description: flightCardContract.description,
    input: flightCardContract.props,
    fallback: FlightCardFallback,
    children: false,
  }),
  exposeComponent(ArrivalsBoard, {
    name: arrivalsBoardContract.name,
    description: arrivalsBoardContract.description,
    input: arrivalsBoardContract.props,
    fallback: ArrivalsBoardFallback,
    children: false,
  }),
  exposeComponent(AircraftCompare, {
    name: aircraftCompareContract.name,
    description: aircraftCompareContract.description,
    input: aircraftCompareContract.props,
    fallback: AircraftCompareFallback,
    children: false,
  }),
];

const components = [
  exposeMarkdown({ className: 'atc-prose' }),
  exposeComponent(FlightCard, {
    name: flightCardContract.name,
    description: flightCardContract.description,
    props: flightCardContract.props,
    fallback: FlightCardFallback,
    children: false,
  }),
  // ...ArrivalsBoard and AircraftCompare
];

@Component({
  selector: 'atc-flight-card',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @let card = view();
    @if (card.status === 'unknown') {
      <article class="atc-card" data-testid="flight-card">
        <p class="atc-card-title">Unknown aircraft</p>
        <p class="atc-card-note">{{ note() }}</p>
      </article>
    } @else {
      <article class="atc-card" data-testid="flight-card">
        <header>
          <button
            type="button"
            class="atc-pick"
            [class.is-selected]="card.selected"
            [disabled]="card.status !== 'live'"
            (click)="store.revealAircraft(card.hex)"
          >
            <strong class="atc-callsign">{{ card.label }}</strong>
            @if (card.subtitle) {
              <span class="atc-card-muted">{{ card.subtitle }}</span>
            }
          </button>
        </header>
        <!-- type, route, altitude, speed, heading... -->
        <p class="atc-card-note">{{ note() }}</p>
      </article>
    }
  `,
})
export class FlightCard implements OnInit {
  readonly note = input.required<string>();
  readonly hex = input.required<string>();
  protected readonly store = inject(ATC_STORE);
  private readonly state = injectAtcState();
  protected readonly view = computed(() =>
    flightCardView(this.state(), this.hex()),
  );

  ngOnInit(): void {
    this.store.pulse(this.hex());
  }
}

export function FlightCard({ note, hex }: FlightCardProps) {
  const store = useAtcStore();
  const view = flightCardView(useAtcState(), hex);
  useEffect(() => store.pulse(hex), [store, hex]);

  if (view.status === 'unknown') {
    return (
      <article className="atc-card" data-testid="flight-card">
        <p className="atc-card-title">Unknown aircraft</p>
        <p className="atc-card-note">{note}</p>
      </article>
    );
  }

  return (
    <article className="atc-card" data-testid="flight-card">
      <header>
        <button
          type="button"
          className={`atc-pick${view.selected ? ' is-selected' : ''}`}
          disabled={view.status !== 'live'}
          onClick={() => store.revealAircraft(view.hex)}
        >
          <strong className="atc-callsign">{view.label}</strong>
          {view.subtitle ? (
            <span className="atc-card-muted">{view.subtitle}</span>
          ) : null}
        </button>
      </header>
      {/* type, route, altitude, speed, heading... */}
      <p className="atc-card-note">{note}</p>
    </article>
  );
}

export function flightCardView(
  state: AtcState,
  hex: string,
  timeZone?: string,
): FlightCardView {
  const found = lookupAircraft(state, hex);
  if (found.status === 'unknown') {
    return { status: 'unknown', hex };
  }
  const { aircraft } = found;

  return {
    status: found.status,
    hex: normalizeHex(hex),
    label: aircraft.label,
    subtitle: aircraftSubtitle(aircraft),
    aircraftType: aircraftTypeName(aircraft.typeCode),
    altitude: formatAltitude(aircraft),
    speed: formatSpeed(aircraft.groundSpeedKt),
    heading: formatHeading(aircraft.trackDeg),
    route:
      aircraft.callsign === null
        ? null
        : routeText(state.routes, aircraft.callsign),
    lastSeen:
      found.status === 'out-of-range'
        ? formatClock(found.lastSeenAt, timeZone)
        : null,
    selected: state.selectedHex === aircraft.hex,
  };
}

export const ATC_TOOL_DEFINITIONS = {
  findAircraft: {
    name: 'findAircraft' as const,
    description:
      'Find aircraft on the map by airline, type, kind, altitude, approach or distance from an airport. With near, the map also shows and outlines that area. Returns compact rows.',
    schema: findAircraftInput,
  },
  lookupPlace: {
    name: 'lookupPlace' as const,
    description:
      'Find a Pacific Northwest airport by ICAO, IATA or FAA code, name or city. Returns its ICAO code, or found false.',
    schema: s.object('Place lookup', {
      query: s.string('What the user called the place, such as Bend or KBDN'),
    }),
  },
  followAircraft: {
    name: 'followAircraft' as const,
    description: 'Keep the map centred on one aircraft.',
    schema: s.object('Aircraft to follow', {
      hex: s.string('Aircraft hex code from a tool result'),
    }),
  },
  // ...seven more
};

export function createAtcTools(context: AtcToolContext) {
  const { store } = context;

  return {
    lookupPlace: {
      ...ATC_TOOL_DEFINITIONS.lookupPlace,
      handler: async ({ query }: { query: string }) => {
        const airport = lookupPlace(query);

        return airport === null
          ? unknownPlace(query)
          : {
              found: true as const,
              code: airport.code,
              faa: airport.faa,
              name: airport.name,
              city: `${airport.city}, ${airport.state}`,
            };
      },
    },
    followAircraft: {
      ...ATC_TOOL_DEFINITIONS.followAircraft,
      handler: async ({ hex }: { hex: string }) => {
        if (!store.getState().aircraft.has(normalizeHex(hex))) {
          return {
            following: false,
            reason: `No aircraft with hex ${normalizeHex(hex)} is on the map.`,
          };
        }
        store.follow(hex);

        return { following: true };
      },
    },
    // ...
  } satisfies Record<AtcToolName, unknown>;
}

/** Input schema for `findAircraft`. Every field is required; null means "any". */
export const findAircraftInput = s.object(
  'Filters for aircraft currently on the map',
  {
    airline: s.anyOf([
      s.string('Airline ICAO code such as UAL, or a name such as United'),
      s.nullish(),
    ]),
    kind: s.anyOf([
      s.enumeration(
        'Only this kind of aircraft: jet, twin (twin-engine prop), single (single-engine prop) or rotor (helicopter)',
        [...KINDS],
      ),
      s.nullish(),
    ]),
    minAltitudeFt: s.anyOf([s.number('Minimum altitude in feet'), s.nullish()]),
    near: s.anyOf([
      s.object('Only aircraft within radiusNm of an airport', {
        airport: s.string('ICAO code from lookupPlace, such as KBDN'),
        radiusNm: s.number('Radius in nautical miles, 5 to 150'),
      }),
      s.nullish(),
    ]),
    sortBy: s.enumeration('Sort order', ['altitude', 'speed', 'distance']),
    limit: s.integer('Maximum rows, 1 to 20'),
    // ...typeCode, maxAltitudeFt, approaching
  },
);

/** The parsed input of `findAircraft`. */
export type FindAircraftInput = s.Infer<typeof findAircraftInput>;

private readonly atc = createAtcTools({
  store: inject(ATC_STORE),
  fetchRoute,
});

// 2. Give the model tools. They run here in the browser, against the aircraft
//    already on the map; no plane list goes to the server.
private readonly tools = [
  createTool(this.atc.findAircraft),
  createTool(this.atc.getSelectedAircraft),
  createTool(this.atc.lookupRoute),
  createTool(this.atc.highlightAircraft),
  createTool(this.atc.clearHighlight),
  createTool(this.atc.followAircraft),
  createTool(this.atc.stopFollowing),
  createTool(this.atc.lookupPlace),
  createTool(this.atc.showArea),
  createTool(this.atc.resetMap),
];

const store = useAtcStore();
const atc = useMemo(() => createAtcTools({ store, fetchRoute }), [store]);

// 2. Give the model tools. They run here in the browser, against the aircraft
//    already on the map; no plane list goes to the server.
const tools = [
  useTool({ ...atc.findAircraft, deps: [atc] }),
  useTool({ ...atc.getSelectedAircraft, deps: [atc] }),
  useTool({ ...atc.lookupRoute, deps: [atc] }),
  // ...
];

// 3. Render the stream.
protected readonly chat = uiChatResource({
  // Required by Hashbrown; the server replaces it with SYSTEM_PROMPT
  // (server/src/run-handler.ts), so the browser cannot change the rules.
  system: 'Provided by the server.',
  components,
  tools: this.tools,
});

// 3. Render the stream.
const chat = useUiChat({
  // Required by Hashbrown; the server replaces it with SYSTEM_PROMPT
  // (server/src/run-handler.ts), so the browser cannot change the rules.
  system: 'Provided by the server.',
  components,
  tools,
});

@case ('answer') {
<li class="atc-answer">
  <hb-render-message [message]="item.message" />
</li>
}

<li key={index} className="atc-answer">
  {item.message.ui}
</li>

/** Each atc tool as the model sees it, built from the shared definitions. */
const PINNED_TOOLS: ReadonlyMap<string, Tool> = new Map(
  Object.values(ATC_TOOL_DEFINITIONS).map(
    ({ name, description, schema }): [AtcToolName, Tool] => [
      name,
      // The same conversion Hashbrown's client applies to a tool's schema.
      { name, description, parameters: s.toJsonSchema(schema) },
    ],
  ),
);

/**
 * The tools the client asked for, each replaced with the server's own
 * definition (description and JSON Schema). Unknown tools and repeats are
 * dropped, so the model only ever sees atc's tools as atc wrote them.
 */
export function pinTools(tools: readonly Tool[]): Tool[] {
  const names = new Set(tools.map((tool) => tool.name));

  return [...names].flatMap((name) => {
    const pinned = PINNED_TOOLS.get(name);

    return pinned === undefined ? [] : [pinned];
  });
}

/**
 * Drops client system and developer messages and puts the server's prompt
 * first. Hashbrown clients always send a system message; dropping it here
 * means the browser can never change the rules.
 */
export function pinSystemPrompt(
  input: RunAgentInput,
  prompt: string,
): RunAgentInput {
  return {
    ...input,
    messages: [
      { id: 'atc-system', role: 'system', content: prompt },
      ...input.messages.filter(
        (message) => message.role !== 'system' && message.role !== 'developer',
      ),
    ],
  };
}

const encoder = new EventEncoder();
const stream = HashbrownOpenAI.stream.text({
  apiKey: options.apiKey,
  baseURL: options.baseURL,
  model: options.model,
  input: pinSystemPrompt(
    { ...input, tools: pinTools(input.tools ?? []) },
    SYSTEM_PROMPT,
  ),
  signal: abortController.signal,
  transformRequestOptions: (request) =>
    limitRequest(request, {
      // Undefined means the default; null means none.
      reasoningEffort:
        options.reasoningEffort === undefined ? 'low' : options.reasoningEffort,
    }),
});
res.writeHead(200, {
  'Content-Type': encoder.getContentType(),
  'Cache-Control': 'no-cache, no-store, must-revalidate, no-transform',
  'X-Accel-Buffering': 'no',
});
for await (const event of stream) {
  res.write(encoder.encodeSSE(event));
}

export const SYSTEM_PROMPT = `You are the assistant in atc, a live map of air traffic over the Pacific Northwest. Answer questions about the aircraft on the map.

Rules:
- Use tools for every fact and number. Never estimate altitudes, speeds, distances or times yourself.
- Only use aircraft hex codes that appear in a tool result. Never invent or shorten one.
- For "this plane" or "the selected plane", call getSelectedAircraft. If it returns null, ask the user to tap or click a plane on the map.
- For a list of aircraft, show one ArrivalsBoard and no FlightCards. For two or three aircraft side by side, show an AircraftCompare.
- When you show aircraft, call highlightAircraft with their hex codes so the map matches your answer.
- Keep prose to one or two short Markdown sentences. Do not repeat what the components already show: numbers, routes, types or airlines.
- Start with the answer. No lead-ins such as "Here are", "Here's", "Sure" or "Let me".
- Routes are scheduled routes from public data and can be wrong. Call them scheduled.
...`;

mock = new LLMock({ port: 0, chunkSize: 8 });

mock.onMessage(STARTER_PROMPTS[1], {
  toolCalls: [
    {
      id: 'arrivals-find',
      name: 'findAircraft',
      arguments: {
        ...ANY,
        approaching: 'KSEA',
        sortBy: 'distance',
        limit: 10,
      },
    },
    {
      id: 'arrivals-highlight',
      name: 'highlightAircraft',
      arguments: { hexes: arrivals.map((r) => r.hex) },
    },
  ],
});

test('shows Seattle arrivals and highlights them on the map', async ({
  page,
}, testInfo) => {
  await open(page, testInfo.project.name);

  await page.getByRole('button', { name: STARTER_PROMPTS[1] }).click();

  await expect(page.getByTestId('arrivals-row')).toHaveCount(arrivals.length);
  await expect(page.locator('.atc-plane.is-dimmed').first()).toBeAttached();
  for (const row of arrivals) {
    await expect(
      page.locator(`.atc-plane[data-hex="${row.hex}"]`),
    ).not.toHaveClass(/is-dimmed/);
  }
  await expectOnlyCompleteIds(page);
});

## Invariants not to break

- Only fields validated in `shared/src/aircraft.ts` (hex, label, kind, numbers) go into
  marker HTML. Everything else is rendered as text.
- `normalizeAdsbLol` copies whitelisted fields only; never spread adsb.lol entries.
- The system prompt, the tool definitions and the output cap are fixed on the server;
  clients cannot change them.
- The map moves only through store view requests: the newest wins, follow mode wins over
  all, a user drag or zoom cancels.
- Markers update in place (`updatePlane`); never rebuild them on a snapshot.
- Component IDs (`hex`, `airport`) never stream, so a card never resolves a partial ID.
- Shared code stays framework-free; the two apps stay thin and mirror each other.

/**
 * To add a tool: (1) add its definition to `ATC_TOOL_DEFINITIONS` and its
 * handler here; (2) register it in
 * `angular/src/app/assistant.ts` and `react/src/assistant.tsx`; (3) add its
 * RUNNING and DONE labels in `tool-chips.ts` (the compiler asks for them);
 * (4) tell the model when to use it in `SYSTEM_PROMPT` (`contracts.ts`);
 * (5) script it in `e2e/src/atc.spec.ts`.
 */