@crowdedkingdoms/construct 0.2.1-dev.1 → 0.2.3-dev.1

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

@@ -0,0 +1,328 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// The SDK barrel pulls Monaco, which does not load under happy-dom; the runner and the
+// Studio's project model are plain modules, so the tests drive the real ones.
+vi.mock('@crowdedkingdoms/crowdyjs', async () => {
+  const dist = '../../../../../node_modules/@crowdedkingdoms/crowdyjs/dist';
+  const halves = await import(/* @vite-ignore */ `${dist}/grid-mods/exec-client-halves.js`);
+  return { ExecClientHalves: halves.ExecClientHalves, PlayerCodeBroker: class {} };
+});
+vi.mock('@crowdedkingdoms/crowdyjs/crowdy-studio', async () => {
+  const dist = '../../../../../node_modules/@crowdedkingdoms/crowdyjs/dist';
+  const models = await import(/* @vite-ignore */ `${dist}/crowdy-studio/models.js`);
+  return { projectTargets: models.projectTargets };
+});
+
+const {
+  GridClientHalves,
+  clientHalfSource,
+  describeClientHalfPrompt,
+  isOwnClientHalfPrompt,
+  studioPreviewModName,
+} = await import('./clientHalves');
+
+const GRID = {
+  gridId: '42',
+  bounds: { low: { x: 5n, y: 0n, z: 5n }, high: { x: 5n, y: 0n, z: 5n } },
+};
+const SUMMARY = {
+  version: 1,
+  target: 'client' as const,
+  imports: ['ck.host_call'],
+  hostFunctions: ['hud_set', 'actors_list', 'user_state_get'],
+  capabilityGroups: ['present', 'world_read', 'state'],
+  presentationHooks: ['hud_set'],
+  exportedFunctions: ['init', 'tick'],
+};
+
+function half(overrides: Record<string, unknown> = {}) {
+  return {
+    modId: 'm1',
+    name: 'greeter',
+    gridId: '42',
+    authorId: '7',
+    listingId: null,
+    clientVersion: 1,
+    digest: 'd1',
+    capabilitySummaryJson: JSON.stringify(SUMMARY),
+    capabilitySummary: SUMMARY,
+    capabilityHash: 'h1',
+    tickIntervalMs: 1000,
+    callerConsented: false,
+    authorCapabilitySummaryJson: JSON.stringify(SUMMARY),
+    authorCapabilitySummary: SUMMARY,
+    authorCapabilityHash: 'ah1',
+    callerTrustsAuthor: false,
+    updatedAt: '2026-09-27T00:00:00Z',
+    ...overrides,
+  };
+}
+
+function harness(
+  options: {
+    listings?: Array<Array<ReturnType<typeof half>>>;
+    self?: string;
+    confirm?: (prompt: unknown, signal: AbortSignal) => Promise<boolean>;
+    filter?: (mod: { name: string }) => boolean;
+  } = {},
+) {
+  const listings = options.listings ?? [[half({ callerConsented: true })]];
+  let listed = 0;
+  const exec = {
+    gridClientMods: vi.fn(async () => listings[Math.min(listed++, listings.length - 1)]!),
+    consentClientMod: vi.fn(async () => true),
+    trustAuthor: vi.fn(async () => true),
+    modClientArtifactBytes: vi.fn(async (_appId: string, modId: string) => {
+      const mod = listings.flat().find((m) => m.modId === modId)!;
+      return {
+        modId,
+        name: mod.name,
+        gridId: mod.gridId,
+        clientVersion: mod.clientVersion,
+        bytes: new ArrayBuffer(8),
+        digest: mod.digest,
+        sizeBytes: 8,
+        fuelPerDispatch: 1_000_000n,
+        tickIntervalMs: mod.tickIntervalMs,
+        capabilitySummaryJson: mod.capabilitySummaryJson,
+        capabilitySummary: SUMMARY,
+        capabilityHash: mod.capabilityHash,
+        abiVersion: 0,
+      };
+    }),
+  };
+  const brokers: Array<{
+    options: {
+      onHostCall(call: unknown): Promise<unknown>;
+      onPresentation?(presentation: unknown): void;
+      consentedHostCalls?: readonly string[];
+      engine?: string;
+    };
+    stop: ReturnType<typeof vi.fn>;
+  }> = [];
+  const hud = { set: vi.fn(), remove: vi.fn() };
+  const overlay = { apply: vi.fn(), remove: vi.fn() };
+  const actorsInChunk = vi.fn(() => [{ uuid: 'u1', name: 'neo' }]);
+  const serverCall = vi.fn(async () => ({ state: 'from the server' }));
+  const serverCalls = vi.fn(() => serverCall);
+  const changes: number[] = [];
+  const halves = new GridClientHalves({
+    exec: () => exec as never,
+    appId: '1',
+    workerUrl: '/glue.js',
+    selfUserId: () => options.self ?? '9',
+    reads: { actorsInChunk, chunkVoxels: () => null },
+    serverCalls,
+    hud: hud as never,
+    overlay: overlay as never,
+    ...(options.confirm ? { confirm: options.confirm as never } : {}),
+    ...(options.filter ? { filter: options.filter as never } : {}),
+    onChange: (running) => changes.push(running.length),
+    brokerFactory: (brokerOptions) => {
+      const broker = { options: brokerOptions as never, stop: vi.fn() };
+      brokers.push(broker);
+      return { start: async () => {}, stop: broker.stop };
+    },
+  });
+  return { halves, exec, brokers, hud, overlay, actorsInChunk, serverCall, serverCalls, changes };
+}
+
+describe('GridClientHalves', () => {
+  it('runs a consented CLIENT half into the HUD and answers its host calls through the game', async () => {
+    const h = harness();
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+
+    expect(h.halves.running.map((m) => m.modId)).toEqual(['m1']);
+    expect(h.changes).toEqual([1]);
+    const [broker] = h.brokers;
+    expect(broker!.options.engine).toBe('ck-exec');
+    expect(broker!.options.consentedHostCalls).toEqual(SUMMARY.hostFunctions);
+
+    broker!.options.onPresentation?.({ channel: 'hud', payload: { greeting: 'hi' } });
+    expect(h.hud.set).toHaveBeenCalledWith({
+      source: 'grid:m1',
+      label: 'greeter',
+      payload: { greeting: 'hi' },
+    });
+    broker!.options.onPresentation?.({ channel: 'overlay', payload: { objects: [] } });
+    expect(h.overlay.apply).toHaveBeenCalledWith('grid:m1', { objects: [] }, GRID.bounds);
+
+    await expect(
+      broker!.options.onHostCall({ fn: 'actors_list', args: { x: '5', y: '0', z: '5' } }),
+    ).resolves.toEqual({ actors: [{ uuid: 'u1', name: 'neo' }] });
+    expect(h.actorsInChunk).toHaveBeenCalledWith(5n, 0n, 5n);
+    // What the game's router does not offer goes to the grid's server calls.
+    await expect(
+      broker!.options.onHostCall({ fn: 'user_state_get', args: { userId: '9' } }),
+    ).resolves.toEqual({ state: 'from the server' });
+    expect(h.serverCalls).toHaveBeenCalledWith(GRID);
+  });
+
+  it('asks about another author, and a yes trusts them at the hash the grid listed', async () => {
+    const asked: unknown[] = [];
+    const h = harness({
+      listings: [[half()], [half({ callerTrustsAuthor: true, callerConsented: true })]],
+      confirm: async (prompt) => {
+        asked.push(prompt);
+        return true;
+      },
+    });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+
+    expect(asked).toHaveLength(1);
+    expect(h.exec.trustAuthor).toHaveBeenCalledWith('1', '42', '7', 'ah1');
+    expect(h.halves.running.map((m) => m.modId)).toEqual(['m1']);
+  });
+
+  it('runs the player’s own CLIENT halves without asking', async () => {
+    const confirm = vi.fn(async () => false);
+    const h = harness({
+      self: '7',
+      listings: [[half()], [half({ callerTrustsAuthor: true, callerConsented: true })]],
+      confirm,
+    });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+
+    expect(confirm).not.toHaveBeenCalled();
+    expect(h.exec.trustAuthor).toHaveBeenCalledWith('1', '42', '7', 'ah1');
+    expect(h.halves.running).toHaveLength(1);
+  });
+
+  it('asks the owner about a CLIENT half installed from someone’s listing', async () => {
+    const confirm = vi.fn(async () => false);
+    const h = harness({ self: '7', listings: [[half({ listingId: '55' })]], confirm });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+
+    expect(confirm).toHaveBeenCalledTimes(1);
+    expect(h.exec.trustAuthor).not.toHaveBeenCalled();
+    expect(h.halves.running).toHaveLength(0);
+  });
+
+  it('runs nothing unconsented when the game asks nothing', async () => {
+    const h = harness({ listings: [[half()]] });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+
+    expect(h.exec.trustAuthor).not.toHaveBeenCalled();
+    expect(h.brokers).toHaveLength(0);
+  });
+
+  it('leaves out what the filter refuses, such as the half Crowdy Studio previews', async () => {
+    const h = harness({ filter: (mod) => mod.name !== 'greeter' });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+
+    expect(h.brokers).toHaveLength(0);
+    expect(h.exec.modClientArtifactBytes).not.toHaveBeenCalled();
+  });
+
+  it('stops its CLIENT halves and clears their HUD when the player leaves the grid', async () => {
+    const h = harness();
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+    const [broker] = h.brokers;
+
+    h.halves.enterGrid(null);
+    expect(broker!.stop).toHaveBeenCalled();
+    expect(h.hud.remove).toHaveBeenCalledWith('grid:m1');
+    expect(h.overlay.remove).toHaveBeenCalledWith('grid:m1');
+    expect(h.changes).toEqual([1, 0]);
+    // A late call from the stopped half does not reach the game.
+    await expect(
+      broker!.options.onHostCall({ fn: 'actors_list', args: { x: '5', y: '0', z: '5' } }),
+    ).rejects.toThrow(/no longer in this CLIENT half/);
+    expect(h.actorsInChunk).not.toHaveBeenCalled();
+  });
+
+  it('withdraws an unanswered question when the player leaves the grid', async () => {
+    let signal: AbortSignal | null = null;
+    const h = harness({
+      listings: [[half()]],
+      confirm: (_prompt, s) =>
+        new Promise((resolve) => {
+          signal = s;
+          s.addEventListener('abort', () => resolve(false));
+        }),
+    });
+    h.halves.enterGrid(GRID);
+    const refreshed = h.halves.refresh();
+    await vi.waitFor(() => expect(signal).not.toBeNull());
+
+    h.halves.enterGrid({ ...GRID, gridId: '43' });
+    expect(signal!.aborted).toBe(true);
+    await refreshed;
+    expect(h.exec.trustAuthor).not.toHaveBeenCalled();
+  });
+});
+
+describe('client half prompts', () => {
+  it('names the author, the halves, anything installed, and the host calls', () => {
+    const text = describeClientHalfPrompt(
+      {
+        kind: 'author',
+        gridId: '42',
+        authorId: '7',
+        capabilityHash: 'ah1',
+        capabilitySummaryJson: JSON.stringify(SUMMARY),
+        capabilitySummary: SUMMARY,
+        mods: [half(), half({ modId: 'm2', name: 'shop', listingId: '55' })] as never,
+      },
+      'trinity',
+    );
+    expect(text.split('\n')[0]).toBe("Run trinity's code on this grid?");
+    expect(text).toContain('greeter, shop will run in a sandbox in your browser');
+    expect(text).toContain('Installed from the marketplace: shop.');
+    expect(text).toContain('• host calls: hud_set, actors_list, user_state_get');
+    expect(text).toContain('• groups: present, world_read, state');
+  });
+
+  it('asks about one CLIENT half, and shows a summary that does not parse as it is', () => {
+    const text = describeClientHalfPrompt({
+      kind: 'mod',
+      gridId: '42',
+      authorId: '7',
+      capabilityHash: 'h1',
+      capabilitySummaryJson: '{"odd":true}',
+      capabilitySummary: null,
+      mods: [half()] as never,
+    });
+    expect(text.split('\n')[0]).toBe('Run the CLIENT half of greeter by player 7?');
+    expect(text).toContain('{"odd":true}');
+  });
+
+  it('counts only the player’s own, self-written halves as theirs', () => {
+    const prompt = (mods: unknown[]) =>
+      ({ kind: 'author', gridId: '42', authorId: '7', mods }) as never;
+    expect(isOwnClientHalfPrompt(prompt([half()]), '7')).toBe(true);
+    expect(isOwnClientHalfPrompt(prompt([half()]), '8')).toBe(false);
+    expect(isOwnClientHalfPrompt(prompt([half()]), null)).toBe(false);
+    expect(isOwnClientHalfPrompt(prompt([half(), half({ listingId: '55' })]), '7')).toBe(false);
+  });
+
+  it('keys the HUD by mod id', () => {
+    expect(clientHalfSource({ modId: 'abc' })).toBe('grid:abc');
+  });
+});
+
+describe('studioPreviewModName', () => {
+  const project = (kind: string, metadata: Record<string, string>) => ({ kind, metadata }) as never;
+
+  it('is the server module of a full-stack project and the client module of a CLIENT one', () => {
+    expect(
+      studioPreviewModName(
+        project('FULL_STACK', { serverModuleName: 'shop-server', clientModuleName: 'shop-client' }),
+      ),
+    ).toBe('shop-server');
+    expect(studioPreviewModName(project('CLIENT', { clientModuleName: ' hud-client ' }))).toBe(
+      'hud-client',
+    );
+  });
+
+  it('is none for a SERVER-only project, which previews no CLIENT half', () => {
+    expect(studioPreviewModName(project('SERVER', { serverModuleName: 'beacon' }))).toBeNull();
+  });
+});

package/src/platform/studio/clientHalves.ts

@@ -0,0 +1,291 @@
+/**
+ * The CLIENT halves of ck-exec mods on the grid the player stands in, run the
+ * way this framework runs player code: through the game's host-call router,
+ * into the text HUD and the holodeck overlay. CrowdyJS's `ExecClientHalves`
+ * lists what the grid serves, asks, fetches by digest and sandboxes each half
+ * in a `PlayerCodeBroker` (`engine: 'ck-exec'`); this adds what only the game
+ * knows. It replaces `runConsentedGridMod` + `ClientModLifecycle`, which run
+ * the legacy grid-attached client mods.
+ *
+ * The player's own CLIENT halves run without a question (on your own grid
+ * every half is yours), unless one was installed from a marketplace listing:
+ * that code is someone else's, so the owner is asked about it like a visitor.
+ */
+import {
+  ExecClientHalves,
+  type ExecAPI,
+  type ExecClientCapabilitySummary,
+  type ExecClientHalfError,
+  type ExecClientHalfPrompt,
+  type ExecClientHalfStopReason,
+  type ExecClientHalvesOptions,
+  type ExecGridClientMod,
+  type PlayerCodeGridBounds,
+  type PlayerCodeHostCall,
+  type PlayerCodePresentation,
+} from '@crowdedkingdoms/crowdyjs';
+import {
+  projectTargets,
+  type CrowdyStudioProject,
+  type CrowdyStudioTextHud,
+} from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+
+import {
+  routeClientHostCall,
+  routeWithFallback,
+  type ClientModHostInput,
+  type ClientModHostReads,
+  type ClientModHostWrites,
+} from './clientModHost';
+import type { ModOverlayStore } from './modOverlay';
+
+export type ClientHalvesExec = Pick<
+  ExecAPI,
+  'gridClientMods' | 'consentClientMod' | 'trustAuthor' | 'modClientArtifactBytes'
+>;
+
+/** The grid the player stands in: its id and chunk box. */
+export interface ClientHalvesGrid {
+  gridId: string;
+  bounds: PlayerCodeGridBounds;
+}
+
+export interface GridClientHalvesOptions {
+  /** The game client's `exec`, read at each call. */
+  exec: () => ClientHalvesExec;
+  appId: string;
+  /** The platform glue worker (`@crowdedkingdoms/crowdyjs/player-glue-worker`), same origin. */
+  workerUrl: string;
+  /** The signed-in player's user id. */
+  selfUserId: () => string | null;
+  reads: ClientModHostReads;
+  writes?: ClientModHostWrites;
+  input?: ClientModHostInput;
+  /**
+   * Answers the host calls the game's router does not (DN-10: `createGridHostCalls`
+   * over the grid's scope); made once per grid.
+   */
+  serverCalls?: (grid: ClientHalvesGrid) => (call: PlayerCodeHostCall) => Promise<unknown>;
+  hud: CrowdyStudioTextHud;
+  overlay?: ModOverlayStore;
+  /** One question per author (the default), or one per CLIENT half. */
+  ask?: 'author' | 'mod';
+  /**
+   * Asks the player about CLIENT halves they neither consented to nor trust the author of.
+   * `signal` aborts when they leave the grid. Without it only what the player already agreed
+   * to runs.
+   */
+  confirm?: (prompt: ExecClientHalfPrompt, signal: AbortSignal) => Promise<boolean>;
+  /** Leaves out the CLIENT halves it returns false for, e.g. the one Crowdy Studio previews. */
+  filter?: (mod: ExecGridClientMod) => boolean;
+  /** After a CLIENT half starts or stops. */
+  onChange?: (running: readonly ExecGridClientMod[]) => void;
+  log?: (line: string) => void;
+  brokerFactory?: ExecClientHalvesOptions['brokerFactory'];
+  now?: () => number;
+}
+
+export class GridClientHalves {
+  private readonly runner: ExecClientHalves;
+  private grid: ClientHalvesGrid | null = null;
+  private serverCalls: ((call: PlayerCodeHostCall) => Promise<unknown>) | null = null;
+  private asking: AbortController | null = null;
+
+  constructor(private readonly options: GridClientHalvesOptions) {
+    const exec = options.exec;
+    this.runner = new ExecClientHalves({
+      exec: {
+        gridClientMods: (appId, gridId) => exec().gridClientMods(appId, gridId),
+        consentClientMod: (appId, modId, hash) => exec().consentClientMod(appId, modId, hash),
+        trustAuthor: (appId, gridId, authorId, hash) =>
+          exec().trustAuthor(appId, gridId, authorId, hash),
+        modClientArtifactBytes: (appId, modId) => exec().modClientArtifactBytes(appId, modId),
+      },
+      appId: options.appId,
+      workerUrl: options.workerUrl,
+      ask: options.ask ?? 'author',
+      confirm: (prompt) => this.confirm(prompt),
+      filter: options.filter,
+      onHostCall: (call, mod) => this.hostCall(call, mod),
+      onPresentation: (presentation, mod) => this.present(presentation, mod),
+      onStarted: (mod) => {
+        this.options.log?.(`CLIENT half of mod ${mod.name} started (version ${mod.clientVersion})`);
+        this.options.onChange?.(this.running);
+      },
+      onStopped: (mod, reason) => this.stopped(mod, reason),
+      onError: (error) => this.options.log?.(this.describeError(error)),
+      ...(options.brokerFactory ? { brokerFactory: options.brokerFactory } : {}),
+      ...(options.now ? { now: options.now } : {}),
+    });
+  }
+
+  /** The CLIENT halves running now. */
+  get running(): readonly ExecGridClientMod[] {
+    return this.runner.running;
+  }
+
+  /** The grid the player stands in, or null; a change stops every CLIENT half of the old one. */
+  enterGrid(grid: ClientHalvesGrid | null): void {
+    if (sameGrid(this.grid, grid)) return;
+    this.asking?.abort();
+    this.asking = null;
+    this.grid = grid ? { gridId: grid.gridId, bounds: grid.bounds } : null;
+    this.serverCalls = null;
+    this.runner.enterGrid(
+      grid ? { gridId: grid.gridId, low: grid.bounds.low, high: grid.bounds.high } : null,
+    );
+  }
+
+  /** One reconcile of the grid's CLIENT halves; rejects when they cannot be listed. */
+  refresh(): Promise<void> {
+    return this.runner.refresh();
+  }
+
+  stop(): void {
+    this.asking?.abort();
+    this.asking = null;
+    this.grid = null;
+    this.serverCalls = null;
+    this.runner.stop();
+  }
+
+  private async confirm(prompt: ExecClientHalfPrompt): Promise<boolean> {
+    if (isOwnClientHalfPrompt(prompt, this.options.selfUserId())) return true;
+    if (!this.options.confirm) return false;
+    this.asking ??= new AbortController();
+    return this.options.confirm(prompt, this.asking.signal);
+  }
+
+  private hostCall(call: PlayerCodeHostCall, mod: ExecGridClientMod): Promise<unknown> {
+    const grid = this.grid;
+    if (!grid || String(mod.gridId) !== grid.gridId) {
+      return Promise.reject(new Error('the player is no longer in this CLIENT half’s grid'));
+    }
+    if (!this.serverCalls && this.options.serverCalls) {
+      this.serverCalls = this.options.serverCalls(grid);
+    }
+    const { reads, writes, input } = this.options;
+    return routeWithFallback(
+      call,
+      () => routeClientHostCall(call, reads, grid.bounds, writes, input),
+      this.serverCalls ?? undefined,
+    );
+  }
+
+  private present(presentation: PlayerCodePresentation, mod: ExecGridClientMod): void {
+    const grid = this.grid;
+    if (!grid || String(mod.gridId) !== grid.gridId) return;
+    const source = clientHalfSource(mod);
+    if (presentation.channel === 'hud') {
+      this.options.hud.set({ source, label: mod.name, payload: presentation.payload });
+    }
+    if (presentation.channel === 'overlay') {
+      this.options.overlay?.apply(source, presentation.payload, grid.bounds);
+    }
+  }
+
+  private stopped(mod: ExecGridClientMod, reason: ExecClientHalfStopReason): void {
+    const source = clientHalfSource(mod);
+    this.options.hud.remove(source);
+    this.options.overlay?.remove(source);
+    this.options.log?.(`CLIENT half of mod ${mod.name} stopped (${reason})`);
+    this.options.onChange?.(this.running);
+  }
+
+  private describeError(error: ExecClientHalfError): string {
+    const now = (this.options.now ?? Date.now)();
+    const again =
+      error.retryAt !== undefined
+        ? `; tried again in ${Math.max(0, Math.round((error.retryAt - now) / 1000))} s`
+        : '';
+    const detail = error.error instanceof Error ? error.error.message : String(error.error);
+    return `CLIENT half of mod ${error.mod.name}: ${error.stage} ${error.reason} (${detail})${again}`;
+  }
+}
+
+/** The HUD and overlay source a CLIENT half writes to. */
+export function clientHalfSource(mod: Pick<ExecGridClientMod, 'modId'>): string {
+  return `grid:${mod.modId}`;
+}
+
+/** The player's own CLIENT halves, none installed from a listing: they run without a question. */
+export function isOwnClientHalfPrompt(
+  prompt: ExecClientHalfPrompt,
+  selfUserId: string | null,
+): boolean {
+  return (
+    selfUserId !== null &&
+    String(prompt.authorId) === String(selfUserId) &&
+    prompt.mods.every((mod) => mod.listingId == null)
+  );
+}
+
+/** The question a player is asked about a grid's CLIENT halves, as plain text. */
+export function describeClientHalfPrompt(
+  prompt: ExecClientHalfPrompt,
+  authorName?: string | null,
+): string {
+  const who = authorName?.trim() || `player ${prompt.authorId}`;
+  const names = prompt.mods.map((mod) => mod.name);
+  const installed = prompt.mods.filter((mod) => mod.listingId != null).map((mod) => mod.name);
+  const lines =
+    prompt.kind === 'author'
+      ? [
+          `Run ${who}'s code on this grid?`,
+          '',
+          `${names.join(', ')} will run in a sandbox in your browser while you stand here. ` +
+            `Trusting ${who} covers their CLIENT halves on this grid until they need more than this.`,
+        ]
+      : [
+          `Run the CLIENT half of ${names[0] ?? 'this mod'} by ${who}?`,
+          '',
+          'It runs in a sandbox in your browser while you stand here.',
+        ];
+  if (installed.length > 0) {
+    lines.push('', `Installed from the marketplace: ${installed.join(', ')}.`);
+  }
+  lines.push(
+    '',
+    'It may use:',
+    describeClientCapabilities(prompt.capabilitySummary, prompt.capabilitySummaryJson),
+  );
+  return lines.join('\n');
+}
+
+export function describeClientCapabilities(
+  summary: ExecClientCapabilitySummary | null,
+  json: string,
+): string {
+  if (!summary) return json || '(no capability summary)';
+  const rows = [
+    `• host calls: ${summary.hostFunctions.length > 0 ? summary.hostFunctions.join(', ') : 'none'}`,
+  ];
+  if (summary.capabilityGroups.length > 0) {
+    rows.push(`• groups: ${summary.capabilityGroups.join(', ')}`);
+  }
+  return rows.join('\n');
+}
+
+/**
+ * The mod whose CLIENT half a Studio project previews on ck-exec: its SERVER module for a
+ * full-stack project, the CLIENT module a CLIENT-only project rides, and none for a
+ * SERVER-only project.
+ */
+export function studioPreviewModName(project: CrowdyStudioProject): string | null {
+  const targets = projectTargets(project.kind);
+  if (!targets.includes('CLIENT')) return null;
+  const name = targets.includes('SERVER')
+    ? project.metadata.serverModuleName
+    : project.metadata.clientModuleName;
+  return name?.trim() || null;
+}
+
+function sameGrid(a: ClientHalvesGrid | null, b: ClientHalvesGrid | null): boolean {
+  if (!a || !b) return a === b;
+  const corner = (c: { x: bigint; y: bigint; z: bigint }) => `${c.x},${c.y},${c.z}`;
+  return (
+    a.gridId === b.gridId &&
+    corner(a.bounds.low) === corner(b.bounds.low) &&
+    corner(a.bounds.high) === corner(b.bounds.high)
+  );
+}

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

@@ -56,7 +56,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 +68,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 +209,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([]);