@defold-typescript/types 0.24.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/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;

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;

package/src/editor.ts

@@ -3,36 +3,137 @@
 // makes them a fourth, disjoint script kind — lowered to a chunk-level
 // `return <hooks table>` rather than the runtime kinds' flat top-level globals.
 //
-// This is the keystone surface only. The full typed `editor.*` global
-// (`get`/`transact`/`command` + the editor-VM `http`/`json`/`zip`) and the
-// per-kind API walls are a later slice, so a command's `run`/`active` receive a
-// loosely-typed opts bag for now.
+// The typed `editor.*` global (`get`/`transact`/`command`) and the walled
+// `@defold-typescript/types/editor-script` entrypoint ship alongside this file,
+// as do the editor VM's own `http`/`json`/`zip`/`zlib`/`tilemap.tiles`
+// libraries and the `editor.ui.*`, `editor.prefs.*`, and `localization.*`
+// surfaces.
+
+import type { Opaque } from "./core-types";
+
+/**
+ * What the editor addresses a node by: either a resource path (e.g.
+ * `"/main/game.script"`) or an internal node id the editor hands to the script.
+ * This is the argument `editor.get` and the `editor.tx.*` builders take.
+ */
+export type EditorNode = string | Opaque<"userdata">;
+
+/**
+ * Declares a command's context: what the editor resolves before calling the
+ * command's hooks, and therefore which members its opts bag carries. Both keys
+ * are optional; a command that declares neither receives an empty bag.
+ */
+export interface EditorCommandQuery {
+  /**
+   * The current selection. `type` picks the selection source, `cardinality`
+   * picks between the first selected item and all of them.
+   */
+  selection?: { type: "resource" | "outline"; cardinality: "one" | "many" };
+  /** Requests the command argument. Declared as an empty table. */
+  argument?: Record<string, never>;
+}
+
+/**
+ * The opts bag the editor populates for a command whose query is `Q` — exactly
+ * the members `Q` declared, and no others.
+ *
+ * Each half branches on *key presence* (`"selection" extends keyof Q`) rather
+ * than on the property type: an optional property is still in `keyof`, so
+ * presence is what separates a declared query from the erased one. The
+ * cardinality test is wrapped in a one-tuple so a union (or `never`) does not
+ * distribute across the conditional.
+ */
+export type EditorCommandOpts<Q extends EditorCommandQuery> = ("selection" extends keyof Q
+  ? {
+      selection: [NonNullable<Q["selection"]>["cardinality"]] extends ["many"]
+        ? EditorNode[]
+        : EditorNode;
+    }
+  : Record<never, never>) &
+  ("argument" extends keyof Q ? { argument: Record<string, unknown> } : Record<never, never>);
 
 /**
  * A single command an editor script contributes: a label, the editor UI
  * locations it appears in (e.g. `"Edit"`, `"Assets"`, `"Outline"`, `"View"`),
- * and optional `active`/`run` hooks the editor calls with a command-context bag.
+ * and optional `active`/`run` hooks the editor calls with the context bag its
+ * own `query` declared.
+ *
+ * The editor calls `active`/`run` as plain functions, so they must emit no
+ * leading self parameter. `@noSelf` has to sit here, on the enclosing
+ * interface: TSTL resolves a hook's self context from its contextual signature,
+ * and the property-signature branch consults only this interface — it returns
+ * before `noImplicitSelf` or a file-level `@noSelfInFile` is ever considered.
+ *
+ * @noSelf
  */
-export interface EditorCommand {
+export interface EditorCommand<Q extends EditorCommandQuery = EditorCommandQuery> {
   /** Menu/label text shown for the command. */
   label: string;
   /** Editor UI locations the command is offered in. */
   locations: string[];
   /**
    * Declares the command's context arguments; the editor passes the resolved
-   * values to `active`/`run`. Loosely typed until the `editor.*` slice lands.
+   * values to `active`/`run` as exactly the matching opts members.
    */
-  query?: Record<string, unknown>;
+  query?: Q;
   /**
    * Called to decide whether the command is currently enabled. Omit to always
-   * enable. The opts bag is loosely typed until the `editor.*` slice lands.
-   */
-  active?: (opts: Record<string, unknown>) => boolean;
-  /**
-   * Called when the command is invoked. The opts bag is loosely typed until the
-   * `editor.*` slice lands.
+   * enable. Should be fast — the editor may call it on key/mouse events.
    */
-  run?: (opts: Record<string, unknown>) => void;
+  active?: (opts: EditorCommandOpts<Q>) => boolean;
+  /** Called when the user invokes the command. */
+  run?: (opts: EditorCommandOpts<Q>) => void;
+}
+
+/**
+ * A command as it sits in a `get_commands` list: the same shape with its query
+ * erased. The hooks take `never`, the one parameter type every concrete opts
+ * bag is assignable *from* under parameter contravariance — so a `"one"` and a
+ * `"many"` command coexist in a single array while each keeps its own precise
+ * typing at its `defineEditorCommand` call site.
+ */
+export interface EditorCommandEntry {
+  /** Menu/label text shown for the command. */
+  label: string;
+  /** Editor UI locations the command is offered in. */
+  locations: string[];
+  /** Declares the command's context arguments. */
+  query?: EditorCommandQuery;
+  /** Called to decide whether the command is currently enabled. */
+  active?: (opts: never) => boolean;
+  /** Called when the user invokes the command. */
+  run?: (opts: never) => void;
+}
+
+/**
+ * Type a single editor command so its `active`/`run` hooks receive exactly the
+ * opts members its own `query` declared. At runtime this is an identity
+ * function — it returns `command` unchanged; its only job is typing, and the
+ * transpiler emits the table literal it wraps.
+ *
+ * @param command - the command to type and return.
+ * @returns the same `command`, typed as a query-erased list entry.
+ * @example
+ * ```ts
+ * export default defineEditorScript({
+ *   get_commands: () => [
+ *     defineEditorCommand({
+ *       label: "Git History",
+ *       locations: ["Assets"],
+ *       query: { selection: { type: "resource", cardinality: "one" } },
+ *       run: (opts) => print(editor.get(opts.selection, "path")),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+// The `Record<never, never>` default (not `Record<string, never>`, whose `keyof`
+// is `string` and would match every presence test) gives a command that declares
+// no query an empty opts bag.
+export function defineEditorCommand<const Q extends EditorCommandQuery = Record<never, never>>(
+  command: EditorCommand<Q>,
+): EditorCommandEntry {
+  return command as EditorCommandEntry;
 }
 
 /**
@@ -41,7 +142,7 @@ export interface EditorCommand {
  */
 export interface EditorScriptModule {
   /** Returns the commands this script contributes to the editor. */
-  get_commands?: () => EditorCommand[];
+  get_commands?: () => EditorCommandEntry[];
   /** Returns language-server descriptors this script contributes. */
   get_language_servers?: () => unknown[];
 }