@doenet/prefigure

Standalone PreFigure compiler package for browser and CDN usage.

Run the PreFigure Python compiler in the browser via Pyodide + Web Worker. This package can be loaded from NPM or from a CDN (jsDelivr) and provides a full-featured PreFigure XML → SVG compiler without server dependencies.

Attribution

This package includes code adapted from the PreFigure project and its browser playground runtime:

• Upstream repository: https://github.com/davidaustinm/prefigure
• Project website: https://prefigure.org

The upstream-derived worker/runtime pieces remain available under the GNU Affero General Public License, version 3 or later. This package is distributed under the same AGPL-3.0-or-later license and preserves attribution to the upstream PreFigure work. See NOTICE.md for package-specific provenance.

Installation

npm install @doenet/prefigure

Or load from CDN:

<script type="module">
  import * as prefigure from 'https://cdn.jsdelivr.net/npm/@doenet/[email protected]/prefigure.js';
  await prefigure.initPrefigure();
  const result = await prefigure.compilePrefigure(diagramXml, { mode: 'svg' });
</script>

Pin a specific CDN version instead of using @latest so the browser runtime, vendored wheel, and downstream Doenet defaults stay reproducible.

Global API

When loaded in a browser, this package registers:

• window.initPrefigure(indexURL?)
• window.prefigure(source, { mode, indexURL })

Both methods return promises.

Example

<script type="module" src="./prefigure.js"></script>
<script type="module">
  await window.initPrefigure();
  const result = await window.prefigure(`<diagram dimensions="(100,100)"></diagram>`);
  console.log(result.svg, result.annotationsXml);
</script>

Browser Runtime Check

Run a local browser runtime check harness that compiles a tiny diagram and checks for non-empty SVG + annotations output:

npm run browser-runtime -w @doenet/prefigure

Then open http://127.0.0.1:4175/.

The page shows PASS when compilePrefigure(...) returns both:

• SVG containing an <svg> element
• annotations XML containing <annotations> or <annotation>

Automated Tests

Run package tests:

npm run test -w @doenet/prefigure

Current coverage includes API-level behavior tests for:

• default index URL resolution
• initPrefigure() idempotency and conflicting-URL guard
• compilePrefigure() delegation/result mapping
• dedicated-worker API wiring and compile delegation behavior

The browser runtime check remains useful as a manual runtime check for real Pyodide+WASM execution.

Runtime Version Sync

Builds vendor wheels from pyodide_packages/, and the browser runtime is only consistent when all pinned PreFigure pieces move together.

Before publishing or bumping the runtime, keep these in sync:

• packages/prefigure/package.json version for the published @doenet/prefigure tag
• src/worker/compiler-metadata.ts PREFIG_VERSION / PREFIG_WHEEL_FILENAME
• pyodide_packages/prefig-<version>-py3-none-any.whl via npm run setup -w @doenet/prefigure
• packages/doenetml/src/Viewer/renderers/utils/prefigureConfig.ts default CDN URLs for @doenet/prefigure and diagcess

At runtime, initPrefigure() defaults to loading wheel assets from an assets/ directory relative to the loaded prefigure.js module URL. Pass indexURL to initPrefigure(indexURL) to override this default.

Repository Hygiene

These directories/files in packages/prefigure are generated and safe to delete locally:

• dist/
• pyodide_packages/
• .wireit/
• src/worker/liblouis/generated/build-no-tables-utf32.js
• src/worker/liblouis/generated/*.cti
• src/worker/liblouis/generated/*.ctb
• src/worker/liblouis/generated/*.uti
• src/worker/liblouis/generated/*.dis

They are re-created by build/setup scripts and are already ignored by the repository .gitignore.

Maintenance Procedures

First-time setup

npm run setup -w @doenet/prefigure

This downloads:

• runtime Pyodide wheels and the pinned prefig wheel into pyodide_packages/
• liblouis JS/tables into src/worker/liblouis/generated/

Normal build + publish checks

npm run build -w @doenet/prefigure
npm run verify-wheel-sync -w @doenet/prefigure

verify-wheel-sync ensures src/worker/compiler-metadata.ts and pyodide_packages/ reference the same prefig wheel.

Upgrade PreFigure runtime version

@doenet/prefigure is not managed by Changesets. Its npm version is manually pinned to match the bundled prefig Python wheel so consumers can immediately see which upstream version they are running. Follow these steps when bumping:

1. Update version in packages/prefigure/package.json to match the new wheel version.
2. Update PREFIG_VERSION in src/worker/compiler-metadata.ts.
3. Update the default CDN module URL in packages/doenetml/src/Viewer/renderers/utils/prefigureConfig.ts.
4. If the bundled accessibility runtime changed, update the default diagcess CDN URL there as well.
5. Update prefigure.doenet.org outside this repository so the fallback build-service path matches the new runtime behavior before local WASM compilation warms up.
6. Update the hardcoded wheel path in packages/doenetml-print/src/ptx-compiler.ts — the Vite ?uint8array&base64 asset import must be a static literal string, so it cannot reference PREFIG_WHEEL_FILENAME directly. Search for the old version string and replace it.
7. Run npm run setup -w @doenet/prefigure to fetch the matching prefig-<version>-py3-none-any.whl.
8. Run npm run verify-wheel-sync -w @doenet/prefigure.
9. Build and run the browser runtime check:

npm run build -w @doenet/prefigure
npm run browser-runtime -w @doenet/prefigure

Upgrade Pyodide runtime packages

1. Bump pyodide in packages/prefigure/package.json.
2. Run npm install at repo root.
3. Run npm run setup -w @doenet/prefigure (reads the new pyodide-lock.json).
4. Run build + the browser runtime check.

Upgrade liblouis assets

1. Update LIBLOUIS_REF and hashes in scripts/fetch-liblouis.ts.
2. Run npm run setup -w @doenet/prefigure.
3. Run build + the browser runtime check.