@crowdedkingdoms/construct 0.3.1-dev.1 → 0.3.3-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.3.1-dev.1",
+  "version": "0.3.3-dev.1",
   "description": "The Construct framework: the Crowded Kingdoms game platform layer (hosted sign-in, World Stores, voice/webcam/chat, Crowdy Studio dock, app and grid mods, grid programs) and engine loop, shared by the-construct starter and the games built on it. Ships TypeScript source for Vite.",
   "license": "MIT",
   "type": "module",
@@ -45,8 +45,8 @@
     "./grid/*": "./src/grid/*.ts"
   },
   "peerDependencies": {
-    "@crowdedkingdoms/crowdyjs": ">=18.0.0-dev.0 <19 || >=18.0.1-dev.0 <19",
-    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1"
+    "@crowdedkingdoms/crowdyjs": ">=18.0.3-dev.0 <19",
+    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1 || >=0.4.3-dev.0 <1"
   },
   "peerDependenciesMeta": {
     "@crowdedkingdoms/crowdy-dsh": {

package/src/index.ts

@@ -91,4 +91,5 @@ export {
   type ClientHalvesGrid,
   type GridClientHalvesOptions,
 } from './platform/studio/clientHalves';
+export { gridServerCalls, type GridServerCallsOptions } from './platform/studio/gridServerCalls';
 export { GridProgramRunner, type GridProgramRunnerOptions } from './grid/GridProgramRunner';

package/src/platform/studio/StudioService.ts

@@ -24,7 +24,6 @@
  * is missing, saying so in the HUD, rather than letting a worker fail silently.
  */
 import {
-  createGridHostCalls,
   type ExecClientHalfPrompt,
   type ExecGridClientMod,
   type PlayerCodeHostCall,
@@ -39,6 +38,7 @@ import glueWorkerAssetUrl from '@crowdedkingdoms/crowdyjs/player-glue-worker?wor
 
 import { API_HTTP_URL, API_WS_URL, CLIENT_MODS_ENABLED, GAME_NAME, STUDIO_ORIGIN } from '../config';
 import { GridProgramRunner } from '../../grid/GridProgramRunner';
+import { gridServerCalls } from './gridServerCalls';
 import type { GameSession } from '../GameSession';
 import { messageOf } from '../network/NetworkManager';
 import { isTextEntry } from '../../engine/Input';
@@ -68,6 +68,8 @@ export interface StudioState {
   clientModsAvailable: boolean;
   /** The grid's CLIENT halves running for this player. */
   clientModsRunning: number;
+  /** Those CLIENT halves, for the controls that take them back. */
+  clientHalves: readonly RunningClientHalf[];
   /** Why CLIENT mods are unavailable, when they are. */
   clientModsReason: string | null;
   /** Agent dock mounted (policy + permission + host). */
@@ -76,6 +78,17 @@ export interface StudioState {
   agentReason: string | null;
 }
 
+/** A CLIENT half running for this player, and whose it is. */
+export interface RunningClientHalf {
+  modId: string;
+  name: string;
+  authorId: string;
+  /** The grid owner's display name, when the game knows it. */
+  authorName: string | null;
+  /** Written by this player (their own grid, not installed from a listing). */
+  own: boolean;
+}
+
 export interface StudioHooks {
   suppressGameplayInput(): () => void;
   onLayoutChange(rightInsetPx: number): void;
@@ -179,6 +192,7 @@ export class StudioService {
       grid: null,
       clientModsAvailable: CLIENT_MODS_ENABLED && isolated,
       clientModsRunning: 0,
+      clientHalves: [],
       clientModsReason: !CLIENT_MODS_ENABLED
         ? 'CLIENT mods are disabled in this build (VITE_CONSTRUCT_CLIENT_MODS=0).'
         : isolated
@@ -326,6 +340,37 @@ export class StudioService {
     this.openOn(grid);
   }
 
+  /** "Stop running this": the player takes back their consent to one CLIENT half here. */
+  async stopClientHalf(modId: string): Promise<void> {
+    await this.takeBack(`stopped the CLIENT half of mod ${modId}`, (halves) =>
+      halves.revoke(modId),
+    );
+  }
+
+  /** "Forget this author": the player takes back their trust in an author on this grid. */
+  async forgetClientHalfAuthor(authorId: string): Promise<void> {
+    await this.takeBack(`forgot author ${authorId} on this grid`, (halves) =>
+      halves.forgetAuthor(authorId),
+    );
+  }
+
+  private async takeBack(
+    done: string,
+    work: (halves: GridClientHalves) => Promise<boolean>,
+  ): Promise<void> {
+    const halves = this.halves;
+    if (!halves) return;
+    try {
+      await work(halves);
+      this.session.network.log(`CLIENT halves: ${done}`);
+    } catch (error) {
+      this.hooks?.notify(
+        `Stopped here, but the platform did not record it (${messageOf(error)}); it may run on your next visit.`,
+        'warn',
+      );
+    }
+  }
+
   close(): void {
     this.embed?.close();
     if (this.currentGrid) {
@@ -422,15 +467,14 @@ export class StudioService {
     gridId: string,
     bounds: GridBounds,
   ): (call: PlayerCodeHostCall) => Promise<unknown> {
-    const game = this.session.network.game;
-    const scope = game.grid(this.session.appId, gridId, toBrokerBounds(bounds));
-    return createGridHostCalls({
-      scope,
-      client: game,
-      local: {
-        gridPermissionKeys: () =>
-          this.currentGrid?.gridId === gridId ? this.currentGrid.permissions.effectiveKeys : [],
-      },
+    return gridServerCalls({
+      game: this.session.network.game,
+      appId: this.session.appId,
+      gridId,
+      bounds,
+      userId: this.session.network.user?.userId,
+      permissionKeys: () =>
+        this.currentGrid?.gridId === gridId ? this.currentGrid.permissions.effectiveKeys : [],
     });
   }
 
@@ -462,7 +506,18 @@ export class StudioService {
         }),
       filter: (mod) => !this.previewedByStudio(mod),
       onChange: (running) => {
-        this.state = { ...this.state, clientModsRunning: running.length };
+        const self = this.session.network.user?.userId ?? null;
+        const clientHalves = running.map((mod) => ({
+          modId: String(mod.modId),
+          name: mod.name,
+          authorId: String(mod.authorId),
+          authorName:
+            this.currentGrid?.gridId === String(mod.gridId)
+              ? (this.currentGrid.ownerName ?? null)
+              : null,
+          own: self !== null && String(mod.authorId) === String(self) && mod.listingId == null,
+        }));
+        this.state = { ...this.state, clientModsRunning: running.length, clientHalves };
         this.emit();
       },
       log: (line) => this.session.network.log(line),

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

@@ -16,6 +16,7 @@ vi.mock('@crowdedkingdoms/crowdyjs/crowdy-studio', async () => {
 const {
   GridClientHalves,
   clientHalfSource,
+  describeClientCapabilities,
   describeClientHalfPrompt,
   isOwnClientHalfPrompt,
   studioPreviewModName,
@@ -73,6 +74,8 @@ function harness(
     gridClientMods: vi.fn(async () => listings[Math.min(listed++, listings.length - 1)]!),
     consentClientMod: vi.fn(async () => true),
     trustAuthor: vi.fn(async () => true),
+    revokeClientModConsent: vi.fn(async () => true),
+    revokeAuthorTrust: vi.fn(async () => true),
     modClientArtifactBytes: vi.fn(async (_appId: string, modId: string) => {
       const mod = listings.flat().find((m) => m.modId === modId)!;
       return {
@@ -166,6 +169,31 @@ describe('GridClientHalves', () => {
     expect(h.serverCalls).toHaveBeenCalledWith(GRID);
   });
 
+  it('stops a CLIENT half the player takes back, and forgets its author, through the game client', async () => {
+    const h = harness({
+      listings: [
+        [
+          half({ callerConsented: true }),
+          half({ modId: 'm2', name: 'shop', digest: 'd2', callerConsented: true }),
+        ],
+      ],
+    });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+    expect(h.halves.running.map((m) => m.modId)).toEqual(['m1', 'm2']);
+
+    await expect(h.halves.revoke('m1')).resolves.toBe(true);
+    expect(h.exec.revokeClientModConsent).toHaveBeenCalledWith('1', 'm1');
+    expect(h.halves.running.map((m) => m.modId)).toEqual(['m2']);
+    expect(h.hud.remove).toHaveBeenCalledWith('grid:m1');
+
+    await expect(h.halves.forgetAuthor('7')).resolves.toBe(true);
+    expect(h.exec.revokeAuthorTrust).toHaveBeenCalledWith('1', '42', '7');
+    expect(h.halves.running).toEqual([]);
+    await h.halves.refresh();
+    expect(h.halves.running).toEqual([]);
+  });
+
   it("forwards a CLIENT half's log lines and invokes its handle_invoke", async () => {
     const lines: string[] = [];
     const h = harness({ log: (line) => lines.push(line) });
@@ -298,6 +326,20 @@ describe('client half prompts', () => {
     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');
+    expect(text).toContain('• it can read your saved state in this game');
+    expect(text).not.toContain('replace your saved state');
+  });
+
+  it('says in plain words what the calls that act as the player can do', () => {
+    const summary = {
+      ...SUMMARY,
+      hostFunctions: ['user_state_set', 'voxel_set', 'emit_spatial', 'constructor'],
+    };
+    const text = describeClientCapabilities(summary as never, JSON.stringify(summary));
+    expect(text).toContain('• it can replace your saved state in this game');
+    expect(text).toContain('• it can change blocks on this grid as you');
+    expect(text).toContain('• it can send messages and effects to players near you');
+    expect(text.split('\n').filter((line) => line.startsWith('• it can'))).toHaveLength(3);
   });
 
   it('asks about one CLIENT half, and shows a summary that does not parse as it is', () => {

package/src/platform/studio/clientHalves.ts

@@ -41,7 +41,12 @@ import type { ModOverlayStore } from './modOverlay';
 
 export type ClientHalvesExec = Pick<
   ExecAPI,
-  'gridClientMods' | 'consentClientMod' | 'trustAuthor' | 'modClientArtifactBytes'
+  | 'gridClientMods'
+  | 'consentClientMod'
+  | 'trustAuthor'
+  | 'modClientArtifactBytes'
+  | 'revokeClientModConsent'
+  | 'revokeAuthorTrust'
 >;
 
 /** The grid the player stands in: its id and chunk box. */
@@ -105,6 +110,9 @@ export class GridClientHalves {
         trustAuthor: (appId, gridId, authorId, hash) =>
           exec().trustAuthor(appId, gridId, authorId, hash),
         modClientArtifactBytes: (appId, modId) => exec().modClientArtifactBytes(appId, modId),
+        revokeClientModConsent: (appId, modId) => exec().revokeClientModConsent(appId, modId),
+        revokeAuthorTrust: (appId, gridId, authorId) =>
+          exec().revokeAuthorTrust(appId, gridId, authorId),
       },
       appId: options.appId,
       workerUrl: options.workerUrl,
@@ -162,6 +170,24 @@ export class GridClientHalves {
     return this.runner.invoke(modId, payload, options);
   }
 
+  /**
+   * "Stop running this": stops the CLIENT half of mod `modId` and takes back the player's consent
+   * to it (and their trust in its author, when it ran through that trust, keeping the author's
+   * other halves). Not asked about again on this grid until it changes. Rejects when the platform
+   * refuses; the half stays stopped here.
+   */
+  revoke(modId: string): Promise<boolean> {
+    return this.runner.revoke(modId);
+  }
+
+  /**
+   * "Forget this author": stops every CLIENT half of `authorId` on this grid and takes back the
+   * player's trust in them here, with every consent to their halves.
+   */
+  forgetAuthor(authorId: string): Promise<boolean> {
+    return this.runner.forgetAuthor(authorId);
+  }
+
   stop(): void {
     this.asking?.abort();
     this.asking = null;
@@ -273,6 +299,16 @@ export function describeClientHalfPrompt(
   return lines.join('\n');
 }
 
+/** What the host calls that act as the player let a CLIENT half do, in the player's words. */
+const ACTS_AS_YOU: Record<string, string> = {
+  user_state_get: 'read your saved state in this game',
+  user_state_set: 'replace your saved state in this game',
+  voxel_set: 'change blocks on this grid as you',
+  emit_spatial: 'send messages and effects to players near you, from your game',
+  emit_channel: "post in this grid's channels, from your game",
+  pointer_clicks: 'see your mouse clicks',
+};
+
 export function describeClientCapabilities(
   summary: ExecClientCapabilitySummary | null,
   json: string,
@@ -284,6 +320,9 @@ export function describeClientCapabilities(
   if (summary.capabilityGroups.length > 0) {
     rows.push(`• groups: ${summary.capabilityGroups.join(', ')}`);
   }
+  for (const fn of summary.hostFunctions) {
+    if (Object.hasOwn(ACTS_AS_YOU, fn)) rows.push(`• it can ${ACTS_AS_YOU[fn]}`);
+  }
   return rows.join('\n');
 }
 

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

@@ -185,6 +185,54 @@ describe('routeClientHostCall', () => {
     ]);
   });
 
+  it('writes no voxel outside the grid, whatever second chunk the call carries', async () => {
+    const r = reads();
+    const written: Array<{ chunk: { x: number; y: number; z: number } }> = [];
+    const writes = {
+      setVoxel: async (input: { chunk: { x: number; y: number; z: number } }) => {
+        written.push(input);
+        return true;
+      },
+    };
+    const voxel = { voxelX: 1, voxelY: 0, voxelZ: 2, voxelType: 7 };
+    // The broker checks chunkX/Y/Z against the grid; a call must not steer the write elsewhere.
+    for (const args of [
+      { chunkX: 0, chunkY: 0, chunkZ: 0, chunk: { x: 999, y: 0, z: 0 }, ...voxel },
+      { chunkX: 0, chunkY: 0, chunkZ: 0, chunk: [999, 0, 0], ...voxel },
+      { chunkX: 0, chunkY: 0, chunkZ: 0, chunk_x: 999, ...voxel },
+    ]) {
+      await routeClientHostCall({ fn: 'voxel_set', args } as never, r.reads, grid, writes);
+    }
+    expect(written.map((w) => w.chunk)).toEqual([
+      { x: 0, y: 0, z: 0 },
+      { x: 0, y: 0, z: 0 },
+      { x: 0, y: 0, z: 0 },
+    ]);
+    // Named only the second way, the chunk is checked against the grid at the write.
+    for (const args of [
+      { chunk: { x: 999, y: 0, z: 0 }, ...voxel },
+      { chunk_x: 5, chunk_y: 0, chunk_z: 0, ...voxel },
+      { chunkX: 2, chunkY: 0, chunkZ: 0, ...voxel },
+    ]) {
+      expect(
+        await routeClientHostCall({ fn: 'voxel_set', args } as never, r.reads, grid, writes),
+      ).toEqual({ ok: false, error: 'out_of_grid' });
+    }
+    expect(written.length).toBe(3);
+  });
+
+  it('refuses voxel_set without the grid to confine it to', async () => {
+    const r = reads();
+    await expect(
+      routeClientHostCall(
+        { fn: 'voxel_set', args: { chunkX: 0, chunkY: 0, chunkZ: 0, voxelType: 1 } } as never,
+        r.reads,
+        undefined,
+        { setVoxel: async () => true },
+      ),
+    ).rejects.toBeInstanceOf(HostCallRefusedError);
+  });
+
   it('parses flattened chunkX host-call args the broker clamps', () => {
     expect(
       parseVoxelSetArgs({

package/src/platform/studio/clientModHost.ts

@@ -110,9 +110,10 @@ export async function routeClientHostCall(
         : { voxels: voxelsFromBase64(chunk.voxelsBase64) };
     }
     case 'voxel_set': {
-      if (!writes) throw new HostCallRefusedError(fn);
+      if (!writes || !grid) throw new HostCallRefusedError(fn);
       const parsed = parseVoxelSetArgs(args);
       if (!parsed) return { ok: false, error: 'invalid voxel_set arguments' };
+      if (!chunkInGrid(parsed.chunk, grid)) return { ok: false, error: 'out_of_grid' };
       const ok = await writes.setVoxel({
         chunk: parsed.chunk,
         x: parsed.x,
@@ -163,7 +164,11 @@ function asCoord3(value: unknown): { x: unknown; y: unknown; z: unknown } | null
   return null;
 }
 
-/** Accept the SDKs' flattened host-call JSON (the broker clamps its chunk) and the tuple shape. */
+/**
+ * Accept the SDKs' flattened host-call JSON and the tuple shape. The chunk is `chunkX/Y/Z`, the
+ * fields the broker checks against the grid, whenever any of them is present; `args.chunk` only
+ * when none is. The caller still checks the chunk against the grid.
+ */
 export function parseVoxelSetArgs(args: Record<string, unknown>): {
   chunk: { x: number; y: number; z: number };
   x: number;
@@ -172,13 +177,15 @@ export function parseVoxelSetArgs(args: Record<string, unknown>): {
   voxelType: number;
   state: string;
 } | null {
-  const chunkRaw =
-    asCoord3(args.chunk) ??
-    ({
-      x: coordField(args, 'chunkX', 'chunk_x'),
-      y: coordField(args, 'chunkY', 'chunk_y'),
-      z: coordField(args, 'chunkZ', 'chunk_z'),
-    } as { x: unknown; y: unknown; z: unknown });
+  const flat = ['chunkX', 'chunkY', 'chunkZ'].some((key) => args[key] !== undefined);
+  const chunkRaw = flat
+    ? { x: args.chunkX, y: args.chunkY, z: args.chunkZ }
+    : (asCoord3(args.chunk) ??
+      ({
+        x: coordField(args, 'chunk_x'),
+        y: coordField(args, 'chunk_y'),
+        z: coordField(args, 'chunk_z'),
+      } as { x: unknown; y: unknown; z: unknown }));
   const voxelRaw =
     asCoord3(args.voxel) ??
     ({
@@ -248,6 +255,23 @@ export async function routeWithFallback(
   }
 }
 
+function chunkInGrid(
+  chunk: { x: number; y: number; z: number },
+  grid: PlayerCodeGridBounds,
+): boolean {
+  const x = BigInt(chunk.x);
+  const y = BigInt(chunk.y);
+  const z = BigInt(chunk.z);
+  return (
+    x >= grid.low.x &&
+    x <= grid.high.x &&
+    y >= grid.low.y &&
+    y <= grid.high.y &&
+    z >= grid.low.z &&
+    z <= grid.high.z
+  );
+}
+
 function minBig(a: bigint, b: bigint): bigint {
   return a < b ? a : b;
 }

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

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// The SDK barrel pulls Monaco, which does not load under happy-dom; the host-call module is
+// plain, so the test drives the real one.
+vi.mock('@crowdedkingdoms/crowdyjs', async () => {
+  const dist = '../../../../../node_modules/@crowdedkingdoms/crowdyjs/dist';
+  const calls = await import(/* @vite-ignore */ `${dist}/grid-mods/grid-host-calls.js`);
+  return { createGridHostCalls: calls.createGridHostCalls };
+});
+
+const { gridServerCalls } = await import('./gridServerCalls');
+
+const BOUNDS = { low: { x: '5', y: '0', z: '5' }, high: { x: '5', y: '0', z: '5' } };
+
+function game() {
+  const grid = vi.fn((appId: string, gridId: string, box: unknown) => ({
+    appId,
+    gridId,
+    bounds: box,
+    assertContains: () => {},
+    channels: { list: async () => [] },
+  }));
+  return { grid } as never;
+}
+
+const check = (userId: string, permissionKey: string) => ({
+  fn: 'grid_permission_check',
+  args: { userId, gridId: '42', permissionKey },
+});
+
+describe('gridServerCalls', () => {
+  it("answers grid_permission_check for the signed-in player from the grid's keys", async () => {
+    const calls = gridServerCalls({
+      game: game(),
+      appId: '1',
+      gridId: '42',
+      bounds: BOUNDS,
+      userId: '9',
+      permissionKeys: () => ['write_client_code', 'run_client_code'],
+    });
+    await expect(calls(check('9', 'run_client_code') as never)).resolves.toBe(true);
+    await expect(calls(check('9', 'write_server_code') as never)).resolves.toBe(false);
+    await expect(calls(check('8', 'run_client_code') as never)).rejects.toThrow(/another player/);
+  });
+
+  it('refuses it when no player is signed in', async () => {
+    const calls = gridServerCalls({
+      game: game(),
+      appId: '1',
+      gridId: '42',
+      bounds: BOUNDS,
+      userId: null,
+      permissionKeys: () => ['run_client_code'],
+    });
+    await expect(calls(check('9', 'run_client_code') as never)).rejects.toThrow();
+  });
+});

package/src/platform/studio/gridServerCalls.ts

@@ -0,0 +1,37 @@
+/**
+ * The CLIENT host calls a game's own router does not answer (DN-10): channels, sessions, user
+ * and avatar state, spatial sends and `grid_permission_check`, through CrowdyJS's
+ * `createGridHostCalls`, confined to one grid and answered as the player running the module.
+ * `grid_permission_check` needs both the player's user id and the keys the game holds for them
+ * on the grid; without either the SDK refuses it.
+ */
+import {
+  createGridHostCalls,
+  type CrowdyClient,
+  type PlayerCodeHostCall,
+} from '@crowdedkingdoms/crowdyjs';
+
+import { toBrokerBounds, type GridBounds } from './permissions';
+
+export interface GridServerCallsOptions {
+  game: CrowdyClient;
+  appId: string;
+  gridId: string;
+  bounds: GridBounds;
+  /** The signed-in player, the only one `grid_permission_check` answers about. */
+  userId: string | null | undefined;
+  /** The permission keys the game holds for that player on this grid. */
+  permissionKeys: () => Iterable<string>;
+}
+
+export function gridServerCalls(
+  options: GridServerCallsOptions,
+): (call: PlayerCodeHostCall) => Promise<unknown> {
+  const { game, appId, gridId, bounds, userId, permissionKeys } = options;
+  return createGridHostCalls({
+    scope: game.grid(appId, gridId, toBrokerBounds(bounds)),
+    client: game,
+    ...(userId ? { userId: String(userId) } : {}),
+    local: { gridPermissionKeys: permissionKeys },
+  });
+}