@crowdedkingdoms/construct 0.2.2-dev.1 → 0.3.0-dev.1

package/src/platform/studio/clientModHost.test.ts

@@ -1,6 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
-
-vi.mock('@crowdedkingdoms/crowdyjs', () => ({ PlayerCodeBroker: class {} }));
+import { describe, expect, it } from 'vitest';
 
 const {
   DEFAULT_VOXEL_STATE,
@@ -56,7 +54,7 @@ describe('routeClientHostCall', () => {
     expect(out).toEqual({ actors: [{ uuid: 'me', name: 'neo' }] });
   });
 
-  it('clamps actors_list_radius to the grid and to radius 8', async () => {
+  it('clamps actors_list_radius to the grid', async () => {
     const r = reads();
     await routeClientHostCall(
       { fn: 'actors_list_radius', args: { x: '0', y: '0', z: '0', radius: 50 } } as never,
@@ -68,6 +66,23 @@ describe('routeClientHostCall', () => {
     expect(r.calls.every((c) => c.split(',').every((v) => Math.abs(Number(v)) <= 1))).toBe(true);
   });
 
+  it('reads crowdy-client-sdk radii and clamps them as the platform does (3 across, 1 up)', async () => {
+    const r = reads();
+    const wide = { low: { x: -9n, y: -9n, z: -9n }, high: { x: 9n, y: 9n, z: 9n } };
+    await routeClientHostCall(
+      {
+        fn: 'actors_list_radius',
+        args: { x: '0', y: '0', z: '0', radiusXz: 9, radiusY: 4 },
+      } as never,
+      r.reads,
+      wide,
+    );
+    expect(r.calls.length).toBe(7 * 3 * 7);
+    const ys = new Set(r.calls.map((c) => Number(c.split(',')[1])));
+    expect([...ys].sort()).toEqual([-1, 0, 1]);
+    expect(r.calls.every((c) => Math.abs(Number(c.split(',')[0])) <= 3)).toBe(true);
+  });
+
   it('serves chunk_get as base64 and voxels_list as sparse rows', async () => {
     const r = reads();
     const dense = (await routeClientHostCall(
@@ -192,6 +207,28 @@ describe('routeClientHostCall', () => {
     });
   });
 
+  it('parses the voxel_set arguments crowdy-client-sdk sends', () => {
+    expect(
+      parseVoxelSetArgs({
+        chunkX: 3,
+        chunkY: 0,
+        chunkZ: 3,
+        voxelX: 8,
+        voxelY: 1,
+        voxelZ: 4,
+        voxelType: 2,
+        stateBase64: null,
+      }),
+    ).toEqual({
+      chunk: { x: 3, y: 0, z: 3 },
+      x: 8,
+      y: 1,
+      z: 4,
+      voxelType: 2,
+      state: DEFAULT_VOXEL_STATE,
+    });
+  });
+
   it('decodes an empty grid to no rows', () => {
     expect(voxelsFromBase64(null)).toEqual([]);
     expect(voxelsFromBase64(bytesToBase64(new Uint8Array(4096)))).toEqual([]);

package/src/platform/studio/clientModHost.ts

@@ -1,25 +1,17 @@
 /**
- * The host side of CLIENT mods: what a sandboxed player module may ask the
- * game for, and how a consented grid-attached mod is started for a visitor.
+ * The host side of CLIENT mods: what a sandboxed player module (the Studio's
+ * preview, or a grid's CLIENT half, `clientHalves.ts`) may ask the game for.
  *
  * The SDK's `PlayerCodeBroker` has already validated every call against the
  * platform allowlist, clamped chunk coordinates to the mod's grid AABB, rate-
  * limited it, and answered `grid_info` / `hud_set` / `overlay_draw` itself.
  * What reaches `routeClientHostCall` is world_read, `voxel_set`, and
- * `pointer_clicks`. Reads return only what the running player can already
- * lawfully see. Writes go through ChunkStore.setVoxel (optimistic + UDP) and
- * markDirty (durable write-back), the same route Paint uses. Never hand a mod
- * the raw client.
+ * `pointer_clicks`, in the argument shapes `crowdy-client-sdk` sends. Reads
+ * return only what the running player can already lawfully see. Writes go
+ * through ChunkStore.setVoxel (optimistic + UDP) and markDirty (durable
+ * write-back), the same route Paint uses. Never hand a mod the raw client.
  */
-import {
-  PlayerCodeBroker,
-  type CrowdyClient,
-  type PlayerCodeGridBounds,
-  type PlayerCodeHostCall,
-  type PlayerCodePresentation,
-} from '@crowdedkingdoms/crowdyjs';
-import type { CrowdyStudioTextHud } from '@crowdedkingdoms/crowdyjs/crowdy-studio';
-import type { ModOverlayStore } from './modOverlay';
+import type { PlayerCodeGridBounds, PlayerCodeHostCall } from '@crowdedkingdoms/crowdyjs';
 
 export interface ClientModHostReads {
   actorsInChunk(x: bigint, y: bigint, z: bigint): Array<Record<string, unknown>>;
@@ -54,12 +46,19 @@ export const OFFERED_HOST_CALLS = [
 /** One zero byte, base64: the smallest non-empty voxel state the API accepts. */
 export const DEFAULT_VOXEL_STATE = 'AA==';
 
-const MAX_RADIUS = 8;
+/** `actors_list_radius` reaches this far, as the platform clamps it. */
+const MAX_RADIUS_XZ = 3;
+const MAX_RADIUS_Y = 1;
 
 function toBigInt(value: unknown): bigint {
   return BigInt(value as string | number | bigint);
 }
 
+function radius(value: unknown, max: number): bigint {
+  const requested = Number(value ?? 0);
+  return BigInt(Number.isFinite(requested) ? Math.max(0, Math.min(max, Math.floor(requested))) : 0);
+}
+
 export class HostCallRefusedError extends Error {
   constructor(readonly fn: string) {
     super(`host call '${fn}' is not offered by this game`);
@@ -80,22 +79,20 @@ export async function routeClientHostCall(
       return { actors: reads.actorsInChunk(toBigInt(args.x), toBigInt(args.y), toBigInt(args.z)) };
     case 'actors_list_radius': {
       const origin = { x: toBigInt(args.x), y: toBigInt(args.y), z: toBigInt(args.z) };
-      const requested = Number(args.radius ?? args.r ?? 0);
-      const radius = BigInt(
-        Number.isFinite(requested) ? Math.max(0, Math.min(MAX_RADIUS, Math.floor(requested))) : 0,
-      );
+      const rXz = radius(args.radiusXz ?? args.radius ?? args.r, MAX_RADIUS_XZ);
+      const rY = radius(args.radiusY, MAX_RADIUS_Y);
       const low = grid
         ? {
-            x: maxBig(grid.low.x, origin.x - radius),
-            y: maxBig(grid.low.y, origin.y - radius),
-            z: maxBig(grid.low.z, origin.z - radius),
+            x: maxBig(grid.low.x, origin.x - rXz),
+            y: maxBig(grid.low.y, origin.y - rY),
+            z: maxBig(grid.low.z, origin.z - rXz),
           }
         : origin;
       const high = grid
         ? {
-            x: minBig(grid.high.x, origin.x + radius),
-            y: minBig(grid.high.y, origin.y + radius),
-            z: minBig(grid.high.z, origin.z + radius),
+            x: minBig(grid.high.x, origin.x + rXz),
+            y: minBig(grid.high.y, origin.y + rY),
+            z: minBig(grid.high.z, origin.z + rXz),
           }
         : origin;
       const actors: Array<Record<string, unknown>> = [];
@@ -166,7 +163,7 @@ function asCoord3(value: unknown): { x: unknown; y: unknown; z: unknown } | null
   return null;
 }
 
-/** Accept the SDK tuple shape and the flattened host-call JSON the broker clamps. */
+/** Accept the SDKs' flattened host-call JSON (the broker clamps its chunk) and the tuple shape. */
 export function parseVoxelSetArgs(args: Record<string, unknown>): {
   chunk: { x: number; y: number; z: number };
   x: number;
@@ -185,9 +182,9 @@ export function parseVoxelSetArgs(args: Record<string, unknown>): {
   const voxelRaw =
     asCoord3(args.voxel) ??
     ({
-      x: coordField(args, 'x', 'vx'),
-      y: coordField(args, 'y', 'vy'),
-      z: coordField(args, 'z', 'vz'),
+      x: coordField(args, 'voxelX', 'x', 'vx'),
+      y: coordField(args, 'voxelY', 'y', 'vy'),
+      z: coordField(args, 'voxelZ', 'z', 'vz'),
     } as { x: unknown; y: unknown; z: unknown });
   const cx = intInRange(chunkRaw.x, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
   const cy = intInRange(chunkRaw.y, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
@@ -234,115 +231,6 @@ export function bytesToBase64(bytes: Uint8Array): string {
   return btoa(binary);
 }
 
-interface CachedArtifact {
-  bytes: Uint8Array;
-  artifactHash?: string;
-  fuelPerDispatch?: string | bigint;
-}
-
-const artifactCache = new Map<string, CachedArtifact>();
-
-/**
- * Fetch a consented grid-attached client mod's artifact and run it in a
- * hash-verified broker with the same allowlist, grid clamp, rate caps and
- * circuit breaker as the Studio's own Test/Run path. Its HUD output lands in
- * the persistent text HUD. Returns null (fails closed) when the artifact
- * cannot be fetched.
- */
-export async function runConsentedGridMod(options: {
-  client: CrowdyClient;
-  appId: string;
-  attachmentId: string;
-  artifactCacheKey: string;
-  hudSource: string;
-  hudLabel: string;
-  /** The module's name, which addressed grid events target (default `hudLabel`). */
-  moduleName?: string;
-  grid: PlayerCodeGridBounds;
-  workerUrl: string;
-  reads: ClientModHostReads;
-  writes?: ClientModHostWrites;
-  hud: CrowdyStudioTextHud;
-  overlay?: ModOverlayStore;
-  input?: ClientModHostInput;
-  /**
-   * Answers the host calls this game does not route itself (DN-10: the rest
-   * of the client catalog, through CrowdyJS `createGridHostCalls`).
-   */
-  serverCalls?: (call: PlayerCodeHostCall) => Promise<unknown>;
-  /**
-   * How often the worker self-drives `on_tick`. Omitted/0 means invoke-only
-   * and a HUD mod then never runs (measured 2026-09-07: broker started, HUD
-   * stayed empty). Studio Test/Deploy reads `[package.metadata.crowdy]
-   * tick_interval_ms` from the CLIENT Cargo.toml (default 1000, clamped
-   * 16–1000). Pass this only for grid-attached visitors until that field is
-   * stored on the compiled version.
-   */
-  tickIntervalMs?: number;
-}): Promise<{ stop: () => void } | null> {
-  let fetched: { bytes: ArrayBuffer; artifactHash?: string; fuelPerDispatch?: string | bigint };
-  const cached = artifactCache.get(options.artifactCacheKey);
-  if (cached) {
-    fetched = {
-      bytes: cached.bytes.slice().buffer,
-      artifactHash: cached.artifactHash,
-      fuelPerDispatch: cached.fuelPerDispatch,
-    };
-  } else {
-    try {
-      fetched = await options.client.marketplace.clientArtifactBytes({
-        appId: options.appId,
-        attachmentId: options.attachmentId,
-      });
-    } catch {
-      return null;
-    }
-    artifactCache.set(options.artifactCacheKey, {
-      bytes: new Uint8Array(fetched.bytes).slice(),
-      artifactHash: fetched.artifactHash,
-      fuelPerDispatch: fetched.fuelPerDispatch,
-    });
-  }
-  const broker = new PlayerCodeBroker({
-    workerUrl: options.workerUrl,
-    grid: options.grid,
-    artifactHash: fetched.artifactHash,
-    fuelPerDispatch: fetched.fuelPerDispatch != null ? BigInt(fetched.fuelPerDispatch) : undefined,
-    tickIntervalMs: options.tickIntervalMs ?? 1000,
-    moduleName: options.moduleName ?? options.hudLabel,
-    onHostCall: (call) =>
-      routeWithFallback(
-        call,
-        () => routeClientHostCall(call, options.reads, options.grid, options.writes, options.input),
-        options.serverCalls,
-      ),
-    onPresentation: (presentation: PlayerCodePresentation) => {
-      if (presentation.channel === 'hud') {
-        options.hud.set({
-          source: options.hudSource,
-          label: options.hudLabel,
-          payload: presentation.payload,
-        });
-      }
-      if (presentation.channel === 'overlay') {
-        options.overlay?.apply(options.hudSource, presentation.payload, options.grid);
-      }
-    },
-    onCircuitOpen: () => {
-      options.hud.remove(options.hudSource);
-      options.overlay?.remove(options.hudSource);
-    },
-  });
-  await broker.start(fetched.bytes);
-  return {
-    stop: () => {
-      broker.stop();
-      options.hud.remove(options.hudSource);
-      options.overlay?.remove(options.hudSource);
-    },
-  };
-}
-
 /**
  * The game's own router first (local reads, optimistic writes); anything it
  * does not offer goes to `serverCalls` when the game supplied it.

package/src/platform/studio/ClientModLifecycle.test.ts

@@ -1,56 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { ClientModLifecycle } from './ClientModLifecycle';
-
-const d = (id: string, artifactHash = 'a', capabilityHash = 'c') => ({
-  attachmentId: id,
-  artifactHash,
-  capabilityHash,
-});
-
-describe('ClientModLifecycle', () => {
-  it('stops every worker when the grid changes', () => {
-    const life = new ClientModLifecycle();
-    expect(life.enterGrid('g1')).toBe(true);
-    const scope = life.scope('g1')!;
-    const stop = vi.fn();
-    expect(life.track(scope, d('m1'), { stop })).toBe(true);
-    expect(life.enterGrid('g1')).toBe(false);
-    expect(life.enterGrid('g2')).toBe(true);
-    expect(stop).toHaveBeenCalledTimes(1);
-    expect(life.runningCount).toBe(0);
-  });
-
-  it('rejects a worker that finished starting after the grid changed', () => {
-    const life = new ClientModLifecycle();
-    life.enterGrid('g1');
-    const stale = life.scope('g1')!;
-    life.enterGrid('g2');
-    const stop = vi.fn();
-    expect(life.track(stale, d('m1'), { stop })).toBe(false);
-    expect(stop).toHaveBeenCalled();
-  });
-
-  it('reconciles by immutable hashes', () => {
-    const life = new ClientModLifecycle();
-    life.enterGrid('g1');
-    const scope = life.scope('g1')!;
-    const stopA = vi.fn();
-    const stopB = vi.fn();
-    life.track(scope, d('a'), { stop: stopA });
-    life.track(scope, d('b'), { stop: stopB });
-    expect(life.reconcile(scope, [d('a'), d('b', 'a2')])).toBe(true);
-    expect(stopA).not.toHaveBeenCalled();
-    expect(stopB).toHaveBeenCalled();
-    expect(life.has('a')).toBe(true);
-    expect(life.has('b')).toBe(false);
-  });
-
-  it('is inert after shutdown', () => {
-    const life = new ClientModLifecycle();
-    life.enterGrid('g1');
-    life.shutdown();
-    expect(life.enterGrid('g2')).toBe(false);
-    expect(life.scope('g2')).toBeNull();
-  });
-});

package/src/platform/studio/ClientModLifecycle.ts

@@ -1,102 +0,0 @@
-/**
- * Owns the worker handles of grid-attached CLIENT mods independently of any
- * scene. Every metadata refresh reconciles immutable hashes; changing grids
- * synchronously tears everything down; a worker that finishes starting after
- * a grid change (or shutdown) is stopped instead of attached stale.
- */
-export interface ClientModDescriptor {
-  attachmentId: string;
-  artifactHash: string;
-  capabilityHash: string;
-}
-
-export interface ClientModHandle {
-  stop: () => void;
-}
-
-export interface ClientModScope {
-  gridId: string;
-  generation: number;
-}
-
-interface RunningClientMod extends ClientModDescriptor, ClientModHandle {}
-
-export class ClientModLifecycle {
-  private readonly running = new Map<string, RunningClientMod>();
-  private activeGridId: string | null = null;
-  private generation = 0;
-  private stopped = false;
-
-  /** Returns true when the grid actually changed (callers reset their caches). */
-  enterGrid(gridId: string | null): boolean {
-    if (this.stopped) return false;
-    if (gridId === this.activeGridId) return false;
-    this.stopAll();
-    this.activeGridId = gridId;
-    this.generation++;
-    return true;
-  }
-
-  get currentGridId(): string | null {
-    return this.activeGridId;
-  }
-
-  has(attachmentId: string): boolean {
-    return this.running.has(attachmentId);
-  }
-
-  get runningCount(): number {
-    return this.running.size;
-  }
-
-  scope(gridId: string): ClientModScope | null {
-    if (this.stopped || gridId !== this.activeGridId) return null;
-    return { gridId, generation: this.generation };
-  }
-
-  isCurrent(scope: ClientModScope): boolean {
-    return (
-      !this.stopped && scope.gridId === this.activeGridId && scope.generation === this.generation
-    );
-  }
-
-  track(scope: ClientModScope, descriptor: ClientModDescriptor, handle: ClientModHandle): boolean {
-    if (!this.isCurrent(scope) || this.running.has(descriptor.attachmentId)) {
-      handle.stop();
-      return false;
-    }
-    this.running.set(descriptor.attachmentId, { ...descriptor, ...handle });
-    return true;
-  }
-
-  /** Stop mods that disappeared or changed hash; returns false if scope is stale. */
-  reconcile(scope: ClientModScope, descriptors: readonly ClientModDescriptor[]): boolean {
-    if (!this.isCurrent(scope)) return false;
-    const current = new Map(descriptors.map((d) => [d.attachmentId, d]));
-    for (const [attachmentId, running] of this.running) {
-      const next = current.get(attachmentId);
-      if (
-        !next ||
-        next.artifactHash !== running.artifactHash ||
-        next.capabilityHash !== running.capabilityHash
-      ) {
-        running.stop();
-        this.running.delete(attachmentId);
-      }
-    }
-    return true;
-  }
-
-  private stopAll(): void {
-    for (const running of this.running.values()) running.stop();
-    this.running.clear();
-  }
-
-  shutdown(): void {
-    if (this.stopped) return;
-    this.stopped = true;
-    this.activeGridId = null;
-    this.generation++;
-    this.stopAll();
-  }
-}