Legacy UI Bridge
Relevant source files
The following files were used as context for generating this wiki page:
The Legacy UI Bridge manages the interoperability between the project's classic JavaScript runtime and the migrated Vue 3 frontend. It allows new Vue components to mount within existing page structures while consuming shared state and services from the legacy shell. The project maintains a set of audited boundaries to track remaining classic/Vue crossings and their respective owners.
Sources: frontend-app/AGENTS.md:1-12, frontend-app/README.md:1-15
Architecture and Migration Status
The frontend uses an incremental migration strategy where new UI features reside in frontend-app/src/. The legacy UI continues to own the application shell, global router, and offline sync machinery. Vue components are delivered via a committed production bundle (frontend/vue/prks-vue.js) which the classic shell loads into a hidden root element (#prks-vue-root).
Sources: frontend-app/README.md:1-15, frontend/index.html:36-38
The diagram shows how the Legacy HTML Shell hosts the Vue Application, which then teleports specific features back into classic DOM containers while consuming legacy state.
Sources: frontend-app/AGENTS.md:34-45, frontend-app/README.md:10-25
Route Surface Bridge
The route-surface module acts as an owner-scoped bridge from the legacy TabContext runtime into Vue views. It is not a secondary router; instead, it provides a discriminated identity for mounted owners based on the legacy router's hash parsing.
Presentation Coordination
The project uses prksPresentVueRoute in app.js to paint every route feature. This coordinator owns the host element and the request envelope, delivering host-local requests to Vue feature presenters.
| Component | Responsibility |
|---|---|
PrksRouteInstance | Discriminated identity of one mounted owner. |
prksPresentVueRoute | Orchestrates the painting of Vue routes within legacy containers. |
prksVueDismissRoute | Handles the dismissal of route features and release of owner resources. |
TabContext | Hosts external resource lifetimes and manages tab-specific generations. |
Sources: frontend-app/AGENTS.md:34-58, frontend-app/src/features/work/detail-lifecycle.ts:74-85
Resource Lifecycle Management
Resources mounted by a route are released when the route component unmounts. The legacy system manages external resource lifetimes through a registration system that distinguishes between suspendable and non-suspendable resources.
- Suspendable Resources: PDF viewer and Research Notes (EasyMDE). These can be "warm parked" when a tab is inactive.
- Non-suspendable Resources: Work metadata, Folder tags, and private notes editors.
Sources: frontend-app/AGENTS.md:65-80, frontend-app/src/features/work/detail-lifecycle.ts:180-210
The sequence diagram illustrates the lifecycle of a work detail mount, from initial presentation to resource suspension during a warm park event.
Sources: frontend-app/AGENTS.md:70-85, frontend-app/src/features/work/detail-lifecycle.ts:93-115
Shared UI Primitives
The bridge utilizes shared visual primitives defined in frontend/js/overview-primitives.js for information-dense strips in page headers and details panels. These primitives are strictly typed and do not allow raw HTML to prevent security vulnerabilities.
Component Mapping
The project maps legacy CSS classes to Vue components to maintain visual consistency during the transition.
| Legacy Primitive | Vue Equivalent | Usage |
|---|---|---|
.prks-btn | PrksButton | Labeled in-page actions. |
.prks-icon-btn | PrksIconButton | Square icon-only controls. |
.prks-scope-line | PrksScopeLine | Collection counts and scope info. |
.prks-rel-summary | PrksRelSummary | Identity strips (plain text links). |
Sources: frontend-app/AGENTS.md:20-32, frontend/js/overview-primitives.js:1-15
Data and API Boundaries
The Vue application uses a typed API client (src/api/) instead of issuing arbitrary transport calls. This layer maintains the distinction between transport Data Transfer Objects (DTOs) and PRKS domain semantics.
Offline and Sync Integration
The bridge ensures that Vue People routes and classic mutation logic respect the offline policy. Mutations like creating or deleting a person enqueue durable operations. The bridge uses prksBindPersonOfflineState to keep mounted pages in step with connectivity status.
function prksBindPersonOfflineState(ctx, container) {
if (!container) return function () {};
// Immediate application of current state
applyAll();
// Subscribe to connectivity changes
let unsubscribe = prksOfflineRuntimeSubscribe(() => {
applyAll();
});
// Register cleanup with legacy TabContext
ctx.registerCleanup(dispose);
}
Sources: frontend/js/components/people.js:149-165, frontend-app/AGENTS.md:95-105
Summary
The Legacy UI Bridge provides the necessary glue to run a modern Vue 3 application within a mature JavaScript ecosystem. By enforcing strict resource ownership and utilizing a shared set of UI primitives, the project achieves a seamless user experience while incrementally migrating features to the new architecture. Key aspects include route-surface synchronization, durable resource management, and a unified design system across both runtimes.
Sources: frontend-app/AGENTS.md:118-125, frontend-app/README.md:1-5