@defold-typescript/types 0.50.0 → 0.51.0

package/src/emit-messages.ts

@@ -137,6 +137,295 @@ export function applyMessageFieldCorrections(
   return { entries };
 }
 
+// What only the engine states about a message the catalog mirrors from the
+// reference: proto optionality, a field the handler reads or the sender fills,
+// a message a component handles or posts, or the shape of a field the reference
+// types only as `table`. `evidence` names `<path>:<symbol>` in the 1.14.0 engine
+// source. Each kind throws once the catalog already states its fact, since that
+// means upstream fixed the reference and the entry is deleted; a `retype` throws
+// once the catalog stops declaring its pinned `upstream` types, since upstream
+// retyped the field and the entry is re-verified against what it now says.
+export type MessageEngineCorrection = {
+  readonly origin: string;
+  readonly name: string;
+  readonly evidence: string;
+} & (
+  | { readonly kind: "optional" | "required"; readonly fields: readonly string[] }
+  | { readonly kind: "add-field"; readonly fields: readonly MessageField[] }
+  | {
+      readonly kind: "add-message";
+      readonly description: string;
+      readonly fields: readonly MessageField[];
+    }
+  | {
+      readonly kind: "retype";
+      readonly fields: readonly string[];
+      readonly tsType: string;
+      readonly upstream: readonly string[];
+    }
+);
+
+const SCRIPT_DDF_DEFAULTS =
+  "script/src/script_ddf.cpp:DoLuaTableToDDF fills an omitted optional field with its default";
+const SOUND_EVENT =
+  "gamesys/src/gamesys/components/comp_sound.cpp:DispatchSoundEvent always sets play_id, and HandleEntryFinishedPlaying sends the event only for a play_sound that supplied one";
+
+function optionalField(name: string, types: string[], doc: string): MessageField {
+  return { name, types, optional: true, doc };
+}
+
+function requiredField(name: string, types: string[], doc: string): MessageField {
+  return { name, types, optional: false, doc };
+}
+
+// The listener and `on_message` paths agree: the DDF the message carries
+// declares the same sub-message fields the listener push sets.
+function physicsBody(message: string): string {
+  return `gamesys/proto/gamesys/physics_ddf.proto:${message} declares the same required fields for the on_message payload`;
+}
+
+function otherGroupField(): MessageField {
+  return {
+    name: "group",
+    types: ["hash"],
+    optional: false,
+    doc: "Collision group of the other object, equal to other_group.",
+  };
+}
+
+export const MESSAGE_ENGINE_CORRECTIONS: readonly MessageEngineCorrection[] = [
+  {
+    kind: "optional",
+    origin: "camera",
+    name: "set_camera",
+    fields: ["orthographic_projection", "orthographic_zoom", "orthographic_mode"],
+    evidence: `gamesys/proto/gamesys/camera_ddf.proto:SetCamera declares them optional with defaults, CompCameraOnMessage handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "sys",
+    name: "reboot",
+    fields: ["arg1", "arg2", "arg3", "arg4", "arg5", "arg6"],
+    evidence: `script/src/script/sys_ddf.proto:Reboot declares every argument optional, engine/src/engine.cpp:Dispatch handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "sys",
+    name: "start_record",
+    fields: ["frame_period", "fps"],
+    evidence: `script/src/script/sys_ddf.proto:StartRecord declares both optional with defaults 2 and 30, engine/src/engine.cpp:Dispatch handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "sprite",
+    name: "play_animation",
+    fields: ["offset", "playback_rate"],
+    evidence: `gamesys/proto/gamesys/sprite_ddf.proto:PlayAnimation declares both optional with defaults 0 and 1, comp_sprite.cpp:CompSpriteOnMessage passes both to PlayAnimation, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "go",
+    name: "set_parent",
+    fields: ["parent_id", "keep_world_transform"],
+    evidence: `gameobject/proto/gameobject/gameobject_ddf.proto:SetParent declares both optional with defaults 0 and 1, gameobject.cpp:DispatchMessagesFunction handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "required",
+    origin: "sound",
+    name: "sound_done",
+    fields: ["play_id"],
+    evidence: SOUND_EVENT,
+  },
+  {
+    kind: "required",
+    origin: "sound",
+    name: "sound_stopped",
+    fields: ["play_id"],
+    evidence: SOUND_EVENT,
+  },
+  {
+    kind: "add-field",
+    origin: "sound",
+    name: "play_sound",
+    fields: [
+      optionalField("pan", ["number"], "Pan between -1 and 1, added to the component's pan."),
+      optionalField("speed", ["number"], "Speed factor, multiplied with the component's speed."),
+    ],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:PlaySound declares pan and speed, and comp_sound.cpp:CompSoundOnMessage applies both to the voice",
+  },
+  {
+    kind: "add-field",
+    origin: "sound",
+    name: "stop_sound",
+    fields: [
+      optionalField(
+        "play_id",
+        ["number"],
+        "Id passed to play_sound; stops only that voice. Omit to stop every voice.",
+      ),
+    ],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:StopSound declares play_id, and comp_sound.cpp:CompSoundOnMessage stops only the voice that matches it",
+  },
+  {
+    kind: "add-message",
+    origin: "sound",
+    name: "pause_sound",
+    description: "Pause or resume every voice the receiving sound component plays.",
+    fields: [optionalField("pause", ["boolean"], "true (default) to pause, false to resume.")],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:PauseSound declares pause, and comp_sound.cpp:CompSoundOnMessage pauses every voice of the component",
+  },
+  {
+    kind: "add-message",
+    origin: "sound",
+    name: "set_pan",
+    description: "Set the pan on the receiving sound component.",
+    fields: [optionalField("pan", ["number"], "Pan between -1 and 1, default 0.")],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:SetPan declares pan, and comp_sound.cpp:CompSoundOnMessage sets the component's pan",
+  },
+  {
+    kind: "add-message",
+    origin: "render",
+    name: "set_view_projection",
+    description:
+      "Posted automatically by camera components to the render script with the active view and projection matrices.",
+    fields: [
+      requiredField("id", ["hash"], "Id of the camera component that posted the matrices."),
+      requiredField("view", ["matrix4"], "View matrix of the camera."),
+      requiredField("projection", ["matrix4"], "Projection matrix of the camera."),
+    ],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:SetViewProjection declares id, view and projection required, and comp_camera.cpp:PostRenderScriptSetViewProjectionMsg posts it to the render socket on every camera update",
+  },
+  {
+    kind: "add-field",
+    origin: "physics",
+    name: "collision_response",
+    fields: [otherGroupField()],
+    evidence:
+      "gamesys/proto/gamesys/physics_ddf.proto:CollisionResponse declares a required group, and comp_collision_object.cpp:CollisionCallback sets it to the other object's group",
+  },
+  {
+    kind: "add-field",
+    origin: "physics",
+    name: "contact_point_response",
+    fields: [otherGroupField()],
+    evidence:
+      "gamesys/proto/gamesys/physics_ddf.proto:ContactPointResponse declares a required group, and comp_collision_object.cpp:ContactPointCallback sets it to the other object's group",
+  },
+  {
+    kind: "add-field",
+    origin: "physics",
+    name: "trigger_response",
+    fields: [otherGroupField()],
+    evidence:
+      "gamesys/proto/gamesys/physics_ddf.proto:TriggerResponse declares a required group, and comp_collision_object.cpp:TriggerEnteredCallback sets it to the other object's group",
+  },
+  {
+    kind: "retype",
+    origin: "physics",
+    name: "contact_point_event",
+    fields: ["a", "b"],
+    tsType:
+      "{ position: Vector3; instance_position: Vector3; normal: Vector3; relative_velocity: Vector3; mass: number; id: Hash; group: Hash }",
+    upstream: ["table"],
+    evidence: `gamesys/src/gamesys/scripts/script_physics.cpp:PushContactPoint sets these seven fields on each body, and ${physicsBody("ContactPoint")}`,
+  },
+  {
+    kind: "retype",
+    origin: "physics",
+    name: "collision_event",
+    fields: ["a", "b"],
+    tsType: "{ position: Vector3; id: Hash; group: Hash }",
+    upstream: ["table"],
+    evidence: `gamesys/src/gamesys/scripts/script_physics.cpp:PushCollision sets these three fields on each body, and ${physicsBody("Collision")}`,
+  },
+  {
+    kind: "retype",
+    origin: "physics",
+    name: "trigger_event",
+    fields: ["a", "b"],
+    tsType: "{ id: Hash; group: Hash }",
+    upstream: ["table"],
+    evidence: `gamesys/src/gamesys/scripts/script_physics.cpp:PushTrigger sets these two fields on each body, and ${physicsBody("Trigger")}`,
+  },
+];
+
+export function applyMessageEngineCorrections(
+  catalog: MessageCatalog,
+  overlay: readonly MessageEngineCorrection[] = MESSAGE_ENGINE_CORRECTIONS,
+): MessageCatalog {
+  const entries = catalog.entries.map((entry) => ({
+    ...entry,
+    payload: entry.payload.map((field) => ({ ...field })),
+  }));
+  for (const correction of overlay) {
+    const identity = `(origin=${correction.origin}, name=${correction.name})`;
+    const stale = (fact: string) =>
+      new Error(
+        `applyMessageEngineCorrections: the catalog ${fact} for ${identity}; delete the correction`,
+      );
+    const entry = entries.find(
+      (candidate) => candidate.origin === correction.origin && candidate.name === correction.name,
+    );
+    if (correction.kind === "add-message") {
+      if (entry) throw stale("already declares message");
+      entries.push({
+        name: correction.name,
+        origin: correction.origin,
+        description: correction.description,
+        payload: correction.fields.map((field) => ({ ...field, types: [...field.types] })),
+      });
+      continue;
+    }
+    if (!entry) {
+      throw new Error(`applyMessageEngineCorrections: no catalog message matches ${identity}`);
+    }
+    if (correction.kind === "add-field") {
+      for (const field of correction.fields) {
+        if (entry.payload.some((candidate) => candidate.name === field.name)) {
+          throw stale(`already declares field ${field.name}`);
+        }
+        entry.payload.push({ ...field, types: [...field.types] });
+      }
+      continue;
+    }
+    for (const name of correction.fields) {
+      const field = entry.payload.find((candidate) => candidate.name === name);
+      if (!field) {
+        throw new Error(
+          `applyMessageEngineCorrections: no catalog field matches ${identity} field=${name}`,
+        );
+      }
+      if (correction.kind === "retype") {
+        if (field.types.join("|") !== correction.upstream.join("|")) {
+          throw new Error(
+            `applyMessageEngineCorrections: the catalog now declares ${field.types.join("|")} for field ${name} of ${identity}, not the pinned ${correction.upstream.join("|")}; re-verify the correction`,
+          );
+        }
+        field.types = [correction.tsType];
+        continue;
+      }
+      const optional = correction.kind === "optional";
+      if (field.optional === optional) throw stale(`field ${name} is already ${correction.kind}`);
+      field.optional = optional;
+    }
+  }
+  return { entries };
+}
+
+// The built-in message surface is the catalog plus these overlays. Every reader
+// of it goes through here, so a message the engine overlay adds is never missing
+// from one of them.
+export function applyMessageOverlays(catalog: MessageCatalog): MessageCatalog {
+  return applyMessageEngineCorrections(
+    applyMessageFieldCorrections(applyMessageDeprecations(catalog)),
+  );
+}
+
 const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const ENGINE_TYPES = [
   "Hash",

package/src/engine-globals.d.ts

@@ -36,7 +36,7 @@ declare global {
   type Opaque<Name extends string> = Core.Opaque<Name>;
   /** A message-passing address with `socket`, `path`, and `fragment`; see {@link Core.Url}. */
   type Url = Core.Url;
-  /** A read-only numeric vector accessed by index; see {@link Core.Vector}. */
+  /** A numeric vector read and written by 1-based index; see {@link Core.Vector}. */
   type Vector = Core.Vector;
   /** A three-component vector with `x`, `y`, `z`; see {@link Core.Vector3}. */
   type Vector3 = Core.Vector3;
@@ -46,4 +46,6 @@ declare global {
   type Quaternion = Core.Quaternion;
   /** A 4x4 transformation matrix; see {@link Core.Matrix4}. */
   type Matrix4 = Core.Matrix4;
+  /** An array constant read back from a constant buffer, 1-based with no length; see {@link Core.ConstantArray}. */
+  type ConstantArray<T> = Core.ConstantArray<T>;
 }

package/src/go-overloads.d.ts

@@ -1,6 +1,6 @@
 /** @noSelfInFile */
 
-import type { Hash, Quaternion, Url, Vector3, Vector4 } from "./core-types";
+import type { Hash, Matrix4, Quaternion, Url, Vector3, Vector4 } from "./core-types";
 
 interface ScriptProperty<TValue> {
   readonly __defoldScriptProperty: TValue;
@@ -61,7 +61,7 @@ declare global {
       url: SceneAddress | Hash | Url,
       property: string | Hash,
       options?: GoPropertyOptions,
-    ): number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion;
+    ): number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion | Matrix4;
     /**
      * sets a named property of the specified game object or component, or a material constant
      *
@@ -97,7 +97,17 @@ declare global {
     function set(
       url: SceneAddress | Hash | Url,
       property: string | Hash,
-      value: number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion | Vector4[],
+      value:
+        | number
+        | boolean
+        | string
+        | Hash
+        | Url
+        | Vector3
+        | Vector4
+        | Quaternion
+        | Matrix4
+        | Vector4[],
       options?: GoPropertyOptions,
     ): void;
     /**

package/src/lifecycle.ts

@@ -7,51 +7,51 @@ export interface InputTouch {
   /**
    * Identifier for the touch during its lifetime.
    */
-  id?: number;
+  id: number;
   /**
    * Whether the finger was pressed this frame.
    */
-  pressed?: boolean;
+  pressed: boolean;
   /**
    * Whether the finger was released this frame.
    */
-  released?: boolean;
+  released: boolean;
   /**
    * Number of taps, such as one for a single tap and two for a double tap.
    */
-  tap_count?: number;
+  tap_count: number;
   /**
    * Touch x-coordinate.
    */
-  x?: number;
+  x: number;
   /**
    * Touch y-coordinate.
    */
-  y?: number;
+  y: number;
   /**
    * Change in the touch x-coordinate.
    */
-  dx?: number;
+  dx: number;
   /**
    * Change in the touch y-coordinate.
    */
-  dy?: number;
+  dy: number;
   /**
    * Touch x-coordinate in screen space.
    */
-  screen_x?: number;
+  screen_x: number;
   /**
    * Touch y-coordinate in screen space.
    */
-  screen_y?: number;
+  screen_y: number;
   /**
    * Change in the touch x-coordinate in screen space.
    */
-  screen_dx?: number;
+  screen_dx: number;
   /**
    * Change in the touch y-coordinate in screen space.
    */
-  screen_dy?: number;
+  screen_dy: number;
 }
 
 // Fields and docs follow the go ref-doc's `on_input.action` STRUCT, whose keys are
@@ -363,7 +363,7 @@ export type GuiScriptHooks<TSelf, TInitState = TSelf> = Omit<
 
 export type RenderScriptHooks<TSelf, TInitState = TSelf> = Omit<
   ScriptHooks<TSelf, TInitState>,
-  "on_input"
+  "on_input" | "final" | "fixed_update" | "late_update"
 >;
 
 // The factory hook table plus the value-keyed `properties` field. `TProps` is
@@ -547,9 +547,9 @@ export function defineGuiScript<
  * {@link defineScript}, and is erased by the transpiler's `lifecycle-erasure`
  * pass into the flat Defold chunk shape.
  *
- * `RenderScriptHooks` is `Omit<ScriptHooks, "on_input">` — render scripts do not
- * receive input. It accepts the rest of the set, all optional: `init`,
- * `update`, `fixed_update`, `late_update`, `on_message`, `final`, `on_reload`.
+ * `RenderScriptHooks` is `Omit<ScriptHooks, "on_input" | "final" |
+ * "fixed_update" | "late_update">` — the engine calls only four render-script
+ * hooks, all optional: `init`, `update`, `on_message`, `on_reload`.
  *
  * Scaffold it with the `def-ts-defineRenderScript-inferred-self` / `def-ts-defineRenderScript-typed-self` VSCode snippets
  * from `defold-typescript init`.

package/src/luals-type-expr.ts

@@ -334,6 +334,11 @@ export function mapLualsExpression(
   return { ts: mapToken(token, walk), unknowns: walk.unknowns };
 }
 
+/** Whether a raw token is a typed LuaLS `fun(...)` expression rather than a bare `function(...)`. */
+export function isLualsFunctionToken(token: string): boolean {
+  return /^fun\s*\(/.test(token.trim());
+}
+
 /**
  * Map a `fun(...)` expression to a TypeScript **call signature** — the colon-return
  * form `(params): ret` an interface uses to become callable, not the `=>` arrow a
@@ -345,7 +350,7 @@ export function mapLualsCallSignatureExpression(
   position: LualsPosition = "output",
 ): LualsMapResult {
   const trimmed = token.trim();
-  if (!/^fun\s*\(/.test(trimmed)) {
+  if (!isLualsFunctionToken(trimmed)) {
     throw new Error(`mapLualsCallSignature: expected a "fun(...)" token, got "${token}".`);
   }
   const walk: Walk = { resolveLeaf, unknowns: [], position };

package/src/physics-event-guard.d.ts

@@ -0,0 +1,39 @@
+/** @noSelfInFile */
+import type { Hash } from "./core-types";
+
+// `physics.set_event_listener` sets `type` on every event to its message-name
+// hash (script_physics.cpp), but a `Hash` is an object type, not a unit type, so
+// an `event.type == hash("…")` check cannot narrow the event union. This guard
+// re-introduces the literal at the use site. The transpiler lowers the call to
+// `event.type == hash("…")` (physics-event-guard-lowering.ts), so this package
+// emits no runtime Lua. It names no `physics` type, so it compiles on a surface
+// whose reference declares no event union.
+type PhysicsEventName<E> = E extends { type: Hash<infer N> } ? N : never;
+
+declare global {
+  /**
+   * Type guard for a `physics.set_event_listener` callback: narrows one event
+   * to the member of the event union whose `type` is the hash of `name`. The
+   * engine sets `type` on every event, but a `Hash` cannot act as a union
+   * discriminant, so an `event.type == hash("collision_event")` check leaves the
+   * event unnarrowed — this guard re-introduces the literal.
+   *
+   * @param event - one entry of the `events` array the listener received.
+   * @param name - the event's message name (e.g. `"collision_event"`).
+   * @returns `true` when `event.type` is `hash(name)`, narrowing `event` to that event.
+   * @example
+   * ```ts
+   * physics.set_event_listener((self, events) => {
+   *   for (const event of events) {
+   *     if (isPhysicsEvent(event, "collision_event")) {
+   *       print(event.a.id, event.b.id);
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  function isPhysicsEvent<E extends { type: Hash }, K extends PhysicsEventName<E>>(
+    event: E,
+    name: K,
+  ): event is Extract<E, { type: Hash<K> }>;
+}

package/src/render-overloads.d.ts

@@ -12,7 +12,7 @@ declare global {
      * @param parameters - table of buffer parameters, see the description for available keys and values
      * @returns new render target
      */
-    function render_target(parameters: Record<string | number, unknown>): Opaque<"render_target">;
+    function render_target(parameters: render.RenderTargetParams): Opaque<"render_target">;
     /**
      * Creates a new named render target according to the supplied specification
      * table. The name is used by the profiler and by render target lookups.
@@ -23,7 +23,7 @@ declare global {
      */
     function render_target(
       name: string,
-      parameters: Record<string | number, unknown>,
+      parameters: render.RenderTargetParams,
     ): Opaque<"render_target">;
   }
 }

package/src/return-correction-provenance.ts

@@ -248,6 +248,10 @@ export interface ReturnTypeProvenance {
   readonly sightedIn: readonly string[];
   readonly neededBy: readonly string[];
   readonly resolvedIn: readonly string[];
+  // Targets whose vendored binding does not show a binding-pinned entry's pin,
+  // so the emitter leaves the entry off there. Never a resolution: upstream
+  // documented nothing, the engine source changed.
+  readonly unboundIn: readonly string[];
   readonly driftedIn: readonly string[];
   readonly typeDrift: readonly string[];
 }
@@ -255,14 +259,26 @@ export interface ReturnTypeProvenance {
 // Same ranking argument as `FIELD_VERDICT_RANK`: `emitReturn` applies the
 // correction to every declaration of the FQN in a target, so one drifted
 // declaration makes that target's emit wrong whatever its siblings say.
-type ReturnVerdict = "drift" | "needed" | "resolved";
+// Binding evidence is per target, so for a binding-pinned entry `unbound` never
+// meets another verdict in the same target.
+type ReturnVerdict = "drift" | "needed" | "unbound" | "resolved";
 
 const RETURN_VERDICT_RANK: Record<ReturnVerdict, number> = {
-  drift: 2,
-  needed: 1,
+  drift: 3,
+  needed: 2,
+  unbound: 1,
   resolved: 0,
 };
 
+// Whether the declared tokens already say what the correction does. Tokens can
+// state only the nil: a binding-pinned `ts` entry corrects what the binding sets
+// (a field it never pushes), so upstream fixing that shows as a retype, which is
+// drift, never as a resolution.
+function declaresCorrection(tokens: readonly string[], correction: ReturnTypeCorrection): boolean {
+  if (correction.nullable === undefined && correction.binding !== undefined) return false;
+  return correction.nullable === false ? !tokens.includes("nil") : tokens.includes("nil");
+}
+
 // The return-type class has the same two-sided evidence: the declared tokens
 // still say what the correction contradicts, and the slot prose still states the
 // contradiction. A target that fixes either half no longer needs the entry.
@@ -273,9 +289,16 @@ const RETURN_VERDICT_RANK: Record<ReturnVerdict, number> = {
 // return correction replaces the whole emitted type, so a base upstream no longer
 // declares means the correction now overwrites a type nobody verified — a
 // decision for a human, not a deletion and not a silent bank.
+//
+// A binding-pinned entry rests on the engine source rather than the prose, so
+// its prose is never searched. `bindingEvidence` maps each vendored target to
+// the keys whose pin holds there; a target absent from it shows no evidence.
+// A target without the entry's evidence is `unbound` before its tokens are
+// read, because the emitter leaves the entry off there.
 export function returnCorrectionProvenance(
   entries: readonly [string, ReturnTypeCorrection][],
   surfaces: readonly ProvenanceSurface[],
+  bindingEvidence: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): ReturnTypeProvenance[] {
   return entries.map(([key, correction]) => {
     const namespace = namespaceOf(key);
@@ -291,7 +314,12 @@ export function returnCorrectionProvenance(
         const tokens = slot.types ?? [];
 
         let verdict: ReturnVerdict;
-        if (!pinMatches(tokens, pins)) {
+        if (
+          correction.binding !== undefined &&
+          bindingEvidence.get(surface.target)?.has(key) !== true
+        ) {
+          verdict = "unbound";
+        } else if (!pinMatches(tokens, pins)) {
           verdict = "drift";
           const messages = drift.get(surface.target) ?? new Set<string>();
           drift.set(surface.target, messages);
@@ -299,8 +327,9 @@ export function returnCorrectionProvenance(
             `${surface.target}: pinned ${pins.map((pin) => pin.join("|")).join(" or ")}, found ${tokens.join("|")}`,
           );
         } else if (
-          tokens.includes("nil") ||
-          !decodeSlotProse(slot.doc ?? "").includes(correction.reason)
+          declaresCorrection(tokens, correction) ||
+          (correction.binding === undefined &&
+            !decodeSlotProse(slot.doc ?? "").includes(correction.reason))
         ) {
           verdict = "resolved";
         } else {
@@ -323,6 +352,7 @@ export function returnCorrectionProvenance(
       sightedIn,
       neededBy: inBucket("needed"),
       resolvedIn: inBucket("resolved"),
+      unboundIn: inBucket("unbound"),
       driftedIn,
       typeDrift: driftedIn.flatMap((target) => [...(drift.get(target) ?? [])]).sort(),
     };

package/src/window-event-guard.d.ts

@@ -4,7 +4,8 @@
 // params, and the `WINDOW_EVENT_*` constants are branded numbers — so TS can
 // neither correlate the two params nor use a branded number as a discriminant.
 // This guard re-introduces the discriminant at the use site, narrowing the
-// untyped `data` payload (only `WINDOW_EVENT_RESIZED` carries fields). It mirrors
+// untyped `data` payload (only `WINDOW_EVENT_RESIZED` carries fields; every
+// other event gets an empty table, script_window.cpp). It mirrors
 // `isMessage` for `on_message`; the transpiler lowers the call to a bare
 // `event == window.WINDOW_EVENT_*` (window-event-guard-lowering.ts), so this
 // package emits no runtime Lua. The event kinds are read off the loaded
@@ -14,7 +15,7 @@ type WindowEventKind = (typeof window)[Extract<keyof typeof window, `WINDOW_EVEN
 
 type WindowEventData<K extends WindowEventKind> = K extends typeof window.WINDOW_EVENT_RESIZED
   ? { width: number; height: number }
-  : undefined;
+  : Record<string, never>;
 
 declare global {
   /**
@@ -24,7 +25,8 @@ declare global {
    * params and the constants are branded numbers, so TS cannot auto-narrow `data`
    * from an `event === window.WINDOW_EVENT_RESIZED` check — this guard
    * re-introduces the discriminant. Only `WINDOW_EVENT_RESIZED` carries fields
-   * (`{ width, height }`); every other event narrows `data` to `undefined`.
+   * (`{ width, height }`); every other event receives an empty table, so `data`
+   * narrows to `Record<string, never>`.
    *
    * @param event - the event constant the callback received.
    * @param data - the untyped data payload the callback received.