@playdrop/playdrop-cli 0.5.2 → 0.5.4

package/dist/commands/browse.js

@@ -14,7 +14,7 @@ function parseBrowseKind(raw) {
         return 'all';
     }
     const normalized = raw.trim().toLowerCase();
-    if (normalized === 'app' || normalized === 'asset' || normalized === 'asset-pack' || normalized === 'all') {
+    if (normalized === 'app' || normalized === 'asset' || normalized === 'asset-pack' || normalized === 'asset-spec' || normalized === 'all') {
         return normalized;
     }
     return null;
@@ -66,6 +66,19 @@ function parseAssetSubcategory(raw) {
     const normalized = (0, types_1.normalizeAssetSubcategory)(raw);
     return normalized || null;
 }
+function parseBrowseSort(raw) {
+    if (!raw || raw.trim().length === 0) {
+        return undefined;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (types_1.ASSET_LIST_SORT_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    if (types_1.ASSET_SPEC_LIST_SORT_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    return null;
+}
 function buildItemRef(kind, creator, name) {
     return `${creator}/${kind}/${name}`;
 }
@@ -84,6 +97,9 @@ function itemSummary(item) {
         const subcategory = item.item.currentVersion?.subcategory;
         return subcategory ? `${item.item.category.toLowerCase()}/${subcategory}` : item.item.category.toLowerCase();
     }
+    if (item.kind === 'asset-spec') {
+        return item.item.currentVersionRef ? `current ${item.item.currentVersionRef.split('@')[1] ?? 'none'}` : 'no current version';
+    }
     return 'asset-pack';
 }
 function formatCountValue(value) {
@@ -97,15 +113,28 @@ function buildCountsSuffix(item) {
         }
         parts.push(`launch ${formatCountValue(item.item.playCount)}`);
     }
-    if (item.kind === 'asset' && typeof item.item.playCount === 'number') {
+    if (item.kind === 'asset') {
         if (typeof item.item.viewCount === 'number') {
             parts.push(`view ${formatCountValue(item.item.viewCount)}`);
         }
-        parts.push(`play ${formatCountValue(item.item.playCount)}`);
+        if (typeof item.item.downloadCount === 'number') {
+            parts.push(`download ${formatCountValue(item.item.downloadCount)}`);
+        }
+        if (typeof item.item.playCount === 'number') {
+            parts.push(`play ${formatCountValue(item.item.playCount)}`);
+        }
     }
     if (item.kind === 'asset-pack' && typeof item.item.downloadCount === 'number') {
         parts.push(`download ${formatCountValue(item.item.downloadCount)}`);
     }
+    if (item.kind === 'asset-spec') {
+        parts.push(`assets ${formatCountValue(item.item.publicAssetCount)}`);
+        parts.push(`apps ${formatCountValue(item.item.supportingAppCount)}`);
+        if (item.item.documentationAvailable) {
+            parts.push('docs yes');
+        }
+        return ` | ${parts.join(' | ')}`;
+    }
     if (typeof item.item.likeCount === 'number') {
         parts.push(`like ${formatCountValue(item.item.likeCount)}`);
     }
@@ -175,50 +204,342 @@ async function resolveCreatorUsername(creator, command, resolveMe) {
     }
     return creator;
 }
-async function browse(options = {}) {
-    const kind = parseBrowseKind(options.kind);
-    if (!kind) {
-        (0, messages_1.printErrorWithHelp)(`Kind "${options.kind ?? ''}" is not supported.`, ['Use one of: app, asset, asset-pack, all.'], { command: 'browse' });
+function normalizeOptionalOption(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeTagFilters(rawTags) {
+    if (!Array.isArray(rawTags) || rawTags.length === 0) {
+        return [];
+    }
+    const normalizedRefs = [];
+    const seenRefs = new Set();
+    for (const rawTag of rawTags) {
+        if (typeof rawTag !== 'string' || rawTag.trim().length === 0) {
+            return null;
+        }
+        let normalizedRef = '';
+        try {
+            normalizedRef = (0, types_1.normalizeTagRef)(rawTag);
+        }
+        catch {
+            return null;
+        }
+        if (seenRefs.has(normalizedRef)) {
+            return null;
+        }
+        seenRefs.add(normalizedRef);
+        normalizedRefs.push(normalizedRef);
+    }
+    if (normalizedRefs.length > 5) {
+        return null;
+    }
+    return normalizedRefs;
+}
+function buildTagSuffix(tags) {
+    const normalizedTags = Array.isArray(tags) ? tags : [];
+    if (normalizedTags.length === 0) {
+        return '';
+    }
+    return ` | tags ${normalizedTags.slice(0, 3).map((tag) => tag.ref).join(', ')}`;
+}
+function parseBrowseSortOption(rawSort, kind) {
+    const sort = parseBrowseSort(rawSort);
+    if (sort === null) {
+        (0, messages_1.printErrorWithHelp)(`Sort "${rawSort ?? ''}" is not supported.`, ['Use one of: recent, likes, downloads, remixes, comments, assets, apps, alpha.'], { command: 'browse' });
         process.exitCode = 1;
-        return;
+        return null;
     }
-    const creator = parseBrowseCreator(options.creator);
-    if (!creator) {
-        (0, messages_1.printErrorWithHelp)('The --creator value is invalid.', ['Use all, me, or a creator slug without path separators.'], { command: 'browse' });
+    if (sort && kind === 'all') {
+        (0, messages_1.printErrorWithHelp)('The --sort option is not supported with --kind all.', ['Choose --kind asset or --kind asset-spec when sorting browse results.'], { command: 'browse' });
         process.exitCode = 1;
-        return;
+        return null;
     }
-    const parsedAppType = options.appType ? (0, types_1.parseAppType)(options.appType.trim().toUpperCase()) : undefined;
-    if (options.appType !== undefined && !parsedAppType) {
-        (0, messages_1.printErrorWithHelp)(`App type "${options.appType}" is not supported.`, ['Use one of: game, demo, tool, template.'], { command: 'browse' });
+    if (sort && kind === 'asset-spec' && !types_1.ASSET_SPEC_LIST_SORT_VALUES.includes(sort)) {
+        (0, messages_1.printErrorWithHelp)(`Sort "${sort}" is not supported for asset specs.`, ['Use one of: recent, assets, apps, alpha.'], { command: 'browse' });
         process.exitCode = 1;
-        return;
+        return null;
     }
-    const appType = parsedAppType ?? undefined;
+    if (sort && kind === 'asset' && !types_1.ASSET_LIST_SORT_VALUES.includes(sort)) {
+        (0, messages_1.printErrorWithHelp)(`Sort "${sort}" is not supported for assets.`, ['Use one of: recent, likes, downloads, remixes, comments.'], { command: 'browse' });
+        process.exitCode = 1;
+        return null;
+    }
+    return sort ?? undefined;
+}
+function parseBrowseLimitsAndFilters(options) {
     const assetCategory = parseAssetCategory(options.assetCategory);
     if (assetCategory === null) {
         (0, messages_1.printErrorWithHelp)(`Asset category "${options.assetCategory}" is not supported.`, ['Use a canonical asset category like IMAGE, VIDEO, AUDIO, SPRITESHEET, or MODEL_3D.'], { command: 'browse' });
         process.exitCode = 1;
-        return;
+        return null;
     }
     const assetSubcategory = parseAssetSubcategory(options.assetSubcategory);
     if (assetSubcategory === null) {
         (0, messages_1.printErrorWithHelp)(`Asset subcategory "${options.assetSubcategory}" is invalid.`, ['Use lowercase slug values like generic, avatar, music, or sfx.'], { command: 'browse' });
         process.exitCode = 1;
-        return;
+        return null;
     }
     const limit = parsePositiveInteger(options.limit, 'limit', 10);
     if (limit === null) {
         (0, messages_1.printErrorWithHelp)('The --limit value must be a positive integer.', ['Example: --limit 10'], { command: 'browse' });
         process.exitCode = 1;
-        return;
+        return null;
     }
     const offset = parsePositiveInteger(options.offset, 'offset', 0);
     if (offset === null) {
         (0, messages_1.printErrorWithHelp)('The --offset value must be zero or a positive integer.', ['Example: --offset 20'], { command: 'browse' });
         process.exitCode = 1;
+        return null;
+    }
+    return {
+        assetCategory: assetCategory ?? undefined,
+        assetSubcategory: assetSubcategory ?? undefined,
+        limit,
+        offset,
+    };
+}
+function parseBrowseCommandOptions(options) {
+    const kind = parseBrowseKind(options.kind);
+    if (!kind) {
+        (0, messages_1.printErrorWithHelp)(`Kind "${options.kind ?? ''}" is not supported.`, ['Use one of: app, asset, asset-pack, asset-spec, all.'], { command: 'browse' });
+        process.exitCode = 1;
+        return { ok: false };
+    }
+    const creator = parseBrowseCreator(options.creator);
+    if (!creator) {
+        (0, messages_1.printErrorWithHelp)('The --creator value is invalid.', ['Use all, me, or a creator slug without path separators.'], { command: 'browse' });
+        process.exitCode = 1;
+        return { ok: false };
+    }
+    const appType = options.appType ? (0, types_1.parseAppType)(options.appType.trim().toUpperCase()) : undefined;
+    if (options.appType !== undefined && !appType) {
+        (0, messages_1.printErrorWithHelp)(`App type "${options.appType}" is not supported.`, ['Use one of: game, demo, tool, template.'], { command: 'browse' });
+        process.exitCode = 1;
+        return { ok: false };
+    }
+    const browseFilters = parseBrowseLimitsAndFilters(options);
+    if (!browseFilters) {
+        return { ok: false };
+    }
+    const sort = parseBrowseSortOption(options.sort, kind);
+    if (sort === null) {
+        return { ok: false };
+    }
+    const tags = normalizeTagFilters(options.tag);
+    if (tags === null) {
+        (0, messages_1.printErrorWithHelp)('The --tag value is invalid.', ['Use canonical refs like theme/pirate or visual-style/pixel-art.', 'Pass at most 5 unique tag refs.'], { command: 'browse' });
+        process.exitCode = 1;
+        return { ok: false };
+    }
+    return {
+        ok: true,
+        input: {
+            kind,
+            creator,
+            appType: appType ?? undefined,
+            ...browseFilters,
+            assetSpec: normalizeOptionalOption(options.assetSpec),
+            assetSpecOwner: normalizeOptionalOption(options.assetSpecOwner),
+            assetSpecName: normalizeOptionalOption(options.assetSpecName),
+            sort,
+            tags,
+        },
+    };
+}
+async function loadMergedBrowseResults(input) {
+    const { client, creator, creatorUsername, appType, assetCategory, assetSubcategory, assetSpec, assetSpecOwner, assetSpecName, limit, offset, tags, } = input;
+    const appResultsPromise = creatorUsername
+        ? collectPaginatedItems((pageLimit, pageOffset) => client.fetchAppsByCreator(creatorUsername, { limit: pageLimit, offset: pageOffset, type: appType, ...(tags.length > 0 ? { tags } : {}) })
+            .then((response) => ({
+            items: response.apps ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_creator_apps'),
+        })))
+        : (appType
+            ? collectPaginatedItems((pageLimit, pageOffset) => client.fetchAppsByType(appType, { limit: pageLimit, offset: pageOffset, ...(tags.length > 0 ? { tags } : {}) }).then((response) => ({
+                items: response.apps ?? [],
+                pagination: requirePagination(response.pagination, 'browse_all_type_apps'),
+            })))
+            : collectPaginatedItems((pageLimit, pageOffset) => client.fetchApps({ limit: pageLimit, offset: pageOffset, ...(tags.length > 0 ? { tags } : {}) }).then((response) => ({
+                items: response.apps ?? [],
+                pagination: requirePagination(response.pagination, 'browse_all_apps'),
+            }))));
+    const assetResultsPromise = creatorUsername
+        ? collectPaginatedItems((pageLimit, pageOffset) => client.listAssetsForCreator(creatorUsername, {
+            limit: pageLimit,
+            offset: pageOffset,
+            category: assetCategory,
+            subcategory: assetSubcategory,
+            assetSpec,
+            assetSpecOwner,
+            assetSpecName,
+            ...(tags.length > 0 ? { tags } : {}),
+        }).then((response) => ({
+            items: response.assets ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_creator_assets'),
+        })))
+        : collectPaginatedItems((pageLimit, pageOffset) => client.listAssets({
+            limit: pageLimit,
+            offset: pageOffset,
+            category: assetCategory,
+            subcategory: assetSubcategory,
+            assetSpec,
+            assetSpecOwner,
+            assetSpecName,
+            ...(tags.length > 0 ? { tags } : {}),
+        }).then((response) => ({
+            items: response.assets ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_assets'),
+        })));
+    const specResultsPromise = creatorUsername
+        ? collectPaginatedItems((pageLimit, pageOffset) => client.listAssetSpecsForCreator(creatorUsername, { limit: pageLimit, offset: pageOffset }).then((response) => ({
+            items: response.assetSpecs ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_creator_specs'),
+        })))
+        : collectPaginatedItems((pageLimit, pageOffset) => client.listAssetSpecs({ limit: pageLimit, offset: pageOffset }).then((response) => ({
+            items: response.assetSpecs ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_specs'),
+        })));
+    const packResultsPromise = creatorUsername
+        ? collectPaginatedItems((pageLimit, pageOffset) => client.listAssetPacksForCreator(creatorUsername, {
+            limit: pageLimit,
+            offset: pageOffset,
+            containsCategory: assetCategory,
+            containsSubcategory: assetSubcategory,
+            ...(tags.length > 0 ? { tags } : {}),
+        }).then((response) => ({
+            items: response.packs ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_creator_packs'),
+        })))
+        : collectPaginatedItems((pageLimit, pageOffset) => client.listAssetPacks({
+            limit: pageLimit,
+            offset: pageOffset,
+            containsCategory: assetCategory,
+            containsSubcategory: assetSubcategory,
+            ...(tags.length > 0 ? { tags } : {}),
+        }).then((response) => ({
+            items: response.packs ?? [],
+            pagination: requirePagination(response.pagination, 'browse_all_packs'),
+        })));
+    const [apps, assets, specs, packs] = await Promise.all([
+        appResultsPromise,
+        assetResultsPromise,
+        specResultsPromise,
+        packResultsPromise,
+    ]);
+    const combined = [
+        ...apps.items.map((item) => toBrowseItem('app', item)),
+        ...assets.items.map((item) => toBrowseItem('asset', item)),
+        ...specs.items.map((item) => toBrowseItem('asset-spec', item)),
+        ...packs.items.map((item) => toBrowseItem('asset-pack', item)),
+    ];
+    return sliceMergedItems(combined, limit, offset);
+}
+async function runAssetBrowseCommand(input) {
+    const { client, creatorUsername, assetCategory, assetSubcategory, assetSpec, assetSpecOwner, assetSpecName, sort, limit, offset, tags } = input;
+    const response = creatorUsername
+        ? await client.listAssetsForCreator(creatorUsername, {
+            limit,
+            offset,
+            category: assetCategory,
+            subcategory: assetSubcategory,
+            assetSpec,
+            assetSpecOwner,
+            assetSpecName,
+            ...(tags.length > 0 ? { tags } : {}),
+            ...(sort ? { sort: sort } : {}),
+        })
+        : await client.listAssets({
+            limit,
+            offset,
+            category: assetCategory,
+            subcategory: assetSubcategory,
+            assetSpec,
+            assetSpecOwner,
+            assetSpecName,
+            ...(tags.length > 0 ? { tags } : {}),
+            ...(sort ? { sort: sort } : {}),
+        });
+    return {
+        items: (response.assets ?? []).map((item) => toBrowseItem('asset', item)),
+        pagination: requirePagination(response.pagination, 'browse_assets'),
+    };
+}
+async function runAssetSpecBrowseCommand(input) {
+    const { client, creatorUsername, sort, limit, offset } = input;
+    const response = creatorUsername
+        ? await client.listAssetSpecsForCreator(creatorUsername, { limit, offset, ...(sort ? { sort: sort } : {}) })
+        : await client.listAssetSpecs({ limit, offset, ...(sort ? { sort: sort } : {}) });
+    return {
+        items: (response.assetSpecs ?? []).map((item) => toBrowseItem('asset-spec', item)),
+        pagination: requirePagination(response.pagination, 'browse_asset_specs'),
+    };
+}
+async function runAssetPackBrowseCommand(input) {
+    const { client, creatorUsername, assetCategory, assetSubcategory, limit, offset, tags } = input;
+    const response = creatorUsername
+        ? await client.listAssetPacksForCreator(creatorUsername, {
+            limit,
+            offset,
+            containsCategory: assetCategory,
+            containsSubcategory: assetSubcategory,
+            ...(tags.length > 0 ? { tags } : {}),
+        })
+        : await client.listAssetPacks({
+            limit,
+            offset,
+            containsCategory: assetCategory,
+            containsSubcategory: assetSubcategory,
+            ...(tags.length > 0 ? { tags } : {}),
+        });
+    return {
+        items: (response.packs ?? []).map((item) => toBrowseItem('asset-pack', item)),
+        pagination: requirePagination(response.pagination, 'browse_asset_packs'),
+    };
+}
+async function runBrowseCommand(input) {
+    const { client, kind, creator, creatorUsername, appType, limit, offset, tags, } = input;
+    if (kind === 'app') {
+        if (creatorUsername) {
+            const response = await client.fetchAppsByCreator(creatorUsername, { limit, offset, type: appType, ...(tags.length > 0 ? { tags } : {}) });
+            return {
+                items: (response.apps ?? []).map((item) => toBrowseItem('app', item)),
+                pagination: requirePagination(response.pagination, 'browse_app_creator'),
+            };
+        }
+        if (appType) {
+            const response = await client.fetchAppsByType(appType, { limit, offset, ...(tags.length > 0 ? { tags } : {}) });
+            return {
+                items: (response.apps ?? []).map((item) => toBrowseItem('app', item)),
+                pagination: requirePagination(response.pagination, 'browse_app_type'),
+            };
+        }
+        const response = await client.fetchApps({ limit, offset, ...(tags.length > 0 ? { tags } : {}) });
+        return {
+            items: (response.apps ?? []).map((item) => toBrowseItem('app', item)),
+            pagination: requirePagination(response.pagination, 'browse_app_all'),
+        };
+    }
+    if (kind === 'asset') {
+        return await runAssetBrowseCommand(input);
+    }
+    if (kind === 'asset-spec') {
+        return await runAssetSpecBrowseCommand(input);
+    }
+    if (kind === 'asset-pack') {
+        return await runAssetPackBrowseCommand(input);
+    }
+    return await loadMergedBrowseResults(input);
+}
+async function browse(options = {}) {
+    const parsed = parseBrowseCommandOptions(options);
+    if (!parsed.ok) {
         return;
     }
+    const { kind, creator, appType, assetCategory, assetSubcategory, assetSpec, assetSpecOwner, assetSpecName, sort, limit, offset, tags } = parsed.input;
     await (0, commandContext_1.withPublicEnvironment)('browse', async ({ client }) => {
         try {
             const creatorUsername = await resolveCreatorUsername(creator, 'browse', async () => {
@@ -232,108 +553,22 @@ async function browse(options = {}) {
             if (process.exitCode) {
                 return;
             }
-            const items = [];
-            let pagination;
-            if (kind === 'app') {
-                if (creatorUsername) {
-                    const response = creator === 'me'
-                        ? await client.fetchMyApps({ limit, offset, type: appType })
-                        : await client.fetchAppsByCreator(creatorUsername, { limit, offset, type: appType });
-                    items.push(...(response.apps ?? []).map((item) => toBrowseItem('app', item)));
-                    pagination = requirePagination(response.pagination, 'browse_app_creator');
-                }
-                else if (appType) {
-                    const response = await client.fetchAppsByType(appType, { limit, offset });
-                    items.push(...(response.apps ?? []).map((item) => toBrowseItem('app', item)));
-                    pagination = requirePagination(response.pagination, 'browse_app_type');
-                }
-                else {
-                    const response = await client.fetchApps({ limit, offset });
-                    items.push(...(response.apps ?? []).map((item) => toBrowseItem('app', item)));
-                    pagination = requirePagination(response.pagination, 'browse_app_all');
-                }
-            }
-            else if (kind === 'asset') {
-                const response = creatorUsername
-                    ? await client.listAssetsForCreator(creatorUsername, { limit, offset, category: assetCategory, subcategory: assetSubcategory })
-                    : await client.listAssets({ limit, offset, category: assetCategory, subcategory: assetSubcategory });
-                items.push(...(response.assets ?? []).map((item) => toBrowseItem('asset', item)));
-                pagination = response.pagination;
-            }
-            else if (kind === 'asset-pack') {
-                const response = creatorUsername
-                    ? await client.listAssetPacksForCreator(creatorUsername, { limit, offset, containsCategory: assetCategory, containsSubcategory: assetSubcategory })
-                    : await client.listAssetPacks({ limit, offset, containsCategory: assetCategory, containsSubcategory: assetSubcategory });
-                items.push(...(response.packs ?? []).map((item) => toBrowseItem('asset-pack', item)));
-                pagination = response.pagination;
-            }
-            else {
-                const [apps, assets, packs] = await Promise.all([
-                    creatorUsername
-                        ? collectPaginatedItems((pageLimit, pageOffset) => (creator === 'me'
-                            ? client.fetchMyApps({ limit: pageLimit, offset: pageOffset, type: appType })
-                            : client.fetchAppsByCreator(creatorUsername, { limit: pageLimit, offset: pageOffset, type: appType }))
-                            .then((response) => ({
-                            items: response.apps ?? [],
-                            pagination: requirePagination(response.pagination, 'browse_all_creator_apps'),
-                        })))
-                        : (appType
-                            ? collectPaginatedItems((pageLimit, pageOffset) => client.fetchAppsByType(appType, { limit: pageLimit, offset: pageOffset }).then((response) => ({
-                                items: response.apps ?? [],
-                                pagination: requirePagination(response.pagination, 'browse_all_type_apps'),
-                            })))
-                            : collectPaginatedItems((pageLimit, pageOffset) => client.fetchApps({ limit: pageLimit, offset: pageOffset }).then((response) => ({
-                                items: response.apps ?? [],
-                                pagination: requirePagination(response.pagination, 'browse_all_apps'),
-                            })))),
-                    creatorUsername
-                        ? collectPaginatedItems((pageLimit, pageOffset) => client.listAssetsForCreator(creatorUsername, {
-                            limit: pageLimit,
-                            offset: pageOffset,
-                            category: assetCategory,
-                            subcategory: assetSubcategory,
-                        }).then((response) => ({
-                            items: response.assets ?? [],
-                            pagination: response.pagination,
-                        })))
-                        : collectPaginatedItems((pageLimit, pageOffset) => client.listAssets({
-                            limit: pageLimit,
-                            offset: pageOffset,
-                            category: assetCategory,
-                            subcategory: assetSubcategory,
-                        }).then((response) => ({
-                            items: response.assets ?? [],
-                            pagination: response.pagination,
-                        }))),
-                    creatorUsername
-                        ? collectPaginatedItems((pageLimit, pageOffset) => client.listAssetPacksForCreator(creatorUsername, {
-                            limit: pageLimit,
-                            offset: pageOffset,
-                            containsCategory: assetCategory,
-                            containsSubcategory: assetSubcategory,
-                        }).then((response) => ({
-                            items: response.packs ?? [],
-                            pagination: response.pagination,
-                        })))
-                        : collectPaginatedItems((pageLimit, pageOffset) => client.listAssetPacks({
-                            limit: pageLimit,
-                            offset: pageOffset,
-                            containsCategory: assetCategory,
-                            containsSubcategory: assetSubcategory,
-                        }).then((response) => ({
-                            items: response.packs ?? [],
-                            pagination: response.pagination,
-                        }))),
-                ]);
-                const combined = [
-                    ...apps.items.map((item) => toBrowseItem('app', item)),
-                    ...assets.items.map((item) => toBrowseItem('asset', item)),
-                    ...packs.items.map((item) => toBrowseItem('asset-pack', item)),
-                ];
-                const sliced = sliceMergedItems(combined, limit, offset);
-                items.push(...sliced.items);
-                pagination = sliced.pagination;
-            }
+            const { items, pagination } = await runBrowseCommand({
+                client,
+                kind,
+                creator,
+                creatorUsername,
+                appType,
+                assetCategory,
+                assetSubcategory,
+                assetSpec,
+                assetSpecOwner,
+                assetSpecName,
+                sort,
+                limit,
+                offset,
+                tags,
+            });
             if (options.json) {
                 (0, output_1.printJson)({
                     items,
@@ -348,20 +583,26 @@ async function browse(options = {}) {
                 return;
             }
             if (kind === 'all') {
-                console.log('Browsing content (apps, then assets, then asset packs):\n');
+                console.log('Browsing content (apps, assets, asset specs, then asset packs):\n');
             }
             else {
                 console.log(`Browsing ${(0, refs_1.contentKindPluralLabel)(kind)}:\n`);
             }
             for (const [index, item] of items.entries()) {
                 const displayName = item.item.displayName || item.item.name;
-                console.log(`${index + 1}. [${item.kind}] ${item.ref} | ${displayName} | @${item.item.creatorUsername} | ${itemSummary(item)}${buildCountsSuffix(item)}`);
+                console.log(`${index + 1}. [${item.kind}] ${item.ref} | ${displayName} | @${item.item.creatorUsername} | ${itemSummary(item)}${buildCountsSuffix(item)}${buildTagSuffix(item.item.tags)}`);
             }
             console.log('\nNext: run "playdrop detail <creator>/<kind>/<name>" to inspect one item.');
         }
         catch (error) {
             const handled = (0, errors_1.handleCommandFailure)(error, 'browse', 'Browse', {
                 apiMessage: (apiError) => {
+                    if (apiError.code === 'invalid_tag_ref' || apiError.code === 'duplicate_tag_ref' || apiError.code === 'tag_filter_limit_exceeded') {
+                        return {
+                            problem: 'One or more tag filters are invalid.',
+                            suggestions: ['Use canonical refs like theme/pirate.', 'Pass at most 5 unique --tag values.'],
+                        };
+                    }
                     if (apiError.status === 401 || apiError.status === 403) {
                         return {
                             problem: 'Browsing this content requires you to be logged in.',

package/dist/commands/capture.js

@@ -117,7 +117,6 @@ async function capture(targetArg, options = {}) {
         return;
     }
     const screenshotPath = options.screenshotPath ? (0, node_path_1.resolve)(process.cwd(), options.screenshotPath) : null;
-    const portToUse = 8888;
     let resolvedTarget;
     try {
         resolvedTarget = (0, devShared_1.resolveDevTarget)(targetArg, options.appName);
@@ -280,7 +279,12 @@ async function capture(targetArg, options = {}) {
         }
         const entryLabel = (0, node_path_1.relative)(process.cwd(), filePath) || filePath;
         console.log(`[capture] Preparing ${entryLabel} for ${env} (${appTypeSlug}).`);
-        const serverAlreadyRunning = await (0, devServer_1.isDevServerAvailable)(appName, portToUse, 750);
+        const serverAlreadyRunning = await (0, devServer_1.isDevServerAvailable)({
+            creatorUsername: currentUsername,
+            appType: appTypeSlug,
+            appName,
+            port: devServer_1.DEV_ROUTER_PORT,
+        }, 750);
         const devServerStartedByCapture = !serverAlreadyRunning;
         let serverHandle = null;
         let signalHandler = null;
@@ -299,14 +303,21 @@ async function capture(targetArg, options = {}) {
             }
         };
         if (serverAlreadyRunning) {
-            console.log(`[capture] Reusing dev server at http://localhost:${portToUse}/apps/${appName}.html`);
+            console.log(`[capture] Reusing dev server at ${(0, devServer_1.buildLocalDevAppUrl)({
+                creatorUsername: currentUsername,
+                appType: appTypeSlug,
+                appName,
+                port: devServer_1.DEV_ROUTER_PORT,
+            })}`);
         }
         else {
             try {
                 serverHandle = await (0, devServer_1.startDevServer)({
                     appName,
+                    appType: appTypeSlug,
+                    creatorUsername: currentUsername,
                     htmlPath: filePath,
-                    port: portToUse,
+                    port: devServer_1.DEV_ROUTER_PORT,
                     projectInfo,
                 });
                 signalHandler = () => {
@@ -316,10 +327,20 @@ async function capture(targetArg, options = {}) {
                 process.on('SIGTERM', signalHandler);
             }
             catch (error) {
-                (0, messages_1.printErrorWithHelp)(error?.message || `Failed to start dev server on port ${portToUse}.`, [
-                    'Check if another process is already using the port.',
-                    'Ensure the HTML file exists and is readable.',
-                ], { command: 'project capture' });
+                const mountConflict = (0, devServer_1.parseMountConflictError)(typeof error?.message === 'string' ? error.message : '');
+                if (mountConflict) {
+                    (0, messages_1.printErrorWithHelp)(`A different dev session already owns ${mountConflict.ref}.`, [
+                        `Active owner pid: ${mountConflict.ownerPid}.`,
+                        `Mounted repo root: ${mountConflict.repoRoot}.`,
+                        `Mounted HTML path: ${mountConflict.htmlPath}.`,
+                    ], { command: 'project capture' });
+                }
+                else {
+                    (0, messages_1.printErrorWithHelp)(error?.message || `Failed to start the shared dev router on port ${devServer_1.DEV_ROUTER_PORT}.`, [
+                        'Close the conflicting process or wait for the stale mount to exit.',
+                        'Ensure the HTML file exists and is readable.',
+                    ], { command: 'project capture' });
+                }
                 process.exitCode = 1;
                 return;
             }
@@ -381,5 +402,5 @@ async function capture(targetArg, options = {}) {
             }
             await cleanup();
         }
-    });
+    }, { workspacePath: resolvedTarget.cataloguePath ?? (0, node_path_1.dirname)(filePath) });
 }