@crowdedkingdoms/construct 0.3.7 → 0.3.9-dev.1

package/README.md

@@ -30,7 +30,7 @@ Releases are on npm under one dist-tag per tier, and a game pins the exact
 version of its own tier, as it pins CrowdyJS:
 
 ```bash
-npm install --save-exact @crowdedkingdoms/construct   # X.Y.Z on latest
+npm install --save-exact @crowdedkingdoms/construct@dev   # an X.Y.Z-dev.N build
 ```
 
 `dev` is `X.Y.Z-dev.N`, `test` is `X.Y.Z-test.N`, and `prod` is `X.Y.Z` on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.3.7",
+  "version": "0.3.9-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,7 +45,7 @@
     "./grid/*": "./src/grid/*.ts"
   },
   "peerDependencies": {
-    "@crowdedkingdoms/crowdyjs": ">=18.0.4-dev.0 <19 || >=18.1.0-dev.0 <19 || >=18.2.0-dev.0 <19",
+    "@crowdedkingdoms/crowdyjs": ">=18.0.4-dev.0 <19 || >=18.1.0-dev.0 <19 || >=18.2.0-dev.0 <19 || >=18.3.0-dev.0 <19 || >=18.4.0-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 || >=0.4.4-dev.0 <1 || >=0.4.5-dev.0 <1"
   },
   "peerDependenciesMeta": {

package/src/engine/Input.test.ts

@@ -86,6 +86,32 @@ describe('Input', () => {
     expect(input.pointer.locked).toBe(false);
   });
 
+  it('aims from cursor movement on the canvas when movementX is stuck at 0', () => {
+    const { input, canvas } = attach();
+    canvas.className = 'scene-canvas';
+    window.dispatchEvent(
+      new PointerEvent('pointermove', {
+        clientX: 10,
+        clientY: 10,
+        movementX: 0,
+        movementY: 0,
+        bubbles: true,
+      }),
+    );
+    Object.defineProperty(canvas, 'closest', { value: () => canvas });
+    canvas.dispatchEvent(
+      new PointerEvent('pointermove', {
+        clientX: 30,
+        clientY: 14,
+        movementX: 0,
+        movementY: 0,
+        bubbles: true,
+      }),
+    );
+    expect(input.isLooking()).toBe(true);
+    expect(input.takePointerDelta()).toEqual({ dx: 20, dy: 4 });
+  });
+
   it('looks while RMB is held and cancels on exitLook', () => {
     const { input } = attach();
     window.dispatchEvent(new PointerEvent('pointerdown', { button: 2, buttons: 2 }));

package/src/engine/Input.ts

@@ -60,6 +60,10 @@ export class Input {
   private wheelY = 0;
   /** Escape cancels RMB look until the button is released. */
   private lookCancelled = false;
+  /** Pointer is over the holodeck canvas, so mouse movement aims. */
+  private overScene = false;
+  /** A client position has been seen, so the next move can be a delta. */
+  private hasClient = false;
 
   attach(target: HTMLElement): void {
     if (this.detach) return;
@@ -81,8 +85,23 @@ export class Input {
     const onBlur = () => this.keys.clear();
     const onPointerMove = (event: PointerEvent) => {
       if (this.suppressed) return;
-      this.pointerState.dx += event.movementX;
-      this.pointerState.dy += event.movementY;
+      const overScene =
+        event.target instanceof Element && Boolean(event.target.closest('.scene-canvas'));
+      this.overScene = overScene;
+      let dx = event.movementX;
+      let dy = event.movementY;
+      // The IDE browser reports movementX/Y as 0 unless the pointer is locked.
+      // Fall back to the cursor position so dragging on the canvas still aims.
+      if (!this.pointerState.locked && dx === 0 && dy === 0 && this.hasClient) {
+        dx = event.clientX - this.pointerState.x;
+        dy = event.clientY - this.pointerState.y;
+      }
+      this.hasClient = true;
+      const aiming = overScene || this.pointerState.locked || (this.pointerState.buttons & 2) !== 0;
+      if (aiming) {
+        this.pointerState.dx += dx;
+        this.pointerState.dy += dy;
+      }
       this.pointerState.x = event.clientX;
       this.pointerState.y = event.clientY;
       this.pointerState.buttons = event.buttons;
@@ -198,6 +217,7 @@ export class Input {
   isLooking(): boolean {
     if (this.suppressed) return false;
     if (this.pointerState.locked) return true;
+    if (this.overScene) return true;
     if (this.lookCancelled) return false;
     return (this.pointerState.buttons & 2) !== 0;
   }

package/src/platform/envScope.test.ts

@@ -5,8 +5,16 @@ vi.mock('@crowdedkingdoms/crowdyjs', () => ({
   CROWDY_DEFAULT_TIER: 'test',
 }));
 
-const { ENV_HANDLE, envHandleFor, envScopedKey, ensureEnvScope, readScoped, writeScoped } =
-  await import('./envScope');
+const {
+  ENV_HANDLE,
+  appTokenStorageKey,
+  envHandleFor,
+  envScopedKey,
+  ensureEnvScope,
+  perGameBase,
+  readScoped,
+  writeScoped,
+} = await import('./envScope');
 
 describe('envScope', () => {
   beforeEach(() => localStorage.clear());
@@ -23,6 +31,19 @@ describe('envScope', () => {
     expect(envScopedKey('x', 'other')).toBe('x:other');
   });
 
+  it('keys a saved app token by game path and API host', () => {
+    expect(appTokenStorageKey('/matchstick/')).toBe('crowdyjs:app:/matchstick/:ck.test.example');
+    expect(appTokenStorageKey('/blocks-with-friends/', 'ck.dev.example')).toBe(
+      'crowdyjs:app:/blocks-with-friends/:ck.dev.example',
+    );
+    expect(appTokenStorageKey('/matchstick/', 'ck.dev.example')).not.toBe(
+      appTokenStorageKey('/other-game/', 'ck.dev.example'),
+    );
+    expect(perGameBase('construct:app-route', '/matchstick/')).toBe(
+      'construct:app-route:/matchstick/',
+    );
+  });
+
   it('drops per-environment values when the environment changes', () => {
     localStorage.setItem('construct:env-handle', 'ck.old.example');
     localStorage.setItem('construct:app-id:ck.old.example', '111');

package/src/platform/envScope.ts

@@ -30,6 +30,29 @@ export function envScopedKey(base: string, handle: string = ENV_HANDLE): string
   return `${base}:${handle}`;
 }
 
+/**
+ * `<base>:<game-path>`, for `readScoped` / `writeScoped`, which append the host.
+ *
+ * The host alone is one key for every Construct game on a games host. Blocks
+ * with Friends keys its app token by `import.meta.env.BASE_URL` so two games
+ * do not share a session. Pass that base here.
+ */
+export function perGameBase(base: string, gamePath: string): string {
+  return `${base}:${gamePath}`;
+}
+
+/**
+ * localStorage key for the saved app token.
+ *
+ * Shape is `BrowserLocalStorageTokenStore.appKey(gamePath)` plus the API-host
+ * handle: `crowdyjs:app:/matchstick/:ck.dev.crowdedkingdoms.com`. The path
+ * keeps a second Construct game from restoring Matchstick's token. The handle
+ * keeps a localhost build pointed at another tier from restoring the first.
+ */
+export function appTokenStorageKey(gamePath: string, handle: string = ENV_HANDLE): string {
+  return envScopedKey(`crowdyjs:app:${gamePath}`, handle);
+}
+
 /** Keys that describe the previous environment and must not survive a switch. */
 const SCOPED_LOCAL_PREFIXES = ['construct:app-id', 'construct:last-program'];
 

package/src/platform/network/NetworkManager.ts

@@ -40,7 +40,13 @@ import {
   APP_TOKEN_REFRESH_RETRY_MS,
   AUTHORIZE_URL,
 } from '../config';
-import { envScopedKey, readScoped, writeScoped } from '../envScope';
+import {
+  appTokenStorageKey,
+  envScopedKey,
+  perGameBase,
+  readScoped,
+  writeScoped,
+} from '../envScope';
 import { WorldHub } from '../exec/worldHub';
 import { Emitter } from '../util/Emitter';
 
@@ -58,11 +64,13 @@ export interface AppRoute {
   expiresAt: string;
 }
 
-/** Where the entered app's route is remembered across a reload (env-scoped). */
+/** Where the entered app's route is remembered across a reload (per game path, per API host). */
 export const APP_ROUTE_STORAGE_KEY = 'construct:app-route';
 
-/** The token store key for the app token (env-scoped). One app at a time. */
-const APP_TOKEN_STORE_KEY = 'construct:app-token';
+/** Route key for this game's Vite base, before the API-host suffix `readScoped` adds. */
+function savedRouteBase(): string {
+  return perGameBase(APP_ROUTE_STORAGE_KEY, import.meta.env.BASE_URL);
+}
 
 export interface BootstrapInfo {
   minimumClientVersion?: string;
@@ -125,7 +133,7 @@ export class NetworkManager {
     this.platform = createCrowdyClient({
       httpUrl: API_HTTP_URL,
       wsUrl: API_WS_URL,
-      tokenStore: new BrowserLocalStorageTokenStore(envScopedKey(APP_TOKEN_STORE_KEY)),
+      tokenStore: new BrowserLocalStorageTokenStore(appTokenStorageKey(import.meta.env.BASE_URL)),
     });
   }
 
@@ -183,7 +191,7 @@ export class NetworkManager {
       const minted = await this.platform.portal.handleSignInCallback();
       if (!minted) return null;
       const route = this.routeFrom(minted, minted.appId);
-      writeScoped(APP_ROUTE_STORAGE_KEY, JSON.stringify(route));
+      writeScoped(savedRouteBase(), JSON.stringify(route));
       await this.hydrateUser();
       this.log(`Hosted sign-in complete for app ${route.appId}`);
       return route;
@@ -200,7 +208,7 @@ export class NetworkManager {
   async restore(): Promise<AppRoute | null> {
     await this.platform.session.restore();
     if (!this.platform.session.getToken()) return null;
-    const raw = readScoped(APP_ROUTE_STORAGE_KEY);
+    const raw = readScoped(savedRouteBase());
     let route: AppRoute | null;
     try {
       route = raw ? (JSON.parse(raw) as AppRoute) : null;
@@ -231,7 +239,7 @@ export class NetworkManager {
 
   private forgetCredentials(): void {
     this.platform.session.setToken(null);
-    writeScoped(APP_ROUTE_STORAGE_KEY, null);
+    writeScoped(savedRouteBase(), null);
   }
 
   private async hydrateUser(): Promise<SessionUser | null> {
@@ -346,7 +354,7 @@ export class NetworkManager {
     }
     this.gameClient.setToken(token);
     this.route = route;
-    writeScoped(APP_ROUTE_STORAGE_KEY, JSON.stringify(route));
+    writeScoped(savedRouteBase(), JSON.stringify(route));
     this.refreshFailures = 0;
     this.scheduleRefresh(APP_TOKEN_REFRESH_MS);
     this.log(`Entered app ${route.appId} via ${httpUrl}`);
@@ -417,7 +425,7 @@ export class NetworkManager {
       const refreshed = await this.gameClient.refreshGameplayToken();
       this.platform.session.setToken(refreshed.token);
       this.route = { ...this.route, expiresAt: refreshed.expiresAt };
-      writeScoped(APP_ROUTE_STORAGE_KEY, JSON.stringify(this.route));
+      writeScoped(savedRouteBase(), JSON.stringify(this.route));
       this.refreshFailures = 0;
       this.log('App token rotated');
       this.scheduleRefresh(APP_TOKEN_REFRESH_MS);

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

@@ -26,6 +26,7 @@ describe('poseCodec', () => {
       z: -7.75,
       yaw: 1.5,
       pitch: -0.125,
+      roll: 0.5,
       vx: 3,
       vy: 0,
       vz: -1.5,

package/src/platform/realtime/actorCodec.ts

@@ -17,7 +17,7 @@
  *   34    tint          u8   (avatar colour index)
  *   35    reserved      u8
  *   36-59 name          24 bytes UTF-8, NUL padded
- *   60-63 reserved
+ *   60-63 roll          f32
  */
 import {
   bytes,
@@ -40,6 +40,8 @@ export interface Pose {
   z: number;
   yaw: number;
   pitch: number;
+  /** Bank. Zero for the ground walker. A chunk mod in flight writes it. */
+  roll?: number;
   vx: number;
   vy: number;
   vz: number;
@@ -55,6 +57,7 @@ export const NEUTRAL_POSE: Pose = {
   z: 0,
   yaw: 0,
   pitch: 0,
+  roll: 0,
   vx: 0,
   vy: 0,
   vz: 0,
@@ -78,7 +81,7 @@ const wire = structCodec({
   tint: u8(),
   pad0: reserved(1),
   name: bytes(NAME_BYTES),
-  pad1: reserved(4),
+  roll: f32(),
 });
 
 const encoder = new TextEncoder();
@@ -112,6 +115,7 @@ export const poseCodec: StateCodec<Pose> = {
       z: pose.z,
       yaw: pose.yaw,
       pitch: pose.pitch,
+      roll: pose.roll ?? 0,
       vx: pose.vx,
       vy: pose.vy,
       vz: pose.vz,
@@ -128,6 +132,7 @@ export const poseCodec: StateCodec<Pose> = {
       z: raw.z,
       yaw: raw.yaw,
       pitch: raw.pitch,
+      roll: raw.roll,
       vx: raw.vx,
       vy: raw.vy,
       vz: raw.vz,

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

@@ -105,6 +105,23 @@ describe('GridService on the world hub registry', () => {
     expect(await new GridService(visitor.net).lookup({ x: 9, y: 0, z: 9 })).toBeNull();
   });
 
+  it("asks a player's session for the admin-only grid read once, then stops", async () => {
+    const owner = network('42');
+    const grids = new GridService(owner.net);
+    await grids.claimHere(AT, 'neo');
+    const probe = (
+      owner.net as unknown as {
+        game: { gameApps: { nearbyPermissions: ReturnType<typeof vi.fn> } };
+      }
+    ).game.gameApps.nearbyPermissions;
+    const before = probe.mock.calls.length;
+    await grids.lookup(AT);
+    await grids.lookup({ x: 9, y: 0, z: 9 });
+    await grids.lookup(AT);
+    expect(probe.mock.calls.length - before).toBeLessThanOrEqual(1);
+    expect((await grids.lookup(AT))?.owned).toBe(true);
+  });
+
   it('caches a chunk briefly and releases through the platform, then the registry', async () => {
     const { net, hub, claims, marketplace } = network();
     const grids = new GridService(net);

package/src/platform/studio/GridService.ts

@@ -75,6 +75,7 @@ export class GridService {
   private registryInFlight = new Map<string, Promise<ClaimRecord | null>>();
   /** Grids this session already tried to put in the registry from `lookup`. */
   private backfilled = new Set<string>();
+  private adminReadRefused = false;
 
   constructor(private readonly network: NetworkManager) {
     this.loadOwned();
@@ -122,7 +123,7 @@ export class GridService {
 
   /** The grid at `chunk` as this player may know it, or null for open world. */
   async lookup(chunk: ChunkCoord): Promise<GridSnapshot | null> {
-    const mine = this.ownedAt(chunk);
+    const mine = this.ownedAt(chunk) ?? (await this.discoverOwned(chunk));
     if (mine) {
       const refreshed = await this.refreshOwnedKeys(chunk, mine);
       // A grid claimed before the registry existed (or from a browser whose registry write
@@ -176,6 +177,63 @@ export class GridService {
 
   // ---------------------------------------------------------------------------
 
+  /**
+   * A fresh browser (another device, another origin) has no remembered claim.
+   * App admins can read the grid under their feet, including a claim wider
+   * than the single chunk stored in the Claim registry.
+   */
+  private async discoverOwned(chunk: ChunkCoord): Promise<OwnedRecord | null> {
+    const userId = this.network.user?.userId;
+    if (!userId || this.adminReadRefused) return null;
+    try {
+      const rows = (await this.network.game.gameApps.nearbyPermissions({
+        appId: this.requireAppId(),
+        userId,
+        lowChunk: chunkInput(chunk),
+        highChunk: chunkInput(chunk),
+      })) as Array<{
+        gridId?: unknown;
+        permissionKeys?: unknown;
+        lowChunk?: unknown;
+        highChunk?: unknown;
+      }>;
+      let best: OwnedRecord | null = null;
+      let bestVolume = 0n;
+      for (const row of rows) {
+        const gridId = String(row.gridId ?? '');
+        const bounds = gridBoundsFrom(row.lowChunk, row.highChunk);
+        if (!gridId || !bounds || !gridBoundsContain(bounds, chunk)) continue;
+        const keys = row.permissionKeys;
+        const effectiveKeys = studioPermissions(Array.isArray(keys) ? keys : null).effectiveKeys;
+        if (effectiveKeys.length === 0) continue;
+        const volume = boundsVolume(bounds);
+        if (best && volume >= bestVolume) continue;
+        best = { gridId, bounds, effectiveKeys };
+        bestVolume = volume;
+      }
+      if (!best) return null;
+      this.owned.set(chunkKey(chunk), best);
+      this.saveOwned();
+      return best;
+    } catch (error) {
+      this.noteAdminReadRefusal(error);
+      return null;
+    }
+  }
+
+  /**
+   * `nearbyGridPermissions` is app-admin only, so every ordinary player is refused it.
+   * After the first refusal this session asks no more, rather than logging a refusal on
+   * every lookup (OI-2026-10-07-008); an admin is never refused and keeps asking.
+   */
+  private noteAdminReadRefusal(error: unknown): void {
+    const e = error as { code?: unknown; message?: unknown } | null;
+    const message = typeof e?.message === 'string' ? e.message : '';
+    if (e?.code === 'FORBIDDEN' || /manage_apps|Missing app permission/i.test(message)) {
+      this.adminReadRefused = true;
+    }
+  }
+
   private ownedAt(chunk: ChunkCoord): OwnedRecord | null {
     const direct = this.owned.get(chunkKey(chunk));
     if (direct) return direct;
@@ -190,7 +248,7 @@ export class GridService {
     record: OwnedRecord,
   ): Promise<PlayerCodePermissionKey[] | null> {
     const userId = this.network.user?.userId;
-    if (!userId) return null;
+    if (!userId || this.adminReadRefused) return null;
     try {
       const rows = (await this.network.game.gameApps.nearbyPermissions({
         appId: this.requireAppId(),
@@ -200,13 +258,30 @@ export class GridService {
       })) as Array<{ gridId?: unknown; permissionKeys?: unknown }>;
       const row = rows.find((r) => String(r.gridId) === record.gridId);
       if (!row || !Array.isArray(row.permissionKeys)) return null;
+      const bounds = gridBoundsFrom(
+        (row as { lowChunk?: unknown }).lowChunk,
+        (row as { highChunk?: unknown }).highChunk,
+      );
+      if (
+        bounds &&
+        (bounds.low.x !== record.bounds.low.x ||
+          bounds.low.y !== record.bounds.low.y ||
+          bounds.low.z !== record.bounds.low.z ||
+          bounds.high.x !== record.bounds.high.x ||
+          bounds.high.y !== record.bounds.high.y ||
+          bounds.high.z !== record.bounds.high.z)
+      ) {
+        record.bounds = bounds;
+        this.saveOwned();
+      }
       const keys = studioPermissions(row.permissionKeys).effectiveKeys;
       if (keys.join() !== record.effectiveKeys.join()) {
         record.effectiveKeys = keys;
         this.saveOwned();
       }
       return keys;
-    } catch {
+    } catch (error) {
+      this.noteAdminReadRefusal(error);
       return null; // not an admin: the claim-time keys stand
     }
   }
@@ -293,3 +368,12 @@ export class GridService {
     writeScoped(OWNED_KEY, JSON.stringify(Object.fromEntries(this.owned)));
   }
 }
+
+function boundsVolume(bounds: GridBounds): bigint {
+  const span = (low: string, high: string) => BigInt(high) - BigInt(low) + 1n;
+  return (
+    span(bounds.low.x, bounds.high.x) *
+    span(bounds.low.y, bounds.high.y) *
+    span(bounds.low.z, bounds.high.z)
+  );
+}