window-panel-authoring

What problem does it solve?

This skill provides a complete pattern to author and manage floating window panels in the matrx-admin system. It covers the full 5-step registration flow (registry → component → OverlayController → SidebarWindowToggle → optional URL hydrator), the Supabase window_sessions persistence contract, onCollectData patterns, ephemeral vs persisted windows, sidebar/footer layout rules, and the multi-window pattern. Use when creating a new window panel, editing an existing window component, adding persistence to a window, wiring a window into the Tools grid, or debugging why a window fails to restore after page reload.

Core Features & Use Cases

• Registration workflow: register in windowRegistry.ts with slug, overlayId, label, and defaultData; create a window component file under windows/; ensure id stability and overlayId alignment.
• Overlay wiring: mount the window via OverlayController.tsx with dynamic imports and selector hooks; ensure open state and data restoration match registry configuration.
• Tools integration: add the window to the Tools grid via SidebarWindowToggle.tsx and provide a consistent action to open the overlay.
• Persistence contract: rely on WindowPanel persistence to store geometry automatically and save window state via onCollectData for JSON-serializable data; support ephemeral vs persisted behavior.
• URL hydration (optional): enable deep-linking to reopen specific windows with initial data via a hydrator.

Quick Start

Register the new window in windowRegistry.ts, implement its window component, wire it into OverlayController.tsx, add it to SidebarWindowToggle.tsx, and optionally enable URL hydration.

Modifying an Existing Window

When changing a window’s content state, update the registry defaultData, adjust onCollectData, propagate new initial props, and modify OverlayController data destructuring as needed.

Persistence Contract

WindowPanel handles automatic geometry persistence when overlayId is set; the child provides content via onCollectData, which must be JSON-serializable and align with the registry’s defaultData shape.

Ephemeral Windows

Use ephemeral: true for non-persistent/debug windows; such windows do not persist state or restore on reload.

Sidebar Layout Rules

Follow the standard root and content structure for a responsive, scrollable Tools sidebar; ensure proper flex layout and avoid overflow handling at the root level.

Common Mistakes

• Mismatched overlayId and registry overlayId breaks save/restore behavior.
• onCollectData returns stale data; include all keys defined in defaultData.
• Missing dynamic import or render block prevents the window from appearing.
• Missing registry entry disables persistence and the Save button.

Additional Resources

• Full prop reference and all registered windows: features/window-panels/README.md
• Registry source of truth: features/window-panels/registry/windowRegistry.ts
• Persistence service: features/window-panels/service/windowPersistenceService.ts
• Context provider: features/window-panels/WindowPersistenceManager.tsx