feat(web): introduce unified appearance package system

[kev1n77]

Summary

• Replace the legacy Web Theme/Skin runtimes with a typed Appearance package system.
• Add an Appearance registry, compiler, transactional runtime, persistent selection, built-in appearances, and validated ZIP package import/export.
• Expose Appearance management through Settings, including previews, activation, diagnostics, deletion, export, and system-mode selection.
• Project Appearance data across Desktop startup, Monaco, xterm, Mermaid, Canvas, MiniApps, generative widgets, and plugin-facing payloads.
• Register explicit Appearance contracts across Web UI components, scenes, portals, Flow Chat surfaces, session trees, and tool cards.
• Prevent background media from flashing when the window regains focus or visibility.
• Add architecture documentation, contract governance, color audits, focused tests, full Web coverage, and Appearance E2E coverage.

Type and Areas

Type:

Feature / refactor / regression fix / UI/UX / test / docs / dependency

Areas:

Rust core, desktop/Tauri, Web UI, Flow Chat, Settings, component library, MiniApp, Canvas, generative widgets, editor integrations, docs, and E2E.

Motivation / Impact

The previous theme implementation was split across multiple runtimes and renderer-specific projections. It relied heavily on implicit CSS-variable behavior, making package validation, custom appearance distribution, cross-surface consistency, and ownership auditing difficult.

This PR introduces one typed Appearance contract and runtime that:

• Applies built-in or imported Appearance packages transactionally.
• Persists the selected Appearance through appearance.selection.
• Validates imported ZIP packages and manages their assets.
• Propagates consistent visual state to embedded and specialized renderers.
• Gives UI surfaces explicit component, Part, state, facet, context, and portal contracts.
• Detects missing contracts, unresolved variables, and color-governance regressions in development and CI.
• Keeps background media stable across window focus and visibility transitions.

Users can select built-in appearances, follow the system appearance, and import, export, activate, or delete custom Appearance packages from Settings.

Developers gain a documented extension model and auditable contracts for introducing or styling UI surfaces.

Verification

Passed:

• cargo check -p bitfun-desktop
  • Completed successfully.
  • Reports one existing non-blocking dead-code warning for compile_market_source_with_app_data_dir.
• pnpm run lint:web
• pnpm run type-check:web
• pnpm run appearance:contract-audit
  • 267 surfaces
  • 3,376 DOM contracts
  • 309 styled component owners
  • 16 non-blocking shared-style ownership warnings
• pnpm run theme:color-audit:all
  • Passed for Web UI, mobile web, installer, and CLI.
  • No component/non-token color occurrences or unresolved CSS variables.
• Focused Flow Chat tests:
  • FlowChatTurnRail.test.tsx
  • PermissionRequestPanel.test.tsx
  • ChatInputWorkspaceStripLayout.test.ts
  • CopyableTextPreview.test.tsx
  • FlowChatHeader.test.tsx
  • SessionTreePopover.test.tsx
• Full Web test suite:
  • 395 files and 2,688 tests passed.
• pnpm run build:web
  • Production Web build completed successfully.

Not run locally:

• Full desktop E2E suite.
• Manual visual walkthrough and screenshot capture.

Reviewer Notes

Recommended review order follows the nine-commit series:

1. Appearance package types, registry, compiler, runtime, and surface descriptors.
2. Desktop bootstrap and persisted selection.
3. Settings package-management experience.
4. Monaco, xterm, Mermaid, Canvas, MiniApp, widget, and plugin projections.
5. General Web UI surface migration.
6. Flow Chat, session-tree, and message-list surface migration.
7. Legacy Theme runtime removal.
8. Governance audits, documentation, tests, and E2E coverage.
9. Background-media focus and visibility regression fix.

Architecture details are documented in docs/architecture/appearance-package-system.md.

Compatibility and migration notes:

• The legacy Web Theme runtime and its renderer-specific helpers are removed.
• GUI appearance selection is stored at appearance.selection.
• Legacy theme and themes configuration sections are no longer exported.
• Existing custom themes are not automatically converted into Appearance packages.
• MiniApp, Canvas, and generated-widget contracts now expose Appearance-oriented payloads.
• The final diff is large because explicit DOM contracts and token migrations touch most visual surfaces; the commits separate architectural logic from mechanical migration.

This work was AI-assisted and has received the local verification listed above.

Screenshots or a short recording should be attached before requesting final UI review.

Checklist

• This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
• Relevant verification is recorded above, or skipped checks are explained.
• User-facing strings, docs, and locales are updated where applicable.