@strategicprojects/rpic 0.6.1 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@ import * as rpic from '@strategicprojects/rpic';
 
 await rpic.ready();                       // browser: wasm fetched automatically
 
-const { svg, animations, diagnostics, warnings } = rpic.compile('box "A"; arrow; box "B"');
+const { svg, animations, diagnostics, warnings, objects } = rpic.compile('box "A"; arrow; box "B"');
 document.querySelector('#stage').innerHTML = svg;
 
 // animate with GSAP:
@@ -25,7 +25,7 @@ rpic.renderSvg('A:(0,0); B:(2,0)\nresistor(A,B)', { circuits: true });
 ```js
 import { readFileSync } from 'node:fs';
 import * as rpic from '@strategicprojects/rpic';
-await rpic.ready(readFileSync(new URL('./node_modules/rpic/pkg/rpic_wasm_bg.wasm', import.meta.url)));
+await rpic.ready(readFileSync(new URL('./node_modules/@strategicprojects/rpic/pkg/rpic_wasm_bg.wasm', import.meta.url)));
 console.log(rpic.renderSvg('box "hi"'));
 ```
 
@@ -38,20 +38,21 @@ data) that is only fetched when you ask for it:
 
 ```js
 await rpic.ready(undefined, { math: true }); // browser: fetches pkg/rpic_wasm_math_bg.wasm
-rpic.renderSvg('box "$-\\\\frac{T}{2}$" fit', { texlabels: true });
+rpic.renderSvg('box "$-\\frac{T}{2}$" fit', { texlabels: true });
 ```
 
 Apps can keep the fast path untouched and lazy-load math only when the source
-contains `$…$`. The build choice is fixed by the first `ready()` call. In
-Node, pass the math artifact's bytes:
+contains `$…$`. The build choice is fixed by the first `ready()` call; a later
+call that asks for the other build rejects instead of silently reusing the
+first build. In Node, pass the math artifact's bytes:
 `ready(readFileSync(new URL('…/pkg/rpic_wasm_math_bg.wasm', import.meta.url)), { math: true })`.
 
 ## API
 
 | Function | Description |
 |----------|-------------|
-| `ready(wasmInput?, {math?})` | Initialize WASM. Browser: no arg. Node: pass `.wasm` bytes/URL. `math: true` loads the math-enabled build. |
-| `compile(src, {circuits?, texlabels?})` | → `{ svg, animations, diagnostics, warnings }` (throws on a pic error with `errorInfo`). |
+| `ready(wasmInput?, {math?})` | Initialize WASM. Browser: no arg. Node: pass `.wasm` bytes/URL. `math: true` loads the math-enabled build; conflicting later calls reject. |
+| `compile(src, {circuits?, texlabels?})` | → `{ svg, animations, diagnostics, warnings, objects }` (throws on a pic error with `errorInfo`). |
 | `renderSvg(src, {circuits?, texlabels?})` | → SVG string. |
 | `animate(root, animations, gsap)` | Build/play a GSAP timeline (`draw`/`fade`/`pop`). Browser only. |
 

package/index.d.ts

@@ -26,6 +26,22 @@ export interface Diagnostic {
   hint: string | null;
 }
 
+export interface ObjectGeometry {
+  /** matches the shape's `<g id="sN">` group in the SVG */
+  id: string;
+  /** "box" | "circle" | "ellipse" | "path" | "spline" | "arc" | "brace" | "text" */
+  kind: string;
+  /** bounds in SVG user units (the viewBox space); `null` for invisible shapes */
+  bbox: { x: number; y: number; w: number; h: number } | null;
+  /** 1-based source position of the statement that drew it, when known */
+  line?: number;
+  col?: number;
+  /** exclusive end column of the statement's leading token */
+  end_col?: number;
+  /** absent = your own input; a `copy` include name or `"circuits"` otherwise */
+  file?: string;
+}
+
 export interface Bundle {
   svg: string;
   animations: Anim[];
@@ -33,6 +49,8 @@ export interface Bundle {
   diagnostics: string[];
   /** non-fatal compiler warnings for accepted but suspicious input */
   warnings: Diagnostic[];
+  /** per-object geometry, index-aligned with the `<g id="sN">` groups */
+  objects: ObjectGeometry[];
 }
 
 export interface CompileError extends Error {
@@ -59,22 +77,23 @@ export interface ReadyOptions {
    * Load the math-enabled wasm build (`pkg/rpic_wasm_math_bg.wasm`), which
    * bundles the RaTeX renderer so `texlabels` sources typeset `$…$` labels.
    * The heavier artifact is only fetched when requested; the choice is fixed
-   * by the first `ready()` call. In Node, pass the math wasm bytes as
-   * `wasmInput`.
+   * by the first `ready()` call, and conflicting later calls reject. In Node,
+   * pass the math wasm bytes as `wasmInput`.
    */
   math?: boolean;
 }
 
 /**
  * Initialize the WebAssembly module. In the browser call with no argument; in
- * Node pass the `.wasm` bytes or a file URL.
+ * Node pass the `.wasm` bytes or a file URL. Idempotent while pending or
+ * after success; a *failed* init clears the slot so `ready()` can be retried.
  */
 export function ready(
   wasmInput?: BufferSource | URL | string,
   opts?: ReadyOptions
 ): Promise<void>;
 
-/** Compile pic source into `{ svg, animations, diagnostics, warnings }`. Throws on a pic error. */
+/** Compile pic source into `{ svg, animations, diagnostics, warnings, objects }`. Throws on a pic error. */
 export function compile(src: string, opts?: CompileOptions): Bundle;
 
 /** Compile and return only the SVG string. */

package/index.js

@@ -7,6 +7,7 @@ import * as leanModule from './pkg/rpic_wasm.js';
 
 let initPromise = null;
 let wasm = null; // the initialized glue module (lean or math)
+let initMath = null;
 
 /**
  * Initialize the WebAssembly module (idempotent; concurrent calls share one
@@ -16,18 +17,42 @@ let wasm = null; // the initialized glue module (lean or math)
  * Pass `{ math: true }` to load the math-enabled build instead: it bundles
  * the RaTeX renderer so `texlabels` sources typeset `$…$` labels exactly like
  * the native CLI. The math glue + wasm are only fetched when requested, so
- * the lean fast path stays untouched. The choice is fixed by the first call;
- * in Node, pass the bytes of `pkg/rpic_wasm_math_bg.wasm` along with it.
+ * the lean fast path stays untouched. The choice is fixed by the first
+ * successful (or in-flight) call; later calls asking for the other build
+ * reject. A *failed* init (bad bytes, fetch error) clears the slot so
+ * `ready()` can be retried. In Node, pass the bytes of
+ * `pkg/rpic_wasm_math_bg.wasm` along with it.
  */
 export function ready(wasmInput, opts = {}) {
-  if (!initPromise) {
-    initPromise = (
-      opts.math ? import('./pkg/rpic_wasm_math.js') : Promise.resolve(leanModule)
-    ).then(async (mod) => {
+  const wantsMath = !!opts.math;
+  if (initPromise) {
+    if (initMath !== wantsMath) {
+      const current = initMath ? 'math-enabled' : 'lean';
+      const requested = wantsMath ? 'math-enabled' : 'lean';
+      return Promise.reject(
+        new Error(`rpic: ready() already initialized the ${current} build; cannot switch to ${requested}`)
+      );
+    }
+    return initPromise;
+  }
+  initMath = wantsMath;
+  const attempt = (
+    wantsMath ? import('./pkg/rpic_wasm_math.js') : Promise.resolve(leanModule)
+  )
+    .then(async (mod) => {
       await mod.default(wasmInput === undefined ? undefined : { module_or_path: wasmInput });
       wasm = mod;
+    })
+    .catch((e) => {
+      // a settled rejection must not poison future calls — clear the slot
+      // (only if it is still ours) so the next ready() starts fresh
+      if (initPromise === attempt) {
+        initPromise = null;
+        initMath = null;
+      }
+      throw e;
     });
-  }
+  initPromise = attempt;
   return initPromise;
 }
 
@@ -38,7 +63,7 @@ function ensure() {
 }
 
 /**
- * Compile pic source into `{ svg, animations, diagnostics, warnings }` (throws on a pic error).
+ * Compile pic source into `{ svg, animations, diagnostics, warnings, objects }` (throws on a pic error).
  * @param {string} src
  * @param {{circuits?: boolean, texlabels?: boolean}} [opts]
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strategicprojects/rpic",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "The pic graphics language compiled to SVG with animation manifests, via WebAssembly. Browser + Node.",
   "type": "module",
   "main": "./index.js",