feat: add Dev Mode branch preview

[werserk]

Summary

This PR pivots Dev Mode branch builds from a branch-build-only concept to a preview-deployment architecture. It introduces a generic PreviewInstance model, serves previews under clean URLs at /preview/:previewId/, and keeps branch/worktree builds as a dev-only provider behind the existing maintainer tool workflow.

Why

We need a stable, shareable preview surface that can be activated, tested, and discussed without exposing internal implementation details or tying the product model to branch-build mechanics. Clean preview URLs also make QA and future deployment flows easier to reason about.

What changed

• Added generic preview domain types and lifecycle APIs.
• Mapped branch/worktree builds into PreviewInstance records.
• Added preview runtime path handling for /preview/:previewId/.
• Migrated app routing to clean URLs so preview and stable routes coexist cleanly.
• Updated Dev Mode settings UI to reflect the branch-preview workflow.
• Added server/client/test coverage for registry lifecycle, runtime routing, shell fallback, and branch preview workflow.

Safety / non-goals

• No Obsidian/private planning docs were committed.
• No force-push or rebase.
• No promotion/rollback feature and no subdomain preview routing in this PR.
• Branch/worktree builds remain a dev-only provider, not a user-facing product toggle.

Manual QA

Stable: https://hermes.kiraproject.ru/
Preview: https://hermes.kiraproject.ru/preview/preview-3e0fd7ff6c56/

Please verify:

1. Stable site remains healthy.
2. Preview URL serves the SPA shell.
3. Deep links under the preview path resolve correctly.
4. Dev Mode settings show the branch preview workflow.

Tests

• pnpm build
• pnpm vitest run tests/server/preview-registry.test.ts tests/server/preview-runtime.test.ts tests/server/dev-mode-branch-builds.test.ts tests/client/dev-mode-settings.test.ts
• pnpm playwright test tests/e2e/history-session-deeplink.spec.ts --project=chromium

Limitations / next step

• This branch is ahead of upstream/main by 10 commits and behind by 1 commit; no force-push or rebase was performed.
• There is no upstream PR object yet for upstream-pr/dev-mode-branch-preview, so this file is the ready-to-post PR body.
• Next requested action: maintainers should reply pass/fail on the preview flow after reviewing the stable and preview URLs.

Notes

• Current branch: upstream-pr/dev-mode-branch-preview
• Recent commits:
  • d41e144 feat: register branch builds as preview instances
  • 8e1567a feat: add preview runtime path handling
  • 42f7584 fix: mark stopped preview instances explicitly
  • efc284e feat: add preview registry lifecycle APIs
  • 82f1cab Introduce generic preview domain types
  • 3fc61c8 feat: migrate app routing to clean URLs
  • 1423c06 test(dev-mode): cover branch preview workflow
  • 0f77d9d feat(settings): add branch preview developer tools
  • 9756193 feat(dev-mode): add branch preview build runner

[werserk]

@EKKOLearnAI please review this feature. It could significantly speed up future development and testing.

If this feature can be integrated, I'll build about 5 new features on top of it, as dev tools have already been a huge help to me, and it will be much easier for me to build on top of them.

I'm not sure dev tools are necessary for all users, so I've tried to hide them a bit. There might be a better way, but for now, the current implementation seems acceptable to me.

I can make some minor edits if you wish. Just Ask.

I hope this will be useful for you and other contributors!

[EKKOLearnAI]

I really like the direction here. A branch preview / dev-mode preview flow would be very useful.

That said, the current implementation feels more like a maintainer/local-development build checker than a feature that real production users can benefit from. It depends on the running Web UI being inside a git checkout, having the full source tree available, having node_modules installed, and then creates a local worktree to run the build. That is useful for maintainers, but most online/production users will be running from an installed package, release artifact, Docker image, or other packaged deployment where .git, source files, and dev dependencies may not exist.

What I would really like from this feature is something production users can actually use: the ability to preview a new Web UI version before switching to it. For example, a user could see that a newer version is available, start a preview instance for that version in isolation, open it in the browser, verify the UI/behavior, and then decide whether to upgrade or roll back.

So my suggestion is to keep this direction, but consider shifting the product goal from “build a selected git branch in a local worktree” toward “preview an available new version safely for end users.” The branch/worktree approach can still be useful for maintainers, but it may be better as an internal/dev-only mode rather than the main user-facing preview experience.

[werserk]

Thanks for the feedback! The comments were helpful. I'll try to design a typical user scenario and implement it in the next few days.