@crowdedkingdoms/construct 0.3.11 → 0.4.1-dev.1

package/src/platform/live/draftModules.ts

@@ -0,0 +1,263 @@
+/**
+ * How the draft service worker turns draft files into modules the page can
+ * import. Pure functions, shared by the worker and the tests.
+ *
+ * URLs, all under the game's base (`BASE`):
+ * - `BASE__draft/g<generation>/<repo path>`: a draft file as an ES module.
+ *   TypeScript is stripped (sucrase keeps line numbers, so stack traces point
+ *   at the draft file); every import is rewritten to another draft URL of the
+ *   same generation, a host shim, or a module that throws a clear error.
+ * - `BASE__draft/host/<specifier>.js`: a shim re-exporting the page's own
+ *   module for a bare or framework import, so a draft scene shares `three`,
+ *   the framework and its singletons with the running game.
+ * - `BASE__draft/missing/<specifier>`: an import the draft cannot satisfy.
+ *
+ * A new generation re-imports the whole draft graph under new URLs; the
+ * browser's module map caches the old one until the page reloads.
+ */
+// The pure-JS build: no WebAssembly (a `script-src 'self'` page cannot compile it) and no init.
+import { parse } from 'es-module-lexer/js';
+import { transform } from 'sucrase';
+
+import type { PreviewError } from './content';
+
+export const DRAFT_SEGMENT = '__draft/';
+/** The service worker's file name, next to the game's index.html. */
+export const DRAFT_WORKER_FILE = 'construct-draft-sw.js';
+/** The content entry every generation imports. */
+export const CONTENT_ENTRY = 'src/game/content.ts';
+
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.js', '.mjs', '.json'];
+const SCRIPT_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.js', '.mjs']);
+
+export type DraftRequest =
+  | { kind: 'module'; generation: number; path: string }
+  | { kind: 'host'; specifier: string }
+  | { kind: 'missing'; specifier: string; importer: string };
+
+/** What a pathname under the draft segment asks for, or null when it is not a draft URL. */
+export function parseDraftUrl(pathname: string, base: string): DraftRequest | null {
+  const prefix = `${base}${DRAFT_SEGMENT}`;
+  if (!pathname.startsWith(prefix)) return null;
+  const rest = pathname.slice(prefix.length);
+  const generation = /^g(\d+)\/(.+)$/.exec(rest);
+  if (generation) {
+    const path = decodeURIComponent(generation[2] ?? '');
+    if (!isDraftPath(path)) return null;
+    return { kind: 'module', generation: Number(generation[1]), path };
+  }
+  const host = /^host\/(.+)\.js$/.exec(rest);
+  if (host) return { kind: 'host', specifier: decodeURIComponent(host[1] ?? '') };
+  const missing = /^missing\/([^/]+)\/(.+)$/.exec(rest);
+  if (missing) {
+    return {
+      kind: 'missing',
+      importer: decodeURIComponent(missing[1] ?? ''),
+      specifier: decodeURIComponent(missing[2] ?? ''),
+    };
+  }
+  return null;
+}
+
+export function draftModuleUrl(base: string, generation: number, path: string): string {
+  return `${base}${DRAFT_SEGMENT}g${generation}/${path.split('/').map(encodeURIComponent).join('/')}`;
+}
+
+function hostShimUrl(base: string, specifier: string): string {
+  return `${base}${DRAFT_SEGMENT}host/${encodeURIComponent(specifier)}.js`;
+}
+
+function missingUrl(base: string, importer: string, specifier: string): string {
+  return `${base}${DRAFT_SEGMENT}missing/${encodeURIComponent(importer)}/${encodeURIComponent(specifier)}`;
+}
+
+/** A relative repository path with no traversal: what a draft URL may name. */
+function isDraftPath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    !path.startsWith('/') &&
+    !path.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+  );
+}
+
+function normalize(path: string): string | null {
+  const out: string[] = [];
+  for (const segment of path.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length === 0) return null;
+      out.pop();
+    } else out.push(segment);
+  }
+  return out.join('/');
+}
+
+function extensionOf(path: string): string {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot) : '';
+}
+
+export type Resolution =
+  { kind: 'draft'; path: string } | { kind: 'host'; specifier: string } | { kind: 'missing' };
+
+/**
+ * Resolve an import written in a draft file: `./`, `../`, `/` and the
+ * template's `@/` (src/) alias name draft files; anything else is the host's.
+ * Extensions resolve as Vite does for this template.
+ */
+export function resolveSpecifier(
+  specifier: string,
+  importer: string,
+  paths: ReadonlySet<string>,
+): Resolution {
+  let target: string | null;
+  if (specifier.startsWith('./') || specifier.startsWith('../')) {
+    target = normalize(`${importer.slice(0, importer.lastIndexOf('/') + 1)}${specifier}`);
+  } else if (specifier.startsWith('@/')) {
+    target = normalize(`src/${specifier.slice(2)}`);
+  } else if (specifier.startsWith('/')) {
+    target = normalize(specifier.slice(1));
+  } else {
+    return { kind: 'host', specifier };
+  }
+  if (!target) return { kind: 'missing' };
+  const candidates = [
+    target,
+    ...RESOLVE_EXTENSIONS.map((extension) => `${target}${extension}`),
+    ...RESOLVE_EXTENSIONS.map((extension) => `${target}/index${extension}`),
+  ];
+  for (const candidate of candidates) {
+    if (paths.has(candidate)) return { kind: 'draft', path: candidate };
+  }
+  return { kind: 'missing' };
+}
+
+export class DraftTransformError extends Error {
+  constructor(
+    message: string,
+    readonly error: PreviewError,
+  ) {
+    super(message);
+    this.name = 'DraftTransformError';
+  }
+}
+
+/**
+ * A draft file as a module of generation `generation`. Throws a
+ * `DraftTransformError` carrying the file and line for a syntax error.
+ */
+export async function transformDraftModule(options: {
+  source: string;
+  path: string;
+  generation: number;
+  base: string;
+  paths: ReadonlySet<string>;
+}): Promise<string> {
+  const { source, path, generation, base, paths } = options;
+  const extension = extensionOf(path);
+  if (extension === '.json') {
+    try {
+      return `export default ${JSON.stringify(JSON.parse(source))};\n`;
+    } catch (error) {
+      throw new DraftTransformError(`${path}: ${(error as Error).message}`, {
+        path,
+        message: (error as Error).message,
+      });
+    }
+  }
+  if (!SCRIPT_EXTENSIONS.has(extension)) {
+    const message = `${path} cannot be previewed (${extension || 'no extension'}): only TypeScript, JavaScript and JSON load from the draft.`;
+    throw new DraftTransformError(message, { path, message });
+  }
+  let code = source;
+  if (extension === '.ts' || extension === '.tsx' || extension === '.mts') {
+    try {
+      code = transform(source, {
+        transforms: extension === '.tsx' ? ['typescript', 'jsx'] : ['typescript'],
+        disableESTransforms: true,
+        preserveDynamicImport: true,
+        production: true,
+        filePath: path,
+      }).code;
+    } catch (error) {
+      const loc = (error as { loc?: { line: number; column: number } }).loc;
+      const message = (error as Error).message;
+      throw new DraftTransformError(
+        `${path}${loc ? `:${loc.line}:${loc.column + 1}` : ''}: ${message}`,
+        {
+          path,
+          ...(loc ? { line: loc.line, column: loc.column + 1 } : {}),
+          message,
+        },
+      );
+    }
+  }
+  let imports: ReturnType<typeof parse>[0];
+  try {
+    [imports] = parse(code, path);
+  } catch (error) {
+    const idx = (error as { idx?: number }).idx;
+    const line = idx === undefined ? undefined : code.slice(0, idx).split('\n').length;
+    const message = (error as Error).message;
+    throw new DraftTransformError(`${path}${line ? `:${line}` : ''}: ${message}`, {
+      path,
+      ...(line ? { line } : {}),
+      message,
+    });
+  }
+  const rewriteSpecifier = (specifier: string): string => {
+    const resolution = resolveSpecifier(specifier, path, paths);
+    if (resolution.kind === 'draft') return draftModuleUrl(base, generation, resolution.path);
+    if (resolution.kind === 'host') return hostShimUrl(base, resolution.specifier);
+    return missingUrl(base, path, specifier);
+  };
+  // Back to front, so earlier offsets stay valid.
+  for (const entry of [...imports].sort((a, b) => b.s - a.s)) {
+    if (entry.d === -2) {
+      const after = code.slice(entry.e);
+      if (after.startsWith('.env')) {
+        code = `${code.slice(0, entry.s)}globalThis.__constructDraftEnv${code.slice(entry.e + 4)}`;
+      } else if (after.startsWith('.hot')) {
+        code = `${code.slice(0, entry.s)}(void 0)${code.slice(entry.e + 4)}`;
+      }
+      continue;
+    }
+    if (entry.n === undefined) continue;
+    const written = code.slice(entry.s, entry.e);
+    const quote = written[0] === '"' || written[0] === "'" || written[0] === '`' ? written[0] : '';
+    const url = rewriteSpecifier(entry.n);
+    code = `${code.slice(0, entry.s)}${quote ? JSON.stringify(url) : url}${code.slice(entry.e)}`;
+  }
+  return code;
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const RESERVED = new Set(
+  'break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await arguments eval'.split(
+    ' ',
+  ),
+);
+
+/** A shim re-exporting the page's module for `specifier` with these export names. */
+export function hostShimSource(specifier: string, names: readonly string[]): string {
+  const lines = [`const m = await globalThis.__constructDraftHost(${JSON.stringify(specifier)});`];
+  names.forEach((name, index) => {
+    const local = `__e${index}`;
+    lines.push(`const ${local} = m[${JSON.stringify(name)}];`);
+    const exported =
+      name === 'default' || (IDENTIFIER.test(name) && !RESERVED.has(name))
+        ? name
+        : JSON.stringify(name);
+    lines.push(`export { ${local} as ${exported} };`);
+  });
+  return `${lines.join('\n')}\n`;
+}
+
+/** A module that fails to load with `error`, so the import names the file and line. */
+export function errorModuleSource(error: PreviewError): string {
+  const where = error.path
+    ? `${error.path}${error.line ? `:${error.line}${error.column ? `:${error.column}` : ''}` : ''}: `
+    : '';
+  return `const error = new Error(${JSON.stringify(`${where}${error.message}`)});\nerror.preview = ${JSON.stringify(error)};\nthrow error;\n`;
+}

package/src/platform/live/draftServiceWorker.ts

@@ -0,0 +1,176 @@
+/**
+ * The draft service worker: serves Crowdy Studio's game-editor draft as ES
+ * modules, so a hosted game previews edits without a build and without
+ * loosening its CSP (`script-src 'self'`: these are same-origin module URLs;
+ * nothing is evaluated from a string or a blob).
+ *
+ * It controls the game's pages (its scope is the game's base) because a
+ * service worker sees only the requests of the pages it controls, but it
+ * answers nothing outside `BASE__draft/`: navigations, the harness, the API
+ * and the game's own assets go to the network untouched. The page that
+ * imports a draft module answers for it (`./draftLoader`): sources, the
+ * generation's file list and the host's export names. A page that is not
+ * running the game editor never answers, and its requests fail.
+ *
+ * Bundled as a classic script by `constructDraftPlugin` (node/vite-plugins).
+ */
+import type { PreviewError } from './content';
+import {
+  DraftTransformError,
+  errorModuleSource,
+  hostShimSource,
+  parseDraftUrl,
+  transformDraftModule,
+  type DraftRequest,
+} from './draftModules';
+
+declare const self: ServiceWorkerGlobalScope;
+
+const ANSWER_TIMEOUT_MS = 10_000;
+const KEPT_GENERATIONS = 4;
+
+type PageAnswer =
+  | { ok: true; paths?: string[]; source?: string; names?: string[] }
+  | { ok: false; message: string };
+
+const base = new URL(self.registration.scope).pathname;
+const manifests = new Map<string, Promise<Set<string>>>();
+
+self.addEventListener('install', () => {
+  void self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+  if (url.origin !== self.location.origin || event.request.method !== 'GET') return;
+  const request = parseDraftUrl(url.pathname, base);
+  if (!request) return;
+  event.respondWith(answer(request, event.clientId));
+});
+
+async function ask(clientId: string, message: Record<string, unknown>): Promise<PageAnswer> {
+  const client = clientId ? await self.clients.get(clientId) : undefined;
+  if (!client) return { ok: false, message: 'No game page is waiting for this draft module.' };
+  const channel = new MessageChannel();
+  return new Promise<PageAnswer>((resolve) => {
+    const timer = setTimeout(() => {
+      channel.port1.close();
+      resolve({
+        ok: false,
+        message: 'The page did not answer for the draft (is the game editor open?).',
+      });
+    }, ANSWER_TIMEOUT_MS);
+    channel.port1.onmessage = (event: MessageEvent<PageAnswer>) => {
+      clearTimeout(timer);
+      channel.port1.close();
+      resolve(event.data);
+    };
+    client.postMessage({ type: 'construct-draft', ...message }, [channel.port2]);
+  });
+}
+
+function manifestOf(clientId: string, generation: number): Promise<Set<string>> {
+  const key = `${clientId}:${generation}`;
+  let manifest = manifests.get(key);
+  if (!manifest) {
+    manifest = ask(clientId, { request: 'manifest', generation }).then((reply) => {
+      if (!reply.ok || !reply.paths)
+        throw new Error(reply.ok ? 'The page sent no file list.' : reply.message);
+      return new Set(reply.paths);
+    });
+    manifest.catch(() => manifests.delete(key));
+    manifests.set(key, manifest);
+    while (manifests.size > KEPT_GENERATIONS)
+      manifests.delete(manifests.keys().next().value as string);
+  }
+  return manifest;
+}
+
+function moduleResponse(code: string, status = 200): Response {
+  return new Response(code, {
+    status,
+    headers: {
+      'Content-Type': 'text/javascript; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'Cross-Origin-Resource-Policy': 'same-origin',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  });
+}
+
+/** A module that throws, after telling the page what failed (it keeps the location). */
+async function failure(
+  clientId: string,
+  error: PreviewError,
+  generation?: number,
+): Promise<Response> {
+  const client = clientId ? await self.clients.get(clientId) : undefined;
+  client?.postMessage({ type: 'construct-draft-error', generation, error });
+  return moduleResponse(errorModuleSource(error));
+}
+
+async function answer(request: DraftRequest, clientId: string): Promise<Response> {
+  try {
+    switch (request.kind) {
+      case 'module': {
+        const paths = await manifestOf(clientId, request.generation);
+        if (!paths.has(request.path)) {
+          return failure(
+            clientId,
+            { path: request.path, message: `${request.path} is not in the draft.` },
+            request.generation,
+          );
+        }
+        const reply = await ask(clientId, {
+          request: 'source',
+          generation: request.generation,
+          path: request.path,
+        });
+        if (!reply.ok || reply.source === undefined) {
+          return failure(
+            clientId,
+            { path: request.path, message: reply.ok ? 'The page sent no source.' : reply.message },
+            request.generation,
+          );
+        }
+        const code = await transformDraftModule({
+          source: reply.source,
+          path: request.path,
+          generation: request.generation,
+          base,
+          paths,
+        });
+        return moduleResponse(code);
+      }
+      case 'host': {
+        const reply = await ask(clientId, { request: 'host', specifier: request.specifier });
+        if (!reply.ok || !reply.names) {
+          return failure(clientId, {
+            message: reply.ok
+              ? `The page sent no exports for ${request.specifier}.`
+              : `${request.specifier}: ${reply.message}`,
+          });
+        }
+        return moduleResponse(hostShimSource(request.specifier, reply.names));
+      }
+      case 'missing':
+        return failure(clientId, {
+          path: request.importer,
+          message: `Cannot find "${request.specifier}" in the draft (imported by ${request.importer}).`,
+        });
+    }
+  } catch (error) {
+    if (error instanceof DraftTransformError) {
+      return failure(
+        clientId,
+        error.error,
+        request.kind === 'module' ? request.generation : undefined,
+      );
+    }
+    return failure(clientId, { message: (error as Error).message ?? String(error) });
+  }
+}

package/src/platform/live/sdk.ts

@@ -0,0 +1,50 @@
+/**
+ * The game editor's slice of CrowdyJS 18.23 (`@crowdedkingdoms/crowdyjs/crowdy-studio`):
+ * the draft-store contract, the hosted store and its storage.
+ *
+ * The types are the SDK's own. The classes are looked up at runtime, so a page
+ * bundled with an SDK that predates them opens a bound project in the mod
+ * editor instead of failing to load.
+ */
+import * as studio from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+import type {
+  GitHubDraftTransport,
+  MountCrowdyStudioOptions,
+} from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+
+export type {
+  DraftChangeEvent,
+  DraftCommitResult,
+  DraftConflict,
+  DraftDeleteResult,
+  DraftEntry,
+  DraftErrorCode,
+  DraftPrecondition,
+  DraftReadResult,
+  DraftSnapshot,
+  DraftSource,
+  DraftStore,
+  DraftWriteResult,
+} from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+
+/** What the Studio controller's `draftStore` option is given. */
+export type DraftProject = Parameters<NonNullable<MountCrowdyStudioOptions['draftStore']>>[0];
+
+/** The commit path of the SDK's GitHub transport (`game.crowdyStudioGitHub`). */
+export type DraftCommitTransport = Pick<GitHubDraftTransport, 'commitFiles'>;
+
+export type LiveCodeSdk = Pick<
+  typeof studio,
+  'GitHubDraftStore' | 'IndexedDbDraftOverlayStorage' | 'DraftError' | 'isRepoPath'
+>;
+
+/** The SDK's game-editor classes, or null when the installed SDK predates them. */
+export function liveCodeSdk(): LiveCodeSdk | null {
+  const sdk = studio as Partial<LiveCodeSdk>;
+  return typeof sdk.GitHubDraftStore === 'function' &&
+    typeof sdk.IndexedDbDraftOverlayStorage === 'function' &&
+    typeof sdk.DraftError === 'function' &&
+    typeof sdk.isRepoPath === 'function'
+    ? (sdk as LiveCodeSdk)
+    : null;
+}

package/src/platform/live/virtual.d.ts

@@ -0,0 +1,5 @@
+/** The lazy host-module registry `constructDraftPlugin` writes at build time (see draftLoader.ts). */
+declare module 'virtual:construct-draft-host' {
+  const modules: Readonly<Record<string, () => Promise<unknown>>>;
+  export default modules;
+}

package/src/platform/localLiveCode.ts

@@ -0,0 +1,11 @@
+/**
+ * A world without Buddy, for trying the game editor where no realtime cluster
+ * runs. Set `VITE_LOCAL_LIVE_CODE=1` on the dev server: the page skips the
+ * world join and the grid claim, and the world hub answers locally instead of
+ * dialling ck-exec. Off unless that flag is set. The game editor itself does
+ * not need it: `LIVE_DRAFT=1` turns the checkout into the draft.
+ */
+export function localLiveCode(): boolean {
+  const env = import.meta.env as { VITE_LOCAL_LIVE_CODE?: string } | undefined;
+  return env?.VITE_LOCAL_LIVE_CODE === '1';
+}

package/src/platform/onboarding/steps.d.mts

@@ -108,7 +108,7 @@ export function ensureRedirectUris(
   identity: CrowdyClient,
   args: { appId: string; origins: string[] },
   log?: Logger,
-): Promise<{ redirectUris: string[]; added: string[] }>;
+): Promise<{ redirectUris: string[]; added: string[]; launchUrl: string | null }>;
 export function ensureConstructorTier(
   identity: CrowdyClient,
   input: { appId: string; userId: string },

package/src/platform/onboarding/steps.mjs

@@ -127,6 +127,11 @@ export async function ensureApp(identity, { orgId, orgSlug, name, slug, datacent
  * on the return leg and no CORS headers on anything else. Idempotent: existing
  * entries are kept, the given ones added; origin-matched by the server, so the
  * path does not matter but `/` keeps the list readable.
+ *
+ * An app with no launch URL also gets the first origin that is not loopback as
+ * its launch URL. Crowded Kingdoms does not host games, so that origin is where
+ * the game lives, and Crowdy Studio's Live code opens it. A launch URL the app
+ * already has is left alone.
  */
 export async function ensureRedirectUris(identity, { appId, origins }, log = noop) {
   const app = await identity.apps.app(appId);
@@ -134,14 +139,21 @@ export async function ensureRedirectUris(identity, { appId, origins }, log = noo
   const have = new Set(existing.map((u) => originOf(u)).filter(Boolean));
   const wanted = origins.map((o) => originOf(o)).filter(Boolean);
   const missing = [...new Set(wanted)].filter((o) => !have.has(o));
-  if (missing.length === 0) {
+  const launchOrigin = app?.launchUrl ? null : wanted.find((o) => !isLoopback(o));
+  const launchUrl = launchOrigin ? `${launchOrigin}/` : null;
+  if (missing.length === 0 && !launchUrl) {
     log(`Redirect URIs already cover ${wanted.join(', ')}`);
-    return { redirectUris: existing, added: [] };
+    return { redirectUris: existing, added: [], launchUrl: app?.launchUrl ?? null };
   }
   const redirectUris = [...existing, ...missing.map((o) => `${o}/`)];
-  await identity.portal.setAppClientSettings({ appId, redirectUris });
-  log(`Registered redirect origin(s) ${missing.join(', ')}`);
-  return { redirectUris, added: missing };
+  await identity.portal.setAppClientSettings({
+    appId,
+    redirectUris,
+    ...(launchUrl ? { launchUrl } : {}),
+  });
+  if (missing.length) log(`Registered redirect origin(s) ${missing.join(', ')}`);
+  if (launchUrl) log(`Launch URL set to ${launchUrl} (Crowdy Studio's Live code opens it)`);
+  return { redirectUris, added: missing, launchUrl: launchUrl ?? app?.launchUrl ?? null };
 }
 
 function originOf(value) {
@@ -152,6 +164,11 @@ function originOf(value) {
   }
 }
 
+function isLoopback(origin) {
+  const host = new URL(origin).hostname;
+  return host === 'localhost' || host === '[::1]' || host.startsWith('127.');
+}
+
 export async function ensureConstructorTier(identity, { appId, userId }, log = noop) {
   const tiers = await identity.appAccess.tiers(appId);
 
@@ -350,9 +367,25 @@ const AGENT_POLICY_CORE = `
 
 const AGENT_APP_POLICY_QUERY = `query ConstructAgentPolicy($appId: BigInt!) {
   crowdyStudioAgentPolicy(appId: $appId) { ${AGENT_POLICY_CORE} }
-  crowdyStudioAgentEffectivePolicy(appId: $appId) { ${AGENT_POLICY_CORE} }
+  crowdyStudioAgentEffectivePolicy(appId: $appId) {
+    ${AGENT_POLICY_CORE} funding { billingMode payerKind walletDebitEnabled }
+  }
 }`;
 
+/**
+ * Who pays for the agent's model use, as the effective policy has it. Metered, a
+ * request the payer's wallet cannot cover is refused, so say so up front.
+ */
+function fundingNote(effective) {
+  const funding = effective?.funding;
+  if (!funding) return 'funding not reported';
+  if (funding.billingMode !== 'METERED' || funding.walletDebitEnabled !== true) {
+    return 'platform-funded';
+  }
+  const payer = funding.payerKind === 'ORG' ? "the app's org wallet" : "each player's own wallet";
+  return `metered: model use is charged to ${payer}, which needs funds before the agent answers`;
+}
+
 const SET_AGENT_APP_POLICY = `mutation ConstructSetAgentPolicy($input: SetCrowdyStudioAgentAppPolicyInput!) {
   setCrowdyStudioAgentPolicy(input: $input) { ${AGENT_POLICY_CORE} }
 }`;
@@ -375,8 +408,8 @@ function catalogVisible(policy) {
  * The dock stays fail-closed until the *app* policy is enabled and the
  * player's Constructor tier holds `use_studio_agent`. The platform catalog is
  * an operator concern — this starter never reads or writes `cp*` fields.
- * Agent tokens are platform-funded; this does not touch a player wallet or an
- * OpenRouter key in the game.
+ * This touches no wallet and no OpenRouter key in the game; who pays for model
+ * use is the effective policy's funding, which the log reports.
  */
 export async function ensureAgentPolicy(identity, { appId }, log = noop) {
   let app;
@@ -400,7 +433,7 @@ export async function ensureAgentPolicy(identity, { appId }, log = noop) {
           'The dock stays closed until an operator publishes it. Studio → your app → Agent.',
       );
     } else {
-      log('Studio Agent app policy already enabled');
+      log(`Studio Agent app policy already enabled (${fundingNote(effective)})`);
     }
     return { enabled: true, skipped: true };
   }
@@ -447,7 +480,7 @@ export async function ensureAgentPolicy(identity, { appId }, log = noop) {
           'Studio → your app → Agent; dock stays closed.',
       );
     } else {
-      log('Studio Agent app policy enabled (platform-funded; no player OpenRouter key)');
+      log(`Studio Agent app policy enabled (${fundingNote(latestEffective)})`);
     }
     return { enabled: true, skipped: false };
   } catch (error) {