History

Antti Kettunen ffd989d0f3 Split issue request code into api module - Move HTTP and query-option helpers out of -issues.helpers.ts. - Keep -issues.helpers.ts focused on pure normalization and formatting helpers. - Update issue route and modal callers to import request code from -issues.api.ts.		2026-05-13 22:26:24 +03:00
..
src	Split issue request code into api module	2026-05-13 22:26:24 +03:00
static	Keep Issues and artist detail history stable	2026-05-13 22:26:24 +03:00
tests	Keep Issues and artist detail history stable	2026-05-13 22:26:24 +03:00
.gitignore	Initial Vite app scaffolding & issues page impl	2026-05-13 22:24:46 +03:00
index.html	Centralize shell bridge glue	2026-05-13 22:26:23 +03:00
package-lock.json	Update webui dependencies	2026-05-13 22:26:21 +03:00
package.json	Format & lint React code	2026-05-13 22:26:23 +03:00
playwright.config.ts	Initial Vite app scaffolding & issues page impl	2026-05-13 22:24:46 +03:00
README.md	Clean up docs related to local development instructions	2026-05-13 22:26:23 +03:00
tsconfig.json	Initial Vite app scaffolding & issues page impl	2026-05-13 22:24:46 +03:00
vite.config.ts	Format & lint React code	2026-05-13 22:26:23 +03:00
vitest.setup.ts	Stub scrollTo in Vitest setup	2026-05-13 22:26:22 +03:00

README.md

WebUI Hybrid Rendering

SoulSync's web UI is in a transition phase:

most pages still render through the legacy vanilla JS shell
/issues is rendered by the new React app
a small shell bridge keeps both runtimes aware of the active page, profile context, and navigation state

How It Fits Together

flowchart LR
    Browser["Browser parses /webui/index.html"]
    Legacy["Legacy shell scripts\n(core.js -> ... -> init.js)"]
    Bridge["shell-bridge.js\nwindow.SoulSyncWebShellBridge"]
    React["Vite React app\nsrc/app/main.tsx"]
    Router["TanStack Router\nwindow.SoulSyncWebRouter"]

    Browser --> Legacy
    Browser --> React
    Legacy --> Bridge
    React --> Router
    Router --> Bridge
    Bridge --> Legacy

Runtime Roles

webui/static/init.js
- boots the legacy shell
- selects the active profile
- handles the old page activation flow
webui/static/shell-bridge.js
- owns the browser-side bridge object
- exposes window.SoulSyncWebShellBridge
- syncs page chrome between legacy and React
webui/src/app/main.tsx
- mounts the React app
- binds window.SoulSyncWebRouter
webui/src/platform/shell/route-controllers.tsx
- listens for bridge readiness
- keeps React pages aligned with the shell

Load Order

The current order in index.html matters:

legacy shell scripts load first
init.js sets up the shell runtime
shell-bridge.js publishes the shell bridge after those helpers exist
the Vite React app is injected through {{ vite_assets('body') }} and boots as a module after parsing

That order avoids load-time references to missing globals and keeps the React side able to react to bridge readiness events. The React entry can start fetching early, but the shell bridge and legacy globals are already available by the time the React runtime starts acting on them.

Notes

The bridge is intentionally small and browser-only.
This is the start of the migration, not a full replacement of the legacy shell.
When adding another React page, check whether it needs:
- a route entry in webui/src/platform/shell/route-manifest.ts
- bridge typings in webui/src/platform/shell/globals.d.ts
- a legacy fallback path in webui/static/init.js
- bridge glue or handoff logic in webui/static/shell-bridge.js

Development

The repo root now owns the full local-dev instructions. Start there for the portable launcher and backend/frontend setup:

README.md for the end-to-end dev flow
npm run check and npm run fix for React-side linting and formatting