figureone 1.7.0 → 1.8.0

package/llms-full.txt

@@ -20,6 +20,10 @@ Colors are `[r, g, b, a]` with values 0-1. Default scene is `[-1, -1, 2, 2]` (x,
 | lineWidth | number | | Default line width |
 | length | number | | Default primary dimension |
 | backgroundColor | TypeColor | | Background color |
+| textStyle | `'italic'` \| `'normal'` | `'italic'` | Default equation text style (also settable on FigurePrimitives and Equation) |
+| antialias | boolean | `true` | Enable WebGL anti-aliasing |
+| atlasScale | number | `2` | GL text atlas texture resolution relative to 1:1 pixel mapping |
+| onWebGLUnavailable | () => void | | Callback fired once during construction if no WebGL context is available (figure is still created but renders nothing) |
 
 ### Key Figure Methods
 
@@ -45,6 +49,11 @@ figure.resize();          // Resize after container change
 figure.animateNextFrame(); // Request next animation frame
 figure.isAnimating();     // Check if any animation running
 
+// WebGL context state
+figure.webglAvailable;    // false if no live WebGL context (e.g. context lost)
+figure.notifications.add('contextLost', () => { /* context removed by browser */ });
+figure.notifications.add('contextRestored', () => { /* context returned */ });
+
 // Coordinate transforms
 figure.transformPoint(point, fromSpace, toSpace);
 figure.spaceTransformMatrix(fromSpace, toSpace);
@@ -92,6 +101,7 @@ Path to figure element(s) within a collection. Supports multiple formats:
 | underline | boolean \| object | `false` | Underline options |
 | outline | boolean \| object | `false` | Outline options |
 | render | `'gl'` \| `'2d'` \| `'html'` | `'gl'` | Render target |
+| atlasId | string | | Share a single GL atlas texture across text elements with different sizes (elements with the same `atlasId` reuse one atlas) |
 
 ### OBJ_Texture
 
@@ -119,6 +129,11 @@ Path to figure element(s) within a collection. Supports multiple formats:
 | defaultColor | TypeColor | | Color when undimmed |
 | scenarios | OBJ_Scenarios | | Named presets |
 | scene | Scene \| OBJ_Scene | | Custom scene |
+| isFormIgnored | boolean | `false` | Exclude from equation form changes — skipped by form layout, show/hide, transform/color sets, and `elementMods`, so its user-applied transform, color, and visibility persist across `showForm` / `goToForm` (contributes zero size to layout) |
+| allowSetColor | `'all'` \| `'opacity'` \| `'none'` | `'all'` | Freeze color: `'opacity'` allows only the alpha channel to change; `'none'` blocks all `setColor` |
+| ignoreSetColor | string \| string[] | `[]` | Source label(s) whose tagged `setColor` commands are ignored (e.g. the equation's default `'form'` color cascade), while explicit/untagged commands (`dim`/`undim`, direct `setColor`) are still honored |
+
+These element properties are also settable at runtime; `setColor(color, setDefault?, from?)` takes an optional `from` source label that is matched against `ignoreSetColor`.
 
 ### OBJ_Collection
 
@@ -1252,6 +1267,26 @@ Array: `{ color: [content, [r, g, b, a]] }`
 | color | TypeColor | | Color to apply |
 | fullContentBounds | boolean | `false` | Use full bounds |
 
+#### EQN_Opacity (`opacity`)
+Array: `{ opacity: [content, opacity_value] }`. Wraps a phrase in an opacity multiplier that cascades multiplicatively through nested `opacity` wrappers (outer `0.5` × inner `0.5` = `0.25` on inner content). The cascaded opacity is assigned to each wrapped element whenever the form is shown, overriding externally-set element opacity — set `ignoreOpacity: true` on the form to suppress this and preserve external opacities.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| content | TypeEquationPhrase | | Content |
+| opacity | number | | Opacity multiplier in range `[0, 1]` |
+| fullContentBounds | boolean | `false` | Use full bounds |
+
+#### EQN_Front (`front`) / EQN_Back (`back`)
+Array: `{ front: [content, num] }` / `{ back: [content, num] }`. Reorder a phrase's elements within the equation's draw stack, per-form. All elements in `content` move together as a group, keeping their relative draw order. Applied whenever the form is shown, relative to the equation's natural definition order, so each form deterministically defines its own stacking. The same operations are available as `front` / `back` element mods (e.g. `elementMods: { a: { back: {} } }`).
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| content | TypeEquationPhrase | | Content |
+| num | number | | `front`: places to move forward (positive) or `\|num\|` places behind the front (negative). `back`: places to move back (positive) or `\|num\|` places ahead of the back (negative). With `before`/`after`, it's the offset from the anchor (default `0`). If omitted with no anchor, moves fully to front/back |
+| before | string \| string[] | | Anchor element name(s) — position the group just before (behind) the most-back anchor |
+| after | string \| string[] | | Anchor element name(s) — position the group just after (in front of) the most-front anchor |
+| fullContentBounds | boolean | `false` | Use full bounds |
+
 #### EQN_Container (`container`)
 Array: `{ container: [content, width] }`
 
@@ -1452,10 +1487,17 @@ forms: {
     scale: { elementName: 1.5 },     // Per-element target scales during animation
     fromPrev: { elementName: 'otherElement' }, // Animate from another element's position
     fromNext: { elementName: 'otherElement' }, // Animate from another element's position (reverse)
+    ignoreColor: false,              // true preserves externally-set element colors (suppresses color cascade)
+    ignoreOpacity: false,            // true preserves externally-set element opacities (suppresses opacity cascade)
+    elementMods: {                   // Per-element property mods applied when form shows
+      elementName: { back: {} },     // e.g. front/back reorder mods (see EQN_Front/EQN_Back)
+    },
   },
 }
 ```
 
+Every equation layout function (container, frac, matrix, brac, annotate, color, opacity, front, back, etc.) also accepts an optional `name` property — purely a label with no layout effect, used to address the function's sub-tree via `eqn.getFunctionElements(name)`.
+
 ### Forms and Animation
 
 ```js
@@ -1474,9 +1516,24 @@ const eqn = figure.add({
 });
 
 eqn.showForm('1');
+eqn.showForm('1', false);            // notify=false suppresses the formChanged event for this call
 eqn.goToForm({ form: '2', delay: 1, duration: 1.5, animate: 'move' });
 eqn.nextForm();   // Navigate formSeries
 eqn.prevForm();
+
+// Element lookup within forms
+eqn.getFormElements(formName, includeHidden?);   // All elements in a form
+eqn.getPhraseElements(phrase);                    // All elements in a phrase
+// Elements inside a named layout function (any function tagged with `name`).
+// (name, formName? = current, mode? = 'all', includeHidden? = false).
+// mode 'first' = first match; 'all' = de-duplicated union across all matches.
+eqn.getFunctionElements('myFrac');
+```
+
+`Equation` publishes a `formChanged` notification whenever the displayed form may have changed, with payload `{ phase, form, fromForm?, progress? }`. `phase` is one of: `'showForm'` (form set via `showForm`; suppress with `notify: false`), `'goToFormStart'`, `'goToFormStep'` (per animation frame, with `progress` 0–1; a final step with `progress: 1` precedes the end), `'goToFormEnd'`. `fromForm` is present only on the `goToForm*` phases.
+
+```js
+eqn.notifications.add('formChanged', ({ phase, form, progress }) => { /* drive UI */ });
 ```
 
 ### Phrases (reusable sub-expressions)
@@ -1488,6 +1545,14 @@ eqn.prevForm();
 }
 ```
 
+### LaTeX Parsing
+`Fig.latexToFigureOne(latex)` converts a LaTeX math expression into `{ elements, form }` for use in an equation definition (basic support).
+
+```js
+const { elements, form } = Fig.latexToFigureOne('\\frac{a}{b} = c');
+figure.add({ make: 'equation', elements, forms: { base: form } });
+```
+
 ---
 
 ## 7. Animation System

package/llms.txt

@@ -24,6 +24,8 @@ figure.add({ make: 'triangle', width: 0.5, height: 0.5, color: [1, 0, 0, 1] });
 
 Colors are `[r, g, b, a]` with values 0-1. Coordinates default to a scene of `[-1, -1, 2, 2]` (x, y, width, height). Override with `new Fig.Figure({ scene: [-2, -2, 4, 4] })`.
 
+Other `Fig.Figure` options: `textStyle` (`'italic'` default | `'normal'` — default equation text style), `antialias` (default `true`), `atlasScale` (GL text atlas resolution, default `2`), `onWebGLUnavailable` (callback if no WebGL context). Check `figure.webglAvailable` and subscribe to `contextLost` / `contextRestored` notifications for runtime WebGL context transitions.
+
 ## Core Concepts
 
 - **Figure** — top-level container that manages all elements and rendering
@@ -105,6 +107,9 @@ All elements accept these common options alongside shape-specific ones:
 - `color` — `[r, g, b, a]`
 - `position` — `[x, y]` shorthand for translation
 - `rotation` — rotation in radians
+- `isFormIgnored` — exclude from equation form changes (its transform/color/visibility persist across `showForm`/`goToForm`)
+- `allowSetColor` — `'all'` (default), `'opacity'` (alpha only), or `'none'` to freeze color
+- `ignoreSetColor` — source label(s) whose tagged `setColor` is ignored (e.g. the equation's `'form'` color cascade), while explicit commands still apply
 
 When `options` is used, shape-specific properties go inside it:
 
@@ -256,9 +261,14 @@ Any element type can be created inline in forms using `make`:
 | `prodOf` | `{ prodOf: { symbol, content, from, to } }` | Product |
 | `scale` | `{ scale: [content, scale_factor] }` | Scale content |
 | `color` | `{ color: [content, [r,g,b,a]] }` | Color content |
+| `opacity` | `{ opacity: [content, 0.3] }` | Opacity multiplier (cascades multiplicatively through nesting) |
+| `front` | `{ front: [content, num] }` | Bring content forward in draw stack (per-form); supports `before`/`after` anchors |
+| `back` | `{ back: [content, num] }` | Send content back in draw stack (per-form); supports `before`/`after` anchors |
 | `container` | `{ container: { content, width, ... } }` | Fixed-size container |
 | `lines` | `{ lines: { content: [...], justify } }` | Multi-line layout |
 
+Any layout function also accepts a `name` label to address its elements via `eqn.getFunctionElements(name)`. Form objects accept `ignoreColor` / `ignoreOpacity` to preserve externally-set element color/opacity (suppress the cascade).
+
 ### Symbols
 
 Define symbols in `elements` with `{ symbol: 'type' }`:
@@ -302,9 +312,12 @@ const eqn = figure.add({
 });
 
 eqn.showForm('1');
+eqn.showForm('1', false);   // notify=false suppresses the formChanged event
 eqn.goToForm({ form: '2', delay: 1, duration: 1.5, animate: 'move' });
 ```
 
+Equation publishes a `formChanged` notification with payload `{ phase, form, fromForm?, progress? }`, where `phase` is `'showForm'`, `'goToFormStart'`, `'goToFormStep'` (with `progress` 0–1), or `'goToFormEnd'`. Use `eqn.getFunctionElements(name)` to fetch elements inside a named layout function.
+
 Use `formSeries` to define an ordered list of forms, then navigate with `eqn.nextForm()` and `eqn.prevForm()`.
 
 Use `phrases` to define reusable sub-expressions:
@@ -529,6 +542,10 @@ new Fig.Transform()            // Transform builder
   .scale(sx, sy)
 Fig.round(value, precision)    // Round to N decimal places
 
+// Convert a LaTeX math expression to an equation form (basic support)
+const { elements, form } = Fig.latexToFigureOne('\\frac{a}{b} = c');
+figure.add({ make: 'equation', elements, forms: { base: form } });
+
 // Color format: [r, g, b, a] with values 0 to 1
 // [1, 0, 0, 1] = red, [0, 0, 1, 0.5] = semi-transparent blue
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Draw, animate and interact with shapes, text, plots and equations in Javascript. Create interactive slide shows, and interactive videos.",
   "main": "index.js",
   "types": "types/index.d.ts",

package/types/js/figure/DrawingObjects/GLObject/GLObject.d.ts

@@ -42,6 +42,12 @@ declare class GLObject extends DrawingObject {
         loadColor: TypeColor;
         [key: string]: any;
     } | null;
+    maskTextures: Array<{
+        id: string;
+        src: string;
+        loadColor: TypeColor;
+        uniformName: string;
+    }>;
     attributes: {
         [attributeName: string]: {
             buffer: WebGLBuffer | null;
@@ -85,6 +91,18 @@ declare class GLObject extends DrawingObject {
      * Buffer a texture for the shape to be painted with.
      */
     addTexture(location: string, mapFrom?: Rect, mapTo?: Rect, mapToBuffer?: string, points?: Array<number>, repeat?: boolean, onLoad?: null | (() => void), loadColor?: TypeColor): void;
+    /**
+     * Buffer a mask texture for the `textureMap` color mode. Each call appends a
+     * mask, bound to the next u_mask{i} sampler. Masks share the base texture's
+     * coordinates, so only a source and load color are needed. The default load
+     * color is fully transparent so that, until the mask loads, no region is
+     * recolored and the base texture shows through unchanged.
+     *
+     * An empty `location` registers a transparent placeholder, which keeps the
+     * u_mask{i} indexing aligned with the tint blocks when a caller supplies an
+     * invalid/missing mask in a positional list (the slot becomes a no-op).
+     */
+    addMaskTexture(location?: string, loadColor?: TypeColor): void;
     updateTexture(data: HTMLImageElement): void;
     initTexture(force?: boolean): void;
     createTextureMap(xMinGL?: number, xMaxGL?: number, yMinGL?: number, yMaxGL?: number, xMinTex?: number, xMaxTex?: number, yMinTex?: number, yMaxTex?: number): void;

package/types/js/figure/FigurePrimitives/FigurePrimitiveTypes.d.ts

@@ -224,6 +224,30 @@ export type OBJ_Texture = {
     repeat?: boolean;
     onLoad?: () => void;
 };
+/**
+ * Mask texture used by the `gl` primitive to recolor regions of a base
+ * `texture`. A mask shares the base texture's coordinates, so it must be the
+ * same dimensions and aligned with the base image. Each of a mask's `r`, `g`,
+ * `b` and `a` channels selects a region recolored by an entry of the
+ * primitive's `tints` option.
+ *
+ * Supply a single mask with `mask`, or several with `masks` (an array). Mask `m`
+ * (0-based) uses `tints[4m]`, `tints[4m + 1]`, `tints[4m + 2]` and
+ * `tints[4m + 3]` for its r, g, b and a channels - so each mask adds four
+ * recolorable regions. A single mask costs one extra texture fetch and four
+ * mixes; each additional mask adds one fetch and four mixes.
+ *
+ * @property {string} [src] url of the mask image
+ * @property {TypeColor} [loadColor] color shown while the mask loads
+ * (`[0, 0, 0, 0]` - fully transparent, so nothing is recolored until the mask
+ * has loaded)
+ * @interface
+ * @group Shaders
+ */
+export type OBJ_TextureMask = {
+    src?: string;
+    loadColor?: TypeColor;
+};
 /**
  * Pulse options object
  *
@@ -443,6 +467,12 @@ export type TypeText = 'gl' | '2d';
  * {@link OBJ_FragmentShader} for names of attributes and uniforms used in the
  * shaders, and when they are used.
  *
+ * A texture can be recolored by region using one or more masks (see the mask
+ * examples below):
+ *
+ * ![](./apiassets/gl_mask.png)
+ * ![](./apiassets/gl_mask2.png)
+ *
  * @property {TypeGLPrimitive} [glPrimitive]
  * @property {TypeVertexShader} [vertexShader]
  * @property {TypeFragmentShader} [fragmentShader]
@@ -585,6 +615,46 @@ export type TypeText = 'gl' | '2d';
  *     },
  *   ],
  * });
+ *
+ * @example
+ * // Recolor regions of a texture with a mask. The mask image marks regions to
+ * // recolor in its red, green, blue and alpha channels, which map to tints 0,
+ * // 1, 2 and 3. Unmasked pixels keep the base texture's color.
+ * const p = figure.add({
+ *   make: 'gl',
+ *   vertices: [-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5],
+ *   numVertices: 6,
+ *   texture: {
+ *     src: './base.png',
+ *     coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1],
+ *     loadColor: [0, 0, 0, 0],
+ *   },
+ *   mask: { src: './mask.png' },
+ *   tints: [[1, 0, 0, 1], [0, 0, 1, 1]],
+ * });
+ * // Change the first region's color at runtime
+ * p.custom.setTint(0, [0, 1, 0, 1]);
+ *
+ * @example
+ * // Recolor with two masks. Each mask adds four regions (its r, g, b, a
+ * // channels), so mask 0 uses tints 0-3 and mask 1 uses tints 4-7. Here mask 0
+ * // recolors three circles (tints 0, 1, 2) and mask 1 recolors a bar (tint 4).
+ * figure.add({
+ *   make: 'gl',
+ *   vertices: [-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5],
+ *   numVertices: 6,
+ *   texture: {
+ *     src: './base.png',
+ *     coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1],
+ *     loadColor: [0, 0, 0, 0],
+ *   },
+ *   masks: [{ src: './mask.png' }, { src: './mask1.png' }],
+ *   tints: [
+ *     [1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1], null, // mask 0: circles
+ *     [0.6, 0, 0.8, 1],                                 // mask 1: bar
+ *   ],
+ * });
+ *
  * @interface
  * @group Shaders
  */
@@ -595,6 +665,9 @@ export type OBJ_GenericGL = {
     attributes?: Array<OBJ_GLAttribute>;
     uniforms?: Array<OBJ_GLUniform>;
     texture?: OBJ_Texture;
+    mask?: OBJ_TextureMask;
+    masks?: Array<OBJ_TextureMask>;
+    tints?: Array<TypeColor | null>;
     dimension?: 2 | 3;
     light?: 'directional' | 'point' | null;
     vertices?: OBJ_GLVertexBuffer;

package/types/js/figure/webgl/shaders.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Number of recolorable regions a single mask texture provides in the
+ * `textureMap` color mode - one per channel (r, g, b, a). N masks therefore
+ * define `CHANNELS_PER_MASK * N` tints.
+ * @group Shaders
+ */
+export declare const CHANNELS_PER_MASK = 4;
 /**
  * Options used to compose vertex shader source code.
  *
@@ -53,14 +60,14 @@
  *    to fragment shader used when `light = 'point'`
  *
  * @property {2 | 3} [dimension] (`2`)
- * @property {'vertex' | 'uniform' | 'texture'} [color] (`uniform`)
+ * @property {'vertex' | 'uniform' | 'texture' | 'textureMap'} [color] (`uniform`)
  * @property {'point' | 'directional' | null} [light] (`null`)
  * @interface
  * @group Shaders
  */
 export type OBJ_VertexShader = {
     light?: 'point' | 'directional' | null;
-    color?: 'vertex' | 'uniform' | 'texture';
+    color?: 'vertex' | 'uniform' | 'texture' | 'textureMap';
     dimension?: 2 | 3;
 };
 /**
@@ -93,7 +100,16 @@ export type TypeVertexShader = string | {
  * - `vec4 u_color`: global color for all vertices used all times. When
  *   `color = 'texture'` or `color = 'vertex'`, only the alpha channel of
  *   `u_color` is used.
- * - `sampler2D u_texture`: texture used when `color = 'texture'`.
+ * - `sampler2D u_texture`: texture used when `color = 'texture'`,
+ *   `color = 'textureAlpha'` or `color = 'textureMap'`.
+ * - `sampler2D u_mask0`, `u_mask1`, ...: mask textures used when
+ *   `color = 'textureMap'` (one per mask, set by the `masks` count). Each mask's
+ *   `r`, `g`, `b` and `a` channels select four regions of `u_texture` to
+ *   recolor. Mask `m`'s four channels map to tints `u_tint{4m+0..3}`.
+ * - `vec4 u_tint0`, `u_tint1`, ...: region tint colors used when
+ *   `color = 'textureMap'` (four per mask). The `rgb` channels are the tint
+ *   color and the `a` channel is the tint strength (`0` leaves the base texture
+ *   unchanged).
  * - `vec3 u_directionalLight`: world space position of directional light
  *   source used when `light = 'directional'`
  * - `float u_ambientLight`: ambient light used when `light = 'directional'` or
@@ -113,14 +129,15 @@ export type TypeVertexShader = string | {
  *    from vertex shader used when `light = 'point'`
  *
  * @property {2 | 3} [dimension] (`2`)
- * @property {'vertex' | 'uniform' | 'texture'} [color] (`uniform`)
+ * @property {'vertex' | 'uniform' | 'texture' | 'textureMap'} [color] (`uniform`)
  * @property {'point' | 'directional' | null} [light] (`null`)
  * @interface
  * @group Shaders
  */
 export type OBJ_FragmentShader = {
     light?: 'point' | 'directional' | null;
-    color?: 'vertex' | 'uniform' | 'texture';
+    color?: 'vertex' | 'uniform' | 'texture' | 'textureMap';
+    masks?: number;
 };
 /**
  * A fragment shader can be defined with either: