@tensnap/js

JavaScript/TypeScript simulator-side bindings for the strict TenSnap v0.3 protocol.

Prepare a release tag from the repository root:

pnpm release:js X.Y.Z
git push origin main
git push origin js-vX.Y.Z

The js-publish GitHub Actions workflow tests, builds, and publishes this package when the tag is pushed. For a batch release, run the workflow manually and select the packages to publish. npm authenticates the workflow through its Trusted Publisher configuration for js-publish.yml; see the versioning guide.

What It Provides

• Declarative model builders through modelBuilder(...).
• Config parameter helpers such as numberField(...), booleanField(...), stringField(...), and enumField(...).
• Low-level protocol metadata helpers for tests and advanced integrations.
• Runtime primitives: SimulatorSession and SimulatorEmitter.
• Scenario replay helpers through ScenarioRegistry.
• Simulator hosts for WebSocket and postMessage transports.

Minimal WebSocket Server

import { createWebSocketTransportHost, modelBuilder, numberField } from '@tensnap/js';

const builder = modelBuilder(
  {
    id: 'demo',
    name: 'Demo',
    description: 'A minimal JavaScript model.',
    stateSchemaVersion: '1',
  },
  {
    defaults: { speed: 1 },
    create(config) {
      return {
        tick: 0,
        config: { ...config },
        agents: [{ id: 'a1', x: 0, y: 0 }],
      };
    },
    getConfig(model) {
      return model.config;
    },
    step(model) {
      model.tick += 1;
      model.agents[0].x += model.config.speed;
      return true;
    },
    time(model) {
      return model.tick;
    },
  },
);

builder.paramsFromConfig({
  get: (model) => model.config,
  set(model, patch) {
    Object.assign(model.config, patch);
  },
  fields: {
    speed: numberField({ label: 'Speed' }),
  },
});

builder.env('main').agentLayer('agents', {
  items: (model) => model.agents,
});

const binding = builder.build();

const host = createWebSocketTransportHost({
  serverOptions: { port: 8765 },
  sessionFactory: () => binding.createSession(),
});

await host.ready;
console.log(host.url);

The builder registers start, step, stop, and reset automatically. start is continuous-capable and uses the boolean returned by step to decide whether the renderer may continue dispatching.

Reset reconciles declarations with strict CRUD, clears chart history, and deletes the previous non-trajectory item set before publishing current state; stable create-only definitions are not replayed as upserts.

The strict v0.3 binding never translates legacy action or state-sync fields. Each session sends simulator_info before any other simulator message, then waits for a valid state_sync before invoking init.

Monitors and scene restore are opt-in: use .monitor(...) for current values. For projected restore, declare sceneRestore: { mode: 'compose', ... } and a layer restore object with complete C/U/D callbacks. The binding validates the full input, applies metadata, deletes dependent layers first, then creates and updates source layers before replaying canonical state. Use sceneRestore: { mode: 'imperative', apply(...) } only when the model owns the entire projected restore; it cannot be mixed with declarative layer handlers.

Exact checkpoint support still requires matching restoreCheckpoint(...) and captureCheckpoint(...) hooks plus a stable stateSchemaVersion, but it does not require projected restore hooks. Capture hooks return only model data (ProtocolValue or Uint8Array); the binding chooses MessagePack or application/octet-stream wire encoding automatically. Restore hooks receive that decoded model data. Restore replay never sends chart messages.

Trajectory builders expose length, width, color, zIndex, onAgentDelete, onStateSync, and onReset directly. Restore request IDs are cached, and paired checkpoint hooks also provide rollback if a later restore phase fails. Create-only state replay is advertised as replace, never as a false reconcile/upsert transaction.

Projection ownership

Standalone built-in item projectors return independent nested snapshots. Eligible automatic layer scans can compare with previous owned snapshots and reuse equal read-only nested fields before materializing changed values; this does not guarantee outer-record identity. Custom callbacks keep safe publication copying and may explicitly declare independent output to avoid it. Layer options control projector and publication copying separately: disabling publication copying does not cancel an owning projector. Configure policies before use, and treat published records as read-only. See the shared ownership contract and focused benchmark commands for the language-specific options, overrides, and source-value rules.

Transport Options

Use createWebSocketTransportHost(...) for a local simulator server.

Import browser endpoint tools and createPostMessageSimulatorHost from @tensnap/js/transport/browser to avoid loading the Node WebSocket host. Renderer transports come from @tensnap/web-adapter/transport.

Use createPostMessageSimulatorHost(...) when the simulator runs in a worker, iframe, or in-memory paired endpoint. createLinkedEndpoints() is useful for tests and bundled examples.

Runnable Examples

pnpm dev:js:schelling
pnpm dev:js:wolf-sheep
pnpm dev:js:axelrod
pnpm dev:js:tornberg

For the full API surface, see docs/api-reference/js-api.md.

IP family

See the networking guide for auto (default), ipv4, and ipv6 policies, IPv6 URLs, and shared ephemeral ports.