@defold-typescript/types 0.8.4 → 0.10.0

package/generated/window.d.ts

@@ -51,8 +51,11 @@ declare global {
      * On platforms that does not support dimming, `window.DIMMING_UNKNOWN` is always returned.
      *
      * @returns The mode for screen dimming
+     *
      * - `window.DIMMING_UNKNOWN`
+     *
      * - `window.DIMMING_ON`
+     *
      * - `window.DIMMING_OFF`
      */
     function get_dim_mode(): Opaque<"constant">;
@@ -74,15 +77,24 @@ declare global {
      * this returns the full window size and zero insets.
      *
      * @returns safe area data
+     *
      * `safe_area`
      * table table containing these keys:
+     *
      * - number `x`
+     *
      * - number `y`
+     *
      * - number `width`
+     *
      * - number `height`
+     *
      * - number `inset_left`
+     *
      * - number `inset_top`
+     *
      * - number `inset_right`
+     *
      * - number `inset_bottom`
      */
     function get_safe_area(): { safe_area: { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number } };
@@ -96,7 +108,9 @@ declare global {
      * This function has no effect on platforms that does not support dimming.
      *
      * @param mode - The mode for screen dimming
+     *
      * - `window.DIMMING_ON`
+     *
      * - `window.DIMMING_OFF`
      */
     function set_dim_mode(mode: Opaque<"constant">): void;
@@ -104,18 +118,27 @@ declare global {
      * Sets a window event listener. Only one window event listener can be set at a time.
      *
      * @param callback - A callback which receives info about window events. Pass an empty function or `nil` if you no longer wish to receive callbacks.
+     *
      * `self`
      * object The calling script
      * `event`
      * constant The type of event. Can be one of these:
+     *
      * - `window.WINDOW_EVENT_FOCUS_LOST`
+     *
      * - `window.WINDOW_EVENT_FOCUS_GAINED`
+     *
      * - `window.WINDOW_EVENT_RESIZED`
+     *
      * - `window.WINDOW_EVENT_ICONIFIED`
+     *
      * - `window.WINDOW_EVENT_DEICONIFIED`
+     *
      * `data`
      * table The callback value `data` is a table which currently holds these values
+     *
      * - number `width`: The width of a resize event. nil otherwise.
+     *
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
      * ```ts

package/index.d.ts

@@ -34,6 +34,7 @@ import "./generated/push";
 import "./generated/render";
 import "./generated/resource";
 import "./generated/socket";
+import "./src/socket-types";
 import "./generated/sound";
 import "./generated/sprite";
 import "./generated/sys";
@@ -57,7 +58,14 @@ export {
   type Vector3,
   type Vector4,
 } from "./src/core-types";
+export { examplesHtmlToMarkdown, htmlToCodeText, htmlToDocText } from "./src/doc-comment";
 export { type EmitOptions, emitDeclarations } from "./src/emit-dts";
+export {
+  hashExampleSource,
+  lookupTranslation,
+  type Translation,
+  type TranslationStore,
+} from "./src/example-store";
 export {
   defineGuiScript,
   defineRenderScript,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,9 @@
     "./core-types": {
       "types": "./src/core-types.ts"
     },
+    "./lifecycle": {
+      "types": "./src/lifecycle.ts"
+    },
     "./timers": {
       "types": "./src/timers.d.ts"
     },

package/scripts/fidelity-audit.ts

@@ -4,6 +4,7 @@ import {
   ARBITRARY_TABLE_SLOTS,
   applyNestedFieldCurations,
   buildTableDocResolver,
+  HANDLE_METHOD_LOCAL,
   HOMOGENEOUS_ARRAY_SLOTS,
   MAPPING_TABLE_SLOTS,
   type NestedMapping,
@@ -76,6 +77,26 @@ function trailingOptionalCutoff(params: readonly Record<string, unknown>[]): num
   return cutoff;
 }
 
+// Colon `<receiver>:<method>` FUNCTION elements are emitted as method-bearing
+// interfaces (see emit-dts collectHandleMethodGroups). Before that recovery they
+// emitted nothing yet were never counted as a droppedMembers loss — a blind spot
+// that let `socket` read `droppedMembers: 0` over an incomplete surface. Count
+// them honestly: with emission on, only a malformed colon name (non-identifier
+// segment) is still a loss; with emission off, every colon method is dropped.
+export function countDroppedHandleMethods(doc: unknown, namespace: string, emit = true): number {
+  const prefix = `${namespace}.`;
+  let dropped = 0;
+  for (const element of elementsOf(doc)) {
+    if (element.type !== "FUNCTION" || typeof element.name !== "string") continue;
+    const local = element.name.startsWith(prefix)
+      ? element.name.slice(prefix.length)
+      : element.name;
+    if (!local.includes(":")) continue;
+    if (!emit || !HANDLE_METHOD_LOCAL.test(local)) dropped += 1;
+  }
+  return dropped;
+}
+
 function auditEntry(
   entry: ModuleManifestEntry,
   knownConstantFqns: ReadonlySet<string>,
@@ -356,9 +377,11 @@ function auditEntry(
     unknownTokens: [...unknown].sort(),
     recordTables,
     multiReturn,
-    droppedMembers: generateModuleDeclaration(entry, {
-      knownConstantFqns: NO_KNOWN_CONSTANTS,
-    }).dropped.filter((name) => !OVERLOAD_COVERED_SKIPS.has(name)).length,
+    droppedMembers:
+      generateModuleDeclaration(entry, {
+        knownConstantFqns: NO_KNOWN_CONSTANTS,
+      }).dropped.filter((name) => !OVERLOAD_COVERED_SKIPS.has(name)).length +
+      countDroppedHandleMethods(entry.doc, entry.namespace),
     optionalAsRequired,
   };
 }

package/scripts/fidelity-baseline.json

@@ -7,7 +7,7 @@
     "droppedMembers": 0,
     "optionalAsRequired": 0
   },
-  "buffer": {
+  "b2d.body": {
     "droppedElements": 0,
     "unknownTokens": [],
     "recordTables": 0,
@@ -15,7 +15,7 @@
     "droppedMembers": 0,
     "optionalAsRequired": 0
   },
-  "camera": {
+  "buffer": {
     "droppedElements": 0,
     "unknownTokens": [],
     "recordTables": 0,
@@ -23,6 +23,14 @@
     "droppedMembers": 0,
     "optionalAsRequired": 0
   },
+  "camera": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 1,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 7
+  },
   "collectionfactory": {
     "droppedElements": 0,
     "unknownTokens": [],
@@ -55,6 +63,14 @@
     "droppedMembers": 0,
     "optionalAsRequired": 0
   },
+  "font": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 1,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0
+  },
   "go": {
     "droppedElements": 0,
     "unknownTokens": [],

package/scripts/materialize-version.ts

@@ -4,10 +4,33 @@ import {
   type ApiTarget,
   generateModuleDeclaration,
   generateVersionIndex,
+  KIND_MODULE_MANIFEST,
+  LUA_STDLIB_REFERENCES,
   type ResolveTargetOptions,
   resolveTargetModules,
 } from "./regen";
 
+export { KIND_MODULE_MANIFEST } from "./regen";
+
+export interface RenderMaterializedKindIndexOptions {
+  readonly kind: string;
+  readonly universalModules: readonly string[];
+  readonly restrictedModule: string | null;
+}
+
+// Render one per-kind subpath for the materialized surface, mirroring
+// `generateKindIndex` but re-exporting the factory from the installed
+// `@defold-typescript/types/lifecycle` subpath (the materialized surface has no
+// relative `src/lifecycle` to reach). Pure: returns a string, no FS.
+export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOptions): string {
+  const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === opts.kind);
+  if (!entry) throw new Error(`unknown script kind: ${opts.kind}`);
+  const universal = [...new Set(["engine-globals", ...opts.universalModules])].sort();
+  const lines = universal.map((mod) => `import "../${mod}";`);
+  if (opts.restrictedModule) lines.push(`import "../${opts.restrictedModule}";`);
+  return `${LUA_STDLIB_REFERENCES}${lines.join("\n")}\n\nexport { ${entry.factory} } from "@defold-typescript/types/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "@defold-typescript/types/lifecycle";\n`;
+}
+
 export interface MaterializeVersionedSurfaceOptions {
   readonly destDir: string;
   readonly resolveOpts?: ResolveTargetOptions;

package/scripts/regen.ts

@@ -36,6 +36,10 @@ export interface ApiTarget {
   readonly coreTypesImport: string;
   readonly source?: ApiTargetSource;
   readonly modules: readonly ApiTargetModule[];
+  // Docs-only Lua stdlib pages (no generated `.d.ts`): vendored fixtures the
+  // docs-site pages under the "Lua standard library" category. Never read by
+  // regen/MODULE_MANIFEST; surfaced here so the registry stays type-honest.
+  readonly luaStdlib?: readonly { readonly namespace: string; readonly fixture: string }[];
 }
 
 const REGISTRY_PATH = resolve(import.meta.dir, "..", "api-targets.json");
@@ -226,7 +230,7 @@ export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
 // The Lua standard library rides every per-kind subpath the same as the full
 // entrypoint. Triple-slash directives must precede the first statement, so they
 // lead the generated kind index.
-const LUA_STDLIB_REFERENCES =
+export const LUA_STDLIB_REFERENCES =
   '/// <reference types="lua-types/5.1" />\n/// <reference types="lua-types/special/jit-only" />\n';
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [

package/scripts/signature-store-io.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { SignatureStore } from "../src/signature-store";
+
+// Build-time only: lives under `scripts/` (never reachable from the shipped
+// `src/index.ts` graph) so its `node:fs` import cannot leak into a consumer's
+// typecheck. `src/signature-store.ts` stays pure for exactly that reason.
+const IO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "io.json");
+
+export function loadSignatures(path: string = IO_SIGNATURES_PATH): SignatureStore {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return {};
+  }
+  return JSON.parse(raw) as SignatureStore;
+}

package/scripts/sync-api-docs.ts

@@ -14,6 +14,11 @@ export interface SyncManifestEntry {
   readonly namespace: string;
   readonly zipEntry: string;
   readonly fixture: string;
+  // Extra ref-doc.zip entries whose elements are merged into this namespace at
+  // sync time. A namespace whose Lua surface is split across several upstream
+  // docs (e.g. `sys`) is reassembled before parse, so the emitter still sees one
+  // fixture, one namespace.
+  readonly mergeEntries?: readonly string[];
 }
 
 // namespace -> ref-doc.zip entry. Entry paths do not match the namespace (gui ->
@@ -21,12 +26,24 @@ export interface SyncManifestEntry {
 // so each path is confirmed against the pinned release artifact, not derived.
 export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("b2d", "doc/scripts-box2d-script_box2d.cpp_doc.json"),
+  // On-disk name uses underscores to avoid a double-dotted filename; the namespace
+  // string stays `b2d.body` so /api/b2d.body routes correctly and the emitter
+  // produces `declare global { namespace b2d.body { ... } }`. Use the non-`_defold`
+  // variant — the `_defold` variant has duplicate `get_world_center` elements.
+  entry(
+    "b2d.body",
+    "doc/scripts-box2d-script_box2d_body.cpp_doc.json",
+    "fixtures/b2d_body_doc.json",
+  ),
   entry("buffer", "doc/scripts-script_buffer.cpp_doc.json"),
-  entry("camera", "doc/scripts-script_camera.cpp_doc.json"),
+  // camera's Lua surface lives in the render-script doc, not the scripts-script
+  // one (`doc/scripts-script_camera.cpp_doc.json` is empty upstream in 1.12.4).
+  entry("camera", "doc/render-render_script_camera.cpp_doc.json"),
   entry("collectionfactory", "doc/scripts-script_collection_factory.cpp_doc.json"),
   entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json"),
   entry("crash", "doc/script_crash.cpp_doc.json"),
   entry("factory", "doc/scripts-script_factory.cpp_doc.json"),
+  entry("font", "doc/scripts-script_font.cpp_doc.json"),
   entry("go", "doc/gameobject_script.cpp_doc.json"),
   entry("graphics", "doc/src-script_graphics.cpp_doc.json"),
   entry("gui", "doc/gui_script.cpp_doc.json"),
@@ -46,9 +63,16 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("socket", "doc/luasocket-luasocket.doc_h_doc.json"),
   entry("sound", "doc/scripts-script_sound.cpp_doc.json"),
   entry("sprite", "doc/scripts-script_sprite.cpp_doc.json"),
-  // The `sys` surface is split across two docs in ref-doc.zip; this is the core
-  // (src-script_sys) doc — the larger gamesys subset is folded in when wired.
-  entry("sys", "doc/src-script_sys.cpp_doc.json"),
+  // The `sys` Lua surface is split across three docs in ref-doc.zip: the core
+  // (src-script_sys), the gamesys subset (`load_buffer`/`load_buffer_async` plus
+  // the `REQUEST_STATUS_*` constants), and the engine doc (`set_engine_throttle`/
+  // `set_render_enable`). `mergeEntries` folds all three into one fixture at sync
+  // time. The `*_ddf.proto` doc is deliberately excluded — it is message-shaped
+  // and owned by the builtin-messages catalog.
+  entry("sys", "doc/src-script_sys.cpp_doc.json", "fixtures/sys_doc.json", [
+    "doc/scripts-script_sys_gamesys.cpp_doc.json",
+    "doc/script-script_engine.cpp_doc.json",
+  ]),
   entry("tilemap", "doc/scripts-script_tilemap.cpp_doc.json"),
   entry("timer", "doc/src-script_timer.cpp_doc.json"),
   entry("types", "doc/src-script_types.cpp_doc.json"),
@@ -62,8 +86,61 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
 // four extension-only surfaces are wired via EXTENSION_MANIFEST below.
 export const UNMAPPED: ReadonlyMap<string, string> = new Map();
 
-function entry(namespace: string, zipEntry: string): SyncManifestEntry {
-  return { namespace, zipEntry, fixture: `fixtures/${namespace}_doc.json` };
+// A Lua script namespace is a lowercase, dot-separated identifier (`sys`,
+// `b2d.body`). The native C/C++ SDK docs (`dmGraphics`, …), the C# bindings
+// (`cs-*`), and the struct-only docs (empty `info.namespace`) fail this shape,
+// so the upstream-coverage guard skips them structurally rather than listing
+// each by hand — that keeps the guard self-maintaining as the SDK grows.
+const LUA_NAMESPACE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
+
+// Lowercase-identifier namespaces that pass LUA_NAMESPACE but are intentionally
+// not wired through SYNC_MANIFEST, each with a sourced reason (mirrors the
+// `EMPTY_BY_UPSTREAM` allowlist shape). The upstream-coverage guard treats these
+// as covered. Adding a namespace here is a deliberate, reviewed act.
+export const IGNORED_UPSTREAM: ReadonlyMap<string, string> = new Map([
+  ["editor", "editor-scripting API (editor.apidoc), not a runtime game namespace"],
+  ["engine", "CLI/engine env doc, not a runtime Lua namespace"],
+  [
+    "builtins",
+    "global Defold builtins (hash/pprint/…) typed as ambient globals, not a `builtins.*` namespace",
+  ],
+]);
+
+// Pure-Lua / LuaJIT surfaces Defold documents (https://defold.com/ref/stable/base-lua/,
+// `bit-lua`) whose TypeScript types are owned by the `lua-types` dependency the
+// `lua-stdlib-globals` goal adopted — `lua-types/special/jit-only.d.ts` declares
+// `declare namespace bit { ... }` and `lua-types/core/global.d.ts` carries the
+// base globals. Re-emitting them as generated Defold namespaces would collide
+// (`declare namespace bit` duplicates; base globals are top-level globals, not
+// a `base.*` namespace). LUA_STDLIB_MANIFEST vendors the same ref-doc JSON
+// `SYNC_MANIFEST` carries, but the docs-site is the only consumer — `regen.ts`
+// / `MODULE_MANIFEST` never read it, so no `generated/<ns>.d.ts` is produced.
+export const LUA_STDLIB_MANIFEST: readonly SyncManifestEntry[] = [
+  entry("base", "doc/lua_base.doc_h_doc.json"),
+  entry("bit", "doc/src-script_bitop.cpp_doc.json"),
+  // Core Lua stdlib docs. The 1.12.4 release names these `doc/lua_<ns>.doc_h_doc.json`
+  // (confirmed against the pinned ref-doc.zip, not derived — the naming drifted from
+  // the 1.9.8 `doc/<ns>_doc.json` form). Typed by the lua-types dependency, so docs-only.
+  entry("math", "doc/lua_math.doc_h_doc.json"),
+  entry("os", "doc/lua_os.doc_h_doc.json"),
+  entry("string", "doc/lua_string.doc_h_doc.json"),
+  entry("table", "doc/lua_table.doc_h_doc.json"),
+  entry("coroutine", "doc/lua_coroutine.doc_h_doc.json"),
+  // Sandboxed-runtime stdlib surfaces. Defold sandboxes the Lua VM, but the pinned
+  // 1.12.4 ref-doc.zip documents all three with real function elements; types stay
+  // owned by lua-types (core/{debug,io}.d.ts + core/modules.d.ts for `package`).
+  entry("debug", "doc/lua_debug.doc_h_doc.json"),
+  entry("io", "doc/lua_io.doc_h_doc.json"),
+  entry("package", "doc/lua_package.doc_h_doc.json"),
+];
+
+function entry(
+  namespace: string,
+  zipEntry: string,
+  fixture: string = `fixtures/${namespace}_doc.json`,
+  mergeEntries?: readonly string[],
+): SyncManifestEntry {
+  return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
 }
 
 export interface ExtensionManifestEntry {
@@ -115,7 +192,7 @@ export function parseChecklistNamespaces(visionMarkdown: string): string[] {
   const seen = new Set<string>();
   for (const match of segment.matchAll(/`([^`]+)`/g)) {
     const token = match[1] as string;
-    if (!/^[a-z][a-z0-9]*$/.test(token) || seen.has(token)) continue;
+    if (!/^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/.test(token) || seen.has(token)) continue;
     seen.add(token);
     namespaces.push(token);
   }
@@ -168,15 +245,52 @@ export interface ExtractedFixture {
   contents: string;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Concatenate the `elements` of every doc into the first doc, deduping by
+// (name, type) with first occurrence winning, and keep the first doc's `info`.
+// First-wins guards the `b2d.body` `_defold` duplicate-`get_world_center`
+// hazard. Operates on the raw ref-doc JSON shape (`{ info, elements }`), so the
+// result is still parseable by `parseDefoldApiDoc`.
+export function mergeApiDocs(docs: readonly unknown[]): unknown {
+  const first = docs[0];
+  const seen = new Set<string>();
+  const elements: unknown[] = [];
+  for (const doc of docs) {
+    if (!isRecord(doc) || !Array.isArray(doc.elements)) continue;
+    for (const element of doc.elements) {
+      const key =
+        isRecord(element) && typeof element.name === "string" && typeof element.type === "string"
+          ? `${element.type}${element.name}`
+          : null;
+      if (key !== null) {
+        if (seen.has(key)) continue;
+        seen.add(key);
+      }
+      elements.push(element);
+    }
+  }
+  return isRecord(first) ? { ...first, elements } : { elements };
+}
+
 export function extractFixtures(
   zip: ZipAccessor,
   manifest: readonly SyncManifestEntry[] = SYNC_MANIFEST,
 ): ExtractedFixture[] {
   return manifest.map((item) => {
-    if (!zip.has(item.zipEntry)) {
-      throw new Error(`zip is missing entry ${item.zipEntry} for namespace ${item.namespace}`);
+    const sources = [item.zipEntry, ...(item.mergeEntries ?? [])];
+    for (const source of sources) {
+      if (!zip.has(source)) {
+        throw new Error(`zip is missing entry ${source} for namespace ${item.namespace}`);
+      }
     }
-    return { namespace: item.namespace, fixture: item.fixture, contents: zip.read(item.zipEntry) };
+    const contents =
+      item.mergeEntries === undefined
+        ? zip.read(item.zipEntry)
+        : JSON.stringify(mergeApiDocs(sources.map((source) => JSON.parse(zip.read(source)))));
+    return { namespace: item.namespace, fixture: item.fixture, contents };
   });
 }
 
@@ -276,11 +390,26 @@ export interface SyncedDoc {
   doc: unknown;
 }
 
+export interface UpstreamNamespace {
+  namespace: string;
+  functionCount: number;
+  zipEntry: string;
+}
+
+export interface UnmappedUpstreamNamespace {
+  namespace: string;
+  zipEntry: string;
+}
+
 export interface CoverageReport {
   wired: string[];
   fixtureOnly: string[];
   missingMapping: string[];
   unknownTypeTokens: { namespace: string; tokens: string[] }[];
+  // Function-bearing Lua namespaces present in the zip but neither mapped nor
+  // allowlisted — the next `font`-style miss. The `--check` path fails when this
+  // is non-empty.
+  unmappedUpstream: UnmappedUpstreamNamespace[];
 }
 
 export interface CoverageInput {
@@ -288,6 +417,38 @@ export interface CoverageInput {
   moduleManifest: readonly { namespace: string }[];
   unmapped: ReadonlyMap<string, string>;
   syncedDocs: readonly SyncedDoc[];
+  // Every function-bearing namespace the zip itself exposes (from
+  // collectUpstreamNamespaces). Absent in pure-fixture callers that don't audit
+  // upstream coverage, in which case unmappedUpstream is empty.
+  upstream?: readonly UpstreamNamespace[];
+  upstreamMapped?: ReadonlySet<string>;
+  ignoredUpstream?: ReadonlyMap<string, string>;
+}
+
+// Enumerate every `doc/*.json` zip entry, reading its `info.namespace` and the
+// count of FUNCTION elements. Only function-bearing docs are returned, so
+// message-only / struct-only docs never reach the coverage guard.
+export function collectUpstreamNamespaces(zip: ZipAccessor): UpstreamNamespace[] {
+  const out: UpstreamNamespace[] = [];
+  for (const zipEntry of zip.entries()) {
+    if (!/^doc\/.*\.json$/.test(zipEntry)) continue;
+    let doc: unknown;
+    try {
+      doc = JSON.parse(zip.read(zipEntry));
+    } catch {
+      continue;
+    }
+    if (!isRecord(doc)) continue;
+    const info = doc.info;
+    const namespace = isRecord(info) && typeof info.namespace === "string" ? info.namespace : "";
+    const elements = Array.isArray(doc.elements) ? doc.elements : [];
+    let functionCount = 0;
+    for (const element of elements) {
+      if (isRecord(element) && element.type === "FUNCTION") functionCount += 1;
+    }
+    if (functionCount > 0) out.push({ namespace, functionCount, zipEntry });
+  }
+  return out;
 }
 
 export function buildCoverageReport(input: CoverageInput): CoverageReport {
@@ -307,7 +468,26 @@ export function buildCoverageReport(input: CoverageInput): CoverageReport {
       unknownTypeTokens.push({ namespace: synced.namespace, tokens });
     }
   }
-  return { wired, fixtureOnly, missingMapping, unknownTypeTokens };
+
+  const mapped = input.upstreamMapped ?? new Set<string>();
+  const ignored = input.ignoredUpstream ?? new Map<string, string>();
+  const flagged = new Map<string, string>();
+  for (const item of input.upstream ?? []) {
+    if (
+      !LUA_NAMESPACE.test(item.namespace) ||
+      mapped.has(item.namespace) ||
+      ignored.has(item.namespace) ||
+      flagged.has(item.namespace)
+    ) {
+      continue;
+    }
+    flagged.set(item.namespace, item.zipEntry);
+  }
+  const unmappedUpstream = [...flagged]
+    .map(([namespace, zipEntry]) => ({ namespace, zipEntry }))
+    .sort((a, b) => a.namespace.localeCompare(b.namespace));
+
+  return { wired, fixtureOnly, missingMapping, unknownTypeTokens, unmappedUpstream };
 }
 
 function collectUnknownTokens(module: ApiModule): string[] {
@@ -349,6 +529,15 @@ function printReport(results: FixtureSyncResult[], report: CoverageReport, check
       console.log(`  ${namespace}: ${tokens.join(", ")}`);
     }
   }
+
+  if (report.unmappedUpstream.length > 0) {
+    console.log(
+      "\nunmapped upstream namespaces (function-bearing, neither mapped nor allowlisted)",
+    );
+    for (const { namespace, zipEntry } of report.unmappedUpstream) {
+      console.log(`  ${namespace}: ${zipEntry}`);
+    }
+  }
 }
 
 if (import.meta.main) {
@@ -359,9 +548,11 @@ if (import.meta.main) {
 
   const coreFixtures = extractFixtures(zip);
   const extensionFixtures = await downloadExtensionFixtures();
+  const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
     ...syncExtractedFixtures(extensionFixtures, { check }),
+    ...syncExtractedFixtures(luaStdlibFixtures, { check }),
   ];
   const syncedDocs = [...coreFixtures, ...extensionFixtures].map((f) => ({
     namespace: f.namespace,
@@ -372,10 +563,15 @@ if (import.meta.main) {
     moduleManifest: MODULE_MANIFEST,
     unmapped: UNMAPPED,
     syncedDocs,
+    upstream: collectUpstreamNamespaces(zip),
+    upstreamMapped: new Set(
+      [...SYNC_MANIFEST, ...EXTENSION_MANIFEST, ...LUA_STDLIB_MANIFEST].map((e) => e.namespace),
+    ),
+    ignoredUpstream: IGNORED_UPSTREAM,
   });
   printReport(results, report, check);
 
-  if (check && results.some((r) => r.status === "drift")) {
+  if (check && (results.some((r) => r.status === "drift") || report.unmappedUpstream.length > 0)) {
     process.exitCode = 1;
   }
 }

package/src/core-types.ts

@@ -17,7 +17,7 @@ export interface Vector3 {
    * @remarks
    * Prefer `v.unm()` over `-v` — TypeScript does not flag unary `-` on object
    * types and silently produces `number`. See
-   * `docs/guide/typescript-gotchas.md` for the full story.
+   * `packages/docs/guide/typescript-gotchas.md` for the full story.
    */
   unm: LuaNegationMethod<Vector3>;
 }
@@ -35,7 +35,7 @@ export interface Vector4 {
    * @remarks
    * Prefer `v.unm()` over `-v` — TypeScript does not flag unary `-` on object
    * types and silently produces `number`. See
-   * `docs/guide/typescript-gotchas.md` for the full story.
+   * `packages/docs/guide/typescript-gotchas.md` for the full story.
    */
   unm: LuaNegationMethod<Vector4>;
 }
@@ -123,13 +123,20 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   constant: 'Opaque<"constant">',
   constant_buffer: 'Opaque<"constant_buffer">',
   buffer: 'Opaque<"buffer">',
-  bufferstream: 'Opaque<"bufferstream">',
+  bufferstream: 'Opaque<"bufferstream"> & { [index: number]: number }',
   userdata: 'Opaque<"userdata">',
   resource: 'Opaque<"resource">',
   b2World: 'Opaque<"b2World">',
   b2Body: 'Opaque<"b2Body">',
-  client: 'Opaque<"client">',
-  master: 'Opaque<"master">',
-  unconnected: 'Opaque<"unconnected">',
+  b2BodyType:
+    '(number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" })',
+  // socket handle types resolve to the method-bearing `interface <receiver>`
+  // emitted inside `namespace socket`, not opaque brands — the documented
+  // colon methods (`client:send`, …) make each handle structurally distinct.
+  client: "client",
+  connected: "connected",
+  master: "master",
+  server: "server",
+  unconnected: "unconnected",
   any: "unknown",
 } as const;