@playdrop/playdrop-cli 0.12.38 → 0.12.39

package/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.12.38",
+  "version": "0.12.39",
   "build": 1,
-  "runtimeSdkVersion": "0.12.38",
+  "runtimeSdkVersion": "0.12.39",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/dist/apps/build.d.ts

@@ -1,4 +1,4 @@
-import type { AppSurface, AppType } from '@playdrop/types';
+import type { AppPlaytestTapes, AppSurface, AppType } from '@playdrop/types';
 import type { AppTask } from '../catalogue';
 export type AppBuildMetadata = {
     displayName?: string;
@@ -7,6 +7,8 @@ export type AppBuildMetadata = {
     emoji?: string | null;
     color?: string | null;
     surfaceTargets?: AppSurface[];
+    primarySurface?: AppSurface;
+    playtestTapes?: AppPlaytestTapes;
     entryPoint?: string;
 };
 export type AppBuildArtifacts = {

package/dist/apps/build.js

@@ -606,6 +606,10 @@ async function buildApp(task) {
     if (task.surfaceTargets && task.surfaceTargets.length > 0) {
         metadata.surfaceTargets = task.surfaceTargets;
     }
+    if (task.primarySurface)
+        metadata.primarySurface = task.primarySurface;
+    if (task.playtestTapes)
+        metadata.playtestTapes = task.playtestTapes;
     metadata.entryPoint = bundleArchive.entryPoint;
     return {
         bundleFile,

package/dist/apps/loadCheck.d.ts

@@ -1,8 +1,9 @@
 import type { ApiClient } from '@playdrop/api-client';
-import type { UserResponse } from '@playdrop/types';
-import type { Frame, Page } from 'playwright-core';
+import { type AppPlaytestTape, type AppSurface, type UserResponse } from '@playdrop/types';
+import type { BrowserContextOptions, Frame, Page } from 'playwright-core';
 import type { AppTask } from '../catalogue';
 import { type TaskCaptureSession } from '../appUrls';
+export { PLAYDROP_SURFACE_CONTEXT_OPTIONS } from './surfaceProfiles';
 export type HostedLoadCheckResult = {
     status: 'PASSED' | 'FAILED';
     errorCode: string | null;
@@ -41,6 +42,8 @@ export type ProjectCheckAction = {
     type: 'wait';
     ms: number;
 };
+export declare function resolveLoadCheckSurface(surfaceTargets: unknown, primarySurface?: unknown): AppSurface;
+export declare function cloneLoadCheckContextOptions(surface: AppSurface): BrowserContextOptions;
 export declare function isSoftwareWebGlRenderer(renderer: string | null | undefined): boolean;
 export declare function normalizeProjectCheckActions(value: unknown): ProjectCheckAction[];
 export declare function focusProjectCheckGameFrame(page: Pick<Page, 'mouse'>, frame: Frame): Promise<{
@@ -49,6 +52,7 @@ export declare function focusProjectCheckGameFrame(page: Pick<Page, 'mouse'>, fr
     width: number;
     height: number;
 }>;
+export declare function dispatchPlaytestTapeToFrame(page: Page, frame: Frame, surface: AppSurface, tape: AppPlaytestTape): Promise<void>;
 export declare function dispatchProjectCheckActionsToFrame(page: Page, frame: Frame, actions: readonly ProjectCheckAction[]): Promise<void>;
 export declare function formatHostedLoadCheckFailure(taskName: string, result: HostedLoadCheckResult, scope?: 'local' | 'staged' | 'final'): string;
 export declare function redactHostedLoadCheckSecrets(text: string, sourceUrl: string): string;
@@ -66,6 +70,9 @@ export declare function runLocalHostedLoadCheck(input: {
     allowUnregisteredViewerLaunch?: boolean;
     screenshotPath?: string | null;
     actions?: ProjectCheckAction[];
+    surface?: AppSurface;
+    playtestTape?: AppPlaytestTape;
+    postReadyWaitMs?: number;
 }): Promise<HostedLoadCheckResult>;
 export declare function runUploadedHostedLoadCheck(input: {
     client: ApiClient;

package/dist/apps/loadCheck.js

@@ -1,13 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAYDROP_SURFACE_CONTEXT_OPTIONS = void 0;
+exports.resolveLoadCheckSurface = resolveLoadCheckSurface;
+exports.cloneLoadCheckContextOptions = cloneLoadCheckContextOptions;
 exports.isSoftwareWebGlRenderer = isSoftwareWebGlRenderer;
 exports.normalizeProjectCheckActions = normalizeProjectCheckActions;
 exports.focusProjectCheckGameFrame = focusProjectCheckGameFrame;
+exports.dispatchPlaytestTapeToFrame = dispatchPlaytestTapeToFrame;
 exports.dispatchProjectCheckActionsToFrame = dispatchProjectCheckActionsToFrame;
 exports.formatHostedLoadCheckFailure = formatHostedLoadCheckFailure;
 exports.redactHostedLoadCheckSecrets = redactHostedLoadCheckSecrets;
 exports.runLocalHostedLoadCheck = runLocalHostedLoadCheck;
 exports.runUploadedHostedLoadCheck = runUploadedHostedLoadCheck;
+const types_1 = require("@playdrop/types");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const appUrls_1 = require("../appUrls");
@@ -19,33 +24,13 @@ const devAuth_1 = require("../devAuth");
 const playwright_1 = require("../playwright");
 const sessionCookie_1 = require("../sessionCookie");
 const registration_1 = require("./registration");
+const surfaceProfiles_1 = require("./surfaceProfiles");
+var surfaceProfiles_2 = require("./surfaceProfiles");
+Object.defineProperty(exports, "PLAYDROP_SURFACE_CONTEXT_OPTIONS", { enumerable: true, get: function () { return surfaceProfiles_2.PLAYDROP_SURFACE_CONTEXT_OPTIONS; } });
 const FRAME_SELECTOR = 'iframe[title="Game"]';
 const DEFAULT_HOSTED_LOAD_TIMEOUT_MS = 15000;
 const POST_READY_SETTLE_MS = 750;
-const MOBILE_USER_AGENT = 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1';
 const LOAD_CHECK_SURFACE_ORDER = ['DESKTOP', 'MOBILE_LANDSCAPE', 'MOBILE_PORTRAIT'];
-const LOAD_CHECK_SURFACE_CONTEXT_OPTIONS = {
-    DESKTOP: {
-        viewport: { width: 1280, height: 720 },
-        deviceScaleFactor: 1,
-        isMobile: false,
-        hasTouch: false,
-    },
-    MOBILE_LANDSCAPE: {
-        viewport: { width: 896, height: 414 },
-        deviceScaleFactor: 2,
-        isMobile: true,
-        hasTouch: true,
-        userAgent: MOBILE_USER_AGENT,
-    },
-    MOBILE_PORTRAIT: {
-        viewport: { width: 414, height: 896 },
-        deviceScaleFactor: 2,
-        isMobile: true,
-        hasTouch: true,
-        userAgent: MOBILE_USER_AGENT,
-    },
-};
 const GOOGLE_TELEMETRY_HOSTS = [
     'analytics.google.com',
     'googletagmanager.com',
@@ -189,8 +174,12 @@ function normalizeLoadCheckSurfaceTargets(value) {
     }
     return Array.from(new Set(value.map(normalizeLoadCheckSurface).filter((entry) => Boolean(entry))));
 }
-function resolveLoadCheckSurface(surfaceTargets) {
+function resolveLoadCheckSurface(surfaceTargets, primarySurface) {
     const targets = normalizeLoadCheckSurfaceTargets(surfaceTargets);
+    const primary = normalizeLoadCheckSurface(primarySurface);
+    if (primary && targets.includes(primary)) {
+        return primary;
+    }
     for (const surface of LOAD_CHECK_SURFACE_ORDER) {
         if (targets.includes(surface)) {
             return surface;
@@ -199,11 +188,7 @@ function resolveLoadCheckSurface(surfaceTargets) {
     return 'DESKTOP';
 }
 function cloneLoadCheckContextOptions(surface) {
-    const source = LOAD_CHECK_SURFACE_CONTEXT_OPTIONS[surface];
-    return {
-        ...source,
-        viewport: source.viewport ? { ...source.viewport } : source.viewport,
-    };
+    return (0, surfaceProfiles_1.clonePlaydropSurfaceContextOptions)(surface);
 }
 function resolvePostAuthHostedLaunchState(controllerMode) {
     return controllerMode === 'REQUIRED' ? 'controller_required' : 'ready';
@@ -329,6 +314,131 @@ async function focusProjectCheckGameFrame(page, frame) {
         await element.dispose().catch(() => { });
     }
 }
+async function prepareProjectCheckGameFrame(frame) {
+    const element = await frame.frameElement();
+    try {
+        await element.scrollIntoViewIfNeeded().catch(() => { });
+        const box = await element.boundingBox();
+        if (!box) {
+            throw new Error('project_check_game_frame_not_visible');
+        }
+        await element.focus().catch(() => { });
+        await frame.evaluate(() => {
+            window.focus();
+            if (document.body) {
+                document.body.tabIndex = document.body.tabIndex >= 0 ? document.body.tabIndex : -1;
+                document.body.focus();
+            }
+        }).catch(() => { });
+        return box;
+    }
+    finally {
+        await element.dispose().catch(() => { });
+    }
+}
+function resolveTapePoint(box, event) {
+    return {
+        x: box.x + (event.x * box.width),
+        y: box.y + (event.y * box.height),
+    };
+}
+async function dispatchTouchPoints(session, type, points) {
+    await session.send('Input.dispatchTouchEvent', {
+        type,
+        touchPoints: Array.from(points.entries()).map(([id, point]) => ({
+            id,
+            x: point.x,
+            y: point.y,
+            radiusX: 1,
+            radiusY: 1,
+            force: 1,
+        })),
+    });
+}
+async function dispatchPlaytestTapeToFrame(page, frame, surface, tape) {
+    const box = await prepareProjectCheckGameFrame(frame);
+    const mobile = surface !== 'DESKTOP';
+    const session = mobile ? await page.context().newCDPSession(page) : null;
+    const touchPoints = new Map();
+    const startedAt = Date.now();
+    try {
+        for (const event of tape.events) {
+            const waitMs = event.atMs - (Date.now() - startedAt);
+            if (waitMs > 0) {
+                await page.waitForTimeout(waitMs);
+            }
+            if (event.type === 'keyDown') {
+                await page.keyboard.down(event.key);
+                continue;
+            }
+            if (event.type === 'keyUp') {
+                await page.keyboard.up(event.key);
+                continue;
+            }
+            if (!('x' in event) || !('y' in event)) {
+                throw new Error(`project_check_playtest_event_unsupported:${event.type}`);
+            }
+            const point = resolveTapePoint(box, event);
+            const pointerId = 'pointerId' in event ? event.pointerId ?? 0 : 0;
+            if (event.type === 'tap') {
+                if (mobile && session) {
+                    touchPoints.set(pointerId, point);
+                    await dispatchTouchPoints(session, 'touchStart', touchPoints);
+                    await page.waitForTimeout(event.durationMs ?? types_1.APP_PLAYTEST_DEFAULT_TAP_DURATION_MS);
+                    touchPoints.delete(pointerId);
+                    await dispatchTouchPoints(session, 'touchEnd', touchPoints);
+                }
+                else {
+                    await page.mouse.move(point.x, point.y);
+                    await page.mouse.down({ button: 'left' });
+                    await page.waitForTimeout(event.durationMs ?? types_1.APP_PLAYTEST_DEFAULT_TAP_DURATION_MS);
+                    await page.mouse.up({ button: 'left' });
+                }
+                continue;
+            }
+            if (event.type === 'pointerDown') {
+                if (mobile && session) {
+                    touchPoints.set(pointerId, point);
+                    await dispatchTouchPoints(session, 'touchStart', touchPoints);
+                }
+                else {
+                    await page.mouse.move(point.x, point.y);
+                    await page.mouse.down({ button: 'left' });
+                }
+                continue;
+            }
+            if (event.type === 'pointerMove') {
+                if (mobile && session) {
+                    touchPoints.set(pointerId, point);
+                    await dispatchTouchPoints(session, 'touchMove', touchPoints);
+                }
+                else {
+                    await page.mouse.move(point.x, point.y);
+                }
+                continue;
+            }
+            if (event.type === 'pointerUp') {
+                if (mobile && session) {
+                    touchPoints.delete(pointerId);
+                    await dispatchTouchPoints(session, 'touchEnd', touchPoints);
+                }
+                else {
+                    await page.mouse.move(point.x, point.y);
+                    await page.mouse.up({ button: 'left' });
+                }
+            }
+        }
+        const remainingMs = tape.durationMs - (Date.now() - startedAt);
+        if (remainingMs > 0) {
+            await page.waitForTimeout(remainingMs);
+        }
+    }
+    finally {
+        if (session) {
+            await session.detach().catch(() => { });
+        }
+    }
+}
 async function dispatchProjectCheckActionsToFrame(page, frame, actions) {
     for (const action of actions) {
         if (action.type === 'wait') {
@@ -627,10 +737,22 @@ async function runHostedLoadCheck(options) {
             if (isSoftwareWebGlRenderer(webglRenderer)) {
                 throw new Error(`project_check_webgl_renderer_software: WebGL renderer is "${webglRenderer}". Real hardware acceleration is required.`);
             }
-            if (options.actions?.length) {
+            if (options.playtestTape && options.actions?.length) {
+                throw new Error('project_check_input_mode_conflict: playtest tape and legacy actions cannot run together.');
+            }
+            if (options.playtestTape) {
+                if (!options.playtestSurface) {
+                    throw new Error('project_check_playtest_surface_required');
+                }
+                await dispatchPlaytestTapeToFrame(page, frame, options.playtestSurface, options.playtestTape);
+            }
+            else if (options.actions?.length) {
                 await dispatchProjectCheckActionsToFrame(page, frame, options.actions);
                 await page.waitForTimeout(POST_READY_SETTLE_MS);
             }
+            else if (options.postReadyWaitMs && options.postReadyWaitMs > 0) {
+                await page.waitForTimeout(options.postReadyWaitMs);
+            }
             screenshotPath = await saveScreenshot(page, options.screenshotPath);
         }, {
             ...options.contextOptions,
@@ -733,7 +855,11 @@ async function runLocalHostedLoadCheck(input) {
             ? null
             : input.devRouterPort;
         const localAppMetadata = mountedRuntime.runtimeAssetManifest.response.localAppMetadata;
-        const captureSurface = resolveLoadCheckSurface(localAppMetadata.surfaceTargets);
+        const declaredSurfaces = normalizeLoadCheckSurfaceTargets(localAppMetadata.surfaceTargets);
+        const captureSurface = input.surface ?? resolveLoadCheckSurface(localAppMetadata.surfaceTargets, input.task.primarySurface);
+        if (!declaredSurfaces.includes(captureSurface)) {
+            return buildFailedLoadCheckResult('surface_unsupported', `Surface ${captureSurface} is not declared in surfaceTargets for "${input.task.name}".`, null);
+        }
         const contextOptions = cloneLoadCheckContextOptions(captureSurface);
         const anonymousExpectedState = resolveAnonymousHostedLaunchState({
             ...localAppMetadata,
@@ -754,6 +880,9 @@ async function runLocalHostedLoadCheck(input) {
                 contextOptions,
                 screenshotPath: input.screenshotPath,
                 actions: input.actions,
+                playtestTape: input.playtestTape,
+                playtestSurface: captureSurface,
+                postReadyWaitMs: input.postReadyWaitMs,
             });
         }
         if (anonymousExpectedState === 'login_required') {
@@ -797,6 +926,9 @@ async function runLocalHostedLoadCheck(input) {
                 contextOptions,
                 screenshotPath: input.screenshotPath,
                 actions: input.actions,
+                playtestTape: input.playtestTape,
+                playtestSurface: captureSurface,
+                postReadyWaitMs: input.postReadyWaitMs,
             });
         }
         return await runHostedLoadCheck({
@@ -813,6 +945,9 @@ async function runLocalHostedLoadCheck(input) {
             contextOptions,
             screenshotPath: input.screenshotPath,
             actions: input.actions,
+            playtestTape: input.playtestTape,
+            playtestSurface: captureSurface,
+            postReadyWaitMs: input.postReadyWaitMs,
         });
     }
     finally {
@@ -829,7 +964,7 @@ function appendLoadCheckParams(targetUrl, devAuth) {
 }
 async function runUploadedHostedLoadCheck(input) {
     const preview = await input.client.fetchAppUploadLaunchCheckPreview(input.creatorUsername, input.task.name, input.sessionId);
-    const captureSurface = resolveLoadCheckSurface(preview.localAppMetadata.surfaceTargets);
+    const captureSurface = resolveLoadCheckSurface(preview.localAppMetadata.surfaceTargets, input.task.primarySurface);
     const contextOptions = cloneLoadCheckContextOptions(captureSurface);
     const anonymousExpectedState = resolveAnonymousHostedLaunchState({
         ...preview.localAppMetadata,

package/dist/apps/surfaceProfiles.d.ts

@@ -0,0 +1,10 @@
+import type { AppSurface } from '@playdrop/types';
+import type { BrowserContextOptions } from 'playwright-core';
+export type PlaydropSurfaceProfile = {
+    contextOptions: BrowserContextOptions;
+    playwrightMcpDevice: string | null;
+};
+export declare const PLAYDROP_SURFACE_PROFILES: Record<AppSurface, PlaydropSurfaceProfile>;
+export declare const PLAYDROP_SURFACE_CONTEXT_OPTIONS: Record<AppSurface, BrowserContextOptions>;
+export declare function clonePlaydropSurfaceContextOptions(surface: AppSurface): BrowserContextOptions;
+export declare function buildPlaywrightMcpSurfaceArgs(surface: AppSurface): string[];

package/dist/apps/surfaceProfiles.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAYDROP_SURFACE_CONTEXT_OPTIONS = exports.PLAYDROP_SURFACE_PROFILES = void 0;
+exports.clonePlaydropSurfaceContextOptions = clonePlaydropSurfaceContextOptions;
+exports.buildPlaywrightMcpSurfaceArgs = buildPlaywrightMcpSurfaceArgs;
+const MOBILE_USER_AGENT = 'Mozilla/5.0 (iPhone; CPU iPhone OS 26_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Mobile/15E148 Safari/604.1';
+exports.PLAYDROP_SURFACE_PROFILES = {
+    DESKTOP: {
+        contextOptions: {
+            viewport: { width: 1280, height: 720 },
+            deviceScaleFactor: 1,
+            isMobile: false,
+            hasTouch: false,
+        },
+        playwrightMcpDevice: null,
+    },
+    MOBILE_LANDSCAPE: {
+        contextOptions: {
+            viewport: { width: 844, height: 390 },
+            screen: { width: 844, height: 390 },
+            deviceScaleFactor: 3,
+            isMobile: true,
+            hasTouch: true,
+            userAgent: MOBILE_USER_AGENT,
+        },
+        playwrightMcpDevice: 'iPhone 13 landscape',
+    },
+    MOBILE_PORTRAIT: {
+        contextOptions: {
+            viewport: { width: 390, height: 844 },
+            screen: { width: 390, height: 844 },
+            deviceScaleFactor: 3,
+            isMobile: true,
+            hasTouch: true,
+            userAgent: MOBILE_USER_AGENT,
+        },
+        playwrightMcpDevice: 'iPhone 13',
+    },
+};
+exports.PLAYDROP_SURFACE_CONTEXT_OPTIONS = {
+    DESKTOP: exports.PLAYDROP_SURFACE_PROFILES.DESKTOP.contextOptions,
+    MOBILE_LANDSCAPE: exports.PLAYDROP_SURFACE_PROFILES.MOBILE_LANDSCAPE.contextOptions,
+    MOBILE_PORTRAIT: exports.PLAYDROP_SURFACE_PROFILES.MOBILE_PORTRAIT.contextOptions,
+};
+function clonePlaydropSurfaceContextOptions(surface) {
+    const source = exports.PLAYDROP_SURFACE_PROFILES[surface].contextOptions;
+    return {
+        ...source,
+        viewport: source.viewport ? { ...source.viewport } : source.viewport,
+        screen: source.screen ? { ...source.screen } : source.screen,
+    };
+}
+function buildPlaywrightMcpSurfaceArgs(surface) {
+    const profile = exports.PLAYDROP_SURFACE_PROFILES[surface];
+    const viewport = profile.contextOptions.viewport;
+    if (!viewport) {
+        throw new Error(`playdrop_surface_viewport_missing:${surface}`);
+    }
+    return [
+        ...(profile.playwrightMcpDevice ? ['--device', profile.playwrightMcpDevice] : []),
+        '--viewport-size',
+        `${viewport.width}x${viewport.height}`,
+    ];
+}

package/dist/apps/upload.js

@@ -247,6 +247,8 @@ async function uploadAppVersion(client, task, artifacts, options) {
         design: task.design,
         clearTags: options?.clearTags,
         surfaceTargets: task.surfaceTargets,
+        primarySurface: task.primarySurface,
+        playtestTapes: task.playtestTapes,
         assetSpecSupport: (task.assetSpecSupport ?? []).map((row) => ({
             assetSpecRef: row.assetSpec,
             versionRange: row.versionRange,

package/dist/catalogue.d.ts

@@ -1,4 +1,4 @@
-import { type AppAchievementCatalogueDefinition, type AppAuthMode, type AppControllerMode, type AppHostingMode, type AppLeaderboardCatalogueDefinition, type AppMetadataAssetSpecSupport, type AppSurface, type AppType, type AppVersionDesign, type AppVersionVisibility, type AssetSpecContract, type AssetSpecStatus, type AssetSpecValidationKind, type CatalogueTagGroupDefinition, type ContentLicense, type PlayerMetaDefinitionStatus } from '@playdrop/types';
+import { type AppAchievementCatalogueDefinition, type AppAuthMode, type AppControllerMode, type AppHostingMode, type AppLeaderboardCatalogueDefinition, type AppMetadataAssetSpecSupport, type AppPlaytestTapes, type AppSurface, type AppType, type AppVersionDesign, type AppVersionVisibility, type AssetSpecContract, type AssetSpecStatus, type AssetSpecValidationKind, type CatalogueTagGroupDefinition, type ContentLicense, type PlayerMetaDefinitionStatus } from '@playdrop/types';
 import { type AssetSpecSupportDeclaration } from './assetSpecs';
 export type CatalogueJson = {
     apps?: Array<Record<string, unknown>>;
@@ -40,6 +40,8 @@ export type AppCatalogueEntry = {
     remixSource?: string | null;
     remix?: string;
     surfaceTargets?: Record<string, unknown> | AppSurface[] | null;
+    primarySurface?: string | null;
+    playtestTapes?: unknown;
     design?: unknown;
     version?: string;
     releaseNotes?: string;
@@ -178,6 +180,8 @@ export type AppTask = {
     emoji?: string | null;
     color?: string | null;
     surfaceTargets: AppSurface[];
+    primarySurface?: AppSurface;
+    playtestTapes?: AppPlaytestTapes;
     design?: AppVersionDesign;
     missingMetadata: string[];
     version?: string;
@@ -346,6 +350,8 @@ export type ValidatedAppMetadata = {
     color?: string | null;
     surfaceTargets: AppSurface[];
     surfaceTargetMap: SurfaceTargetsMap;
+    primarySurface?: AppSurface;
+    playtestTapes?: AppPlaytestTapes;
     missingFields: string[];
     warnings: string[];
     errors: string[];

package/dist/catalogue.js

@@ -868,6 +868,29 @@ function validateAppMetadata(entry) {
     catch (error) {
         errors.push(error?.message || 'invalid surfaceTargets');
     }
+    let primarySurface;
+    if (Object.prototype.hasOwnProperty.call(entry, 'primarySurface')) {
+        primarySurface = (0, types_1.parseAppSurface)(entry.primarySurface) ?? undefined;
+        if (!primarySurface) {
+            errors.push('primarySurface must be DESKTOP, MOBILE_LANDSCAPE, or MOBILE_PORTRAIT');
+        }
+        else if (!surfaceTargetsList.includes(primarySurface)) {
+            errors.push(`primarySurface ${primarySurface} must also be enabled in surfaceTargets`);
+        }
+    }
+    let playtestTapes;
+    if (Object.prototype.hasOwnProperty.call(entry, 'playtestTapes')) {
+        const normalized = (0, types_1.normalizeAppPlaytestTapes)(entry.playtestTapes, {
+            surfaceTargets: surfaceTargetsList,
+            requireComplete: true,
+        });
+        if (!normalized.ok) {
+            errors.push(normalized.error);
+        }
+        else {
+            playtestTapes = normalized.value;
+        }
+    }
     return {
         displayName,
         description,
@@ -876,6 +899,8 @@ function validateAppMetadata(entry) {
         color,
         surfaceTargets: surfaceTargetsList,
         surfaceTargetMap: surfaceTargetsMap,
+        primarySurface,
+        playtestTapes,
         missingFields,
         warnings,
         errors,
@@ -1486,6 +1511,8 @@ function buildAppTasks(rootDir, catalogues, options) {
                 emoji: metadata.emoji === undefined ? undefined : metadata.emoji,
                 color: metadata.color === undefined ? undefined : metadata.color,
                 surfaceTargets: metadata.surfaceTargets,
+                primarySurface: metadata.primarySurface,
+                playtestTapes: metadata.playtestTapes,
                 design,
                 missingMetadata: metadata.missingFields,
                 // Versioning fields

package/dist/commands/check.d.ts

@@ -3,6 +3,7 @@ type ProjectCheckOptions = {
     timeout?: string | number;
     screenshot?: string;
     actions?: string;
+    tape?: string;
 };
 export declare function check(targetArg: string | undefined, options?: ProjectCheckOptions): Promise<void>;
 export {};

package/dist/commands/check.js

@@ -53,6 +53,13 @@ function readProjectCheckActions(actionsPath) {
 function defaultProjectCheckScreenshotPath(appName) {
     return (0, node_path_1.join)('assets', 'marketing', 'playdrop', 'check', `${appName}.png`);
 }
+function buildComparisonScreenshotPath(basePath, run) {
+    const extension = (0, node_path_1.extname)(basePath);
+    if (!extension) {
+        return `${basePath}-${run}.png`;
+    }
+    return `${basePath.slice(0, -extension.length)}-${run}${extension}`;
+}
 async function check(targetArg, options = {}) {
     let timeoutMs;
     let actions;
@@ -86,6 +93,27 @@ async function check(targetArg, options = {}) {
         process.exitCode = 1;
         return;
     }
+    let tapeSurface = null;
+    let playtestTape = null;
+    if (options.tape) {
+        if (actions.length > 0) {
+            (0, messages_1.printErrorWithHelp)('--tape and --actions cannot be used together.', ['Use the catalogue playtest tape by itself so the timed sequence remains deterministic.'], { command: 'project check' });
+            process.exitCode = 1;
+            return;
+        }
+        tapeSurface = (0, types_1.parseAppSurface)(options.tape);
+        if (!tapeSurface) {
+            (0, messages_1.printErrorWithHelp)(`Invalid tape surface "${options.tape}".`, ['Use DESKTOP, MOBILE_LANDSCAPE, or MOBILE_PORTRAIT.'], { command: 'project check' });
+            process.exitCode = 1;
+            return;
+        }
+        playtestTape = taskLookup.task.playtestTapes?.[tapeSurface] ?? null;
+        if (!playtestTape) {
+            (0, messages_1.printErrorWithHelp)(`No ${tapeSurface} playtest tape is declared for this app.`, [`Add playtestTapes.${tapeSurface} to catalogue.json.`], { command: 'project check' });
+            process.exitCode = 1;
+            return;
+        }
+    }
     let appName = resolvedTarget.appName;
     try {
         const match = (0, catalogue_utils_1.findAppDefinition)(filePath);
@@ -176,7 +204,7 @@ async function check(targetArg, options = {}) {
                 console.log(`[check] package.json detected at ${projectLabel}, but no "dev" script was found. Run your app build manually if needed.`);
             }
         }
-        const result = await (0, loadCheck_1.runLocalHostedLoadCheck)({
+        const runCheck = async (input) => await (0, loadCheck_1.runLocalHostedLoadCheck)({
             client,
             apiBase: envConfig.apiBase,
             webBase: envConfig.webBase,
@@ -186,9 +214,47 @@ async function check(targetArg, options = {}) {
             token,
             currentUser: null,
             captureSession,
-            screenshotPath,
+            screenshotPath: input.screenshotPath,
             actions,
+            surface: input.surface,
+            playtestTape: input.tape,
+            postReadyWaitMs: input.postReadyWaitMs,
         });
+        if (tapeSurface && playtestTape) {
+            const idleScreenshotPath = buildComparisonScreenshotPath(screenshotPath, 'idle');
+            const tapeScreenshotPath = buildComparisonScreenshotPath(screenshotPath, 'tape');
+            console.log(`[check] Running ${playtestTape.durationMs} ms zero-input baseline on ${tapeSurface}.`);
+            const idleResult = await runCheck({
+                screenshotPath: idleScreenshotPath,
+                surface: tapeSurface,
+                postReadyWaitMs: playtestTape.durationMs,
+            });
+            if (idleResult.status !== 'PASSED') {
+                (0, messages_1.printErrorWithHelp)((0, loadCheck_1.formatHostedLoadCheckFailure)(appName, idleResult, 'local'), idleResult.screenshotPath ? [`Idle screenshot: ${idleResult.screenshotPath}`] : [], { command: 'project check' });
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`[check] Reopening a clean run and executing the ${tapeSurface} tape.`);
+            const tapeResult = await runCheck({
+                screenshotPath: tapeScreenshotPath,
+                surface: tapeSurface,
+                tape: playtestTape,
+            });
+            if (tapeResult.status !== 'PASSED') {
+                (0, messages_1.printErrorWithHelp)((0, loadCheck_1.formatHostedLoadCheckFailure)(appName, tapeResult, 'local'), tapeResult.screenshotPath ? [`Tape screenshot: ${tapeResult.screenshotPath}`] : [], { command: 'project check' });
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`[check] Captured matched idle and tape runs for ${currentUsername}/${appName}.`);
+            console.log(`[check] Idle: ${idleResult.screenshotPath ?? idleScreenshotPath}`);
+            console.log(`[check] Tape: ${tapeResult.screenshotPath ?? tapeScreenshotPath}`);
+            console.log('[check] The tape passes only when visible evidence shows it meaningfully beats idle.');
+            for (const signal of playtestTape.successSignals) {
+                console.log(`[check] Success signal ${signal.kind}: ${signal.description}`);
+            }
+            return;
+        }
+        const result = await runCheck({ screenshotPath });
         if (result.status !== 'PASSED') {
             (0, messages_1.printErrorWithHelp)((0, loadCheck_1.formatHostedLoadCheckFailure)(appName, result, 'local'), result.screenshotPath ? [`Screenshot: ${result.screenshotPath}`] : [], { command: 'project check' });
             process.exitCode = 1;

package/dist/commands/upload.d.ts

@@ -37,6 +37,7 @@ export type WorkerAppPublishResult = {
 };
 export type WorkerPlaydropAssetRequirement = 'PACK' | 'ASSET_OR_PACK';
 export declare function resolveWorkerPlaydropAssetRequirement(value: unknown): WorkerPlaydropAssetRequirement | null;
+export declare function assertAgentNewGamePlaytestContract(task: AppTask): void;
 export declare function assertTaskPlaytestEvidenceManifest(task: AppTask, options?: {
     requireOutcomeProof?: boolean;
 }): AgentTaskPlaytestProof | null;