@strategicprojects/rpic 0.11.3 → 0.12.0

package/index.d.ts

@@ -43,6 +43,95 @@ export interface ObjectGeometry {
   file?: string;
 }
 
+/** One subpath of a scene item: a cubic Bézier chain or a polyline. */
+export interface ScenePath {
+  closed?: true;
+  /** cubic form: start point + `[c1, c2, end]` triples */
+  start?: [number, number];
+  cubics?: [[number, number], [number, number], [number, number]][];
+  /** polyline form (inherently straight, or `flatten`ed) */
+  points?: [number, number][];
+}
+
+export interface SceneItem {
+  /** `"s<N>"` — matches the SVG's `<g id>` — or `"blk<N>"` for blocks */
+  id: string;
+  kind:
+    | 'box' | 'circle' | 'ellipse' | 'arc' | 'line' | 'arrow'
+    | 'spline' | 'text' | 'dot' | 'brace' | 'block';
+  /** draw-order index (dense over shape items; absent on blocks) */
+  z?: number;
+  label?: string;
+  /** enclosing block item ids, outermost first */
+  block?: string[];
+  class?: string;
+  link?: string;
+  /** the item paints nothing (`move`, invisible helpers) */
+  hidden?: true;
+  at?: [number, number];
+  w?: number;
+  h?: number;
+  r?: number;
+  rad?: number;
+  points?: [number, number][];
+  closed?: true;
+  paths?: ScenePath[];
+  fillPaths?: ScenePath[];
+  fillPoints?: [number, number][];
+  heads?: {
+    at: 'start' | 'end';
+    filled: boolean;
+    points?: [number, number][];
+    path?: ScenePath;
+  }[];
+  stroke?: {
+    color: string;
+    /** points */
+    width: number;
+    dash?: { kind: 'dashed' | 'dotted'; len?: number; gap?: number };
+  };
+  fill?: {
+    color?: string;
+    gradient?: { angle: number; stops: { offset: number; color: string }[] };
+    hatch?: { angle: number; spacing: number; width: number; color: string; cross: boolean };
+  };
+  opacity?: number;
+  text?: {
+    text: string;
+    /** the line's baseline anchor point (see docs/scene.md §5) */
+    at: [number, number];
+    anchor: 'c' | 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+    font: { size: number; family?: string; bold?: true; italic?: true };
+    rotation?: number;
+    math?: { width: number; height: number; depth: number };
+    outline?: string;
+  }[];
+  /** block items: the child item ids */
+  items?: string[];
+}
+
+/**
+ * The device-independent resolved draw list (docs/scene.md). Coordinates in
+ * inches, y-up; curves as cubic Béziers; style as descriptors.
+ */
+export interface Scene {
+  /** format version (currently 1) */
+  scene: number;
+  units: 'in';
+  y_up: true;
+  canvas: {
+    w: number;
+    h: number;
+    margin: { top: number; right: number; bottom: number; left: number };
+    /** where the pic origin sits, from the canvas lower-left corner */
+    origin: [number, number];
+  };
+  source?: string;
+  /** final values of every variable (user + pic built-ins) */
+  vars: Record<string, number>;
+  items: SceneItem[];
+}
+
 export interface Bundle {
   svg: string;
   animations: Anim[];
@@ -59,6 +148,8 @@ export interface Bundle {
    * the timeline on scroll rather than autoplay. Present only when set.
    */
   scroll?: boolean;
+  /** the resolved draw list; present only when compiled with `scene: true` */
+  scene?: Scene;
 }
 
 export interface CompileError extends Error {
@@ -78,6 +169,12 @@ export interface CompileOptions {
    * labels fall back to literal text plus a diagnostic.
    */
   texlabels?: boolean;
+  /** also compute the device-independent `scene` draw list (docs/scene.md) */
+  scene?: boolean;
+  /** scene: deliver curves as polylines within this tolerance (inches); implies `scene` */
+  flatten?: number;
+  /** scene: embed typeset math as SVG glyph fragments (`outline` keys) */
+  outline?: boolean;
 }
 
 export interface ReadyOptions {

package/index.js

@@ -66,16 +66,26 @@ function ensure() {
  * Compile pic source into `{ svg, animations, diagnostics, warnings, objects }`
  * (throws on a pic error). A top-level `scroll: true` is present when the source
  * used `animate scroll` — a hint to scrub the timeline on scroll (see `animate`).
+ *
+ * Pass `scene: true` for the device-independent resolved draw list as a
+ * `scene` key (see docs/scene.md; versioned, y-up inches, cubic curves);
+ * `flatten` (inches) delivers its curves as polylines instead, and
+ * `outline` embeds typeset math as SVG glyph fragments.
  * @param {string} src
- * @param {{circuits?: boolean, texlabels?: boolean}} [opts]
+ * @param {{circuits?: boolean, texlabels?: boolean, scene?: boolean, flatten?: number, outline?: boolean}} [opts]
  */
 export function compile(src, opts = {}) {
   ensure();
-  const json = opts.texlabels
-    ? wasm.compile_with(src, !!opts.circuits, true)
-    : opts.circuits
-      ? wasm.compile_circuits(src)
-      : wasm.compile(src);
+  if (opts.flatten !== undefined && !(Number.isFinite(opts.flatten) && opts.flatten > 0)) {
+    throw new Error('rpic: flatten must be a positive finite tolerance in inches');
+  }
+  const json = opts.scene || opts.flatten !== undefined
+    ? wasm.compile_scene(src, !!opts.circuits, !!opts.texlabels, opts.flatten, !!opts.outline)
+    : opts.texlabels
+      ? wasm.compile_with(src, !!opts.circuits, true)
+      : opts.circuits
+        ? wasm.compile_circuits(src)
+        : wasm.compile(src);
   const out = JSON.parse(json);
   if (out.error) {
     const err = new Error(out.error);

package/package.json

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

package/pkg/rpic_wasm.d.ts

@@ -14,6 +14,14 @@ export function compile(src: string): string;
  */
 export function compile_circuits(src: string): string;
 
+/**
+ * Like [`compile_with`], but the bundle also carries the device-independent
+ * `scene` draw list (docs/scene.md); `flatten` (inches) delivers curves as
+ * polylines. The plain entry points above stay byte-identical — the scene is
+ * computed only here.
+ */
+export function compile_scene(src: string, circuits: boolean, texlabels: boolean, flatten: number | null | undefined, outline: boolean): string;
+
 /**
  * Like [`compile`], with options: `circuits` loads the circuit-element
  * library; `texlabels` sets `texlabels = 1` so `$…$` labels are typeset as
@@ -30,6 +38,7 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly compile: (a: number, b: number) => [number, number];
     readonly compile_circuits: (a: number, b: number) => [number, number];
+    readonly compile_scene: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly compile_with: (a: number, b: number, c: number, d: number) => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;

package/pkg/rpic_wasm.js

@@ -43,6 +43,33 @@ export function compile_circuits(src) {
     }
 }
 
+/**
+ * Like [`compile_with`], but the bundle also carries the device-independent
+ * `scene` draw list (docs/scene.md); `flatten` (inches) delivers curves as
+ * polylines. The plain entry points above stay byte-identical — the scene is
+ * computed only here.
+ * @param {string} src
+ * @param {boolean} circuits
+ * @param {boolean} texlabels
+ * @param {number | null | undefined} flatten
+ * @param {boolean} outline
+ * @returns {string}
+ */
+export function compile_scene(src, circuits, texlabels, flatten, outline) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(src, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.compile_scene(ptr0, len0, circuits, texlabels, !isLikeNone(flatten), isLikeNone(flatten) ? 0 : flatten, outline);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * Like [`compile`], with options: `circuits` loads the circuit-element
  * library; `texlabels` sets `texlabels = 1` so `$…$` labels are typeset as
@@ -100,6 +127,10 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/pkg/rpic_wasm_bg.wasm.d.ts

@@ -3,6 +3,7 @@
 export const memory: WebAssembly.Memory;
 export const compile: (a: number, b: number) => [number, number];
 export const compile_circuits: (a: number, b: number) => [number, number];
+export const compile_scene: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
 export const compile_with: (a: number, b: number, c: number, d: number) => [number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;

package/pkg/rpic_wasm_math.d.ts

@@ -14,6 +14,14 @@ export function compile(src: string): string;
  */
 export function compile_circuits(src: string): string;
 
+/**
+ * Like [`compile_with`], but the bundle also carries the device-independent
+ * `scene` draw list (docs/scene.md); `flatten` (inches) delivers curves as
+ * polylines. The plain entry points above stay byte-identical — the scene is
+ * computed only here.
+ */
+export function compile_scene(src: string, circuits: boolean, texlabels: boolean, flatten: number | null | undefined, outline: boolean): string;
+
 /**
  * Like [`compile`], with options: `circuits` loads the circuit-element
  * library; `texlabels` sets `texlabels = 1` so `$…$` labels are typeset as
@@ -38,6 +46,7 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly compile: (a: number, b: number) => [number, number];
     readonly compile_circuits: (a: number, b: number) => [number, number];
+    readonly compile_scene: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly compile_with: (a: number, b: number, c: number, d: number) => [number, number];
     readonly init_math: () => void;
     readonly __wbindgen_externrefs: WebAssembly.Table;

package/pkg/rpic_wasm_math.js

@@ -43,6 +43,33 @@ export function compile_circuits(src) {
     }
 }
 
+/**
+ * Like [`compile_with`], but the bundle also carries the device-independent
+ * `scene` draw list (docs/scene.md); `flatten` (inches) delivers curves as
+ * polylines. The plain entry points above stay byte-identical — the scene is
+ * computed only here.
+ * @param {string} src
+ * @param {boolean} circuits
+ * @param {boolean} texlabels
+ * @param {number | null | undefined} flatten
+ * @param {boolean} outline
+ * @returns {string}
+ */
+export function compile_scene(src, circuits, texlabels, flatten, outline) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(src, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.compile_scene(ptr0, len0, circuits, texlabels, !isLikeNone(flatten), isLikeNone(flatten) ? 0 : flatten, outline);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * Like [`compile`], with options: `circuits` loads the circuit-element
  * library; `texlabels` sets `texlabels = 1` so `$…$` labels are typeset as
@@ -113,6 +140,10 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/pkg/rpic_wasm_math_bg.wasm.d.ts

@@ -3,6 +3,7 @@
 export const memory: WebAssembly.Memory;
 export const compile: (a: number, b: number) => [number, number];
 export const compile_circuits: (a: number, b: number) => [number, number];
+export const compile_scene: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
 export const compile_with: (a: number, b: number, c: number, d: number) => [number, number];
 export const init_math: () => void;
 export const __wbindgen_externrefs: WebAssembly.Table;