@defold-typescript/docs 0.9.0

package/README.md

@@ -0,0 +1,3 @@
+# @defold-typescript/docs
+
+This package publishes the human-facing guide for the defold-typescript toolchain. The canonical source is [`guide/`](guide/README.md); consumers (the cli, the docs site) reach it through this package rather than the repo root.

package/guide/README.md

@@ -0,0 +1,52 @@
+---
+toc-title: Overview
+---
+# Overview
+
+Build your [Defold](https://defold.com/) game in [TypeScript](https://www.typescriptlang.org/) and get VSCode's full editor experience — autocomplete, inline type errors, and safe refactors — across the whole Defold API, while still shipping the plain [Lua](https://www.lua.org/) the engine runs.
+
+- **The full Defold API, typed** — every module and namespace is typed from the official reference, so `go`, `gui`, `vmath`, `msg`, and the rest autocomplete and type-check as you write.
+- **Compiles to plain Lua** — your TypeScript runs through the battle-tested [TypeScriptToLua](https://typescripttolua.github.io/) (TSTL) compiler down to the Lua Defold already runs: no engine fork, no proprietary runtime, no lock-in.
+- **Typed scripts end to end** — `self`, `on_message`, and `on_input` payloads are typed through `defineScript`, `defineGuiScript`, and `defineRenderScript`.
+- **Fits new and existing projects** — scaffold from scratch, or add the TypeScript surface to a project that already has `game.project` and adopt type safety gradually, one script at a time alongside your existing Lua.
+- **Built for the real loop** — `watch` recompiles beside the Defold editor, live transpile diagnostics surface errors inline, and source maps let you set breakpoints in your `.ts`.
+
+End-user documentation for `defold-typescript`: how to scaffold a project, write TypeScript that the toolchain compiles to Lua, and look up the language-and-toolchain quirks you will hit along the way. The repository's `README.md` covers why this project exists and the planning workflow; this folder covers how to use the toolchain.
+
+The sections below mirror the top navigation; each lists the pages in its left-sidebar order.
+
+## Get started
+
+- [Getting started](./getting-started.md) — install Bun, scaffold a new project with `bunx @defold-typescript/cli@latest init`, write a one-screen script, and build to Lua with `bunx @defold-typescript/cli build`.
+- [Starter templates](./init-templates.md) — pick a new-project layout with `init --template <name>`: the opinionated `default` or a blank-script `minimal`.
+- [Existing project](./add-typescript.md) — run `bunx @defold-typescript/cli@latest init` in a folder with `game.project` to add the TypeScript surface without replacing the Defold project.
+- [Editor setup](./editor-setup.md) — open the project in VSCode, use the generated `tsconfig.json`, and run `bunx @defold-typescript/cli watch` beside the Defold editor.
+- [Defold editor](./defold-editor.md) — install Defold, open the generated project folder, attach a compiled script (`.ts.script`, `.ts.gui_script`, or `.ts.render_script`) to its game object, GUI scene, or render pipeline, and run the game (TypeScript is transpiled to Lua by the CLI, not the editor).
+
+## Guides
+
+- [Transpile diagnostics](./transpile-diagnostics.md) — the scaffolded `@defold-typescript/tstl-plugin` language-service plugin that surfaces TypeScript-to-Lua transpile errors live in the editor, advisory-only and never blocking `tsc --noEmit`.
+- [Debugging](./debugging.md) — step through `.ts` source with breakpoints via the Local Lua Debugger and the scaffolded Bun launch path (no shell, Windows-native), resolving through the emitted `<name>.ts.script.map`.
+- [Pinning the Defold version](./pinning-defold-version.md) — keep the default latest surface, or pin an older Defold version whose API surface is generated on the fly and materialized into a project-local `.defold-types/<version>/`.
+- [Native extensions](./extensions.md) — declare an extension in `game.project` `[dependencies]`, run `defold-typescript resolve` to generate an ambient namespace per `.script_api` into a gitignored `.defold-types/extensions/` surface, and consume it with no import.
+- [Advanced CLI](./advanced-cli.md) — opt-in per-directory API walls with the `wall` command (interactive checkbox and flag forms), the full-surface-by-default policy, and the import-from-subpath rule a wall depends on.
+- [Agent runbooks](./agent-runbooks.md) — harness-neutral procedures for driving the CLI from an automated agent: scaffold a project, [install the agent contract](./agent-runbooks.md#install-the-agent-contract), regenerate extension types, [add and attach a script](./agent-runbooks.md#add-a-script) (build, wire the compiled component, verify), and fix the Lua output over the `--json` envelope, gating on `ok`.
+
+## Language
+
+- [TypeScript vs Lua](./typescript-vs-lua.md) — the Lua-developer on-ramp: a cheat sheet that translates syntax, tables, modules, and the standard library from Lua to the TypeScript the toolchain expects.
+- [Script lifecycle](./script-lifecycle.md) — type `self`, `on_message`, and `on_input` payloads with `defineScript`, `defineGuiScript`, and `defineRenderScript`.
+- [Vector math](./vector-math.md) — the method-form arithmetic surface (`add`, `sub`, `mul`, `div`, `unm`) on `Vector3`, `Vector4`, `Quaternion`, and `Matrix4`, plus why you cannot write `v3 + v3`.
+- [TypeScript gotchas](./typescript-gotchas.md) — the canonical catalog of TS / TSTL / Defold sharp edges. Today: the unary-minus quirk that silently produces `number` from a `Vector3`. Future entries land here as the toolchain encounters them.
+- [API docs vs `ts-defold-types`](./api-docs-vs-ts-defold.md) — a factual, dimension-by-dimension comparison of the JSDoc that `@defold-typescript/types` and `ts-defold-types` emit (Markdown conversion, dash params, grid-aligned multi-line docs, branded constants, the `@example` trade-off), with a picker for which surface fits your project.
+- [Migrating from `ts-defold`](./migrating-from-ts-defold.md) — move a project off the `@ts-defold/*` stack: the package/tooling map, the step-by-step port via `init` add-TypeScript mode and a `tsconfig.json` reconcile, and the type-surface differences you will hit.
+
+## Reference
+
+- [API](/api) — the generated `@defold-typescript/types` reference: every documented Defold namespace, grouped alphabetically as cards (site-only; built from the typed surface the toolchain ships).
+- [Lua standard library](/api/base) — the pure-Lua / LuaJIT reference category (`base`, `bit`, …). Types are owned by the `lua-types` dependency the `lua-stdlib-globals` goal adopted; `@defold-typescript/types` does not re-emit them as generated namespaces.
+
+## Coming later
+
+- Per-module API guide — landing with `builtin-messages-typing` and `script-lifecycle-typing`.
+- Messages guide — `msg.post` payload narrowing, builtin message IDs — landing with `builtin-messages-typing`.

package/guide/add-typescript.md

@@ -0,0 +1,57 @@
+---
+toc-title: Existing project
+---
+# Add TypeScript to an existing Defold project
+
+Use `bunx @defold-typescript/cli@latest init` inside a Defold project that already has `game.project`.
+
+```sh
+cd my-existing-defold-game
+bunx @defold-typescript/cli@latest init
+bun install
+```
+
+Scaffold with the `@latest` tag: `init` writes your `@defold-typescript/types`
+version pin, so a stale `bunx` cache would pin an older release. Then run
+`bun install` once — `init` only declares the dev dependencies below; `install`
+is what puts them in `node_modules` so the editor can resolve the Defold types.
+
+The package is scoped — run it as `@defold-typescript/cli`. The bare
+`bunx defold-typescript` resolves a nonexistent unscoped package and 404s unless
+you have already installed `@defold-typescript/cli` locally.
+
+When `game.project` exists, `init` does not synthesize a new Defold project. It only writes the TypeScript surface:
+
+- `src/main.ts` — a starter entry script, written only when absent. `main.ts` is your source, not managed config, so an existing one is left untouched (and omitted from the reported `written` list) even under `--force`.
+- `tsconfig.json`
+- `package.json`
+
+If `package.json` already exists, the command preserves its existing fields and merges these dev dependencies when they are missing:
+
+- `@defold-typescript/types` — pinned to the CLI's own published version (the packages release in lockstep). This is the only `@defold-typescript/*` package your project needs; it is type-only and feeds the editor. The transpiler is a dependency of the CLI itself, pulled in when you run `build`/`watch`, so the scaffold does not add it.
+- `@biomejs/biome`
+
+If `package.json` does not exist, the command creates one.
+
+## Conflicting config files
+
+`init` refuses to overwrite an existing TypeScript or defold-typescript config. Remove or move the conflicting file before running the command.
+
+Conflicts today are:
+
+- `tsconfig.json`
+- `defold-typescript.config.ts`
+- `defold-typescript.config.mts`
+- `defold-typescript.config.js`
+
+Pass `--force` to overwrite a conflicting TS config (in new-project mode, `--force` also lets `init` synthesize into a non-empty directory). `--force` overwrites the config wholesale; it does not merge fields, so any settings you had in `tsconfig.json` are replaced by the scaffold config. `--force` refreshes managed config only — it never overwrites `src/main.ts`, since that file is your source.
+
+## Build the Lua output
+
+After initialization, write TypeScript under `src/` and run:
+
+```sh
+bunx @defold-typescript/cli build
+```
+
+The default `tsconfig.json` type-checks against `@defold-typescript/types` and writes generated Lua next to each `.ts` source. Files that call a lifecycle factory become Defold components: `defineScript` writes `<name>.ts.script`, `defineGuiScript` writes `<name>.ts.gui_script`, and `defineRenderScript` writes `<name>.ts.render_script`. Helper modules with no lifecycle factory write plain Lua modules such as `src/util.lua`, matching the `require(...)` path emitted for TypeScript imports. The scaffold also drops a `.gitignore` so generated component files, helper `.lua` modules under `src/`, and their `.map` siblings stay out of version control. Set a concrete `outDir` to collect the outputs under a separate tree instead.

package/guide/advanced-cli.md

@@ -0,0 +1,101 @@
+---
+toc-title: Advanced CLI
+---
+# Advanced CLI
+
+This page covers `wall`, the opt-in command for narrowing the API surface of a
+source directory to a single script kind.
+
+## Full surface by default
+
+Defold scopes two namespaces to a script kind: `gui.*` resolves only inside a
+`.gui_script`, and `render.*` only inside a `.render_script`. Every other
+namespace (`go`, `msg`, `vmath`, `sys`, `physics`, …) is available in every kind.
+
+By default `defold-typescript` gives you the **full** `@defold-typescript/types`
+surface everywhere. `init`, `build`, and `watch` never change this: they scaffold
+and build against whatever entrypoint your `tsconfig` names and never add, remove,
+or prune a wall. The full surface never rejects a call the engine would allow, but
+it also can't catch a `gui.*` use in a plain `.script`. To get the engine's wall
+at compile time, opt in with `wall`.
+
+## What a wall is
+
+A wall is a composite `tsconfig.json` written into a single-kind source directory
+that narrows `compilerOptions.types` to that kind's subpath:
+
+| Script kind | `types` entrypoint | Namespaces |
+| ----------- | ------------------ | ---------- |
+| `.script` | `@defold-typescript/types/script` | universal only |
+| `.gui_script` | `@defold-typescript/types/gui-script` | universal + `gui` |
+| `.render_script` | `@defold-typescript/types/render-script` | universal + `render` |
+
+The root `tsconfig.json` references each walled directory and excludes it from the
+root program, so `tsc -b --noEmit` builds every walled directory against only its
+narrowed surface — a `render.*` use inside a gui-walled directory becomes a compile
+error, while the rest of the project stays full-surface.
+
+A directory is **eligible** to be walled only when every `.ts` source in it is one
+kind; a directory mixing kinds cannot be walled, because no single narrowing
+applies. `build` and `watch` never touch walls — they are entirely yours to
+manage.
+
+## Interactive
+
+Run `wall` with no arguments in a terminal:
+
+```sh
+bunx @defold-typescript/cli wall
+```
+
+You get a checkbox of every eligible source directory, pre-checked to the
+directories already walled. Checking an unwalled directory walls it; unchecking a
+walled directory removes its wall. Mixed-kind directories appear disabled, with
+their competing kinds shown as the reason. The final selection **is** the desired
+wall set — the command reconciles the project on disk to exactly what you checked.
+
+## Flags
+
+For agents, CI, and scripted use, pass directories explicitly (a bare `wall` with
+no TTY errors rather than hanging on an unrenderable prompt):
+
+```sh
+# Wall these directories (added to any already walled)
+bunx @defold-typescript/cli wall src/ui src/rendering
+
+# Remove a wall
+bunx @defold-typescript/cli wall --remove src/ui
+
+# List current and eligible walls (writes nothing)
+bunx @defold-typescript/cli wall --list
+bunx @defold-typescript/cli wall --list --json
+```
+
+`--json` emits the resulting `directoryWalls` (and, for `--list`, the `eligible`
+set) for machine consumption. `--json` is machine-driven intent, so a bare
+`wall --json` never opens the interactive menu — pass directories or `--list`.
+
+## Import the factory from the kind subpath
+
+A wall only holds if a walled source imports its lifecycle factory from the **kind
+subpath**, not the main entry:
+
+```ts
+// src/ui/hud.ts — inside a gui wall
+import { defineGuiScript } from "@defold-typescript/types/gui-script"; // correct
+```
+
+Importing the same factory from the main `@defold-typescript/types` entry pulls
+*every* `declare global` namespace (including `render`) into the wall's program and
+silently defeats the narrowing — `render.*` would type-check inside a gui wall:
+
+```ts
+// Wrong: re-introduces the full surface, defeating the wall
+import { defineGuiScript } from "@defold-typescript/types";
+```
+
+The interactive snippets scaffolded by `init` already import from the kind
+subpaths. `build` enforces this: a walled source that imports a lifecycle factory
+from the main entry fails the build before transpile, naming the file and the kind
+subpath it should import from instead. (`watch` does not enforce it yet — its
+session path is a separate slice.)

package/guide/agent-runbooks.md

@@ -0,0 +1,357 @@
+---
+toc-title: Agent runbooks
+---
+# Agent runbooks
+
+Harness-neutral procedures for driving `defold-typescript` from an automated
+agent. `defold-typescript` is a CLI published to npm (run with `bunx`) plus a
+types package; it ships no
+harness-specific skill or command assets, so the durable interface for an agent
+is the CLI verbs themselves and their machine-readable `--json` output. Every
+runbook below works from any harness: run the command, read the JSON envelope on
+stdout, gate on `ok`.
+
+Each one-shot command (`init`, `build`, `resolve`) prints a single JSON object
+when given `--json`. The envelope is always one of two shapes:
+
+```json
+{ "command": "<verb>", "ok": true, "written": ["<path>", "..."] }
+```
+
+```json
+{ "command": "<verb>", "ok": false, "error": "<message>" }
+```
+
+The agent branches on `ok`: on `true`, read `written` for the paths the command
+created or updated; on `false`, read `error` for the failure reason. Some verbs
+add fields to the success envelope (noted per runbook), but `command`, `ok`, and
+either `written` or `error` are always present.
+
+## Scaffold a project
+
+**Goal:** create a new TypeScript surface — either a fresh project, or the
+TypeScript layer added to an existing Defold project.
+
+**Command (fresh project, empty folder):**
+
+```sh
+bunx @defold-typescript/cli@latest init --json
+```
+
+**Command (existing Defold project — run inside the folder that holds
+`game.project`):**
+
+```sh
+bunx @defold-typescript/cli@latest init --json
+```
+
+`init` detects whether a `game.project` is already present and either scaffolds a
+whole new project or adds the TypeScript surface alongside the existing one.
+
+**Returns:**
+
+```json
+{ "command": "init", "ok": true, "written": ["tsconfig.json", "src/main.ts", "..."] }
+```
+
+On failure:
+
+```json
+{ "command": "init", "ok": false, "error": "<message>" }
+```
+
+**Reading `ok`:** if `ok` is `true`, the scaffold succeeded and `written` lists
+every file created or modified — use it to know what to open next. If `ok` is
+`false`, stop and surface `error`; nothing was scaffolded.
+
+## Install the agent contract
+
+**Goal:** drop an agent contract at the project root so any harness (or human)
+opening the repo finds the conventions and a pointer to the installed guide.
+
+**Command:**
+
+```sh
+bunx @defold-typescript/cli@latest init-agents --json
+```
+
+This writes two files. `AGENTS.md` carries a managed block delimited by HTML
+comment markers; `CLAUDE.md` is the single line `@AGENTS.md`, re-exporting it.
+Only the content **between** the markers is ever rewritten, so any notes you add
+above or below the block survive re-runs untouched. If `AGENTS.md` already exists
+without the markers, the block is appended after one blank line and your prior
+content is left intact; a `CLAUDE.md` that already equals `@AGENTS.md` is left
+byte-for-byte unchanged. The block is versionless — its guide pointer resolves to
+`node_modules/@defold-typescript/cli/docs/guide/README.md`, which the install
+swaps under the same path — so the verb is safe to re-run any time.
+
+**Returns:**
+
+```json
+{ "command": "init-agents", "ok": true, "written": ["AGENTS.md", "CLAUDE.md"] }
+```
+
+On failure:
+
+```json
+{ "command": "init-agents", "ok": false, "error": "<message>" }
+```
+
+**Reading `ok`:** if `ok` is `true`, `written` lists the files touched in order;
+a re-run that changes nothing omits the untouched file. If `ok` is `false`, stop
+and surface `error`; nothing was written.
+
+## Regenerate extension types
+
+**Goal:** refresh the ambient TypeScript surface for native extensions after a
+`game.project` `[dependencies]` change, so extension namespaces stay in sync with
+the declared archives. This automates the workflow described in
+[Typing native extensions](./extensions.md).
+
+**Command (run from the project root, after editing `[dependencies]`):**
+
+```sh
+defold-typescript resolve --json
+```
+
+`resolve` reads each declared extension's `.script_api`, regenerates the
+gitignored `.defold-types/extensions/` ambient surface, and rewrites its index
+and `package.json` to exactly the declared set.
+
+**Returns** the same one-shot envelope keyed `command: "resolve"`, plus an
+`extensions` array reporting provenance for each resolved dependency:
+
+```json
+{
+  "command": "resolve",
+  "ok": true,
+  "written": [".defold-types/extensions/<namespace>.d.ts", "..."],
+  "extensions": [
+    {
+      "url": "<archive url>",
+      "provenance": "<cache | download>",
+      "namespaces": ["<namespace>"],
+      "scriptApiCount": 1,
+      "assetOnly": false
+    }
+  ]
+}
+```
+
+On failure:
+
+```json
+{ "command": "resolve", "ok": false, "error": "<message>" }
+```
+
+**Reading `ok`:** if `ok` is `true`, the extension surface is current — `written`
+lists the regenerated declaration files, and `extensions` records where each one
+came from (`provenance`) and how many `.script_api` files it contributed
+(`scriptApiCount`); an `assetOnly` dependency contributes no types. If `ok` is
+`false`, surface `error`; the existing surface is left untouched.
+
+## Add a script
+
+**Goal:** add a new gameplay script to a TypeScript Defold project and attach it
+so it runs. There is no `add` verb — the workflow composes ordinary file
+creation with the shipped `build` verb, then a scene-file edit to wire the
+compiled component.
+
+**1. Write the source.** One Defold script per file under `src/`, exporting a
+single lifecycle factory as `default` (never two in one file). The factory
+decides the compiled kind:
+
+| Source factory | Compiled artifact | Referenced by |
+| -------------- | ----------------- | ------------- |
+| `defineScript` | `<name>.ts.script` | a game object (`.go` / `.collection`) as a component |
+| `defineGuiScript` | `<name>.ts.gui_script` | a GUI scene (`.gui`), as its **Script** property |
+| `defineRenderScript` | `<name>.ts.render_script` | the render pipeline (a `.render` file, set via `game.project`) |
+
+A source that calls no factory emits a plain `<name>.lua` module to `import`
+instead. Which hooks to export (`init`, `update`, `fixed_update`, `on_message`,
+`on_input`, `final`, …) and how `self` is typed are covered in
+[Script lifecycle](./script-lifecycle.md).
+
+**2. Build** (from the project root):
+
+```sh
+bunx @defold-typescript/cli@latest build --json
+```
+
+Or, if a [`watch --json`](#fix-the-lua-output) is already running, just save the
+file and read its `rebuild` event instead of invoking `build`.
+
+**Returns** the one-shot envelope keyed `command: "build"`, plus the build
+context fields:
+
+```json
+{
+  "command": "build",
+  "ok": true,
+  "written": ["src/<name>.ts.script", "..."],
+  "defoldVersion": "<version>",
+  "defoldChannel": "<stable | beta | alpha>",
+  "apiSurface": "<surface id>",
+  "materializedSurface": "<path | null>"
+}
+```
+
+On failure:
+
+```json
+{ "command": "build", "ok": false, "error": "<message>" }
+```
+
+**Reading `ok`:** if `ok` is `true`, the script transpiled — `written` lists the
+emitted artifact (`.ts.script`, `.ts.gui_script`, or `.ts.render_script`) to
+attach next; `defoldVersion` and `apiSurface` record which API surface it was
+built against; `defoldChannel` records the resolved release channel (`stable`
+unless pinned or passed via `--channel`; it does not yet change which surface is
+fetched). If `ok` is `false`, the build failed — surface `error` and follow
+[Fix the Lua output](#fix-the-lua-output).
+
+**What `build` writes.** Each `.ts` source under `src/` produces exactly one
+output in the Defold project tree — a script component or a `<name>.lua` module,
+per the table above. `import` is rewritten to `require("<module>")` resolving
+against the emitted `.lua`, so a shared module must be built for its require to
+resolve at runtime. Two runtime modules are synthesized at the output root on
+demand: `lualib_bundle.lua` (when a source uses a TS runtime helper like
+`Object.keys` or spread) and `defold_typescript_timers.lua` (when timers are
+used).
+
+Who creates these: typescript-to-lua (TSTL) produces the Lua *content* in
+memory; the CLI writes the *files*, choosing the `.ts.script` / `.ts.gui_script`
+/ `.ts.render_script` / `.lua` name and location. TSTL never touches disk — that
+is why the outputs carry Defold-correct extensions instead of plain `.lua`.
+Treat the `--json` `written` array as the authoritative list of what landed; do
+not infer paths.
+
+**3. Attach the compiled script.** Building only produces the artifact; nothing
+runs until a scene references it as a component. Scene files (`.go`,
+`.collection`, `.gui`, `.render`) reference the **compiled** artifact, never the
+`.ts` source. A game object references a `.ts.script` through a `components { … }`
+entry naming its project-root-absolute path:
+
+```
+components {
+  id: "player"
+  component: "/src/player.ts.script"
+}
+```
+
+In a standalone `.go` the block appears verbatim. When the game object is
+embedded in a `.collection`, Defold stores the same block as an escaped string
+inside an `embedded_instances { data: "…" }` entry — the form to write when
+editing the file directly. The platformer example shows this in
+[`game/player.collection`](../examples/platformer/game/player.collection):
+
+```
+embedded_instances {
+  id: "player"
+  data: "components {\n"
+  "  id: \"player\"\n"
+  "  component: \"/src/player.ts.script\"\n"
+  ...
+  "}\n"
+  ...
+}
+```
+
+A `.ts.gui_script` is referenced by a `.gui` scene's **Script** property and a
+`.ts.render_script` by the render pipeline, the same compiled-artifact rule.
+
+**4. Verify the attachment.** Two checks confirm the script is wired in:
+
+- Grep the scene files for the compiled name:
+
+  ```sh
+  grep -rl "player.ts.script" --include="*.go" --include="*.collection" --include="*.gui" .
+  ```
+
+  A hit means a scene references it; no hit means it is orphaned and will not
+  run.
+
+- Defold compiles only **reachable** resources, so after a Defold build
+  (the CLI's `defold build` subcommand) an attached script produces `build/default/src/player.ts.scriptc`
+  — the path mirrors the source — while an orphaned script never appears under
+  `build/default/` at all. (The `_generated_*` artifacts there are inlined or
+  asset-derived resources — embedded game objects, components, textures — never
+  referenced script files, which keep their source path.)
+
+## Narrow engine callback payloads
+
+**Goal:** type an engine callback's untyped payload without hand-rolling `typeof`/`in`/`as`.
+
+**Rule for clankers:** when an engine callback hands back an untyped or `unknown`
+payload that is discriminated by a *separate* id/event argument, reach for the
+**provided declaration-only guard** before reaching for `typeof`/`in`/`as`.
+TypeScript cannot correlate two independent parameters, and Defold's ids/event
+constants are pre-hashed `Hash` values or branded numbers — neither works as a
+discriminated-union tag. Each guard below re-introduces the discriminant at the
+use site. They are all **declaration-only**: the transpiler lowers each call to
+its runtime comparison, so there is no runtime Lua symbol and **no import to
+add**.
+
+`on_message` — narrow one message with `isMessage`, or route many with `onMessage`:
+
+```ts
+export default defineScript({
+  on_message(self, message_id, message) {
+    if (isMessage(message_id, message, "contact_point_response")) {
+      // message narrowed to the contact_point_response payload — no cast.
+      print(message.distance);
+    }
+  },
+});
+```
+
+`window.set_listener` — narrow the callback's `data` with `isWindowEvent`:
+
+```ts
+window.set_listener((self, event, data) => {
+  if (isWindowEvent(event, data, window.WINDOW_EVENT_RESIZED)) {
+    // data narrowed to { width: number; height: number } — no cast.
+    print(data.width, data.height);
+  }
+});
+```
+
+An unknown id/event constant is a compile error, so the guard also catches typos.
+The full narrowing reference, including `onMessage`'s multi-message dispatcher,
+lives in [Script lifecycle](./script-lifecycle.md#receiving-messages-with-type-narrowing)
+and the [`window.set_listener` gotcha](./typescript-gotchas.md#windowsetlistener-hands-event-and-data-as-separate-params).
+
+## Fix the Lua output
+
+**Goal:** recover from a transpile failure reported by `build` or `watch`.
+
+**Command (re-run after each source fix):**
+
+```sh
+bunx @defold-typescript/cli@latest build --json
+```
+
+On a transpile failure the one-shot `build --json` envelope carries the message:
+
+```json
+{ "command": "build", "ok": false, "error": "<message>" }
+```
+
+Under a long-lived `watch --json`, the same failure arrives as an NDJSON event on
+stdout (one JSON object per line) keyed `command: "watch"`:
+
+```json
+{ "command": "watch", "event": "rebuild", "ok": false, "error": "<message>" }
+```
+
+The first build emits `event: "build"`; each later rebuild emits
+`event: "rebuild"`. `build` and the transpile-diagnostics pass share one
+diagnostic run, so the `error` names the offending source span.
+
+**Reading `ok`:** while `ok` is `false`, read `error` for the failing span,
+then fix the source and rebuild. Two pages route the fix:
+[TypeScript gotchas](./typescript-gotchas.md) for the runtime-semantics traps
+that compile clean but surprise under Lua, and
+[Transpile diagnostics](./transpile-diagnostics.md) for what the diagnostic pass
+surfaces. Repeat until `ok` is `true`, then read `written` as in
+[Add a script](#add-a-script).