@defold-typescript/types 0.38.0 → 0.40.0

package/generated/window.d.ts

@@ -5,6 +5,8 @@ declare global {
    * and screen dimming.
    */
   namespace window {
+    type DimModeState = typeof window.DIMMING_UNKNOWN | typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
+    type DimModeStateSettable = typeof window.DIMMING_ON | typeof window.DIMMING_OFF;
     /**
      * Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.
      */
@@ -56,7 +58,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function get_dim_mode(): number & { readonly __brand: "window.DIMMING_UNKNOWN" } | number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" };
+    function get_dim_mode(): window.DimModeState;
     /**
      * This returns the content scale of the current display.
      *
@@ -111,7 +113,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function set_dim_mode(mode: number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" }): void;
+    function set_dim_mode(mode: window.DimModeStateSettable): void;
     /**
      * Sets a window event listener. Only one window event listener can be set at a time.
      *
@@ -140,7 +142,7 @@ declare global {
      * - number `height`: The height of a resize event. nil otherwise.
      * @example
      * ```ts
-     * function window_callback(self, event, data) {
+     * function window_callback(self: unknown, event: unknown, data: Record<string | number, unknown>) {
      *   if (event === window.WINDOW_EVENT_FOCUS_LOST) {
      *     print("window.WINDOW_EVENT_FOCUS_LOST");
      *   } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {

package/index.d.ts

@@ -25,6 +25,7 @@ import "./generated/factory";
 import "./generated/font";
 import "./generated/go";
 import "./src/go-overloads";
+import "./src/component-properties";
 import "./generated/graphics";
 import "./generated/gui";
 import "./generated/html5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -70,6 +70,7 @@
     "!scripts/fidelity-audit.ts",
     "!scripts/augmentation-namespaces.ts",
     "!scripts/example-pins.ts",
+    "!scripts/example-semantics.ts",
     "!scripts/example-surfaces.ts",
     "!scripts/example-typecheck.ts"
   ],

package/scripts/generate-api-signatures.ts

@@ -14,7 +14,8 @@ const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
 
 export interface SignaturesArtifact {
-  // version -> symbolIdentityKey -> authoritative TS signature text
+  // version -> symbolIdentityKey -> authoritative TS signature text; a symbol
+  // with several declared arms carries one arm per line, primary first
   readonly versions: Record<string, Record<string, string>>;
   // The same axis and keys, carrying each documented slot's rendered type. Kept
   // parallel rather than folded into `versions` because three consumers

package/scripts/prose-constants.ts

@@ -0,0 +1,96 @@
+import type { ModuleManifestEntry } from "./regen";
+
+// A constant family the engine registers and one function's parameter prose
+// lists, but no ref-doc element declares. Each release's own list is the
+// evidence, so a surface declares exactly the members its release documents.
+interface ProseConstantFamily {
+  readonly namespace: string;
+  readonly prefix: string;
+  readonly describes: string;
+  readonly evidence: {
+    readonly namespace: string;
+    readonly function: string;
+    readonly parameter: string;
+  };
+}
+
+const PROSE_CONSTANT_FAMILIES: readonly ProseConstantFamily[] = [
+  {
+    namespace: "graphics",
+    prefix: "SEMANTIC_TYPE_",
+    describes: "Vertex attribute semantic type",
+    evidence: {
+      namespace: "material",
+      function: "material.set_vertex_attributes",
+      parameter: "attributes",
+    },
+  },
+];
+
+interface DocElement {
+  readonly type: string;
+  readonly name: string;
+  readonly parameters?: readonly { readonly name: string; readonly doc?: string }[];
+}
+
+interface ApiDoc {
+  readonly elements: readonly DocElement[];
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function evidencedNames(family: ProseConstantFamily, modules: readonly ModuleManifestEntry[]) {
+  const source = modules.find((m) => m.namespace === family.evidence.namespace);
+  if (!source) return [];
+  const fn = (source.doc as ApiDoc).elements.find(
+    (e) => e.type === "FUNCTION" && e.name === family.evidence.function,
+  );
+  const prose = fn?.parameters?.find((p) => p.name === family.evidence.parameter)?.doc ?? "";
+  const item = new RegExp(
+    `<li><code>(${escapeRegExp(`${family.namespace}.${family.prefix}`)}\\w+)</code></li>`,
+    "g",
+  );
+  return [...new Set(Array.from(prose.matchAll(item), (m) => m[1] as string))];
+}
+
+function constantElement(name: string, brief: string) {
+  return {
+    type: "CONSTANT",
+    name,
+    brief,
+    description: "",
+    returnvalues: [],
+    parameters: [],
+    examples: "",
+    replaces: "",
+    error: "",
+    tparams: [],
+    members: [],
+    notes: [],
+    language: "",
+  };
+}
+
+export function synthesizeProseConstants(
+  modules: readonly ModuleManifestEntry[],
+): ModuleManifestEntry[] {
+  let out = [...modules];
+  for (const family of PROSE_CONSTANT_FAMILIES) {
+    const names = evidencedNames(family, out);
+    if (names.length === 0) continue;
+    const index = out.findIndex((m) => m.namespace === family.namespace);
+    const target = out[index];
+    if (!target) continue;
+    const doc = target.doc as ApiDoc;
+    const declared = new Set(doc.elements.map((e) => e.name));
+    const brief = `${family.describes}, for \`${family.evidence.function}\`.`;
+    const added = names.filter((n) => !declared.has(n)).map((n) => constantElement(n, brief));
+    if (added.length === 0) continue;
+    out = out.map((m, i) =>
+      i === index ? { ...m, doc: { ...doc, elements: [...doc.elements, ...added] } } : m,
+    );
+  }
+  return out;
+}

package/scripts/regen.ts

@@ -26,6 +26,7 @@ import {
   resolveRefDoc,
 } from "./doc-source";
 import { loadTranslations } from "./example-store-io";
+import { synthesizeProseConstants } from "./prose-constants";
 import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
 
 export interface ApiTargetModule {
@@ -99,7 +100,7 @@ export function loadTargetModules(
   target: ApiTarget,
   packageRoot: string = PACKAGE_ROOT,
 ): ModuleManifestEntry[] {
-  return target.modules.map((module) => {
+  const modules = target.modules.map((module) => {
     const path = resolve(packageRoot, target.fixturesDir, module.fixture);
     let raw: string;
     try {
@@ -117,6 +118,7 @@ export function loadTargetModules(
     };
     return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
   });
+  return synthesizeProseConstants(modules);
 }
 
 export interface ModuleManifestEntry {
@@ -168,7 +170,7 @@ export async function resolveTargetModules(
     ...(opts.fetchChannelInfo ? { fetchChannelInfo: opts.fetchChannelInfo } : {}),
   });
   const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
-  return target.modules.map((module) => {
+  const modules = target.modules.map((module) => {
     const sync = syncManifest.find((s) => s.namespace === module.namespace);
     if (!sync) {
       throw new Error(
@@ -184,6 +186,7 @@ export async function resolveTargetModules(
     };
     return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
   });
+  return synthesizeProseConstants(modules);
 }
 
 const API_TARGETS = loadApiTargets();
@@ -556,6 +559,7 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
   { specifier: "../../src/window-event-guard" },
   { specifier: "../../src/scene-addresses" },
   { specifier: "../../src/go-overloads" },
+  { specifier: "../../src/component-properties" },
   { specifier: "../../src/render-overloads", restrictedTo: "render" },
   { specifier: "../../src/vmath-overloads" },
 ];

package/src/api-doc.ts

@@ -20,6 +20,10 @@ export interface ApiTypedef {
   name: string;
   functions?: ApiFunction[];
   properties?: ApiVariable[];
+  /** A union alias's top-level arms; a shape with members carries none. */
+  types?: string[];
+  /** The type text of each parent an interface-backed typedef extends. */
+  extends?: string[];
   /** See {@link ApiFunction.global}. */
   global?: true;
 }
@@ -164,10 +168,14 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
 function parseTypedef(element: Record<string, unknown>): ApiTypedef {
   const functions = parseFunctionList(element.functions);
   const properties = parseVariableList(element.properties);
+  const types = parseStringArray(element.types);
+  const parents = parseStringArray(element.extends);
   return {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
+    ...(types.length > 0 ? { types } : {}),
+    ...(parents.length > 0 ? { extends: parents } : {}),
     ...globalKey(element),
   };
 }

package/src/component-properties.d.ts

@@ -0,0 +1,33 @@
+/** @noSelfInFile */
+
+import type { Hash } from "./core-types";
+
+// Component property keys upstream examples read through `go.get` while no
+// ref-doc catalog declares them. Only evidenced keys belong here.
+declare global {
+  namespace sprite {
+    interface properties {
+      /**
+       * The texture bound to the sprite's first sampler. Not in the sprite
+       * ref-doc; `resource.set`'s example reads it with
+       * `go.get("#sprite", "texture0")`.
+       */
+      texture0: Hash;
+    }
+  }
+
+  /**
+   * Mesh component properties. Upstream ships no mesh API module, so this
+   * catalog holds only the keys upstream examples read.
+   */
+  namespace mesh {
+    interface properties {
+      /**
+       * The buffer resource holding the mesh's vertex data.
+       * `resource.get_buffer` and `resource.set_buffer` read it with
+       * `go.get("#mesh", "vertices")`.
+       */
+      vertices: Hash;
+    }
+  }
+}

package/src/core-types.ts

@@ -214,9 +214,11 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   texture: 'Opaque<"texture">',
   render_target: 'Opaque<"render_target">',
   constant: 'Opaque<"constant">',
-  constant_buffer: 'Opaque<"constant_buffer">',
+  constant_buffer:
+    'Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }',
   buffer: 'Opaque<"buffer">',
-  bufferstream: 'Opaque<"bufferstream"> & { [index: number]: number }',
+  bufferstream:
+    'Opaque<"bufferstream"> & { [index: number]: number; length: LuaLengthMethod<number> }',
   userdata: 'Opaque<"userdata">',
   // Vocabulary, not a shipped brand: no current ref-doc fixture types a slot
   // `resource`, so nothing hand-written may name `Opaque<"resource">`. Kept so a

package/src/custom-messages.d.ts

@@ -41,14 +41,15 @@ declare global {
   // diagnostic at the call site rather than the declaration.
   /**
    * The payload declared for a message id: its `BuiltinMessages` entry, else
-   * its `CustomMessages` entry, else the open record an undeclared id keeps.
-   * An id declared in both resolves to the built-in payload.
+   * its `CustomMessages` entry, else the open table an undeclared id keeps: a
+   * record or a Lua sequence. An id declared in both resolves to the built-in
+   * payload.
    */
   type MessagePayload<K> = K extends BuiltinMessageId
     ? BuiltinMessages[K]
     : K extends keyof CustomMessages
       ? CustomMessages[K]
-      : Record<string | number, unknown>;
+      : Record<string | number, unknown> | readonly unknown[];
 }
 
 export {};

package/src/doc-comment.ts

@@ -1,19 +1,83 @@
 const NAMED_ENTITIES: Record<string, string> = {
-  "&lt;": "<",
-  "&gt;": ">",
-  "&quot;": '"',
-  "&#39;": "'",
-  "&apos;": "'",
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  // A non-breaking space in JSDoc is invisible noise; a plain space reads the same.
+  nbsp: " ",
+  times: "×",
+  copy: "©",
+  mdash: "—",
+  ndash: "–",
+  hellip: "…",
+  middot: "·",
+  deg: "°",
+  plusmn: "±",
+  le: "≤",
+  ge: "≥",
+  ne: "≠",
+  rarr: "→",
+  larr: "←",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
 };
 
+// One pass over the text, so a character an entity decodes to (`&amp;` -> `&`)
+// is never read as the start of another entity.
 function decodeEntities(text: string): string {
-  let out = text;
-  for (const [entity, char] of Object.entries(NAMED_ENTITIES)) {
-    out = out.split(entity).join(char);
+  return text.replace(/&(?:#[xX]([0-9a-fA-F]+)|#(\d+)|([a-zA-Z]+));/g, (entity, hex, dec, name) => {
+    if (hex !== undefined) return codePointOr(Number.parseInt(hex, 16), entity);
+    if (dec !== undefined) return codePointOr(Number(dec), entity);
+    return Object.hasOwn(NAMED_ENTITIES, name) ? (NAMED_ENTITIES[name] ?? entity) : entity;
+  });
+}
+
+function codePointOr(code: number, fallback: string): string {
+  return code <= 0x10ffff ? String.fromCodePoint(code) : fallback;
+}
+
+/**
+ * Join a list marker left alone on its line back onto the item's first content
+ * line. Upstream prose puts a newline between `<li>` and the item's first word,
+ * which the whitespace pass preserves, dropping the value out of the list. The
+ * item's remaining lines stay where they are: Markdown's lazy continuation
+ * already keeps an unindented line inside the item's paragraph.
+ */
+function weldStrandedListMarkers(text: string): string {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let inFence = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.startsWith("```")) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    if (inFence || line !== "-") {
+      out.push(line);
+      continue;
+    }
+    let ahead = index + 1;
+    while (ahead < lines.length && lines[ahead] === "") ahead += 1;
+    const content = lines[ahead];
+    if (
+      content === undefined ||
+      content === "-" ||
+      content.startsWith("- ") ||
+      content.startsWith("```")
+    ) {
+      // No value to weld onto — drop the marker and the blank run behind it.
+      index = ahead - 1;
+      continue;
+    }
+    out.push(`- ${content}`);
+    index = ahead;
   }
-  out = out.replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)));
-  // `&amp;` last so an already-decoded `&` is never re-interpreted.
-  return out.split("&amp;").join("&");
+  return out.join("\n").trim();
 }
 
 /**
@@ -45,6 +109,12 @@ export function htmlToDocText(html: string): string {
     .replace(/\n{3,}/g, "\n\n")
     .trim();
 
+  text = weldStrandedListMarkers(text);
+
+  // Upstream prose can open a fence and end mid-body; left open it swallows the
+  // rest of the JSDoc block and everything after it on the rendered page.
+  if ((text.match(/^```/gm) ?? []).length % 2 === 1) text += "\n```";
+
   // A literal `*/` would close the JSDoc comment early; escape it.
   return text.split("*/").join("*\\/");
 }
@@ -70,45 +140,169 @@ 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 fence via
- * `htmlToCodeText`. The fence language comes from a `class="language-X"` on the
- * block's `<code>` (as converted extension `.script_api` examples carry), else
- * `lua`, since engine ref-doc blocks carry no language class. 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 "";
+// One run of the `examples` fragment: the inner markup of a `<div
+// class="codehilite">` block, or the markup between two of them. `lang` is
+// meaningful on a code region only.
+interface ExampleRegion {
+  kind: "code" | "prose";
+  html: string;
+  lang: string;
+}
 
-  const parts: string[] = [];
+// The one `codehilite` walk. Both the markdown lane (`examplesHtmlToMarkdown`)
+// and the store lane (`splitExampleSources`) read their regions from here, so
+// the two cannot disagree about where an example begins. `matched` is false for
+// a fragment carrying no block at all, which both lanes treat as one whole-blob
+// code run.
+function scanExampleRegions(html: string): { matched: boolean; regions: ExampleRegion[] } {
+  const regions: ExampleRegion[] = [];
   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);
+    regions.push({ kind: "prose", html: html.slice(lastIndex, match.index), lang: "lua" });
     const inner = match[1] ?? "";
-    const lang = /<code\b[^>]*\bclass="language-([^"\s]+)"/i.exec(inner)?.[1] ?? "lua";
-    const code = htmlToCodeText(inner);
-    if (code !== "") parts.push(`\`\`\`${lang}\n${code}\n\`\`\``);
+    regions.push({
+      kind: "code",
+      html: inner,
+      lang: /<code\b[^>]*\bclass="language-([^"\s]+)"/i.exec(inner)?.[1] ?? "lua",
+    });
     lastIndex = match.index + match[0].length;
   }
+  if (!matched) return { matched: false, regions: [{ kind: "code", html, lang: "lua" }] };
+  regions.push({ kind: "prose", html: html.slice(lastIndex), lang: "lua" });
+  return { matched: true, regions };
+}
 
-  if (!matched) {
-    const code = htmlToCodeText(html);
-    return code === "" ? "" : `\`\`\`lua\n${code}\n\`\`\``;
-  }
+/**
+ * Convert a ref-doc `examples` HTML fragment — prose interleaved with one or
+ * more `<div class="codehilite">…</div>` syntax-highlight blocks — into Markdown,
+ * one fence per example that `segmentExampleRegions` carves out. Each segment
+ * emits its leading prose then a fence in its own language: `class="language-X"`
+ * on the block's `<code>` (as converted extension `.script_api` examples carry)
+ * or an inner ` ```X ` opener, else `lua`, since engine ref-doc blocks carry no
+ * language class. Prose trailing the last example is emitted last, and 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 {
+  const { segments, trailingProse } = segmentExampleRegions(html);
 
-  const trailing = htmlToDocText(html.slice(lastIndex));
-  if (trailing !== "") parts.push(trailing);
+  const parts: string[] = [];
+  for (const segment of segments) {
+    if (segment.prose !== "") parts.push(segment.prose);
+    parts.push(`\`\`\`${segment.lang}\n${segment.code}\n\`\`\``);
+  }
+  if (trailingProse !== "") parts.push(trailingProse);
 
   return parts.join("\n\n");
 }
 
+/** One example carved out of an `examples` fragment, with the prose leading it. */
+export interface ExampleSegment {
+  prose: string;
+  code: string;
+  lang: string;
+}
+
+// A line that opens a code run: ``` followed by a bare language token and
+// nothing else. Any other ``` line closes the run, its remainder being prose
+// upstream welded onto the fence.
+const FENCE_OPENER = /^```([A-Za-z0-9_+-]+)$/;
+
+/** The examples a fragment carries, plus any prose left over after the last one. */
+export interface ExampleSegmentation {
+  segments: ExampleSegment[];
+  /** Prose following the final code run, which belongs to no segment. */
+  trailingProse: string;
+}
+
+/**
+ * Carve an `examples` HTML fragment into one segment per example it carries.
+ *
+ * A `<div class="codehilite">` block is a code region and the markup between
+ * two of them is a prose region; inside either, a ` ``` ` line switches between
+ * code and prose, and an opener reached while already in code ends the running
+ * example and starts the next. Upstream writes several examples both ways — as
+ * several blocks, and as its own Markdown fences inside one block — so both
+ * signals are read.
+ *
+ * This is the walk alone: no whole-blob fallback, so a caller sees the real
+ * segments even where there is only one. `splitExampleSources` adds the
+ * stability post-pass that keys stored translations.
+ */
+export function segmentExampleRegions(html: string): ExampleSegmentation {
+  if (html.trim() === "") return { segments: [], trailingProse: "" };
+
+  const { regions } = scanExampleRegions(html);
+  const segments: ExampleSegment[] = [];
+  let codeLines: string[] = [];
+  let proseLines: string[] = [];
+  let lang = "lua";
+
+  const flush = () => {
+    const code = trimBlankEdges(codeLines).join("\n");
+    codeLines = [];
+    if (code === "") return;
+    segments.push({ prose: trimBlankEdges(proseLines).join("\n"), code, lang });
+    proseLines = [];
+  };
+
+  for (const region of regions) {
+    const text = region.kind === "code" ? htmlToCodeText(region.html) : htmlToDocText(region.html);
+    let inCode = region.kind === "code";
+    if (region.kind === "code") lang = region.lang;
+    // Prose surviving an empty code run keeps its paragraph break from the next.
+    if (region.kind === "prose" && text !== "" && proseLines.length > 0) proseLines.push("");
+    for (const line of text === "" ? [] : text.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("```")) {
+        (inCode ? codeLines : proseLines).push(line);
+        continue;
+      }
+      const opener = FENCE_OPENER.exec(trimmed);
+      if (opener) {
+        if (inCode) flush();
+        inCode = true;
+        lang = opener[1] ?? lang;
+        continue;
+      }
+      flush();
+      inCode = false;
+      const remainder = trimmed.slice(3).trim();
+      if (remainder !== "") proseLines.push(remainder);
+    }
+    flush();
+  }
+
+  return { segments, trailingProse: trimBlankEdges(proseLines).join("\n") };
+}
+
+/**
+ * `segmentExampleRegions` plus the stability post-pass: a fragment that yields
+ * at most one segment returns the whole-blob `htmlToCodeText` verbatim, prose
+ * lines included. That is the string every stored translation is pinned
+ * against, so a single-example element keeps its identity and cannot be re-keyed
+ * by this walk.
+ */
+export function splitExampleSources(html: string): ExampleSegment[] {
+  const { segments } = segmentExampleRegions(html);
+  if (segments.length > 1) return segments;
+  if (html.trim() === "") return [];
+  const whole = htmlToCodeText(html);
+  if (whole === "") return [];
+  return [{ prose: "", code: whole, lang: segments[0]?.lang ?? "lua" }];
+}
+
+function trimBlankEdges(lines: readonly string[]): string[] {
+  const out = [...lines];
+  while (out.length > 0 && out[0]?.trim() === "") out.shift();
+  while (out.length > 0 && out[out.length - 1]?.trim() === "") out.pop();
+  return out;
+}
+
 export interface DocCommentParts {
   summary: string;
   // Present exactly when the source carried a deprecation tag; `""` is the bare
@@ -117,8 +311,12 @@ export interface DocCommentParts {
   deprecated?: string;
   params?: { name: string; doc: string }[];
   returns?: string;
-  example?: string;
-  exampleLang?: "lua" | "ts";
+  // One entry per example the element documents, each rendered as its own
+  // `@example` block. An element whose ref-doc blob holds several examples
+  // carries several entries; a blank body is dropped. `prose` is the sentence
+  // introducing that example, rendered above its fence; blank or absent leaves
+  // the block byte-identical to a prose-less one.
+  examples?: { text: string; lang: "lua" | "ts"; prose?: string }[];
 }
 
 /**
@@ -129,14 +327,14 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   const summaryLines = parts.summary.trim() === "" ? [] : parts.summary.split("\n");
   const params = (parts.params ?? []).filter((p) => p.doc.trim() !== "");
   const returns = parts.returns?.trim() ? parts.returns : "";
-  const example = parts.example?.trim() ? parts.example : "";
+  const examples = (parts.examples ?? []).filter((entry) => entry.text.trim() !== "");
   const deprecated = parts.deprecated;
 
   if (
     summaryLines.length === 0 &&
     params.length === 0 &&
     returns === "" &&
-    example === "" &&
+    examples.length === 0 &&
     deprecated === undefined
   ) {
     return [];
@@ -147,7 +345,8 @@ export function renderDocComment(parts: DocCommentParts): string[] {
     lines.push(line === "" ? " *" : ` * ${line}`);
   }
 
-  const hasTags = deprecated !== undefined || params.length > 0 || returns !== "" || example !== "";
+  const hasTags =
+    deprecated !== undefined || params.length > 0 || returns !== "" || examples.length > 0;
   if (summaryLines.length > 0 && hasTags) {
     lines.push(" *");
   }
@@ -173,10 +372,15 @@ export function renderDocComment(parts: DocCommentParts): string[] {
       lines.push(line === "" ? " *" : ` * ${line}`);
     }
   }
-  if (example !== "") {
+  for (const entry of examples) {
     lines.push(" * @example");
-    lines.push(` * \`\`\`${parts.exampleLang ?? "lua"}`);
-    for (const line of example.split("\n")) {
+    if (entry.prose !== undefined && entry.prose.trim() !== "") {
+      for (const line of entry.prose.split("\n")) {
+        lines.push(line === "" ? " *" : ` * ${line}`);
+      }
+    }
+    lines.push(` * \`\`\`${entry.lang}`);
+    for (const line of entry.text.split("\n")) {
       lines.push(line === "" ? " *" : ` * ${line}`);
     }
     lines.push(" * ```");