ball2d 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,42 @@
+Ball2D SDK License, version 1.0
+Copyright (c) 2026 Fillbyte. All rights reserved.
+
+1. Permission
+Fillbyte grants you a non-exclusive, worldwide, royalty-free license to download,
+install and run the unmodified Ball2D SDK to develop and operate integrations
+with the official Ball2D service, including commercial integrations. You may
+copy the SDK into your deployment artifacts for that purpose. You may use, copy
+and adapt the public type declarations, documentation and examples to build your
+integration. Retain this license and the applicable third-party notices in copies
+of the SDK that you distribute with your integration.
+
+2. Service access
+Native room hosting requires a valid Ball2D API key and compliance with the
+service's authorization, scope, rate and concurrent-session limits. This license
+does not grant unlimited service access or permission to bypass those controls.
+You are responsible for protecting your credentials and your integration's data.
+
+3. Reserved rights
+The game implementation remains proprietary. No right to its private source code,
+trademarks or branding is granted. Except for the permission above, you may not
+redistribute a modified Ball2D runtime or offer the SDK as an independent competing
+service without Fillbyte's written permission. This is a proprietary SDK license,
+not an open-source license. Rights that cannot lawfully be restricted remain
+unaffected.
+
+4. Third-party components
+Components identified in dist/licenses retain their own licenses, which govern
+those components and take precedence over conflicting restrictions in this
+license. No ownership of those components is claimed by Fillbyte.
+
+5. Warranty and liability
+To the extent permitted by applicable law, the SDK is provided "AS IS", without
+warranty of any kind. Fillbyte is not liable for damages arising from use of or
+inability to use the SDK. Nothing excludes liability that cannot lawfully be
+excluded. No uptime, compatibility or fitness guarantee is implied.
+
+6. Termination
+If you materially violate this license, the permissions granted by this license
+terminate. Stop using and distributing the SDK under those permissions. The
+third-party licenses remain independent. Separately agreed written terms with
+Fillbyte take precedence where they expressly address the same subject.

package/README.md

@@ -1,155 +1,201 @@
 # Ball2D SDK
 
-```ts
-import { createRoom, type RoomConfig } from 'ball2d';
+Host a Ball2D football room on your own server and control it through a typed
+JavaScript API. The host runs the simulation; players connect directly over
+WebRTC. Ball2D provides authorization, room discovery and signaling.
 
-const config: RoomConfig = { roomName: 'My room', noPlayer: true };
-const room = await createRoom(config);
-room.onPlayerJoin = (player) => room.setPlayerTeam(player.id, 1);
-await room.startGame();
-// When the host is finished:
-// room.close();
-```
+**Release: 0.2.0.** The matching production service supports API-key-authorized
+Node.js hosting, account quotas and key revocation. This release has passed an
+authenticated production acceptance run with a real browser player.
 
-This initial entry runs in a browser on an origin serving the matching Ball2D
-Worker API, WASM and stadium assets. The separate experimental `ball2d/node` entry provides native Node hosting. The
-browser entry does not provide remote-origin hosting or an isolated plugin runtime.
-Importing it does not register a window global or allocate a room. Creating a
-room explicitly starts the existing browser host and its network lifecycle.
-
-`RoomConfig`, `Room`, `HostPlayer`, `HostScores` and `HostDiscProperties` are exported
-types. `readReplay` reads Ball2D recordings.
-
-State-changing SDK commands return Promises and run in call order. A synchronous
-getter immediately after a command still observes the earlier state; await the
-command before reading its result. Inputs are copied at call time. Up to 256
-commands may wait; overflow rejects without dropping accepted work. Live command
-errors also reach `onError`; cancellation and calls after closure only reject their
-Promises. `close()` immediately rejects pending SDK work and closes the
-host; it does not undo operations already applied remotely. Getters and recording
-start/stop remain synchronous. Chat filters must synchronously return false.
-Callbacks receive the SDK facade as `this`; engine/network internals are not
-part of that facade. This is an API boundary, not a sandbox for untrusted code.
-
-`createRoom()` accepts omitted options. Defaults are a private room named
-`Headless Room`, capacity 12, and an admin host player named `Host`. Set
-`noPlayer: true` for an unattended playerless room and `public: true` to list it.
-Integer capacity is clamped to 2–30; malformed numeric or privacy values reject
-before engine/network allocation. Omitted/null optional default fields resolve
-to defaults. The standalone `/headless` and `/headless.html` pages have been
-retired; import the SDK instead. No `window.Ball2D` global is registered.
-
-Version 0.1.0 is the first functional SDK release. For native hosting use Node.js
-24 and the `ball2d/node` entry below. This is an early API; the native transport
-remains experimental and the acceptance limits below still apply.
-
-Validate a stadium before allocating a room:
-
-```ts
-import { validateStadium } from 'ball2d';
+Repository maintainers: [local setup](https://github.com/fillbyte/ball2d/blob/main/docs/DEVELOPMENT.md) · [release procedure](https://github.com/fillbyte/ball2d/blob/main/docs/RELEASING.md) · [changelog](https://github.com/fillbyte/ball2d/blob/main/CHANGELOG.md).
 
-const report = validateStadium('{name:"Training", canBeStored:false}');
-console.log(report.name, report.canBeStored, report.warnings);
+## Node.js quick start
+
+Use Node.js 24 or newer. The verified native runtime is Node.js 24.19.0 on macOS
+arm64; other systems need independent acceptance. Native transport is experimental.
+
+```sh
+npm install ball2d@0.2.0
 ```
 
-`validateStadium(source)` is synchronous and works without browser globals,
-network requests or a WASM instance. It uses the same parser and limits as room
-creation. Malformed/unsupported input throws; ignored field names become bounded
-warnings. The returned `StadiumValidation` and warning array are readonly and
-frozen. No geometry or internal engine objects are exposed. Passing validation
-means Ball2D can parse the source; it does not guarantee every gameplay outcome.
-Use the separate `ball2d/node` entry for native room hosting.
-
-`room.signal` is a readonly `AbortSignal` that aborts once when host closure
-begins, including a fatal transport closure. Use it to cancel your own room-bound
-work. It signals cancellation, not completion of every cleanup operation. Pending
-SDK commands are cancelled from the same signal; cancellation never reenters the
-room's error callback. A terminal transport error can still be reported once.
-
-SDK `setScoreLimit` and `setTimeLimit` clamp integer arguments to 0–99 (goals
-and minutes respectively); zero disables that limit. Await them before reading
-updated state. Active-match calls remain no-ops. Non-integer or non-numeric
-values reject when settings are editable. These commands use the same queued
-contract in browser and native SDK hosts.
-
-## Experimental native Node host
-
-```ts
-import { createRoom, type NodeRoom } from 'ball2d/node';
-
-const room: NodeRoom = await createRoom({
-  serviceOrigin: 'http://127.0.0.1:8787', // A matching Ball2D deployment
-  roomName: 'Native room',
+Create an API key through your Ball2D account.
+Supply it as `BALL2D_API_KEY` through your server's secret manager or environment;
+never commit it or include it in a browser bundle.
+
+```js
+import { createRoom } from 'ball2d/node';
+
+const apiKey = process.env.BALL2D_API_KEY;
+if (!apiKey) throw new Error('Set BALL2D_API_KEY');
+
+const room = await createRoom({
+  apiKey,
+  roomName: 'Evening football',
   noPlayer: true,
+  maxPlayers: 16,
+  public: true,
 });
+
+room.onError = (error) => console.error('Room error:', error.message);
 room.onPlayerJoin = (player) => room.setPlayerTeam(player.id, 1);
 await room.setDefaultStadium('Classic');
+await room.setScoreLimit(3);
 await room.startGame();
-// Later:
-room.close();
-await room.closed; // Native peer cleanup finished; rejects on cleanup failure.
+console.log(room.roomLink);
+
+async function shutdown() {
+  room.close();
+  await room.closed;
+}
+process.once('SIGINT', () => void shutdown().catch(console.error));
+process.once('SIGTERM', () => void shutdown().catch(console.error));
 ```
 
-Verified on Node 24.19.0 and Bun 1.4.2 on macOS arm64 with local Worker signaling
-and real Chrome guests. Both use the same `ball2d/node` entry, runtime WebSocket
-and bundled, patched werift 0.24.4; no
-browser host, postinstall patching or external transport dependency is required.
-WASM and default stadium files are included and the engine identity is checked.
-`serviceOrigin` defaults to `https://ball2d.com`; the deployment's client/protocol
-and engine must match this SDK version. Importing the package does not
-open a room. Browser consumers continue to import from `ball2d`.
-
-On a deployment with accounts and SDK keys configured, supply an account-owned
-key from an environment variable:
+`serviceOrigin` defaults to `https://ball2d.com`. A custom origin must serve a
+matching Ball2D deployment, authorization API and engine/protocol. The native
+package includes its compiled runtime, WebAssembly engine, transport and stadiums;
+it needs no browser process, postinstall patch or sibling source checkout.
+
+## Authorization and limits
+
+The native `apiKey` is required. Missing or malformed credentials fail before
+engine and transport allocation. There is no anonymous fallback. The key is sent
+only to the configured service in Authorization headers, never in peer messages
+or room URLs. Cross-origin redirects cannot forward it.
+
+| Policy                        | Initial limit                           |
+| ----------------------------- | --------------------------------------- |
+| Active API keys per account   | 2                                       |
+| Active rooms per key          | 1                                       |
+| Active rooms per account      | 2                                       |
+| New room attempts per key     | 3 per rolling minute                    |
+| New room attempts per account | 5 per rolling minute                    |
+| Startup reservation           | 30 seconds                              |
+| Active lease                  | Up to 90 seconds, bounded by key expiry |
+| Lease renewal                 | Every 30 seconds                        |
+
+Capacity is enforced by the service, not by a local process counter. Repeated
+idempotent admissions do not consume another room; failed capacity attempts count
+against admission rate limits. Admission and renewal recheck key expiry and
+revocation. The official runtime closes on terminal rejection or lease expiry;
+network failures receive bounded retries. Account revocation is not an instant
+remote kill guarantee. Obey `Retry-After` and avoid tight retry loops.
+
+Anonymous browser play is a separate service policy. API keys govern official
+native admission; they cannot make downloaded executable code confidential or
+prevent modified participants from running an unconnected private simulation.
+
+## Room API
+
+The public types are included in `dist/types`. The `ball2d/node` entry exports
+`createRoom`, `validateStadium`, `readReplay` and the native/public room types.
+TypeScript projects can use `module: "NodeNext"`, `lib: ["ES2022"]` and Node types;
+native declarations do not require DOM/WebRTC globals or `skipLibCheck`.
+
+- **Players and lobby:** inspect players, assign teams/admins, lock teams, kick/ban,
+  manage admission, send chat and announcements, and configure the room.
+- **Matches:** start/stop, pause/resume, score/time limits, kick-rate limits and
+  `await room.setSurfaceEnabled(true)` for wet grass and ground wear. Pass `false`
+  to restore dry ground. Stop the match before changing the surface; loading a
+  stadium resets it. Surface changes are retained in replays.
+- **Physics and stadiums:** load custom stadium text, select ten bundled defaults,
+  query and modify supported player/disc properties, and use `CollisionFlags`.
+- **Events:** player join/leave/chat, team/admin changes, ball kicks, goals,
+  match ticks, position resets, victory, stadium changes and recording completion.
+- **Replay:** record and decode Ball2D recordings with their embedded stadium and
+  matching engine identity.
+
+State-changing commands return Promises and run in call order. Await a command
+before reading the resulting state. Getters and recording start/stop are
+synchronous. Inputs and returned public data are copied; mutable engine and
+transport internals are not exposed through the API. Up to 256 commands may wait;
+overflow rejects without dropping accepted commands.
+
+Callbacks receive the room facade as `this`. Callback failures are reported to
+`onError`; that handler's own failures are contained. Chat filtering must return
+`false` synchronously to suppress a message. Player IDs are stable public IDs,
+not physics slots; departed player IDs are not reused within a room.
+
+Room creation resolves only after signaling confirms host authority. An optional
+second argument `{ signal }` cancels startup. Startup has a 15-second overall
+deadline; after creation, call `close()` to stop the room. `signal` aborts when
+closure begins and `closed` settles after native cleanup. `close()` is idempotent,
+cancels pending commands and finalizes an active recording once. It does not
+confirm that every remote player has received a shutdown message.
+
+## Signaling recovery
+
+Browser and native runtimes request resumable signaling by default. If the
+signaling connection briefly drops, the same admitted host or player can recover
+within the service membership lifetime while retaining healthy direct peer
+connections. Custom services must support the matching signaling protocol.
+
+This does not automatically transfer ownership to another player when the host
+leaves, guarantee uninterrupted delivery, or provide a relay for incompatible
+networks. Native recovery remains subject to the API key and room lease; it does
+not bypass revocation or quota enforcement.
+
+## Stadiums and replays
+
+```js
+import { validateStadium, readReplay } from 'ball2d/node';
 
-```ts
-const apiKey = process.env.BALL2D_API_KEY;
-if (!apiKey) throw new Error('Set BALL2D_API_KEY from your Ball2D account.');
-const room = await createRoom({ roomName: 'My room host', noPlayer: true, apiKey });
-```
-
-`apiKey` is optional for existing anonymous hosting. When supplied, it is sent
-only in the authenticated room-creation request's Authorization header, never
-in a URL or peer message. Keys currently authorize only `rooms:create`. New keys
-expire after 90 days by default; the account page offers 7, 30, 90 or 365 days.
-Expiry and revocation prevent new room creation without stopping an existing match. Never include this key in browser bundles or version control.
-Account access depends on configured social providers and Worker bindings.
-Anonymous room hosting is available without an API key.
-
-The matching Worker limits room creation to 10 attempts per minute per
-API key and 20 per minute across an account's keys, in addition to the IP gate.
-HTTP rate-limit responses include `Retry-After: 60`; avoid immediate retry loops.
-These are approximate, location-local abuse limits, not globally exact quotas.
-Exhausting a creation budget does not interrupt an established match.
-Node.js 24 is the primary supported development target; Bun uses the same entry
-without a separate implementation.
-
-Native room callbacks and commands use the same SDK facade. `signal` aborts when
-close begins; `closed` settles after native cleanup. Neither is a confirmation
-that every remote player has received a shutdown message. This is not yet WAN,
-Linux, other Bun versions, automatic outage recovery, sustained churn or capacity acceptance.
-Bundled dependency licenses are in
-`dist/licenses`; the transport includes DCEP unordered-bit and ICE restart fixes.
-
-TypeScript Node consumers can use `module: "NodeNext"`, `lib: ["ES2022"]` and
-`types: ["node"]` with their Node type package. Public declarations do not require
-DOM/WebRTC globals or `skipLibCheck`; browser runtime classes remain internal.
-`Replay` is exported as a data type from both SDK entries.
-
-Both SDK entries accept `createRoom(config, { signal })`. The optional
-`AbortSignal` cancels startup only; aborting it after creation does not close the
-room. Use `room.close()` for an active room. Startup has a 15-second overall
-deadline for engine assets, HTTP admission/body and signaling, while the existing
-12-second signaling timeout can fail earlier. Rejection preserves the caller's
-abort reason; the overall deadline rejects with `TimeoutError`. In-flight asset
-and admission requests receive the startup signal, and late results cannot
-continue admission after cancellation.
-
-## Install
-
-```sh
-npm install ball2d@0.1.1
+const report = validateStadium('{name:"Training", canBeStored:false}');
+console.log(report.name, report.warnings);
+
+room.startRecording();
+// Play, then stop recording:
+const recording = room.stopRecording();
+if (recording) {
+  const replay = await readReplay(recording);
+  console.log(replay);
+}
 ```
 
-The application source remains private. The package retains its existing
-UNLICENSED designation; bundled third-party notices are included separately.
+Validation is synchronous and does not allocate a room. Passing validation means
+the stadium can be parsed, not that all gameplay outcomes have been certified.
+Bundled defaults are Classic, Easy, Small, Big, Rounded, Hockey, Big Easy,
+Big Rounded, Big Hockey and Huge. They are Ball2D-authored procedural designs;
+provenance and hashes are included. Custom stadiums and embedded-stadium replays
+remain supported. Geometry and physics can differ from earlier SDK assets.
+Recordings are binary containers: use `readReplay`, not JSON parsing.
+
+## Browser integration
+
+`import { createRoom } from 'ball2d'` is the browser entry for an origin serving
+matching Ball2D APIs, WASM and stadium assets. It is not a remote-origin native
+host or an untrusted plugin sandbox. It follows the browser admission policy;
+never put a native API key into its bundle. Importing either entry does not create
+a room or register a window global. Browser and native hosts share public room
+commands while retaining their distinct startup and cleanup contracts.
+
+## Distribution, license and support
+
+This public repository contains reviewed executable artifacts, public declarations
+and integration documentation. The game and infrastructure source remain in a
+separate private repository. Source maps, internal declarations and platform
+credentials are excluded. Distributed JavaScript and WASM can still be inspected
+and modified; the package is not a reverse-engineering prevention mechanism.
+
+The proprietary [SDK license](LICENSE) permits integrations with the official
+Ball2D service, including commercial use. Public visibility does not make the
+runtime open source. Third-party components retain their licenses in `dist/licenses`.
+
+Run `npm run check` in this repository to verify pinned runtime hashes, the
+package boundary and native missing-key behavior. `npm pack --dry-run --ignore-scripts`
+shows the publish contents. GitHub Actions is permanently disabled.
+
+Report reproducible defects through [issues](https://github.com/fillbyte/ball2d/issues).
+Remove secrets, personal data and private room links. Use
+[private vulnerability reporting](https://github.com/fillbyte/ball2d/security/advisories/new)
+for sensitive findings. See [contribution guidance](https://github.com/fillbyte/ball2d/blob/main/CONTRIBUTING.md).
+
+Production acceptance on 12 September 2026 verified a confirmed-email account
+creating an API key, Node.js room creation, wet-ground simulation with a Chrome
+player, a second room rejected by the key quota, and active-key revocation closing
+the official host and rejecting new admission. Local verification also includes
+installed-package hosting, gameplay, replay and cleanup. This evidence does not
+establish broad WAN/NAT reachability,
+Linux compatibility, sustained capacity or an uptime guarantee. Direct WebRTC
+requires peer reachability; no TURN relay is provided.