@defold-typescript/types 0.24.0 → 0.26.0

package/scripts/regen.ts

@@ -1,8 +1,13 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
 import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
-import { emitDeclarations, emitSymbolSignatures, type SymbolSignature } from "../src/emit-dts";
+import {
+  defaultMapType,
+  emitDeclarations,
+  emitSymbolSignatures,
+  type SymbolSignature,
+} from "../src/emit-dts";
 import {
   applyMessageDeprecations,
   emitBuiltinMessages,
@@ -10,6 +15,7 @@ import {
 } from "../src/emit-messages";
 import type { TranslationStore } from "../src/example-store";
 import { wrapAsAmbientGlobal, wrapAsModule } from "../src/publish-dts";
+import type { UrlParameterTable } from "../src/url-parameters";
 import {
   type DocSourceProvenance,
   type DownloadRefDoc,
@@ -28,6 +34,16 @@ export interface ApiTargetModule {
   readonly skipFunctions?: readonly string[];
 }
 
+// An editor-VM document declared by a target. It carries two things a runtime
+// module never needs: its own `importsFrom` (the `editor-vm/` subdirectory sits
+// a level below the runtime surface, so the target's `coreTypesImport` does not
+// reach) and a named `mapType` selector, since the editor VM is the only surface
+// with handle tokens no runtime namespace uses.
+export interface ApiTargetEditorModule extends ApiTargetModule {
+  readonly importsFrom?: string;
+  readonly mapType?: string;
+}
+
 // A target sourced from a resolved ref-doc zip (resolved on demand, never
 // pre-baked) versus the committed-fixture default (`null`).
 export type ApiTargetSource = { readonly kind: "ref-doc"; readonly version: string } | null;
@@ -40,6 +56,11 @@ export interface ApiTarget {
   readonly coreTypesImport: string;
   readonly source?: ApiTargetSource;
   readonly modules: readonly ApiTargetModule[];
+  // The editor-scripting documents this target ships, or absent when it ships
+  // none. Absence is declared, never inferred from a missing file, so a fixture
+  // deleted by accident fails loudly instead of silently degrading a pinned
+  // project to the default target's editor surface.
+  readonly editorModules?: readonly ApiTargetEditorModule[];
   // Docs-only Lua stdlib pages (no generated `.d.ts`): vendored fixtures the
   // docs-site pages under the "Lua standard library" category. Never read by
   // regen/MODULE_MANIFEST; surfaced here so the registry stays type-honest.
@@ -49,7 +70,10 @@ export interface ApiTarget {
 const REGISTRY_PATH = resolve(import.meta.dir, "..", "api-targets.json");
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 
-export function loadApiTargets(registryPath: string = REGISTRY_PATH): ApiTarget[] {
+export function loadApiTargets(
+  registryPath: string = REGISTRY_PATH,
+  packageRoot: string = resolve(registryPath, ".."),
+): ApiTarget[] {
   const { targets } = JSON.parse(readFileSync(registryPath, "utf8")) as { targets: ApiTarget[] };
   const defaults = targets.filter((t) => t.default === true);
   if (defaults.length !== 1) {
@@ -57,6 +81,16 @@ export function loadApiTargets(registryPath: string = REGISTRY_PATH): ApiTarget[
       `api-targets.json: expected exactly one default target, found ${defaults.length}`,
     );
   }
+  for (const target of targets) {
+    for (const module of target.editorModules ?? []) {
+      const path = resolve(packageRoot, target.fixturesDir, module.fixture);
+      if (!existsSync(path)) {
+        throw new Error(
+          `api-targets.json: target "${target.id}" editor module "${module.namespace}" fixture not found: ${path}`,
+        );
+      }
+    }
+  }
   return targets;
 }
 
@@ -88,10 +122,18 @@ export interface ModuleManifestEntry {
   readonly namespace: string;
   readonly doc: unknown;
   readonly outFile: string;
+  // Each item drops one member of any element kind — a FUNCTION or a VARIABLE —
+  // by an exact stripped local (`get`), or — when it ends in `.` — a segment
+  // prefix dropping everything beneath it (`ui.`). The field keeps its historic
+  // name; its reach is not limited to functions.
   readonly skipFunctions?: readonly string[];
   readonly importsFrom?: string;
   readonly moduleId?: string;
   readonly sourceProvenance?: DocSourceProvenance;
+  // Overrides the shared token -> TS type mapping for this entry alone. Reserved
+  // for tokens no runtime namespace uses, so `DEFOLD_TYPE_MAP` keeps describing
+  // only the runtime surface.
+  readonly mapType?: (token: string) => string;
 }
 
 export interface ResolveTargetOptions {
@@ -157,6 +199,152 @@ const FIDELITY_BASELINE_TARGET = DEFAULT_TARGET;
 export const FIDELITY_BASELINE_MANIFEST: readonly ModuleManifestEntry[] =
   loadTargetModules(FIDELITY_BASELINE_TARGET);
 
+// Handle tokens the editor VM alone exposes. `transaction_step[` is what
+// upstream literally emits for `transaction_step[]` — the ref-doc's own type
+// string loses the closing bracket — so it is repaired here, per entry, rather
+// than in the parser: no runtime namespace carries it, and normalizing a
+// truncated bracket globally would silently reinterpret any future token of that
+// shape. The doc's other truncated token, `string[`, is deliberately left to map
+// to `unknown`: it covers both a plain path list and `create_resources`' mixed
+// path/[path, content] entries, so `string[]` would be wrong at one of its two
+// slots.
+const EDITOR_TYPE_MAP: Readonly<Record<string, string>> = {
+  // `editor.command` — the token's only consumer today — is skipped in favour of
+  // the hand-authored overload file, which returns the same `Opaque<"command">`.
+  // The entry stays so a future `command`-returning function maps identically.
+  command: 'Opaque<"command">',
+  // The handle every `editor.ui.*` builder returns and `editor.ui.show_dialog`
+  // consumes. Branding it keeps the whole component chain one nominal type
+  // rather than letting each end fall to the default `unknown` mapping.
+  component: 'Opaque<"component">',
+  transaction_step: 'Opaque<"transaction_step">',
+  "transaction_step[": 'Opaque<"transaction_step">[]',
+  // The handle every `localization` function returns: a userdata whose only
+  // documented use is being stringified or nested into another pattern.
+  message: 'Opaque<"message">',
+  // Repaired per entry for the same reason as `transaction_step[` above. Unlike
+  // `string[`, this token means one thing everywhere it appears — a list of
+  // values to render — so `unknown[]` is sound at all three of its slots.
+  "any[": "unknown[]",
+};
+
+function mapEditorType(token: string): string {
+  return EDITOR_TYPE_MAP[token] ?? defaultMapType(token);
+}
+
+// The named type maps an `editorModules` entry may select. A closed set, so an
+// unknown selector fails loudly instead of silently falling back to the runtime
+// token mapping and emitting `unknown` for every editor handle.
+const NAMED_TYPE_MAPS: Readonly<Record<string, (token: string) => string>> = {
+  editor: mapEditorType,
+};
+
+// The subdirectory the namespace-shaped libraries the editor VM exposes
+// alongside `editor` emit into, rather than beside the runtime modules, for a
+// hard reason: `tsconfig.json` includes the flat glob `generated/*.d.ts`, so an
+// editor `http.d.ts` there would share a program with the runtime one and
+// declare `namespace http` twice. A subdirectory keeps them out of that glob,
+// the same escape `generated/versions/` and `generated/kinds/` already use.
+// Because that boundary is forced, it also discriminates the two halves of a
+// target's declaration: the `editor` namespace a kind index names directly, and
+// the VM libraries it must import by explicit path.
+export const EDITOR_VM_SUBDIR = "editor-vm/";
+
+export function isEditorVmModule(module: { readonly outFile: string }): boolean {
+  return module.outFile.startsWith(EDITOR_VM_SUBDIR);
+}
+
+function oneLevelDeeper(importPath: string): string {
+  return importPath.startsWith("./") ? `../${importPath.slice(2)}` : `../${importPath}`;
+}
+
+// The editor-scripting surface a target declares. Vendored and emitted through
+// the same pipeline as MODULE_MANIFEST but deliberately separate from it:
+// MODULE_MANIFEST drives every runtime kind's universal imports, the per-version
+// targets and the published API artifacts, none of which describe the editor VM.
+// Reached only through the `editor-script` kind index.
+//
+// The `skipFunctions` rules a target declares in `api-targets.json` withhold
+// members for reasons the registry data alone cannot state. Rules are local
+// names — the `<namespace>.` prefix is stripped before matching — and they
+// withhold VARIABLEs as well as FUNCTIONs.
+//
+// On the `editor` entry, the editor VM's own `http`/`json`/`zip`/`zlib`/
+// `pprint`/`localization`/`tilemap.tiles` sit in that same upstream document
+// under their own top-level namespaces. They are emitted from their own
+// per-namespace fixtures instead, and skipped on `editor` so that entry cannot
+// misname them as `editor.*` — `pprint`, a flat identifier, would otherwise land
+// as `editor.pprint`. `command` is the one rule there that is not a dropped
+// namespace prefix: the hand-authored `src/editor-overloads.d.ts` supplies
+// `editor.command` with a generic signature that couples a command's opts bag to
+// its own query, which the emitter cannot express.
+//
+// On a VM entry, the withheld members are hand-authored in
+// `src/editor-vm-globals.d.ts` instead. The functions are ones whose vendored
+// signature the emitter cannot render soundly, both causes being the fixture's
+// positional model being a lossy description of the Lua function its own
+// `examples` block calls: an optional parameter sitting *before* a required one
+// (TypeScript cannot mark a middle parameter `?`, so the emit renders it
+// `T | undefined` and rejects every documented short form), and an empty
+// `returnvalues` on a function upstream's own prose says returns a value.
+//
+// The constant tables are expressible now that the nested pass reaches
+// variables, but a VARIABLE carries no `types`, so the emit would be `unknown` —
+// and `ZipPackOptions.method?: string` rejects that. Their brief is the literal
+// value, which looks like a string-literal type until you notice upstream's own
+// `zip.ON_CONFLICT.OVERWRITE` reads `"skip"`, so no type is derived from it.
+// The hand-authored declarations stay authoritative and these stay withheld.
+export function loadTargetEditorModules(
+  target: ApiTarget,
+  packageRoot: string = PACKAGE_ROOT,
+): ModuleManifestEntry[] {
+  return (target.editorModules ?? []).map((module) => {
+    const path = resolve(packageRoot, target.fixturesDir, module.fixture);
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch {
+      throw new Error(
+        `api-targets.json: target "${target.id}" editor module "${module.namespace}" fixture not found: ${path}`,
+      );
+    }
+    if (module.mapType !== undefined && NAMED_TYPE_MAPS[module.mapType] === undefined) {
+      throw new Error(
+        `api-targets.json: target "${target.id}" editor module "${module.namespace}": unknown mapType "${module.mapType}"`,
+      );
+    }
+    const entry: ModuleManifestEntry = {
+      namespace: module.namespace,
+      doc: JSON.parse(raw),
+      outFile: module.outFile,
+      // A VM module sits one directory below the rest of the surface, so it
+      // cannot ride the target's own `coreTypesImport` unchanged. Deriving the
+      // deeper form keeps a relocated surface (a materialized `.defold-types/`
+      // copy rewrites `coreTypesImport` to `./core-types`) resolving too.
+      importsFrom:
+        module.importsFrom ??
+        (isEditorVmModule(module)
+          ? oneLevelDeeper(target.coreTypesImport)
+          : target.coreTypesImport),
+      ...(module.skipFunctions ? { skipFunctions: module.skipFunctions } : {}),
+      ...(module.mapType ? { mapType: NAMED_TYPE_MAPS[module.mapType] } : {}),
+    };
+    return entry;
+  });
+}
+
+const DEFAULT_EDITOR_MODULES = loadTargetEditorModules(DEFAULT_TARGET);
+
+export const EDITOR_MODULE_MANIFEST: readonly ModuleManifestEntry[] = DEFAULT_EDITOR_MODULES.filter(
+  (entry) => !isEditorVmModule(entry),
+);
+
+export const EDITOR_VM_MODULE_MANIFEST: readonly ModuleManifestEntry[] =
+  DEFAULT_EDITOR_MODULES.filter(isEditorVmModule);
+
+export const EDITOR_SKIP_FUNCTIONS: readonly string[] =
+  EDITOR_MODULE_MANIFEST.find((entry) => entry.namespace === "editor")?.skipFunctions ?? [];
+
 export interface MessagesManifestEntry {
   readonly doc: unknown;
   readonly outFile: string;
@@ -194,15 +382,34 @@ export function collectConstantFqns(
   return fqns;
 }
 
+const URL_PARAMETERS_PATH = resolve(PACKAGE_ROOT, "url-parameters.json");
+
+// The committed classification table, read once. Both the `.d.ts` emit and the
+// authoritative-signature emit default to it, so the two surfaces cannot
+// disagree about which slots address the scene graph.
+export function loadUrlParameters(path: string = URL_PARAMETERS_PATH): UrlParameterTable {
+  return JSON.parse(readFileSync(path, "utf8")) as UrlParameterTable;
+}
+
+let urlParametersCache: UrlParameterTable | null = null;
+
+function committedUrlParameters(): UrlParameterTable {
+  urlParametersCache ??= loadUrlParameters();
+  return urlParametersCache;
+}
+
 export interface GenerateOptions {
   knownConstantFqns?: ReadonlySet<string>;
   translations?: TranslationStore;
+  urlParameters?: UrlParameterTable;
 }
 
 interface PreparedGeneratedModule {
   module: ApiModule;
   knownConstantFqns: ReadonlySet<string>;
   translations: TranslationStore;
+  urlParameters: UrlParameterTable;
+  mapType: ((token: string) => string) | undefined;
   dropped: string[];
 }
 
@@ -217,29 +424,42 @@ function prepareGeneratedModule(
   const module = parseDefoldApiDoc(entry.doc);
   const prefix = `${module.namespace}.`;
   const dropped: string[] = [];
-  const skip = new Set(entry.skipFunctions ?? []);
-  module.functions = module.functions.filter((fn) => {
-    const local = fn.name.startsWith(prefix) ? fn.name.slice(prefix.length) : fn.name;
-    if (skip.has(local)) {
-      dropped.push(fn.name);
-      return false;
-    }
+  const rules = entry.skipFunctions ?? [];
+  const exact = new Set(rules.filter((rule) => !rule.endsWith(".")));
+  const segments = rules.filter((rule) => rule.endsWith("."));
+  const withheld = (name: string): boolean => {
+    const local = name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    if (!exact.has(local) && !segments.some((segment) => local.startsWith(segment))) return false;
+    dropped.push(name);
     return true;
-  });
+  };
+  module.functions = module.functions.filter((fn) => !withheld(fn.name));
+  module.variables = module.variables.filter((v) => !withheld(v.name));
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
   const translations = options?.translations ?? loadTranslations();
-  return { module, knownConstantFqns, translations, dropped };
+  const urlParameters = options?.urlParameters ?? committedUrlParameters();
+  return {
+    module,
+    knownConstantFqns,
+    translations,
+    urlParameters,
+    mapType: entry.mapType,
+    dropped,
+  };
 }
 
 export function generateModuleDeclaration(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): GenerateResult {
-  const { module, knownConstantFqns, translations, dropped } = prepareGeneratedModule(
-    entry,
-    options,
-  );
-  const emitted = emitDeclarations(module, { knownConstantFqns, translations });
+  const { module, knownConstantFqns, translations, urlParameters, mapType, dropped } =
+    prepareGeneratedModule(entry, options);
+  const emitted = emitDeclarations(module, {
+    knownConstantFqns,
+    translations,
+    urlParameters,
+    ...(mapType ? { mapType } : {}),
+  });
   const importsFrom = entry.importsFrom ?? "../src/core-types";
   const contents = entry.moduleId
     ? wrapAsModule({ namespace: module.namespace, emitted, importsFrom, moduleId: entry.moduleId })
@@ -255,23 +475,50 @@ export function generateModuleSignatures(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): SymbolSignature[] {
-  const { module, knownConstantFqns } = prepareGeneratedModule(entry, options);
-  return emitSymbolSignatures(module, { knownConstantFqns });
+  const { module, knownConstantFqns, urlParameters, mapType } = prepareGeneratedModule(
+    entry,
+    options,
+  );
+  return emitSymbolSignatures(module, {
+    knownConstantFqns,
+    urlParameters,
+    ...(mapType ? { mapType } : {}),
+  });
 }
 
 export interface VersionedModuleManifestEntry extends ModuleManifestEntry {
   readonly versionId: string;
+  // Set on an entry derived from the target's `editorModules`. The editor
+  // surface rides the same per-version emit as the runtime modules but never the
+  // version's aggregate index — importing it there would drag the editor VM into
+  // every runtime program pinned to that version.
+  readonly editor?: boolean;
 }
 
 // Committed generation covers only filesystem-fixture targets (source == null).
 // ref-doc targets are resolved on the fly and never pre-baked, so they are
 // excluded from the committed regen loop and the byte-drift guards.
+export function versionedModuleManifest(
+  targets: readonly ApiTarget[],
+  packageRoot: string = PACKAGE_ROOT,
+): VersionedModuleManifestEntry[] {
+  return targets
+    .filter((target) => target.default !== true && (target.source ?? null) == null)
+    .flatMap((target) => [
+      ...loadTargetModules(target, packageRoot).map((entry) => ({
+        ...entry,
+        versionId: target.id,
+      })),
+      ...loadTargetEditorModules(target, packageRoot).map((entry) => ({
+        ...entry,
+        versionId: target.id,
+        editor: true,
+      })),
+    ]);
+}
+
 export const VERSIONED_MODULE_MANIFEST: readonly VersionedModuleManifestEntry[] =
-  API_TARGETS.filter(
-    (target) => target.default !== true && (target.source ?? null) == null,
-  ).flatMap((target) =>
-    loadTargetModules(target).map((entry) => ({ ...entry, versionId: target.id })),
-  );
+  versionedModuleManifest(API_TARGETS);
 
 export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
   gui: "gui_script",
@@ -280,9 +527,18 @@ export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
 
 // The Lua standard library rides every per-kind subpath the same as the full
 // entrypoint. Triple-slash directives must precede the first statement, so they
-// lead the generated kind index.
-export const LUA_STDLIB_REFERENCES =
-  '/// <reference types="lua-types/5.1" />\n/// <reference types="lua-types/special/jit-only" />\n';
+// lead the generated kind index. The two lines select independently: the game
+// runtime is LuaJIT, but the editor VM is plain Lua 5.1 and has no `bit`.
+const LUA_51_REFERENCE = '/// <reference types="lua-types/5.1" />\n';
+const LUA_JIT_ONLY_REFERENCE = '/// <reference types="lua-types/special/jit-only" />\n';
+export const LUA_STDLIB_REFERENCES = `${LUA_51_REFERENCE}${LUA_JIT_ONLY_REFERENCE}`;
+
+// The stdlib references a kind's own VM earns. Shared with the materialized
+// renderer so a surface generated on the fly makes the same LuaJIT call the
+// committed emit does.
+export function kindStdlibReferences(entry: KindManifestEntry): string {
+  return `${LUA_51_REFERENCE}${entry.jit === false ? "" : LUA_JIT_ONLY_REFERENCE}`;
+}
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
   "../builtin-messages",
@@ -290,33 +546,109 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
   "../../src/msg-overloads",
   "../../src/message-guard",
   "../../src/window-event-guard",
+  "../../src/scene-addresses",
   "../../src/go-overloads",
   "../../src/vmath-overloads",
 ];
 
+const DEFAULT_FACTORY_MODULE = "../../src/lifecycle";
+
 export interface KindManifestEntry {
   readonly kind: string;
   readonly restricted?: string;
   readonly factory: string;
+  // Replaces the universal import set with exactly these generated modules. A
+  // kind that names one is disjoint from the runtime surface, not a narrowing
+  // of it, so it takes none of the universal extras either.
+  readonly only?: readonly string[];
+  // Hand-authored ambient modules the kind imports on top of `only`. A kind
+  // naming `only` takes none of `UNIVERSAL_EXTRA_IMPORTS`, so it cannot ride
+  // that set to reach an overload file.
+  readonly extraModules?: readonly string[];
+  // Extra value exports the factory module contributes to the kind subpath.
+  readonly extraExports?: readonly string[];
+  // Extra type-only exports the factory module contributes to the kind subpath.
+  readonly extraTypeExports?: readonly string[];
+  // Where the factory (and, when emitted, the script-property helper types) is
+  // re-exported from. Defaults to the runtime lifecycle module.
+  readonly factoryFrom?: string;
+  // Whether the kind has script properties at all. Editor scripts do not.
+  readonly propertyTypes?: boolean;
+  // Whether the kind's VM is LuaJIT. The editor runs plain Lua 5.1.
+  readonly jit?: boolean;
 }
 
 export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
   { kind: "script", factory: "defineScript" },
   { kind: "gui-script", restricted: "gui", factory: "defineGuiScript" },
   { kind: "render-script", restricted: "render", factory: "defineRenderScript" },
+  {
+    kind: "editor-script",
+    // Empty on purpose: the emitted namespaces come from the declaring target's
+    // `editorModules` (see `editorKindModules`), and the empty array is what
+    // marks the kind as disjoint from the runtime surface rather than a
+    // narrowing of it.
+    only: [],
+    extraModules: ["../../src/editor-overloads", "../../src/editor-vm-globals"],
+    factory: "defineEditorScript",
+    extraExports: ["defineEditorCommand"],
+    extraTypeExports: ["EditorCommandQuery", "EditorNode"],
+    factoryFrom: "../../src/editor",
+    propertyTypes: false,
+    jit: false,
+  },
 ];
 
-export function generateKindIndex(kind: string): string {
+// The kinds every materialized *versioned* surface carries, whatever the target.
+// An `only` kind is built from the target's own `editorModules`, so it has a
+// versioned form only for a target that declares an editor document — see
+// `targetKindManifest`, which is what a per-target emit resolves through.
+export const RUNTIME_KIND_MANIFEST: readonly KindManifestEntry[] = KIND_MODULE_MANIFEST.filter(
+  (entry) => entry.only === undefined,
+);
+
+// The emitted modules an editor kind index imports, read from the declaring
+// target rather than from a list beside the kind entry, so a pinned surface
+// names its own editor document instead of the default target's. The plain
+// namespace leads and the VM libraries follow by explicit path — `only` holds
+// namespaces and would build `../http` (the runtime module) and
+// `../tilemap.tiles` (not a path) for those.
+function editorKindModules(target: ApiTarget): string[] {
+  const declared = target.editorModules ?? [];
+  if (declared.length === 0) {
+    throw new Error(`api-targets.json: target "${target.id}" declares no editor document`);
+  }
+  return [
+    ...declared.filter((m) => !isEditorVmModule(m)),
+    ...declared.filter(isEditorVmModule),
+  ].map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
+}
+
+export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARGET): string {
   const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === kind);
   if (!entry) throw new Error(`unknown script kind: ${kind}`);
+  const srcPrefix = targetSrcPrefix(target);
   const universalNamespaces = MODULE_MANIFEST.filter(
     (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
   ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
-  const lines = [
-    ...new Set([...universalNamespaces.sort(), ...[...UNIVERSAL_EXTRA_IMPORTS].sort()]),
-  ].map((path) => `import "${path}";`);
+  const modules = (
+    entry.only === undefined
+      ? [...new Set([...universalNamespaces.sort(), ...[...UNIVERSAL_EXTRA_IMPORTS].sort()])]
+      : [...editorKindModules(target), ...(entry.extraModules ?? [])]
+  ).map((path) => retargetSrcPath(path, srcPrefix));
+  const lines = modules.map((path) => `import "${path}";`);
   if (entry.restricted) lines.push(`import "../${entry.restricted}";`);
-  return `${LUA_STDLIB_REFERENCES}${lines.join("\n")}\n\nexport { ${entry.factory} } from "../../src/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "../../src/lifecycle";\n`;
+  const references = kindStdlibReferences(entry);
+  const from = retargetSrcPath(entry.factoryFrom ?? DEFAULT_FACTORY_MODULE, srcPrefix);
+  const values = [entry.factory, ...(entry.extraExports ?? [])].join(", ");
+  const typeExports = entry.extraTypeExports?.length
+    ? `\nexport type { ${entry.extraTypeExports.join(", ")} } from "${from}";`
+    : "";
+  const properties =
+    entry.propertyTypes === false
+      ? ""
+      : `\nexport type { ScriptProperties, ScriptProperty } from "${from}";`;
+  return `${references}${lines.join("\n")}\n\nexport { ${values} } from "${from}";${typeExports}${properties}\n`;
 }
 
 export function generateVersionIndex(
@@ -324,7 +656,7 @@ export function generateVersionIndex(
   manifest: readonly VersionedModuleManifestEntry[] = VERSIONED_MODULE_MANIFEST,
 ): string {
   const imports = manifest
-    .filter((entry) => entry.versionId === versionId)
+    .filter((entry) => entry.versionId === versionId && entry.editor !== true)
     .map((entry) => entry.outFile.replace(/\.d\.ts$/, ""))
     .sort()
     .map((module) => `import "./${module}";`)
@@ -332,9 +664,40 @@ export function generateVersionIndex(
   return `${imports}\n\nexport {};\n`;
 }
 
+// The `src/`-relative prefix a kind index living in `<generatedDir>/kinds/` needs
+// to reach the package's hand-authored modules. The target's own
+// `coreTypesImport` already measures its generated dir's depth; the kind index
+// sits one level below it.
+function targetSrcPrefix(target: ApiTarget): string {
+  return `../${target.coreTypesImport.slice(0, -"core-types".length)}`;
+}
+
+const DEFAULT_SRC_PREFIX = "../../src/";
+
+function retargetSrcPath(modulePath: string, srcPrefix: string): string {
+  return modulePath.startsWith(DEFAULT_SRC_PREFIX)
+    ? `${srcPrefix}${modulePath.slice(DEFAULT_SRC_PREFIX.length)}`
+    : modulePath;
+}
+
+// The kinds a materialized surface for `target` can carry: the runtime trio
+// always, plus the editor kind when — and only when — the target declares an
+// editor document of its own.
+export function targetKindManifest(target: ApiTarget): readonly KindManifestEntry[] {
+  if ((target.editorModules?.length ?? 0) === 0) {
+    return RUNTIME_KIND_MANIFEST;
+  }
+  return [...RUNTIME_KIND_MANIFEST, ...KIND_MODULE_MANIFEST.filter((e) => e.only !== undefined)];
+}
+
 if (import.meta.main) {
   const generated = resolve(import.meta.dir, "..", "generated");
-  for (const entry of MODULE_MANIFEST) {
+  mkdirSync(resolve(generated, "editor-vm"), { recursive: true });
+  for (const entry of [
+    ...MODULE_MANIFEST,
+    ...EDITOR_MODULE_MANIFEST,
+    ...EDITOR_VM_MODULE_MANIFEST,
+  ]) {
     const { contents, dropped } = generateModuleDeclaration(entry);
     if (dropped.length > 0) {
       console.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
@@ -347,7 +710,17 @@ if (import.meta.main) {
   writeFileSync(messagesOut, generateBuiltinMessagesDeclaration(MESSAGES_MANIFEST));
   console.log(`wrote ${messagesOut}`);
 
-  const versionIds = new Set(VERSIONED_MODULE_MANIFEST.map((entry) => entry.versionId));
+  // The target's own `generatedDir` is where a version lands, so a declaring
+  // target's editor surface (and its `editor-vm/` subdirectory) rides the same
+  // destination rule as its runtime modules rather than a second convention.
+  const versionedTargets = API_TARGETS.filter(
+    (target) => target.default !== true && (target.source ?? null) == null,
+  );
+  const versionDirOf = (versionId: string): string => {
+    const target = versionedTargets.find((t) => t.id === versionId);
+    if (!target) throw new Error(`no committed target for version ${versionId}`);
+    return resolve(PACKAGE_ROOT, target.generatedDir);
+  };
   for (const entry of VERSIONED_MODULE_MANIFEST) {
     const { contents, dropped } = generateModuleDeclaration(entry);
     if (dropped.length > 0) {
@@ -355,16 +728,26 @@ if (import.meta.main) {
         `note: dropped skipped member(s) from ${entry.versionId}/${entry.namespace}: ${dropped.join(", ")}`,
       );
     }
-    const versionDir = resolve(generated, "versions", entry.versionId);
-    mkdirSync(versionDir, { recursive: true });
-    const out = resolve(versionDir, entry.outFile);
+    const out = resolve(versionDirOf(entry.versionId), entry.outFile);
+    mkdirSync(dirname(out), { recursive: true });
     writeFileSync(out, contents);
     console.log(`wrote ${out}`);
   }
-  for (const versionId of versionIds) {
-    const indexOut = resolve(generated, "versions", versionId, "index.d.ts");
-    writeFileSync(indexOut, generateVersionIndex(versionId));
+  for (const target of versionedTargets) {
+    const indexOut = resolve(versionDirOf(target.id), "index.d.ts");
+    mkdirSync(dirname(indexOut), { recursive: true });
+    writeFileSync(indexOut, generateVersionIndex(target.id));
     console.log(`wrote ${indexOut}`);
+
+    const editorKinds = targetKindManifest(target).filter((entry) => entry.only !== undefined);
+    if (editorKinds.length === 0) continue;
+    const versionKindsDir = resolve(versionDirOf(target.id), "kinds");
+    mkdirSync(versionKindsDir, { recursive: true });
+    for (const entry of editorKinds) {
+      const out = resolve(versionKindsDir, `${entry.kind}.d.ts`);
+      writeFileSync(out, generateKindIndex(entry.kind, target));
+      console.log(`wrote ${out}`);
+    }
   }
 
   const kindsDir = resolve(generated, "kinds");