@crowdedkingdoms/construct 0.0.0 → 0.2.0-dev.1

package/src/platform/onboarding/steps.test.ts

@@ -0,0 +1,486 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@crowdedkingdoms/crowdyjs', () => ({
+  progressionBlueprint: (o: unknown) => ({ name: 'progression', options: o }),
+  leaderboardsBlueprint: (o: unknown) => ({ name: 'leaderboards', options: o }),
+}));
+
+const steps = await import('./steps.mjs');
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Any = any;
+
+function identityStub(overrides: Any = {}): Any {
+  const created: Any[] = [];
+  return {
+    created,
+    organizations: {
+      mine: vi.fn(async () => overrides.orgs ?? []),
+      create: vi.fn(async (input: Any) => {
+        created.push(['org', input]);
+        return { orgId: '1', slug: input.slug, name: input.name };
+      }),
+    },
+    apps: {
+      forOrg: vi.fn(async () => overrides.apps ?? []),
+      placeableDatacenters: vi.fn(async () => ({
+        datacenters: overrides.datacenters ?? [
+          { code: 'va', placeable: true, serving: true, appShardCount: 9 },
+          { code: 'or', placeable: true, serving: true, appShardCount: 2 },
+          { code: 'zz', placeable: false, serving: true, appShardCount: 0 },
+        ],
+      })),
+      create: vi.fn(async (input: Any) => {
+        created.push(['app', input]);
+        return { appId: '77', name: input.name, slug: input.slug };
+      }),
+    },
+    appAccess: {
+      tiers: vi.fn(async () => overrides.tiers ?? []),
+      createTier: vi.fn(async (input: Any) => {
+        created.push(['tier', input]);
+        return { tierId: 't1', name: input.name, permissionKeys: input.permissionKeys };
+      }),
+      updateTier: vi.fn(async (id: string, input: Any) => {
+        created.push(['tierUpdate', id, input]);
+        return { tierId: id, name: 'Constructor', permissionKeys: input.permissionKeys };
+      }),
+      myAccess: vi.fn(async () => overrides.myAccess ?? null),
+      grant: vi.fn(async (input: Any) => {
+        created.push(['grant', input]);
+        return { tierId: input.tierId };
+      }),
+    },
+  };
+}
+
+describe('onboarding steps', () => {
+  it('slugifies names conservatively', () => {
+    expect(steps.slugify("Neo's Studio!")).toBe('neo-s-studio');
+    expect(steps.slugify('   ')).toBe('construct');
+  });
+
+  it('creates an org only when the account has none', async () => {
+    const fresh = identityStub();
+    const a = await steps.ensureOrganization(fresh as never, { name: 'My studio' });
+    expect(a.created).toBe(true);
+    expect(fresh.organizations.create).toHaveBeenCalledWith({
+      name: 'My studio',
+      slug: 'my-studio',
+    });
+
+    const existing = identityStub({
+      orgs: [{ org: { orgId: '5', slug: 'x', name: 'X' }, permissions: ['manage_apps'] }],
+    });
+    const b = await steps.ensureOrganization(existing as never, { name: 'ignored' });
+    expect(b.created).toBe(false);
+    expect(b.org.orgId).toBe('5');
+    expect(existing.organizations.create).not.toHaveBeenCalled();
+  });
+
+  it('reuses an app by slug and otherwise picks the least-loaded placeable datacenter', async () => {
+    const reuse = identityStub({ apps: [{ appId: '9', slug: 'the-construct', name: 'Old' }] });
+    const a = await steps.ensureApp(reuse as never, {
+      orgId: '1',
+      orgSlug: 'o',
+      name: 'The Construct',
+      slug: 'the-construct',
+    });
+    expect(a.created).toBe(false);
+    expect(reuse.apps.create).not.toHaveBeenCalled();
+
+    const fresh = identityStub();
+    const b = await steps.ensureApp(fresh as never, {
+      orgId: '1',
+      orgSlug: 'o',
+      name: 'The Construct',
+      slug: 'the-construct',
+    });
+    expect(b.created).toBe(true);
+    expect(fresh.apps.create.mock.calls[0][0].datacenter).toBe('or');
+  });
+
+  it('refuses when no datacenter can place an app', async () => {
+    const none = identityStub({ datacenters: [{ code: 'or', placeable: false, serving: true }] });
+    await expect(
+      steps.ensureApp(none as never, { orgId: '1', orgSlug: 'o', name: 'A', slug: 'a' }),
+    ).rejects.toThrow(/No datacenter/);
+  });
+
+  it('creates the Constructor tier with the code keys, widens the default tier, and grants once', async () => {
+    const fresh = identityStub({
+      tiers: [
+        {
+          tierId: 'd',
+          name: 'Default',
+          isDefault: true,
+          status: 'active',
+          permissionKeys: ['access'],
+        },
+      ],
+    });
+    const a = await steps.ensureConstructorTier(fresh as never, { appId: '77', userId: '42' });
+    expect(a.created).toBe(true);
+    expect(a.granted).toBe(true);
+    const tierInput = fresh.appAccess.createTier.mock.calls[0][0];
+    expect(tierInput.permissionKeys).toEqual(
+      expect.arrayContaining([...steps.CONSTRUCTOR_TIER_KEYS]),
+    );
+    expect(tierInput.isDefault).toBe(false);
+    const defaultUpdate = (fresh.appAccess.updateTier.mock.calls as Any[][]).find(
+      (c) => c[0] === 'd',
+    );
+    expect(defaultUpdate?.[1].permissionKeys).toEqual(
+      expect.arrayContaining([...steps.VISITOR_RUN_KEYS]),
+    );
+    expect(fresh.appAccess.grant).toHaveBeenCalledWith({ appId: '77', userId: '42', tierId: 't1' });
+
+    const already = identityStub({
+      tiers: [
+        {
+          tierId: 'd',
+          name: 'Default',
+          isDefault: true,
+          status: 'active',
+          permissionKeys: ['access', ...steps.VISITOR_RUN_KEYS],
+        },
+        {
+          tierId: 't1',
+          name: 'Constructor',
+          status: 'active',
+          permissionKeys: [...steps.CONSTRUCTOR_TIER_KEYS],
+        },
+      ],
+      myAccess: { tierId: 't1', status: 'active' },
+    });
+    const b = await steps.ensureConstructorTier(already as never, { appId: '77', userId: '42' });
+    expect(b.created).toBe(false);
+    expect(b.granted).toBe(false);
+    expect(already.appAccess.grant).not.toHaveBeenCalled();
+    expect(already.appAccess.updateTier).not.toHaveBeenCalled();
+  });
+
+  it('only sets the claim policy when it differs', async () => {
+    const game = {
+      marketplace: {
+        gridClaimPolicy: vi.fn(async () => 'SELF_CLAIM'),
+        setGridClaimPolicy: vi.fn(),
+      },
+    };
+    expect(await steps.ensureSelfClaimPolicy(game as never, { appId: '77' })).toEqual({
+      policy: 'SELF_CLAIM',
+      changed: false,
+    });
+    expect(game.marketplace.setGridClaimPolicy).not.toHaveBeenCalled();
+    game.marketplace.gridClaimPolicy = vi.fn(async () => 'APPROVAL');
+    expect(await steps.ensureSelfClaimPolicy(game as never, { appId: '77' })).toEqual({
+      policy: 'SELF_CLAIM',
+      changed: true,
+    });
+  });
+
+  it('does not re-seed containers that already exist', async () => {
+    const deploy = vi.fn(async () => ({
+      seed: { containersCreated: 0 },
+      automations: [],
+      warnings: [],
+    }));
+    const game = {
+      kit: () => ({ deploy }),
+      gameModel: {
+        containers: vi.fn(async ({ typeName }: Any) =>
+          typeName === 'WorldState' ? [{ displayName: 'The Construct' }] : [],
+        ),
+      },
+    };
+    await steps.deployModel(game as never, {
+      appId: '77',
+      blueprints: [
+        {
+          name: 'construct-world',
+          containers: [
+            { typeName: 'WorldState', displayName: 'The Construct' },
+            { typeName: 'Program', displayName: 'Paint' },
+          ],
+        },
+      ],
+    });
+    const blueprints = (deploy.mock.calls as Any[][])[0]![0] as Any[];
+    const world = blueprints.find((b) => b.name === 'construct-world')!;
+    expect(world.containers.map((c: Any) => c.typeName)).toEqual(['Program']);
+  });
+
+  const execManifest = {
+    root: 'construct',
+    types: {
+      construct: { kind: 'hub', crate: 'construct', client: true },
+      world: { kind: 'hub', parent: 'construct', crate: 'construct', client: true },
+    },
+  };
+  const execCrates = [{ name: 'construct', files: { 'Cargo.toml': '', 'src/lib.rs': '' } }];
+
+  function execStub(build: Any = { status: 'succeeded', log: '' }) {
+    const calls: string[] = [];
+    const exec = {
+      build: vi.fn(async () => {
+        calls.push('build');
+        return { buildId: 'b1', status: 'queued' };
+      }),
+      waitForBuild: vi.fn(async () => {
+        calls.push('wait');
+        return {
+          buildId: 'b1',
+          artifacts: [{ crate: 'construct', sizeBytes: 10, digest: 'd' }],
+          ...build,
+        };
+      }),
+      deploy: vi.fn(async () => {
+        calls.push('deploy');
+        return { version: 3 };
+      }),
+      setEnabled: vi.fn(async (_appId: string, on: boolean, nodeType: string) => {
+        calls.push(`${nodeType}:${on ? 'on' : 'off'}`);
+      }),
+    };
+    return { client: { exec, close: vi.fn() }, exec, calls };
+  }
+
+  it('builds the ck-exec crates on the platform and deploys that build', async () => {
+    const { client, exec, calls } = execStub();
+    const result = await steps.deployExec(client as never, {
+      appId: '77',
+      manifest: execManifest as never,
+      crates: execCrates,
+    });
+    expect(result).toEqual({ buildId: 'b1', version: 3, restarted: [] });
+    expect(exec.build).toHaveBeenCalledWith('77', execCrates);
+    expect(exec.deploy).toHaveBeenCalledWith({
+      appId: '77',
+      root: 'construct',
+      types: execManifest.types,
+      buildId: 'b1',
+    });
+    expect(calls).toEqual(['build', 'wait', 'deploy']);
+  });
+
+  it('switches the named types off and on after the deploy when asked to restart', async () => {
+    const { client, calls } = execStub();
+    let retried = 0;
+    await steps.deployExec(client as never, {
+      appId: '77',
+      manifest: execManifest as never,
+      crates: execCrates,
+      restart: ['construct', 'world'],
+      restartPauseMs: 0,
+      retry: async (request) => {
+        retried += 1;
+        return request();
+      },
+    });
+    expect(calls).toEqual([
+      'build',
+      'wait',
+      'deploy',
+      'construct:off',
+      'world:off',
+      'construct:on',
+      'world:on',
+    ]);
+    expect(retried).toBe(7);
+  });
+
+  it('refuses to deploy a failed build and shows why', async () => {
+    const { client, exec } = execStub({ status: 'failed', log: 'error[E0425]: cannot find value' });
+    await expect(
+      steps.deployExec(client as never, {
+        appId: '77',
+        manifest: execManifest as never,
+        crates: execCrates,
+      }),
+    ).rejects.toThrow(/build b1 failed:\nerror\[E0425\]/);
+    expect(exec.deploy).not.toHaveBeenCalled();
+  });
+
+  it('runs the ck-exec step, on its own client, where a game has no model', async () => {
+    const identity = identityStub();
+    identity.marketplace = {
+      gridClaimPolicy: vi.fn(async () => 'SELF_CLAIM'),
+      setGridClaimPolicy: vi.fn(),
+    };
+    identity.graphql = {
+      query: vi.fn(async () => {
+        throw new Error('manage_compute required');
+      }),
+    };
+    const game = { crowdyStudio: { listCommonFiles: vi.fn(async () => []) }, kit: vi.fn() };
+    const { client, calls } = execStub();
+    const clientFor = vi.fn(async () => client);
+    const done: string[] = [];
+    const report = await steps.runOnboarding({
+      identity,
+      userId: '42',
+      enterApp: async () => game as never,
+      orgName: 'My studio',
+      appName: 'The Construct',
+      exec: { manifest: execManifest as never, crates: execCrates, client: clientFor as never },
+      onStep: (event) => {
+        if (event.status === 'done') done.push(event.id);
+      },
+    });
+    expect(report.appId).toBe('77');
+    expect(done).toEqual([
+      'org',
+      'app',
+      'tier',
+      'enter',
+      'claims',
+      'exec',
+      'studio',
+      'agent',
+      'github',
+    ]);
+    expect(clientFor).toHaveBeenCalledWith('77');
+    expect(calls).toEqual(['build', 'wait', 'deploy']);
+    expect(client.close).toHaveBeenCalled();
+    expect(game.kit).not.toHaveBeenCalled();
+  });
+
+  it('keeps use_studio_agent on Constructor and off the visitor default', () => {
+    expect(steps.CONSTRUCTOR_TIER_KEYS).toContain('use_studio_agent');
+    expect(steps.VISITOR_RUN_KEYS).not.toContain('use_studio_agent');
+  });
+
+  it('writes only the app agent policy and never calls cp* fields', async () => {
+    const query = vi.fn(async (document: string, _variables?: Any) => {
+      expect(document).not.toMatch(/\bcp[A-Z]/);
+      if (document.includes('ConstructSetAgentPolicy')) {
+        return {
+          setCrowdyStudioAgentPolicy: {
+            enabled: true,
+            killSwitch: false,
+            allowedModes: [...steps.STUDIO_AGENT_MODES],
+            revision: '1',
+          },
+        };
+      }
+      return {
+        crowdyStudioAgentPolicy: { enabled: false, revision: '0' },
+        crowdyStudioAgentEffectivePolicy: {
+          enabled: false,
+          killSwitch: false,
+          allowedModelIds: [...steps.STUDIO_AGENT_MODELS],
+          allowedModes: [],
+        },
+      };
+    });
+    const result = await steps.ensureAgentPolicy({ graphql: { query } } as never, { appId: '77' });
+    expect(result).toEqual({ enabled: true, skipped: false });
+    const appInput = (
+      query.mock.calls.find((c: Any[]) => String(c[0]).includes('ConstructSetAgentPolicy'))?.[1] as
+        { input: Any } | undefined
+    )?.input;
+    expect(appInput).toEqual(
+      expect.objectContaining({
+        appId: '77',
+        enabled: true,
+        allowedModes: [...steps.STUDIO_AGENT_MODES],
+        allowedModelIds: [...steps.STUDIO_AGENT_MODELS],
+        idempotencyKey: 'construct-agent-app-77-v5',
+      }),
+    );
+    expect(appInput?.allowedModelIds).toEqual([...steps.STUDIO_AGENT_MODELS]);
+    expect(appInput?.allowedToolNames).toBeUndefined();
+    expect(appInput?.allowedRiskClasses).toBeUndefined();
+  });
+
+  it('skips writes when effective policy already allows Ask/Build', async () => {
+    const ready = {
+      enabled: true,
+      killSwitch: false,
+      allowedModelIds: [steps.STUDIO_AGENT_MODEL],
+      allowedModes: [...steps.STUDIO_AGENT_MODES],
+    };
+    const query = vi.fn(async () => ({
+      crowdyStudioAgentPolicy: ready,
+      crowdyStudioAgentEffectivePolicy: ready,
+    }));
+    const result = await steps.ensureAgentPolicy({ graphql: { query } } as never, { appId: '77' });
+    expect(result).toEqual({ enabled: true, skipped: true });
+    expect(query.mock.calls.some((c: Any[]) => String(c[0]).includes('mutation'))).toBe(false);
+  });
+
+  it('stays green when the caller cannot read app policy', async () => {
+    const query = vi.fn(async () => {
+      throw new Error('manage_compute required');
+    });
+    const lines: string[] = [];
+    const result = await steps.ensureAgentPolicy(
+      { graphql: { query } } as never,
+      { appId: '77' },
+      (line) => lines.push(line),
+    );
+    expect(result).toEqual({ enabled: false, skipped: true });
+    expect(lines.some((line) => /Studio → your app → Agent/.test(line))).toBe(true);
+  });
+
+  it('stays green and logs when the platform catalog is unpublished after the app write', async () => {
+    const query = vi.fn(async (document: string) => {
+      expect(document).not.toMatch(/\bcp[A-Z]/);
+      if (document.includes('ConstructSetAgentPolicy')) {
+        return {
+          setCrowdyStudioAgentPolicy: {
+            enabled: true,
+            killSwitch: false,
+            allowedModes: [...steps.STUDIO_AGENT_MODES],
+          },
+        };
+      }
+      return {
+        crowdyStudioAgentPolicy: { enabled: false, revision: '0' },
+        crowdyStudioAgentEffectivePolicy: {
+          enabled: false,
+          killSwitch: false,
+          allowedModelIds: [],
+          allowedModes: [],
+        },
+      };
+    });
+    const lines: string[] = [];
+    const result = await steps.ensureAgentPolicy(
+      { graphql: { query } } as never,
+      { appId: '77' },
+      (line) => lines.push(line),
+    );
+    expect(result).toEqual({ enabled: true, skipped: false });
+    expect(lines.some((line) => /platform catalog not published/.test(line))).toBe(true);
+  });
+
+  it('checks GitHub integration status and logs advisory when unconnected', async () => {
+    const lines: string[] = [];
+    const unconnectedGame = {
+      crowdyStudioGitHub: {
+        status: async () => ({ connected: false, owner: null, repo: null }),
+      },
+    };
+    const resUnconnected = await steps.checkGitHubIntegration(
+      unconnectedGame as never,
+      { appId: '77' },
+      (l) => lines.push(l),
+    );
+    expect(resUnconnected.connected).toBe(false);
+    expect(resUnconnected.skipped).toBe(true);
+    expect(lines.some((l) => /Advisory: No GitHub repository bound/.test(l))).toBe(true);
+
+    const connectedGame = {
+      crowdyStudioGitHub: {
+        status: async () => ({ connected: true, owner: 'modder', repo: 'my-mod' }),
+      },
+    };
+    const resConnected = await steps.checkGitHubIntegration(connectedGame as never, {
+      appId: '77',
+    });
+    expect(resConnected.connected).toBe(true);
+    expect(resConnected.skipped).toBe(false);
+    expect(resConnected.repo).toBe('modder/my-mod');
+  });
+});

package/src/platform/realtime/WorldStores.ts

@@ -0,0 +1,153 @@
+/**
+ * The game's single World Stores session: SDK-managed state over ONE shared
+ * `udpNotifications` subscription.
+ *
+ *  - `self`   — the local actor: stable uuid, typed pose, 5 Hz send loop with
+ *               send-on-change dedup and keyframes. Scenes feed it a pose.
+ *  - `actors` — everyone else, decoded once and routed into lanes. Both scenes
+ *               render from `actors.lane('players')`; program-specific actors
+ *               would get their own lane.
+ *  - `chunks` — the voxel cache Paint draws in 2D and the holodeck draws as
+ *               cubes. CLIENT `voxel_set` writes here so other players see
+ *               the same blocks.
+ *  - `errors` — server-reported send failures attributed to what we sent.
+ *  - `events` — SERVER `emit_spatial("server_event")` catalog/pose packets
+ *               for the replicated instance layer (construct.scene.v1).
+ *  - `host`   — actor heartbeats (keeps presence fresh for server-side gates
+ *               such as player-compute occupancy; the elected host is
+ *               informational).
+ *  - `save`   — the typed per-user save blob, autosaved.
+ *
+ * Created lazily so it binds the ROUTED game client and the app the player
+ * actually entered; disposed when the player leaves the app.
+ */
+import {
+  createWorldSession,
+  jsonCodec,
+  localStorageUuidStore,
+  type WorldSession,
+} from '@crowdedkingdoms/crowdyjs/stores';
+
+import { ACTOR_SYNC_INTERVAL_MS, REPLICATION_DISTANCE, STALE_ACTOR_TIMEOUT_MS } from '../config';
+import { envScopedKey } from '../envScope';
+import { NetworkManager } from '../network/NetworkManager';
+import { NEUTRAL_POSE, poseCodec, type Pose } from './actorCodec';
+import { InstanceStore } from '../studio/instanceStore';
+
+/** What survives between sessions. Deliberately small; add fields freely. */
+export interface SaveState {
+  version: 1;
+  position?: { x: number; y: number; z: number; yaw: number };
+  lastProgram?: number;
+  visits: number;
+  tint?: number;
+}
+
+export const EMPTY_SAVE: SaveState = { version: 1, visits: 0 };
+
+function buildConfig() {
+  return {
+    self: {
+      codec: poseCodec,
+      initialState: NEUTRAL_POSE,
+      uuidStore: localStorageUuidStore(envScopedKey('construct:actor-uuid')),
+      sendIntervalMs: ACTOR_SYNC_INTERVAL_MS,
+      distance: REPLICATION_DISTANCE,
+    },
+    actors: {
+      codec: poseCodec,
+      staleAfterMs: STALE_ACTOR_TIMEOUT_MS,
+      historySize: 3,
+      lanes: {
+        players: () => true,
+      },
+    },
+    chunks: {
+      distance: REPLICATION_DISTANCE,
+      // The Construct has no terrain to generate: a chunk the server has never
+      // stored is simply empty. Seed it locally (no write-back) so the paint
+      // program and CLIENT mods always see a dense grid.
+      onMissing: () => ({ voxels: new Uint8Array(4096), writeBack: false }),
+    },
+    errors: true as const,
+    events: true as const,
+    host: {
+      intervalMs: 3_000,
+      myUserId: () => NetworkManager.instance.user?.userId ?? null,
+    },
+    save: {
+      codec: jsonCodec<SaveState>(),
+      autosaveMs: 10_000,
+    },
+  };
+}
+
+export type ConstructWorldSession = WorldSession<ReturnType<typeof buildConfig>>;
+
+let session: ConstructWorldSession | null = null;
+let sessionAppId: string | null = null;
+let instances: InstanceStore | null = null;
+
+/** The lazily created shared session for the CURRENT app. */
+export function worldSession(): ConstructWorldSession {
+  const network = NetworkManager.instance;
+  const appId = network.appId;
+  if (!appId) throw new Error('worldSession() needs an entered app');
+  if (session && sessionAppId !== appId) disposeWorldSession();
+  if (!session) {
+    session = createWorldSession(network.game, appId, buildConfig());
+    sessionAppId = appId;
+    instances = new InstanceStore(session.events);
+    session.errors.onError((error) => {
+      network.log(`UDP send error ${error.errorCode}${error.send ? ` (${error.send.kind})` : ''}`);
+    });
+  }
+  return session;
+}
+
+export function hasWorldSession(): boolean {
+  return session !== null;
+}
+
+export function disposeWorldSession(): void {
+  instances?.dispose();
+  instances = null;
+  session?.dispose();
+  session = null;
+  sessionAppId = null;
+}
+
+/** Replicated construct.scene.v1 instances for the current app. */
+export function instanceStore(): InstanceStore {
+  worldSession();
+  if (!instances) throw new Error('instanceStore() needs a world session');
+  return instances;
+}
+
+/** Remote players as the scenes want them: pose + chunk + freshness. */
+export interface RemotePlayer {
+  uuid: string;
+  pose: Pose;
+  /** Newest-first samples for interpolation. */
+  samples: Array<{ pose: Pose; epochMillis: number; receivedAt: number }>;
+  chunk: { x: number; y: number; z: number };
+  receivedAt: number;
+}
+
+export function remotePlayers(): RemotePlayer[] {
+  if (!session) return [];
+  return session.actors
+    .lane('players')
+    .list()
+    .map((actor) => ({
+      uuid: actor.uuid,
+      pose: actor.state,
+      samples: actor.samples.map((s) => ({
+        pose: s.state,
+        epochMillis: s.epochMillis,
+        receivedAt: s.receivedAt,
+      })),
+      chunk: { x: Number(actor.chunk.x), y: Number(actor.chunk.y), z: Number(actor.chunk.z) },
+      receivedAt: actor.receivedAt,
+    }));
+}

package/src/platform/realtime/actorCodec.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  FLAG_IN_PROGRAM,
+  FLAG_STUDIO_OPEN,
+  NAME_BYTES,
+  NEUTRAL_POSE,
+  POSE_BYTES,
+  decodeName,
+  encodeName,
+  poseCodec,
+  type Pose,
+} from './actorCodec';
+
+describe('poseCodec', () => {
+  it('is a fixed 64-byte layout', () => {
+    expect(POSE_BYTES).toBe(64);
+    const bytes = atob(poseCodec.encode(NEUTRAL_POSE)).length;
+    expect(bytes).toBe(64);
+  });
+
+  it('round-trips a pose (floats to f32 precision)', () => {
+    const pose: Pose = {
+      x: 12.5,
+      y: 0.25,
+      z: -7.75,
+      yaw: 1.5,
+      pitch: -0.125,
+      vx: 3,
+      vy: 0,
+      vz: -1.5,
+      flags: FLAG_IN_PROGRAM | FLAG_STUDIO_OPEN,
+      program: 1,
+      tint: 5,
+      name: 'neo',
+    };
+    const decoded = poseCodec.decode(poseCodec.encode(pose));
+    expect(decoded).toEqual(pose);
+  });
+
+  it('truncates names to the byte budget without splitting a character', () => {
+    const long = 'ünïcödé-name-that-is-far-too-long-for-the-wire';
+    const encoded = encodeName(long);
+    expect(encoded.length).toBe(NAME_BYTES);
+    const back = decodeName(encoded);
+    expect(long.startsWith(back)).toBe(true);
+    expect(new TextEncoder().encode(back).length).toBeLessThanOrEqual(NAME_BYTES);
+  });
+
+  it('masks flag/program/tint to one byte', () => {
+    const decoded = poseCodec.decode(
+      poseCodec.encode({ ...NEUTRAL_POSE, flags: 0x1ff, program: 300, tint: 264 }),
+    );
+    expect(decoded.flags).toBe(0xff);
+    expect(decoded.program).toBe(300 & 0xff);
+    expect(decoded.tint).toBe(264 & 0xff);
+  });
+
+  it('refuses a payload shorter than the layout', () => {
+    expect(() => poseCodec.decode('AA==')).toThrow(/structCodec/);
+  });
+});