@adatechnology/game-devtools 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,209 @@
+# Migration: `ModoLivreSDK` (modo-livre.js) to `@adatechnology/game-devtools`
+
+Source: `sdk/teste/modo-livre.js` and its README. Every old name maps to exactly one new name. With `locale: 'pt-BR'` every user-facing string is
+identical to the original (checked by running both implementations on the same inputs and comparing HUD, form and panel texts, placeholders,
+aria-labels, notification messages and the copy text).
+
+## Loading
+
+| Old | New |
+|---|---|
+| global `ModoLivreSDK` (concatenated `<script>`) | ESM `import { create } from '@adatechnology/game-devtools'`, or IIFE `dist/index.global.js` exposing `GameDevtools` |
+| `ModoLivreSDK.criar(THREE, cfg)` | `GameDevtools.create(THREE, options)` |
+
+## Options (`criar` second argument)
+
+| Old | New |
+|---|---|
+| `chaveMarcas` (default `'sdk-modo-livre-marcas'`) | `marksStorageKey` (default `'game-devtools-marks'`) |
+| `colecao` (default `'marcas'`) | `collection` (default `'marks'`) |
+| `arquivo` (default `'marcas.txt'`) | `fileName` (default from the locale: `marks.txt` / `marcas.txt`) |
+| `equipes` (default `[['geral', 'Geral']]`) | `teams` (default `[['general', <locale label>]]`) |
+| `area` | `area` |
+| `hora` | `time` |
+| `msg(texto, segundos)` | `notify(text, seconds)` |
+| `pausa(aberto)` | `pause(paused)` |
+| `pos()` | `position()` |
+| `limites` | `bounds` |
+| `velocidade` | `speed` |
+| `etiquetasMax` | `labelsMax` |
+| `etiquetasDist` | `labelsDistance` (still not read, kept for compatibility) |
+| (none) | `locale` (`'en'` default, `'pt-BR'`) and `strings` (partial overrides) |
+
+Data that already exists under the old defaults keeps working if you pass the old values: `marksStorageKey: 'sdk-modo-livre-marcas'`,
+`collection: 'marcas'`. The ZombiAdA adapter passes its own `chaveMarcas`, so only `collection` matters for server-side marks. Stored marks also carry
+renamed fields (see "Mark fields" below): marks saved by the old SDK have `rumo`/`graus`/`olhar`/`hora`/`voo` and need a one-off conversion, or
+simply start fresh.
+
+Team ids are game data, so `'geral'` stays valid if you declare `teams` yourself.
+
+## Returned object (`ml`)
+
+State and fields:
+
+| Old | New |
+|---|---|
+| `ml.voo` | `dev.flying` |
+| `ml.x`, `ml.y`, `ml.z` | `dev.x`, `dev.y`, `dev.z` |
+| `ml.vel` | `dev.speed` |
+| `ml.hud` | `dev.hud` |
+| `ml.aberto` (`null`, `'form'`, `'lista'`) | `dev.openPanel` (`null`, `'form'`, `'list'`) |
+| `ml.db` | `dev.db` |
+| `ml.marcas` | `dev.marks` |
+| `ml.chaves` | internal (use `dev.toggle`) |
+| `ml.acoes` | internal (use `dev.action`) |
+| `ml.horas` | internal (use `dev.timesOfDay`) |
+| `ml.grupos` | internal (use `dev.places`) |
+| `ml.cens` | `dev.scenarioList` (read-only) |
+| `ml.cenAtivo` | `dev.activeScenario` (read-only) |
+| `ml.etiq` | `dev.showLabels` |
+| `ml.etiquetas` | internal (use `dev.labelsFor`) |
+| `ml.abertos` | internal (which place groups are expanded) |
+| `ml.irPara` | `dev.goTo` |
+| `ml.extras` | `dev.extras` |
+
+Methods:
+
+| Old | New |
+|---|---|
+| `ml.rumo(yaw)` | `dev.compass(yaw)` |
+| `ml.aqui()` | `dev.here()` |
+| `ml.linha(marca)` | `dev.line(mark)` |
+| `ml.voa(dt, yaw, pitch, teclas)` | `dev.fly(dt, yaw, pitch, keys)` |
+| `ml.cameraVoo(cam, yaw, pitch)` | `dev.flyCamera(camera, yaw, pitch)` |
+| `ml.chave(id, nome, get, set)` | `dev.toggle(id, label, get, set)` |
+| `ml.acao(id, nome, fn)` | `dev.action(id, label, fn)` |
+| `ml.horasDoDia(lista, set)` | `dev.timesOfDay(list, set)` |
+| `ml.lugares(fn)` | `dev.places(fn)` |
+| `ml.etiquetasDe(fn)` | `dev.labelsFor(fn)` |
+| `ml.cenarios(lista, aplicar, checar)` | `dev.scenarios(list, apply, check)` |
+| `ml.cenario(id)` | `dev.scenario(id)` |
+| `ml.checar(id)` | `dev.check(id)` |
+| `ml.abre('form' \| 'lista')` | `dev.open('form' \| 'list')` |
+| `ml.fecha()` | `dev.close()` |
+| `ml.render()` | `dev.render()` |
+| `ml.atualiza(dt, cam, visivel)` | `dev.update(dt, camera, visible)` |
+| `ml.expoe()` | `dev.expose()` |
+| (none) | `dev.dispose()` (new) |
+
+## Key object for `voa` (`fly`)
+
+| Old | New |
+|---|---|
+| `frente` | `forward` |
+| `lado` | `strafe` |
+| `sobe` | `up` |
+| `rapido` | `fast` |
+
+## Mark and `aqui()` (`here()`) fields
+
+| Old | New |
+|---|---|
+| `x`, `y`, `z`, `yaw`, `pitch` | unchanged |
+| `area` | `area` |
+| `rumo` | `heading` |
+| `graus` | `degrees` |
+| `olhar` | `look` |
+| `hora` | `time` |
+| `voo` | `flying` |
+| `team`, `text`, `at`, `by`, `id` (mark only) | unchanged |
+
+`rumo(yaw)` returned `[rumo, graus]`; `compass(yaw)` returns `[heading, degrees]`.
+
+## Callback and registration argument shapes
+
+| Old | New |
+|---|---|
+| `lugares(() => [[grupo, [[nome, ir]]]])` | `places(() => [[group, [[name, go]]]])` (same shape) |
+| `etiquetasDe(cam => [{ x, y, z, texto, cor }])` | `labelsFor(camera => [{ x, y, z, text, color }])` |
+| `texto` | `text` |
+| `cor` | `color` |
+| `horasDoDia([[nome, valor]], set)` | `timesOfDay([[label, value]], set)` (same shape) |
+| `cenarios(lista, aplicar, checar)`: `checar(c) -> { criterio: { ok, nota } }` | `scenarios(list, apply, check)`: `check(s) -> { criterion: { ok, note } }` |
+| `nota` | `note` |
+| `chave(...)` `set` returns `true` to close the panel | `toggle(...)` `set` returns `true` to close the panel (same) |
+| `acao(...)` `fn` returns `true` to keep the panel open | `action(...)` `fn` returns `true` to keep the panel open (same) |
+
+## Browser-test globals (`expoe`)
+
+| Old | New |
+|---|---|
+| `window.__cenario` | `window.__scenario` |
+| `window.__cenCheck` | `window.__scenarioCheck` |
+| `window.__cenLista` | `window.__scenarioList` |
+| `window.__modoLivre` | `window.__devtools` |
+
+## DOM (ids, classes, data attributes)
+
+| Old | New |
+|---|---|
+| `#mlpos`, `.mlpos`, `.mlpos.voo` | `#gd-pos`, `.gd-pos`, `.gd-pos.flying` |
+| `#mlform` | `#gd-form` |
+| `#mllista` | `#gd-list` |
+| `.mlpainel` | `.gd-panel` |
+| `#mlet`, `.mlet` | `#gd-labels`, `.gd-labels` |
+| `.mlrow` | `.gd-row` |
+| `.mlsub` | `.gd-sub` |
+| `.mlm` | `.gd-mark` |
+| `.mlcopia`, `#mlcopia` | `.gd-copy`, `#gd-copy` |
+| `#mleq` | `#gd-team` |
+| `#mltxt` | `#gd-note` |
+| `#mlbaixar` | `#gd-download` |
+| `data-f="salva" / "fecha" / "copiar" / "baixar"` | `data-f="save" / "close" / "copy" / "download"` |
+| `data-tg` | `data-toggle` |
+| `data-ac` | `data-action` |
+| `data-hora` | `data-time` |
+| `data-lug` | `data-place` |
+| `data-ir` | `data-goto` |
+| `data-apaga` | `data-delete` |
+| `data-g` | `data-g` (unchanged) |
+
+The CSS variables read from the host (`--panel`, `--ink`, `--line`, `--accent`, `--muted`, `--f-mono`, `--f-display`) are unchanged.
+
+## User-facing strings (now in the locale table)
+
+`pt-BR` equals the previous Portuguese text exactly.
+
+| Old (hard-coded) | New key | `en` |
+|---|---|---|
+| `['N','NE','L','SE','S','SO','O','NO']` | `compass` | `N NE E SE S SW W NW` |
+| `'Geral'` | `defaultTeam` | `General` |
+| `'marcas.txt'` | `fileName` | `marks.txt` |
+| `'Marcar ajuste'` | `markFormLabel` | `Mark adjustment` |
+| `'Modo livre'` (panel heading and aria-label) | `panelTitle` | `Free mode` |
+| `'Marcar este lugar'` | `markHereTitle` | `Mark this place` |
+| `'olhando'` | `lookingAt` | `looking` |
+| `'Equipe'` | `teamLabel` | `Team` |
+| `'O que ajustar aqui?'` | `notePlaceholder` | `What should be adjusted here?` |
+| `'Salvar (Enter)'` | `saveButton` | `Save (Enter)` |
+| `'Cancelar (Esc)'` | `cancelButton` | `Cancel (Esc)` |
+| `'sim'` / `'não'` | `yes` / `no` | `yes` / `no` |
+| `'Lugares de teste'` | `placesTitle` | `Test places` |
+| `` `Marcas (${n})` `` | `marksTitle(n)` | `Marks (n)` |
+| `'Salvas no servidor desta página: Claude lê direto, não precisa copiar.'` | `savedOnServer` | `Saved on this page's server: Claude reads them directly, no need to copy.` |
+| `'Salvas neste navegador. Para mandar: Copiar tudo e colar no chat, ou Baixar arquivo.'` | `savedInBrowser` | `Saved in this browser. To send them: Copy all and paste in the chat, or Download file.` |
+| `'(sem nota)'` | `noNote` | `(no note)` |
+| `'Ir'` | `goButton` | `Go` |
+| `'Apagar'` | `deleteButton` | `Delete` |
+| `'Nenhuma marca ainda.'` | `noMarks` | `No marks yet.` |
+| `'Copiar tudo'` | `copyAll` | `Copy all` |
+| `'Baixar arquivo'` | `downloadFile` | `Download file` |
+| `'Fechar (Esc)'` | `closeButton` | `Close (Esc)` |
+| `'Copiado'` | `copied` | `Copied` |
+| `'Selecionado: Ctrl+C'` | `copySelected` | `Selected: Ctrl+C` |
+| `'Marca salva. Claude já consegue ler'` | `savedServerMsg` | `Mark saved. Claude can already read it` |
+| `'Não deu para salvar no servidor, ficou neste navegador'` | `serverFailMsg` | `Could not save to the server, it stayed in this browser` |
+| `'Marca salva neste navegador. Abra o painel para copiar'` | `savedBrowserMsg` | `Mark saved in this browser. Open the panel to copy` |
+| `olhar` (HUD) | `hudLook` | `look` |
+| `` `voo ${v} m/s` `` | `hudFlight(speed)` | `fly <v> m/s` |
+| `` `${n} marcas` `` | `hudMarks(n)` | `n mark(s)` |
+
+Use `create(THREE, { locale: 'pt-BR' })` to keep the Portuguese UI. Override any entry with `strings`.
+
+## Behaviour changes beyond renaming
+
+- New `dispose()` removes the injected `<style>`, elements and the `wheel`/`keydown` listeners (the original had no teardown).
+- Options set to `undefined` no longer erase their defaults (the original `{ ...defaults, ...cfg }` did).
+- The mark text/serialisation logic is now also exported as pure functions (`formatMarkLine`, `serializeMarks`, `sortMarks`, `compass`) and the
+  scenario bookkeeping as `createScenarioRunner`, with no behaviour difference.
+- Default `collection` and `marksStorageKey` changed (see above); pass the old values to keep existing data.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @adatechnology/game-devtools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+In-game test tooling for three.js games. It knows nothing about any game: the host plugs everything in through options and a handful of
+registration calls.
+
+- **Free-fly mode** that goes through everything (bounded, mouse-wheel speed).
+- **Position HUD**: area, coordinates, compass heading, look angle, time of day, optional extras.
+- **Notes and marks**: "mark this place" form with team and note. Marks are stored in the page's server database when one is available
+  (`window.claude`), otherwise in `localStorage`, with copy-all and download. Pure helpers format and serialise them.
+- **Panel** with on/off switches, action buttons, time-of-day buttons and grouped test places.
+- **Scenarios runner**: apply a scenario by id and run an automatic check that returns `{ criterion: { ok, note } }`.
+- **Entity labels** floating over world points.
+- Localised (`en`, `pt-BR`); every default string can be overridden.
+
+`three` is a peer dependency used for types only: you pass your own `THREE` instance at runtime.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-devtools three
+```
+
+Browser without a bundler (the global is `GameDevtools`):
+
+```html
+<script src="https://unpkg.com/@adatechnology/game-devtools/dist/index.global.js"></script>
+<script>
+  const dev = GameDevtools.create(THREE, { locale: 'en' })
+</script>
+```
+
+## Usage
+
+```ts
+import * as THREE from 'three'
+import { create } from '@adatechnology/game-devtools'
+
+const dev = create(THREE, {
+  marksStorageKey: 'my-game-marks',
+  teams: [['map', 'Map'], ['art', 'Art']],
+  area: (x, z) => 'Plaza',
+  time: () => '12:00',
+  notify: (text, seconds) => showToast(text, seconds),
+  position: () => ({ x, y, z, yaw, pitch }),
+  bounds: { x: [-500, 500], y: [0.4, 260], z: [-500, 500] },
+  pause: (paused) => { /* release the mouse, pause the game */ },
+  locale: 'en', // or 'pt-BR'
+})
+
+dev
+  .toggle('fog', 'Fog', () => fog, (on) => { fog = on })
+  .action('spawn', 'Spawn zombie', () => { spawn(); return true /* keep the panel open */ })
+  .timesOfDay([['Morning', 0.3], ['Night', 0.9]], setTimeOfDay)
+  .places(() => [['City', [['Plaza', () => teleport(0, 0)]]]])
+  .labelsFor((camera) => [{ x, y, z, text: 'npc-12', color: '#9fd0ff' }])
+  .scenarios(list, (scenario) => apply(scenario), (scenario) => ({ lit: { ok: isLit(), note: '...' } }))
+
+dev.goTo = (x, y, z, yaw, pitch) => teleport(x, y, z, yaw, pitch)
+
+// every frame
+if (dev.flying) {
+  dev.fly(dt, yaw, pitch, { forward, strafe, up, fast })
+  dev.flyCamera(camera, yaw, pitch)
+}
+dev.update(dt, camera, visible)
+
+// your own keys
+dev.open('form') // or 'list'; dev.close()
+dev.expose() // window.__scenario, __scenarioCheck, __scenarioList, __devtools for Playwright
+```
+
+Keys stay in the game. Free-fly is on when you set `dev.flying = true`.
+
+## API
+
+### `create(THREE, options?) => Devtools`
+
+| Option | Default | Meaning |
+|---|---|---|
+| `marksStorageKey` | `'game-devtools-marks'` | localStorage key for marks |
+| `collection` | `'marks'` | Server database collection |
+| `fileName` | locale (`marks.txt` / `marcas.txt`) | Name of the downloaded file |
+| `teams` | `[['general', 'General']]` | `[id, label]` pairs for the form |
+| `area(x, z)` | `''` | Area name |
+| `time()` | `''` | Time-of-day text |
+| `notify(text, seconds)` | no-op | Short messages to the player |
+| `pause(paused)` | no-op | Called with `true` when a panel opens and `false` when it closes |
+| `position()` | origin | `{ x, y, z, yaw, pitch }` of the player |
+| `bounds` | +-1e4 / y 0.4..400 | Free-fly limits |
+| `speed` | `14` | Initial free-fly speed (m/s) |
+| `labelsMax` | `48` | Label pool size |
+| `locale` | `'en'` | `'en'` or `'pt-BR'` |
+| `strings` | | Partial overrides of any user-facing string |
+
+### `Devtools`
+
+State (read/write): `flying`, `x`, `y`, `z`, `speed`, `hud`, `showLabels`, `goTo`, `extras`. State (read): `openPanel`, `marks`, `db`, `scenarioList`,
+`activeScenario`.
+
+Methods: `compass(yaw)`, `here()`, `line(mark)`, `fly(dt, yaw, pitch, keys)`, `flyCamera(camera, yaw, pitch)`, `toggle(...)`, `action(...)`,
+`timesOfDay(...)`, `places(...)`, `labelsFor(...)`, `scenarios(list, apply, check)`, `scenario(id)`, `check(id?)`, `open(panel)`, `close()`, `render()`,
+`update(dt, camera, visible?)`, `expose()`, `dispose()`.
+
+### Pure helpers (no DOM)
+
+`compass(yaw, headings)`, `formatMarkLine(mark, teams, strings)`, `sortMarks(marks)`, `serializeMarks(marks, teams, strings)` (returns `{ text, file }`; `file`
+is the text plus the raw JSON array), `createScenarioRunner()`, `escapeHtml(s)`, and the `locales` table.
+
+Coming from the Portuguese `ModoLivreSDK`? See [MIGRATION.md](./MIGRATION.md).
+
+## Português
+
+Ferramentas de teste dentro do jogo para three.js: voo livre que atravessa tudo, posição na tela, marcas com nota (banco do artifact ou
+navegador), painel com chaves, ações, hora e lugares de teste, cenários com checagem automática e etiquetas sobre entidades. Não conhece nenhum jogo.
+
+```ts
+const dev = create(THREE, { locale: 'pt-BR', teams: [['mapa', 'Mapa']], area, time, notify, position, pause })
+dev.toggle('neblina', 'Neblina', () => neblina, (on) => { neblina = on })
+```
+
+Com `locale: 'pt-BR'` todos os textos (HUD, painel, formulário, mensagens, pontos cardeais "N NE L SE S SO O NO") ficam idênticos aos do SDK
+original. A tabela de nomes antigos e novos está em [MIGRATION.md](./MIGRATION.md).

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import * as ThreeNamespace from 'three';
+
+/** Locales shipped with the package. Unknown locales fall back to `en`. */
+type DevtoolsLocale = 'en' | 'pt-BR';
+/** Every user-facing default string. Override any of them with the `strings` option. */
+interface DevtoolsStrings {
+    /** Eight compass headings starting at north, clockwise (N, NE, E, SE, S, SW, W, NW). */
+    compass: [string, string, string, string, string, string, string, string];
+    /** Label of the default team. */
+    defaultTeam: string;
+    /** Default file name of the downloaded marks file. */
+    fileName: string;
+    /** aria-label of the "mark this place" form. */
+    markFormLabel: string;
+    /** aria-label and title of the main panel. */
+    panelTitle: string;
+    markHereTitle: string;
+    /** Word before the heading in position lines ("looking N 12"). */
+    lookingAt: string;
+    teamLabel: string;
+    notePlaceholder: string;
+    saveButton: string;
+    cancelButton: string;
+    yes: string;
+    no: string;
+    placesTitle: string;
+    marksTitle: (count: number) => string;
+    savedOnServer: string;
+    savedInBrowser: string;
+    noNote: string;
+    goButton: string;
+    deleteButton: string;
+    noMarks: string;
+    copyAll: string;
+    downloadFile: string;
+    closeButton: string;
+    copied: string;
+    copySelected: string;
+    savedServerMsg: string;
+    serverFailMsg: string;
+    savedBrowserMsg: string;
+    hudLook: string;
+    hudFlight: (speed: string) => string;
+    hudMarks: (count: number) => string;
+}
+declare const locales: Record<DevtoolsLocale, DevtoolsStrings>;
+declare const resolveStrings: (locale?: string, overrides?: Partial<DevtoolsStrings>) => DevtoolsStrings;
+
+/** The only three.js member the devtools need at runtime. Pass your own `THREE` instance. */
+type ThreeLib = Pick<typeof ThreeNamespace, 'Vector3'>;
+/** A camera that can project world points to the screen. */
+type ProjectionCamera = ThreeNamespace.Camera;
+/** Where the player is. Yaw 0 looks toward -z (north); positive pitch looks down. */
+interface PlayerPosition {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+    pitch: number;
+}
+/** `[team id, team label]` pairs shown in the mark form. */
+type Team = [id: string, label: string];
+interface Bounds {
+    x: [number, number];
+    y: [number, number];
+    z: [number, number];
+}
+interface DevtoolsOptions {
+    /** localStorage key where marks are kept when there is no server database. */
+    marksStorageKey?: string;
+    /** Database collection used when a `window.claude` database is available. */
+    collection?: string;
+    /** File name of the downloaded marks file (default comes from the locale). */
+    fileName?: string;
+    /** Teams offered in the mark form (default: one team `general`). */
+    teams?: Team[];
+    /** Name of the area at world (x, z). */
+    area?: (x: number, z: number) => string;
+    /** Time-of-day text shown in the HUD and stored in marks. */
+    time?: () => string;
+    /** Short message to the player: `notify(text, seconds)`. */
+    notify?: (text: string, seconds?: number) => void;
+    /** `pause(true)` when a panel opens, `pause(false)` when it closes. */
+    pause?: (paused: boolean) => void;
+    /** Current player position. */
+    position?: () => PlayerPosition;
+    /** Free-fly limits. */
+    bounds?: Bounds;
+    /** Initial free-fly speed (m/s). */
+    speed?: number;
+    /** Pool size of the entity labels. */
+    labelsMax?: number;
+    /** Kept for compatibility; not read by the devtools. */
+    labelsDistance?: number;
+    locale?: DevtoolsLocale | (string & {});
+    /** Overrides for individual user-facing strings. */
+    strings?: Partial<DevtoolsStrings>;
+}
+/** Snapshot of "here": position, area, heading, time. */
+interface HereInfo {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+    pitch: number;
+    area: string;
+    /** Compass heading, e.g. `NE`. */
+    heading: string;
+    /** Heading in degrees, 0..359. */
+    degrees: number;
+    /** Look angle in degrees (positive = up). */
+    look: number;
+    time: string;
+    flying: boolean;
+}
+/** A saved note. */
+interface Mark extends HereInfo {
+    id: string;
+    team: string;
+    text: string;
+    /** Epoch milliseconds. */
+    at: number;
+    /** User id when saved on a server. */
+    by?: string;
+}
+interface FlyKeys {
+    /** -1..1 */
+    forward: number;
+    /** -1..1 */
+    strafe: number;
+    /** -1..1 */
+    up: number;
+    /** 4x speed when truthy. */
+    fast?: boolean | number;
+}
+interface EntityLabel {
+    x: number;
+    y: number;
+    z: number;
+    text: string;
+    /** CSS colour, default `#9fd0ff`. */
+    color?: string;
+}
+/** `[group name, [[place name, go()]]]` */
+type PlaceGroup = [name: string, places: Array<[name: string, go: () => void]>];
+interface Scenario {
+    id: string;
+    [extra: string]: unknown;
+}
+/** Result of a scenario check: criterion -> verdict. */
+type ScenarioResult = Record<string, {
+    ok: boolean;
+    note?: string;
+}>;
+interface Devtools {
+    /** Whether free-fly is on. Set it from your own key handler. */
+    flying: boolean;
+    x: number;
+    y: number;
+    z: number;
+    /** Free-fly speed (m/s); the mouse wheel changes it while flying. */
+    speed: number;
+    /** Whether the position HUD is visible. */
+    hud: boolean;
+    /** Which panel is open (`null` when none). */
+    openPanel: 'form' | 'list' | null;
+    /** Whether entity labels are shown. */
+    showLabels: boolean;
+    /** Server database handle when `window.claude` offers one. */
+    db: any;
+    marks: Mark[];
+    scenarioList: Scenario[];
+    activeScenario: Scenario | null;
+    /** Set by the game: teleport to a mark. */
+    goTo: ((x: number, y: number, z: number, yaw: number, pitch: number) => void) | null;
+    /** Set by the game: extra text appended to the HUD line. */
+    extras: () => string;
+    /** Compass heading and degrees for a yaw. */
+    compass(yaw: number): [heading: string, degrees: number];
+    here(): HereInfo;
+    /** One-line text for a mark. */
+    line(mark: Pick<Mark, 'team' | 'area' | 'x' | 'y' | 'z' | 'heading' | 'degrees' | 'time'> & {
+        text?: string;
+    }): string;
+    /** Moves the free-fly position for this frame. */
+    fly(dt: number, yaw: number, pitch: number, keys: FlyKeys): void;
+    /** Places the camera at the free-fly position. */
+    flyCamera(camera: ProjectionCamera, yaw: number, pitch: number): void;
+    /** Registers an on/off switch in the panel; `set` returns true to close the panel. */
+    toggle(id: string, label: string, get: () => boolean, set: (on: boolean) => boolean | void): Devtools;
+    /** Registers a button; `fn` returns true to keep the panel open. */
+    action(id: string, label: string | (() => string), fn: () => boolean | void): Devtools;
+    /** Registers time-of-day buttons: `[[label, value]]`. */
+    timesOfDay(list: Array<[string, unknown]>, set: (value: unknown) => void): Devtools;
+    /** Registers test places. */
+    places(fn: () => PlaceGroup[]): Devtools;
+    /** Registers the entity label source. */
+    labelsFor(fn: (camera: ProjectionCamera) => EntityLabel[]): Devtools;
+    /** Registers scenarios with an `apply` and an automatic `check`. */
+    scenarios<S extends Scenario>(list: S[], apply: (scenario: S) => void, check: (scenario: S) => ScenarioResult): Devtools;
+    /** Applies a scenario; false if the id is unknown. */
+    scenario(id: string): boolean;
+    /** Checks a scenario (or the active one). */
+    check(id?: string): ScenarioResult;
+    open(which: 'form' | 'list'): void;
+    close(): void;
+    /** Re-renders the list panel. */
+    render(): void;
+    /** Call every frame. */
+    update(dt: number, camera: ProjectionCamera, visible?: boolean): void;
+    /** Exposes `window.__scenario`, `__scenarioCheck`, `__scenarioList`, `__devtools` for automated browser tests. */
+    expose(): void;
+    /** Removes the DOM, styles and listeners. */
+    dispose(): void;
+}
+
+/** Minimal shape of the optional `window.claude` runtime that provides a shared database. */
+interface ClaudeRuntime {
+    use(name: 'db' | 'user'): Promise<any>;
+}
+declare global {
+    interface Window {
+        claude?: ClaudeRuntime;
+        __scenario?: Devtools['scenario'];
+        __scenarioCheck?: Devtools['check'];
+        __scenarioList?: unknown;
+        __devtools?: Devtools;
+    }
+}
+/**
+ * Creates the devtools: free-fly, position HUD, marks with notes, control panel, scenarios and entity labels.
+ * The game plugs everything in through the options and the registration methods; see the README.
+ */
+declare function create(THREE: ThreeLib, options?: DevtoolsOptions): Devtools;
+
+/** Escapes text for use inside HTML. */
+declare const escapeHtml: (s: unknown) => string;
+/** Compass heading and degrees for a yaw (yaw 0 looks toward -z, i.e. north). */
+declare function compass(yaw: number, headings: DevtoolsStrings['compass']): [string, number];
+type LineMark = Pick<Mark, 'team' | 'area' | 'x' | 'y' | 'z' | 'heading' | 'degrees' | 'time'> & {
+    text?: string;
+};
+/** One-line text for a mark: `[Team] Area · x 1 y 2 z 3 · looking N 0° · 12:00 · note`. */
+declare function formatMarkLine(m: LineMark, teams: Team[], strings: Pick<DevtoolsStrings, 'lookingAt'>): string;
+/** Newest first, without mutating the input. */
+declare const sortMarks: (marks: Mark[]) => Mark[];
+/**
+ * Serialises marks for copy and download.
+ * `text` is one line per mark (newest first); `file` is that text, a blank line, and the raw JSON array
+ * (the content of the downloaded file, which Claude or a script can parse back).
+ */
+declare function serializeMarks(marks: Mark[], teams: Team[], strings: Pick<DevtoolsStrings, 'lookingAt'>): {
+    text: string;
+    file: string;
+};
+
+interface ScenarioRunner<S extends Scenario = Scenario> {
+    /** Registers the scenarios, how to apply one and how to check it. */
+    set(list: S[], apply: (scenario: S) => void, check: (scenario: S) => ScenarioResult): void;
+    readonly list: S[];
+    readonly active: S | null;
+    /** Applies a scenario and makes it the active one; false if the id is unknown. */
+    run(id: string): boolean;
+    /** Checks the scenario with that id, or the active one when the id is unknown; `{}` when there is none. */
+    check(id?: string): ScenarioResult;
+}
+/** Pure scenario bookkeeping (no DOM): `{ id, ... }` scenarios, `apply(s)` and `check(s) -> { criterion: { ok, note } }`. */
+declare function createScenarioRunner<S extends Scenario = Scenario>(): ScenarioRunner<S>;
+
+export { type Bounds, type Devtools, type DevtoolsLocale, type DevtoolsOptions, type DevtoolsStrings, type EntityLabel, type FlyKeys, type HereInfo, type Mark, type PlaceGroup, type PlayerPosition, type ProjectionCamera, type Scenario, type ScenarioResult, type ScenarioRunner, type Team, type ThreeLib, compass, create, createScenarioRunner, escapeHtml, formatMarkLine, locales, resolveStrings, serializeMarks, sortMarks };