@defold-typescript/types 0.8.4 → 0.9.0

package/index.d.ts

@@ -57,7 +57,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.9.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {

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/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");

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>;
 }
@@ -128,6 +128,8 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   resource: 'Opaque<"resource">',
   b2World: 'Opaque<"b2World">',
   b2Body: 'Opaque<"b2Body">',
+  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" })',
   client: 'Opaque<"client">',
   master: 'Opaque<"master">',
   unconnected: 'Opaque<"unconnected">',

package/src/doc-comment.ts

@@ -29,18 +29,20 @@ export function htmlToDocText(html: string): string {
     .replace(/<li>/gi, "\n- ")
     .replace(/<\/li>/gi, "")
     .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
     .replace(/<\/?pre>/gi, "\n")
     .replace(/<[^>]+>/g, "");
 
   text = decodeEntities(text);
 
-  // Collapse horizontal whitespace runs, trim around newlines, drop blank
-  // runs, then trim the whole string — preserving single newlines from lists
-  // and `<br>`.
+  // Collapse horizontal whitespace runs, trim around newlines, fold runaway
+  // blank runs to one blank line, then trim the whole string — preserving
+  // single newlines from lists and `<br>`, and the paragraph-break blank line
+  // from `</p>`.
   text = text
     .replace(/[ \t]+/g, " ")
     .replace(/ *\n */g, "\n")
-    .replace(/\n{2,}/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
     .trim();
 
   // A literal `*/` would close the JSDoc comment early; escape it.
@@ -68,6 +70,41 @@ export function htmlToCodeText(html: string): string {
   return collapsed.split("*/").join("*\\/");
 }
 
+/**
+ * Convert a ref-doc `examples` HTML fragment — prose interleaved with one or
+ * more `<div class="codehilite">…</div>` syntax-highlight blocks — into Markdown:
+ * prose runs become `htmlToDocText`, each highlight block becomes a ` ```lua `
+ * fence via `htmlToCodeText`. A fragment with no `codehilite` block is wrapped
+ * whole as a single ` ```lua ` fence (back-compat for plain-code examples).
+ * Returns `""` for empty / whitespace-only input.
+ */
+export function examplesHtmlToMarkdown(html: string): string {
+  if (html.trim() === "") return "";
+
+  const parts: string[] = [];
+  const blocks = /<div class="codehilite">([\s\S]*?)<\/div>/gi;
+  let lastIndex = 0;
+  let matched = false;
+  for (let match = blocks.exec(html); match !== null; match = blocks.exec(html)) {
+    matched = true;
+    const prose = htmlToDocText(html.slice(lastIndex, match.index));
+    if (prose !== "") parts.push(prose);
+    const code = htmlToCodeText(match[1] ?? "");
+    if (code !== "") parts.push(`\`\`\`lua\n${code}\n\`\`\``);
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (!matched) {
+    const code = htmlToCodeText(html);
+    return code === "" ? "" : `\`\`\`lua\n${code}\n\`\`\``;
+  }
+
+  const trailing = htmlToDocText(html.slice(lastIndex));
+  if (trailing !== "") parts.push(trailing);
+
+  return parts.join("\n\n");
+}
+
 export interface DocCommentParts {
   summary: string;
   params?: { name: string; doc: string }[];
@@ -92,7 +129,7 @@ export function renderDocComment(parts: DocCommentParts): string[] {
 
   const lines = ["/**"];
   for (const line of summaryLines) {
-    lines.push(` * ${line}`);
+    lines.push(line === "" ? " *" : ` * ${line}`);
   }
 
   const hasTags = params.length > 0 || returns !== "" || example !== "";

package/src/engine-globals.d.ts

@@ -4,6 +4,8 @@ import type * as Core from "./core-types";
 declare global {
   type Hash = Core.Hash;
   function hash(s: string): Core.Hash;
+  function hash_to_hex(h: Core.Hash): string;
+  function pprint(v: unknown): void;
   type Opaque<Name extends string> = Core.Opaque<Name>;
   type Url = Core.Url;
   type Vector = Core.Vector;

package/src/example-store.ts

@@ -7,7 +7,10 @@ export interface Translation {
   ts: string;
 }
 
-export type TranslationStore = Record<string, Translation>;
+// An FQN maps to one translation per distinct example body it carries: an
+// overloaded element (same name, differing `@example` source) contributes one
+// array entry per body, each pinned by its own `sourceHash`.
+export type TranslationStore = Record<string, Translation[]>;
 
 const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
 const FNV_PRIME = 0x100000001b3n;
@@ -30,15 +33,16 @@ export function hashExampleSource(source: string): string {
   return hash.toString(16).padStart(16, "0");
 }
 
-// Return the stored TypeScript body only when the FQN exists and its pinned
-// `sourceHash` matches the source we are about to emit; any mismatch returns
-// `null` so the caller keeps the Lua fallback.
+// Return the stored TypeScript body only when the FQN exists and one of its
+// pinned `sourceHash`es matches the source we are about to emit; any mismatch
+// returns `null` so the caller keeps the Lua fallback.
 export function lookupTranslation(
   store: TranslationStore,
   fqn: string,
   sourceHash: string,
 ): string | null {
-  const entry = store[fqn];
-  if (!entry || entry.sourceHash !== sourceHash) return null;
-  return entry.ts;
+  const entries = store[fqn];
+  if (!entries) return null;
+  const match = entries.find((entry) => entry.sourceHash === sourceHash);
+  return match ? match.ts : null;
 }

package/src/index.ts

@@ -10,8 +10,20 @@ export {
   type Vector3,
   type Vector4,
 } from "./core-types";
-export { type DocCommentParts, htmlToDocText, renderDocComment } from "./doc-comment";
+export {
+  type DocCommentParts,
+  examplesHtmlToMarkdown,
+  htmlToCodeText,
+  htmlToDocText,
+  renderDocComment,
+} from "./doc-comment";
 export { type EmitOptions, emitDeclarations } from "./emit-dts";
+export {
+  hashExampleSource,
+  lookupTranslation,
+  type Translation,
+  type TranslationStore,
+} from "./example-store";
 export {
   defineGuiScript,
   defineRenderScript,
@@ -30,3 +42,8 @@ export {
   type ScriptProperty,
 } from "./lifecycle";
 export { type WrapOptions, wrapAsAmbientGlobal } from "./publish-dts";
+export {
+  lookupSignature,
+  type SignatureOverride,
+  type SignatureStore,
+} from "./signature-store";

package/src/msg-overloads.d.ts

@@ -12,8 +12,11 @@ declare global {
      * to a component. If the component part of the receiver is omitted, the message
      * is broadcast to all components in the game object.
      * The following receiver shorthands are available:
+     *
      * - `"."` the current game object
+     *
      * - `"#"` the current component
+     *
      * There is a 2 kilobyte limit to the message parameter table size.
      *
      * @param receiver - The receiver must be a string in URL-format, a URL object or a hashed string.

package/src/signature-store.ts

@@ -0,0 +1,20 @@
+// A hand-authored override for one ref-doc element's signature, sourced from
+// the `lua-types` declarations the compiler actually enforces. The ref-doc's
+// own signatures are far weaker (`...` params show `unknown`, no return types),
+// so these strengthen the rendered signature while the ref-doc prose stays.
+export interface SignatureOverride {
+  signatures: string[];
+}
+
+// An FQN (`io.open`, `file:read`, …) maps to one override. An element with
+// several overloads carries more than one entry in `signatures`, in authored
+// order (the order the docs should render them).
+export type SignatureStore = Record<string, SignatureOverride>;
+
+// Return the override for an FQN, or `null` when the store has no entry. Pure
+// and dependency-free like `example-store.ts`: this module is reachable from
+// `index.ts`, so a `node:fs`/ambient-`Bun` reference here would fail type-checking
+// in every downstream consumer that compiles the shipped `src/` graph.
+export function lookupSignature(store: SignatureStore, fqn: string): SignatureOverride | null {
+  return store[fqn] ?? null;
+}