| name | fantasia-floating-windows |
| description | In-renderer floating Window* surfaces: Teleport to body, useFaFloatingWindowFrame, per-edge viewport margins, resize geometry and clamp, z-index band 5000–5999, Vitest teleport stub, custom fa-floatingWindowPop open/close transition. Use when adding or changing Window* components, frame behavior, or src/scripts/floatingWindows helpers. |
Fantasia Archive — in-renderer floating windows
What they are
Window* under src/components/floatingWindows/ — movable/resizable position: fixed in same renderer. Not extra Electron BrowserWindow instances.
Architecture (checklist)
- Teleport —
_FaFloatingWindowBodyTeleport under document.body. Transition wraps single element: Teleport → Transition → frame root
- Composable —
useFaFloatingWindowFrame(visibleRef, layout?) from src/scripts/floatingWindows/: center, title drag, resize, ResizeObserver, frameStyle + z-index
- Z-index —
5000–5999 session counters; below 6000 (modals/chrome). Bands: standard 5000–5799, projectStyling 5800–5899, app noteboard 5900–5949, project noteboard 5950–5999. raiseZ on open/interaction
- Layout —
I_FaFloatingWindowFrameLayout / FA_FLOATING_WINDOW_FRAME_DEFAULT_LAYOUT: fractions, min/max, per-edge margins
- Resize —
faFloatingWindowResizeGeometry.ts, faFloatingWindowResizeClamp.ts; _FaFloatingWindowFrameResizeHandles
- Modals — no
registerComponentDialogStackGuard for Window*
- i18n —
i18n/<locale>/floatingWindows/
Shared window families (_shared*)
_sharedWindowStyling/ — createWindowStylingFrame, Monaco session, color panel, keybind help, persist; WindowAppStyling / WindowProjectStyling bind app vs project state only._sharedWindowNoteboard/ — createAssembledWindowNoteboard, persist, factory bind; WindowAppNoteboard / WindowProjectNoteboard thin over shared assembly.- Extend shared
functions/ + per-window *_manager.ts — no monolithic createWindowAppStyling / createWindowProjectStyling.
Open/close Transition (Custom app CSS / WindowAppStyling)
faFloatingWindowPopTransition.ts: FA_FLOATING_WINDOW_POP_TRANSITION_MS, class fa-floatingWindowPop-*- SCSS in
WindowAppStyling.floatingWindowPopTransition.unscoped.scss — not stock q-transition--scale (breaks Electron/Monaco Playwright)
Project Noteboard (WindowProjectNoteboard)
- Text debounce 380 ms; frame 280 ms. Frame-only save may race text debounce →
persistProjectNoteboardPartialSilent merges in-memory textarea when patch omits text
floatingWindowZLayer: 'projectNoteboard' → 5950–5999
Project Custom CSS (WindowProjectStyling)
- KV
project_styling_*; frame 280 ms, body 380 ms; persistProjectStylingPartialSilent merges in-memory CSS on frame-only race
Tests
- Geometry:
faFloatingWindowResizeGeometry.vitest.test.ts
- Component Vitest: stub teleport binding +
<div><slot /></div>
- Playwright:
data-test-locator on teleported frame
Custom app CSS help (WindowAppStyling)
? menu lists --fa-color-* names — logic in src/scripts/faTheme/
Related docs
