@defold-typescript/types 0.6.0 → 0.8.0

package/scripts/fidelity-baseline.json

@@ -26,7 +26,7 @@
   "collectionfactory": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -34,7 +34,7 @@
   "collectionproxy": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -42,7 +42,7 @@
   "crash": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 2,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -50,7 +50,7 @@
   "factory": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -58,9 +58,9 @@
   "go": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 2,
+    "recordTables": 0,
     "multiReturn": 0,
-    "droppedMembers": 3,
+    "droppedMembers": 0,
     "optionalAsRequired": 0
   },
   "graphics": {
@@ -74,7 +74,15 @@
   "gui": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 2,
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0
+  },
+  "html5": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -82,7 +90,7 @@
   "http": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -148,7 +156,7 @@
     "unknownTokens": [],
     "recordTables": 0,
     "multiReturn": 0,
-    "droppedMembers": 1,
+    "droppedMembers": 0,
     "optionalAsRequired": 0
   },
   "particlefx": {
@@ -162,7 +170,7 @@
   "physics": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 3,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -170,7 +178,7 @@
   "profiler": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -186,7 +194,7 @@
   "render": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 4,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -194,7 +202,7 @@
   "resource": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 3,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -202,7 +210,7 @@
   "socket": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 4,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0
@@ -247,6 +255,14 @@
     "droppedMembers": 0,
     "optionalAsRequired": 0
   },
+  "types": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0
+  },
   "vmath": {
     "droppedElements": 0,
     "unknownTokens": [],
@@ -258,7 +274,7 @@
   "webview": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0

package/scripts/regen.ts

@@ -9,6 +9,8 @@ import { wrapAsAmbientGlobal } from "../src/publish-dts";
 import {
   type DocSourceProvenance,
   type DownloadRefDoc,
+  type FetchChannelInfo,
+  type RefDocChannel,
   refDocCacheDir,
   resolveRefDoc,
 } from "./doc-source";
@@ -89,6 +91,8 @@ export interface ResolveTargetOptions {
   readonly readZip?: typeof readZip;
   readonly syncManifest?: readonly SyncManifestEntry[];
   readonly packageRoot?: string;
+  readonly channel?: RefDocChannel;
+  readonly fetchChannelInfo?: FetchChannelInfo;
 }
 
 // Source-aware module resolution: a `null`-source target reads committed
@@ -106,8 +110,10 @@ export async function resolveTargetModules(
   const { zip, provenance } = await resolveRefDoc({
     version: source.version,
     cacheDir: opts.cacheDir ?? refDocCacheDir(),
+    ...(opts.channel ? { channel: opts.channel } : {}),
     ...(opts.download ? { download: opts.download } : {}),
     ...(opts.readZip ? { readZip: opts.readZip } : {}),
+    ...(opts.fetchChannelInfo ? { fetchChannelInfo: opts.fetchChannelInfo } : {}),
   });
   const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
   return target.modules.map((module) => {
@@ -217,6 +223,12 @@ export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
   render: "render_script",
 };
 
+// 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.
+const LUA_STDLIB_REFERENCES =
+  '/// <reference types="lua-types/5.1" />\n/// <reference types="lua-types/special/jit-only" />\n';
+
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
   "../builtin-messages",
   "../../src/engine-globals",
@@ -247,7 +259,7 @@ export function generateKindIndex(kind: string): string {
     ...new Set([...universalNamespaces.sort(), ...[...UNIVERSAL_EXTRA_IMPORTS].sort()]),
   ].map((path) => `import "${path}";`);
   if (entry.restricted) lines.push(`import "../${entry.restricted}";`);
-  return `${lines.join("\n")}\n\nexport { ${entry.factory} } from "../../src/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "../../src/lifecycle";\n`;
+  return `${LUA_STDLIB_REFERENCES}${lines.join("\n")}\n\nexport { ${entry.factory} } from "../../src/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "../../src/lifecycle";\n`;
 }
 
 export function generateVersionIndex(

package/scripts/sync-api-docs.ts

@@ -30,6 +30,7 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("go", "doc/gameobject_script.cpp_doc.json"),
   entry("graphics", "doc/src-script_graphics.cpp_doc.json"),
   entry("gui", "doc/gui_script.cpp_doc.json"),
+  entry("html5", "doc/src-script_html5_js.cpp_doc.json"),
   entry("http", "doc/scripts-script_http.cpp_doc.json"),
   entry("image", "doc/scripts-script_image.cpp_doc.json"),
   entry("json", "doc/src-script_json.cpp_doc.json"),
@@ -50,6 +51,7 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
   entry("sys", "doc/src-script_sys.cpp_doc.json"),
   entry("tilemap", "doc/scripts-script_tilemap.cpp_doc.json"),
   entry("timer", "doc/src-script_timer.cpp_doc.json"),
+  entry("types", "doc/src-script_types.cpp_doc.json"),
   entry("vmath", "doc/src-script_vmath.cpp_doc.json"),
   entry("window", "doc/scripts-script_window.cpp_doc.json"),
   entry("zlib", "doc/src-script_zlib.cpp_doc.json"),
@@ -123,6 +125,9 @@ export function parseChecklistNamespaces(visionMarkdown: string): string[] {
 export interface ZipAccessor {
   has(entry: string): boolean;
   read(entry: string): string;
+  // Surfaces the same entry set `has` is built from, so the extension-archive
+  // resolver can hand the list to the pure `locateScriptApis` / `classifyExtension`.
+  entries(): string[];
 }
 
 export function readZip(path: string): ZipAccessor {
@@ -133,6 +138,7 @@ export function readZip(path: string): ZipAccessor {
   const entries = new Set(list.stdout.toString().split("\n").filter(Boolean));
   return {
     has: (name) => entries.has(name),
+    entries: () => [...entries],
     read: (name) => {
       const out = Bun.spawnSync(["unzip", "-p", path, name]);
       if (out.exitCode !== 0) {

package/src/emit-dts.ts

@@ -82,6 +82,20 @@ export const TS_RESERVED_NAMES = new Set([
   "extends",
 ]);
 
+// A parameter name that clears `TS_IDENTIFIER` but is a TS reserved word (e.g.
+// `var` on the `types.is_*` guards) is illegal in parameter position (TS1390),
+// unlike a member name which `TS_RESERVED_NAMES` recovers via an export alias.
+// Parameter names in a `.d.ts` are non-binding, so a reserved word takes the
+// idiomatic trailing-underscore escape (`var` -> `var_`, matching
+// ts-defold-types so the parity audit stays a superset); a genuinely
+// non-identifier token still falls back to the positional `arg<index>` form.
+// The emitted signature and its `@param` tag share this name so the tag stays
+// resolvable on hover.
+function safeParamName(name: string, index: number): string {
+  if (!TS_IDENTIFIER.test(name)) return `arg${index}`;
+  return TS_RESERVED_NAMES.has(name) ? `${name}_` : name;
+}
+
 // Element names whose `table` slot is a genuinely-arbitrary lua table by design.
 // Two kinds: the serialization/JSON passthrough functions (Defold-internal — the
 // engine round-trips an arbitrary lua value), and the platform/OS-sourced opaque
@@ -101,6 +115,55 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   "iac.set_listener",
   "push.get_scheduled",
   "push.get_all_scheduled",
+  // runtime-owned passthrough: the table is filled by user code at runtime, never
+  // by Defold's API contract. factory.create/collectionfactory.create `properties`
+  // are spawn-time overrides keyed by the spawned object's own script-property
+  // names; bare `on_message`'s receive `message` is the pre-hashed, user-routed
+  // payload (mitigated for authored code by isMessage/onMessage). No static shape
+  // exists, so `Record<string | number, unknown>` is faithful, not a loss.
+  "factory.create",
+  "collectionfactory.create",
+  "on_message",
+  // engine-formatted blob: the engine produces the value at runtime and no
+  // field list is documented, so the whole-slot `Record` is faithful, not a
+  // loss. crash.get_backtrace is "table containing the backtrace",
+  // crash.get_modules is "module table".
+  "crash.get_backtrace",
+  "crash.get_modules",
+  // platform-specific options: the doc is a dead backtick-prose cross-ref to a
+  // sibling whose function is absent from the fixture (webview.open is not
+  // documented), so no machine-readable shape exists.
+  "webview.open_raw",
+  // OS-resolver returns: the shape is set by the host resolver, not Defold's
+  // API contract; each fixture doc reads "a table with all information
+  // returned by the resolver". Mirrors the iac.set_listener / push.* platform-
+  // opaque precedent.
+  "socket.dns.tohostname",
+  "socket.dns.toip",
+  "socket.dns.getaddrinfo",
+  "socket.dns.getnameinfo",
+  // engine-built render-target tables: the "see the description" cross-refs
+  // are dead (the function's own description is empty) or carry a typed
+  // `transient: table` field whose sub-doc is prose-only, so the nested table
+  // is opaque to the field-list parser and the whole-slot `Record` is faithful.
+  "render.render_target",
+  "render.set_render_target",
+]);
+
+// skipFunction FQNs (see `api-targets.json`'s `skipFunctions`) whose absence
+// from the generated surface is *not* a fidelity loss — each is replaced by a
+// hand-written, better-typed overload in the cited `*-overloads.d.ts`, so the
+// final surface still ships the symbol, fully typed. The audit consults this
+// set to keep the `droppedMembers` count honest; an uncovered skip (e.g. a new
+// `skipFunctions` entry with no matching overload) still counts, so the gate
+// stays a real signal. Mirrors the ARBITRARY_TABLE_SLOTS audit-honesty pattern.
+export const OVERLOAD_COVERED_SKIPS = new Set([
+  // go-overloads.d.ts supplies the typed go.get / go.set / go.property shapes.
+  "go.get",
+  "go.set",
+  "go.property",
+  // msg-overloads.d.ts supplies the typed msg.post shape.
+  "msg.post",
 ]);
 
 // Element names whose `table` slot is a prose-only `a table mapping X to Y`
@@ -288,6 +351,175 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
     "tilemap.get_tiles:return:tiles",
     { kind: "mapping", key: "number", value: { key: "number", value: "number" } },
   ],
+  // resource.get_text_metrics's `metrics` return is an untyped name-only <ul>
+  // (width/height/max_ascent/max_descent, no <span class="type"> and no See
+  // cross-reference), so parseTableFields recovers nothing and the whole slot
+  // collapses to Record. The four fields are font metrics in pixels, i.e.
+  // `number`; as a return-table object curation they are required.
+  [
+    "resource.get_text_metrics:return:metrics",
+    {
+      kind: "object",
+      fields: [
+        { name: "width", types: ["number"] },
+        { name: "height", types: ["number"] },
+        { name: "max_ascent", types: ["number"] },
+        { name: "max_descent", types: ["number"] },
+      ],
+    },
+  ],
+  // profiler.view_recorded_frame's `frame_index` is a typed `<ul>` "specify one
+  // of the following": `distance` and `frame`, both numeric frame offsets. The
+  // <li> items carry no `<span class="type">`, so parseTableFields recovers
+  // nothing and the slot collapses to Record. As a param option bag both fields
+  // are optional (the caller supplies one), which the param-side `?` flag emits.
+  [
+    "profiler.view_recorded_frame:param:frame_index",
+    {
+      kind: "object",
+      fields: [
+        { name: "distance", types: ["number"] },
+        { name: "frame", types: ["number"] },
+      ],
+    },
+  ],
+  // http.request's `headers` is "optional table with custom headers", a
+  // string-keyed string map (no field list). Slot-path keying targets only
+  // `headers`; the sibling `options` table stays parser-recovered.
+  ["http.request:param:headers", { kind: "mapping", key: "string", value: "string" }],
+  // collectionproxy.get_resources returns "the resources, or an empty list", a
+  // homogeneous list of resource-path hashes (prose only, no field list).
+  ["collectionproxy.get_resources:return:resources", { kind: "array", element: "hash" }],
+  // render.predicate's `tags` is "table of tags ... can be of either hash or
+  // string type", a homogeneous array whose element is the string|hash union.
+  ["render.predicate:param:tags", { kind: "array", element: ["string", "hash"] }],
+  // render.clear's `buffers` maps the numeric graphics.BUFFER_* constants to
+  // their clear value: vector4 for the color buffer, number for depth/stencil.
+  // The mapping value is the `number | vector4` union; the mapping string branch
+  // splits the union token, so the value emits `number | Vector4`.
+  ["render.clear:param:buffers", { kind: "mapping", key: "number", value: "number | vector4" }],
+  // go.on_input and gui.on_input share the same well-known InputAction shape
+  // (the on_input function description lists the well-known fields: value,
+  // pressed, released, repeated, x/y/screen_x/screen_y/dx/dy/screen_dx/screen_dy,
+  // plus gamepad/touch/text multi-touch fields). The doc markup carries no
+  // field list of its own, so the shape is curated verbatim from the prose.
+  // Param-side optional fields: each input kind (mouse/key/text/gamepad) sets a
+  // different subset, so the call site always sees an `?` on every field.
+  // `touch` stays `table` (the nested multi-touch table has no machine-readable
+  // field list; mirrors the render.set_render_target.transient recursive case).
+  // The element is the bare `on_input` script hook (no namespace prefix), the
+  // same form the `on_message` arbitrary-table entry uses. The doc carries a
+  // well-formed touch input table, so `touch` is curated as a nested
+  // array-of-touch-records (the field has its own `<table>` listing id,
+  // pressed, released, tap_count, x, y, dx, dy, acc_x/y/z).
+  [
+    "on_input:param:action",
+    {
+      kind: "object",
+      fields: [
+        { name: "value", types: ["number"], optional: true },
+        { name: "pressed", types: ["boolean"], optional: true },
+        { name: "released", types: ["boolean"], optional: true },
+        { name: "repeated", types: ["boolean"], optional: true },
+        { name: "x", types: ["number"], optional: true },
+        { name: "y", types: ["number"], optional: true },
+        { name: "screen_x", types: ["number"], optional: true },
+        { name: "screen_y", types: ["number"], optional: true },
+        { name: "dx", types: ["number"], optional: true },
+        { name: "dy", types: ["number"], optional: true },
+        { name: "screen_dx", types: ["number"], optional: true },
+        { name: "screen_dy", types: ["number"], optional: true },
+        { name: "gamepad", types: ["number"], optional: true },
+        { name: "gamepad_axis", types: ["vector3"], optional: true },
+        {
+          name: "touch",
+          types: ["table"],
+          optional: true,
+          isList: true,
+          fields: [
+            { name: "id", types: ["number"] },
+            { name: "pressed", types: ["boolean"] },
+            { name: "released", types: ["boolean"] },
+            { name: "tap_count", types: ["number"] },
+            { name: "x", types: ["number"] },
+            { name: "y", types: ["number"] },
+            { name: "dx", types: ["number"] },
+            { name: "dy", types: ["number"] },
+            { name: "acc_x", types: ["number"] },
+            { name: "acc_y", types: ["number"] },
+            { name: "acc_z", types: ["number"] },
+          ],
+        },
+        { name: "text", types: ["string"], optional: true },
+      ],
+    },
+  ],
+  // physics.create_joint and physics.set_joint_properties both declare
+  // `properties` as a joint-type-specific table; the only universal field is
+  // `collide_connected` (parseTableFields already recovers it from the
+  // <span class="type">+<code> shape in the create_joint doc and the bare
+  // <code> shape in the set_joint_properties doc). Joint-type-specific fields
+  // stay deferred — they live in joint-type-specific docs the parser cannot
+  // see from a top-level param doc.
+  [
+    "physics.create_joint:param:properties",
+    {
+      kind: "object",
+      fields: [{ name: "collide_connected", types: ["boolean"], optional: true }],
+    },
+  ],
+  [
+    "physics.set_joint_properties:param:properties",
+    {
+      kind: "object",
+      fields: [{ name: "collide_connected", types: ["boolean"], optional: true }],
+    },
+  ],
+  // physics.raycast's `result` is "a list … see ray_cast_response for details";
+  // buildTableDocResolver resolves only FUNCTION elements so the cross-ref
+  // cannot fire (the message payload lives in messages_doc.json, not the
+  // FUNCTION slot pool). The shape is curated directly from the message
+  // catalog (the six ray_cast_response payload fields). The doc declares a
+  // `nil` branch ("If missed it returns <code>nil</code>"), so the existing
+  // nil-aware emit already projects the curated array onto the
+  // `array-object | nil` return type — no curation change needed there.
+  [
+    "physics.raycast:return:result",
+    {
+      kind: "array-object",
+      fields: [
+        { name: "fraction", types: ["number"] },
+        { name: "position", types: ["vector3"] },
+        { name: "normal", types: ["vector3"] },
+        { name: "id", types: ["hash"] },
+        { name: "group", types: ["hash"] },
+        { name: "request_id", types: ["number"] },
+      ],
+    },
+  ],
+]);
+
+// resource.set_atlas's `table` param and resource.get_atlas's `data` return are
+// flattened `<li><dl>` field lists whose `geometries` header is followed by the
+// `table`-typed siblings `vertices`/`uvs`/`indices` — the grouping heuristic
+// stops at the next `table` header, so `geometries` is left memberless and
+// collapses to `Record`. The doc markup carries no signal that those number-list
+// fields nest *under* `geometries` rather than beside it, so the nesting is
+// hand-curated. Each geometry is the triangle data (the create-input form
+// get_atlas mirrors via its cross-ref), and `vertices`/`uvs`/`indices` are
+// brace-form number-lists, hence `numberList: true` (emitted `number[]`).
+// Injected onto the already-parsed field list (every sibling stays
+// parser-authoritative), so this is a nested-field curation, not a whole-slot
+// object curation.
+const ATLAS_GEOMETRY_MEMBERS: readonly TableField[] = [
+  { name: "vertices", types: ["table"], numberList: true },
+  { name: "uvs", types: ["table"], numberList: true },
+  { name: "indices", types: ["table"], numberList: true },
+];
+
+export const NESTED_FIELD_CURATIONS: ReadonlyMap<string, readonly TableField[]> = new Map([
+  ["resource.set_atlas:param:table:geometries", ATLAS_GEOMETRY_MEMBERS],
+  ["resource.get_atlas:return:data:geometries", ATLAS_GEOMETRY_MEMBERS],
 ]);
 
 /**
@@ -415,6 +647,7 @@ export interface TableField {
   fields?: TableField[];
   isList?: boolean;
   numberList?: boolean;
+  optional?: boolean;
 }
 
 function parseUlFields(doc: string): TableField[] {
@@ -783,7 +1016,7 @@ function emitFunction(
 // for a fully-undocumented function, leaving its emission byte-identical.
 function functionDocLines(fn: ApiFunction, translations: TranslationStore): string[] {
   const params = fn.parameters.map((p, index) => ({
-    name: TS_IDENTIFIER.test(p.name) ? p.name : `arg${index}`,
+    name: safeParamName(p.name, index),
     doc: htmlToDocText(p.doc),
   }));
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
@@ -853,7 +1086,7 @@ function emitParameter(
   resolver: TableDocResolver,
   elementName: string,
 ): string {
-  const name = TS_IDENTIFIER.test(p.name) ? p.name : `arg${index}`;
+  const name = safeParamName(p.name, index);
   const concrete = p.types.filter((t) => t !== "nil");
   const ts =
     concrete.length > 0
@@ -937,7 +1170,13 @@ function mapSlotUnion(
       if (mapping !== undefined) {
         let value: string;
         if (typeof mapping.value === "string") {
-          value = mapType(mapping.value);
+          // A mapping value may be a `T | U` union token (render.clear's
+          // `number | vector4` clear value); split on `|` so each token maps
+          // individually. A single-token value (no `|`) is unaffected.
+          value = unionFromTokens(
+            mapping.value.split("|").map((token) => token.trim()),
+            mapType,
+          );
         } else if (Array.isArray(mapping.value)) {
           value = inlineTableType(mapping.value, mapType, optionalFields);
         } else {
@@ -951,8 +1190,9 @@ function mapSlotUnion(
         const object = inlineTableType(curation.fields, mapType, optionalFields);
         ts = curation.kind === "array-object" ? `${object}[]` : object;
       } else {
-        const fields = parseTableFields(doc, resolver);
-        if (fields !== null) {
+        const parsed = parseTableFields(doc, resolver);
+        if (parsed !== null) {
+          const fields = applyNestedFieldCurations(elementName, slotKind, slotName, parsed);
           const object = inlineTableType(fields, mapType, optionalFields);
           ts = isSlotLevelList(doc) ? `${object}[]` : object;
         } else {
@@ -973,6 +1213,36 @@ function tableSlotKey(elementName: string, slotKind: "param" | "return", slotNam
   return `${elementName}:${slotKind}:${slotName}`;
 }
 
+function nestedFieldKey(
+  elementName: string,
+  slotKind: "param" | "return",
+  slotName: string,
+  fieldName: string,
+): string {
+  return `${tableSlotKey(elementName, slotKind, slotName)}:${fieldName}`;
+}
+
+// Inject the curated nested members of NESTED_FIELD_CURATIONS onto the matching
+// top-level field of an otherwise parser-recovered slot, leaving every sibling
+// parser-authoritative. A field the parser already gave nested fields is left
+// alone (parser won). Returns a new array; never mutates the parser's result.
+export function applyNestedFieldCurations(
+  elementName: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  fields: readonly TableField[],
+): TableField[] {
+  if (slotKind === undefined || slotName === undefined) return [...fields];
+  return fields.map((field) => {
+    if (field.fields !== undefined) return field;
+    const curated = NESTED_FIELD_CURATIONS.get(
+      nestedFieldKey(elementName, slotKind, slotName, field.name),
+    );
+    if (curated === undefined) return field;
+    return { ...field, fields: [...curated], isList: true };
+  });
+}
+
 function arrayTypeFromTokens(
   element: string | readonly string[],
   mapType: (t: string) => string,

package/src/go-overloads.d.ts

@@ -27,8 +27,16 @@ declare global {
      * @example
      * ```ts
      * const position = go.get("#sprite", "position");
+     * // Name the target component to read its catalogued property type. The
+     * // empty call applies the type argument, then the inner call infers the key:
+     * const animation = go.get<sprite.properties>()("#sprite", "animation"); // Hash
      * ```
      */
+    function get<P>(): <K extends keyof P>(
+      url: string | Hash | Url,
+      property: K,
+      options?: GoPropertyOptions,
+    ) => P[K];
     function get<K extends keyof go.properties>(
       url: string | Hash | Url,
       property: K,
@@ -52,8 +60,17 @@ declare global {
      * @example
      * ```ts
      * go.set("#sprite", "tint", vmath.vector4(1, 0, 0, 1));
+     * // Name the target component to gate the value to its property type. The
+     * // empty call applies the type argument, then the inner call infers the key:
+     * go.set<sprite.properties>()("#sprite", "playback_rate", 2);
      * ```
      */
+    function set<P>(): <K extends keyof P>(
+      url: string | Hash | Url,
+      property: K,
+      value: P[K],
+      options?: GoPropertyOptions,
+    ) => void;
     function set<K extends keyof go.properties>(
       url: string | Hash | Url,
       property: K,

package/src/lifecycle.ts

@@ -120,27 +120,52 @@ export type RenderScriptHooks<TSelf, TInitState = TSelf> = Omit<
 // callbacks see (`NoInfer`-wrapped inside the hook set), and `TInitState` what
 // `init` returns. `ScriptHooks` itself stays callback-only so the
 // `SCRIPT_HOOK_NAMES` drift pin remains valid.
-export type ScriptHooksWithProperties<TProps, TSelf, TInitState> = ScriptHooks<
-  TSelf,
-  TInitState
+//
+// `init` is overridden to receive `self: NoInfer<TProps>` — Defold applies the
+// declared property values to `self` before `init` runs, so init-time setup can
+// read them. `self` is *only* the property channel (`TProps`), not the merged
+// `TSelf`: the return is still the sole `TInitState` inference site, and
+// `NoInfer<TProps>` keeps `self` from competing with `properties` as a second
+// `TProps` inference site (the non-circularity the no-`self` `init` originally
+// bought).
+export type ScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
+  ScriptHooks<TSelf, TInitState>,
+  "init"
 > & {
+  init?(self: NoInfer<TProps>): TInitState;
   properties?: TProps;
 };
 
-export type GuiScriptHooksWithProperties<TProps, TSelf, TInitState> = GuiScriptHooks<
-  TSelf,
-  TInitState
+export type GuiScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
+  GuiScriptHooks<TSelf, TInitState>,
+  "init"
 > & {
+  init?(self: NoInfer<TProps>): TInitState;
   properties?: TProps;
 };
 
-export type RenderScriptHooksWithProperties<TProps, TSelf, TInitState> = RenderScriptHooks<
-  TSelf,
-  TInitState
+export type RenderScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
+  RenderScriptHooks<TSelf, TInitState>,
+  "init"
 > & {
+  init?(self: NoInfer<TProps>): TInitState;
   properties?: TProps;
 };
 
+/**
+ * Extract a script module's declared property channel (`TProps`) as a nameable
+ * type. A script declares its editor properties with the value-keyed
+ * `properties` field of `defineScript`; another module reads that shape with
+ * `ScriptPropertiesOf<typeof script>` and names it as the `P` generic of
+ * `go.get`/`go.set` to read or tune those properties cross-script by URL (e.g.
+ * `go.get<ScriptPropertiesOf<typeof enemy>>()("/enemy#controller", "speed")`).
+ *
+ * It keeps one source of truth: the extracted shape is the same `TProps` the
+ * owning script's `self` exposes, so there is no second hand-maintained
+ * interface to drift.
+ */
+export type ScriptPropertiesOf<T extends { properties?: object }> = NonNullable<T["properties"]>;
+
 /**
  * Type a `.script` component's hook table. At runtime this is an identity
  * function — it returns `hooks` unchanged; its only job is typing. It infers