@defold-typescript/types 0.24.0 → 0.26.0

package/src/emit-dts.ts

@@ -16,6 +16,7 @@ import {
 } from "./doc-comment";
 import type { TranslationStore } from "./example-store";
 import { hashExampleSource, lookupTranslation } from "./example-store";
+import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
 export interface EmitOptions {
   mapType?: (defoldType: string) => string;
@@ -30,6 +31,12 @@ export interface EmitOptions {
   // `examples/translations.json`. Loading lives in `scripts/example-store-io.ts`
   // so this module stays node-free for downstream consumers.
   translations?: TranslationStore;
+  // Which parameters address the scene graph, so their `string` member emits a
+  // scene-derived address alias instead. Defaults to an empty table — every
+  // slot classifies `none` and the output is byte-identical to an un-retyped
+  // emit. `regen` supplies the committed `url-parameters.json`; the table
+  // arrives as data so this module stays free of `node:fs` (bug-88).
+  urlParameters?: UrlParameterTable;
 }
 
 export const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -81,6 +88,7 @@ export const TS_RESERVED_NAMES = new Set([
   "with",
   "debugger",
   "extends",
+  "enum",
 ]);
 
 // A parameter name that clears `TS_IDENTIFIER` but is a TS reserved word (e.g.
@@ -149,6 +157,12 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   // is opaque to the field-list parser and the whole-slot `Record` is faithful.
   "render.render_target",
   "render.set_render_target",
+  // reserved-but-undocumented options bag: `collectionproxy.load`'s `options`
+  // slot is documented verbatim as "options table, currently unused" and accepts
+  // `nil`, so upstream defines no field list to emit. The whole-slot `Record` is
+  // faithful to what is documented today. If a later release fills the bag in,
+  // drop this entry so the missing fields resurface under `recordTables`.
+  "collectionproxy.load",
 ]);
 
 // Per-slot companion to ARBITRARY_TABLE_SLOTS (`element:kind:name`), for a
@@ -218,7 +232,13 @@ export const MAPPING_TABLE_SLOTS: ReadonlyMap<string, { key: string; value: stri
 // honest, ts-defold-matching shape. Per-FQN, not a blanket "empty returnvalues
 // -> unknown" rule: `gui.set` also has empty returnvalues and `void` is correct
 // there.
-export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([["gui.get", "unknown"]]);
+export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
+  ["gui.get", "unknown"],
+  // Upstream documents the returned transaction step in prose only — its
+  // `returnvalues` is empty while every sibling `editor.tx.*` builder declares
+  // one, and `editor.transact()` takes exactly that.
+  ["editor.tx.add", 'Opaque<"transaction_step">'],
+]);
 
 // FQN-keyed allowlist of the `types.is_*` checks that genuinely narrow their
 // argument, mapped to the `DEFOLD_TYPE_MAP` token whose interface they prove.
@@ -1426,6 +1446,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   const constantFqns = new Set(module.constants.map((c) => c.name));
   const knownConstantFqns = options?.knownConstantFqns;
   const translations = options?.translations ?? {};
+  const urlParameters = options?.urlParameters ?? [];
   const baseMapType = options?.mapType ?? defaultMapType;
   const mapType = (token: string): string =>
     constantFqns.has(token) || knownConstantFqns?.has(token)
@@ -1451,32 +1472,14 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
         : a.name.localeCompare(b.name),
     );
 
-  // One-level nested functions (`socket.dns.toip`) fail the flat-identifier test
-  // in `prepareFunction` above (the stripped `dns.toip` has a dot), so they are
-  // absent from `functions`. Re-collect them grouped by their single leading
-  // segment, re-stripping against `<namespace>.<segment>.` so the emitted
-  // identifier is the final segment. Only exactly-one-dot, both-sides-identifier
-  // locals qualify; deeper nesting and non-identifier segments stay dropped.
-  const nestedFunctionLocal = /^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/;
-  const nestedGroups = new Map<string, PreparedFunction[]>();
-  for (const fn of module.functions) {
-    const local = stripPrefix(fn.name, prefix);
-    if (!nestedFunctionLocal.test(local)) continue;
-    const segment = local.slice(0, local.indexOf("."));
-    const prepared = prepareFunction(fn, `${module.namespace}.${segment}.`);
-    if (prepared === null) continue;
-    const group = nestedGroups.get(segment) ?? [];
-    group.push(prepared);
-    nestedGroups.set(segment, group);
-  }
-  for (const group of nestedGroups.values()) {
-    group.sort((a, b) =>
-      a.name === b.name
-        ? a.original.parameters.length - b.original.parameters.length
-        : a.name.localeCompare(b.name),
-    );
-  }
-  const nestedSegments = [...nestedGroups.keys()].sort((a, b) => a.localeCompare(b));
+  // Nested members (`socket.dns.toip`, `editor.ui.COLOR.TEXT`) fail the
+  // flat-identifier test in `prepareVariable`/`prepareFunction` above (the
+  // stripped local has a dot), so they are absent from `variables`/`functions`.
+  // Re-collect them into a tree keyed by their full leading path, re-stripping
+  // against `<namespace>.<path>.` so the emitted identifier is the final
+  // segment. One or two leading identifier segments qualify; anything deeper,
+  // and any non-identifier segment, stays dropped.
+  const nestedRoot = collectNestedGroups(module, prefix);
 
   // Colon methods (`client:send`) are FUNCTION elements named `<receiver>:<method>`
   // and are NOT namespace-prefixed, so they fail the flat-identifier test in
@@ -1525,7 +1528,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
       for (const docLine of functionDocLines(fn.original, translations, handleIndent)) {
         lines.push(docLine);
       }
-      lines.push(`${handleIndent}${emitMethod(fn, mapType, resolver)}`);
+      lines.push(`${handleIndent}${emitMethod(fn, mapType, resolver, urlParameters)}`);
     }
     lines.push(`${INDENT}}`);
   }
@@ -1554,7 +1557,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     const reserved = TS_RESERVED_NAMES.has(fn.name);
     const emitName = aliasName(fn.name, aliases);
     for (const docLine of functionDocLines(fn.original, translations)) lines.push(docLine);
-    const line = emitFunction(fn, emitName, mapType, resolver);
+    const line = emitFunction(fn, emitName, mapType, resolver, urlParameters);
     lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
   }
 
@@ -1562,31 +1565,57 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     lines.push(`${INDENT}export { ${alias.internal} as ${alias.public} };`);
   }
 
-  const nestedIndent = `${INDENT}${INDENT}`;
-  for (const segment of nestedSegments) {
-    const group = nestedGroups.get(segment) ?? [];
-    // A reserved-name function inside a nested namespace gets the same recovery as
-    // a top-level one: emitted un-exported as `_<name>` and re-exported under the
-    // reserved name. The alias switches this namespace out of implicit-export mode,
-    // so its siblings then need an explicit `export` to stay reachable.
-    const segmentAliases: { internal: string; public: string }[] = [];
-    const segmentDecl = group.some((fn) => TS_RESERVED_NAMES.has(fn.name)) ? "export " : "";
-    lines.push(`${INDENT}${decl}namespace ${segment} {`);
-    for (const fn of group) {
-      const reserved = TS_RESERVED_NAMES.has(fn.name);
-      const emitName = aliasName(fn.name, segmentAliases);
-      for (const docLine of functionDocLines(fn.original, translations, nestedIndent)) {
-        lines.push(docLine);
+  const emitNestedLevel = (
+    level: ReadonlyMap<string, NestedGroup>,
+    indent: string,
+    outerDecl: string,
+  ): void => {
+    for (const segment of [...level.keys()].sort((a, b) => a.localeCompare(b))) {
+      const group = level.get(segment) as NestedGroup;
+      const bodyIndent = `${indent}${INDENT}`;
+      // A reserved-name member inside a nested namespace gets the same recovery as
+      // a top-level one: emitted un-exported as `_<name>` and re-exported under the
+      // reserved name. The alias switches this namespace out of implicit-export mode,
+      // so its siblings then need an explicit `export` to stay reachable.
+      const segmentAliases: { internal: string; public: string }[] = [];
+      const segmentDecl =
+        group.variables.some((v) => TS_RESERVED_NAMES.has(v.name)) ||
+        group.functions.some((fn) => TS_RESERVED_NAMES.has(fn.name))
+          ? "export "
+          : "";
+      lines.push(`${indent}${outerDecl}namespace ${segment} {`);
+      for (const v of group.variables) {
+        const reserved = TS_RESERVED_NAMES.has(v.name);
+        const emitName = aliasName(v.name, segmentAliases);
+        for (const docLine of summaryDocLines(
+          v.original.brief,
+          v.original.description,
+          bodyIndent,
+        )) {
+          lines.push(docLine);
+        }
+        lines.push(
+          `${bodyIndent}${reserved ? "" : segmentDecl}${emitVariable(v, emitName, mapType)}`,
+        );
       }
-      lines.push(
-        `${nestedIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver)}`,
-      );
-    }
-    for (const alias of [...segmentAliases].sort((a, b) => a.public.localeCompare(b.public))) {
-      lines.push(`${nestedIndent}export { ${alias.internal} as ${alias.public} };`);
+      for (const fn of group.functions) {
+        const reserved = TS_RESERVED_NAMES.has(fn.name);
+        const emitName = aliasName(fn.name, segmentAliases);
+        for (const docLine of functionDocLines(fn.original, translations, bodyIndent)) {
+          lines.push(docLine);
+        }
+        lines.push(
+          `${bodyIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver, urlParameters)}`,
+        );
+      }
+      for (const alias of [...segmentAliases].sort((a, b) => a.public.localeCompare(b.public))) {
+        lines.push(`${bodyIndent}export { ${alias.internal} as ${alias.public} };`);
+      }
+      emitNestedLevel(group.children, bodyIndent, segmentDecl);
+      lines.push(`${indent}}`);
     }
-    lines.push(`${INDENT}}`);
-  }
+  };
+  emitNestedLevel(nestedRoot, INDENT, decl);
 
   if (module.properties.length > 0) {
     const members = [...module.properties].sort((a, b) => a.name.localeCompare(b.name));
@@ -1616,13 +1645,17 @@ export interface SymbolSignature {
  * availability matrix joins on. This is the single declaration-backed source for
  * the shared `api-signatures.json` artifact: the same `mapType` (constant
  * branding) and table-doc resolver produce text that appears verbatim in the
- * committed `.d.ts`. The caller applies the same `skipFunctions` filter the
- * `.d.ts` generation does, so a dropped member never yields a signature.
+ * committed `.d.ts`, and nested members come from the same
+ * {@link collectNestedGroups} tree the declaration emitter walks, so neither
+ * surface can decide on its own which members are nested or how deep they go.
+ * The caller applies the same `skipFunctions` filter the `.d.ts` generation
+ * does, so a dropped member never yields a signature.
  */
 export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions): SymbolSignature[] {
   const prefix = `${module.namespace}.`;
   const constantFqns = new Set(module.constants.map((c) => c.name));
   const knownConstantFqns = options?.knownConstantFqns;
+  const urlParameters = options?.urlParameters ?? [];
   const baseMapType = options?.mapType ?? defaultMapType;
   const mapType = (token: string): string =>
     constantFqns.has(token) || knownConstantFqns?.has(token)
@@ -1649,20 +1682,32 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     if (prepared === null) continue;
     out.push({
       identity: fnIdentity(fn),
-      tsSignature: emitFunction(prepared, emitName(prepared.name), mapType, resolver),
+      tsSignature: emitFunction(
+        prepared,
+        emitName(prepared.name),
+        mapType,
+        resolver,
+        urlParameters,
+      ),
     });
   }
 
-  const nestedFunctionLocal = /^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/;
-  for (const fn of module.functions) {
-    const local = stripPrefix(fn.name, prefix);
-    if (!nestedFunctionLocal.test(local)) continue;
-    const segment = local.slice(0, local.indexOf("."));
-    const prepared = prepareFunction(fn, `${module.namespace}.${segment}.`);
-    if (prepared === null) continue;
+  const nested = flattenNestedGroups(collectNestedGroups(module, prefix));
+  for (const v of nested.variables) {
     out.push({
-      identity: fnIdentity(fn),
-      tsSignature: emitFunction(prepared, prepared.name, mapType, resolver),
+      identity: {
+        namespace: module.namespace,
+        kind: "VARIABLE",
+        name: v.original.name,
+        signature: "",
+      },
+      tsSignature: emitVariable(v, emitName(v.name), mapType),
+    });
+  }
+  for (const fn of nested.functions) {
+    out.push({
+      identity: fnIdentity(fn.original),
+      tsSignature: emitFunction(fn, emitName(fn.name), mapType, resolver, urlParameters),
     });
   }
 
@@ -1671,7 +1716,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
     for (const prepared of group) {
       out.push({
         identity: fnIdentity(prepared.original),
-        tsSignature: emitMethod(prepared, mapType, resolver),
+        tsSignature: emitMethod(prepared, mapType, resolver, urlParameters),
       });
     }
   }
@@ -1728,6 +1773,92 @@ interface PreparedVariable {
   original: ApiVariable;
 }
 
+// One level of the nested-member tree: the members declared directly under a
+// segment, plus the segments declared beneath it.
+interface NestedGroup {
+  variables: PreparedVariable[];
+  functions: PreparedFunction[];
+  children: Map<string, NestedGroup>;
+}
+
+// A stripped local carrying one or two leading identifier segments before the
+// member name (`dns.toip`, `COLOR.TEXT`, `schema.integer`). Three levels deep is
+// beyond anything the vendored documents describe, so it stays dropped rather
+// than half-emitted.
+const NESTED_MEMBER_LOCAL = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*){1,2}$/;
+
+function collectNestedGroups(module: ApiModule, prefix: string): Map<string, NestedGroup> {
+  const root = new Map<string, NestedGroup>();
+  const groupAt = (segments: readonly string[]): NestedGroup => {
+    let level = root;
+    let group: NestedGroup | undefined;
+    for (const segment of segments) {
+      let next = level.get(segment);
+      if (next === undefined) {
+        next = { variables: [], functions: [], children: new Map() };
+        level.set(segment, next);
+      }
+      group = next;
+      level = next.children;
+    }
+    return group as NestedGroup;
+  };
+  const pathOf = (local: string): string[] => local.split(".").slice(0, -1);
+
+  for (const v of module.variables) {
+    const local = stripPrefix(v.name, prefix);
+    if (!NESTED_MEMBER_LOCAL.test(local)) continue;
+    const segments = pathOf(local);
+    const prepared = prepareVariable(v, `${module.namespace}.${segments.join(".")}.`);
+    if (prepared === null) continue;
+    groupAt(segments).variables.push(prepared);
+  }
+  for (const fn of module.functions) {
+    const local = stripPrefix(fn.name, prefix);
+    if (!NESTED_MEMBER_LOCAL.test(local)) continue;
+    const segments = pathOf(local);
+    const prepared = prepareFunction(fn, `${module.namespace}.${segments.join(".")}.`);
+    if (prepared === null) continue;
+    groupAt(segments).functions.push(prepared);
+  }
+
+  const sortLevel = (level: Map<string, NestedGroup>): void => {
+    for (const group of level.values()) {
+      group.variables.sort((a, b) => a.name.localeCompare(b.name));
+      group.functions.sort((a, b) =>
+        a.name === b.name
+          ? a.original.parameters.length - b.original.parameters.length
+          : a.name.localeCompare(b.name),
+      );
+      sortLevel(group.children);
+    }
+  };
+  sortLevel(root);
+  return root;
+}
+
+// Every member a nested tree holds, at any depth, in the order the declaration
+// emitter walks it (segments sorted, each group's own members before its
+// children). Callers that need no per-segment container read the tree through
+// this rather than re-deriving which members are nested and how deep.
+function flattenNestedGroups(level: ReadonlyMap<string, NestedGroup>): {
+  variables: PreparedVariable[];
+  functions: PreparedFunction[];
+} {
+  const variables: PreparedVariable[] = [];
+  const functions: PreparedFunction[] = [];
+  const walk = (current: ReadonlyMap<string, NestedGroup>): void => {
+    for (const segment of [...current.keys()].sort((a, b) => a.localeCompare(b))) {
+      const group = current.get(segment) as NestedGroup;
+      variables.push(...group.variables);
+      functions.push(...group.functions);
+      walk(group.children);
+    }
+  };
+  walk(level);
+  return { variables, functions };
+}
+
 function prepareFunction(fn: ApiFunction, prefix: string): PreparedFunction | null {
   const stripped = stripPrefix(fn.name, prefix);
   if (!TS_IDENTIFIER.test(stripped)) return null;
@@ -1813,13 +1944,23 @@ function memberSignature(
   name: string,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  urlParameters: UrlParameterTable,
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
   const cutoff = trailingOptionalCutoff(original);
-  const params = original
-    .map((p, i) => emitParameter(p, i, i >= cutoff, mapType, resolver, elementName))
-    .join(", ");
+  const varargIndex = original.findIndex(isVarargParameter);
+  const positional = (varargIndex === -1 ? original : original.slice(0, varargIndex)).map((p, i) =>
+    emitParameter(p, i, i >= cutoff, mapType, resolver, elementName, urlParameters),
+  );
+  const params = (
+    varargIndex === -1
+      ? positional
+      : [
+          ...positional,
+          emitRestParameter(original, varargIndex, mapType, resolver, elementName, urlParameters),
+        ]
+  ).join(", ");
   const ret = emitReturn(prepared.original.returnValues, mapType, resolver, elementName);
   const predicateToken = TYPE_PREDICATES.get(elementName);
   const soleParam = original[0];
@@ -1839,8 +1980,9 @@ function emitFunction(
   name: string,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  urlParameters: UrlParameterTable,
 ): string {
-  return `function ${memberSignature(prepared, name, mapType, resolver)}`;
+  return `function ${memberSignature(prepared, name, mapType, resolver, urlParameters)}`;
 }
 
 // A colon-method member of a handle interface: identical signature machinery to a
@@ -1850,15 +1992,18 @@ function emitMethod(
   prepared: PreparedFunction,
   mapType: (t: string) => string,
   resolver: TableDocResolver,
+  urlParameters: UrlParameterTable,
 ): string {
-  return memberSignature(prepared, prepared.name, mapType, resolver);
+  return memberSignature(prepared, prepared.name, mapType, resolver, urlParameters);
 }
 
 // Build the indented JSDoc lines for a function from its ref-doc prose. The
 // summary prefers the full `description`, falling back to the one-line `brief`;
 // each `@param` name is the parameter's *emitted* name (the `arg<index>`
-// fallback applies to non-identifier names, matching `emitParameter`) so the tag
-// resolves on hover; a single documented return becomes `@returns`. Returns `[]`
+// fallback applies to non-identifier names and a vararg drops its dots, matching
+// `emitParameter` and `emitRestParameter`) so the tag resolves on hover; a
+// parameter folded into a rest element union keeps its own tag, so the prose
+// documenting it survives. A single documented return becomes `@returns`. Returns `[]`
 // for a fully-undocumented function, leaving its emission byte-identical.
 function functionDocLines(
   fn: ApiFunction,
@@ -1866,7 +2011,7 @@ function functionDocLines(
   indent: string = INDENT,
 ): string[] {
   const params = fn.parameters.map((p, index) => ({
-    name: safeParamName(p.name, index),
+    name: emittedParamName(p, index),
     doc: htmlToDocText(p.doc),
   }));
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
@@ -1928,6 +2073,83 @@ function trailingOptionalCutoff(params: readonly ApiParameter[]): number {
   return cutoff;
 }
 
+const SCENE_ADDRESS_ALIASES: Readonly<Record<string, string>> = {
+  "game-object": "SceneGameObjectAddress",
+  component: "SceneComponentAddress",
+  either: "SceneAddress",
+};
+
+// A classified address slot keeps every mapped member except `string`, which
+// becomes the matching scene-derived alias. Wrapping `mapType` rather than
+// rewriting the finished union leaves `mapSlotUnion`'s member ordering and
+// de-duplication in charge, so only the one token moves.
+function addressMapType(mapType: (t: string) => string, alias: string): (t: string) => string {
+  return (token) => (token === "string" ? alias : mapType(token));
+}
+
+// The mapped slot type of a parameter, without the name, `?` or `| undefined`
+// decoration — so a parameter folded into a rest element union contributes its
+// type alone.
+function parameterType(
+  p: ApiParameter,
+  mapType: (t: string) => string,
+  resolver: TableDocResolver,
+  elementName: string,
+  urlParameters: UrlParameterTable,
+): string {
+  const concrete = p.types.filter((t) => t !== "nil");
+  // The table is keyed by the *raw* ref-doc parameter name, not the emitted
+  // `safeParamName` fallback.
+  const alias = SCENE_ADDRESS_ALIASES[classifyUrlParameter(urlParameters, elementName, p.name)];
+  const slotMapType = alias === undefined ? mapType : addressMapType(mapType, alias);
+  return concrete.length > 0
+    ? mapSlotUnion(concrete, p.doc, slotMapType, true, resolver, elementName, "param", p.name)
+    : "unknown";
+}
+
+const VARARG_PREFIX = "...";
+
+function isVarargParameter(p: ApiParameter): boolean {
+  return p.name.startsWith(VARARG_PREFIX);
+}
+
+// A vararg's emitted name is its documented name minus the dots (`...commands`
+// -> `commands`); a bare `...` carries none, so it becomes `args`.
+function varargParamName(rawName: string, index: number): string {
+  const named = rawName.slice(VARARG_PREFIX.length);
+  return named === "" ? "args" : safeParamName(named, index);
+}
+
+function emittedParamName(p: ApiParameter, index: number): string {
+  return isVarargParameter(p) ? varargParamName(p.name, index) : safeParamName(p.name, index);
+}
+
+// TS1266 forbids a positional parameter after a rest one, so every parameter
+// documented *after* the vararg folds into the rest's element union — which is
+// the only shape that types `editor.execute("git", "log", { out: "capture" })`,
+// where upstream documents a trailing options table behind the vararg.
+function emitRestParameter(
+  params: readonly ApiParameter[],
+  varargIndex: number,
+  mapType: (t: string) => string,
+  resolver: TableDocResolver,
+  elementName: string,
+  urlParameters: UrlParameterTable,
+): string {
+  const vararg = params[varargIndex];
+  if (vararg === undefined) return "";
+  const members = [
+    ...new Set(
+      params
+        .slice(varargIndex)
+        .map((p) => parameterType(p, mapType, resolver, elementName, urlParameters)),
+    ),
+  ];
+  const first = members[0] ?? "unknown";
+  const element = members.length > 1 ? `(${members.join(" | ")})` : first;
+  return `...${varargParamName(vararg.name, varargIndex)}: ${element}[]`;
+}
+
 function emitParameter(
   p: ApiParameter,
   index: number,
@@ -1935,13 +2157,10 @@ function emitParameter(
   mapType: (t: string) => string,
   resolver: TableDocResolver,
   elementName: string,
+  urlParameters: UrlParameterTable,
 ): string {
   const name = safeParamName(p.name, index);
-  const concrete = p.types.filter((t) => t !== "nil");
-  const ts =
-    concrete.length > 0
-      ? mapSlotUnion(concrete, p.doc, mapType, true, resolver, elementName, "param", p.name)
-      : "unknown";
+  const ts = parameterType(p, mapType, resolver, elementName, urlParameters);
   // An interior doc-optional param (a required param follows, so the trailing-`?`
   // projection cannot mark it) keeps its optionality as `| undefined` — TSTL
   // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
@@ -2193,7 +2412,7 @@ export function isKnownDefoldTypeToken(token: string): boolean {
   );
 }
 
-function defaultMapType(token: string): string {
+export function defaultMapType(token: string): string {
   if (Object.hasOwn(DEFOLD_TYPE_MAP, token)) {
     const mapped = DEFOLD_TYPE_MAP[token];
     if (typeof mapped === "string") return mapped;

package/src/engine-globals.d.ts

@@ -7,9 +7,9 @@ import type * as Core from "./core-types";
 // engine-globals test fails if the two fall out of sync.
 declare global {
   /** An opaque, branded handle to a hashed name; see {@link Core.Hash}. */
-  type Hash = Core.Hash;
+  type Hash<S extends string = string> = Core.Hash<S>;
   /** Hash a string into the engine's `Hash` handle. */
-  function hash(s: string): Core.Hash;
+  function hash<S extends string>(s: S): Core.Hash<S>;
   /** Render a `Hash` handle as its hexadecimal string. */
   function hash_to_hex(h: Core.Hash): string;
   /** Pretty-print any value to the console for debugging. */

package/src/go-overloads.d.ts

@@ -33,17 +33,17 @@ declare global {
      * ```
      */
     function get<P>(): <K extends keyof P>(
-      url: string | Hash | Url,
+      url: SceneAddress | Hash | Url,
       property: K,
       options?: GoPropertyOptions,
     ) => P[K];
     function get<K extends keyof go.properties>(
-      url: string | Hash | Url,
+      url: SceneAddress | Hash | Url,
       property: K,
       options?: GoPropertyOptions,
     ): go.properties[K];
     function get(
-      url: string | Hash | Url,
+      url: SceneAddress | Hash | Url,
       property: string | Hash,
       options?: GoPropertyOptions,
     ): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">;
@@ -66,19 +66,19 @@ declare global {
      * ```
      */
     function set<P>(): <K extends keyof P>(
-      url: string | Hash | Url,
+      url: SceneAddress | Hash | Url,
       property: K,
       value: P[K],
       options?: GoPropertyOptions,
     ) => void;
     function set<K extends keyof go.properties>(
-      url: string | Hash | Url,
+      url: SceneAddress | Hash | Url,
       property: K,
       value: go.properties[K],
       options?: GoPropertyOptions,
     ): void;
     function set(
-      url: string | Hash | Url,
+      url: SceneAddress | Hash | Url,
       property: string | Hash,
       value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">,
       options?: GoPropertyOptions,

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type ApiSymbolIdentity,
   type AvailabilityLabel,
   type AvailabilityLabelKind,
+  type AvailabilityLabelOptions,
   applyMigrationOverlay,
   availabilityLabel,
   type Box2dBackend,
@@ -14,7 +15,9 @@ export {
   isSignatureTransition,
   type LogicalNameGroup,
   normalizedFunctionSignature,
+  signatureTransitionNames,
   symbolIdentityKey,
+  symbolNameKey,
   type VersionSurface,
   validateAvailability,
 } from "./api-availability";
@@ -91,3 +94,15 @@ export {
   type SignatureOverride,
   type SignatureStore,
 } from "./signature-store";
+export {
+  classifyUrlParameter,
+  collectParameterSlots,
+  collectUrlParameterSlots,
+  parameterTypesSatisfyClass,
+  REQUIRED_TYPES,
+  type UrlParameterClass,
+  type UrlParameterEntry,
+  type UrlParameterSlot,
+  type UrlParameterSource,
+  type UrlParameterTable,
+} from "./url-parameters";

package/src/msg-overloads.d.ts

@@ -31,12 +31,12 @@ declare global {
      * ```
      */
     function post<K extends string>(
-      receiver: string | Url | Hash,
+      receiver: SceneAddress | Url | Hash,
       message_id: K,
       message?: MsgPostPayload<K>,
     ): void;
     function post(
-      receiver: string | Url | Hash,
+      receiver: SceneAddress | Url | Hash,
       message_id: Hash,
       message?: Record<string | number, unknown>,
     ): void;
@@ -76,7 +76,7 @@ declare global {
      * ```
      */
     function url(): Url;
-    function url(urlstring: string): Url;
+    function url(urlstring: SceneAddress): Url;
     function url(socket: string | Hash, path: string | Hash, fragment: string | Hash): Url;
   }
 }