3D engine that AI agents drive
Add the third-party addon contract and starter (#985)
Nguyen Xuan Ane0628ee2e55d
diff --git a/changes/985.md b/changes/985.mdnew file mode 100644index 00000000..ab93751d--- /dev/null+++ b/changes/985.md@@ -0,0 +1 @@+- Third-party addons have a contract, a checker (`scripts/addon-check.mjs`), a guide (`docs/addons.md`) and a starter template (#985)diff --git a/docs/addons.md b/docs/addons.mdnew file mode 100644index 00000000..fc986e97--- /dev/null+++ b/docs/addons.md@@ -0,0 +1,60 @@+# Addons from other people++A code addon is an npm package that extends 67js through the extension points it already has. 67js's own addons (`67js/addons/*`) are first-party; this page is the contract for third-party ones.++## Security++A code addon runs with the full rights of your page or Node process: it can read files, use the network and change anything in the scene. The MCP server never loads one from a tool call. Install only addons you trust, and read what an addon does before you add it.++## The contract++An addon package:++- lists `@codepawlhq/67js` under `peerDependencies`, so it shares the host's copy instead of bundling its own;+- has `67js-addon` in `keywords`, so a search by that keyword finds it;+- has a SPDX `license`;+- has a `67js` field in `package.json` that states what the addon needs:++```json+"67js": {+ "range": ">=0.19.0 <1.0.0",+ "extensionPoints": ["registerController"],+ "bundleBytes": 2048+}+```++`range` is the 67js versions it was tested with (comparators such as `>=0.19.0 <1.0.0`, or `^0.19.0`). `extensionPoints` lists every point it uses. `bundleBytes` is the size of the entry file named by `main` or `exports`.++The manifest lives in `package.json` rather than a separate `67js-addon.json` because the npm registry returns the whole `package.json` of each version, so a listing can read the range and points without unpacking the tarball, and there is no second file to forget to publish.++## Extension points++These are the ways code can extend 67js today, and the only names the `extensionPoints` list accepts:++| Name | What the addon calls | Import |+| --- | --- | --- |+| `registerController` | `registerController(kind, factory)`: a controller kind (a boat, a ball) | `67js/addons/player` |+| `registerCameraRig` | `registerCameraRig(kind, factory)`: a camera rig kind | `67js/addons/player` |+| `userPass` | a GLSL `userPass(vec2 uv)` fragment set on `renderer.userPasses` ([user passes](user-passes.md)) | `67js/addons/user-pass` |+| `streamingLoader` | `registerLoader(format, loader)` on a streaming instance ([streaming](streaming.md)) | `67js/addons/streaming` |+| `runtimeSystem` | `runtime.addSystem(system)` ([runtime](runtime.md)) | `67js/addons/runtime` |++Kinds and formats cannot be replaced once registered, so pick a name that is unlikely to clash, such as a prefix with your package name.++## Write one++Copy [templates/addon-starter](https://github.com/codepawl/67.js/tree/main/templates/addon-starter). It registers a `hover` controller kind, has a test written with `node:test`, and passes the check below. Export a function that registers, rather than registering on import, so the host decides when.++## Test one++Run your own tests with `@codepawlhq/67js` installed as a dev dependency next to the peer entry. Then check the contract:++```sh+node node_modules/@codepawlhq/67js/scripts/addon-check.mjs . --version 0.19.0+```++The check says what failed and what to pass instead. It tests the keyword, the peer dependency, the license, the `67js` field, the entry size, and that the range allows the version you pass.++## Publish one++`npm publish` the package. Keep `67js-addon` in the keywords and bump the `range` after you test against a new 67js release.diff --git a/docs/guide.md b/docs/guide.mdindex 3492e57e..c73d03db 100644--- a/docs/guide.md+++ b/docs/guide.md@@ -84,6 +84,8 @@ Core exports are available from `67js`:`67js/addons/canvas2d`: 2D recipes. `67js/addons/gltf`: optional asset decoding. These are separate imports to keep the core smaller.+Other people's addons follow the [addon contract](addons.md): a peer dependency on 67js, the `67js-addon` keyword and a `67js` manifest.+67js targets WebGL2. Version `0.4.0` includes the APIs below. Check the installed package version and release metadata before using them.## Release and source availabilitydiff --git a/package.json b/package.jsonindex c9d4bcd7..26b8825b 100644--- a/package.json+++ b/package.json@@ -55,6 +55,8 @@"docs/game.md","docs/scene-query.md","docs/user-passes.md",+ "docs/addons.md",+ "scripts/addon-check.mjs","docs/skeleton-pose.md","docs/verification.md"],diff --git a/scripts/addon-check.mjs b/scripts/addon-check.mjsnew file mode 100644index 00000000..dbd15151--- /dev/null+++ b/scripts/addon-check.mjs@@ -0,0 +1,169 @@+// Checks a folder against the 67js third-party addon contract (docs/addons.md).+// Usage: node scripts/addon-check.mjs <addon-folder> [--version <67js version>]+import { existsSync, readFileSync, statSync } from 'node:fs';+import { join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++export const ADDON_KEYWORD = '67js-addon';+export const CORE_PACKAGE = '@codepawlhq/67js';+export const EXTENSION_POINTS = Object.freeze({+ registerController: 'registerController(kind, factory) from 67js/addons/player',+ registerCameraRig: 'registerCameraRig(kind, factory) from 67js/addons/player',+ userPass: 'a user GLSL pass given to renderer.userPasses.set (67js/addons/user-pass)',+ streamingLoader: 'registerLoader(format, loader) on a streaming instance (67js/addons/streaming)',+ runtimeSystem: 'runtime.addSystem(system) on a runtime (67js/addons/runtime)',+});++const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;+const COMPARATOR_PATTERN = /^(>=|<=|>|<|=|\^)?(\d+\.\d+\.\d+)$/;+const POINT_NAMES = Object.keys(EXTENSION_POINTS).join(', ');++function parseVersion(text) {+ const match = VERSION_PATTERN.exec(text);+ return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;+}++function compareVersions(left, right) {+ for (let index = 0; index < 3; index += 1) {+ if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;+ }+ return 0;+}++function caretUpperBound([major, minor, patch]) {+ if (major > 0) return [major + 1, 0, 0];+ if (minor > 0) return [0, minor + 1, 0];+ return [0, 0, patch + 1];+}++// Parses a range such as ">=0.19.0 <1.0.0" or "^0.19.0" into [operator, version] pairs, or null when it is not one.+export function parseRange(range) {+ if (typeof range !== 'string' || range.trim() === '') return null;+ const comparators = [];+ for (const part of range.trim().split(/\s+/)) {+ const match = COMPARATOR_PATTERN.exec(part);+ if (!match) return null;+ const version = parseVersion(match[2]);+ if (match[1] === '^') {+ comparators.push(['>=', version], ['<', caretUpperBound(version)]);+ } else {+ comparators.push([match[1] ?? '=', version]);+ }+ }+ return comparators;+}++export function rangeAllows(range, version) {+ const comparators = parseRange(range);+ const parsed = parseVersion(version);+ if (!comparators || !parsed) return false;+ return comparators.every(([operator, bound]) => {+ const order = compareVersions(parsed, bound);+ return { '>=': order >= 0, '<=': order <= 0, '>': order > 0, '<': order < 0, '=': order === 0 }[operator];+ });+}++function readPackage(folder, errors) {+ const path = join(folder, 'package.json');+ if (!existsSync(path)) {+ errors.push(`No package.json in ${folder}. Run the check on the addon package folder.`);+ return null;+ }+ try {+ return JSON.parse(readFileSync(path, 'utf8'));+ } catch (error) {+ errors.push(`package.json is not valid JSON (${error.message}). Fix the syntax.`);+ return null;+ }+}++function checkManifest(manifest, errors) {+ if (manifest === undefined || manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {+ errors.push('package.json has no "67js" field. Add "67js": { "range": ">=0.19.0 <1.0.0", "extensionPoints": ["registerController"], "bundleBytes": 2048 }.');+ return;+ }+ if (!parseRange(manifest.range)) {+ errors.push(`"67js".range must be a version range such as ">=0.19.0 <1.0.0" or "^0.19.0", got ${JSON.stringify(manifest.range)}.`);+ }+ const points = manifest.extensionPoints;+ if (!Array.isArray(points) || points.length === 0) {+ errors.push(`"67js".extensionPoints must list at least one of: ${POINT_NAMES}.`);+ } else {+ for (const point of points) {+ if (!Object.hasOwn(EXTENSION_POINTS, point)) {+ errors.push(`"67js".extensionPoints names unknown point ${JSON.stringify(point)}. Use one of: ${POINT_NAMES}.`);+ }+ }+ }+ if (!Number.isInteger(manifest.bundleBytes) || manifest.bundleBytes <= 0) {+ errors.push(`"67js".bundleBytes must be a positive whole number of bytes for the entry file, got ${JSON.stringify(manifest.bundleBytes)}.`);+ }+}++function checkEntrySize(folder, pack, errors) {+ const manifest = pack['67js'];+ const entry = typeof pack.main === 'string' ? pack.main : typeof pack.exports === 'string' ? pack.exports : null;+ if (entry === null || !Number.isInteger(manifest?.bundleBytes)) return;+ const path = resolve(folder, entry);+ if (!existsSync(path)) {+ errors.push(`The entry file ${entry} does not exist. Point "main" or "exports" at a file that is published.`);+ return;+ }+ const actual = statSync(path).size;+ if (actual > manifest.bundleBytes) {+ errors.push(`${entry} is ${actual} bytes but "67js".bundleBytes says ${manifest.bundleBytes}. Raise bundleBytes to at least ${actual}.`);+ }+}++function checkPeer(pack, errors, warnings) {+ const peerRange = pack.peerDependencies?.[CORE_PACKAGE];+ if (peerRange === undefined) {+ errors.push(`package.json "peerDependencies" must list ${CORE_PACKAGE} so the addon shares the host's copy. Add "${CORE_PACKAGE}": ">=0.19.0 <1.0.0".`);+ } else if (!parseRange(peerRange)) {+ errors.push(`peerDependencies.${CORE_PACKAGE} must be a version range such as ">=0.19.0 <1.0.0", got ${JSON.stringify(peerRange)}.`);+ }+ if (pack.dependencies?.[CORE_PACKAGE] !== undefined) {+ warnings.push(`${CORE_PACKAGE} is in dependencies. Move it to peerDependencies so hosts do not get two copies.`);+ }+}++// Returns { errors, warnings } for the addon package in `folder`. `version` is a 67js version the declared range must allow.+export function checkAddon(folder, { version } = {}) {+ const errors = [];+ const warnings = [];+ const pack = readPackage(folder, errors);+ if (pack === null) return { errors, warnings };+ if (typeof pack.name !== 'string' || pack.name === '') errors.push('package.json needs a "name".');+ if (!Array.isArray(pack.keywords) || !pack.keywords.includes(ADDON_KEYWORD)) {+ errors.push(`package.json "keywords" must include "${ADDON_KEYWORD}" so the listing finds the addon. Add it.`);+ }+ checkPeer(pack, errors, warnings);+ if (typeof pack.license !== 'string' || pack.license === '') {+ errors.push('package.json "license" must be an SPDX identifier such as "MIT".');+ }+ checkManifest(pack['67js'], errors);+ checkEntrySize(folder, pack, errors);+ const declaredRange = pack['67js']?.range;+ if (version && parseRange(declaredRange) && !rangeAllows(declaredRange, version)) {+ errors.push(`"67js".range ${declaredRange} does not allow 67js ${version}. Widen the range or test the addon against ${version}.`);+ }+ return { errors, warnings };+}++function main(argumentsList) {+ const versionIndex = argumentsList.indexOf('--version');+ const version = versionIndex >= 0 ? argumentsList[versionIndex + 1] : undefined;+ const valueIndex = versionIndex >= 0 ? versionIndex + 1 : -1;+ const folder = argumentsList.find((value, index) => !value.startsWith('--') && index !== valueIndex);+ if (!folder) {+ console.error('Pass the addon package folder: node scripts/addon-check.mjs <addon-folder> [--version <67js version>]');+ return 2;+ }+ const { errors, warnings } = checkAddon(resolve(folder), { version });+ for (const warning of warnings) console.warn(`warning: ${warning}`);+ for (const error of errors) console.error(`error: ${error}`);+ console.log(errors.length === 0 ? 'addon contract: ok' : `addon contract: ${errors.length} problem(s)`);+ return errors.length === 0 ? 0 : 1;+}++if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));diff --git a/templates/addon-starter/README.md b/templates/addon-starter/README.mdnew file mode 100644index 00000000..f028e2da--- /dev/null+++ b/templates/addon-starter/README.md@@ -0,0 +1,12 @@+# 67js addon starter++A minimal 67js addon. It registers a `hover` controller kind through `registerController`.++1. Copy this folder, then rename the package in `package.json`.+2. `npm install`, then `npm test`.+3. Check the contract: `node node_modules/@codepawlhq/67js/scripts/addon-check.mjs .`+4. `npm publish`. The `67js-addon` keyword is how the addon is found.++Keep `@codepawlhq/67js` a peer dependency, list every extension point you use in the `67js` field, and keep `bundleBytes` at least the size of the entry file. The full guide is [docs/addons.md](https://github.com/codepawl/67.js/blob/main/docs/addons.md).++Install only addons you trust: a code addon runs with the full rights of your page or Node process.diff --git a/templates/addon-starter/package.json b/templates/addon-starter/package.jsonnew file mode 100644index 00000000..6a202f97--- /dev/null+++ b/templates/addon-starter/package.json@@ -0,0 +1,25 @@+{+ "name": "67js-addon-starter",+ "version": "0.1.0",+ "description": "A starter for a 67js addon: registers a hover controller kind.",+ "type": "module",+ "main": "./src/index.js",+ "exports": "./src/index.js",+ "files": ["src"],+ "license": "MIT",+ "keywords": ["67js-addon", "67js", "three-d"],+ "scripts": {+ "test": "node --test tests/starter.spec.js"+ },+ "67js": {+ "range": ">=0.19.0 <1.0.0",+ "extensionPoints": ["registerController"],+ "bundleBytes": 2048+ },+ "peerDependencies": {+ "@codepawlhq/67js": ">=0.19.0 <1.0.0"+ },+ "devDependencies": {+ "@codepawlhq/67js": "^0.19.0"+ }+}diff --git a/templates/addon-starter/src/index.js b/templates/addon-starter/src/index.jsnew file mode 100644index 00000000..4f035168--- /dev/null+++ b/templates/addon-starter/src/index.js@@ -0,0 +1,29 @@+import { registerController } from '@codepawlhq/67js/addons/player';++const DEFAULT_HOVER_HEIGHT = 1.5;+const DEFAULT_SPEED = 4;++// A controller kind that holds a body at a fixed height and moves it with two input axes.+function createHoverController(options = {}) {+ const hoverHeight = options.hoverHeight ?? DEFAULT_HOVER_HEIGHT;+ const speed = options.speed ?? DEFAULT_SPEED;+ const state = { position: [0, hoverHeight, 0] };+ return {+ name: options.name ?? 'player',+ kind: 'hover',+ state,+ fixedUpdate(stepSeconds) {+ const sideways = options.input?.getAxis('moveX') ?? 0;+ const forward = options.input?.getAxis('moveForward') ?? 0;+ state.position[0] += sideways * speed * stepSeconds;+ state.position[2] -= forward * speed * stepSeconds;+ state.position[1] = hoverHeight;+ },+ };+}++// Call once per page or process: a kind name can be registered only one time.+export function registerHoverController(kind = 'hover') {+ registerController(kind, createHoverController);+ return kind;+}diff --git a/templates/addon-starter/tests/starter.spec.js b/templates/addon-starter/tests/starter.spec.jsnew file mode 100644index 00000000..b716096f--- /dev/null+++ b/templates/addon-starter/tests/starter.spec.js@@ -0,0 +1,17 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { createController, listControllerKinds } from '@codepawlhq/67js/addons/player';+import { registerHoverController } from '../src/index.js';++test('the hover kind is registered and holds its height while moving', () => {+ registerHoverController('hover');+ assert.ok(listControllerKinds().includes('hover'));+ const input = { getAxis: name => (name === 'moveX' ? 1 : 0) };+ const controller = createController('hover', { input, hoverHeight: 2, speed: 3 });+ controller.fixedUpdate(0.5);+ assert.deepEqual(controller.state.position, [1.5, 2, 0]);+});++test('registering the same kind twice names the clash', () => {+ assert.throws(() => registerHoverController('hover'), /already registered/);+});diff --git a/tests/addon-starter.test.js b/tests/addon-starter.test.jsnew file mode 100644index 00000000..9a721c7b--- /dev/null+++ b/tests/addon-starter.test.js@@ -0,0 +1,105 @@+import assert from 'node:assert/strict';+import { spawnSync } from 'node:child_process';+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { register } from 'node:module';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import test from 'node:test';+import { fileURLToPath, pathToFileURL } from 'node:url';+import { checkAddon, parseRange, rangeAllows } from '../scripts/addon-check.mjs';+import { VERSION } from '../src/version.js';++const root = fileURLToPath(new URL('..', import.meta.url));+const starterFolder = join(root, 'templates', 'addon-starter');+const PEER_PREFIX = '@codepawlhq/67js/addons/';++// Resolves the peer package's addon subpaths to this checkout's source, as the built package would.+const resolveHooks = `+export async function resolve(specifier, context, next) {+ if (specifier.startsWith(${JSON.stringify(PEER_PREFIX)})) {+ const name = specifier.slice(${PEER_PREFIX.length});+ return { url: new URL('src/' + name + '.js', ${JSON.stringify(pathToFileURL(root + '/').href)}).href, shortCircuit: true };+ }+ return next(specifier, context);+}+`;+const hooksUrl = `data:text/javascript,${encodeURIComponent(resolveHooks)}`;+register(hooksUrl);++function copyStarter(change) {+ const folder = mkdtempSync(join(tmpdir(), 'addon-starter-'));+ cpSync(starterFolder, folder, { recursive: true });+ const path = join(folder, 'package.json');+ const pack = JSON.parse(readFileSync(path, 'utf8'));+ change(pack);+ writeFileSync(path, JSON.stringify(pack));+ return folder;+}++function errorsFor(change, options) {+ const folder = copyStarter(change);+ try {+ return checkAddon(folder, options).errors;+ } finally {+ rmSync(folder, { recursive: true, force: true });+ }+}++test('the starter template passes the contract for the current 67js version', () => {+ const { errors, warnings } = checkAddon(starterFolder, { version: VERSION });+ assert.deepEqual(errors, []);+ assert.deepEqual(warnings, []);+});++test('the starter registers its controller kind against the local 67js source', async () => {+ const { registerHoverController } = await import(pathToFileURL(join(starterFolder, 'src', 'index.js')).href);+ const { createController } = await import('../src/player.js');+ assert.equal(registerHoverController('starter-hover'), 'starter-hover');+ const controller = createController('starter-hover', { hoverHeight: 3 });+ assert.deepEqual(controller.state.position, [0, 3, 0]);+});++test('the starter own tests pass against the local 67js source', () => {+ const result = spawnSync(process.execPath, ['--import', hooksUrl, '--test', join(starterFolder, 'tests', 'starter.spec.js')], { encoding: 'utf8' });+ assert.equal(result.status, 0, result.stdout + result.stderr);+});++test('a missing keyword is refused with the fix', () => {+ const errors = errorsFor(pack => { pack.keywords = ['three-d']; });+ assert.match(errors.join('\n'), /must include "67js-addon".*Add it/);+});++test('a missing peer dependency is refused with the fix', () => {+ const errors = errorsFor(pack => { delete pack.peerDependencies; });+ assert.match(errors.join('\n'), /peerDependencies" must list @codepawlhq\/67js/);+});++test('a bad range, unknown point and missing manifest are refused', () => {+ assert.match(errorsFor(pack => { pack['67js'].range = 'latest'; }).join('\n'), /"67js".range must be a version range/);+ assert.match(errorsFor(pack => { pack['67js'].extensionPoints = ['hackTheGibson']; }).join('\n'), /unknown point "hackTheGibson"/);+ assert.match(errorsFor(pack => { delete pack['67js']; }).join('\n'), /no "67js" field/);+});++test('a range that excludes the running version and an oversized entry are refused', () => {+ assert.match(errorsFor(pack => { pack['67js'].range = '>=9.0.0'; }, { version: VERSION }).join('\n'), /does not allow 67js/);+ assert.match(errorsFor(pack => { pack['67js'].bundleBytes = 10; }).join('\n'), /raise bundleBytes|Raise bundleBytes/i);+});++test('the command line exits non-zero for a folder that breaks the contract', () => {+ const folder = copyStarter(pack => { pack.keywords = []; });+ try {+ const result = spawnSync(process.execPath, [join(root, 'scripts', 'addon-check.mjs'), folder], { encoding: 'utf8' });+ assert.equal(result.status, 1);+ assert.match(result.stderr, /error: /);+ } finally {+ rmSync(folder, { recursive: true, force: true });+ }+});++test('ranges parse caret and comparator forms', () => {+ assert.ok(parseRange('^0.19.0'));+ assert.equal(parseRange('wat'), null);+ assert.equal(rangeAllows('^0.19.0', '0.19.4'), true);+ assert.equal(rangeAllows('^0.19.0', '0.20.0'), false);+ assert.equal(rangeAllows('>=0.19.0 <1.0.0', '0.20.0'), true);+});