{"_id":"@ar-js-org/ar.js-next","name":"@ar-js-org/ar.js-next","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ar-js-org/ar.js-next","version":"0.2.0","description":"core library of AR.js","main":"dist/arjs-core.js","module":"dist/arjs-core.mjs","exports":{".":{"import":"./dist/arjs-core.mjs","require":"./dist/arjs-core.js","default":"./dist/arjs-core.mjs"}},"types":"types/src/index.d.ts","sideEffects":false,"scripts":{"build":"npm run build:vite && npm run build:types","build:types":"tsc","build:vite":"vite build","dev:vite":"vite","format-check":"prettier --check .","format":"prettier --write .","lint":"eslint . --ext .js","prepare":"husky install && npm run build","prepack":"npm run build","prepublishOnly":"npm run build","serve:vite":"vite preview","test":"vitest","test:watch":"vitest --watch","test:coverage":"vitest run --coverage"},"repository":{"type":"git","url":"git+https://github.com/AR-js-org/AR.js-core.git"},"keywords":["AR.js","WebAR","AugmentedReality"],"author":{"name":"@kalwalt"},"license":"MIT","devDependencies":{"@vitest/coverage-v8":"^4.0.16","@vitest/ui":"^4.0.16","eslint":"^9.39.2","eslint-config-prettier":"^10.1.8","husky":"^9.1.7","lint-staged":"16.2.7","prettier":"^3.7.4","typescript":"^5.9.3","vite":"^7.3.0","vitest":"^4.0.16"},"lint-staged":{"*.{js,jsx,ts,tsx,css,md,json}":["prettier --write"],"*.{js,jsx,ts,tsx}":["eslint --fix --cache"]},"_id":"@ar-js-org/ar.js-next@0.2.0","gitHead":"54b6305e33917baa9133d38cb26faed941af9ad6","bugs":{"url":"https://github.com/AR-js-org/AR.js-core/issues"},"homepage":"https://github.com/AR-js-org/AR.js-core#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-xgMBkNMzDs8Zt6G7Jak4TfUBl+wsqRQgfOFbT6rORrA6x6qrlaZyJvGZL/aw8qhbGRYc5eCaulEPw7m2GcpoGw==","shasum":"91f7edd6ec4d7f8239ae49abff04e69a8a419e89","tarball":"https://registry.npmjs.org/@ar-js-org/ar.js-next/-/ar.js-next-0.2.0.tgz","fileCount":45,"unpackedSize":315202,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICe78NZQAvfSita/a2TNmtenyMbfPJIjrNc5bYUonlUCAiEAwDOfxTyy166QsUVgH+WkgDfqMANWiobIUyBgWkGfbJY="}]},"_npmUser":{"name":"kalwalt","email":"info@kalwaltart.it"},"directories":{},"maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ar.js-next_0.2.0_1767968782971_0.16121402259565154"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-09T14:26:22.764Z","0.2.0":"2026-01-09T14:26:23.121Z","modified":"2026-01-09T14:26:23.573Z"},"maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"description":"core library of AR.js","homepage":"https://github.com/AR-js-org/AR.js-core#readme","keywords":["AR.js","WebAR","AugmentedReality"],"repository":{"type":"git","url":"git+https://github.com/AR-js-org/AR.js-core.git"},"author":{"name":"@kalwalt"},"bugs":{"url":"https://github.com/AR-js-org/AR.js-core/issues"},"license":"MIT","readme":"# AR.js-next\n\n[![npm version](https://badge.fury.io/js/%40ar-js-org%2Far.js-next.svg)](https://badge.fury.io/js/%40ar-js-org%2Far.js-next)\n[![CI](https://github.com/AR-js-org/AR.js-next/actions/workflows/ci.yml/badge.svg)](https://github.com/AR-js-org/AR.js-next/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub issues](https://img.shields.io/github/issues/AR-js-org/AR.js-next.svg)](https://github.com/AR-js-org/AR.js-next/issues)\n[![GitHub forks](https://img.shields.io/github/forks/AR-js-org/AR.js-next.svg)](https://github.com/AR-js-org/AR.js-next/network/members)\n[![GitHub stars](https://img.shields.io/github/stars/AR-js-org/AR.js-next.svg)](https://github.com/AR-js-org/AR.js-next/stargazers)\n\nA renderer-agnostic AR library built on a modern Entity-Component-System (ECS) architecture with a plugin system.\n\n## 🚀 Installing\n\nInstall from npm (recommended):\n\n```bash\nnpm install @ar-js-org/ar.js-next\n```\n\nNotes:\n\n- GitHub installs clone the repository and execute the `prepare` script, which builds `dist/` on the fly.\n- Ensure devDependencies are installed; avoid `npm install --production` when consuming from GitHub.\n- Prefer the npm registry release for reproducible installations.\n- The `dist/` directory is generated during installations and is not committed to the repository.\n\n## ✨ ECS-Only Core\n\nAs of 0.2.x, AR.js-next is ECS-only. Legacy classes (Source, Profile, Session, SessionDebugUI) have been removed to focus on:\n\n- Modular design with a clean plugin system\n- Data‑oriented ECS for efficient processing\n- Event‑driven architecture with pub/sub messaging\n- Renderer‑agnostic foundation for AR.js‑next\n\nRenderer integrations live in external repositories:\n\n- [arjs-plugin-threejs](https://github.com/AR-js-org/arjs-plugin-threejs)\n\nIf you need the legacy API, use 0.1.x or migrate to the ECS architecture below.\n\n## 🏁 Quick Start (ECS)\n\n```js\nimport {\n  Engine,\n  CaptureSystem,\n  SOURCE_TYPES,\n  defaultProfilePlugin,\n  webcamPlugin,\n} from '@ar-js-org/ar.js-next';\n\nconst engine = new Engine();\nconst ctx = engine.getContext();\n\n// Register and enable core plugins\nengine.pluginManager.register(defaultProfilePlugin.id, defaultProfilePlugin);\nengine.pluginManager.register(webcamPlugin.id, webcamPlugin);\nawait engine.pluginManager.enable(defaultProfilePlugin.id, ctx);\nawait engine.pluginManager.enable(webcamPlugin.id, ctx);\n\n// Initialize capture and start engine\nawait CaptureSystem.initialize(\n  { sourceType: SOURCE_TYPES.WEBCAM, sourceWidth: 640, sourceHeight: 480 },\n  ctx,\n);\n\nengine.start();\n```\n\n## 🖼️ Frame Pump + Video Viewport\n\nDetection plugins (e.g., arjs-plugin-artoolkit) consume frames as ImageBitmap during engine:update. The webcam plugin provides a playing <video> but does not emit frames itself.\n\nBasic flow:\n\n```js\nimport { CaptureSystem, SOURCE_TYPES, FramePumpSystem } from '@ar-js-org/ar.js-next';\n\n// 1) Start capture\nawait CaptureSystem.initialize({ sourceType: SOURCE_TYPES.WEBCAM }, ctx);\n\n// 2) Show live video (optional UI)\nconst { element: videoEl } = CaptureSystem.getFrameSource(ctx);\ndocument.getElementById('viewport').appendChild(videoEl);\n\n// 3) Pump frames to detection plugins\nFramePumpSystem.start(ctx);\n\n// 4) Stop when done\nFramePumpSystem.stop(ctx);\n```\n\nWhy separate from the webcam plugin?\n\n- The webcam plugin owns media capture; pumping frames and showing UI are cross‑cutting concerns shared by multiple detection plugins.\n\n## 🔧 Core (AR.js-next) vs Plugin Responsibilities\n\nThis section clarifies where key behaviors belong.\n\n- Axis transform (coordinate conventions)\n  - Responsibility: detection plugin\n  - Core defines a canonical world frame used across the ecosystem:\n    - Right‑handed, Y‑up, camera looks down -Z (Three.js‑friendly)\n    - 4×4 matrices are column‑major Float32Array(16), units in meters\n  - Detection plugins must emit marker transforms in this canonical frame (or internally convert from their native coordinates). Renderer plugins should not fix coordinate handedness—just apply the matrix.\n\n- Projection matrix (intrinsics)\n  - Responsibility: detection plugin emits; renderer plugin listens\n  - Event: ar:cameraProjectionChanged\n    - payload: { projectionMatrix: Float32Array(16), width: number, height: number, near?: number, far?: number, timestamp?: number }\n  - Core provides the event bus; defaultProfilePlugin may seed a fallback projection, but the detection plugin should publish accurate intrinsics when available.\n\n- Marker events\n  - Emitted by detection plugins:\n    - ar:markerFound { markerId: string|number, matrix: Float32Array(16), timestamp?: number }\n    - ar:markerUpdated { markerId: string|number, matrix: Float32Array(16), timestamp?: number }\n    - ar:markerLost { markerId: string|number, timestamp?: number }\n\n- Example UI toggles (e.g., show/hide video, axis helpers)\n  - Responsibility: examples (recommended)\n  - Plugins may expose options or simple debug hooks, but UI is not part of core.\n\n- Rendering\n  - Responsibility: renderer plugins (e.g., arjs-plugin-threejs)\n  - Renderer plugins attach a canvas, render a scene, and consume marker/projection events.\n\n## 📝 TypeScript Definitions\n\nAR.js-next ships TypeScript declaration files (.d.ts). Editors will pick them up automatically.\n\n- Importing types in TS:\n\n```ts\nimport type { Engine, PluginManager, CaptureSystem } from '@ar-js-org/ar.js-next';\n\nimport type {\n  COMPONENTS,\n  RESOURCES,\n  EVENTS,\n  SOURCE_TYPES,\n  CAPTURE_STATES,\n  DEVICE_PROFILES,\n  QUALITY_TIERS,\n} from '@ar-js-org/ar.js-next';\n```\n\n- Key exported types (names may vary by file):\n  - Engine, PluginManager, EventBus\n  - Components/Resources registries\n  - System APIs like CaptureSystem and FramePumpSystem\n  - Enums/consts: SOURCE_TYPES, CAPTURE_STATES, QUALITY_TIERS, etc.\n\nIf your toolchain requires an explicit types path, ensure your resolver honors the package’s types entry. No additional configuration is typically necessary.\n\n## ⭐ Features\n\n- Core ECS with queries and resources\n- Event Bus for decoupled communication\n- Plugin system for capture, detection, and more\n- Capture System for webcam, video, and image sources\n- Profile policies for device capability tuning\n\n## 📦 Distribution and Imports\n\nAR.js-next ships ESM and CJS bundles:\n\n- ESM (recommended): dist/arjs-core.mjs\n- CJS: dist/arjs-core.js\n\nExamples:\n\n```js\n// ESM\nimport { Engine, CaptureSystem, webcamPlugin } from '@ar-js-org/ar.js-next';\n\n// CJS\nconst { Engine, CaptureSystem, webcamPlugin } = require('@ar-js-org/ar.js-next');\n\n// Direct (local dev only)\nimport { Engine } from './node_modules/@ar-js-org/ar.js-next/dist/arjs-core.mjs';\n```\n\n## 🛠️ Development\n\n### Building\n\nRun a full build:\n\n```bash\nnpm run build\n```\n\nThis generates TypeScript declarations in `types/` and bundles in `dist/`.\n\nThe build also runs automatically when you:\n\n- package or publish (`npm pack`, `npm publish`) via the `prepack` script\n- install from GitHub (source checkout) via the `prepare` script\n\nYou do not need to commit `dist/`; it is recreated for each build or publish cycle.\n\n## 🏃 Running Examples\n\nYou can use Vite (recommended) during development.\n\nVite:\n\n```bash\nnpm install\nnpm run dev:vite\nnpm run build:vite\nnpm run serve:vite\n```\n\n- Examples index: examples/index.html\n- Minimal ECS example: examples/minimal/index.html\n\nIf the camera doesn’t start, click to allow autoplay. On Safari, prefer HTTPS in dev.\n\n## 🤝 Contributing\n\nWe welcome all contributions! Before you begin, please review our **[CONTRIBUTING.md](https://github.com/AR-js-org/AR.js-core/blob/main/CONTRIBUTING.md)** for guidelines and our **[CODE_OF_CONDUCT.md](https://github.com/AR-js-org/AR.js-core/blob/main/CODE_OF_CONDUCT.md)**. A great way to get started is by exploring open issues and pull requests.\n\n## ❓ Troubleshooting (Common)\n\n- Worker/assets 404 with vendor ESMs: co‑locate the ESM with its assets/ folder or import from CDN.\n- No detections: start FramePumpSystem after capture; verify engine:update ticks.\n- Video is not visible: attach the webcam <video> to a visible container and override offscreen styles.\n- Autoplay/permissions: set video.muted = true; add playsinline; use HTTPS on mobile.\n\n## 🚚 Migration to ECS‑Only Core\n\n- Legacy API (Source/Profile/Session/SessionDebugUI) removed from the core.\n- Core focuses on ECS + plugins; renderer integrations live externally (e.g., arjs-plugin-threejs).\n- Import from the bundled library (ESM .mjs or CJS .js) as shown above.\n","readmeFilename":"README.md","_rev":"1-ae35df9afa088204c2672df818966390"}