@defold-typescript/types 0.54.0 → 0.56.0

package/examples/translations.json

@@ -795,8 +795,8 @@
   ],
   "gui.play_particlefx": [
     {
-      "sourceHash": "19a26b6e14ad0997",
-      "ts": "// How to play a particle fx when a gui node is created.\n// The callback receives the gui node, the hash of the id\n// of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.\nexport default defineGuiScript({\n  init(self) {\n    gui.play_particlefx(gui.get_node(\"particlefx\"), (self, node, emitter, state) => {\n      if (emitter === hash(\"exhaust\") && state === particlefx.EMITTER_STATE_POSTSPAWN) {\n        // exhaust is done spawning particles...\n      }\n    });\n  },\n});"
+      "sourceHash": "3a4e5cb8e98bf1a0",
+      "ts": "// How to play a particle fx when a gui node is created.\n// The callback receives the gui node, the hash of the id\n// of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.\nexport default defineGuiScript({\n  init(self) {\n    gui.play_particlefx(gui.get_node(\"particlefx\"), (self, node, emitter, state) => {\n      if (emitter === hash(\"exhaust\") && state === particlefx.EMITTER_STATE_POSTSPAWN) {\n        // exhaust is done spawning particles...\n      }\n    });\n  },\n});"
     }
   ],
   "gui.reset_material": [
@@ -1107,8 +1107,8 @@
   ],
   "particlefx.play": [
     {
-      "sourceHash": "01a21997b47ac4fc",
-      "ts": "// How to play a particle fx when a game object is created.\n// The callback receives the hash of the path to the particlefx, the hash of the id\n// of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.\nexport default defineScript({\n  init(self) {\n    particlefx.play(\"#particlefx\", (self, id, emitter, state) => {\n      if (emitter === hash(\"exhaust\") && state === particlefx.EMITTER_STATE_POSTSPAWN) {\n        // exhaust is done spawning particles...\n      }\n    });\n  },\n});"
+      "sourceHash": "ad5d0aba2677b291",
+      "ts": "// How to play a particle fx when a game object is created.\n// The callback receives the hash of the path to the particlefx, the hash of the id\n// of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.\nexport default defineScript({\n  init(self) {\n    particlefx.play(\"#particlefx\", (self, id, emitter, state) => {\n      if (emitter === hash(\"exhaust\") && state === particlefx.EMITTER_STATE_POSTSPAWN) {\n        // exhaust is done spawning particles...\n      }\n    });\n  },\n});"
     }
   ],
   "particlefx.reset_constant": [

package/generated/gui.d.ts

@@ -1355,7 +1355,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a gui node is created.
      * // The callback receives the gui node, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineGuiScript({
      *   init(self) {
      *     gui.play_particlefx(gui.get_node("particlefx"), (self, node, emitter, state) => {

package/generated/particlefx.d.ts

@@ -45,7 +45,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a game object is created.
      * // The callback receives the hash of the path to the particlefx, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineScript({
      *   init(self) {
      *     particlefx.play("#particlefx", (self, id, emitter, state) => {

package/generated/versions/defold-1.12.4/gui.d.ts

@@ -1324,7 +1324,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a gui node is created.
      * // The callback receives the gui node, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineGuiScript({
      *   init(self) {
      *     gui.play_particlefx(gui.get_node("particlefx"), (self, node, emitter, state) => {

package/generated/versions/defold-1.12.4/model.d.ts

@@ -53,7 +53,7 @@ declare global {
      * AABB information return as a table with `min` and `max` fields, where `min` and `max` has type `vmath.vector3`.
      *
      * @param url - the model
-     * @returns A table containing info about all AABB in the format
+     * @returns A table containing info about all AABB in the format <hash(mesh_id), aabb_info>
      * @example
      * ```ts
      * model.get_mesh_aabb("#model"); // => { hash("Sword") = { min = vmath.vector3(-0.5, -0.5, 0), max = vmath.vector3(0.5, 0.5, 0) }, hash("Shield") = { min = vmath.vector3(-0.5, -0.5, -0.5), max = vmath.vector3(0.5, 0.5, 0.5) } }

package/generated/versions/defold-1.12.4/particlefx.d.ts

@@ -49,7 +49,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a game object is created.
      * // The callback receives the hash of the path to the particlefx, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineScript({
      *   init(self) {
      *     particlefx.play("#particlefx", (self, id, emitter, state) => {

package/generated/versions/defold-1.12.4/resource.d.ts

@@ -102,10 +102,10 @@ declare global {
      * number the height of the animation
      *
      * - `frame_start`
-     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `frame_end`
-     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `playback`
      * constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD
@@ -1096,10 +1096,10 @@ declare global {
      * number the height of the animation
      *
      * - `frame_start`
-     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `frame_end`
-     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `playback`
      * constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD

package/generated/versions/defold-1.13.0/gui.d.ts

@@ -1322,7 +1322,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a gui node is created.
      * // The callback receives the gui node, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineGuiScript({
      *   init(self) {
      *     gui.play_particlefx(gui.get_node("particlefx"), (self, node, emitter, state) => {

package/generated/versions/defold-1.13.0/model.d.ts

@@ -72,7 +72,7 @@ declare global {
      * AABB information return as a table with `min` and `max` fields, where `min` and `max` has type `vmath.vector3`.
      *
      * @param url - the model
-     * @returns A table containing info about all AABB in the format
+     * @returns A table containing info about all AABB in the format <hash(mesh_id), aabb_info>
      * @example
      * ```ts
      * model.get_mesh_aabb("#model"); // => { hash("Sword") = { min = vmath.vector3(-0.5, -0.5, 0), max = vmath.vector3(0.5, 0.5, 0) }, hash("Shield") = { min = vmath.vector3(-0.5, -0.5, -0.5), max = vmath.vector3(0.5, 0.5, 0.5) } }

package/generated/versions/defold-1.13.0/particlefx.d.ts

@@ -49,7 +49,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a game object is created.
      * // The callback receives the hash of the path to the particlefx, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineScript({
      *   init(self) {
      *     particlefx.play("#particlefx", (self, id, emitter, state) => {

package/generated/versions/defold-1.13.0/resource.d.ts

@@ -102,10 +102,10 @@ declare global {
      * number the height of the animation
      *
      * - `frame_start`
-     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `frame_end`
-     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `playback`
      * constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD
@@ -1100,10 +1100,10 @@ declare global {
      * number the height of the animation
      *
      * - `frame_start`
-     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `frame_end`
-     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `playback`
      * constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD

package/generated/versions/defold-1.13.1/gui.d.ts

@@ -1322,7 +1322,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a gui node is created.
      * // The callback receives the gui node, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineGuiScript({
      *   init(self) {
      *     gui.play_particlefx(gui.get_node("particlefx"), (self, node, emitter, state) => {

package/generated/versions/defold-1.13.1/model.d.ts

@@ -72,7 +72,7 @@ declare global {
      * AABB information return as a table with `min` and `max` fields, where `min` and `max` has type `vmath.vector3`.
      *
      * @param url - the model
-     * @returns A table containing info about all AABB in the format
+     * @returns A table containing info about all AABB in the format <hash(mesh_id), aabb_info>
      * @example
      * ```ts
      * model.get_mesh_aabb("#model"); // => { hash("Sword") = { min = vmath.vector3(-0.5, -0.5, 0), max = vmath.vector3(0.5, 0.5, 0) }, hash("Shield") = { min = vmath.vector3(-0.5, -0.5, -0.5), max = vmath.vector3(0.5, 0.5, 0.5) } }

package/generated/versions/defold-1.13.1/particlefx.d.ts

@@ -49,7 +49,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a game object is created.
      * // The callback receives the hash of the path to the particlefx, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineScript({
      *   init(self) {
      *     particlefx.play("#particlefx", (self, id, emitter, state) => {

package/generated/versions/defold-1.13.1/resource.d.ts

@@ -102,10 +102,10 @@ declare global {
      * number the height of the animation
      *
      * - `frame_start`
-     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `frame_end`
-     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `playback`
      * constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD
@@ -1100,10 +1100,10 @@ declare global {
      * number the height of the animation
      *
      * - `frame_start`
-     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the first geometry of the animation. Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `frame_end`
-     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. in atlas.
+     * number index to the last geometry of the animation (non-inclusive). Indices are lua based and must be in the range of 1 .. <number-of-geometries> in atlas.
      *
      * - `playback`
      * constant optional playback mode of the animation, the default value is go.PLAYBACK_ONCE_FORWARD

package/generated/versions/defold-1.13.2/gui.d.ts

@@ -1355,7 +1355,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a gui node is created.
      * // The callback receives the gui node, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineGuiScript({
      *   init(self) {
      *     gui.play_particlefx(gui.get_node("particlefx"), (self, node, emitter, state) => {

package/generated/versions/defold-1.13.2/particlefx.d.ts

@@ -45,7 +45,7 @@ declare global {
      * ```ts
      * // How to play a particle fx when a game object is created.
      * // The callback receives the hash of the path to the particlefx, the hash of the id
-     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
+     * // of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_<STATE>.
      * export default defineScript({
      *   init(self) {
      *     particlefx.play("#particlefx", (self, id, emitter, state) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -62,6 +62,11 @@
       "bun": "./scripts/cli-runtime.ts",
       "default": "./dist/cli-runtime.js"
     },
+    "./library-runtime": {
+      "types": "./scripts/library-runtime.ts",
+      "bun": "./scripts/library-runtime.ts",
+      "default": "./dist/library-runtime.js"
+    },
     "./api-availability.json": "./api-availability.json",
     "./api-signatures.json": "./api-signatures.json",
     "./url-parameters.json": "./url-parameters.json",
@@ -80,6 +85,7 @@
     "url-parameters.json",
     "index.d.ts",
     "dist/cli-runtime.js",
+    "dist/library-runtime.js",
     "fixtures/messages_doc.json",
     "fixtures/defold-*/**",
     "!fixtures/defold-*/engine-bindings/**",
@@ -118,7 +124,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && bun run build:cli-runtime",
-    "build:cli-runtime": "bun build scripts/cli-runtime.ts --target=node --format=esm --packages=external --outdir=dist",
+    "build:cli-runtime": "bun build scripts/cli-runtime.ts scripts/library-runtime.ts --target=node --format=esm --packages=external --outdir=dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "regen": "bun scripts/regen.ts",
     "generate-api-availability": "bun scripts/generate-api-availability.ts",

package/scripts/cli-runtime.ts

@@ -15,4 +15,9 @@ export {
   targetKindManifest,
 } from "./materialize-version";
 export { generateGlobalTableDeclaration, generateModuleDeclaration } from "./regen";
-export { readZip, scriptApiToFixtureJson, type ZipAccessor } from "./sync-api-docs";
+export {
+  readZip,
+  scriptApiToFixtureJson,
+  type ZipAccessor,
+  type ZipArchive,
+} from "./sync-api-docs";

package/scripts/doc-source.ts

@@ -138,7 +138,7 @@ export async function resolveRefDoc(opts: {
   channel?: RefDocChannel;
   download?: DownloadRefDoc;
   locate?: LocateLocalRefDoc;
-  readZip?: typeof readZip;
+  readZip?: (path: string) => ZipAccessor;
   fetchChannelInfo?: FetchChannelInfo;
 }): Promise<ResolvedRefDoc> {
   const open = opts.readZip ?? readZip;

package/scripts/extension-goldens.ts

@@ -13,11 +13,11 @@ export const EXTENSION_GOLDENS_DIR = "extension-goldens";
 const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
 const EXTENSION_GOLDEN_NAMESPACES = ["iac", "iap", "push", "webview"] as const;
 
-// Each golden's doc is the conversion of the extension's `.script_api` at its
-// `packages/library-types/defold-extensions.json` pin, the same JSON the
-// Libraries pages render, so a golden carries the namespace's constants, optional
-// slots and callback arguments exactly as `resolve` would emit them for a project.
-const EXTENSION_DOCS_DIR = resolve(PACKAGE_ROOT, "../library-types/defold-extensions/api-doc");
+// Each golden's doc is a copy of the conversion of the extension's `.script_api`
+// at its `defold-extensions.json` pin, the same JSON the Libraries pages render,
+// so a golden carries the namespace's constants, optional slots and callback
+// arguments exactly as `resolve` would emit them for a project.
+const EXTENSION_DOCS_DIR = resolve(PACKAGE_ROOT, "fixtures/extension-docs");
 
 export const EXTENSION_GOLDEN_MANIFEST: readonly ModuleManifestEntry[] =
   EXTENSION_GOLDEN_NAMESPACES.map((namespace) => ({

package/scripts/generate-api-signatures.ts

@@ -23,7 +23,7 @@ export interface SignaturesArtifact {
   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
-  // (`api-surface-loader`, `combined-surface`, `version-window`) type that map's
+  // (`toolchain-surface-loader`, `combined-surface`, `version-window`) type that map's
   // value as a string; a symbol documenting no slot is absent here.
   readonly slotTypes: Record<string, Record<string, SlotTypes>>;
 }

package/scripts/library-runtime.ts

@@ -0,0 +1,22 @@
+// The emitter helpers the CLI's library printer imports statically, published as
+// `@defold-typescript/types/library-runtime` and resolved the way `cli-runtime`
+// is: Bun's `bun` condition to this source, Node's `default` to the bundle built
+// beside it (`dist/library-runtime.js`). It stays apart from `cli-runtime`, whose
+// `regen.ts` reads target registries at load: a static import lands at the top of
+// the CLI bundle, so everything here must be safe to load on every command.
+
+export { renderDocComment } from "../src/doc-comment";
+export { isKnownDefoldTypeToken, TS_IDENTIFIER, TS_RESERVED_NAMES } from "../src/emit-dts";
+export {
+  appendNotes,
+  libraryIndexBaseNotes,
+  parseLibraryIndexSlotClassifications,
+} from "../src/index-slot-classifications";
+export { luaMultiReturn, varargElementType } from "../src/library-signature";
+export {
+  LUALS_VARARG_TOKEN,
+  mapLualsCallSignatureExpression,
+  mapLualsExpression,
+  matchBracket,
+  splitTopLevel,
+} from "../src/luals-type-expr";

package/scripts/regen.ts

@@ -43,7 +43,7 @@ import {
 import { loadTranslations } from "./example-store-io";
 import { synthesizeProseConstants } from "./prose-constants";
 import { restoreSharedHandleMethods } from "./shared-handle-methods";
-import { groupDocsByNamespace, mergeApiDocs, type readZip } from "./sync-api-docs";
+import { groupDocsByNamespace, mergeApiDocs, type ZipAccessor } from "./sync-api-docs";
 import { compareVersions, versionOf } from "./target-version";
 
 export interface ApiTargetModule {
@@ -184,7 +184,7 @@ export interface ModuleManifestEntry {
 export interface ResolveTargetOptions {
   readonly cacheDir?: string;
   readonly download?: DownloadRefDoc;
-  readonly readZip?: typeof readZip;
+  readonly readZip?: (path: string) => ZipAccessor;
   readonly packageRoot?: string;
   readonly channel?: RefDocChannel;
   readonly fetchChannelInfo?: FetchChannelInfo;

package/scripts/sync-api-docs.ts

@@ -273,6 +273,17 @@ export interface ZipAccessor {
   entries(): string[];
 }
 
+// What `readZip` returns beyond the ref-doc seam, for the extension-archive
+// resolver, which pins a dependency by what this exposes.
+export interface ZipArchive extends ZipAccessor {
+  // An entry's bytes as stored, for a file that is not UTF-8 text or whose
+  // exact content is hashed.
+  bytes(entry: string): Uint8Array;
+  // The archive comment, `""` when there is none. A GitHub archive carries the
+  // commit it was packed from here, as `git archive` writes it.
+  comment(): string;
+}
+
 const ZIP_LOCAL_HEADER_SIGNATURE = 0x04034b50;
 const ZIP_CENTRAL_HEADER_SIGNATURE = 0x02014b50;
 const ZIP_END_RECORD_SIGNATURE = 0x06054b50;
@@ -349,8 +360,12 @@ function readCentralDirectory(
 // A comment may itself contain an end record, so a candidate counts only when
 // its own comment length reaches exactly to the end of the archive and it
 // describes a central directory ending at it. When no candidate does, the
-// nearest one's own defect is reported.
-function readZipDirectory(bytes: Buffer, path: string): Map<string, ZipDirectoryEntry> {
+// nearest one's own defect is reported. The comment is everything after the
+// record that counted.
+function readZipDirectory(
+  bytes: Buffer,
+  path: string,
+): { entries: Map<string, ZipDirectoryEntry>; comment: string } {
   const earliest = Math.max(0, bytes.length - ZIP_END_RECORD_SIZE - ZIP_MAX_COMMENT_SIZE);
   let nearestDefect: Error | undefined;
   for (let at = bytes.length - ZIP_END_RECORD_SIZE; at >= earliest; at--) {
@@ -360,7 +375,10 @@ function readZipDirectory(bytes: Buffer, path: string): Map<string, ZipDirectory
     ) {
       const directory = readCentralDirectory(bytes, at, path);
       if (!(directory instanceof Error)) {
-        return directory;
+        return {
+          entries: directory,
+          comment: bytes.toString("utf8", at + ZIP_END_RECORD_SIZE, bytes.length),
+        };
       }
       nearestDefect ??= directory;
     }
@@ -374,33 +392,36 @@ function readZipDirectory(bytes: Buffer, path: string): Map<string, ZipDirectory
 // Parses the archive itself rather than shelling out to `unzip`, which a stock
 // Windows machine does not have: the CLI opens extension archives through this
 // under Node and Bun on every OS.
-export function readZip(path: string): ZipAccessor {
+export function readZip(path: string): ZipArchive {
   const bytes = readFileSync(path);
-  const entries = readZipDirectory(bytes, path);
+  const { entries, comment } = readZipDirectory(bytes, path);
+  const entryBytes = (name: string): Buffer => {
+    const entry = entries.get(name);
+    if (entry === undefined) {
+      throw new Error(`no entry ${name} in ${path}`);
+    }
+    const { localHeaderOffset, compressedSize, method } = entry;
+    if (bytes.readUInt32LE(localHeaderOffset) !== ZIP_LOCAL_HEADER_SIGNATURE) {
+      throw new Error(`${path}: local header of ${name} has no signature`);
+    }
+    const nameLength = bytes.readUInt16LE(localHeaderOffset + 26);
+    const extraLength = bytes.readUInt16LE(localHeaderOffset + 28);
+    const start = localHeaderOffset + 30 + nameLength + extraLength;
+    const data = bytes.subarray(start, start + compressedSize);
+    if (method === ZIP_METHOD_STORED) {
+      return data;
+    }
+    if (method === ZIP_METHOD_DEFLATE) {
+      return inflateRawSync(data);
+    }
+    throw new Error(`${path}: entry ${name} uses unsupported compression method ${method}`);
+  };
   return {
     has: (name) => entries.has(name),
     entries: () => [...entries.keys()],
-    read: (name) => {
-      const entry = entries.get(name);
-      if (entry === undefined) {
-        throw new Error(`no entry ${name} in ${path}`);
-      }
-      const { localHeaderOffset, compressedSize, method } = entry;
-      if (bytes.readUInt32LE(localHeaderOffset) !== ZIP_LOCAL_HEADER_SIGNATURE) {
-        throw new Error(`${path}: local header of ${name} has no signature`);
-      }
-      const nameLength = bytes.readUInt16LE(localHeaderOffset + 26);
-      const extraLength = bytes.readUInt16LE(localHeaderOffset + 28);
-      const start = localHeaderOffset + 30 + nameLength + extraLength;
-      const data = bytes.subarray(start, start + compressedSize);
-      if (method === ZIP_METHOD_STORED) {
-        return data.toString("utf8");
-      }
-      if (method === ZIP_METHOD_DEFLATE) {
-        return inflateRawSync(data).toString("utf8");
-      }
-      throw new Error(`${path}: entry ${name} uses unsupported compression method ${method}`);
-    },
+    read: (name) => entryBytes(name).toString("utf8"),
+    bytes: (name) => new Uint8Array(entryBytes(name)),
+    comment: () => comment,
   };
 }
 

package/src/doc-comment.ts

@@ -87,6 +87,37 @@ function weldStrandedListMarkers(text: string): string {
   return out.join("\n").trim();
 }
 
+// What counts as markup in upstream prose: the tags the docs use, plus any tag
+// assigning an attribute. Every other `<` is text, as in `Values <= 0` or
+// `<logger_name>.log`. A listed name must close straight away, because a
+// comparison such as `a <b and c> d` reads the same as a tag with bare
+// attributes. `object` stays off the list: `wrap` documents `<object>` as text.
+// `lia` and `super` are upstream typos. The toolchain docs site renders this
+// output with `html: true`, so script-bearing elements go whatever follows their
+// name, and a quoted attribute value may hold a `<` a browser reads as part of
+// the tag.
+const MARKUP_TAG = new RegExp(
+  [
+    "</?(?:a|b|blockquote|br|code|dd|div|dl|dt|em|h[1-6]|hr|i|iframe|img|kbd|li|lia|ol|p|pre|s|script|small|span|strong|style|sub|sup|super|table|tbody|td|tfoot|th|thead|tr|u|ul)\\s*/?>",
+    "</?(?:script|style|iframe)\\b[^<>]*>",
+    "</?[a-z][^<>=]*=(?:[^<>\"']|\"[^\"]*\"|'[^']*')*>",
+    "</?[a-z][^<>=]*=[^<>]*>",
+  ].join("|"),
+  "gi",
+);
+
+// Removing a tag can join the text around it into a new one (`<scr<b>ipt>`), so
+// this repeats until nothing changes.
+function stripMarkup(html: string): string {
+  let text = html;
+  let previous: string;
+  do {
+    previous = text;
+    text = text.replace(MARKUP_TAG, "");
+  } while (text !== previous);
+  return text;
+}
+
 // Upstream Markdown indented one level too deep is highlighted as code while
 // still reading as Markdown: every line opens on a backtick-quoted name, as in
 // the field table `graphics.get_adapter_info` documents under `limits`. That
@@ -156,10 +187,9 @@ export function htmlToDocText(html: string): string {
       return close ? "" : `\n${LIST_INDENT.repeat(Math.max(0, listDepth - 1))}- `;
     })
     .replace(/<br\s*\/?>/gi, "\n")
-    .replace(/<\/p>/gi, "\n\n")
-    .replace(/<[^>]+>/g, "");
+    .replace(/<\/p>/gi, "\n\n");
 
-  text = decodeEntities(text);
+  text = decodeEntities(stripMarkup(text));
 
   // Collapse horizontal whitespace runs, trim around newlines, fold runaway
   // blank runs to one blank line, then trim the whole string — preserving
@@ -195,8 +225,8 @@ export function htmlToDocText(html: string): string {
  * runs of blank lines to one. Returns `""` for empty / whitespace-only input.
  */
 export function htmlToCodeText(html: string): string {
-  let text = html.replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, "");
-  text = decodeEntities(text);
+  const stripped = stripMarkup(html.replace(/<br\s*\/?>/gi, "\n"));
+  const text = decodeEntities(stripped);
 
   const lines = text.split("\n").map((line) => line.replace(/[ \t]+$/g, ""));
   while (lines.length > 0 && lines[0] === "") lines.shift();
@@ -479,6 +509,7 @@ export function renderDocComment(parts: DocCommentParts): string[] {
     lines.push(" * ```");
   }
 
-  lines.push(" */");
-  return lines;
+  // Doc text holding `*/` would end the comment and leak the rest into the
+  // declaration.
+  return [...lines.map((line) => line.replaceAll("*/", "*\\/")), " */"];
 }

package/src/index-slot-classifications.ts

@@ -568,8 +568,8 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 // multi-value return as a field of that return (`cast:return::tile_x`). A
 // typedef method is keyed by its bare name, so one key covers every class of the
 // page that declares that method.
-// `docs-site/app/lib/library-index-slot-gate.test.ts` reds on a scanned slot
-// missing from `library-types/index-slot-classifications.json` and on an entry
+// The library docs site's `site/app/lib/library-index-slot-gate.test.ts` reds on a scanned slot
+// missing from the library data folder's `index-slot-classifications.json` and on an entry
 // no library page declares.
 export function parseLibraryIndexSlotClassifications(
   json: unknown,

package/src/library-signature.ts

@@ -1,9 +1,9 @@
 /**
  * Pure string helpers for rendering variadic parameters and multi-value returns
  * the way the library `.d.ts` emitter does. Shared by the emitter
- * (`packages/library-types`) and the docs-site renderer (`packages/docs-site`),
+ * (`packages/cli/src/library`) and the docs-site renderer (`packages/docs-site`),
  * which both depend on `@defold-typescript/types`, so a library `/api` signature
- * cannot drift from the shipped `generated/<ns>.d.ts` for these two shapes — the
+ * cannot drift from the printed library declaration for these two shapes — the
  * same anti-drift move the type/name/generic primitives already use.
  */
 

package/src/luals-type-expr.ts

@@ -3,7 +3,7 @@
  * grouping parentheses, `fun(...)`, `table<K, V>`, inline records, string, numeric
  * and boolean literals), shared by the engine lane (`emit-dts.ts`
  * `defaultMapType`) and the library lane
- * (`packages/library-types/scripts/map-luals-types.ts`). Pure and deterministic.
+ * (`packages/cli/src/library/map-luals-types.ts`). Pure and deterministic.
  *
  * Every name that is not structure — `integer`, `table`, `function`, `...`,
  * `vmath.vector3`, `druid.component` — is a leaf handed to the caller's