@crowdedkingdoms/construct 0.0.0 → 0.2.1-dev.1

package/src/platform/GameSession.ts

@@ -0,0 +1,239 @@
+/**
+ * The engine-agnostic facade scenes receive. One instance per entered app.
+ *
+ * It wraps the World Stores session (presence, chunks, save), chat, webcam,
+ * voice, and the player's identity as a small, stable surface. Scenes read `players()` to
+ * render others and never touch the SDK; the loop calls `feedPose` / `moveTo`
+ * with what the active scene reports.
+ */
+import { NetworkManager } from './network/NetworkManager';
+import { FLAG_STUDIO_OPEN, NEUTRAL_POSE, type Pose } from './realtime/actorCodec';
+import { chunkInput, type ChunkCoord } from './realtime/space';
+import {
+  EMPTY_SAVE,
+  disposeWorldSession,
+  remotePlayers,
+  worldSession,
+  type ConstructWorldSession,
+  type RemotePlayer,
+  type SaveState,
+} from './realtime/WorldStores';
+import { WebcamService } from './media/WebcamService';
+import { VoiceService } from './media/VoiceService';
+import { ModelService } from './model/ModelService';
+import { ChatService } from './social/ChatService';
+import { StudioService } from './studio/StudioService';
+import { Emitter } from './util/Emitter';
+
+export interface GameSessionEvents {
+  joined: { chunk: ChunkCoord };
+  left: undefined;
+}
+
+export const TINT_COUNT = 8;
+
+export class GameSession {
+  readonly events = new Emitter<GameSessionEvents>();
+  readonly chat: ChatService;
+  /** Proximity webcam: `toggle()` to send; scenes listen for `frame`/`ended`. */
+  readonly webcam: WebcamService;
+  /** Proximity voice: `toggle()` to send; playback is automatic. */
+  readonly voice: VoiceService;
+  readonly studio: StudioService;
+  readonly model: ModelService;
+  /** Flipped by the Studio service so other players see the "coding" marker. */
+  studioOpen = false;
+
+  private joinedFlag = false;
+  private tintValue = 0;
+  private save: SaveState = { ...EMPTY_SAVE };
+
+  constructor(readonly network: NetworkManager = NetworkManager.instance) {
+    this.chat = new ChatService(network);
+    this.webcam = new WebcamService({
+      onVideo: (handler) => network.on('video', handler),
+      onActorLeft: (handler) => network.on('actorLeft', handler),
+      onLaneLeave: (handler) =>
+        this.world.actors.lane('players').onLeave((actor) => handler(actor.uuid)),
+      selfUuid: () => (this.joinedFlag ? this.world.self.uuid : null),
+      selfChunk: () => {
+        if (!this.joinedFlag) return null;
+        const chunk = this.world.self.chunk;
+        return chunk ? { x: String(chunk.x), y: String(chunk.y), z: String(chunk.z) } : null;
+      },
+      appId: () => this.appId,
+      sendVideoFrame: (input) => network.game.udp.sendVideoFrame(input),
+      log: (message) => network.log(message),
+    });
+    this.voice = new VoiceService({
+      onAudio: (handler) => network.on('audio', handler),
+      onActorLeft: (handler) => network.on('actorLeft', handler),
+      onLaneLeave: (handler) =>
+        this.world.actors.lane('players').onLeave((actor) => handler(actor.uuid)),
+      selfUuid: () => (this.joinedFlag ? this.world.self.uuid : null),
+      selfChunk: () => {
+        if (!this.joinedFlag) return null;
+        const chunk = this.world.self.chunk;
+        return chunk ? { x: String(chunk.x), y: String(chunk.y), z: String(chunk.z) } : null;
+      },
+      selfPosition: () => {
+        if (!this.joinedFlag) return null;
+        const pose = this.world.self.state;
+        return pose ? { x: pose.x, y: pose.y, z: pose.z } : null;
+      },
+      remotePositions: () =>
+        remotePlayers().map((player) => ({
+          uuid: player.uuid,
+          x: player.pose.x,
+          y: player.pose.y,
+          z: player.pose.z,
+        })),
+      appId: () => this.appId,
+      sendAudioPacket: (input) => network.game.udp.sendAudioPacket(input),
+      log: (message) => network.log(message),
+    });
+    this.studio = new StudioService(this);
+    this.model = new ModelService(this);
+  }
+
+  get appId(): string {
+    const appId = this.network.appId;
+    if (!appId) throw new Error('GameSession needs an entered app');
+    return appId;
+  }
+
+  get userId(): string {
+    return this.network.user?.userId ?? '';
+  }
+
+  /** What other players see over your head. */
+  get displayName(): string {
+    const user = this.network.user;
+    return (user?.gamertag || user?.email?.split('@')[0] || 'player').slice(0, 20);
+  }
+
+  get tint(): number {
+    return this.tintValue;
+  }
+
+  setTint(tint: number): void {
+    this.tintValue = ((tint % TINT_COUNT) + TINT_COUNT) % TINT_COUNT;
+    this.world.save.patch({ tint: this.tintValue });
+  }
+
+  get joined(): boolean {
+    return this.joinedFlag;
+  }
+
+  /** The World Stores session for this app (lazily created). */
+  get world(): ConstructWorldSession {
+    return worldSession();
+  }
+
+  get selfUuid(): string {
+    return this.world.self.uuid;
+  }
+
+  /** The saved state as loaded (or the empty default). */
+  get saved(): Readonly<SaveState> {
+    return this.save;
+  }
+
+  /** Load the save blob and hydrate identity-ish fields (tint). */
+  async loadSave(): Promise<SaveState> {
+    const loaded = await this.world.save.load();
+    this.save = loaded && loaded.version === 1 ? loaded : { ...EMPTY_SAVE };
+    if (!loaded) this.world.save.set(this.save);
+    if (this.save.tint !== undefined) this.tintValue = this.save.tint;
+    else this.setTint(hashTint(this.userId));
+    return this.save;
+  }
+
+  /** Announce presence at `position` and start receiving the world. */
+  async join(position: { x: number; y: number; z: number }): Promise<void> {
+    const chunk = chunkInput({
+      x: Math.floor(position.x / 16),
+      y: Math.floor(position.y / 16),
+      z: Math.floor(position.z / 16),
+    });
+    await this.world.self.join(chunk, {
+      ...NEUTRAL_POSE,
+      x: position.x,
+      y: position.y,
+      z: position.z,
+      name: this.displayName,
+      tint: this.tint,
+    });
+    this.joinedFlag = true;
+    this.chat.start();
+    this.webcam.listen();
+    this.voice.listen();
+    this.world.save.patch({ visits: (this.save.visits ?? 0) + 1 });
+    this.events.emit('joined', {
+      chunk: { x: Number(chunk.x), y: Number(chunk.y), z: Number(chunk.z) },
+    });
+  }
+
+  feedPose(pose: Pose): void {
+    if (!this.joinedFlag) return;
+    this.world.self.setState(pose);
+  }
+
+  extraPoseFlags(): number {
+    return this.studioOpen ? FLAG_STUDIO_OPEN : 0;
+  }
+
+  async moveTo(chunk: ChunkCoord): Promise<void> {
+    if (!this.joinedFlag) return;
+    try {
+      await this.world.self.moveTo(chunkInput(chunk));
+      await this.world.chunks.ensureAround(chunk, 1);
+    } catch (error) {
+      this.network.log(`moveTo failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  rememberPosition(sceneId: string, pose: Pose): void {
+    this.world.save.patch({
+      position: { x: pose.x, y: pose.y, z: pose.z, yaw: pose.yaw },
+      lastProgram: sceneId === 'holodeck' ? 0 : this.save.lastProgram,
+    });
+  }
+
+  rememberProgram(programId: number): void {
+    this.save = { ...this.save, lastProgram: programId };
+    this.world.save.patch({ lastProgram: programId });
+  }
+
+  /** Remote players, optionally only those in the same program. */
+  players(programId?: number): RemotePlayer[] {
+    const all = remotePlayers();
+    return programId === undefined ? all : all.filter((p) => p.pose.program === programId);
+  }
+
+  async flushSave(): Promise<void> {
+    try {
+      await this.world.save.save();
+    } catch (error) {
+      this.network.log(`save failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async leave(): Promise<void> {
+    if (!this.joinedFlag) return;
+    this.joinedFlag = false;
+    this.chat.stop();
+    this.webcam.dispose();
+    this.voice.dispose();
+    this.studio.close();
+    await this.flushSave();
+    disposeWorldSession();
+    this.events.emit('left', undefined);
+  }
+}
+
+function hashTint(seed: string): number {
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) h = (h * 31 + seed.charCodeAt(i)) >>> 0;
+  return h % TINT_COUNT;
+}

package/src/platform/auth/AuthService.ts

@@ -0,0 +1,45 @@
+/**
+ * Sign-in for a game on its own domain: HOSTED, always.
+ *
+ * The player is sent to Crowded Kingdoms' sign-in page (Studio's `/authorize`)
+ * with a PKCE challenge and comes back with a token confined to this app. This
+ * page never sees a password and never holds an identity session -- the direct
+ * sign-in mutations are refused from any browser origin that is not Crowded
+ * Kingdoms' own (`HOSTED_SIGN_IN_REQUIRED`, ck-api v1.88.0). The reason is the
+ * player's password: a form here that collected it would be indistinguishable,
+ * to the platform and to the player, from a phishing page.
+ *
+ * What this means for a third-party game:
+ *  - there is no login form, register form, magic link or guest account in the
+ *    browser. Account creation happens on Studio's page during the redirect.
+ *  - the app id must be known BEFORE sign-in (the redirect names it). It comes
+ *    from `VITE_APP_ID`, `?app=`, or this browser's storage; `npm run setup`
+ *    creates the app and prints the id.
+ *  - this page's origin must be one of the app's registered redirect URIs.
+ *    `npm run setup` registers the dev server's; add the production origin in
+ *    Studio > Apps > Settings > Sign-in & redirect URIs.
+ */
+import { NetworkManager, type AppRoute } from '../network/NetworkManager';
+
+export class AuthService {
+  constructor(private readonly network: NetworkManager = NetworkManager.instance) {}
+
+  /** Leave for Crowded Kingdoms' sign-in page; the browser navigates away. */
+  async signIn(appId: string): Promise<void> {
+    await this.network.signInHosted(appId);
+  }
+
+  /** Finish a sign-in this page is returning from, if any. */
+  async completeIfReturning(): Promise<AppRoute | null> {
+    return this.network.completeHostedSignInIfPresent();
+  }
+
+  /** A previous visit's token and route, if they still work. */
+  async restore(): Promise<AppRoute | null> {
+    return this.network.restore();
+  }
+
+  async signOut(): Promise<void> {
+    await this.network.signOut();
+  }
+}

package/src/platform/config.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// The SDK root barrel drags Monaco into a unit test; config only needs the
+// two generated constants.
+vi.mock('@crowdedkingdoms/crowdyjs', () => ({
+  CROWDY_DEFAULT_HTTP_ORIGIN: 'https://ck.test.example',
+  CROWDY_DEFAULT_TIER: 'test',
+}));
+
+const { resolveAppId, resolveAuthorizeUrl, resolveStudioOrigin, API_HTTP_URL, API_WS_URL } =
+  await import('./config');
+
+describe('resolveAppId', () => {
+  it('prefers the URL, then storage, then the build', () => {
+    expect(resolveAppId({ search: '?app=123', stored: '456', env: '789' })).toEqual({
+      appId: '123',
+      source: 'query',
+    });
+    expect(resolveAppId({ search: '', stored: '456', env: '789' })).toEqual({
+      appId: '456',
+      source: 'storage',
+    });
+    expect(resolveAppId({ search: null, stored: null, env: '789' })).toEqual({
+      appId: '789',
+      source: 'env',
+    });
+  });
+
+  it('falls through to none when nothing is set', () => {
+    expect(resolveAppId({})).toEqual({ appId: null, source: 'none' });
+  });
+
+  it('ignores values that are not numeric ids', () => {
+    expect(resolveAppId({ search: '?app=drop%20table', stored: 'abc', env: ' ' })).toEqual({
+      appId: null,
+      source: 'none',
+    });
+    expect(resolveAppId({ search: '?app=', stored: '42' })).toEqual({
+      appId: '42',
+      source: 'storage',
+    });
+  });
+});
+
+describe('API origin', () => {
+  it('defaults to the SDK build origin with a websocket twin', () => {
+    expect(API_HTTP_URL).toBe('https://ck.test.example');
+    expect(API_WS_URL).toBe('wss://ck.test.example');
+  });
+});
+
+describe('resolveAuthorizeUrl', () => {
+  it('rewrites a loopback authorize host when the page is public', () => {
+    expect(
+      resolveAuthorizeUrl({
+        authorizeUrl: 'http://127.0.0.1:5173/authorize',
+        pageHostname: '203.0.113.8',
+      }),
+    ).toBe('http://203.0.113.8:5173/authorize');
+  });
+
+  it('keeps loopback when the page is also loopback', () => {
+    expect(
+      resolveAuthorizeUrl({
+        authorizeUrl: 'http://localhost:5173/authorize?app=1',
+        pageHostname: '127.0.0.1',
+      }),
+    ).toBe('http://localhost:5173/authorize?app=1');
+  });
+
+  it('returns undefined when nothing is set', () => {
+    expect(resolveAuthorizeUrl({})).toBeUndefined();
+    expect(resolveAuthorizeUrl({ authorizeUrl: '  ' })).toBeUndefined();
+  });
+});
+
+describe('resolveStudioOrigin', () => {
+  it('prefers an explicit Studio URL', () => {
+    expect(
+      resolveStudioOrigin({
+        authorizeUrl: 'http://127.0.0.1:5173/authorize',
+        studioUrl: 'https://studio.example/app',
+        pageHostname: '203.0.113.8',
+      }),
+    ).toBe('https://studio.example');
+  });
+
+  it('rewrites a loopback authorize host when the page is public', () => {
+    expect(
+      resolveStudioOrigin({
+        authorizeUrl: 'http://127.0.0.1:5173/authorize',
+        pageHostname: '203.0.113.8',
+      }),
+    ).toBe('http://203.0.113.8:5173');
+  });
+
+  it('keeps loopback when the page is also loopback', () => {
+    expect(
+      resolveStudioOrigin({
+        authorizeUrl: 'http://localhost:5173/authorize',
+        pageHostname: '127.0.0.1',
+      }),
+    ).toBe('http://localhost:5173');
+  });
+
+  it('returns null when nothing can be derived', () => {
+    expect(resolveStudioOrigin({})).toBeNull();
+    expect(resolveStudioOrigin({ authorizeUrl: 'not-a-url' })).toBeNull();
+  });
+});

package/src/platform/config.ts

@@ -0,0 +1,212 @@
+/**
+ * Build-time and runtime configuration for The Construct.
+ *
+ * The starter needs almost nothing configured: the installed CrowdyJS build
+ * already knows the public API origin for its tier, and the app id can come
+ * from the Setup wizard instead of an env file. Everything here is therefore
+ * optional and resolved in a documented order, and the pure functions are
+ * unit-tested in `config.test.ts`.
+ */
+import { CROWDY_DEFAULT_HTTP_ORIGIN, CROWDY_DEFAULT_TIER } from '@crowdedkingdoms/crowdyjs';
+
+function envString(name: string): string | undefined {
+  const value = (import.meta.env as Record<string, string | undefined>)[name];
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function envFlag(name: string, fallback: boolean): boolean {
+  const raw = envString(name);
+  if (raw === undefined) return fallback;
+  return !['0', 'false', 'off', 'no'].includes(raw.toLowerCase());
+}
+
+function trimApiOrigin(url: string): string {
+  return url.replace(/\/graphql\/?$/, '').replace(/\/$/, '');
+}
+
+/**
+ * The API root the bundle dials. Explicit override first; otherwise the origin
+ * the SDK was published with. Never a hostname written into this repository.
+ *
+ * `same-origin` (or `/`) means "this page" — used when Vite proxies `/graphql`
+ * so the IDE browser on a public IP and Playwright on localhost share one build.
+ */
+export const API_HTTP_URL: string = trimApiOrigin(
+  (() => {
+    const raw = envString('VITE_CROWDY_HTTP_URL');
+    if (!raw) return CROWDY_DEFAULT_HTTP_ORIGIN;
+    if (
+      (raw === 'same-origin' || raw === '/') &&
+      typeof window !== 'undefined' &&
+      window.location?.origin
+    ) {
+      return window.location.origin;
+    }
+    return raw;
+  })(),
+);
+
+/** The same host over WebSocket. */
+export const API_WS_URL: string = API_HTTP_URL.replace(
+  /^http(s?):/,
+  (_m, secure: string) => `ws${secure}:`,
+);
+
+/** Which tier the SDK build targets; informational (shown in the boot card). */
+export const API_TIER: string = envString('VITE_CROWDY_HTTP_URL') ? 'custom' : CROWDY_DEFAULT_TIER;
+
+function originOf(value: string): string | null {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+function isLoopbackHost(host: string): boolean {
+  const normalized = host.toLowerCase();
+  return (
+    normalized === 'localhost' ||
+    normalized === '127.0.0.1' ||
+    normalized === '::1' ||
+    normalized === '[::1]'
+  );
+}
+
+/**
+ * When the game is opened on a public IP (IDE browser) but Studio is
+ * configured as loopback, rewrite the hostname so navigation can actually
+ * reach it. Path, port, and query stay intact.
+ */
+function rewriteLoopbackToPageHost(raw: string, pageHostname?: string | null): URL | null {
+  try {
+    const url = new URL(raw);
+    const pageHost = pageHostname?.trim();
+    if (pageHost && isLoopbackHost(url.hostname) && !isLoopbackHost(pageHost)) {
+      url.hostname = pageHost;
+    }
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Hosted sign-in URL. Same loopback rewrite as Studio origin — otherwise
+ * `portal.signIn` sends the IDE browser to `127.0.0.1` and the tab goes blank.
+ */
+export function resolveAuthorizeUrl(input: {
+  authorizeUrl?: string | null;
+  pageHostname?: string | null;
+}): string | undefined {
+  const raw = input.authorizeUrl?.trim();
+  if (!raw) return undefined;
+  return rewriteLoopbackToPageHost(raw, input.pageHostname)?.toString() ?? raw;
+}
+
+/**
+ * Hosted sign-in page (Studio `/authorize`). Required when `VITE_CROWDY_HTTP_URL`
+ * is not a CK tier host — CrowdyJS cannot derive Studio from a same-origin
+ * proxy or a raw IP. Leave unset to use the SDK's tier convention.
+ */
+export const AUTHORIZE_URL: string | undefined = resolveAuthorizeUrl({
+  authorizeUrl: envString('VITE_AUTHORIZE_URL'),
+  pageHostname: typeof window !== 'undefined' ? window.location.hostname : null,
+});
+
+/**
+ * Studio origin for in-game links. Explicit `VITE_STUDIO_URL` wins; otherwise
+ * the origin of the hosted-sign-in URL. When that URL is loopback and the
+ * page is not (public-IP IDE against a local stack), the page hostname is
+ * substituted so Wallet opens the Studio the player can actually reach.
+ * Never a hostname written into this repository.
+ */
+export function resolveStudioOrigin(input: {
+  authorizeUrl?: string | null;
+  studioUrl?: string | null;
+  pageHostname?: string | null;
+}): string | null {
+  const explicit = input.studioUrl?.trim();
+  if (explicit) return originOf(explicit);
+  const authorize = input.authorizeUrl?.trim();
+  if (!authorize) return null;
+  return rewriteLoopbackToPageHost(authorize, input.pageHostname)?.origin ?? null;
+}
+
+export const STUDIO_ORIGIN: string | null = resolveStudioOrigin({
+  authorizeUrl: envString('VITE_AUTHORIZE_URL'),
+  studioUrl: envString('VITE_STUDIO_URL'),
+  pageHostname: typeof window !== 'undefined' ? window.location.hostname : null,
+});
+
+/** Player wallet page in Studio. Null when we cannot derive Studio's origin. */
+export const STUDIO_WALLET_URL: string | null = STUDIO_ORIGIN
+  ? `${STUDIO_ORIGIN}/account/wallet`
+  : null;
+
+/** CLIENT-target Crowdy Studio mods (browser sandbox). A fork can turn these off. */
+export const CLIENT_MODS_ENABLED: boolean = envFlag('VITE_CONSTRUCT_CLIENT_MODS', true);
+
+/** App-token rotation cadence. Tokens live ~30 minutes; rotate well before. */
+export const APP_TOKEN_REFRESH_MS: number =
+  Math.max(60, Number(envString('VITE_APP_TOKEN_REFRESH_SECONDS') ?? 1200)) * 1000;
+
+/** Retry a failed rotation sooner than the full interval. */
+export const APP_TOKEN_REFRESH_RETRY_MS = 30_000;
+
+/** Fixed spatial parameters shared by every scene. */
+export const CHUNK_SIZE = 16;
+export const REPLICATION_DISTANCE = 4;
+export const ACTOR_SYNC_INTERVAL_MS = 200;
+export const STALE_ACTOR_TIMEOUT_MS = 12_000;
+
+/** Shown in the Studio dock and the boot card; `VITE_GAME_NAME` overrides it. */
+export const GAME_NAME: string = envString('VITE_GAME_NAME') ?? 'The Construct';
+
+// ---------------------------------------------------------------------------
+// App id resolution
+// ---------------------------------------------------------------------------
+
+export const APP_ID_STORAGE_KEY = 'construct:app-id';
+
+export interface AppIdSources {
+  /** `window.location.search` (or any query string). */
+  search?: string | null;
+  /** The env-scoped storage the wizard writes to. */
+  stored?: string | null;
+  /** `VITE_APP_ID` as built. */
+  env?: string | null;
+}
+
+export type AppIdResolution =
+  { appId: string; source: 'query' | 'storage' | 'env' } | { appId: null; source: 'none' };
+
+const APP_ID_PATTERN = /^\d{1,20}$/;
+
+function validAppId(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed && APP_ID_PATTERN.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Resolution order, most explicit first:
+ *  1. `?app=<id>` in the URL (share a link to a specific app),
+ *  2. the id the Setup wizard remembered in this browser (env-scoped),
+ *  3. `VITE_APP_ID` baked into the build,
+ *  4. none — the boot flow opens the Setup wizard.
+ */
+export function resolveAppId(sources: AppIdSources): AppIdResolution {
+  const fromQuery = validAppId(
+    sources.search ? new URLSearchParams(sources.search).get('app') : null,
+  );
+  if (fromQuery) return { appId: fromQuery, source: 'query' };
+  const fromStorage = validAppId(sources.stored);
+  if (fromStorage) return { appId: fromStorage, source: 'storage' };
+  const fromEnv = validAppId(sources.env);
+  if (fromEnv) return { appId: fromEnv, source: 'env' };
+  return { appId: null, source: 'none' };
+}
+
+/** The env-baked app id, if any (exposed for the boot flow + the wizard UI). */
+export const BUILD_APP_ID: string | null = validAppId(envString('VITE_APP_ID'));

package/src/platform/envScope.test.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@crowdedkingdoms/crowdyjs', () => ({
+  CROWDY_DEFAULT_HTTP_ORIGIN: 'https://ck.test.example',
+  CROWDY_DEFAULT_TIER: 'test',
+}));
+
+const { ENV_HANDLE, envHandleFor, envScopedKey, ensureEnvScope, readScoped, writeScoped } =
+  await import('./envScope');
+
+describe('envScope', () => {
+  beforeEach(() => localStorage.clear());
+
+  it('derives a handle from the origin without inspecting hostname shape', () => {
+    expect(envHandleFor('https://ck.prod.crowdedkingdoms.com')).toBe('ck.prod.crowdedkingdoms.com');
+    expect(envHandleFor('http://localhost:3000')).toBe('localhost_3000');
+    expect(envHandleFor('not a url')).toBe('not_a_url');
+    expect(ENV_HANDLE).toBe('ck.test.example');
+  });
+
+  it('suffixes keys with the handle', () => {
+    expect(envScopedKey('construct:app-id')).toBe('construct:app-id:ck.test.example');
+    expect(envScopedKey('x', 'other')).toBe('x:other');
+  });
+
+  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');
+    localStorage.setItem('construct:app-id:ck.test.example', '222');
+    ensureEnvScope();
+    expect(localStorage.getItem('construct:app-id:ck.old.example')).toBeNull();
+    expect(localStorage.getItem('construct:app-id:ck.test.example')).toBe('222');
+    expect(localStorage.getItem('construct:env-handle')).toBe('ck.test.example');
+  });
+
+  it('reads and writes scoped values', () => {
+    writeScoped('construct:app-id', '99');
+    expect(readScoped('construct:app-id')).toBe('99');
+    writeScoped('construct:app-id', null);
+    expect(readScoped('construct:app-id')).toBeNull();
+  });
+});