@defold-typescript/types 0.41.0 → 0.43.0

package/hsm/defold.d.ts

@@ -0,0 +1,9 @@
+// Generated from packages/hsm/src/defold.ts by `bun run --cwd packages/hsm declarations`; do not edit.
+export type MessageEvent<K extends MessageId> = K extends MessageId ? {
+    readonly type: K;
+} & Omit<MessagePayload<K>, "type"> : never;
+/** @noSelf */
+export interface MessageEventMapper<K extends MessageId> {
+    readonly toEvent: (message_id: Hash, message: Record<string | number, unknown>) => MessageEvent<K> | undefined;
+}
+export declare function messageEvents<const K extends MessageId>(ids: readonly K[]): MessageEventMapper<K>;

package/hsm/index.d.ts

@@ -0,0 +1,102 @@
+// Generated from packages/hsm/src/index.ts by `bun run --cwd packages/hsm declarations`; do not edit.
+export interface EventObject {
+    readonly type: string;
+}
+/** @noSelf */
+export interface MachineInstance<Ctx, E extends EventObject, P extends string = string> {
+    readonly ctx: Ctx;
+    readonly path: P | undefined;
+    readonly matches: (path: P) => boolean;
+    readonly send: (event: E) => void;
+    readonly update: (dt: number) => void;
+    readonly stop: () => void;
+}
+export type TransitionAction<Ctx, E extends EventObject, V extends E = E> = (ctx: Ctx, event: V, m: MachineInstance<Ctx, E>) => void;
+/** @noSelf */
+export interface TransitionConfig<Ctx, E extends EventObject, V extends E = E> {
+    readonly target?: string;
+    readonly guard?: (ctx: Ctx, event: V) => boolean;
+    readonly actions?: TransitionAction<Ctx, E, V> | readonly TransitionAction<Ctx, E, V>[];
+    readonly reenter?: boolean;
+}
+export type TransitionSpec<Ctx, E extends EventObject, V extends E = E> = string | TransitionConfig<Ctx, E, V> | readonly [TransitionConfig<Ctx, E, V>, ...TransitionConfig<Ctx, E, V>[]];
+export type OnConfig<Ctx, E extends EventObject> = {
+    readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, {
+        type: K;
+    }>>;
+};
+export type StateHook<Ctx, E extends EventObject> = (ctx: Ctx, m: MachineInstance<Ctx, E>) => void;
+export type UpdateHook<Ctx, E extends EventObject> = (ctx: Ctx, dt: number, m: MachineInstance<Ctx, E>) => string | undefined;
+/** @noSelf */
+export type InvokeStart<Ctx, E extends EventObject> = (ctx: Ctx, settle: (event: E) => void, m: MachineInstance<Ctx, E>) => void;
+/** @noSelf */
+export interface StateConfig<Ctx, E extends EventObject> {
+    readonly initial?: string;
+    readonly states?: {
+        readonly [name: string]: StateConfig<Ctx, E>;
+    };
+    readonly on?: OnConfig<Ctx, E>;
+    readonly after?: {
+        readonly [seconds: number]: string;
+    };
+    readonly enter?: StateHook<Ctx, E>;
+    readonly exit?: StateHook<Ctx, E>;
+    readonly update?: UpdateHook<Ctx, E>;
+    readonly invoke?: InvokeStart<Ctx, E>;
+}
+export interface MachineConfig<Ctx, E extends EventObject> extends StateConfig<Ctx, E> {
+    readonly initial: string;
+    readonly states: {
+        readonly [name: string]: StateConfig<Ctx, E>;
+    };
+}
+/** @noSelf */
+export interface Machine<Ctx, E extends EventObject, P extends string = string> {
+    readonly start: (ctx: Ctx) => MachineInstance<Ctx, E, P>;
+}
+type PathDepth = [never, 0, 1, 2, 3];
+type PathsBelow<S, D extends number> = S extends {
+    readonly states: infer Children;
+} ? {
+    [K in keyof Children & string]: K | `${K}/${D extends 1 ? Children[K] extends {
+        readonly states: object;
+    } ? string : never : PathsBelow<Children[K], PathDepth[D]>}`;
+}[keyof Children & string] : never;
+export type StatePath<C> = `/${PathsBelow<C, 4>}`;
+interface TransitionCheck<T> {
+    readonly target?: T;
+    readonly guard?: unknown;
+    readonly actions?: unknown;
+    readonly reenter?: unknown;
+}
+type SpecCheck<T> = T | TransitionCheck<T> | readonly TransitionCheck<T>[];
+type PathCheck<S, Self extends string, All extends string, Ev extends string> = {
+    readonly initial?: S extends {
+        readonly states: infer Children;
+    } ? `${Self}/${keyof Children & string}` : never;
+    readonly states?: S extends {
+        readonly states: infer Children;
+    } ? {
+        readonly [K in keyof Children]: PathCheck<Children[K], `${Self}/${K & string}`, All, Ev>;
+    } : unknown;
+    readonly on?: S extends {
+        readonly on: infer On;
+    } ? {
+        readonly [K in keyof On]: K extends Ev ? SpecCheck<All> : never;
+    } : unknown;
+    readonly after?: S extends {
+        readonly after: infer After;
+    } ? {
+        readonly [K in keyof After]: All;
+    } : unknown;
+    readonly enter?: unknown;
+    readonly exit?: unknown;
+    readonly update?: unknown;
+    readonly invoke?: unknown;
+};
+export interface MachineConfigError {
+    readonly "hsm: an initial or target names an unknown state path, or an on key an unknown event": never;
+}
+export type DefinedMachine<Ctx, E extends EventObject, C> = C extends PathCheck<C, "", StatePath<C>, E["type"]> ? Machine<Ctx, E, StatePath<C>> : MachineConfigError;
+export declare function defineMachine<Ctx, E extends EventObject>(): <const C extends MachineConfig<Ctx, E>>(config: C) => DefinedMachine<Ctx, E, C>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -45,6 +45,12 @@
     "./timers": {
       "types": "./src/timers.d.ts"
     },
+    "./hsm": {
+      "types": "./hsm/index.d.ts"
+    },
+    "./hsm/defold": {
+      "types": "./hsm/defold.d.ts"
+    },
     "./api-availability.json": "./api-availability.json",
     "./api-signatures.json": "./api-signatures.json",
     "./url-parameters.json": "./url-parameters.json",
@@ -53,6 +59,7 @@
   "files": [
     "src",
     "generated",
+    "hsm",
     "scripts",
     "api-targets.json",
     "api-migrations.json",
@@ -64,6 +71,7 @@
     "fixtures/messages_doc.json",
     "fixtures/defold-*",
     "!fixtures/defold-*/engine-bindings",
+    "!fixtures/defold-*/annotations",
     "examples/translations.json",
     "!src/**/*.test.ts",
     "!scripts/**/*.test.ts",
@@ -82,7 +90,11 @@
     "!scripts/engine-binding-verdicts.ts",
     "!scripts/engine-binding-verdicts.json",
     "!scripts/lua-kind.ts",
-    "!scripts/index-slot-scan.ts"
+    "!scripts/index-slot-scan.ts",
+    "!scripts/lua-annotations.ts",
+    "!scripts/lua-annotation-diff.ts",
+    "!scripts/lua-annotation-verdicts.ts",
+    "!scripts/lua-annotation-verdicts.json"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/import-defold-release.ts

@@ -5,6 +5,8 @@ import { refDocCacheDir, resolveRefDoc } from "./doc-source";
 import {
   apiElementIdentity,
   EDITOR_MANIFEST,
+  type ExtractedFixture,
+  extractAnnotationFixtures,
   IGNORED_UPSTREAM,
   mergeApiDocs,
   readZip,
@@ -153,6 +155,9 @@ export interface ReleaseImportManifest {
     readonly unknownTypes: UnknownTypeBlocker[];
     readonly unmappedFunctionNamespaces: UnmappedNamespaceBlocker[];
   };
+  // The file names vendored under `annotations/`, which `loadAnnotations` holds
+  // the directory to. Empty before 1.13.2; absent from manifests written earlier.
+  readonly annotationFiles: readonly string[];
   readonly snapshots: Array<{
     readonly namespace: string;
     readonly fixture: string;
@@ -164,6 +169,8 @@ export interface ReleaseImportManifest {
 export type ReleaseImportPlan = Omit<ReleaseImportManifest, "snapshots"> & {
   readonly manifest: ReleaseImportManifest;
   readonly snapshots: ReleaseImportSnapshot[];
+  // The release's LuaLS annotation files, vendored verbatim. Empty before 1.13.2.
+  readonly annotations: ExtractedFixture[];
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -259,7 +266,9 @@ function unknownTypeBlockers(
   return out;
 }
 
-function reportWithoutSnapshots(plan: Omit<ReleaseImportPlan, "manifest">): ReleaseImportManifest {
+function reportWithoutSnapshots(
+  plan: Omit<ReleaseImportPlan, "manifest" | "annotations">,
+): ReleaseImportManifest {
   return {
     version: plan.version,
     baseline: plan.baseline,
@@ -269,6 +278,7 @@ function reportWithoutSnapshots(plan: Omit<ReleaseImportPlan, "manifest">): Rele
     moved: plan.moved,
     symbols: plan.symbols,
     blockers: plan.blockers,
+    annotationFiles: plan.annotationFiles,
     snapshots: plan.snapshots.map(({ namespace, fixture, sourceEntries, symbolSources }) => ({
       namespace,
       fixture,
@@ -417,6 +427,7 @@ export function buildReleaseImportPlan(input: {
     (a, b) => a.namespace.localeCompare(b.namespace) || a.symbol.localeCompare(b.symbol),
   );
   const ready = unknownTypes.length === 0 && unmappedFunctionNamespaces.length === 0;
+  const annotations = extractAnnotationFixtures(input.zip);
   const planBase = {
     version: input.version,
     baseline: input.baseline.id,
@@ -426,10 +437,11 @@ export function buildReleaseImportPlan(input: {
     moved,
     symbols,
     blockers: { unknownTypes, unmappedFunctionNamespaces },
+    annotationFiles: annotations.map((annotation) => annotation.namespace).sort(),
     snapshots,
   };
   const manifest = reportWithoutSnapshots(planBase);
-  return { ...planBase, manifest };
+  return { ...planBase, manifest, annotations };
 }
 
 export function releaseImportReportJson(plan: ReleaseImportPlan): string {
@@ -448,6 +460,13 @@ export function applyReleaseImport(plan: ReleaseImportPlan, packageRoot = PACKAG
     writeFileSync(path, `${JSON.stringify(snapshot.doc, null, 2)}\n`);
     written.push(relative);
   }
+  for (const annotation of plan.annotations) {
+    const relative = `${relativeRoot}/${annotation.fixture}`;
+    const path = resolve(packageRoot, relative);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, annotation.contents);
+    written.push(relative);
+  }
   // The prefixless builtins (`hash`, `pprint`, ...) are hand-vendored rather than
   // generated, so no upstream snapshot carries them. Seeding the canonical copy
   // here is what keeps a newly imported target from being born without a globals

package/scripts/sync-api-docs.ts

@@ -1,6 +1,6 @@
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
 import { DEFOLD_TYPE_MAP } from "../src/core-types";
 import { parseScriptApi } from "../src/script-api";
@@ -404,6 +404,21 @@ export function extractFixtures(
   });
 }
 
+// Since 1.13.2 the ref-doc zip ships LuaLS annotation files beside the JSON:
+// `doc/<namespace>.lua` for the game runtime and `doc/<namespace>.editor_script`
+// for the editor VM. They are vendored verbatim, never parsed at sync time.
+const ANNOTATION_ENTRY = /^doc\/([^/]+\.(?:lua|editor_script))$/;
+
+export function extractAnnotationFixtures(zip: ZipAccessor): ExtractedFixture[] {
+  const out: ExtractedFixture[] = [];
+  for (const zipEntry of [...zip.entries()].sort()) {
+    const file = ANNOTATION_ENTRY.exec(zipEntry)?.[1];
+    if (file === undefined) continue;
+    out.push({ namespace: file, fixture: `annotations/${file}`, contents: zip.read(zipEntry) });
+  }
+  return out;
+}
+
 export type FixtureSyncStatus = "clean" | "drift" | "created";
 
 export interface FixtureSyncResult {
@@ -442,7 +457,8 @@ export function syncFixtures(zip: ZipAccessor, options: SyncOptions = {}): Fixtu
 
 // Compare/write a set of already-extracted fixtures against disk. Shared by
 // the core (zip) and extension (`.script_api`) sync paths so both honor the
-// identical created/clean/drift + format-on-write semantics.
+// identical created/clean/drift + format-on-write semantics. A non-JSON fixture
+// (a vendored annotation file) compares and writes byte-for-byte.
 export function syncExtractedFixtures(
   items: readonly ExtractedFixture[],
   options: Omit<SyncOptions, "manifest"> = {},
@@ -453,15 +469,21 @@ export function syncExtractedFixtures(
   const results: FixtureSyncResult[] = [];
   for (const item of items) {
     const path = resolve(root, item.fixture);
+    const json = item.fixture.endsWith(".json");
     const existing = readFixtureOrNull(path);
     const status: FixtureSyncStatus =
       existing === null
         ? "created"
-        : canonicalJson(existing) === canonicalJson(item.contents)
+        : (
+              json
+                ? canonicalJson(existing) === canonicalJson(item.contents)
+                : existing === item.contents
+            )
           ? "clean"
           : "drift";
     if (!check && status !== "clean") {
-      writeFileSync(path, format(item.contents));
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, json ? format(item.contents) : item.contents);
     }
     results.push({ namespace: item.namespace, fixture: item.fixture, status });
   }
@@ -641,11 +663,16 @@ if (import.meta.main) {
   const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
   const editorFixtures = extractFixtures(zip, EDITOR_MANIFEST);
   const editorVmFixtures = extractFixtures(zip, EDITOR_VM_MANIFEST);
+  const annotationFixtures = extractAnnotationFixtures(zip);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
     ...syncExtractedFixtures(luaStdlibFixtures, { check }),
     ...syncExtractedFixtures(editorFixtures, { check }),
     ...syncExtractedFixtures(editorVmFixtures, { check }),
+    ...syncExtractedFixtures(annotationFixtures, {
+      check,
+      fixturesRoot: resolve(PACKAGE_ROOT, `fixtures/defold-${DEFOLD_VERSION}`),
+    }),
   ];
   const syncedDocs = coreFixtures.map((f) => ({
     namespace: f.namespace,