@ar-js-org/artoolkit5-ts 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-16
+
+### Added
+
+- `createARToolKitState` / `disposeARToolKitState` — lifecycle. Dispose calls
+  the core's `teardown()` and then Embind's `delete()`; skipping the first leaks
+  the ARToolKit handles the instance owns. Idempotent.
+- `ARToolKitError`, thrown by every operation called on a disposed state, so a
+  use-after-dispose names the misused function instead of crashing somewhere
+  inside the WASM module.
+- `loadPatternMarker` and `trackMarker` for registering markers.
+- `processFrame`, returning `{ detected, lost }`.
+- `getCameraProjectionMatrix`, `transMatToGLMat` and `arglCameraViewRHf`.
+- Vitest suite covering the matrix maths, the visibility state machine and the
+  dispose lifecycle, running without WASM or a browser against a mocked core.
+- CI on Node 22 and 24: typecheck, test, build, and a packaging check.
+- Release workflow, run manually with a version. It runs the checks, sets the
+  version, promotes this changelog, derives notes from the commits, tags,
+  creates the GitHub Release and publishes to npm with provenance. A `dry_run`
+  input rehearses all of it without tagging or publishing.
+- `scripts/release-notes.mjs`, which groups Conventional Commits since the
+  previous tag so release notes reflect what actually landed, and
+  `scripts/promote-changelog.mjs`, which promotes the Unreleased section.
+- Webcam example: camera to Three.js cube overlay.
+- This changelog.
+
+### Changed
+
+- `processFrame` returns `{ detected, lost }` rather than `MarkerPose[]`. The
+  visibility transition was already computed internally and then discarded,
+  forcing consumers to diff successive results to recover it.
+- Named `@ar-js-org/artoolkit5-ts`, matching the rest of the organisation.
+- Depends on `@ar-js-org/artoolkit5-wasm@^0.1.3` from npm rather than a pinned
+  git commit. `three` moved to `devDependencies`; only the examples use it.
+
+### Fixed
+
+- `arglCameraViewRHf` allocated a `Float64Array` while every type declaration
+  promised `Float32Array`. Consumers reading `matrixGL` would have received a
+  different array type than the published types described, and the AR.js-next
+  marker event contract specifies `Float32Array(16)`.
+- `processFrame` allocated roughly three typed arrays per marker per frame. Both
+  matrix helpers now write into caller-supplied buffers, with one module-scoped
+  scratch array for the intermediate 4×4.
+- Debug logging removed from `src/`, which dumped the entire WASM module to the
+  console on every marker load and every `trackMarker` call.
+- `favicon.svg` and orphaned `.d.ts.map` files no longer ship in the package.
+
+### Notes
+
+Pattern markers only. Barcode support is planned; NFT is out of scope for this
+project. Worker compatibility is untested — nothing in `src/` touches the DOM,
+which is necessary but not proof.
+
+[Unreleased]: https://github.com/AR-js-org/artoolkit5-ts/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/AR-js-org/artoolkit5-ts/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 AR-js-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This library wraps a WebAssembly build of ARToolkit5 (WebARKitLib), which is
+licensed under the GNU Lesser General Public License v3.0. Redistributing a
+build that includes the ARToolkit5 (WebARKitLib) WebAssembly binary carries the
+obligations of that licence in addition to the terms above.

package/README.md

@@ -0,0 +1,268 @@
+# artoolkit5-ts 🎯
+
+[![npm](https://img.shields.io/npm/v/@ar-js-org/artoolkit5-ts.svg?logo=npm&logoColor=white)](https://www.npmjs.com/package/@ar-js-org/artoolkit5-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg?logo=typescript&logoColor=white)](tsconfig.json)
+[![Tested with Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18.svg?logo=vitest&logoColor=white)](test)
+[![WebAssembly](https://img.shields.io/badge/WebAssembly-ARToolkit5-654FF0.svg?logo=webassembly&logoColor=white)](https://github.com/AR-js-org/artoolkit5-wasm)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#-roadmap)
+[![AR.js-next](https://img.shields.io/badge/AR.js--next-engine%20layer-00B4D8.svg)](https://github.com/AR-js-org/AR.js-next)
+
+TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib).
+
+**This is the replacement for [`artoolkit5-js`](https://github.com/AR-js-org/artoolkit5-js)**, which is a fork of [`andypotato/artoolkit5-js`](https://github.com/andypotato/artoolkit5-js) — itself an ES6 module port of artoolkit5.
+
+`artoolkit5-ts` is a rewrite rather than another fork in that line. It is written in TypeScript against a maintained WebAssembly build, and it drops the monolithic `ARController` class those ports carried forward in favour of plain data and free functions. Nothing is hidden behind a class, so nothing has to be constructed before it can be used, tested, or tree-shaken.
+
+> ⚠️ **Status: alpha.** Pattern markers work end to end, but the API is not stable yet — expect breaking changes before 1.0. See [Roadmap](#-roadmap).
+
+## 🧩 Where this fits
+
+`artoolkit5-ts` is the detection engine layer of the AR.js-next ecosystem:
+
+```
+AR.js-next                ECS core, event bus, frame pump
+  arjs-plugin-artoolkit     ECS plugin: Web Worker, ImageBitmap, marker events
+    artoolkit5-ts           ← this library
+      artoolkit5-wasm       Emscripten / C++ bindings
+        artoolkit5-constants  ARToolkit5 constants, extracted from the headers
+```
+
+It is renderer-agnostic and DOM-free. It gives you marker poses as matrices; what you draw with them is your business — Three.js, Babylon.js, raw WebGL, or nothing at all.
+
+## 📦 Installation
+
+```bash
+npm install @ar-js-org/artoolkit5-ts
+```
+
+[`@ar-js-org/artoolkit5-wasm`](https://www.npmjs.com/package/@ar-js-org/artoolkit5-wasm) (`^0.1.3`) provides the WebAssembly engine. It installs automatically as a dependency, and is left external rather than bundled so the `.wasm` binary is fetched once and cached instead of being copied into every bundle that depends on it.
+
+`three` is only needed to run the examples, not the library.
+
+## 🚀 Quick start
+
+```typescript
+import {
+  createARToolKitState,
+  loadPatternMarker,
+  trackMarker,
+  processFrame,
+} from '@ar-js-org/artoolkit5-ts';
+
+// 1. Initialise once — loads the WASM module and camera calibration
+const state = await createARToolKitState(640, 480, './data/camera_para.dat');
+
+// 2. Register the markers you care about.
+//    The ID is assigned by the engine — never hardcode it.
+const markerId = await loadPatternMarker(state, './data/patt.hiro');
+trackMarker(state, markerId, 1.0);
+
+// 3. Per frame: pass RGBA pixels in, get poses out.
+//    Draw your video to a canvas and read it back; the library never
+//    touches the DOM, so obtaining the pixels is your side of the line.
+const pixels = ctx.getImageData(0, 0, 640, 480).data;
+const { detected, lost } = processFrame(state, pixels);
+
+for (const marker of detected) {
+  // marker.matrixGL is a 4x4 column-major right-handed matrix,
+  // ready to hand to WebGL or Three.js.
+  // With Three.js, set mesh.matrixAutoUpdate = false once beforehand,
+  // or it recomputes the matrix from position/quaternion/scale and
+  // discards the pose you just wrote.
+  mesh.matrix.fromArray(marker.matrixGL);
+}
+
+// `lost` holds markers that were visible last frame and are not now —
+// reported once, on the frame they disappear
+for (const id of lost) {
+  hideObjectFor(id);
+}
+```
+
+A complete working example lives in [`examples/webcam`](examples/webcam) — webcam capture, marker tracking and a Three.js cube overlay:
+
+```bash
+npm run dev
+```
+
+You will need the [Hiro marker](https://commons.wikimedia.org/wiki/File:Hiro_marker_wikipedia.png) printed or on a second screen.
+
+## 🧠 Why functions instead of a controller class
+
+The `ARController` that `artoolkit5-js` inherited from `jsartoolkit5` was a God Object: it owned the WASM module, the canvas, the video element, marker state and the render loop. That made it impossible to tree-shake, awkward to run in a Worker, and hard to test without a browser.
+
+Here, `ARToolKitState` is a plain data container with no methods, and every operation takes it as its first argument:
+
+- **Tree-shakeable** — you bundle only the functions you import
+- **Testable** — functions take input and return output; no mocking a class hierarchy
+- **Worker-friendly** — no DOM anywhere in `src/`, so state can live off the main thread
+- **Framework-agnostic** — nothing assumes React, Vue, or any renderer
+
+The trade-off is deliberate: this library will not open your camera, create a canvas, or run a render loop for you. Those belong to your application.
+
+## 📖 API
+
+### `createARToolKitState(width, height, cameraUrl, wasmUrl?)`
+
+Initialises the WASM module and camera parameters. Returns `Promise<ARToolKitState>`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `width` | `number` | Frame width; must match the frames you pass to `processFrame` |
+| `height` | `number` | Frame height |
+| `cameraUrl` | `string` | URL of an ARToolKit `camera_para.dat` calibration file |
+| `wasmUrl` | `string?` | Explicit URL for `artoolkit5.wasm`. Required when your bundler rewrites asset paths, as Vite does |
+
+### `loadPatternMarker(state, markerUrl)`
+
+Downloads a `.patt` file, writes it to the WASM virtual filesystem and registers it. Returns `Promise<number>` — the engine-assigned marker ID.
+
+Loading a marker does not start tracking it; pass the ID to `trackMarker`.
+
+### `trackMarker(state, pattId, markerWidth?)`
+
+Registers a marker for tracking and allocates its reusable pose buffers.
+
+`markerWidth` defaults to `1.0`. Whatever unit you choose here is the unit all returned translations are expressed in — use millimetres if you want millimetres.
+
+### `processFrame(state, videoFrame)`
+
+Detects registered markers in one frame. Returns a `FrameResult`:
+
+```typescript
+interface FrameResult {
+  detected: MarkerPose[];  // visible in this frame
+  lost: number[];          // IDs visible last frame, gone in this one
+}
+```
+
+`lost` is reported **exactly once**, on the frame a marker disappears — it does not repeat while the marker stays absent. Tracking already computes this transition internally, so exposing it saves every consumer from diffing successive results to recover it.
+
+`videoFrame` is a `Uint8ClampedArray` of RGBA pixels matching the width and height the state was created with — typically `ctx.getImageData(...).data`.
+
+This runs on every animation frame and allocates no typed arrays: poses are written into buffers owned by the marker's tracking state, and **those buffers are reused next frame**. Copy the values if you need to retain them.
+
+### `disposeARToolKitState(state)`
+
+Releases the WASM resources the state holds. Call it when tracking stops — otherwise a page that starts and stops AR leaks the C++ instance and its heap allocations every time.
+
+```typescript
+const state = await createARToolKitState(640, 480, cameraUrl);
+// … track markers …
+disposeARToolKitState(state);
+```
+
+Safe to call more than once. Afterwards every other operation on that state throws `ARToolKitError` rather than reaching freed memory, so a use-after-dispose gives you a clear message instead of a crash inside the WASM module.
+
+### `ARToolKitError`
+
+Thrown for misuse of this API — currently, using a state after disposing it. Distinct from a plain `Error` so you can tell an API mistake apart from a failure inside the WASM module or your own code.
+
+### `getCameraProjectionMatrix(state)`
+
+Returns the 4×4 projection matrix ARToolKit computed from your `camera_para.dat`, as a `Float64Array`. Use it in place of a generic perspective camera: it carries the measured focal length and principal point of the actual lens, so rendered geometry lines up with the video rather than merely sitting near it. (Radial distortion is not part of this matrix — no projection matrix can express it. ARToolKit corrects for it separately, when un-distorting detected marker corners.)
+
+### `transMatToGLMat(transMat, out?)` / `arglCameraViewRHf(glMatrix, out?, scale?)`
+
+Matrix helpers, exported because they are occasionally useful directly. `processFrame` already applies both.
+
+ARToolKit produces a 3×4 row-major pose; WebGL wants a 4×4 column-major matrix in a right-handed system. `transMatToGLMat` expands the matrix, `arglCameraViewRHf` negates the Y and Z axes. Without the second step, poses render behind the camera.
+
+Both take an optional output buffer — supply one in hot paths to avoid allocating.
+
+### Types
+
+`ARToolKitState`, `MarkerPose`, `FrameResult`, `TrackedMarkerState`, plus `ARToolKitModule`, `ARToolKitCore` and `MarkerInfo` describing the WASM boundary.
+
+```typescript
+interface MarkerPose {
+  id: number;
+  matrix: Float64Array;    // 3x4, row-major, as ARToolKit produces it
+  matrixGL: Float32Array;  // 4x4, column-major, right-handed, WebGL-ready
+}
+```
+
+## 🖼️ Feeding frames from an ImageBitmap
+
+`processFrame` takes raw pixels, so `src/` never touches a canvas API. If your frames arrive as `ImageBitmap` — as they do in AR.js-next — convert them yourself, reusing one canvas rather than creating one per frame:
+
+```typescript
+// The same dimensions the state was created with. Reading back any other
+// size gives processFrame a buffer it will misinterpret.
+const WIDTH = 640;
+const HEIGHT = 480;
+
+const canvas = new OffscreenCanvas(WIDTH, HEIGHT);
+const ctx = canvas.getContext('2d', { willReadFrequently: true })!;
+
+function toPixels(bitmap: ImageBitmap): Uint8ClampedArray {
+  ctx.drawImage(bitmap, 0, 0, WIDTH, HEIGHT);
+  return ctx.getImageData(0, 0, WIDTH, HEIGHT).data;
+}
+```
+
+A helper that does this is on the roadmap; until then it is a few lines you own.
+
+## ⚠️ Limitations
+
+- **Pattern markers only.** Barcode/matrix markers are planned; NFT is out of scope for this project — see [Roadmap](#-roadmap).
+- **No detector tuning yet.** Threshold, threshold mode, labelling mode and related settings are exposed by the engine but not yet surfaced here.
+- **Worker support is untested.** Nothing in `src/` touches the DOM, which is necessary but not proof — WASM instantiation in worker scope has not been verified.
+
+## 🗺️ Roadmap
+
+Detailed design lives in [`docs/DESIGN-v0.1.md`](docs/DESIGN-v0.1.md); work is tracked in [issues](https://github.com/AR-js-org/artoolkit5-ts/issues).
+
+**v0.1** (done) — lifecycle, packaging, marker-lost reporting from `processFrame`, a test suite and CI.
+
+**Next** — `configureDetector` for threshold and labelling settings, barcode markers, a verified Worker example, an `ImageBitmap` conversion helper, and multi-marker sets.
+
+**Out of scope** — NFT tracking. This project and `artoolkit5-wasm` cover pattern and barcode markers; NFT belongs to other projects in the ecosystem.
+
+## 🛠️ Development
+
+```bash
+npm run dev        # Vite dev server, opens the webcam example
+npm run build      # library build (ES + UMD) plus type declarations
+npm run preview    # preview the production build
+npm test           # run the test suite once
+npm run test:watch # re-run tests on change
+npm run typecheck  # tsc --noEmit
+```
+
+### Tests
+
+[Vitest](https://vitest.dev) covers the matrix maths, the marker visibility state machine and the dispose lifecycle. The suite runs in well under a second because the WASM boundary is faked: `test/mock-core.ts` stands in for the Emscripten module and the bound C++ instance, so neither a browser nor a compiled binary is needed.
+
+The suite aims at the code that fails *quietly* rather than at a line-count target — a transposed matrix still renders, just in the wrong place, and a marker-lost event that fires twice looks fine until something downstream double-handles it.
+
+It is validated by mutation: deliberately breaking the collection order, the `Float32Array` return type, or the continuous-tracking condition each makes exactly one test fail. If you add tests, check they can actually fail.
+
+### Contributing
+
+Branch from `dev`; `main` holds release-ready code only. Commits follow [Conventional Commits](https://www.conventionalcommits.org/). Fuller guidance is in [`AGENTS.md`](AGENTS.md).
+
+### Releasing
+
+Releases are cut by the **Release** workflow, run manually from the Actions tab. Its only required input is the version to publish, without a leading `v` — for example `0.1.0`.
+
+Everything after that is automatic: it runs typecheck, tests and build, sets the version, promotes the changelog, derives release notes from the commits, commits, tags `vX.Y.Z`, creates the GitHub Release and publishes to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) — so the package carries a verifiable link back to the commit and workflow run that built it.
+
+**Run it with `dry_run` first.** That performs every check and prints the notes and the tarball contents without tagging, committing or publishing. It is the only way to rehearse: npm never allows a published version to be replaced.
+
+Before running for real, the workflow refuses to start unless:
+
+- the version is valid semver, not already tagged, and not already on npm
+- the branch is `main`
+- the repository is public — npm will not generate provenance from a private repository
+
+Preparing a release means writing the changelog. Add entries to `## [Unreleased]` as you go; the workflow renames that heading to the released version and opens a fresh one. Anything between `<!-- promote:strip -->` markers is dropped during promotion, so notes meant only for editors do not survive into a released section. `npm run release-notes` prints the Conventional Commits since the last tag if you want to see what has accumulated.
+
+It is a single workflow rather than a "create release" and a "publish" pair because a Release created with the default `GITHUB_TOKEN` does not trigger other workflows — GitHub blocks that to prevent recursion, so the second one would silently never fire.
+
+## 📄 Licence
+
+MIT — see [LICENSE](LICENSE).
+
+This library wraps a WebAssembly build of **ARToolkit5 (WebARKitLib), which is licensed under the LGPL v3.0**. The MIT licence covers this TypeScript code, not the engine underneath: redistributing a build that includes the ARToolkit5 (WebARKitLib) WebAssembly binary carries that licence's obligations as well.

package/dist/artoolkit5-ts.js

@@ -0,0 +1,102 @@
+import { addMarkerFromUrl as e, createARToolKit as t, loadCameraFromUrl as n } from "@ar-js-org/artoolkit5-wasm";
+//#region src/errors.ts
+var r = class e extends Error {
+	constructor(t) {
+		super(t), this.name = "ARToolKitError", Object.setPrototypeOf(this, e.prototype);
+	}
+};
+function i(e, t) {
+	if (e.disposed) throw new r(`${t} was called on a disposed ARToolKitState. Create a new one with createARToolKitState().`);
+}
+//#endregion
+//#region src/init.ts
+async function a(e, r, i, a) {
+	let o = (await t({ locateFile: (e) => a && e.endsWith(".wasm") ? a : e })).mod, s = new o.ARToolKitCore(), c = await n(o, s, i);
+	return await s.setup(e, r, c), {
+		mod: o,
+		core: s,
+		width: e,
+		height: r,
+		markers: {},
+		disposed: !1
+	};
+}
+function o(e) {
+	e.disposed ||= (e.core.teardown(), e.core.delete(), e.markers = {}, !0);
+}
+//#endregion
+//#region src/markers.ts
+async function s(t, n) {
+	return i(t, "loadPatternMarker"), e(t.mod, t.core, n);
+}
+//#endregion
+//#region src/math.ts
+var c = 16;
+function l(e) {
+	return i(e, "getCameraProjectionMatrix"), e.core.getCameraLens();
+}
+function u(e, t = new Float32Array(c)) {
+	return t[0] = e[0], t[1] = e[4], t[2] = e[8], t[3] = 0, t[4] = e[1], t[5] = e[5], t[6] = e[9], t[7] = 0, t[8] = e[2], t[9] = e[6], t[10] = e[10], t[11] = 0, t[12] = e[3], t[13] = e[7], t[14] = e[11], t[15] = 1, t;
+}
+function d(e, t = new Float32Array(c), n) {
+	return t[0] = e[0], t[4] = e[4], t[8] = e[8], t[12] = e[12], t[1] = -e[1], t[5] = -e[5], t[9] = -e[9], t[13] = -e[13], t[2] = -e[2], t[6] = -e[6], t[10] = -e[10], t[14] = -e[14], t[3] = 0, t[7] = 0, t[11] = 0, t[15] = 1, n !== void 0 && n !== 0 && (t[12] *= n, t[13] *= n, t[14] *= n), t;
+}
+//#endregion
+//#region src/tracking.ts
+var f = 12, p = 3, m = -1, h = [], g = !0, _ = /* @__PURE__ */ new Float32Array(16);
+function v(e, t, n = 1) {
+	i(e, "trackMarker"), e.markers[t] = {
+		id: t,
+		markerWidth: n,
+		inPrevious: !1,
+		inCurrent: !1,
+		matrix: new Float64Array(f),
+		matrixGL: /* @__PURE__ */ new Float32Array(16)
+	};
+}
+function y(e, t) {
+	return i(e, "processFrame"), b(e, t), x(e), {
+		detected: S(e),
+		lost: C(e)
+	};
+}
+function b(e, t) {
+	e.core.passVideoData(t, h, g), e.core.detectMarker();
+}
+function x(e) {
+	for (let t in e.markers) {
+		let n = e.markers[t];
+		n.inPrevious = n.inCurrent, n.inCurrent = !1;
+	}
+}
+function S(e) {
+	let t = [], n = e.core.getMarkerNum();
+	for (let r = 0; r < n; r++) {
+		let { id: n } = e.core.getMarkerInfo(r);
+		if (n === m) continue;
+		let i = e.markers[n];
+		i && (i.inCurrent = !0, w(e, r, i), t.push({
+			id: i.id,
+			matrix: i.matrix,
+			matrixGL: i.matrixGL
+		}));
+	}
+	return t;
+}
+function C(e) {
+	let t = [];
+	for (let n in e.markers) {
+		let r = e.markers[n];
+		r.inPrevious && !r.inCurrent && t.push(r.id);
+	}
+	return t;
+}
+function w(e, t, n) {
+	n.inPrevious ? e.core.getTransMatSquareCont(t, n.markerWidth) : e.core.getTransMatSquare(t, n.markerWidth), T(e, n.matrix), u(n.matrix, _), d(_, n.matrixGL);
+}
+function T(e, t) {
+	let n = e.core.getTransform() >> p;
+	t.set(e.mod.HEAPF64.subarray(n, n + f));
+}
+//#endregion
+export { r as ARToolKitError, d as arglCameraViewRHf, a as createARToolKitState, o as disposeARToolKitState, l as getCameraProjectionMatrix, s as loadPatternMarker, y as processFrame, v as trackMarker, u as transMatToGLMat };

package/dist/artoolkit5-ts.umd.cjs

@@ -0,0 +1 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@ar-js-org/artoolkit5-wasm")):typeof define==`function`&&define.amd?define([`exports`,`@ar-js-org/artoolkit5-wasm`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.ARToolkit5TS={},e.ARToolkit5Wasm))})(this,function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var n=class e extends Error{constructor(t){super(t),this.name=`ARToolKitError`,Object.setPrototypeOf(this,e.prototype)}};function r(e,t){if(e.disposed)throw new n(`${t} was called on a disposed ARToolKitState. Create a new one with createARToolKitState().`)}async function i(e,n,r,i){let a=(await(0,t.createARToolKit)({locateFile:e=>i&&e.endsWith(`.wasm`)?i:e})).mod,o=new a.ARToolKitCore,s=await(0,t.loadCameraFromUrl)(a,o,r);return await o.setup(e,n,s),{mod:a,core:o,width:e,height:n,markers:{},disposed:!1}}function a(e){e.disposed||=(e.core.teardown(),e.core.delete(),e.markers={},!0)}async function o(e,n){return r(e,`loadPatternMarker`),(0,t.addMarkerFromUrl)(e.mod,e.core,n)}var s=16;function c(e){return r(e,`getCameraProjectionMatrix`),e.core.getCameraLens()}function l(e,t=new Float32Array(s)){return t[0]=e[0],t[1]=e[4],t[2]=e[8],t[3]=0,t[4]=e[1],t[5]=e[5],t[6]=e[9],t[7]=0,t[8]=e[2],t[9]=e[6],t[10]=e[10],t[11]=0,t[12]=e[3],t[13]=e[7],t[14]=e[11],t[15]=1,t}function u(e,t=new Float32Array(s),n){return t[0]=e[0],t[4]=e[4],t[8]=e[8],t[12]=e[12],t[1]=-e[1],t[5]=-e[5],t[9]=-e[9],t[13]=-e[13],t[2]=-e[2],t[6]=-e[6],t[10]=-e[10],t[14]=-e[14],t[3]=0,t[7]=0,t[11]=0,t[15]=1,n!==void 0&&n!==0&&(t[12]*=n,t[13]*=n,t[14]*=n),t}var d=12,f=3,p=-1,m=[],h=!0,g=new Float32Array(16);function _(e,t,n=1){r(e,`trackMarker`),e.markers[t]={id:t,markerWidth:n,inPrevious:!1,inCurrent:!1,matrix:new Float64Array(d),matrixGL:new Float32Array(16)}}function v(e,t){return r(e,`processFrame`),y(e,t),b(e),{detected:x(e),lost:S(e)}}function y(e,t){e.core.passVideoData(t,m,h),e.core.detectMarker()}function b(e){for(let t in e.markers){let n=e.markers[t];n.inPrevious=n.inCurrent,n.inCurrent=!1}}function x(e){let t=[],n=e.core.getMarkerNum();for(let r=0;r<n;r++){let{id:n}=e.core.getMarkerInfo(r);if(n===p)continue;let i=e.markers[n];i&&(i.inCurrent=!0,C(e,r,i),t.push({id:i.id,matrix:i.matrix,matrixGL:i.matrixGL}))}return t}function S(e){let t=[];for(let n in e.markers){let r=e.markers[n];r.inPrevious&&!r.inCurrent&&t.push(r.id)}return t}function C(e,t,n){n.inPrevious?e.core.getTransMatSquareCont(t,n.markerWidth):e.core.getTransMatSquare(t,n.markerWidth),w(e,n.matrix),l(n.matrix,g),u(g,n.matrixGL)}function w(e,t){let n=e.core.getTransform()>>f;t.set(e.mod.HEAPF64.subarray(n,n+d))}e.ARToolKitError=n,e.arglCameraViewRHf=u,e.createARToolKitState=i,e.disposeARToolKitState=a,e.getCameraProjectionMatrix=c,e.loadPatternMarker=o,e.processFrame=v,e.trackMarker=_,e.transMatToGLMat=l});

package/dist/domain.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared data structures.
+ *
+ * This module contains types only — no logic, no side effects.
+ */
+/**
+ * Detection result for a single marker in a single frame.
+ *
+ * `matrix` and `matrixGL` are views onto buffers owned by the tracker and
+ * reused every frame. Copy them if you need to retain values across frames.
+ *
+ * The differing precisions are deliberate: full precision is kept at the
+ * source and narrowed exactly once, at the boundary where the data becomes
+ * GPU-bound. Prefer `matrix` for any CPU-side maths — smoothing,
+ * interpolation, physics — and `matrixGL` only for rendering.
+ */
+export interface MarkerPose {
+    id: number;
+    /**
+     * 3x4 row-major pose, exactly as ARToolKit produces it.
+     *
+     * 64-bit because the C core computes in `ARdouble` and writes to
+     * `HEAPF64`; reading it as `Float64Array` is a lossless copy.
+     */
+    matrix: Float64Array;
+    /**
+     * 4x4 column-major right-handed pose, ready for WebGL.
+     *
+     * 32-bit because WebGL is single-precision end to end — `uniformMatrix4fv`
+     * takes a `Float32Array` and GLSL's `highp float` is 32-bit, so any wider
+     * precision is discarded on upload. Not an accuracy compromise: float32
+     * resolves below a micron at metre scale, while pose error is dominated by
+     * camera noise and calibration in the millimetre range.
+     */
+    matrixGL: Float32Array;
+}
+/**
+ * Outcome of a single call to `processFrame`.
+ *
+ * `lost` exists because the visibility transition is already computed while
+ * tracking, and discarding it would force every consumer to re-derive it by
+ * diffing successive results.
+ */
+export interface FrameResult {
+    /** Markers visible in this frame, with their poses. */
+    detected: MarkerPose[];
+    /**
+     * IDs of markers visible in the previous frame but not this one.
+     *
+     * Reported exactly once, on the frame the marker disappears.
+     */
+    lost: number[];
+}
+/** Per-marker tracking state, owned by {@link ARToolKitState}. */
+export interface TrackedMarkerState {
+    id: number;
+    markerWidth: number;
+    /** Visible in the previous frame — enables continuous tracking. */
+    inPrevious: boolean;
+    /** Visible in the frame currently being processed. */
+    inCurrent: boolean;
+    /** Reused across frames; never reallocated after registration. */
+    matrix: Float64Array;
+    /** Reused across frames; never reallocated after registration. */
+    matrixGL: Float32Array;
+}
+/**
+ * The Emscripten module, narrowed to the surface this library uses.
+ *
+ * Structurally compatible with the `Mod` type expected by the
+ * `@ar-js-org/artoolkit5-wasm` loader helpers.
+ */
+export interface ARToolKitModule {
+    /** Emscripten heap, read directly when unpacking pose pointers. */
+    HEAPF64: Float64Array;
+    FS: unknown;
+    loadCameraFromPath(path: string): number;
+    addMarker(path: string): number;
+}
+/** Marker metadata returned by the detector for one candidate square. */
+export interface MarkerInfo {
+    /** Engine-assigned marker ID, or -1 when unrecognised. */
+    id: number;
+}
+/**
+ * The C++ `ARToolKitCore` instance, narrowed to the methods this library calls.
+ *
+ * Pose getters return a pointer into the Emscripten heap rather than a value;
+ * see {@link ARToolKitCore.getTransform}.
+ */
+export interface ARToolKitCore {
+    setup(width: number, height: number, cameraId: number): Promise<void>;
+    passVideoData(frame: Uint8ClampedArray, lumaBuffer: number[], convertToLuma: boolean): void;
+    detectMarker(): void;
+    getMarkerNum(): number;
+    getMarkerInfo(index: number): MarkerInfo;
+    getTransMatSquare(index: number, markerWidth: number): void;
+    getTransMatSquareCont(index: number, markerWidth: number): void;
+    /** Byte offset into `HEAPF64` holding the most recent 3x4 pose. */
+    getTransform(): number;
+    getCameraLens(): Float64Array;
+    /** Releases the ARToolKit handles held by the C++ instance. */
+    teardown(): number;
+    /** Frees the C++ instance itself. Generated by Embind, not declared in C++. */
+    delete(): void;
+}
+/**
+ * The central state object threaded through every operation.
+ *
+ * A pure data container: it has no methods, and functions receive it as their
+ * first argument rather than being bound to it.
+ */
+export interface ARToolKitState {
+    readonly mod: ARToolKitModule;
+    readonly core: ARToolKitCore;
+    readonly width: number;
+    readonly height: number;
+    /** Registered markers, keyed by engine-assigned ID. */
+    markers: Record<number, TrackedMarkerState>;
+    /**
+     * Set by `disposeARToolKitState`. Once true the C++ instance is gone and
+     * every operation on this state throws rather than reaching freed memory.
+     */
+    disposed: boolean;
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+import { ARToolKitState } from './domain';
+/**
+ * Error thrown by this library.
+ *
+ * Distinct from a plain `Error` so callers can tell a misuse of this API apart
+ * from a failure inside the WASM module or the host application.
+ */
+export declare class ARToolKitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Throws if the state has been disposed.
+ *
+ * Every public operation calls this first. Without it, using a disposed state
+ * reaches freed WASM memory and fails somewhere inside the module, where the
+ * error says nothing about the actual mistake.
+ *
+ * @param operation Name of the calling function, used in the message.
+ */
+export declare function assertNotDisposed(state: ARToolKitState, operation: string): void;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { ARToolKitCore, ARToolKitModule, ARToolKitState, FrameResult, MarkerInfo, MarkerPose, TrackedMarkerState, } from './domain';
+export { ARToolKitError } from './errors';
+export { createARToolKitState, disposeARToolKitState } from './init';
+export { loadPatternMarker } from './markers';
+export { processFrame, trackMarker } from './tracking';
+export { arglCameraViewRHf, getCameraProjectionMatrix, transMatToGLMat } from './math';

package/dist/init.d.ts

@@ -0,0 +1,27 @@
+import { ARToolKitState } from './domain';
+/**
+ * Initialises the WASM module, loads camera parameters and returns the state
+ * object that every other operation in this library operates on.
+ *
+ * @param width  Frame width in pixels; must match the frames passed to `processFrame`.
+ * @param height Frame height in pixels; must match the frames passed to `processFrame`.
+ * @param cameraUrl URL of an ARToolKit `camera_para.dat` calibration file.
+ * @param wasmUrl Optional explicit URL for `artoolkit5.wasm`. Required when the
+ *   bundler rewrites asset paths, as Vite does.
+ */
+export declare function createARToolKitState(width: number, height: number, cameraUrl: string, wasmUrl?: string): Promise<ARToolKitState>;
+/**
+ * Releases the WASM resources held by a state.
+ *
+ * Call this when tracking stops — a single-page app that starts and stops AR,
+ * or a test creating a state per case, otherwise leaks the C++ instance and its
+ * heap allocations every time.
+ *
+ * Two steps are needed: `teardown()` frees the ARToolKit handles the instance
+ * owns, and `delete()` — generated by Embind rather than declared in C++ —
+ * frees the instance itself. Calling only the latter leaks the handles.
+ *
+ * Safe to call more than once; subsequent calls do nothing. Every other
+ * operation on the state throws {@link ARToolKitError} afterwards.
+ */
+export declare function disposeARToolKitState(state: ARToolKitState): void;

package/dist/markers.d.ts

@@ -0,0 +1,11 @@
+import { ARToolKitState } from './domain';
+/**
+ * Downloads a pattern file (`.patt`), writes it to the WASM virtual file system
+ * and registers it with the ARToolKit core.
+ *
+ * The returned ID is assigned by the C++ engine and must be passed to
+ * `trackMarker` before the marker will be tracked. Never hardcode it.
+ *
+ * @throws {ARToolKitError} if the state has been disposed.
+ */
+export declare function loadPatternMarker(state: ARToolKitState, markerUrl: string): Promise<number>;

package/dist/math.d.ts

@@ -0,0 +1,30 @@
+import { ARToolKitState } from './domain';
+/**
+ * Returns the camera projection matrix computed by ARToolKit from the loaded
+ * `camera_para.dat`, accounting for real lens distortion.
+ *
+ * NOTE: unlike `getTransform`, which returns a heap pointer, this returns the
+ * matrix directly. That asymmetry is unverified against the C++ source. See
+ * "spike: verify what getCameraLens() actually returns":
+ * https://github.com/AR-js-org/artoolkit5-ts/issues/10
+ *
+ * @throws {ARToolKitError} if the state has been disposed.
+ */
+export declare function getCameraProjectionMatrix(state: ARToolKitState): Float64Array;
+/**
+ * Expands ARToolKit's 3x4 row-major pose into a 4x4 column-major matrix.
+ *
+ * @param out Optional destination. Supply one in hot paths to avoid allocating.
+ */
+export declare function transMatToGLMat(transMat: Float64Array, out?: Float32Array): Float32Array;
+/**
+ * Converts a 4x4 ARToolKit matrix into the right-handed coordinate system used
+ * by WebGL, by negating the Y and Z axes.
+ *
+ * Without this the pose renders behind the camera. It is the mathematically
+ * correct equivalent of manually flipping matrix signs.
+ *
+ * @param out Optional destination. Supply one in hot paths to avoid allocating.
+ * @param scale Optional uniform scale applied to the translation column.
+ */
+export declare function arglCameraViewRHf(glMatrix: Float32Array, out?: Float32Array, scale?: number): Float32Array;

package/dist/tracking.d.ts

@@ -0,0 +1,26 @@
+import { ARToolKitState, FrameResult } from './domain';
+/**
+ * Registers a marker for tracking and allocates its reusable pose buffers.
+ *
+ * @param pattId ID returned by `loadPatternMarker`.
+ * @param markerWidth Physical marker width; the unit chosen here is the unit
+ *   all returned translations are expressed in.
+ * @throws {ARToolKitError} if the state has been disposed.
+ */
+export declare function trackMarker(state: ARToolKitState, pattId: number, markerWidth?: number): void;
+/**
+ * Detects registered markers in a single frame.
+ *
+ * Returns both the markers visible now and those that have just disappeared,
+ * so a consumer emitting found/updated/lost events does not have to diff
+ * successive results to recover information tracking already had.
+ *
+ * Called once per animation frame, so it allocates no typed arrays: every pose
+ * is written into buffers owned by the marker's tracking state. Those buffers
+ * are reused next frame — copy them if you need to retain values.
+ *
+ * @param videoFrame RGBA pixels matching the width and height the state was
+ *   created with.
+ * @throws {ARToolKitError} if the state has been disposed.
+ */
+export declare function processFrame(state: ARToolKitState, videoFrame: Uint8ClampedArray): FrameResult;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@ar-js-org/artoolkit5-ts",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib). Composable and tree-shakeable: state is plain data, operations are functions.",
+  "keywords": [
+    "artoolkit",
+    "artoolkit5",
+    "augmented-reality",
+    "ar",
+    "webar",
+    "marker-tracking",
+    "barcode-marker",
+    "webassembly",
+    "wasm",
+    "typescript",
+    "ar.js",
+    "webarkit"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Walter Perdan",
+    "url": "https://github.com/kalwalt"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AR-js-org/artoolkit5-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AR-js-org/artoolkit5-ts/issues"
+  },
+  "homepage": "https://github.com/AR-js-org/artoolkit5-ts#readme",
+  "main": "./dist/artoolkit5-ts.umd.cjs",
+  "module": "./dist/artoolkit5-ts.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/artoolkit5-ts.js",
+      "require": "./dist/artoolkit5-ts.umd.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "release-notes": "node scripts/release-notes.mjs"
+  },
+  "dependencies": {
+    "@ar-js-org/artoolkit5-wasm": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "@types/three": "^0.185.0",
+    "three": "^0.185.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0",
+    "vitest": "^4.1.10"
+  }
+}