@defold-typescript/types 0.34.0 → 0.35.0

package/generated/versions/defold-1.13.0/render.d.ts

@@ -128,7 +128,7 @@ declare global {
      * render.draw(self.tile_pred);
      * ```
      */
-    function disable_state(state: Opaque<"constant">): void;
+    function disable_state(state: number & { readonly __brand: "graphics.STATE_DEPTH_TEST" } | number & { readonly __brand: "graphics.STATE_STENCIL_TEST" } | number & { readonly __brand: "graphics.STATE_BLEND" } | number & { readonly __brand: "graphics.STATE_ALPHA_TEST" } | number & { readonly __brand: "graphics.STATE_CULL_FACE" } | number & { readonly __brand: "graphics.STATE_POLYGON_OFFSET_FILL" }): void;
     /**
      * Disables a texture that has previourly been enabled.
      *
@@ -307,7 +307,7 @@ declare global {
      * render.disable_state(graphics.STATE_STENCIL_TEST);
      * ```
      */
-    function enable_state(state: Opaque<"constant">): void;
+    function enable_state(state: number & { readonly __brand: "graphics.STATE_DEPTH_TEST" } | number & { readonly __brand: "graphics.STATE_STENCIL_TEST" } | number & { readonly __brand: "graphics.STATE_BLEND" } | number & { readonly __brand: "graphics.STATE_ALPHA_TEST" } | number & { readonly __brand: "graphics.STATE_CULL_FACE" } | number & { readonly __brand: "graphics.STATE_POLYGON_OFFSET_FILL" }): void;
     /**
      * Sets the specified texture handle for a render target attachment or a regular texture
      * that should be used for rendering. The texture can be bound to either a texture unit
@@ -502,154 +502,6 @@ declare global {
      * ```
      */
     function predicate(tags: (string | Hash)[]): number;
-    /**
-     * Creates a new render target according to the supplied
-     * specification table.
-     * The table should contain keys specifying which buffers should be created
-     * with what parameters. Each buffer key should have a table value consisting
-     * of parameters. The following parameter keys are available:
-     *
-     * Key
-     * Values
-     *
-     * `format`
-     * `graphics.TEXTURE_FORMAT_LUMINANCE`
-     * `graphics.TEXTURE_FORMAT_RGB`
-     * `graphics.TEXTURE_FORMAT_RGBA`
-     * `graphics.TEXTURE_FORMAT_DEPTH`
-     * `graphics.TEXTURE_FORMAT_STENCIL`
-     * `graphics.TEXTURE_FORMAT_RGBA32F`
-     * `graphics.TEXTURE_FORMAT_RGBA16F`
-     *
-     * `width`
-     * number
-     *
-     * `height`
-     * number
-     *
-     * `min_filter` (optional)
-     * `graphics.TEXTURE_FILTER_LINEAR`
-     * `graphics.TEXTURE_FILTER_NEAREST`
-     *
-     * `mag_filter` (optional)
-     * `graphics.TEXTURE_FILTER_LINEAR`
-     * `graphics.TEXTURE_FILTER_NEAREST`
-     *
-     * `u_wrap` (optional)
-     * `graphics.TEXTURE_WRAP_CLAMP_TO_BORDER`
-     * `graphics.TEXTURE_WRAP_CLAMP_TO_EDGE`
-     * `graphics.TEXTURE_WRAP_MIRRORED_REPEAT`
-     * `graphics.TEXTURE_WRAP_REPEAT`
-     *
-     * `v_wrap` (optional)
-     * `graphics.TEXTURE_WRAP_CLAMP_TO_BORDER`
-     * `graphics.TEXTURE_WRAP_CLAMP_TO_EDGE`
-     * `graphics.TEXTURE_WRAP_MIRRORED_REPEAT`
-     * `graphics.TEXTURE_WRAP_REPEAT`
-     *
-     * `flags` (optional)
-     * `render.TEXTURE_BIT` (only applicable to depth and stencil buffers)
-     *
-     * The render target can be created to support multiple color attachments. Each attachment can have different format settings and texture filters,
-     * but attachments must be added in sequence, meaning you cannot create a render target at slot 0 and 3.
-     * Instead it has to be created with all four buffer types ranging from [0..3] (as denoted by graphics.BUFFER_TYPE_COLORX_BIT where 'X' is the attachment you want to create).
-     * It is not guaranteed that the device running the script can support creating render targets with multiple color attachments. To check if the device can support multiple attachments,
-     * you can check if the `render` table contains any of the `BUFFER_TYPE_COLOR1_BIT`, `BUFFER_TYPE_COLOR2_BIT` or `BUFFER_TYPE_COLOR3_BIT` constants:
-     *
-     * `function init(self)
-     * if graphics.BUFFER_TYPE_COLOR1_BIT == nil then
-     * -- this devices does not support multiple color attachments
-     * end
-     * end
-     * `
-     *
-     * @param name - render target name
-     * @param parameters - table of buffer parameters, see the description for available keys and values
-     * @returns new render target
-     * @example
-     * ```ts
-     * // How to create a new render target and draw to it:
-     * export default defineScript({
-     *   init() {
-     *     // render target buffer parameters
-     *     const color_params = {
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
-     *       width: render.get_window_width(),
-     *       height: render.get_window_height(),
-     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
-     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
-     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *     };
-     *     const depth_params = {
-     *       format: graphics.TEXTURE_FORMAT_DEPTH,
-     *       width: render.get_window_width(),
-     *       height: render.get_window_height(),
-     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *     };
-     *     return {
-     *       my_render_target: render.render_target({
-     *         [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
-     *         [graphics.BUFFER_TYPE_DEPTH_BIT]: depth_params,
-     *       }),
-     *     };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // enable target so all drawing is done to it
-     *     render.set_render_target(self.my_render_target);
-     *
-     *     // draw a predicate to the render target
-     *     render.draw(self.my_pred);
-     *   },
-     * });
-     *
-     * // How to create a render target with multiple outputs:
-     * export default defineScript({
-     *   init() {
-     *     // render target buffer parameters
-     *     const color_params_rgba = {
-     *       format: graphics.TEXTURE_FORMAT_RGBA,
-     *       width: render.get_window_width(),
-     *       height: render.get_window_height(),
-     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
-     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
-     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *     };
-     *     const color_params_float = {
-     *       format: graphics.TEXTURE_FORMAT_RG32F,
-     *       width: render.get_window_width(),
-     *       height: render.get_window_height(),
-     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
-     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
-     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
-     *     };
-     *
-     *     // Create a render target with three color attachments
-     *     // Note: No depth buffer is attached here
-     *     return {
-     *       my_render_target: render.render_target({
-     *         [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params_rgba,
-     *         [graphics.BUFFER_TYPE_COLOR1_BIT]: color_params_rgba,
-     *         [graphics.BUFFER_TYPE_COLOR2_BIT]: color_params_float,
-     *       }),
-     *     };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // enable target so all drawing is done to it
-     *     render.enable_render_target(self.my_render_target);
-     *
-     *     // draw a predicate to the render target
-     *     render.draw(self.my_pred);
-     *   },
-     * });
-     * ```
-     */
-    function render_target(name: string, parameters: Record<string | number, unknown>): Opaque<"render_target">;
     /**
      * Sets the blend equation with separate equations for the color and alpha channels.
      *

package/generated/versions/defold-1.13.0/sys.d.ts

@@ -228,7 +228,7 @@ declare global {
      * }
      * ```
      */
-    function get_connectivity(): Opaque<"constant">;
+    function get_connectivity(): number & { readonly __brand: "sys.NETWORK_DISCONNECTED" } | number & { readonly __brand: "sys.NETWORK_CONNECTED_CELLULAR" } | number & { readonly __brand: "sys.NETWORK_CONNECTED" };
     /**
      * Returns a table with engine information.
      *

package/generated/versions/defold-1.13.0/vmath.d.ts

@@ -91,25 +91,6 @@ declare global {
      * ```
      */
     function dot(v1: Vector3 | Vector4, v2: Vector3 | Vector4): number;
-    /**
-     * Converts euler angles (x, y, z) in degrees into a quaternion
-     * The error is guaranteed to be less than 0.001.
-     * If the first argument is vector3, its values are used as x, y, z angles.
-     *
-     * @param x - rotation around x-axis in degrees or vector3 with euler angles in degrees
-     * @param y - rotation around y-axis in degrees
-     * @param z - rotation around z-axis in degrees
-     * @returns quaternion describing an equivalent rotation (231 (YZX) rotation sequence)
-     * @example
-     * ```ts
-     * const q = vmath.euler_to_quat(0, 45, 90);
-     * print(q); // => vmath.quat(0.27059805393219, 0.27059805393219, 0.65328145027161, 0.65328145027161)
-     *
-     * const v = vmath.vector3(0, 0, 90);
-     * print(vmath.euler_to_quat(v)); // => vmath.quat(0, 0, 0.70710676908493, 0.70710676908493)
-     * ```
-     */
-    function euler_to_quat(x: number | Vector3, y: number, z: number): Quaternion;
     /**
      * The resulting matrix is the inverse of the supplied matrix.
      * For ortho-normal matrices, e.g. regular object transformation,

package/generated/versions/defold-1.13.0/window.d.ts

@@ -1,6 +1,4 @@
 /** @noSelfInFile */
-import type { Opaque } from "../../../src/core-types";
-
 declare global {
   /**
    * Functions and constants to access the window, window event listeners
@@ -58,7 +56,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function get_dim_mode(): Opaque<"constant">;
+    function get_dim_mode(): number & { readonly __brand: "window.DIMMING_UNKNOWN" } | number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" };
     /**
      * This returns the content scale of the current display.
      *
@@ -113,7 +111,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function set_dim_mode(mode: Opaque<"constant">): void;
+    function set_dim_mode(mode: number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" }): void;
     /**
      * Sets a window event listener. Only one window event listener can be set at a time.
      *

package/generated/vmath.d.ts

@@ -91,25 +91,6 @@ declare global {
      * ```
      */
     function dot(v1: Vector3 | Vector4, v2: Vector3 | Vector4): number;
-    /**
-     * Converts euler angles (x, y, z) in degrees into a quaternion
-     * The error is guaranteed to be less than 0.001.
-     * If the first argument is vector3, its values are used as x, y, z angles.
-     *
-     * @param x - rotation around x-axis in degrees or vector3 with euler angles in degrees
-     * @param y - rotation around y-axis in degrees
-     * @param z - rotation around z-axis in degrees
-     * @returns quaternion describing an equivalent rotation (231 (YZX) rotation sequence)
-     * @example
-     * ```ts
-     * const q = vmath.euler_to_quat(0, 45, 90);
-     * print(q); // => vmath.quat(0.27059805393219, 0.27059805393219, 0.65328145027161, 0.65328145027161)
-     *
-     * const v = vmath.vector3(0, 0, 90);
-     * print(vmath.euler_to_quat(v)); // => vmath.quat(0, 0, 0.70710676908493, 0.70710676908493)
-     * ```
-     */
-    function euler_to_quat(x: number | Vector3, y: number, z: number): Quaternion;
     /**
      * The resulting matrix is the inverse of the supplied matrix.
      * For ortho-normal matrices, e.g. regular object transformation,

package/generated/window.d.ts

@@ -1,6 +1,4 @@
 /** @noSelfInFile */
-import type { Opaque } from "../src/core-types";
-
 declare global {
   /**
    * Functions and constants to access the window, window event listeners
@@ -58,7 +56,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function get_dim_mode(): Opaque<"constant">;
+    function get_dim_mode(): number & { readonly __brand: "window.DIMMING_UNKNOWN" } | number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" };
     /**
      * This returns the content scale of the current display.
      *
@@ -113,7 +111,7 @@ declare global {
      *
      * - `window.DIMMING_OFF`
      */
-    function set_dim_mode(mode: Opaque<"constant">): void;
+    function set_dim_mode(mode: number & { readonly __brand: "window.DIMMING_ON" } | number & { readonly __brand: "window.DIMMING_OFF" }): void;
     /**
      * Sets a window event listener. Only one window event listener can be set at a time.
      *

package/index.d.ts

@@ -28,8 +28,6 @@ import "./generated/graphics";
 import "./generated/gui";
 import "./generated/html5";
 import "./generated/http";
-import "./generated/iac";
-import "./generated/iap";
 import "./generated/image";
 import "./generated/json";
 import "./generated/label";
@@ -40,8 +38,8 @@ import "./generated/msg";
 import "./generated/particlefx";
 import "./generated/physics";
 import "./generated/profiler";
-import "./generated/push";
 import "./generated/render";
+import "./src/render-overloads";
 import "./generated/resource";
 import "./generated/socket";
 import "./src/socket-types";
@@ -53,7 +51,6 @@ import "./generated/timer";
 import "./generated/types";
 import "./generated/vmath";
 import "./src/vmath-overloads";
-import "./generated/webview";
 import "./generated/window";
 import "./generated/zlib";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -66,7 +66,9 @@
     "!src/**/*.test.ts",
     "!scripts/**/*.test.ts",
     "!src/**/__snapshots__",
-    "!scripts/lua-types-signature-index.ts"
+    "!scripts/lua-types-signature-index.ts",
+    "!scripts/fidelity-audit.ts",
+    "!scripts/augmentation-namespaces.ts"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/extension-goldens.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ModuleManifestEntry } from "./regen";
+
+// Committed declarations the `resolve` emitter must reproduce for the extensions
+// whose ref-docs this repo carries. They are a golden lane, not a surface: no
+// entrypoint, kind index or pinned version imports them. They live in their own
+// module because `resolve` imports `regen.ts` from the published package, which
+// does not ship these root fixtures, so reading them at `regen.ts` load time would
+// break every installed `resolve`.
+export const EXTENSION_GOLDENS_DIR = "extension-goldens";
+
+const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const EXTENSION_GOLDEN_NAMESPACES = ["iac", "iap", "push", "webview"] as const;
+
+export const EXTENSION_GOLDEN_MANIFEST: readonly ModuleManifestEntry[] =
+  EXTENSION_GOLDEN_NAMESPACES.map((namespace) => ({
+    namespace,
+    doc: JSON.parse(
+      readFileSync(resolve(PACKAGE_ROOT, "fixtures", `${namespace}_doc.json`), "utf8"),
+    ),
+    outFile: `${namespace}.d.ts`,
+  }));

package/scripts/generate-api-signatures.ts

@@ -1,7 +1,13 @@
 import { resolve } from "node:path";
 import { symbolIdentityKey } from "../src/api-availability";
 import { selectCompleteVersionSurfaces, versionOf } from "./generate-api-availability";
-import { generateModuleSignatures, loadApiTargets, loadTargetModules } from "./regen";
+import {
+  generateModuleSignatures,
+  loadApiTargets,
+  loadTargetModules,
+  type ModuleManifestEntry,
+} from "./regen";
+import { loadSignatureFile } from "./signature-store-fs";
 
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
@@ -16,6 +22,35 @@ export interface BuildSignaturesOptions {
   readonly registryPath?: string;
 }
 
+// The authored replacement for a symbol the skip filter withheld, read from the
+// same `signatures/<ns>.json` store the version-prefixed API pages render from.
+// One seam keeps all three artifacts consistent: `overloads-signature-parity`
+// pins the store to the `src/*-overloads.d.ts` declarations, so folding the
+// store in cannot drift from the surface a consumer actually compiles against.
+function authoredSignature(packageRoot: string, namespace: string, fqn: string): string | null {
+  const store = loadSignatureFile(resolve(packageRoot, "signatures", `${namespace}.json`));
+  const forms = store[fqn]?.signatures ?? [];
+  return forms.length > 0 ? forms.join("\n") : null;
+}
+
+// The symbols `skipFunctions` removed from this module, as the difference
+// between the unfiltered and filtered signature emits. Derived rather than
+// re-matched so the withholding rules stay owned by `prepareGeneratedModule`.
+export function withheldSymbols(entry: ModuleManifestEntry): { key: string; fqn: string }[] {
+  if ((entry.skipFunctions ?? []).length === 0) return [];
+  const kept = new Set(
+    generateModuleSignatures(entry).map(({ identity }) => symbolIdentityKey(identity)),
+  );
+  const withheld: { key: string; fqn: string }[] = [];
+  for (const { identity } of generateModuleSignatures({ ...entry, skipFunctions: [] })) {
+    const key = symbolIdentityKey(identity);
+    if (kept.has(key)) continue;
+    const fqn = key.split("\0")[2] as string;
+    withheld.push({ key, fqn });
+  }
+  return withheld;
+}
+
 function sortObjectKeys(record: Record<string, string>): Record<string, string> {
   const sorted: Record<string, string> = {};
   for (const key of Object.keys(record).sort()) sorted[key] = record[key] as string;
@@ -34,6 +69,10 @@ export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): S
       for (const { identity, tsSignature } of generateModuleSignatures(entry)) {
         perSymbol[symbolIdentityKey(identity)] = tsSignature;
       }
+      for (const { key, fqn } of withheldSymbols(entry)) {
+        const authored = authoredSignature(packageRoot, entry.namespace, fqn);
+        if (authored !== null) perSymbol[key] = authored;
+      }
     }
     versions[version] = sortObjectKeys(perSymbol);
   }

package/scripts/materialize-version.ts

@@ -15,7 +15,12 @@ import {
   resolveTargetModules,
 } from "./regen";
 
-export { RUNTIME_KIND_MANIFEST, SRC_AUGMENTATION_MODULES, targetKindManifest } from "./regen";
+export {
+  RESTRICTED_SRC_AUGMENTATIONS,
+  RUNTIME_KIND_MANIFEST,
+  SRC_AUGMENTATION_MODULES,
+  targetKindManifest,
+} from "./regen";
 
 // The surface's own `core-types` module: a re-export of the installed package's,
 // so every declaration in the surface reaches the brand types through a
@@ -26,6 +31,10 @@ export interface RenderMaterializedKindIndexOptions {
   readonly kind: string;
   readonly universalModules: readonly string[];
   readonly restrictedModule: string | null;
+  // The `src/*` augmentations this kind earns because they re-open the very
+  // namespace the kind is restricted to. They sit outside `universalModules`
+  // precisely so no other kind imports them.
+  readonly restrictedAugmentations?: readonly string[];
   // Set for a kind built from the target's own editor documents. It replaces
   // the universal set outright — an editor kind is disjoint from the runtime
   // surface, not a narrowing of it.
@@ -54,6 +63,11 @@ export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOpt
   if (entry.only === undefined && opts.restrictedModule) {
     lines.push(`import "../${opts.restrictedModule}";`);
   }
+  if (entry.only === undefined) {
+    for (const augmentation of opts.restrictedAugmentations ?? []) {
+      lines.push(`import "../${augmentation}";`);
+    }
+  }
   const from = installedFactoryModule(entry);
   const values = [entry.factory, ...(entry.extraExports ?? [])].join(", ");
   const typeExports = entry.extraTypeExports?.length

package/scripts/regen.ts

@@ -191,15 +191,6 @@ const DEFAULT_TARGET = API_TARGETS.find((t) => t.default === true) as ApiTarget;
 
 export const MODULE_MANIFEST: readonly ModuleManifestEntry[] = loadTargetModules(DEFAULT_TARGET);
 
-// The fidelity audit runs over the promoted default surface (the `default: true`
-// target) so the 1.13-only modules (b2d.*, compute, material) and the 1.13 model
-// additions are audited too — auditing the older 1.12.4 target left them unseen,
-// which is how the promoted surface shipped opaque `Record` fallbacks while the
-// gate read `recordTables: 0`.
-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
@@ -544,16 +535,29 @@ 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",
-  "../../src/custom-messages",
-  "../../src/engine-globals",
-  "../../src/msg-overloads",
-  "../../src/message-guard",
-  "../../src/window-event-guard",
-  "../../src/scene-addresses",
-  "../../src/go-overloads",
-  "../../src/vmath-overloads",
+// One augmentation a complete script surface imports. `restrictedTo` names the
+// kind-restricted namespace the augmentation re-opens: such an entry belongs on
+// that namespace's kind index alone, or it would re-open a wall the kind closes.
+// The marker is declared rather than parsed out of the `.d.ts`, so
+// `generateKindIndex` stays pure; `srcAugmentationScopingViolations` in
+// `./augmentation-namespaces` is what catches a future restricted augmentation
+// added without one, by reading the namespaces each file really re-opens.
+interface UniversalExtraImport {
+  readonly specifier: string;
+  readonly restrictedTo?: string;
+}
+
+const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
+  { specifier: "../builtin-messages" },
+  { specifier: "../../src/custom-messages" },
+  { specifier: "../../src/engine-globals" },
+  { specifier: "../../src/msg-overloads" },
+  { specifier: "../../src/message-guard" },
+  { specifier: "../../src/window-event-guard" },
+  { specifier: "../../src/scene-addresses" },
+  { specifier: "../../src/go-overloads" },
+  { specifier: "../../src/render-overloads", restrictedTo: "render" },
+  { specifier: "../../src/vmath-overloads" },
 ];
 
 const SRC_IMPORT_PREFIX = "../../src/";
@@ -561,9 +565,18 @@ const SRC_IMPORT_PREFIX = "../../src/";
 // The hand-authored `src/*` augmentations a complete script surface needs,
 // derived from the one declaration the generated kind index renders from so a
 // new augmentation reaches every materialization path with no second edit.
-export const SRC_AUGMENTATION_MODULES: readonly string[] = UNIVERSAL_EXTRA_IMPORTS.filter(
-  (specifier) => specifier.startsWith(SRC_IMPORT_PREFIX),
-).map((specifier) => specifier.slice(SRC_IMPORT_PREFIX.length));
+export const SRC_AUGMENTATION_MODULES: readonly string[] = UNIVERSAL_EXTRA_IMPORTS.filter((entry) =>
+  entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+).map((entry) => entry.specifier.slice(SRC_IMPORT_PREFIX.length));
+
+// The `src/*` augmentations bound to a kind-restricted namespace, as
+// `<module name> -> <namespace>`. Exported so the CLI's materialization scopes
+// them the same way the in-repo kind indexes do, from one declaration.
+export const RESTRICTED_SRC_AUGMENTATIONS: Readonly<Record<string, string>> = Object.fromEntries(
+  UNIVERSAL_EXTRA_IMPORTS.filter(
+    (entry) => entry.restrictedTo !== undefined && entry.specifier.startsWith(SRC_IMPORT_PREFIX),
+  ).map((entry) => [entry.specifier.slice(SRC_IMPORT_PREFIX.length), entry.restrictedTo as string]),
+);
 
 // Read those augmentations as surface-root files. Mirrors
 // `loadTargetEditorModules`: a missing file throws with its path rather than
@@ -664,9 +677,14 @@ export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARG
   const universalNamespaces = MODULE_MANIFEST.filter(
     (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
   ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
+  // An augmentation bound to a restricted namespace rides only that namespace's
+  // kind index; every unmarked entry stays universal.
+  const extraImports = UNIVERSAL_EXTRA_IMPORTS.filter(
+    (extra) => extra.restrictedTo === undefined || extra.restrictedTo === entry.restricted,
+  ).map((extra) => extra.specifier);
   const modules = (
     entry.only === undefined
-      ? [...new Set([...universalNamespaces.sort(), ...[...UNIVERSAL_EXTRA_IMPORTS].sort()])]
+      ? [...new Set([...universalNamespaces.sort(), ...extraImports.sort()])]
       : [...editorKindModules(target), ...(entry.extraModules ?? [])]
   ).map((path) => retargetSrcPath(path, srcPrefix));
   const lines = modules.map((path) => `import "${path}";`);
@@ -687,8 +705,10 @@ export function generateKindIndex(kind: string, target: ApiTarget = DEFAULT_TARG
 export function generateVersionIndex(
   versionId: string,
   manifest: readonly VersionedModuleManifestEntry[] = VERSIONED_MODULE_MANIFEST,
-  // Bare names appended after the module imports. A materialized surface carries
-  // the `src/*` augmentations beside its modules; the in-repo emit does not.
+  // Names appended after the module imports. A materialized surface carries the
+  // `src/*` augmentations beside its modules and names them bare; the in-repo
+  // emit reaches back into the package and passes an already-relative specifier,
+  // which is kept verbatim rather than re-anchored to the surface directory.
   extraImports: readonly string[] = [],
 ): string {
   const imports = [
@@ -698,7 +718,7 @@ export function generateVersionIndex(
       .sort(),
     ...extraImports,
   ]
-    .map((module) => `import "./${module}";`)
+    .map((module) => `import "${module.startsWith(".") ? module : `./${module}`}";`)
     .join("\n");
   // A pinned consumer names this surface in `types` and never loads the
   // package entrypoint, so the stdlib directives have to lead here too. A
@@ -706,6 +726,16 @@ export function generateVersionIndex(
   return `${LUA_STDLIB_REFERENCES}${imports}\n\nexport {};\n`;
 }
 
+// The authored augmentations a committed per-version index imports, addressed
+// back into the package's `src/`. The in-repo surface has no copies beside its
+// modules, so a skipped symbol would otherwise be declared on no versioned
+// surface at all. Derived from `SRC_AUGMENTATION_MODULES`, so a new augmentation
+// reaches the pinned surfaces on the same edit that reaches the materialized ones.
+export function versionSrcAugmentationImports(target: ApiTarget): string[] {
+  const srcPrefix = target.coreTypesImport.slice(0, -"core-types".length);
+  return SRC_AUGMENTATION_MODULES.map((name) => `${srcPrefix}${name}`);
+}
+
 // 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
@@ -732,7 +762,37 @@ export function targetKindManifest(target: ApiTarget): readonly KindManifestEntr
   return [...RUNTIME_KIND_MANIFEST, ...KIND_MODULE_MANIFEST.filter((e) => e.only !== undefined)];
 }
 
+// Every `src/*` augmentation bound to a kind-restricted namespace carries its
+// `restrictedTo` marker, and every marker names a namespace its file re-opens.
+// Exported so a test can reach the guard the entry point runs; never called on
+// import, so the dynamic import below stays unreached from an installed package.
+export async function assertSrcAugmentationScoping(
+  packageRoot: string = PACKAGE_ROOT,
+): Promise<number> {
+  // Imported here rather than at module scope: it imports the devDependency
+  // `typescript`, and `resolve` loads this module from an installed package.
+  const { srcAugmentationScopingViolations } = await import("./augmentation-namespaces");
+  const files = loadSrcAugmentations(packageRoot);
+  const violations = srcAugmentationScopingViolations(
+    files,
+    RESTRICTED_SRC_AUGMENTATIONS,
+    RESTRICTED_NAMESPACES,
+  );
+  if (violations.length > 0) {
+    throw new Error(`src augmentation scoping violations:\n${violations.join("\n")}`);
+  }
+  return files.length;
+}
+
 if (import.meta.main) {
+  // Ordering contract: `regen-entrypoint.test.ts` reads this line's prefix to
+  // prove the guard runs before the first write. The count comes from the guard's
+  // own return value so the marker cannot be printed without a completed guard
+  // run — do not simplify it back to `SRC_AUGMENTATION_MODULES.length`, which
+  // would let the guard be deleted or reordered with the line still intact.
+  const checked = await assertSrcAugmentationScoping();
+  console.log(`src augmentation scoping checked: ${checked} file(s)`);
+
   const generated = resolve(import.meta.dir, "..", "generated");
   mkdirSync(resolve(generated, "editor-vm"), { recursive: true });
   for (const entry of [
@@ -752,6 +812,21 @@ if (import.meta.main) {
   writeFileSync(messagesOut, generateBuiltinMessagesDeclaration(MESSAGES_MANIFEST));
   console.log(`wrote ${messagesOut}`);
 
+  // Imported here rather than at module scope: its fixtures are not published,
+  // and `resolve` loads this module from an installed package.
+  const { EXTENSION_GOLDENS_DIR, EXTENSION_GOLDEN_MANIFEST } = await import("./extension-goldens");
+  const goldens = resolve(PACKAGE_ROOT, EXTENSION_GOLDENS_DIR);
+  mkdirSync(goldens, { recursive: true });
+  for (const entry of EXTENSION_GOLDEN_MANIFEST) {
+    const { contents, dropped } = generateModuleDeclaration(entry);
+    if (dropped.length > 0) {
+      console.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
+    }
+    const out = resolve(goldens, entry.outFile);
+    writeFileSync(out, contents);
+    console.log(`wrote ${out}`);
+  }
+
   // 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.
@@ -778,7 +853,14 @@ if (import.meta.main) {
   for (const target of versionedTargets) {
     const indexOut = resolve(versionDirOf(target.id), "index.d.ts");
     mkdirSync(dirname(indexOut), { recursive: true });
-    writeFileSync(indexOut, generateVersionIndex(target.id));
+    writeFileSync(
+      indexOut,
+      generateVersionIndex(
+        target.id,
+        VERSIONED_MODULE_MANIFEST,
+        versionSrcAugmentationImports(target),
+      ),
+    );
     console.log(`wrote ${indexOut}`);
 
     const editorKinds = targetKindManifest(target).filter((entry) => entry.only !== undefined);