@playdrop/playdrop-cli 0.12.41 → 0.13.0

package/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.12.41",
+  "version": "0.13.0",
   "build": 1,
-  "runtimeSdkVersion": "0.12.41",
+  "runtimeSdkVersion": "0.13.0",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/dist/apps/index.d.ts

@@ -19,13 +19,16 @@ export type AppPipelineOptions = {
     token?: string | null;
     user?: UserResponse | null;
     runLocalLoadCheck?: boolean;
+    devRouterPort?: number;
     runStagedUploadLoadCheck?: boolean;
     loadCheckTimeoutMs?: number;
     ensureRegisteredAppShell?: boolean;
     agentTaskId?: number;
     playtestProof?: AgentTaskPlaytestProof;
     mediaCaptureRequired?: boolean;
+    machineCausalGateRequired?: boolean;
     captureSession?: TaskCaptureSession | null;
+    artifacts?: AppBuildArtifacts;
 };
 export declare function runAppPipeline(client: ApiClient, task: AppTask, options?: AppPipelineOptions): Promise<AppPipelineResult>;
 export { collectAppValidationWarnings, validateAppTask, buildApp, uploadApp, runFormatScript };

package/dist/apps/index.js

@@ -29,7 +29,7 @@ async function runAppPipeline(client, task, options) {
             agentTaskId: options.agentTaskId,
         });
     }
-    const artifacts = isExternal ? null : await (0, build_1.buildApp)(task);
+    const artifacts = isExternal ? null : options?.artifacts ?? await (0, build_1.buildApp)(task);
     const warnings = (0, validate_1.collectAppValidationWarnings)(task, isExternal ? 'source' : 'bundle');
     if (!isExternal && options?.runLocalLoadCheck) {
         const creatorUsername = typeof options.creatorUsername === 'string' ? options.creatorUsername.trim() : '';
@@ -46,6 +46,7 @@ async function runAppPipeline(client, task, options) {
             webBase: options.webBase,
             creatorUsername,
             task,
+            devRouterPort: options.devRouterPort,
             timeoutMs: options.loadCheckTimeoutMs,
             token: options.token ?? null,
             currentUser: options.user ?? null,
@@ -66,6 +67,7 @@ async function runAppPipeline(client, task, options) {
         agentTaskId: options?.agentTaskId,
         playtestProof: options?.playtestProof,
         mediaCaptureRequired: options?.mediaCaptureRequired,
+        machineCausalGateRequired: options?.machineCausalGateRequired,
         captureSession: options?.captureSession,
     };
     const upload = await (0, upload_1.uploadApp)(client, task, artifacts, uploadOptions);

package/dist/apps/loadCheck.d.ts

@@ -1,5 +1,5 @@
 import type { ApiClient } from '@playdrop/api-client';
-import { type AppPlaytestTape, type AppSurface, type UserResponse } from '@playdrop/types';
+import { type AppPlaytestTape, type AppSurface, type AppUploadCausalComparison, type AppUploadMachineCausalEvidence, type UserResponse } from '@playdrop/types';
 import type { BrowserContextOptions, Frame, Page } from 'playwright-core';
 import type { AppTask } from '../catalogue';
 import { type TaskCaptureSession } from '../appUrls';
@@ -84,4 +84,24 @@ export declare function runUploadedHostedLoadCheck(input: {
     currentUser?: UserResponse | null;
     captureSession?: TaskCaptureSession | null;
     screenshotPath?: string | null;
+    readyGameFrameScreenshotPath?: string | null;
+    gameFrameScreenshotPath?: string | null;
+    playtestTape?: AppPlaytestTape;
+    postReadyWaitMs?: number;
 }): Promise<HostedLoadCheckResult>;
+export declare function sliceFirstPrimaryVerbAction(tape: AppPlaytestTape): AppPlaytestTape;
+export declare function compareCausalFrames(firstPath: string, secondPath: string, thresholds?: {
+    meanDeltaMin: number;
+    changedPixelRatioMin: number;
+}): Promise<AppUploadCausalComparison>;
+export declare function runUploadedHostedCausalCheck(input: {
+    client: ApiClient;
+    creatorUsername: string;
+    task: AppTask;
+    sessionId: string;
+    teachingText: string;
+    timeoutMs?: number;
+    token?: string | null;
+    currentUser?: UserResponse | null;
+    captureSession?: TaskCaptureSession | null;
+}): Promise<AppUploadMachineCausalEvidence>;

package/dist/apps/loadCheck.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PLAYDROP_SURFACE_CONTEXT_OPTIONS = void 0;
 exports.resolveLoadCheckSurface = resolveLoadCheckSurface;
@@ -12,9 +15,15 @@ exports.formatHostedLoadCheckFailure = formatHostedLoadCheckFailure;
 exports.redactHostedLoadCheckSecrets = redactHostedLoadCheckSecrets;
 exports.runLocalHostedLoadCheck = runLocalHostedLoadCheck;
 exports.runUploadedHostedLoadCheck = runUploadedHostedLoadCheck;
+exports.sliceFirstPrimaryVerbAction = sliceFirstPrimaryVerbAction;
+exports.compareCausalFrames = compareCausalFrames;
+exports.runUploadedHostedCausalCheck = runUploadedHostedCausalCheck;
 const types_1 = require("@playdrop/types");
+const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const sharp_1 = __importDefault(require("sharp"));
 const appUrls_1 = require("../appUrls");
 const devShared_1 = require("../commands/devShared");
 const dev_1 = require("../commands/dev");
@@ -30,6 +39,12 @@ Object.defineProperty(exports, "PLAYDROP_SURFACE_CONTEXT_OPTIONS", { enumerable:
 const FRAME_SELECTOR = 'iframe[title="Game"]';
 const DEFAULT_HOSTED_LOAD_TIMEOUT_MS = 15000;
 const POST_READY_SETTLE_MS = 750;
+const CAUSAL_FRAME_MEAN_DELTA_MIN = 0.025;
+const CAUSAL_FRAME_CHANGED_PIXEL_RATIO_MIN = 0.12;
+const CAUSAL_START_FRAME_MEAN_DELTA_MIN = 0.02;
+const CAUSAL_START_FRAME_CHANGED_PIXEL_RATIO_MIN = 0.08;
+const CAUSAL_PROGRESS_FRAME_MEAN_DELTA_MIN = 0.012;
+const CAUSAL_PROGRESS_FRAME_CHANGED_PIXEL_RATIO_MIN = 0.05;
 const LOAD_CHECK_SURFACE_ORDER = ['DESKTOP', 'MOBILE_LANDSCAPE', 'MOBILE_PORTRAIT'];
 const GOOGLE_TELEMETRY_HOSTS = [
     'analytics.google.com',
@@ -499,6 +514,14 @@ async function saveScreenshot(page, screenshotPath) {
     console.log(`[check] Saved screenshot to ${(0, node_path_1.relative)(process.cwd(), normalizedPath) || normalizedPath}`);
     return normalizedPath;
 }
+async function saveGameFrameScreenshot(page, screenshotPath) {
+    const normalizedPath = typeof screenshotPath === 'string' ? screenshotPath.trim() : '';
+    if (!normalizedPath)
+        return null;
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(normalizedPath), { recursive: true });
+    await page.locator(FRAME_SELECTOR).screenshot({ path: normalizedPath, type: 'png' });
+    return normalizedPath;
+}
 function normalizeLoadCheckFailure(error, artifactFingerprint) {
     const rawMessage = error instanceof Error ? error.message : String(error);
     const message = normalizeLoadCheckMessage(rawMessage);
@@ -716,7 +739,7 @@ async function runHostedLoadCheck(options) {
                 hostedLaunchWaiter,
                 page.waitForTimeout(timeoutMs).then(() => {
                     throw new Error(expectedHostedLaunchState === 'ready'
-                        ? 'hosted_app_missing_ready: Hosted app did not report ready before the load-check timeout.'
+                        ? 'hosted_app_missing_ready: instrument_error:game_ready_timeout: Hosted app did not report sdk.host.ready() before the instrument timeout.'
                         : `hosted_app_gate_missing: Hosted app did not report ${expectedHostedLaunchState} before the load-check timeout.`);
                 }),
             ]);
@@ -737,6 +760,7 @@ async function runHostedLoadCheck(options) {
             if (isSoftwareWebGlRenderer(webglRenderer)) {
                 throw new Error(`project_check_webgl_renderer_software: WebGL renderer is "${webglRenderer}". Real hardware acceleration is required.`);
             }
+            await saveGameFrameScreenshot(page, options.readyGameFrameScreenshotPath);
             if (options.playtestTape && options.actions?.length) {
                 throw new Error('project_check_input_mode_conflict: playtest tape and legacy actions cannot run together.');
             }
@@ -753,6 +777,7 @@ async function runHostedLoadCheck(options) {
             else if (options.postReadyWaitMs && options.postReadyWaitMs > 0) {
                 await page.waitForTimeout(options.postReadyWaitMs);
             }
+            await saveGameFrameScreenshot(page, options.gameFrameScreenshotPath);
             screenshotPath = await saveScreenshot(page, options.screenshotPath);
         }, {
             ...options.contextOptions,
@@ -981,6 +1006,11 @@ async function runUploadedHostedLoadCheck(input) {
             expectedHostedLaunchState: resolvePostAuthHostedLaunchState(preview.localAppMetadata.controllerMode),
             contextOptions,
             screenshotPath: input.screenshotPath,
+            readyGameFrameScreenshotPath: input.readyGameFrameScreenshotPath,
+            gameFrameScreenshotPath: input.gameFrameScreenshotPath,
+            playtestTape: input.playtestTape,
+            playtestSurface: captureSurface,
+            postReadyWaitMs: input.postReadyWaitMs,
         });
     }
     else if (anonymousExpectedState === 'login_required') {
@@ -1009,6 +1039,11 @@ async function runUploadedHostedLoadCheck(input) {
                     savedSessionBootstrap: true,
                     contextOptions,
                     screenshotPath: input.screenshotPath,
+                    readyGameFrameScreenshotPath: input.readyGameFrameScreenshotPath,
+                    gameFrameScreenshotPath: input.gameFrameScreenshotPath,
+                    playtestTape: input.playtestTape,
+                    playtestSurface: captureSurface,
+                    postReadyWaitMs: input.postReadyWaitMs,
                 });
             }
         }
@@ -1021,6 +1056,11 @@ async function runUploadedHostedLoadCheck(input) {
             expectedHostedLaunchState: anonymousExpectedState,
             contextOptions,
             screenshotPath: input.screenshotPath,
+            readyGameFrameScreenshotPath: input.readyGameFrameScreenshotPath,
+            gameFrameScreenshotPath: input.gameFrameScreenshotPath,
+            playtestTape: input.playtestTape,
+            playtestSurface: captureSurface,
+            postReadyWaitMs: input.postReadyWaitMs,
         });
     }
     const recorded = await input.client.recordAppUploadLaunchCheck(input.creatorUsername, input.task.name, input.sessionId, {
@@ -1042,3 +1082,215 @@ async function runUploadedHostedLoadCheck(input) {
         artifactFingerprint: recordedLaunchCheck.artifactFingerprint,
     };
 }
+function sliceFirstPrimaryVerbAction(tape) {
+    const prefix = tape.events.slice(0, tape.startOnlyEventCount);
+    const postStartEvents = tape.events.slice(tape.startOnlyEventCount);
+    let actionEventCount = 0;
+    if (tape.primaryVerb === 'tap') {
+        actionEventCount = 1;
+    }
+    else if (tape.primaryVerb === 'key') {
+        const activeKeys = new Set();
+        for (let index = 0; index < postStartEvents.length; index += 1) {
+            const event = postStartEvents[index];
+            if (event.type === 'keyDown')
+                activeKeys.add(event.key);
+            if (event.type === 'keyUp')
+                activeKeys.delete(event.key);
+            if (activeKeys.size === 0 && index > 0) {
+                actionEventCount = index + 1;
+                break;
+            }
+        }
+    }
+    else {
+        const activePointers = new Set();
+        for (let index = 0; index < postStartEvents.length; index += 1) {
+            const event = postStartEvents[index];
+            if (event.type === 'pointerDown')
+                activePointers.add(event.pointerId ?? 0);
+            if (event.type === 'pointerUp')
+                activePointers.delete(event.pointerId ?? 0);
+            if (activePointers.size === 0 && index > 0) {
+                actionEventCount = index + 1;
+                break;
+            }
+        }
+    }
+    if (actionEventCount <= 0) {
+        throw new Error(`agent_task_machine_causal_gate_invalid_tape:first_${tape.primaryVerb}_action_incomplete`);
+    }
+    return {
+        ...tape,
+        events: [...prefix, ...postStartEvents.slice(0, actionEventCount)],
+    };
+}
+async function hashFile(path) {
+    return (0, node_crypto_1.createHash)('sha256').update(await (0, promises_1.readFile)(path)).digest('hex');
+}
+async function compareCausalFrames(firstPath, secondPath, thresholds = {
+    meanDeltaMin: CAUSAL_FRAME_MEAN_DELTA_MIN,
+    changedPixelRatioMin: CAUSAL_FRAME_CHANGED_PIXEL_RATIO_MIN,
+}) {
+    const readPixels = async (path) => {
+        return await (0, sharp_1.default)(path)
+            .resize(64, 64, { fit: 'fill' })
+            .greyscale()
+            .raw()
+            .toBuffer();
+    };
+    const [first, second] = await Promise.all([readPixels(firstPath), readPixels(secondPath)]);
+    if (first.length !== second.length || first.length === 0) {
+        throw new Error('agent_task_machine_causal_gate_frame_shape_mismatch');
+    }
+    let deltaTotal = 0;
+    let changedPixels = 0;
+    for (let index = 0; index < first.length; index += 1) {
+        const delta = Math.abs(first[index] - second[index]);
+        deltaTotal += delta;
+        if (delta >= 16)
+            changedPixels += 1;
+    }
+    const meanDelta = deltaTotal / first.length / 255;
+    const changedPixelRatio = changedPixels / first.length;
+    return {
+        meanDelta,
+        changedPixelRatio,
+        passed: meanDelta >= thresholds.meanDeltaMin || changedPixelRatio >= thresholds.changedPixelRatioMin,
+    };
+}
+async function runUploadedHostedCausalCheck(input) {
+    const primarySurface = input.task.primarySurface;
+    const fullTape = primarySurface ? input.task.playtestTapes?.[primarySurface] : null;
+    if (!primarySurface || !fullTape) {
+        throw new Error('agent_task_machine_causal_gate_primary_tape_required');
+    }
+    if (fullTape.startOnlyEventCount <= 0) {
+        throw new Error('agent_task_machine_causal_gate_start_only_required');
+    }
+    const startOnlyTape = {
+        ...fullTape,
+        events: fullTape.events.slice(0, fullTape.startOnlyEventCount),
+    };
+    const firstActionTape = sliceFirstPrimaryVerbAction(fullTape);
+    const tempDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'playdrop-causal-gate-'));
+    const paths = {
+        zeroInput: (0, node_path_1.join)(tempDir, 'zero-input.png'),
+        startOnlyReady: (0, node_path_1.join)(tempDir, 'start-only-ready.png'),
+        startOnly: (0, node_path_1.join)(tempDir, 'start-only.png'),
+        firstAction: (0, node_path_1.join)(tempDir, 'first-action.png'),
+        fullTape: (0, node_path_1.join)(tempDir, 'full-tape.png'),
+    };
+    const run = async (label, options) => {
+        console.log(`[upload] Machine causal gate: ${label} from sdk.host.ready().`);
+        const result = await runUploadedHostedLoadCheck({
+            client: input.client,
+            creatorUsername: input.creatorUsername,
+            task: input.task,
+            sessionId: input.sessionId,
+            timeoutMs: input.timeoutMs,
+            token: input.token,
+            currentUser: input.currentUser,
+            captureSession: input.captureSession,
+            ...options,
+        });
+        if (result.status !== 'PASSED') {
+            throw new Error(`Machine causal ${label} run failed. ${formatHostedLoadCheckFailure(input.task.name, result, 'staged')}`);
+        }
+        if (!result.artifactFingerprint) {
+            throw new Error('agent_task_machine_causal_gate_artifact_fingerprint_missing');
+        }
+        return result;
+    };
+    try {
+        const zeroInput = await run('zero-input', {
+            postReadyWaitMs: fullTape.durationMs,
+            gameFrameScreenshotPath: paths.zeroInput,
+        });
+        const startOnly = await run('start-only', {
+            playtestTape: startOnlyTape,
+            readyGameFrameScreenshotPath: paths.startOnlyReady,
+            gameFrameScreenshotPath: paths.startOnly,
+        });
+        const firstAction = await run('first-action', {
+            playtestTape: firstActionTape,
+            gameFrameScreenshotPath: paths.firstAction,
+        });
+        const full = await run('full-tape', {
+            playtestTape: fullTape,
+            gameFrameScreenshotPath: paths.fullTape,
+        });
+        const artifactFingerprint = full.artifactFingerprint;
+        if ([zeroInput, startOnly, firstAction].some((result) => result.artifactFingerprint !== artifactFingerprint)) {
+            throw new Error('agent_task_machine_causal_gate_artifact_changed_during_check');
+        }
+        const comparisons = {
+            startOnlyVsReady: await compareCausalFrames(paths.startOnlyReady, paths.startOnly, {
+                meanDeltaMin: CAUSAL_START_FRAME_MEAN_DELTA_MIN,
+                changedPixelRatioMin: CAUSAL_START_FRAME_CHANGED_PIXEL_RATIO_MIN,
+            }),
+            startOnlyVsZeroInput: await compareCausalFrames(paths.zeroInput, paths.startOnly, {
+                meanDeltaMin: CAUSAL_START_FRAME_MEAN_DELTA_MIN,
+                changedPixelRatioMin: CAUSAL_START_FRAME_CHANGED_PIXEL_RATIO_MIN,
+            }),
+            fullTapeVsZeroInput: await compareCausalFrames(paths.zeroInput, paths.fullTape, {
+                meanDeltaMin: CAUSAL_PROGRESS_FRAME_MEAN_DELTA_MIN,
+                changedPixelRatioMin: CAUSAL_PROGRESS_FRAME_CHANGED_PIXEL_RATIO_MIN,
+            }),
+            fullTapeVsStartOnly: await compareCausalFrames(paths.startOnly, paths.fullTape, {
+                meanDeltaMin: CAUSAL_PROGRESS_FRAME_MEAN_DELTA_MIN,
+                changedPixelRatioMin: CAUSAL_PROGRESS_FRAME_CHANGED_PIXEL_RATIO_MIN,
+            }),
+            fullTapeVsFirstAction: await compareCausalFrames(paths.firstAction, paths.fullTape, {
+                meanDeltaMin: CAUSAL_PROGRESS_FRAME_MEAN_DELTA_MIN,
+                changedPixelRatioMin: CAUSAL_PROGRESS_FRAME_CHANGED_PIXEL_RATIO_MIN,
+            }),
+        };
+        if (!comparisons.startOnlyVsReady.passed || !comparisons.startOnlyVsZeroInput.passed) {
+            throw new Error(`agent_task_machine_causal_gate_failed:start-only did not provably leave the title state. `
+                + `ready(mean=${comparisons.startOnlyVsReady.meanDelta.toFixed(4)},changed=${comparisons.startOnlyVsReady.changedPixelRatio.toFixed(4)}); `
+                + `zero(mean=${comparisons.startOnlyVsZeroInput.meanDelta.toFixed(4)},changed=${comparisons.startOnlyVsZeroInput.changedPixelRatio.toFixed(4)}). `
+                + 'Fix the start action, visible start-only outcome, or ready-relative timing.');
+        }
+        if (!comparisons.fullTapeVsZeroInput.passed || !comparisons.fullTapeVsStartOnly.passed) {
+            throw new Error(`agent_task_machine_causal_gate_failed:full tape did not meaningfully beat zero-input and start-only controls. `
+                + `zero(mean=${comparisons.fullTapeVsZeroInput.meanDelta.toFixed(4)},changed=${comparisons.fullTapeVsZeroInput.changedPixelRatio.toFixed(4)}); `
+                + `start(mean=${comparisons.fullTapeVsStartOnly.meanDelta.toFixed(4)},changed=${comparisons.fullTapeVsStartOnly.changedPixelRatio.toFixed(4)}). `
+                + 'Fix the game or tape before upload.');
+        }
+        if (!comparisons.fullTapeVsFirstAction.passed) {
+            throw new Error(`agent_task_machine_causal_gate_failed:first primary action trivially reached the full-tape outcome. `
+                + `action(mean=${comparisons.fullTapeVsFirstAction.meanDelta.toFixed(4)},changed=${comparisons.fullTapeVsFirstAction.changedPixelRatio.toFixed(4)}). `
+                + 'Add a sustained causal loop before upload.');
+        }
+        const teachingText = input.teachingText.trim();
+        const evidence = {
+            version: 1,
+            source: 'CLI_MACHINE',
+            artifactFingerprint,
+            primarySurface,
+            primaryVerb: fullTape.primaryVerb,
+            runs: {
+                zeroInput: { finalFrameSha256: await hashFile(paths.zeroInput) },
+                startOnly: {
+                    readyFrameSha256: await hashFile(paths.startOnlyReady),
+                    finalFrameSha256: await hashFile(paths.startOnly),
+                },
+                firstAction: { finalFrameSha256: await hashFile(paths.firstAction) },
+                fullTape: { finalFrameSha256: await hashFile(paths.fullTape) },
+            },
+            comparisons,
+            teachingText,
+            teachingTextSha256: (0, node_crypto_1.createHash)('sha256').update(teachingText).digest('hex'),
+        };
+        const recorded = await input.client.recordAppUploadCausalCheck(input.creatorUsername, input.task.name, input.sessionId, { evidence });
+        if (recorded.session.causalCheck.status !== 'PASSED') {
+            throw new Error('agent_task_machine_causal_gate_not_recorded');
+        }
+        console.log(`[upload] Machine causal gate passed for ${input.creatorUsername}/${input.task.name}.`);
+        return evidence;
+    }
+    finally {
+        await (0, promises_1.rm)(tempDir, { recursive: true, force: true });
+    }
+}

package/dist/apps/playtestContract.d.ts

@@ -0,0 +1,2 @@
+import type { AppTask } from '../catalogue';
+export declare function assertPrimaryVerbTeachingParity(task: AppTask): string;

package/dist/apps/playtestContract.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertPrimaryVerbTeachingParity = assertPrimaryVerbTeachingParity;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const types_1 = require("@playdrop/types");
+function extractPotentialPlayerText(source, extension) {
+    const candidates = new Set();
+    if (extension === '.html') {
+        const visibleText = source
+            .replace(/<!--[\s\S]*?-->/g, ' ')
+            .replace(/<(?:script|style)\b[^>]*>[\s\S]*?<\/(?:script|style)>/gi, ' ')
+            .replace(/<[^>]+>/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (visibleText)
+            candidates.add(visibleText.slice(0, 300));
+    }
+    const stringLiteral = /"((?:\\.|[^"\\]){1,300})"|'((?:\\.|[^'\\]){1,300})'|`((?:\\.|[^`\\]){1,300})`/g;
+    for (const match of source.matchAll(stringLiteral)) {
+        const text = (match[1] ?? match[2] ?? match[3] ?? '')
+            .replace(/\\[nrt]/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (text)
+            candidates.add(text);
+    }
+    return Array.from(candidates);
+}
+function readPrimaryVerbTeachingText(task) {
+    const runtimeRoot = (0, node_path_1.dirname)(task.filePath);
+    const matches = new Set();
+    const walk = (dir) => {
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            const absolute = (0, node_path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!['node_modules', '.git', 'assets'].includes(entry.name))
+                    walk(absolute);
+                continue;
+            }
+            if (!entry.isFile() || !['.html', '.js', '.mjs', '.cjs'].includes((0, node_path_1.extname)(entry.name).toLowerCase()))
+                continue;
+            const extension = (0, node_path_1.extname)(entry.name).toLowerCase();
+            const source = (0, node_fs_1.readFileSync)(absolute, 'utf8');
+            for (const text of extractPotentialPlayerText(source, extension)) {
+                if (types_1.APP_PLAYTEST_PRIMARY_VERB_VALUES.some((verb) => (0, types_1.appPlaytestTeachingTextMatchesVerb)(text, verb))) {
+                    matches.add(text);
+                }
+            }
+        }
+    };
+    walk(runtimeRoot);
+    return Array.from(matches);
+}
+function assertPrimaryVerbTeachingParity(task) {
+    const primarySurface = task.primarySurface;
+    const tape = primarySurface ? task.playtestTapes?.[primarySurface] : null;
+    if (!primarySurface || !tape) {
+        throw new Error('agent_task_primary_verb_tape_required');
+    }
+    const teachingTexts = readPrimaryVerbTeachingText(task);
+    const matchingText = teachingTexts.find((text) => (0, types_1.appPlaytestTeachingTextMatchesVerb)(text, tape.primaryVerb));
+    if (!matchingText) {
+        throw new Error(`agent_task_primary_verb_not_taught:${tape.primaryVerb}: show the player a concise instruction using the declared primary verb.`);
+    }
+    const competingVerbs = types_1.APP_PLAYTEST_PRIMARY_VERB_VALUES
+        .filter((verb) => verb !== tape.primaryVerb)
+        .filter((verb) => teachingTexts.some((text) => {
+        if (!(0, types_1.appPlaytestTeachingTextMatchesVerb)(text, verb))
+            return false;
+        return verb !== 'tap' || !/\btap\b[^\n]{0,30}\b(?:start|play|begin|continue|retry)\b/i.test(text);
+    }));
+    if (competingVerbs.length > 0) {
+        throw new Error(`agent_task_primary_verb_teaching_mismatch:${tape.primaryVerb}:${competingVerbs.join(',')}`);
+    }
+    return matchingText;
+}

package/dist/apps/staticHtml.d.ts

@@ -0,0 +1,28 @@
+import type { AppSurface } from '@playdrop/types';
+import type { AppTask } from '../catalogue';
+import { type AppBuildArtifacts } from './build';
+export type StaticHtmlMetadata = {
+    title: string;
+    description: string | null;
+    imagePath: string | null;
+    warnings: string[];
+};
+export type PreparedStaticHtmlProject = {
+    sourceTask: AppTask;
+    runtimeTask: AppTask;
+    artifacts: AppBuildArtifacts;
+    sourceHash: string;
+    runtimeHash: string;
+    metadata: StaticHtmlMetadata;
+    runtimeDir: string;
+    cleanup: () => Promise<void>;
+};
+export declare function parseStaticHtmlMetadata(projectDir: string, entryPoint?: string): StaticHtmlMetadata;
+export declare function buildStaticGameSlug(title: string, taskId?: number): string;
+export declare function prepareStaticHtmlProject(input: {
+    projectDir: string;
+    taskId?: number;
+    appName?: string;
+    primarySurface: AppSurface;
+}): Promise<PreparedStaticHtmlProject>;
+export declare function sha256File(filePath: string): string;