@defold-typescript/types 0.23.0 → 0.25.0

package/scripts/sync-api-docs.ts

@@ -24,6 +24,10 @@ export interface SyncManifestEntry {
   // docs (e.g. `sys`) is reassembled before parse, so the emitter still sees one
   // fixture, one namespace.
   readonly mergeEntries?: readonly string[];
+  // Extract only this namespace's elements from `zipEntry` and rewrite
+  // `info.namespace`. One upstream document that carries several top-level
+  // namespaces (the editor apidoc) becomes one fixture per namespace.
+  readonly split?: true;
 }
 
 // namespace -> ref-doc.zip entry. Entry paths do not match the namespace (gui ->
@@ -122,7 +126,6 @@ const LUA_NAMESPACE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
 // `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",
@@ -158,6 +161,46 @@ export const LUA_STDLIB_MANIFEST: readonly SyncManifestEntry[] = [
   entry("package", "doc/lua_package.doc_h_doc.json"),
 ];
 
+// The editor-scripting API. It runs in the Defold *editor's* Lua VM, not the
+// game runtime, so it is deliberately not a `MODULE_MANIFEST` citizen: that
+// manifest drives every runtime kind's universal import set, the per-version
+// targets, `api-availability.json` / `api-signatures.json` and the docs-site API
+// pages, none of which describe the editor. It still syncs and emits through the
+// same machinery (`EDITOR_MODULE_MANIFEST` in regen.ts writes
+// `generated/editor.d.ts`), reached only through the `editor-script` kind index.
+export const EDITOR_MANIFEST: readonly SyncManifestEntry[] = [
+  entry("editor", "doc/editor.apidoc_doc.json"),
+];
+
+// The non-`editor.*` namespaces the same editor apidoc carries. Each is split
+// out of that one document into its own fixture; the `editor` entry above keeps
+// vendoring the document whole, so `editor_doc.json` is unaffected.
+//
+// Deliberately absent from `COVERAGE_MANIFEST`, `UPSTREAM_MAPPED_NAMESPACES`
+// and `syncedDocs`: these exist only in the editor VM, so marking them mapped
+// would tell the upstream-coverage guard the *runtime* covers `zip`, `pprint`
+// and `tilemap.tiles` and silently suppress a future real miss. Fixture paths
+// are explicit because the default would collide with the unrelated runtime
+// `http_doc.json` / `json_doc.json` / `zlib_doc.json`.
+export const EDITOR_VM_MANIFEST: readonly SyncManifestEntry[] = [
+  editorVm("http"),
+  editorVm("json"),
+  editorVm("localization"),
+  editorVm("zip"),
+  editorVm("zlib"),
+  editorVm("pprint"),
+  editorVm("tilemap.tiles"),
+];
+
+function editorVm(namespace: string): SyncManifestEntry {
+  return {
+    namespace,
+    zipEntry: "doc/editor.apidoc_doc.json",
+    fixture: `fixtures/defold-${DEFOLD_VERSION}/editor_${namespace.replace(/\./g, "_")}_doc.json`,
+    split: true,
+  };
+}
+
 function entry(
   namespace: string,
   zipEntry: string,
@@ -196,6 +239,21 @@ function ext(namespace: string, repo: string, tag: string, path: string): Extens
   };
 }
 
+// Every vendored fixture set the coverage report audits, and the namespaces it
+// counts as reached from upstream. Composed once here so the `--check` run and
+// the guard over it cannot disagree about which sets are in scope.
+export const COVERAGE_MANIFEST: readonly { readonly namespace: string }[] = [
+  ...SYNC_MANIFEST,
+  ...EXTENSION_MANIFEST,
+  ...EDITOR_MANIFEST,
+];
+
+export const UPSTREAM_MAPPED_NAMESPACES: ReadonlySet<string> = new Set(
+  [...SYNC_MANIFEST, ...EXTENSION_MANIFEST, ...LUA_STDLIB_MANIFEST, ...EDITOR_MANIFEST].map(
+    (e) => e.namespace,
+  ),
+);
+
 export const extensionRawUrl = (e: ExtensionManifestEntry): string =>
   `https://raw.githubusercontent.com/${e.repo}/${e.tag}/${e.path}`;
 
@@ -328,6 +386,21 @@ function normalizedArguments(value: unknown): string {
   );
 }
 
+// Segment-wise ownership: `pprint` owns `pprint` and `pprint.x` but never
+// `pprintx`, and `tilemap.tiles` never claims `tilemap.set_tile`.
+function ownsElement(name: string, namespace: string): boolean {
+  return name === namespace || name.startsWith(`${namespace}.`);
+}
+
+function splitNamespace(contents: string, namespace: string): string {
+  const doc = JSON.parse(contents);
+  const elements = (Array.isArray(doc.elements) ? doc.elements : []).filter(
+    (element: unknown) =>
+      isRecord(element) && typeof element.name === "string" && ownsElement(element.name, namespace),
+  );
+  return JSON.stringify({ ...doc, info: { ...doc.info, namespace }, elements });
+}
+
 export function extractFixtures(
   zip: ZipAccessor,
   manifest: readonly SyncManifestEntry[] = SYNC_MANIFEST,
@@ -339,10 +412,11 @@ export function extractFixtures(
         throw new Error(`zip is missing entry ${source} for namespace ${item.namespace}`);
       }
     }
-    const contents =
+    const merged =
       item.mergeEntries === undefined
         ? zip.read(item.zipEntry)
         : JSON.stringify(mergeApiDocs(sources.map((source) => JSON.parse(zip.read(source)))));
+    const contents = item.split ? splitNamespace(merged, item.namespace) : merged;
     return { namespace: item.namespace, fixture: item.fixture, contents };
   });
 }
@@ -602,24 +676,26 @@ if (import.meta.main) {
   const coreFixtures = extractFixtures(zip);
   const extensionFixtures = await downloadExtensionFixtures();
   const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
+  const editorFixtures = extractFixtures(zip, EDITOR_MANIFEST);
+  const editorVmFixtures = extractFixtures(zip, EDITOR_VM_MANIFEST);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
     ...syncExtractedFixtures(extensionFixtures, { check }),
     ...syncExtractedFixtures(luaStdlibFixtures, { check }),
+    ...syncExtractedFixtures(editorFixtures, { check }),
+    ...syncExtractedFixtures(editorVmFixtures, { check }),
   ];
   const syncedDocs = [...coreFixtures, ...extensionFixtures].map((f) => ({
     namespace: f.namespace,
     doc: JSON.parse(f.contents),
   }));
   const report = buildCoverageReport({
-    manifest: [...SYNC_MANIFEST, ...EXTENSION_MANIFEST],
+    manifest: COVERAGE_MANIFEST,
     moduleManifest: MODULE_MANIFEST,
     unmapped: UNMAPPED,
     syncedDocs,
     upstream: collectUpstreamNamespaces(zip),
-    upstreamMapped: new Set(
-      [...SYNC_MANIFEST, ...EXTENSION_MANIFEST, ...LUA_STDLIB_MANIFEST].map((e) => e.namespace),
-    ),
+    upstreamMapped: UPSTREAM_MAPPED_NAMESPACES,
     ignoredUpstream: IGNORED_UPSTREAM,
   });
   printReport(results, report, check);

package/src/api-doc.ts

@@ -20,12 +20,16 @@ export interface ApiTypedef {
   name: string;
   functions?: ApiFunction[];
   properties?: ApiVariable[];
+  /** See {@link ApiFunction.global}. */
+  global?: true;
 }
 
 export interface ApiConstant {
   name: string;
   brief: string;
   description: string;
+  /** See {@link ApiFunction.global}. */
+  global?: true;
 }
 
 export interface ApiFunction {
@@ -41,6 +45,27 @@ export interface ApiFunction {
    * library functions; engine ref-docs carry no `generics`, so it stays absent.
    */
   generics?: string;
+  /**
+   * Present exactly when the source carried a `@deprecated` tag; `""` for a bare
+   * tag. Absence is the only encoding of "not deprecated", so a bare tag stays
+   * distinguishable from an untagged symbol.
+   */
+  deprecated?: string;
+  /**
+   * Present exactly when the source declared the symbol as an ambient global —
+   * outside the library's `declare module` block — so it is reachable without
+   * the module import. Absence is the only encoding of "module member"; the key
+   * is never written as `false`.
+   */
+  global?: true;
+  /**
+   * Present exactly when this symbol's prose was imported from the upstream
+   * source rather than written in the declaration — the authored/forked library
+   * lane lowers upstream's own LuaDoc summary for a member its fork documents
+   * nowhere. Absence is the only encoding of first-party prose, so every engine
+   * and hand-authored symbol reads as before.
+   */
+  docSource?: "upstream";
 }
 
 export interface ApiParameter {
@@ -67,6 +92,30 @@ export interface ApiVariable {
   brief: string;
   description: string;
   types: string[];
+  /**
+   * True for an optional member of a typedef shape (`clear?: boolean`). Set only
+   * when the element carries `is_optional: "True"`, so a module-level engine
+   * ref-doc VARIABLE — which never carries the key — leaves it absent.
+   */
+  isOptional?: boolean;
+  /** See {@link ApiFunction.deprecated}. */
+  deprecated?: string;
+  /** See {@link ApiFunction.global}. */
+  global?: true;
+  /** See {@link ApiFunction.docSource}. */
+  docSource?: "upstream";
+}
+
+/** The `{ global }` key to spread onto a parsed element, empty for a module member. */
+function globalKey(element: Record<string, unknown>): { global?: true } {
+  return element.global === true ? { global: true } : {};
+}
+
+/** The `{ docSource }` key to spread onto a parsed element, empty for first-party
+ * prose. Only the one recognised value yields a key: an unknown provenance would
+ * otherwise reach a page with no marker the render layer knows how to draw. */
+function docSourceKey(element: Record<string, unknown>): { docSource?: "upstream" } {
+  return element.docSource === "upstream" ? { docSource: "upstream" } : {};
 }
 
 export function parseDefoldApiDoc(input: unknown): ApiModule {
@@ -119,6 +168,7 @@ function parseTypedef(element: Record<string, unknown>): ApiTypedef {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
+    ...globalKey(element),
   };
 }
 
@@ -145,6 +195,7 @@ function parseConstant(element: Record<string, unknown>): ApiConstant {
     name: stringOr(element.name, ""),
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
+    ...globalKey(element),
   };
 }
 
@@ -157,6 +208,9 @@ function parseFunction(element: Record<string, unknown>): ApiFunction {
     returnValues: parseParameterList(element.returnvalues),
     examples: stringOr(element.examples, ""),
     ...(typeof element.generics === "string" ? { generics: element.generics } : {}),
+    ...(typeof element.deprecated === "string" ? { deprecated: element.deprecated } : {}),
+    ...globalKey(element),
+    ...docSourceKey(element),
   };
 }
 
@@ -166,6 +220,10 @@ function parseVariable(element: Record<string, unknown>): ApiVariable {
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
     types: parseStringArray(element.types),
+    ...(element.is_optional === "True" ? { isOptional: true } : {}),
+    ...(typeof element.deprecated === "string" ? { deprecated: element.deprecated } : {}),
+    ...globalKey(element),
+    ...docSourceKey(element),
   };
 }
 

package/src/core-types.ts

@@ -88,6 +88,7 @@ export interface Matrix4 {
 }
 
 declare const HashBrand: unique symbol;
+declare const HashSource: unique symbol;
 /**
  * An opaque, branded handle to a *hashed name*: hold it and pass it back to the
  * engine API, but never inspect or construct it. Defold uses it in place of a
@@ -111,9 +112,22 @@ declare const HashBrand: unique symbol;
  * `hash_to_hex(h)` renders it as a hexadecimal string for logging, and `pprint`
  * shows it as `hash: [0x…]`. Two hashes are equal exactly when they name the
  * same thing, so a `Hash` is safe to compare, store, and use as a table key.
+ *
+ * The `S` parameter records the string `hash()` was called with, so a tool can
+ * *read* an address back out of `const SPRITE = hash("#sprite")`. It is not a
+ * checked constraint: it defaults to `string`, so every bare `Hash` keeps
+ * meaning what it always did, and its phantom member is optional, so `Hash` and
+ * `Hash<"#sprite">` stay assignable to each other in both directions. Nothing
+ * that compiles without it stops compiling with it.
  */
-export interface Hash {
+export interface Hash<S extends string = string> {
   readonly [HashBrand]: "Hash";
+  // Method syntax, and load-bearing: a method's parameters are compared
+  // bivariantly, which is what keeps `Hash` and `Hash<"#sprite">` assignable in
+  // *both* directions. Written as a plain optional property (`?: S`) the
+  // parameter would be covariant, and passing a bare `Hash` where a sourced one
+  // is expected would start failing — the one thing this type must never do.
+  [HashSource]?(source: S): void;
 }
 
 declare const OpaqueBrand: unique symbol;
@@ -188,6 +202,9 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   vector4: "Vector4",
   quaternion: "Quaternion",
   matrix4: "Matrix4",
+  // Authored-README shorthand for `vmath.matrix4`; absent from every engine
+  // ref-doc, which a core-types.test.ts guard keeps true as releases import.
+  matrix: "Matrix4",
   "vmath.vector3": "Vector3",
   "vmath.vector4": "Vector4",
   "vmath.matrix4": "Matrix4",

package/src/doc-comment.ts

@@ -107,6 +107,10 @@ export function examplesHtmlToMarkdown(html: string): string {
 
 export interface DocCommentParts {
   summary: string;
+  // Present exactly when the source carried a deprecation tag; `""` is the bare
+  // form and still renders, so this is tested against `undefined` rather than for
+  // truthiness the way the other optional parts are.
+  deprecated?: string;
   params?: { name: string; doc: string }[];
   returns?: string;
   example?: string;
@@ -122,8 +126,15 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   const params = (parts.params ?? []).filter((p) => p.doc.trim() !== "");
   const returns = parts.returns?.trim() ? parts.returns : "";
   const example = parts.example?.trim() ? parts.example : "";
-
-  if (summaryLines.length === 0 && params.length === 0 && returns === "" && example === "") {
+  const deprecated = parts.deprecated;
+
+  if (
+    summaryLines.length === 0 &&
+    params.length === 0 &&
+    returns === "" &&
+    example === "" &&
+    deprecated === undefined
+  ) {
     return [];
   }
 
@@ -132,11 +143,18 @@ export function renderDocComment(parts: DocCommentParts): string[] {
     lines.push(line === "" ? " *" : ` * ${line}`);
   }
 
-  const hasTags = params.length > 0 || returns !== "" || example !== "";
+  const hasTags = deprecated !== undefined || params.length > 0 || returns !== "" || example !== "";
   if (summaryLines.length > 0 && hasTags) {
     lines.push(" *");
   }
 
+  if (deprecated !== undefined) {
+    const [first, ...rest] = deprecated.split("\n");
+    lines.push(first === "" ? " * @deprecated" : ` * @deprecated ${first}`);
+    for (const line of rest) {
+      lines.push(line === "" ? " *" : ` * ${line}`);
+    }
+  }
   for (const param of params) {
     const [first, ...rest] = param.doc.split("\n");
     lines.push(` * @param ${param.name} - ${first}`);

package/src/editor-overloads.d.ts

@@ -0,0 +1,33 @@
+/** @noSelfInFile */
+
+import type { Opaque } from "./core-types";
+import type { EditorCommand, EditorCommandQuery } from "./editor";
+
+declare global {
+  namespace editor {
+    /**
+     * Create an editor command
+     *
+     * @param opts - A table with the following keys:`label string, message`required, user-visible command name, either a string or a localization message`locations string[]`required, a non-empty list of locations where the command is displayed in the editor, values are either `"Edit"`, `"View"`, `"Project"`, `"Debug"` (the editor menubar), `"Assets"` (the assets pane), or `"Outline"` (the outline pane)`query table`optional, a query that both controls the command availability and provides additional information to the command handler functions; a table with the following keys:`selection table`current selection, a table with the following keys:`type string`either `"resource"` (selected resource) or `"outline"` (selected outline node)`cardinality string`either `"one"` (will use first selected item) or `"many"` (will use all selected items)`argument table`the command argument`id string`optional, keyword identifier that may be used for assigning a shortcut to a command; should be a dot-separated identifier string, e.g. `"my-extension.do-stuff"``active function`optional function that additionally checks if a command is active in the current context; will receive opts table with values populated by the query; should be fast to execute since the editor might invoke it in response to UI interactions (on key typed, mouse clicked)`run function`optional function that is invoked when the user decides to execute the command; will receive opts table with values populated by the query
+     * @example
+     * ```ts
+     * // Print Git history for a file:
+     * // (`locations` is added here: upstream's own example omits it, but its
+     * // prose declares the key required.)
+     * editor.command({
+     *   label: "Git History",
+     *   locations: ["Assets"],
+     *   query: { selection: { type: "resource", cardinality: "one" } },
+     *   run: (opts) => {
+     *     editor.execute("git", "log", "--follow", `.${editor.get(opts.selection, "path")}`, {
+     *       reload_resources: false,
+     *     });
+     *   },
+     * });
+     * ```
+     */
+    function command<const Q extends EditorCommandQuery = Record<never, never>>(
+      opts: EditorCommand<Q>,
+    ): Opaque<"command">;
+  }
+}

package/src/editor-vm-globals.d.ts

@@ -0,0 +1,200 @@
+/** @noSelfInFile */
+
+import type {
+  HttpRouteHandler,
+  ZipEntries,
+  ZipPackOptions,
+  ZipUnpackOptions,
+} from "./editor-vm-types";
+
+// The editor VM surfaces the emit leaves behind, hand-authored and pinned to
+// their vendored fixtures by `test/editor-vm-globals-parity.test.ts`. Three
+// shapes land here: `pprint` is a bare global function with no namespace to hang
+// off; the two-segment VARIABLEs (`zip.METHOD.*`, `http.server.*`) are reachable
+// by the emitter's nested pass but deliberately withheld, because a VARIABLE
+// carries no type and would emit as `unknown` — useless to `ZipPackOptions`,
+// which types `method` as a string — while its brief is an unreliable literal
+// (upstream's own `zip.ON_CONFLICT.OVERWRITE` reads `"skip"`); and the functions
+// whose *vendored signature* cannot be rendered soundly — an optional parameter
+// sitting before a required one, or an empty `returnvalues` on a function
+// upstream's own prose says returns a value — are written out here as overload
+// sets. All three are withheld from the emit by `EDITOR_VM_SKIP_FUNCTIONS`. The
+// contract is unchanged and still derived: this file declares exactly what the
+// emit leaves behind. The namespaces below merge with the emitted
+// `generated/editor-vm/` bodies rather than replacing them. Upstream records no
+// type for a VARIABLE, so those annotations are read from each member's prose.
+
+declare global {
+  /**
+   * Pretty-print a Lua value
+   */
+  function pprint(value: unknown): void;
+
+  namespace http {
+    namespace server {
+      /**
+       * Editor's HTTP server local url
+       */
+      const local_url: string;
+      /**
+       * Editor's HTTP server port
+       */
+      const port: number;
+      /**
+       * Editor's HTTP server url
+       */
+      const url: string;
+      /**
+       * Create route definition for the editor's HTTP server
+       *
+       * `method`, `as` and `openapi` are optional but sit before the required
+       * `handler`, so each documented call shape is its own overload. An optional
+       * is supplied only when every earlier optional is: `method` and `as` are
+       * both strings, so a form that skipped `method` alone would be
+       * indistinguishable from one that supplied it.
+       *
+       * @param path - HTTP URI path, starts with `/`; may include path patterns (`{name}` for a single segment and `{*name}` for the rest of the request path) that will be extracted from the path and provided to the handler as a part of the request
+       * @param method - HTTP request method, default `"GET"`
+       * @param as - Request body converter, either `"string"` or `"json"`; the body will be discarded if not specified
+       * @param openapi - Optional OpenAPI Operation Object for this route method, exposed from `/openapi.json`
+       * @param handler - Request handler function, receives the request table and returns either a single response value, or 0 or more arguments to `http.server.response()`
+       * @returns HTTP server route
+       * @example
+       * ```ts
+       * // Receive JSON and respond with JSON:
+       * http.server.route("/json", "POST", "json", (request) => {
+       *   pprint(request);
+       *   return 200;
+       * });
+       *
+       * // Extract parts of the path:
+       * http.server.route("/users/{user}/orders", (request) => {
+       *   print((request as { user: string }).user);
+       * });
+       * ```
+       */
+      function route(path: string, handler: HttpRouteHandler): unknown;
+      function route(path: string, method: string, handler: HttpRouteHandler): unknown;
+      function route(path: string, method: string, as: string, handler: HttpRouteHandler): unknown;
+      function route(
+        path: string,
+        method: string,
+        as: string,
+        openapi: Record<string | number, unknown>,
+        handler: HttpRouteHandler,
+      ): unknown;
+    }
+  }
+
+  namespace json {
+    /**
+     * Decode JSON string to Lua value
+     *
+     * Upstream records no return value while its own brief names one, so the
+     * return is written here. `unknown` is the honest answer: `options.all`
+     * makes the result an array, and a JSON document may be a scalar.
+     *
+     * @param json - json data
+     * @param options - A table with the following keys:`all boolean`if `true`, decodes all json values in a string and returns an array
+     * @returns the decoded value
+     */
+    function decode(json: string, options?: Record<string | number, unknown>): unknown;
+    /**
+     * Encode Lua value to JSON string
+     *
+     * @param value - any Lua value that may be represented as JSON
+     * @returns the encoded document
+     */
+    function encode(value: unknown): string;
+  }
+
+  namespace zip {
+    namespace METHOD {
+      /**
+       * `"deflated"` compression method
+       */
+      const DEFLATED: string;
+      /**
+       * `"stored"` compression method, i.e. no compression
+       */
+      const STORED: string;
+    }
+    namespace ON_CONFLICT {
+      /**
+       * `"error"`, any conflict aborts extraction
+       */
+      const ERROR: string;
+      /**
+       * `"skip"`, existing file is preserved
+       */
+      const SKIP: string;
+      /**
+       * `"skip"`, existing file is overwritten
+       */
+      const OVERWRITE: string;
+    }
+    /**
+     * Create a ZIP archive
+     *
+     * `opts` is optional but sits before the required `entries`, so the two
+     * documented call shapes are separate overloads.
+     *
+     * @param output_path - output zip file path, resolved against project root if relative
+     * @param opts - compression options
+     * @param entries - entries to compress, either a relative path or a list of entries
+     * @example
+     * ```ts
+     * // Archive a file and a folder:
+     * zip.pack("build.zip", ["build", "game.project"]);
+     *
+     * // Change the location of the files within the archive:
+     * zip.pack("build.zip", [
+     *   ["build/wasm-web", "."],
+     *   ["configs/prod.json", "config.json"],
+     * ]);
+     *
+     * // Create archive without compression:
+     * zip.pack("build.zip", { method: zip.METHOD.STORED }, ["build", "resources"]);
+     *
+     * // Don't compress one of the folders:
+     * zip.pack("build.zip", [{ 1: "assets", method: zip.METHOD.STORED }, "build/wasm-web"]);
+     * ```
+     */
+    function pack(output_path: string, entries: ZipEntries): void;
+    function pack(output_path: string, opts: ZipPackOptions, entries: ZipEntries): void;
+    /**
+     * Extract a ZIP archive
+     *
+     * `target_path`, `opts` and `paths` are all optional and share the second
+     * slot, so the shape-discriminated forms come first: an all-optional
+     * `ZipUnpackOptions` cannot absorb a paths array, and vice versa.
+     *
+     * @param archive_path - zip file path, resolved against project root if relative
+     * @param target_path - target path for extraction, defaults to parent of `archive_path` if omitted
+     * @param opts - extraction options
+     * @param paths - entries to extract, relative string paths
+     * @example
+     * ```ts
+     * // Extract everything next to the archive:
+     * zip.unpack("build/dev/resources.zip");
+     *
+     * // Extract to a different directory:
+     * zip.unpack("build/dev/resources.zip", "build/dev/tmp");
+     *
+     * // Extract while overwriting existing files on conflict:
+     * zip.unpack("build/dev/resources.zip", { on_conflict: zip.ON_CONFLICT.OVERWRITE });
+     *
+     * // Extract a single file:
+     * zip.unpack("build/dev/resources.zip", ["config.json"]);
+     * ```
+     */
+    function unpack(archive_path: string, paths: readonly string[]): void;
+    function unpack(archive_path: string, opts: ZipUnpackOptions, paths?: readonly string[]): void;
+    function unpack(
+      archive_path: string,
+      target_path?: string,
+      opts?: ZipUnpackOptions,
+      paths?: readonly string[],
+    ): void;
+  }
+}

package/src/editor-vm-types.ts

@@ -0,0 +1,44 @@
+/** @noSelfInFile */
+
+// The named types the hand-authored editor VM overloads take. They live outside
+// `src/editor-vm-globals.d.ts` on purpose: the parity test compares that file's
+// declared set to the set the emit leaves behind, exactly, and a type alias
+// declared there would count as an extra declaration with no upstream member to
+// answer for it.
+
+/**
+ * One entry in a `zip.pack` archive: a source path, a `[source, target]` pair
+ * that relocates it inside the archive, or a table carrying per-entry
+ * compression options alongside those positions.
+ */
+export type ZipEntry = string | readonly string[] | Record<string | number, unknown>;
+
+/**
+ * What `zip.pack` compresses: a single relative path, or a list of entries.
+ */
+export type ZipEntries = string | readonly ZipEntry[];
+
+/**
+ * Archive-wide compression options for `zip.pack`.
+ */
+export interface ZipPackOptions {
+  /** Compression method, either `zip.METHOD.DEFLATED` (default) or `zip.METHOD.STORED`. */
+  readonly method?: string;
+  /** Compression level, 0 to 9; only useful with `zip.METHOD.DEFLATED`, defaults to 6. */
+  readonly level?: number;
+}
+
+/**
+ * Extraction options for `zip.unpack`. Every key is optional, which is what lets
+ * TypeScript tell this table apart from the paths list that shares its slot.
+ */
+export interface ZipUnpackOptions {
+  /** Conflict resolution strategy, defaults to `zip.ON_CONFLICT.ERROR`. */
+  readonly on_conflict?: string;
+}
+
+/**
+ * A `http.server.route` handler. Left at the looseness the emit gave it: typing
+ * the request table is a separate slice.
+ */
+export type HttpRouteHandler = (...args: unknown[]) => unknown;