feat(marketplace): add rich plugin detail pages backed by capability metadata

[xcv58]

Summary

Add rich plugin detail pages to the MacTools Marketplace.

The current Marketplace is optimized for package lifecycle management. Users can search, filter, install, update, relaunch, and uninstall plugins, but they cannot inspect an unfamiliar plugin in enough detail before installation.

The new experience should preserve the current list while adding a detail destination that explains:

• What the plugin does
• Which actions it provides
• What setup it requires
• What data it accesses
• Where its actions can be used
• Whether it is compatible with the current Mac
• How to try it after installation

Goals

• Let users understand a plugin before installing it.
• Present action-level capabilities, not only plugin names.
• Explain permissions before installation.
• Explain privacy and network behavior.
• Show hardware and application requirements.
• Provide screenshots and concrete examples.
• Make installation and first-use setup a continuous flow.
• Support installed, available, incompatible, failed, revoked, and update states.
• Reuse the same signed metadata used by Unified Search and the website.
• Preserve keyboard and accessibility navigation.

Non-goals

• Third-party reviews or ratings
• User comments
• Paid plugins or purchases
• Executing an uninstalled action
• Loading arbitrary remote HTML
• Building a general web browser inside Settings
• Replacing each plugin's full settings workspace
• Showing machine-local dynamic actions before installation

Navigation model

Keep the current Marketplace list and filters.

Selecting a plugin row should open a detail view in the same Settings window.

Acceptable presentation models include:

• List and detail split view
• Drill-down navigation with a back button

The final choice should match the existing Settings-window architecture and minimum supported window size.

The row's lifecycle buttons may remain available for quick management, but the row itself should also be selectable.

Detail-page sections

Header

Show:

• Plugin icon
• Localized name
• Short summary
• Version
• Release channel
• Category
• Install/update/relaunch/open-settings button
• Compatibility or attention status

What it does

Show:

• Long description
• Two or three concrete use cases
• Screenshots or short static visual previews
• Links to documentation and support where available

Do not use vague marketing language in place of capability descriptions.

Available actions

List static action descriptors.

Each action should show:

• Title
• Description
• Required permission
• Risk or confirmation requirement
• Supported surface chips

Example chips:

• Search
• Shortcut
• Workflow
• Action Grid
• Gesture
• App Intent
• Run Link

Dynamic providers should show a template such as:

Creates actions for each currently playing application after installation.

Do not fabricate machine-local entries before installation.

Requirements

Show:

• Minimum macOS version
• Supported architecture
• Required hardware
• Required installed applications
• Required command-line executables
• Permissions
• Whether a relaunch is required
• Setup-complexity indicator

Compatibility should be computed against the current Mac where possible.

Privacy and safety

Show:

• Data the plugin observes
• Data it stores
• Retention behavior
• Whether it uses the network
• Network domains where declared
• Whether telemetry is used
• Destructive or confirmation-required operations
• Whether external invocation is supported

This section should be available before installation.

Setup

For installed plugins, show a short activation checklist:

• Installed
• Required permissions granted
• Required dependency available
• Initial configuration completed
• Test action completed

Provide direct repair actions where possible.

Related capabilities

Show:

• Complementary plugins
• Alternative plugins only when they genuinely overlap
• Packs containing this plugin
• Example recipes
• Existing workflows that use its actions after installation

Provenance

Show:

• Official publisher
• Source-code reference
• License
• Release notes
• Support reference
• Catalog signing/source status

Metadata dependency

Extend the catalog with optional product and capability metadata, including:

• Long description
• Keywords and use cases
• Screenshot assets
• Publisher and support metadata
• Requirements
• Privacy declaration
• Static action descriptors
• Related plugins
• Setup steps

Remote assets must include:

• Stable path or URL
• SHA-256
• Byte size
• Media type
• Optional dimensions

The detail view must not load unverified executable content.

Installed-plugin enrichment

When a plugin is installed, enrich catalog metadata with runtime information:

• Actual action definitions
• Dynamic action entries
• Current availability
• Permission state
• Dependency state
• Plugin settings availability
• Runtime load failure
• Restart requirement

Runtime data is authoritative when it conflicts with pre-install catalog descriptors.

Installation flow

When a user presses Install:

1. Keep the user on the plugin detail page.
2. Show package progress.
3. Show restart requirements if any.
4. Refresh runtime plugin state.
5. Replace the install button with the next useful action:
   • Grant permission
   • Install dependency
   • Open Settings
   • Try first action
6. Mark setup complete after a successful first action or explicit dismissal.

Do not automatically prompt for all permissions immediately after installation.

Search integration

Unified Search should be able to navigate directly to the corresponding detail page.

Uninstalled capability results should:

• Be visually separated from executable results.
• Open the detail page.
• Never execute or silently install.
• Highlight the matched action or use case in the detail page.

Offline and failure behavior

• Continue showing the last verified catalog snapshot when refresh fails.
• Continue showing installed-plugin runtime information.
• Show a clear stale-catalog indicator where appropriate.
• Do not discard an installed plugin's local settings navigation because Marketplace metadata is unavailable.
• Handle missing screenshot assets without failing the page.
• Handle older catalog entries with sparse metadata.

Health integration

The detail page should include a Diagnostics or Needs Attention section when relevant:

• Permission missing
• Dependency missing
• Plugin failed to load
• Restart required
• Action provider unavailable
• Gesture conflict
• Last runtime error

Do not show an empty diagnostics card when the plugin is healthy.

Implementation plan

Metadata

• Define catalog v3 optional product metadata.
• Define static action-descriptor metadata.
• Define verified presentation-asset metadata.
• Add decoding compatibility for existing v2 catalogs.
• Add catalog validation tests.
• Add localization validation.

Models

• Add a plugin-detail presentation model.
• Merge catalog, package-management, and runtime state.
• Define compatibility and attention summaries.
• Define dynamic-action placeholder behavior.
• Define setup-checklist state.

UI

• Make Marketplace rows selectable.
• Add detail navigation.
• Add header and lifecycle controls.
• Add actions section.
• Add requirements section.
• Add privacy section.
• Add setup section.
• Add related capabilities.
• Add provenance and release notes.
• Add loading, sparse-metadata, and error states.

Integration

• Add Unified Search navigation to plugin details.
• Support highlighting a matched action.
• Connect permission-repair actions.
• Connect plugin settings.
• Connect first-action testing.
• Connect install/update/relaunch/uninstall state changes.
• Add accessibility identifiers and keyboard navigation.

Test coverage

Include tests for:

• Installed plugin
• Available plugin
• Update available
• Restart required
• Incompatible plugin
• Revoked plugin
• Failed package
• Failed runtime load
• Sparse v2 catalog entry
• Rich v3 catalog entry
• Missing or invalid screenshot
• Dynamic action provider
• Permission missing
• Dependency missing
• Catalog unavailable
• Catalog refresh while detail is open
• Installation completed while detail is open
• Localization fallback
• Search deep-link highlighting
• VoiceOver navigation

Acceptance criteria

• Every Marketplace item can open a detail page.
• Uninstalled plugins can be understood before installation.
• Static actions and supported surfaces are visible before installation.
• Permissions and privacy behavior are visible before installation.
• Requirements are evaluated against the current Mac where possible.
• Installation continues into setup rather than returning to an unexplained list.
• Installed runtime state overrides stale catalog capability state.
• Existing v2 catalog entries continue working.
• Verified catalog failure does not remove access to installed-plugin settings.
• Unified Search can navigate to and highlight a plugin or action.
• The experience is fully keyboard and VoiceOver accessible.