@needle-tools/engine 5.1.0-alpha.1 → 5.1.0-canary.0d9f44e

package/plugins/dts-generator/index.js

@@ -0,0 +1,36 @@
+// @ts-check
+/**
+ * Needle Engine — HTML binding DTS generator
+ *
+ * Scans all GLB/glTF files in the project's assets directory, extracts
+ * NEEDLE_components data, and emits a `needle-bindings.d.ts` virtual-module
+ * declaration so that TypeScript can type-check HTML ↔ 3D component bindings.
+ *
+ * Typical generated output:
+ *
+ *   declare module "needle-bindings" {
+ *     interface SceneData {
+ *       Sphere: {
+ *         MyBall: { speed: number; label: string; };
+ *       };
+ *     }
+ *   }
+ *
+ * How component field types are resolved:
+ *   - For built-in Needle Engine components, types are read from
+ *     `components.needle.json` which lists only @serializable fields with
+ *     their proper TypeScript types.
+ *   - For user-defined components (not in the manifest), types are inferred
+ *     from the JSON value in the GLB (number/string/boolean → typed, else → unknown).
+ *   - Known Three.js types (Color, Vector3, Object3D, …) are emitted as
+ *     `import("three").TypeName` and known Needle types (RGBAColor, AssetReference, …)
+ *     as `import("@needle-tools/engine").TypeName`.
+ *   - Truly unknown types fall back to `unknown`.
+ */
+
+export { resolveEntrypointGlbs, collectSceneFiles } from './glb.discovery.js';
+export { readGlbJsonChunk, readGltfJsonFile, readRemoteGlbJsonChunk } from './glb.reader.js';
+export { extractComponentBindings, sanitizeNodeName, inferNodeThreeType, inferTsType } from './glb.extractor.js';
+export { scanBindings } from './dts.scan.js';
+export { generateDts, generateHtmlCustomData } from './dts.codegen.js';
+export { generateBindingsDts } from './dts.writer.js';

package/plugins/dts-generator/manifest.types.js

@@ -0,0 +1,174 @@
+// @ts-check
+/**
+ * Type tables and components.needle.json manifest loader.
+ *
+ * Knows about primitive TS types, known Three.js types, known Needle Engine
+ * types, and how to resolve field types from the manifest.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Primitive TS type strings that can safely appear in an ambient declaration. */
+export const PRIMITIVE_TYPES = new Set(["number", "string", "boolean"]);
+
+/**
+ * Known Three.js types → import("three").TypeName
+ * @type {Record<string, string>}
+ */
+export const THREE_TYPES = {
+    Color: `import("three").Color`,
+    ColorRepresentation: `import("three").ColorRepresentation`,
+    Euler: `import("three").Euler`,
+    Texture: `import("three").Texture`,
+    // Materials
+    Material: `import("three").Material`,
+    MeshStandardMaterial: `import("three").MeshStandardMaterial`,
+    // Objects
+    Object3D: `import("three").Object3D`,
+    Mesh: `import("three").Mesh`,
+    SkinnedMesh: `import("three").SkinnedMesh`,
+    // Other
+    Vector2: `import("three").Vector2`,
+    Vector3: `import("three").Vector3`,
+    Vector4: `import("three").Vector4`,
+    Matrix3: `import("three").Matrix3`,
+    Matrix4: `import("three").Matrix4`,
+    Quaternion: `import("three").Quaternion`,
+    // Animation
+    AnimationClip: `import("three").AnimationClip`,
+    AnimationMixer: `import("three").AnimationMixer`,
+};
+
+/**
+ * Known Needle Engine types → import("@needle-tools/engine").TypeName
+ * @type {Record<string, string>}
+ */
+export const NEEDLE_TYPES = {
+    AssetReference: `import("@needle-tools/engine").AssetReference`,
+    EventList: `import("@needle-tools/engine").EventList`,
+    GameObject: `import("@needle-tools/engine").GameObject`,
+    LookAtConstraint: `import("@needle-tools/engine").LookAtConstraint`,
+    RGBAColor: `import("@needle-tools/engine").RGBAColor`,
+    RenderTexture: `import("@needle-tools/engine").RenderTexture`,
+    Renderer: `import("@needle-tools/engine").Renderer`,
+    Rigidbody: `import("@needle-tools/engine").Rigidbody`,
+    Sprite: `import("@needle-tools/engine").Sprite`,
+    Vec2: `import("@needle-tools/engine").Vec2`,
+};
+
+/**
+ * Map a single non-array, non-primitive type token to its TS representation.
+ * Returns null if unknown.
+ * @param {string} token
+ * @returns {string | null}
+ */
+function mapKnownType(token) {
+    if (token in THREE_TYPES) return THREE_TYPES[token];
+    if (token in NEEDLE_TYPES) return NEEDLE_TYPES[token];
+    return null;
+}
+
+/**
+ * Convert a manifest type string to a safe ambient TS type.
+ * Primitives and known Three.js/Needle types are resolved precisely.
+ * For unknown types on a manifest component, falls back to
+ * `import("@needle-tools/engine").ComponentName["fieldName"]`.
+ * Truly unresolvable types → "unknown".
+ *
+ * @param {string} typeStr
+ * @param {string} [componentName]  The manifest component class name (enables indexed-access fallback)
+ * @param {string} [fieldName]      The field name on that component
+ * @returns {string}
+ */
+export function manifestTypeToTs(typeStr, componentName, fieldName) {
+    const parts = typeStr.split(" | ").map(p => p.trim());
+    const safeParts = parts.map(p => {
+        if (p === "undefined" || p === "null") return p;
+        const arrayMatch = p.match(/^(number|string|boolean)\[\]$/);
+        if (arrayMatch) return p;
+        if (PRIMITIVE_TYPES.has(p)) return p;
+        const arrayTypeMatch = p.match(/^(\w+)\[\]$/);
+        if (arrayTypeMatch) {
+            const base = arrayTypeMatch[1];
+            const mapped = mapKnownType(base);
+            if (mapped) return `${mapped}[]`;
+        }
+        const known = mapKnownType(p);
+        if (known) return known;
+        return null;
+    });
+    if (safeParts.every(p => p !== null)) {
+        return /** @type {string[]} */ (safeParts).join(" | ");
+    }
+    if (componentName && fieldName) {
+        return `import("@needle-tools/engine").${componentName}["${fieldName}"]`;
+    }
+    return "unknown";
+}
+
+/**
+ * Load components.needle.json and build a lookup:
+ *   componentName → Map<fieldName, tsType>
+ * Inherited fields are flattened (inheritedFrom chain is resolved).
+ *
+ * @returns {Map<string, Map<string, string>>}
+ */
+export function loadComponentsManifest() {
+    /** @type {Map<string, Map<string, string>>} */
+    const manifest = new Map();
+    const manifestPath = join(__dirname, "../../components.needle.json");
+    if (!existsSync(manifestPath)) return manifest;
+    try {
+        /** @type {Array<{name: string, inheritedFrom?: string, children?: Array<{name: string, kind: string, type: string}>}>} */
+        const entries = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+        /** @type {Map<string, Map<string, string>>} */
+        const ownFields = new Map();
+        /** @type {Map<string, string>} */
+        const inheritedFrom = new Map();
+        for (const entry of entries) {
+            if (!entry.name) continue;
+            inheritedFrom.set(entry.name, entry.inheritedFrom || "");
+            /** @type {Map<string, string>} */
+            const fields = new Map();
+            if (Array.isArray(entry.children)) {
+                for (const child of entry.children) {
+                    if (child.kind === "property" && child.name && child.type) {
+                        fields.set(child.name, manifestTypeToTs(child.type, entry.name, child.name));
+                    }
+                }
+            }
+            ownFields.set(entry.name, fields);
+        }
+
+        /** @param {string} name @returns {Map<string, string>} */
+        function resolveFields(name) {
+            if (manifest.has(name)) return /** @type {Map<string, string>} */ (manifest.get(name));
+            const own = ownFields.get(name) ?? new Map();
+            const parent = inheritedFrom.get(name);
+            if (parent && ownFields.has(parent)) {
+                const parentFields = resolveFields(parent);
+                const merged = new Map([...parentFields, ...own]);
+                manifest.set(name, merged);
+                return merged;
+            }
+            manifest.set(name, own);
+            return own;
+        }
+
+        for (const name of ownFields.keys()) {
+            resolveFields(name);
+        }
+    } catch (e) {
+        console.warn("[needle:dts-generator] Failed to load components.needle.json:", (/** @type {any} */ (e))?.message ?? e);
+    }
+    return manifest;
+}
+
+/** @type {Map<string, Map<string, string>>} */
+export const componentsManifest = loadComponentsManifest();

package/plugins/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./needleConfig.js";
 export * from './userconfig.js';
-export * from "./webmanifest.js";
+export * from "./webmanifest.js";
+export * from "./needle-bindings.js";

package/plugins/types/needle-bindings.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ambient module declaration for `needle-bindings`.
+ *
+ * `SceneData` is keyed by GLB friendly name, then by the node hierarchy:
+ *   ctx.sceneData.Minimal.Camera.$object          // → THREE.Camera
+ *   ctx.sceneData.Minimal.Camera.$components.OrbitControls.autoRotate = true;
+ *   ctx.sceneData.Minimal.UI.Button.$components.Button
+ *
+ * Each node entry has:
+ *   $object      — the Three.js Object3D (typed precisely, e.g. Mesh, Camera, Light)
+ *   $components  — Needle components attached to this node
+ *   [childName]  — child nodes, recursively typed
+ *
+ * When the `needle:dts-generator` Vite plugin is active it writes
+ * `.needle/generated/needle-bindings.gen.d.ts` next to the installed package,
+ * which augments this interface with the actual bindings extracted from
+ * the project's GLB files at build time.
+ */
+
+// Pull in the project-local generated augmentation (written by needle:dts-generator).
+/// <reference path="../../.needle/generated/needle-bindings.gen.d.ts" />
+
+declare module "needle-bindings" {
+    /**
+     * Scene data keyed by GLB friendly name, then by node hierarchy.
+     * Fallback index signature allows unknown names without crashing.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface SceneData {}
+}

package/plugins/types/userconfig.d.ts

@@ -26,10 +26,17 @@ export type userSettings = {
     noCopy?: boolean;
     /** When enabled the needle-engine include directory will be copied */
     copyIncludesFromEngine?: boolean;
-    /** set to false to tree-shake rapier physics engine to the reduce bundle size */
+
+
+    /** Set to `false` to prevent the Rapier physics engine from loading.  
+     * NOTE: by default Needle Engine uses dynamic loading of the Rapier physics engine. This means that the Rapier code is only loaded when a physics component is used in the scene.
+     */
     useRapier?: boolean;
-    /** experimental */
+    /** Set to `false` to prevent postprocessing effects from loading.  
+     * NOTE: by default Needle Engine uses dynamic loading of postprocessing modules. This means that the postprocessing code is only loaded when a postprocessing effect is used in the scene.
+     */
     usePostprocessing?: boolean;
+
     noDependencyWatcher?: boolean;
     /** set to false to suppress editor-sync package installation and connection */
     dontInstallEditor?: boolean;
@@ -169,4 +176,16 @@ export type userSettings = {
 
     /** Set to true to disable the plugin that ensures VSCode workspace settings for custom-elements.json data */
     noCustomElementData?: boolean;
+
+    /**   
+     * Generate Typescript declaration files for references 3D assets in your project.  
+     * These will be available via `context.sceneData` in your code.
+     * @default enabled
+     */
+    dts?: {
+        /** When set to false, disables the generation of TypeScript declaration files. 
+         * @default true
+         */
+        enabled?: boolean;
+    }
 }

package/plugins/vite/asap.js

@@ -22,7 +22,7 @@ export async function needleAsap(command, config, userSettings) {
 
     fixMainTs();
 
-    if (command != "build") {
+    if (command === "serve") {
         return null;
     }
 

package/plugins/vite/dependency-watcher.d.ts

@@ -1,10 +1,10 @@
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | null}
  */
-export function needleDependencyWatcher(command: "build" | "serve", _config: unknown, userSettings: import("../types").userSettings): import("vite").Plugin | null;
+export function needleDependencyWatcher(_command: "build" | "serve" | undefined, _config: unknown, userSettings: import("../types").userSettings): import("vite").Plugin | null;
 export type PackageJson = {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;

package/plugins/vite/dependency-watcher.js

@@ -12,14 +12,12 @@ function log(...msg) {
 }
 
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | null}
  */
-export function needleDependencyWatcher(command, _config, userSettings) {
-    if (command === "build") return null;
-
+export function needleDependencyWatcher(_command, _config, userSettings) {
     if (userSettings?.noDependencyWatcher === true) return null;
 
     const dir = process.cwd();
@@ -28,6 +26,7 @@ export function needleDependencyWatcher(command, _config, userSettings) {
 
     return /** @type {import('vite').Plugin} */ ({
         name: 'needle-dependency-watcher',
+        apply: 'serve',
         /** @param {import('vite').ViteDevServer} server */
         configureServer(server) {
             manageClients(server);

package/plugins/vite/drop.d.ts

@@ -1,7 +1,7 @@
 /** Experimental, allow dropping files from Unity into the running scene.
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types/userconfig.js').userSettings} userSettings
  * @returns {import('vite').Plugin | null | undefined}
  */
-export function needleDrop(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types/userconfig.js").userSettings): import("vite").Plugin | null | undefined;
+export function needleDrop(_command: "build" | "serve" | undefined, config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types/userconfig.js").userSettings): import("vite").Plugin | null | undefined;

package/plugins/vite/drop.js

@@ -7,18 +7,17 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 /** Experimental, allow dropping files from Unity into the running scene.
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types/userconfig.js').userSettings} userSettings
  * @returns {import('vite').Plugin | null | undefined}
  */
-export function needleDrop(command, config, userSettings) {
-    if (command === "build") return;
-    
+export function needleDrop(_command, config, userSettings) {
     if(userSettings.useDrop !== true) return null;
 
     return {
         name: "needle:drop",
+        apply: 'serve',
         config(/** @type {{ server?: { hmr?: { port?: number } } }} */ viteConfig) {
             if(userSettings)
             if (!viteConfig.server) viteConfig.server = {};

package/plugins/vite/dts-generator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {"build" | "serve"} _command  Vite command (unused — runs in both modes)
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} _config
+ * @param {import('../types').userSettings} [_userSettings]
+ * @returns {import('vite').Plugin | null}
+ */
+export function needleDtsGenerator(_command: "build" | "serve", _config: import("../types/needleConfig").needleMeta | null | undefined, _userSettings?: import("../types").userSettings): import("vite").Plugin | null;

package/plugins/vite/dts-generator.js

@@ -0,0 +1,191 @@
+// @ts-check
+/**
+ * Vite plugin: needle:dts-generator
+ *
+ * Thin wrapper around plugins/dts-generator/index.js.
+ * Regenerates `needle-bindings.d.ts` on startup and whenever a .glb / .gltf
+ * file changes in the assets directory.
+ *
+ * The generated file is written to `{codegenDirectory}/needle-bindings.d.ts`
+ * (falls back to `src/generated/needle-bindings.d.ts`).
+ *
+ * Usage — the plugin is already wired into needlePlugins(). To use standalone:
+ *
+ *   import { needleDtsGenerator } from "@needle-tools/engine/plugins/vite/dts-generator.js";
+ *   // in vite.config.js plugins array:
+ *   needleDtsGenerator(command, needleConfig, userSettings)
+ */
+
+import { join, resolve, dirname } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'fs';
+import { tryLoadProjectConfig } from './config.js';
+import { generateBindingsDts } from '../dts-generator/index.js';
+import { needleLog } from './logging.js';
+
+// Two dirs up from plugins/vite/ → package root.
+// Use fileURLToPath so %7E and other URL-encoded characters in the path are decoded correctly.
+// realpathSync follows symlinks so the path is stable even in npm link / monorepo setups.
+import { fileURLToPath } from 'url';
+let _packageRoot = /** @type {string | null} */ (null);
+try {
+    _packageRoot = realpathSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..'));
+} catch (_e) {
+    // If we can't resolve the package root (e.g. unusual install layout), the plugin
+    // will silently skip generation rather than crashing the dev server.
+}
+
+/**
+ * Ensure `.vscode/settings.json` references the generated `needle-html-data.json`
+ * so VS Code provides `data-bind-needle` completions in HTML files automatically.
+ * Only adds the entry if it isn't already present — never overwrites other settings.
+ *
+ * @param {string} projectRoot
+ * @param {string} htmlDataPath  Absolute path to the generated needle-html-data.json
+ */
+function ensureVscodeHtmlCustomData(projectRoot, htmlDataPath) {
+    const vscodeDir = join(projectRoot, ".vscode");
+    const settingsPath = join(vscodeDir, "settings.json");
+
+    // Relative path from project root for portability
+    const relPath = htmlDataPath.replace(projectRoot + "/", "").replace(projectRoot + "\\", "");
+
+    /** @type {Record<string, unknown>} */
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        } catch (_e) { /* malformed JSON — leave settings empty, will add key */ }
+    }
+
+    const key = "html.customData";
+    const existing = Array.isArray(settings[key]) ? /** @type {string[]} */ (settings[key]) : [];
+    if (existing.includes(relPath)) return; // already registered
+
+    settings[key] = [...existing, relPath];
+
+    mkdirSync(vscodeDir, { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+    needleLog("needle:dts-generator", `registered HTML completions in .vscode/settings.json`);
+}
+
+/**
+ * @param {"build" | "serve"} _command  Vite command (unused — runs in both modes)
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} _config
+ * @param {import('../types').userSettings} [_userSettings]
+ * @returns {import('vite').Plugin | null}
+ */
+export function needleDtsGenerator(_command, _config, _userSettings) {
+
+    if(_userSettings?.dts?.enabled === false) {
+        return null;
+    }
+
+    let projectRoot = process.cwd();
+
+    function resolveCodegenDir() {
+        const projectConfig = tryLoadProjectConfig();
+        return projectConfig?.codegenDirectory
+            ? resolve(projectRoot, projectConfig.codegenDirectory)
+            : join(projectRoot, "src", "generated");
+    }
+
+    function resolveOutputPath() {
+        // Write to a .needle dotfolder at the package root.
+        // Not in the `files` allowlist → never npm-published.
+        // ../../.needle/ from plugins/types/ resolves correctly for both
+        // symlinked (js/package~/) and published (node_modules/@needle-tools/engine/) layouts.
+        return join(/** @type {string} */ (_packageRoot), ".needle", "generated", "needle-bindings.gen.d.ts");
+    }
+
+    function resolveAssetsDir() {
+        const projectConfig = tryLoadProjectConfig();
+        return projectConfig?.assetsDirectory
+            ? resolve(projectRoot, projectConfig.assetsDirectory)
+            : join(projectRoot, "assets");
+    }
+
+    /** @type {import('vite').ViteDevServer | undefined} */
+    let devServer;
+
+    /** @type {Promise<void> | null} */
+    let _runInFlight = null;
+
+    function run() {
+        if (_runInFlight) return _runInFlight;
+        _runInFlight = _doRun().finally(() => { _runInFlight = null; });
+        return _runInFlight;
+    }
+
+    async function _doRun() {
+        try {
+            if (!_packageRoot) return;
+            const assetsDir = resolveAssetsDir();
+            const outputPath = resolveOutputPath();
+            const codegenDir = resolveCodegenDir();
+            const count = await generateBindingsDts({ assetsDir, outputPath, projectRoot, codegenDir });
+            // HTML custom data sits next to the generated dts in .needle/generated/
+            const htmlDataPath = join(/** @type {string} */ (_packageRoot), ".needle", "generated", "needle-html-data.json");
+            ensureVscodeHtmlCustomData(projectRoot, htmlDataPath);
+            if (count !== false) {
+                needleLog("needle:dts-generator", `${count} binding(s) → ${outputPath.replace(process.cwd(), ".")}`);
+                if (devServer) {
+                    const hot = devServer.hot ?? devServer.ws;
+                    hot.send({ type: "full-reload", path: "*" });
+                }
+            } else {
+                needleLog("needle:dts-generator", `up-to-date → ${outputPath.replace(process.cwd(), ".")}`);
+            }
+        } catch (err) {
+            needleLog("needle:dts-generator", "Failed: " + (/** @type {any} */ (err)?.message ?? err));
+        }
+    }
+
+    return {
+        name: "needle:dts-generator",
+
+        /** @param {import('vite').ResolvedConfig} config */
+        configResolved(config) {
+            projectRoot = config.root ?? process.cwd();
+        },
+
+        buildStart() {
+            // In serve mode, the configureServer post-hook runs instead.
+            // Only run here for actual builds (no devServer).
+            if (!devServer) return run();
+            return undefined;
+        },
+
+        /** @param {import('vite').ViteDevServer} server */
+        configureServer(server) {
+            devServer = server;
+
+            // Watch assets directory for GLB/glTF changes and regenerate
+            const assetsDir = resolveAssetsDir();
+            server.watcher.add(assetsDir);
+
+            // Also watch files that determine which GLBs are entrypoints
+            const indexHtmlPath = join(projectRoot, "index.html");
+            const genJsPath = join(resolveCodegenDir(), "gen.js");
+            server.watcher.add(indexHtmlPath);
+            server.watcher.add(genJsPath);
+
+            server.watcher.on("change", (file) => {
+                if (
+                    (/\.(glb|gltf)$/i.test(file) && file.startsWith(assetsDir)) ||
+                    file === indexHtmlPath ||
+                    file === genJsPath
+                ) {
+                    run();
+                }
+            });
+            server.watcher.on("add", (file) => {
+                if (/\.(glb|gltf)$/i.test(file) && file.startsWith(assetsDir)) {
+                    run();
+                }
+            });
+
+            // Return post-hook so Vite awaits the initial run before printing "ready"
+            return () => run();
+        },
+    };
+}

package/plugins/vite/index.d.ts

@@ -19,13 +19,20 @@
  *        ],
  *    }
  * ```
- * @param {"build" | "serve"} command
- * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * When used without arguments (e.g. in a SvelteKit `defineConfig({})` plain object),
+ * the command is resolved automatically from Vite's `configResolved` hook.
+ * ```js
+ * // SvelteKit — no command needed:
+ * export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+ * ```
+ * @param {"build" | "serve" | undefined} [command]
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} [config]
  * @param {import('../types/index.js').userSettings} [userSettings]
  * @returns {Promise<import('vite').Plugin[]>}
  */
-export function needlePlugins(command: "build" | "serve", config?: import("../types/needleConfig").needleMeta | null | undefined, userSettings?: import("../types/index.js").userSettings): Promise<import("vite").Plugin[]>;
+export function needlePlugins(command?: "build" | "serve" | undefined, config?: import("../types/needleConfig").needleMeta | null | undefined, userSettings?: import("../types/index.js").userSettings): Promise<import("vite").Plugin[]>;
 export { needleAI } from "./ai.js";
+export { needleDtsGenerator } from "./dts-generator.js";
 export { needleAsap } from "./asap.js";
 export { needleDefines } from "./defines.js";
 export { needleBuildPipeline } from "./build-pipeline.js";

package/plugins/vite/index.js

@@ -1,6 +1,9 @@
 import { needleAI } from "./ai.js";
 export { needleAI } from "./ai.js";
 
+import { needleDtsGenerator } from "./dts-generator.js";
+export { needleDtsGenerator } from "./dts-generator.js";
+
 import { needleAsap } from "./asap.js";
 export { needleAsap } from "./asap.js";
 
@@ -113,12 +116,18 @@ const defaultUserSettings = {
  *        ],
  *    }
  * ```
- * @param {"build" | "serve"} command
- * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * When used without arguments (e.g. in a SvelteKit `defineConfig({})` plain object),
+ * the command is resolved automatically from Vite's `configResolved` hook.
+ * ```js
+ * // SvelteKit — no command needed:
+ * export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+ * ```
+ * @param {"build" | "serve" | undefined} [command]
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} [config]
  * @param {import('../types/index.js').userSettings} [userSettings]
  * @returns {Promise<import('vite').Plugin[]>}
  */
-export async function needlePlugins(command, config = undefined, userSettings = {}) {
+export async function needlePlugins(command = undefined, config = undefined, userSettings = {}) {
 
     if (!config) config = {}
 
@@ -126,6 +135,7 @@ export async function needlePlugins(command, config = undefined, userSettings =
     userSettings = { ...defaultUserSettings, ...userSettings };
 
     const array = [
+        needleDtsGenerator(command, config, userSettings),
         needleAI(command, config, userSettings),
         needleLogger(command, config, userSettings),
         needleDefines(command, config, userSettings),
@@ -164,14 +174,21 @@ export async function needlePlugins(command, config = undefined, userSettings =
     array.push(await editorConnection(command, config, userSettings, array));
     array.push(needleDependencyWatcher(command, config, userSettings));
 
-    // Ensure the process exits on SIGINT (Ctrl+C) since plugin timers/sockets can keep the event loop alive
-    if (command === "serve") {
+    // Ensure the process exits on SIGINT (Ctrl+C) since plugin timers/sockets can keep the event loop alive.
+    // If command is unknown at call time (e.g. SvelteKit plain defineConfig), defer to configResolved.
+    const registerSigint = () => {
         process.on('SIGINT', () => {
-            // Wait a moment to allow plugins to clean up if needed, then exit
-            setTimeout(() => {
-                console.debug('\nGoodbye!');
-                process.exit();
-            }, 1000);
+            setTimeout(() => { console.debug('\nGoodbye!'); process.exit(); }, 1000);
+        });
+    };
+    if (command === "serve") {
+        registerSigint();
+    } else if (command === undefined) {
+        array.push({
+            name: "needle:sigint",
+            configResolved(config) {
+                if (config.command === "serve") registerSigint();
+            }
         });
     }