feat: add Press content mode and plugin-aware discovery

[Mohamed Mansour (mohamedmansour)]

Component galleries need a shell-free documentation view without losing server-rendered examples or hydration. This adds that presentation to native Press and makes component discovery follow the selected plugin's authoring conventions instead of assuming every npm package uses the same layout.

Approach

• Add --show=all|content to Press build and serve, defaulting to all. Content mode omits shell markup, scripts, and layout constraints before compilation while retaining metadata, authored examples, page modules, SSR, and hydration. The CLI override survives config reloads, including home/custom/404 pages.
• Separate content and shell styles. Full-mode manual themes override OS preferences for native tokens and controls; content mode follows live OS changes without applying the saved shell preference. Forced-colors overrides retain precedence.
• Keep default discovery filename-based. Isolate FAST's CEM-driven inventory and standard *.template.html resolution, with ordinary HTML fallback for undeclared components. Support symlinked packages, ancestor package/scope lookup, and npm collection spellings; report broken declared components instead of silently omitting them.
• Make package metadata an explicit discovery opt-in. Default/WebUI/none skips package JSON loading, parsing, hashing, and FAST export/ownership analysis. FAST still supports ordinary named HTML/CSS/script components directly in the app folder.
• Preserve parser error chains, resolve config-relative aliases consistently, serialize concurrent cold asset extraction, and exclude Finder metadata. Move FAST-specific documentation beside its implementation.

Validation

• cargo xtask check
• Discovery regressions for filename naming, CEM inventory, fallback, caching, symlinks, scoped lookup, and error propagation.
• FAST 2 and FAST 3 build/render coverage.
• Press browser coverage for content/all output, no-JS SSR, same-node hydration, config reloads, native themes, OS changes, forced colors, and existing shell behavior.
• Metadata-isolation regressions prove unused metadata is not parsed and does not invalidate filename-discovery caches.

An optimized synthetic probe (7 rounds of 200 warm discoveries, one unchanged component) measured a metadata-heavy 377 KB package at roughly 1.2-1.5 ms before and 0.2-0.3 ms after the metadata opt-in change. These are shared-machine measurements, not a general throughput guarantee.

[Copilot]

🟡 Changes recommended

Four moderate discovery issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds shell-free Press content mode and plugin-aware npm component discovery while preserving SSR and hydration.

Changes:

• Adds --show=all|content, themes, reload handling, and split shell/content styles.
• Refactors native and FAST discovery, metadata loading, caching, and package resolution.
• Updates documentation, fixtures, and regression coverage.

File summaries

File	Summary
docs/guide/webui-press.md	Documents Press content mode and regions.
docs/guide/concepts/components/index.md	Updates native package discovery guidance.
docs/guide/cli/index.md	Documents CLI and package rules.
docs/ai.md	Updates AI-facing guidance.
DESIGN.md	Documents Press and discovery contracts.
crates/webui/src/tests/fast.rs	Tests FAST app-folder discovery.
crates/webui-press/tests/theme-mode.test.ts	Tests themes, OS changes, and forced colors.
crates/webui-press/tests/show-mode.test.ts	Tests content/full rendering and hydration.
crates/webui-press/tests/regions_build.rs	Tests region behavior across modes.
crates/webui-press/tests/native-fixture.ts	Adds native discovery fixtures.
crates/webui-press/template/shell.css	Adds shell-specific layout styles.
crates/webui-press/template/index.html	Updates full-mode template behavior.
crates/webui-press/template/docs.css	Provides shared and content styling.
crates/webui-press/template/content.html	Adds the shell-free scaffold.
crates/webui-press/src/types.rs	Adds typed display-mode configuration.
crates/webui-press/src/state.rs	Updates shared render state.
crates/webui-press/src/serve.rs	Preserves show-mode overrides across reloads.
crates/webui-press/src/main.rs	Adds CLI handling and asset extraction.
crates/webui-press/src/lib.rs	Exposes show-mode APIs.
crates/webui-press/src/content.rs	Handles content-mode rendering.
crates/webui-press/src/bundler.rs	Updates aliases and bundling.
crates/webui-press/src/build.rs	Implements mode-specific builds.
crates/webui-press/README.md	Documents Press display modes.
crates/webui-discovery/tests/scopes.rs	Tests scoped package resolution.
crates/webui-discovery/tests/metadata.rs	Tests metadata isolation and caching.
crates/webui-discovery/tests/catalog.rs	Tests catalog discovery behavior.
crates/webui-discovery/src/plugin/mod.rs	Defines discovery plugin contracts.
crates/webui-discovery/src/plugin/fast/tests.rs	Tests FAST discovery behavior.
crates/webui-discovery/src/plugin/fast/README.md	Documents FAST discovery internals.
crates/webui-discovery/src/plugin/fast.rs	Moderate, 1 vote: validates declared exports before empty-CEM fallback; Moderate, 1 vote: prevents fallback entries from colliding with declared effective names.
crates/webui-discovery/src/npm.rs	Moderate, 1 vote: reports broken symlinked package entries instead of silently skipping them.
crates/webui-discovery/src/lib.rs	Exposes plugin-aware discovery APIs.
crates/webui-discovery/src/catalog.rs	Moderate, 2 votes: excludes reserved FAST template suffixes from native filename discovery.
crates/webui-discovery/src/cache.rs	Updates plugin-specific cache inputs.
crates/webui-discovery/README.md	Documents discovery behavior.
crates/webui-cli/src/commands/build.rs	Updates build integration.
.gitignore	Excludes Finder metadata.

Review details

Suppressed comments (3)

crates/webui-discovery/src/npm.rs:156

• path.is_dir() follows symlinks but returns false for a broken package symlink, so a scope request silently skips an entry such as node_modules/@scope/pkg -> /missing and can succeed without reporting the declared member failure. Treat symlink entries as candidates and let resolve_single/canonicalize surface the broken target, while continuing to skip ordinary non-directory files.

        let path = entry.path();
        if !path.is_dir() {
            continue;

crates/webui-discovery/src/plugin/fast.rs:130

• When a FAST package has a customElements manifest with an empty declaration list, this early return skips exported_assets(). A malformed or escaping exports["./template.html"] is then silently ignored while ordinary HTML fallback succeeds, even though the FAST contract says invalid declared assets must be errors and an empty inventory only enables fallback. Validate the package-level export before taking this fallback path and add a regression for an empty CEM plus an invalid template export.
  crates/webui-discovery/src/plugin/fast.rs:120
• The fallback inventory is filtered using the CEM tagName, but FAST registration later replaces that key with the <f-template name> from the discovered template. If a package declares fast-button while its template is named custom-button and also contains an ordinary custom-button.html, both entries are returned here; parser registration then resolves them to the same tag and fails with a duplicate-component error instead of letting the declared component win as documented. Exclude fallback files using the declared templates' effective names (or resolve declared templates before collecting fallbacks), and add a regression for a CEM tag/name mismatch.

• Files reviewed: 36/37 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Mohamed Mansour (mohamedmansour)]

Superseded by two focused, stacked PRs: #524 for plugin-aware discovery and #525 for WebUI Press content mode. The combined tree preserves this PR's changes plus the requested FAST converted-template correction and module-folder layout.