name: lyx-shell-expert description: >- Expert on the Lyx Shell: layout rendering, Module Federation, SSR streaming, URL parsing, devtools. Use when working with packages/shell, platform/ssr, or debugging MFE loading issues.

Lyx Shell Expert

Architecture

• ShellApp → LayoutRenderer → MFESlot[] → Module Federation remotes
• SSR: entry-server.tsx streams HTML → entry-client.tsx hydrates

URL Parsing (getAppIdentifier)

Regex: /^\/([a-z0-9][a-z0-9-]{1,30}[a-z0-9]|[a-f0-9]{24})\/([^/]+)/

• Matches both custom aliases (3-32 chars, alphanumeric + hyphens) and MongoDB ObjectIds (24 hex)
• Returns { accountId, slug }
• SSR path: initialSlug from __LYX_INITIAL__ bypasses URL parsing

Layout Engine

5-band flex layout:

1. top regions → full width
2. left + center + right → CSS grid row (left/right: region.size ?? "250px", center: 1fr)
3. bottom regions → full width

Navigation events (lyx:lyx:navigate) override slot content dynamically.

Module Federation Integration

• Host: lyx_shell (init once)
• Remote key: {name}_v{version} with dots replaced by underscores
• registerRemotes([{ name: key, entry: url, type: "module" }], { force: true })
• loadRemote(\${key}/default`)— cast result, never use generics onloadRemote`
• Critical: Each version MUST have a unique key to avoid MF cache returning wrong version

SSR Flow

1. Server: renderToPipeableStream with ShellApp (layout + slug props)
2. MFESlot renders SlotSkeleton on server (no federation)
3. Stream includes <script>window.__LYX_INITIAL__={...}</script>
4. Client hydrates → MFESlot loads real remotes
5. Assets at /_assets/ base path (both vite configs)

Devtools

• Toggle: Ctrl/Cmd + Shift + D
• Tabs: State (Zustand snapshot), Events (ring buffer), Navigation (history)
• Patches window.dispatchEvent and history.pushState for logging