@playdrop/playdrop-cli 0.14.5 → 0.14.7

package/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.14.5",
+  "version": "0.14.7",
   "build": 1,
-  "runtimeSdkVersion": "0.14.5",
+  "runtimeSdkVersion": "0.14.7",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/dist/apps/staticHtml.js

@@ -223,6 +223,7 @@ function buildListing(imagePath, primarySurface) {
         screenshotLandscapePaths: [],
         videoPortraitPaths: [],
         videoLandscapePaths: [],
+        mediaMetadata: [],
     };
 }
 function buildStaticAppTask(input) {

package/dist/apps/upload.js

@@ -245,6 +245,7 @@ async function uploadAppVersion(client, task, artifacts, options) {
         usesPacks: task.uses.packs,
         tags: task.tags,
         design: task.design,
+        tweaks: task.tweaks,
         clearTags: options?.clearTags,
         surfaceTargets: task.surfaceTargets,
         primarySurface: task.primarySurface,
@@ -285,6 +286,7 @@ async function uploadAppVersion(client, task, artifacts, options) {
             status: definition.status,
         })),
         externalUrl: task.hostingMode === 'EXTERNAL' ? task.externalUrl : undefined,
+        listingMedia: listing?.mediaMetadata,
         files: preparedSessionFiles.map((file) => ({
             fileKey: file.fileKey,
             filename: file.filename,

package/dist/catalogue.d.ts

@@ -1,4 +1,4 @@
-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 AppAchievementCatalogueDefinition, type AppAuthMode, type AppControllerMode, type AppHostingMode, type AppLeaderboardCatalogueDefinition, type AppListingMediaMetadata, type AppMetadataAssetSpecSupport, type AppPlaytestTapes, type AppSurface, type AppType, type AppTweaksDeclaration, 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>>;
@@ -7,6 +7,8 @@ export type CatalogueJson = {
     assets?: Array<Record<string, unknown>>;
     assetPacks?: Array<Record<string, unknown>>;
 } & Record<string, unknown>;
+export declare const APP_DESCRIPTION_RECOMMENDED_MIN_CHARACTERS = 120;
+export declare const APP_DESCRIPTION_RECOMMENDED_MIN_WORDS = 20;
 /**
  * Listing assets configuration for an app version.
  * All paths are relative to the catalogue.json directory.
@@ -15,12 +17,20 @@ export type AppListingConfig = {
     icon?: string;
     heroPortrait?: string;
     heroLandscape?: string;
-    screenshotsPortrait?: string[];
-    screenshotsLandscape?: string[];
-    videosPortrait?: string[];
-    videosLandscape?: string[];
+    screenshotsPortrait?: AppListingMediaConfig[];
+    screenshotsLandscape?: AppListingMediaConfig[];
+    videosPortrait?: AppListingMediaConfig[];
+    videosLandscape?: AppListingMediaConfig[];
     captureReport?: string;
 };
+export type AppListingMediaConfig = string | {
+    path: string;
+    slug?: string;
+    title?: string;
+    alt?: string;
+    caption?: string;
+    description?: string;
+};
 export type ResolvedAppAchievementDefinition = Omit<AppAchievementCatalogueDefinition, 'status'> & {
     iconPath: string;
     status: PlayerMetaDefinitionStatus;
@@ -44,6 +54,7 @@ export type AppCatalogueEntry = {
     primarySurface?: string | null;
     playtestTapes?: unknown;
     design?: unknown;
+    tweaks?: unknown;
     version?: string;
     releaseNotes?: string;
     visibility?: string;
@@ -156,6 +167,7 @@ export type ResolvedListingAssets = {
     screenshotLandscapePaths: string[];
     videoPortraitPaths: string[];
     videoLandscapePaths: string[];
+    mediaMetadata: AppListingMediaMetadata[];
     captureReportPath?: string;
 };
 export type AppDependencyAssetRef = {
@@ -185,6 +197,7 @@ export type AppTask = {
     primarySurface?: AppSurface;
     playtestTapes?: AppPlaytestTapes;
     design?: AppVersionDesign;
+    tweaks?: AppTweaksDeclaration;
     missingMetadata: string[];
     version?: string;
     releaseNotes?: string;

package/dist/catalogue.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_DESCRIPTION_RECOMMENDED_MIN_WORDS = exports.APP_DESCRIPTION_RECOMMENDED_MIN_CHARACTERS = void 0;
 exports.validateAppMetadata = validateAppMetadata;
 exports.resolveCatalogueTagGroups = resolveCatalogueTagGroups;
 exports.resolveCatalogueEntries = resolveCatalogueEntries;
@@ -18,6 +19,8 @@ const LEGACY_CATALOGUE_VERSION_KEY = ['schema', 'Version'].join('');
 const ASSET_CATEGORY_SET = new Set(types_1.ASSET_CATEGORY_VALUES);
 const LISTING_IMAGE_EXTENSIONS = new Set(['.png']);
 const LISTING_VIDEO_EXTENSIONS = new Set(['.mp4']);
+exports.APP_DESCRIPTION_RECOMMENDED_MIN_CHARACTERS = 120;
+exports.APP_DESCRIPTION_RECOMMENDED_MIN_WORDS = 20;
 const BOXEL_GENERATED_FILE_ROLES = new Set(['mesh', 'preview']);
 const BOXEL_REQUIRED_FILE_ROLES = ['primary', 'mesh', 'preview'];
 const VOX_GENERATED_FILE_ROLES = new Set(['boxel', 'mesh', 'preview']);
@@ -177,6 +180,74 @@ function validateListingAssetExtension(relativePath, fieldName, kind) {
 function resolveListingAssetPath(baseDir, relativePath) {
     return (0, node_path_1.resolve)(baseDir, relativePath);
 }
+const LISTING_MEDIA_SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const LISTING_MEDIA_TEXT_LIMITS = {
+    title: 120,
+    alt: 200,
+    caption: 300,
+    description: 300,
+};
+function resolveListingMediaEntries(input) {
+    if (input.value === undefined) {
+        return { paths: [], metadata: [] };
+    }
+    if (!Array.isArray(input.value)) {
+        return { paths: [], metadata: [], error: `${input.fieldName} must be an array` };
+    }
+    const paths = [];
+    const metadata = [];
+    for (let index = 0; index < input.value.length; index += 1) {
+        const value = input.value[index];
+        const fieldName = `${input.fieldName}[${index}]`;
+        const objectValue = value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : null;
+        const relativePath = typeof value === 'string'
+            ? value.trim()
+            : typeof objectValue?.path === 'string'
+                ? objectValue.path.trim()
+                : '';
+        if (!relativePath) {
+            return { paths, metadata, error: `${fieldName} must be a path string or an object with a non-empty path` };
+        }
+        const extensionError = validateListingAssetExtension(relativePath, fieldName, input.kind);
+        if (extensionError) {
+            return { paths, metadata, error: extensionError };
+        }
+        const pathError = validateListingAssetPath(input.baseDir, relativePath, fieldName);
+        if (pathError) {
+            return { paths, metadata, error: pathError };
+        }
+        const item = {
+            fileKey: `${input.fileKeyPrefix}:${index}`,
+        };
+        if (objectValue) {
+            for (const key of ['title', 'alt', 'caption', 'description']) {
+                const raw = objectValue[key];
+                if (raw === undefined) {
+                    continue;
+                }
+                if (typeof raw !== 'string' || raw.trim().length === 0) {
+                    return { paths, metadata, error: `${fieldName}.${key} must be a non-empty string when provided` };
+                }
+                const normalized = raw.trim();
+                if (normalized.length > LISTING_MEDIA_TEXT_LIMITS[key]) {
+                    return { paths, metadata, error: `${fieldName}.${key} must be ${LISTING_MEDIA_TEXT_LIMITS[key]} characters or fewer` };
+                }
+                item[key] = normalized;
+            }
+            if (objectValue.slug !== undefined) {
+                if (typeof objectValue.slug !== 'string' || !LISTING_MEDIA_SLUG_REGEX.test(objectValue.slug.trim())) {
+                    return { paths, metadata, error: `${fieldName}.slug must use lowercase words separated by hyphens` };
+                }
+                item.slug = objectValue.slug.trim();
+            }
+        }
+        paths.push(resolveListingAssetPath(input.baseDir, relativePath));
+        metadata.push(item);
+    }
+    return { paths, metadata };
+}
 function normalizeCatalogueRemixRef(value, expectedKind, errors, context) {
     if (value === undefined || value === null) {
         return undefined;
@@ -869,6 +940,13 @@ function validateAppMetadata(entry) {
     let description;
     if (typeof entry.description === 'string') {
         description = entry.description;
+        const normalizedDescription = description.trim();
+        const wordCount = normalizedDescription ? normalizedDescription.split(/\s+/).length : 0;
+        if (normalizedDescription
+            && (normalizedDescription.length < exports.APP_DESCRIPTION_RECOMMENDED_MIN_CHARACTERS
+                || wordCount < exports.APP_DESCRIPTION_RECOMMENDED_MIN_WORDS)) {
+            warnings.push(`description is ${normalizedDescription.length} characters and ${wordCount} words. Aim for at least ${exports.APP_DESCRIPTION_RECOMMENDED_MIN_CHARACTERS} characters and ${exports.APP_DESCRIPTION_RECOMMENDED_MIN_WORDS} words describing what the player does, the objective, and the game's distinctive hook.`);
+        }
     }
     let surfaceTargetsList = [];
     let surfaceTargetsMap = { desktop: false, mobileLandscape: false, mobilePortrait: false };
@@ -1169,6 +1247,7 @@ function buildAppTasks(rootDir, catalogues, options) {
                     screenshotLandscapePaths: [],
                     videoPortraitPaths: [],
                     videoLandscapePaths: [],
+                    mediaMetadata: [],
                 };
                 // Icon
                 if (typeof rawListing.icon === 'string' && rawListing.icon.trim()) {
@@ -1236,87 +1315,28 @@ function buildAppTasks(rootDir, catalogues, options) {
                         }
                     }
                 }
-                // Screenshots
-                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsPortrait)) {
-                    for (const p of rawListing.screenshotsPortrait) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const screenshotPath = p.trim();
-                            const extensionError = validateListingAssetExtension(screenshotPath, 'listing.screenshotsPortrait item', 'image');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, screenshotPath, 'listing.screenshotsPortrait item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.screenshotPortraitPaths.push(resolveListingAssetPath(file.directory, screenshotPath));
-                        }
-                    }
-                }
-                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsLandscape)) {
-                    for (const p of rawListing.screenshotsLandscape) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const screenshotPath = p.trim();
-                            const extensionError = validateListingAssetExtension(screenshotPath, 'listing.screenshotsLandscape item', 'image');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, screenshotPath, 'listing.screenshotsLandscape item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.screenshotLandscapePaths.push(resolveListingAssetPath(file.directory, screenshotPath));
-                        }
-                    }
-                }
-                // Videos
-                if (!listingValidationFailed && Array.isArray(rawListing.videosPortrait)) {
-                    for (const p of rawListing.videosPortrait) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const videoPath = p.trim();
-                            const extensionError = validateListingAssetExtension(videoPath, 'listing.videosPortrait item', 'video');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, videoPath, 'listing.videosPortrait item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.videoPortraitPaths.push(resolveListingAssetPath(file.directory, videoPath));
-                        }
-                    }
-                }
-                if (!listingValidationFailed && Array.isArray(rawListing.videosLandscape)) {
-                    for (const p of rawListing.videosLandscape) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const videoPath = p.trim();
-                            const extensionError = validateListingAssetExtension(videoPath, 'listing.videosLandscape item', 'video');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, videoPath, 'listing.videosLandscape item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.videoLandscapePaths.push(resolveListingAssetPath(file.directory, videoPath));
-                        }
+                for (const mediaField of [
+                    { value: rawListing.screenshotsPortrait, fieldName: 'listing.screenshotsPortrait', kind: 'image', fileKeyPrefix: 'screenshotsPortrait', target: resolvedListing.screenshotPortraitPaths },
+                    { value: rawListing.screenshotsLandscape, fieldName: 'listing.screenshotsLandscape', kind: 'image', fileKeyPrefix: 'screenshotsLandscape', target: resolvedListing.screenshotLandscapePaths },
+                    { value: rawListing.videosPortrait, fieldName: 'listing.videosPortrait', kind: 'video', fileKeyPrefix: 'videosPortrait', target: resolvedListing.videoPortraitPaths },
+                    { value: rawListing.videosLandscape, fieldName: 'listing.videosLandscape', kind: 'video', fileKeyPrefix: 'videosLandscape', target: resolvedListing.videoLandscapePaths },
+                ]) {
+                    if (listingValidationFailed)
+                        break;
+                    const resolvedMedia = resolveListingMediaEntries({
+                        value: mediaField.value,
+                        baseDir: file.directory,
+                        fieldName: mediaField.fieldName,
+                        kind: mediaField.kind,
+                        fileKeyPrefix: mediaField.fileKeyPrefix,
+                    });
+                    if (resolvedMedia.error) {
+                        errors.push(`[${label}] Skipping ${rawName}: ${resolvedMedia.error}`);
+                        listingValidationFailed = true;
+                        break;
                     }
+                    mediaField.target.push(...resolvedMedia.paths);
+                    resolvedListing.mediaMetadata.push(...resolvedMedia.metadata);
                 }
                 if (!listingValidationFailed && typeof rawListing.captureReport === 'string' && rawListing.captureReport.trim()) {
                     const captureReportPath = rawListing.captureReport.trim();
@@ -1355,6 +1375,15 @@ function buildAppTasks(rootDir, catalogues, options) {
                 }
                 design = parsedDesign.value;
             }
+            let tweaks;
+            if (Object.prototype.hasOwnProperty.call(entry, 'tweaks')) {
+                const parsedTweaks = (0, types_1.normalizeAppTweaks)(entry.tweaks);
+                if (!parsedTweaks.ok) {
+                    errors.push(`[${label}] App "${rawName}" ${parsedTweaks.error}`);
+                    continue;
+                }
+                tweaks = parsedTweaks.value;
+            }
             const errorCountBeforeTagMetadata = errors.length;
             const remix = normalizeCatalogueRemixRef(entry.remix, 'app', errors, `[${label}] App "${rawName}"`);
             const tags = normalizeCatalogueTags(entry.tags, errors, `[${label}] App "${rawName}"`);
@@ -1559,6 +1588,7 @@ function buildAppTasks(rootDir, catalogues, options) {
                 primarySurface: metadata.primarySurface,
                 playtestTapes: metadata.playtestTapes,
                 design,
+                tweaks,
                 missingMetadata: metadata.missingFields,
                 // Versioning fields
                 version,
@@ -2117,6 +2147,7 @@ function buildAssetPackTasks(catalogues) {
                     screenshotLandscapePaths: [],
                     videoPortraitPaths: [],
                     videoLandscapePaths: [],
+                    mediaMetadata: [],
                 };
                 if (typeof rawListing.icon === 'string' && rawListing.icon.trim()) {
                     const iconPath = rawListing.icon.trim();
@@ -2172,85 +2203,28 @@ function buildAssetPackTasks(catalogues) {
                         }
                     }
                 }
-                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsPortrait)) {
-                    for (const p of rawListing.screenshotsPortrait) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const screenshotPath = p.trim();
-                            const extensionError = validateListingAssetExtension(screenshotPath, 'assetPacks.listing.screenshotsPortrait item', 'image');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, screenshotPath, 'assetPacks.listing.screenshotsPortrait item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.screenshotPortraitPaths.push(resolveListingAssetPath(file.directory, screenshotPath));
-                        }
-                    }
-                }
-                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsLandscape)) {
-                    for (const p of rawListing.screenshotsLandscape) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const screenshotPath = p.trim();
-                            const extensionError = validateListingAssetExtension(screenshotPath, 'assetPacks.listing.screenshotsLandscape item', 'image');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, screenshotPath, 'assetPacks.listing.screenshotsLandscape item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.screenshotLandscapePaths.push(resolveListingAssetPath(file.directory, screenshotPath));
-                        }
-                    }
-                }
-                if (!listingValidationFailed && Array.isArray(rawListing.videosPortrait)) {
-                    for (const p of rawListing.videosPortrait) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const videoPath = p.trim();
-                            const extensionError = validateListingAssetExtension(videoPath, 'assetPacks.listing.videosPortrait item', 'video');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, videoPath, 'assetPacks.listing.videosPortrait item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.videoPortraitPaths.push(resolveListingAssetPath(file.directory, videoPath));
-                        }
-                    }
-                }
-                if (!listingValidationFailed && Array.isArray(rawListing.videosLandscape)) {
-                    for (const p of rawListing.videosLandscape) {
-                        if (typeof p === 'string' && p.trim()) {
-                            const videoPath = p.trim();
-                            const extensionError = validateListingAssetExtension(videoPath, 'assetPacks.listing.videosLandscape item', 'video');
-                            if (extensionError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${extensionError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            const validationError = validateListingAssetPath(file.directory, videoPath, 'assetPacks.listing.videosLandscape item');
-                            if (validationError) {
-                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
-                                listingValidationFailed = true;
-                                break;
-                            }
-                            resolvedListing.videoLandscapePaths.push(resolveListingAssetPath(file.directory, videoPath));
-                        }
+                for (const mediaField of [
+                    { value: rawListing.screenshotsPortrait, fieldName: 'assetPacks.listing.screenshotsPortrait', kind: 'image', fileKeyPrefix: 'screenshotsPortrait', target: resolvedListing.screenshotPortraitPaths },
+                    { value: rawListing.screenshotsLandscape, fieldName: 'assetPacks.listing.screenshotsLandscape', kind: 'image', fileKeyPrefix: 'screenshotsLandscape', target: resolvedListing.screenshotLandscapePaths },
+                    { value: rawListing.videosPortrait, fieldName: 'assetPacks.listing.videosPortrait', kind: 'video', fileKeyPrefix: 'videosPortrait', target: resolvedListing.videoPortraitPaths },
+                    { value: rawListing.videosLandscape, fieldName: 'assetPacks.listing.videosLandscape', kind: 'video', fileKeyPrefix: 'videosLandscape', target: resolvedListing.videoLandscapePaths },
+                ]) {
+                    if (listingValidationFailed)
+                        break;
+                    const resolvedMedia = resolveListingMediaEntries({
+                        value: mediaField.value,
+                        baseDir: file.directory,
+                        fieldName: mediaField.fieldName,
+                        kind: mediaField.kind,
+                        fileKeyPrefix: mediaField.fileKeyPrefix,
+                    });
+                    if (resolvedMedia.error) {
+                        errors.push(`[${label}] Skipping asset pack "${name}": ${resolvedMedia.error}`);
+                        listingValidationFailed = true;
+                        break;
                     }
+                    mediaField.target.push(...resolvedMedia.paths);
+                    resolvedListing.mediaMetadata.push(...resolvedMedia.metadata);
                 }
                 if (listingValidationFailed) {
                     continue;

package/dist/commands/dev.js

@@ -16,6 +16,7 @@ const http_1 = require("../http");
 const messages_1 = require("../messages");
 const devRuntimeAssets_1 = require("./devRuntimeAssets");
 const devServer_1 = require("./devServer");
+const tweakStaleness_1 = require("../tweakStaleness");
 const devShared_1 = require("./devShared");
 function formatDevRuntimeAssetManifestFailure(error) {
     const rawMessage = error instanceof Error ? error.message : String(error ?? 'unknown_error');
@@ -301,6 +302,14 @@ async function dev(targetArg, appOption, devOptions = {}) {
         });
         let runtimeAssetManifest = (0, devRuntimeAssets_1.createEmptyDevRuntimeAssetManifest)();
         if (taskLookup.task) {
+            try {
+                await (0, tweakStaleness_1.fetchAndAssertTweakState)(client, currentUsername, taskLookup.task);
+            }
+            catch (error) {
+                (0, messages_1.printErrorWithHelp)(error instanceof Error ? error.message : 'Could not verify the current tweak state.', [], { command: 'project dev' });
+                process.exitCode = 1;
+                return;
+            }
             try {
                 runtimeAssetManifest = await (0, devRuntimeAssets_1.buildDevRuntimeAssetManifest)({
                     client,

package/dist/commands/devRuntimeAssets.d.ts

@@ -1,5 +1,5 @@
 import type { ApiClient } from '@playdrop/api-client';
-import { type AppAuthMode, type AppControllerMode, type AppMetadataAssetSpecSupport, type AppRuntimeAssetsResponse, type AppSurface, type AppType } from '@playdrop/types';
+import { type AppAuthMode, type AppControllerMode, type AppMetadataAssetSpecSupport, type AppRuntimeAssetsResponse, type AppSurface, type AppType, type TweakValues } from '@playdrop/types';
 import type { AppTask } from '../catalogue';
 export type LocalOwnedRuntimeAssetFileRecord = {
     absolutePath: string;
@@ -14,6 +14,7 @@ export type LocalDevAppMetadata = {
     previewable: boolean;
     assetSpecSupport: AppMetadataAssetSpecSupport[];
     version: string | null;
+    tweakValues?: TweakValues;
 };
 export type DevRuntimeAssetsResponse = AppRuntimeAssetsResponse & {
     localAppMetadata: LocalDevAppMetadata;

package/dist/commands/devRuntimeAssets.js

@@ -124,6 +124,9 @@ function buildLocalAppMetadata(task) {
             capabilities: Array.from(entry.capabilities),
         })),
         version: typeof task.version === 'string' && task.version.trim().length > 0 ? task.version.trim() : null,
+        ...(task.tweaks && task.tweaks.removed !== true
+            ? { tweakValues: { ...task.tweaks.defaults } }
+            : {}),
     };
 }
 function assertCustomAssetVersionSupported(task, assetRef, version) {

package/dist/commands/notes.d.ts

@@ -0,0 +1,7 @@
+export declare function browseNotes(rawRef: string | undefined, options?: {
+    json?: boolean;
+    output?: string;
+}): Promise<void>;
+export declare function clearNotes(rawRef: string | undefined, rawIds: string[], options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/notes.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browseNotes = browseNotes;
+exports.clearNotes = clearNotes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const types_1 = require("@playdrop/types");
+const commandContext_1 = require("../commandContext");
+const errors_1 = require("../errors");
+const messages_1 = require("../messages");
+const output_1 = require("../output");
+function notesApiMessage(error) {
+    if (error.code === 'playtest_notes_changed') {
+        const missingIds = Array.isArray(error.details?.['missingIds']) ? error.details['missingIds'] : [];
+        return {
+            problem: `The note inbox changed before it could be cleared${missingIds.length > 0 ? `: ${missingIds.join(', ')}` : '.'}`,
+            suggestions: ['Run notes browse again, then clear the current IDs.'],
+        };
+    }
+    return { problem: `PlayDrop rejected the notes request: ${error.code ?? error.message} (HTTP ${error.status}).` };
+}
+function parseAppVersionRef(raw, command) {
+    const ref = (0, types_1.parseContentVersionRef)(raw ?? '');
+    if (!ref || ref.kind !== 'app') {
+        (0, messages_1.printErrorWithHelp)('An exact canonical app-version ref is required.', ['Use app:creator/name@x.y.z.', `Example: playdrop ${command} app:olivier/platformer@1.4.0`], { command });
+        process.exitCode = 1;
+        return null;
+    }
+    return ref;
+}
+async function browseNotes(rawRef, options = {}) {
+    const ref = parseAppVersionRef(rawRef, 'notes browse');
+    if (!ref)
+        return;
+    await (0, commandContext_1.withEnvironment)('notes browse', 'Reading playtest notes', async ({ client }) => {
+        try {
+            const response = await client.listPlaytestNotes(ref.creatorUsername, ref.name, ref.version);
+            let output = response;
+            if (options.output) {
+                const outputDirectory = (0, node_path_1.resolve)(options.output);
+                (0, node_fs_1.mkdirSync)(outputDirectory, { recursive: true });
+                const notes = [];
+                for (const note of response.notes) {
+                    if (!note.attachment) {
+                        notes.push(note);
+                        continue;
+                    }
+                    const localPath = (0, node_path_1.resolve)(outputDirectory, `${note.id}-${note.attachment.fileName}`);
+                    const blob = await client.downloadPlaytestNoteAttachment(ref.creatorUsername, ref.name, ref.version, note.id);
+                    (0, node_fs_1.writeFileSync)(localPath, Buffer.from(await blob.arrayBuffer()));
+                    notes.push({ ...note, localPath });
+                }
+                output = { notes };
+                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(outputDirectory, 'notes.json'), `${JSON.stringify(output, null, 2)}\n`, 'utf8');
+            }
+            if (options.json) {
+                (0, output_1.printJson)(output);
+                return;
+            }
+            if (options.output) {
+                (0, output_1.printSuccess)(`Materialized ${output.notes.length} playtest notes in ${(0, node_path_1.resolve)(options.output)}.`);
+                return;
+            }
+            if (output.notes.length === 0) {
+                console.log('No pending playtest notes.');
+                return;
+            }
+            for (const note of output.notes) {
+                const summary = note.kind === 'TEXT'
+                    ? note.text
+                    : note.kind === 'ASSET'
+                        ? `${note.assetRef}: ${note.comment}`
+                        : note.attachment?.fileName;
+                console.log(`${note.id}\t${note.kind}\tv${note.authoredVersion}\t${summary ?? ''}`);
+            }
+        }
+        catch (error) {
+            if (!(0, errors_1.handleCommandFailure)(error, 'notes browse', 'Read playtest notes', { apiMessage: notesApiMessage }))
+                throw error;
+        }
+    });
+}
+async function clearNotes(rawRef, rawIds, options = {}) {
+    const ref = parseAppVersionRef(rawRef, 'notes clear');
+    if (!ref)
+        return;
+    const ids = rawIds.map(Number);
+    if (ids.length === 0 || ids.some((id) => !Number.isInteger(id) || id <= 0) || new Set(ids).size !== ids.length) {
+        (0, messages_1.printErrorWithHelp)('One or more explicit note IDs are required.', ['Example: playdrop notes clear app:olivier/platformer@1.4.0 42 43'], { command: 'notes clear' });
+        process.exitCode = 1;
+        return;
+    }
+    await (0, commandContext_1.withEnvironment)('notes clear', 'Clearing playtest notes', async ({ client }) => {
+        try {
+            const result = await client.clearPlaytestNotes(ref.creatorUsername, ref.name, ref.version, ids);
+            if (options.json) {
+                (0, output_1.printJson)(result);
+                return;
+            }
+            (0, output_1.printSuccess)(`Cleared ${result.cleared.length} playtest notes. ${result.count} pending.`);
+        }
+        catch (error) {
+            if (!(0, errors_1.handleCommandFailure)(error, 'notes clear', 'Clear playtest notes', { apiMessage: notesApiMessage }))
+                throw error;
+        }
+    });
+}

package/dist/commands/tweaks.d.ts

@@ -0,0 +1,6 @@
+type TweaksOptions = {
+    json?: boolean;
+};
+export declare function getTweaks(rawRef: string | undefined, options?: TweaksOptions): Promise<void>;
+export declare function replaceTweaks(rawRef: string | undefined, file: string | undefined, options?: TweaksOptions): Promise<void>;
+export {};