@tensor-cad/engine 0.1.2 → 0.1.4

package/node.d.ts

@@ -6,15 +6,28 @@
  * singleton the way the editor does: one engine per process, loaded before the
  * first command runs.
  */
-import { type Engine } from "./index.js";
+import { type Engine, type LoadOptions } from "./index.js";
 import "../vendor/wasm_exec.js";
 /**
  * Loads the engine, once per process.
  *
  * A missing module is the one failure worth naming precisely: it means the
  * repository was cloned but not built, and the fix is one command.
+ *
+ * ## Being handed the module instead of finding it
+ *
+ * `options.wasm` skips the search. That is not a convenience — it is the only
+ * way this entry point works in a Worker, where there is no filesystem to read
+ * and the module arrives already compiled from the bundler.
+ *
+ * It matters because of what else lives here: the free functions below share
+ * *this* singleton, and the MCP tools are written against them. A host that
+ * loaded its own engine through `createEngine` would have two, and the tools
+ * would find the one nobody filled — "the engine is not loaded yet", moments
+ * after loading it. So a host with its own module gives it to this loader
+ * rather than keeping it.
  */
-export declare function loadEngine(): Promise<Engine>;
+export declare function loadEngine(options?: LoadOptions): Promise<Engine>;
 /** The engine. Throws if something asked before the load finished. */
 export declare function engine(): Engine;
 export * from "./index.js";

package/node.js

@@ -1371,9 +1371,14 @@ function modulePaths() {
   const here = dirname(fileURLToPath(import.meta.url));
   return [join(here, "tensorcad.wasm"), join(here, "..", "wasm", "tensorcad.wasm")];
 }
-async function loadEngine() {
+async function loadEngine(options) {
   if (loaded)
     return loaded;
+  if (options?.wasm !== undefined) {
+    loaded = await createEngine(options);
+    publish(loaded);
+    return loaded;
+  }
   const paths = modulePaths();
   let bytes = null;
   for (const path of paths) {
@@ -1387,12 +1392,15 @@ async function loadEngine() {
     throw new EngineError(`The analysis engine is not built (looked in ${paths.join(" and ")}). Run: bun run build:wasm`);
   }
   loaded = await createEngine({ wasm: bytes });
-  PRESET_NAMES.push(...loaded.presets());
-  HARDWARE.push(...loaded.hardware());
-  for (const entry of loaded.blocks.builtInEntries)
-    CATALOG[entry.type] = entry;
+  publish(loaded);
   return loaded;
 }
+function publish(engine) {
+  PRESET_NAMES.push(...engine.presets());
+  HARDWARE.push(...engine.hardware());
+  for (const entry of engine.blocks.builtInEntries)
+    CATALOG[entry.type] = entry;
+}
 function engine() {
   if (!loaded)
     throw new EngineError("The engine is not loaded yet; await loadEngine() first.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensor-cad/engine",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The TensorCAD analysis engine, compiled from Go to WebAssembly, with its TypeScript client",
   "type": "module",
   "main": "./index.js",

package/types.d.ts

@@ -170,12 +170,27 @@ export interface PortSpec {
     dtype?: string;
     /** A port that may legitimately dangle. */
     optional?: boolean;
+    /**
+     * What the tensor carries, as a *kind* rather than a width: "real" for
+     * anything a matmul can multiply, "int" for an index, "bool" for a mask,
+     * "inherit" to take it from whatever arrives. Which real type — fp32,
+     * bf16, fp8 — is a condition of the run and belongs to the operating
+     * point (invariant 8), not to the block.
+     */
     /** "flow" or "side": which edge of the symbol a wire leaves by. */
     anchor?: "flow" | "side";
     showName?: boolean;
     doc?: string;
 }
 export interface BlockDocs {
+    /**
+     * What a drawing calls this block: a short noun phrase in the words a
+     * published figure would use, where `type` is the identifier the engine
+     * dispatches on and a path is written with. Both are kept — the identifier is
+     * what an MCP call names, and a reader who found a block by its drawing then
+     * has to type it.
+     */
+    name?: string;
     summary?: string;
     formula?: string;
     refs?: string[];