@wippy-fe/vue-host 0.0.25

package/README.md

@@ -0,0 +1,81 @@
+# @wippy-fe/vue-host
+
+Vue 3 reactive bindings for the Wippy `host.*` proxy API. Tree-shakable hooks that wrap `host.layout.*` in Vue refs + event subscriptions, with auto-cleanup on unmount.
+
+## Install
+
+```bash
+pnpm add @wippy-fe/vue-host
+```
+
+Peer deps: `vue >= 3.5`, `@wippy-fe/proxy` (also a peer so your bundler deduplicates with the rest of your Wippy integration).
+
+## `useWippyLayout()`
+
+The main composable. Returns reactive layout state + bound mutation methods.
+
+```vue
+<script setup lang="ts">
+import { useWippyLayout } from '@wippy-fe/vue-host'
+
+const layout = useWippyLayout()
+// layout.snapshot         : Ref<LayoutSnapshot | null>
+// layout.activeBreakpoint : ComputedRef<string>
+// layout.panels           : ComputedRef<Record<string, unknown>>
+// layout.isManaged        : ComputedRef<boolean>
+</script>
+
+<template>
+  <div>
+    <p v-if="!layout.isManaged">Not inside a managed-layout host.</p>
+    <p v-else>Current breakpoint: {{ layout.activeBreakpoint }}</p>
+    <button @click="layout.collapsePanel('nav')">Collapse nav</button>
+    <button @click="layout.expandPanel('nav')">Expand nav</button>
+  </div>
+</template>
+```
+
+Snapshot is seeded from `host.layout.snapshot` (sync, always available inside a managed-layout host — boot-payload carries the initial value). Subscribes to `@layout-change`; unsubscribes on unmount.
+
+## `useWippyPanel(panelId)`
+
+Reactive ref to a single panel's live def. Returns `null` when the panel doesn't exist in the current snapshot.
+
+```vue
+<script setup lang="ts">
+import { useWippyPanel } from '@wippy-fe/vue-host'
+
+const editor = useWippyPanel('editor')
+// editor.value?.route — current internal route of the editor panel
+// editor.value?.props?.sessionId — for chat-wrapper builtin
+</script>
+```
+
+## `useWippyBreakpoint()`
+
+Reactive breakpoint ref. Also updates off the `@layout-breakpoint` event (which fires immediately — not debounced with the 50ms `@layout-change` push).
+
+```ts
+import { useWippyBreakpoint } from '@wippy-fe/vue-host'
+
+const bp = useWippyBreakpoint()
+// bp.value === 'md' | 'sm' | 'default' | ...
+```
+
+## `useWippyMainRoute()`
+
+Reactive ref to the main panel's current route — the one that drives `window.location`.
+
+```ts
+import { useWippyMainRoute } from '@wippy-fe/vue-host'
+
+const route = useWippyMainRoute()
+// route.value === '/projects/42/timeline'
+```
+
+## When to use this vs `@wippy-fe/layout`'s composables
+
+- `@wippy-fe/layout` — `useLayoutSlot`, `useLayoutBreakpoint`, `useLayoutPanel`, `useLayoutFloating` operate on a `LayoutManager` instance provided in the current Vue app. Use inside panel components mounted by `LayoutManagerView` — they have direct access to the local manager.
+- `@wippy-fe/vue-host` — `useWippyLayout` et al. operate on the `host.*` proxy surface from a CHILD iframe. The child doesn't have a LayoutManager; it reads the snapshot pushed from the parent.
+
+Rule of thumb: inside a page/artifact/component iframe rendered by a managed-layout host, use `@wippy-fe/vue-host`. Inside host-layer code (resolvers, built-in panels) with direct `LayoutManager` access, use `@wippy-fe/layout`.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@wippy-fe/vue-host",
+  "version": "0.0.25",
+  "description": "Vue 3 reactive bindings for the Wippy host.* proxy API. Hooks for layout state, panel live state, breakpoints, and per-panel routes — inside a Wippy iframe.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/",
+    "package.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "@wippy-fe/proxy": "0.0.25"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  useWippyBreakpoint,
+  useWippyLayout,
+  useWippyMainRoute,
+  useWippyPanel,
+} from './useWippyLayout'
+export type { UseWippyLayout } from './useWippyLayout'

package/src/useWippyLayout.test.ts

@@ -0,0 +1,399 @@
+/**
+ * @vitest-environment jsdom
+ */
+import type { LayoutSnapshot } from '@wippy-fe/proxy'
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, isRef, ref } from 'vue'
+
+// Mock @wippy-fe/proxy with a controllable host + on(). The shared
+// state in useWippyLayout reads `host.layout.snapshot` ONCE at first
+// hook call (per iframe lifetime — and per Vitest module), so we
+// pre-seed the snapshot, then drive updates by firing registered
+// `@layout-change` listeners.
+
+const mockState = {
+  snapshot: null as LayoutSnapshot | null,
+  listeners: new Map<string, Set<(payload: any) => void>>(),
+  hostLayoutMethods: {
+    resizePanel: vi.fn(),
+    collapsePanel: vi.fn(),
+    expandPanel: vi.fn(),
+    movePanel: vi.fn(),
+    removePanel: vi.fn(),
+    closeModal: vi.fn(),
+    removeFloating: vi.fn(),
+  },
+}
+
+function fire(topic: string, payload: any) {
+  const set = mockState.listeners.get(topic)
+  if (set) {
+    for (const cb of set) cb(payload)
+  }
+}
+
+function listenerCount(topic: string): number {
+  return mockState.listeners.get(topic)?.size ?? 0
+}
+
+vi.mock('@wippy-fe/proxy', () => ({
+  host: {
+    layout: {
+      get snapshot() {
+        return mockState.snapshot
+      },
+      ...mockState.hostLayoutMethods,
+    },
+  },
+  on: (topic: string, cb: (payload: any) => void) => {
+    let set = mockState.listeners.get(topic)
+    if (!set) {
+      set = new Set()
+      mockState.listeners.set(topic, set)
+    }
+    set.add(cb)
+    return () => {
+      set!.delete(cb)
+    }
+  },
+}))
+
+// Import AFTER the mock — the hooks resolve `@wippy-fe/proxy` at module-load.
+const {
+  useWippyLayout,
+  useWippyPanel,
+  useWippyBreakpoint,
+  useWippyMainRoute,
+} = await import('./useWippyLayout')
+
+function makeSnapshot(over: Partial<LayoutSnapshot> = {}): LayoutSnapshot {
+  return {
+    layouts: { default: { direction: 'horizontal', children: [] } },
+    panels: {},
+    activeBreakpoint: 'default',
+    ...over,
+  }
+}
+
+beforeEach(() => {
+  // Reset all mock counters; the shared snapshot ref persists across
+  // tests by design (it's installed once on first hook call).
+  for (const fn of Object.values(mockState.hostLayoutMethods)) fn.mockReset()
+})
+
+afterEach(() => {
+  // Reset mock state for next test
+  mockState.snapshot = null
+})
+
+describe('useWippyLayout', () => {
+  it('seeds snapshot.value from host.layout.snapshot at first call', () => {
+    const initial = makeSnapshot({ activeBreakpoint: 'md' })
+    mockState.snapshot = initial
+
+    let captured: any
+    const Comp = defineComponent({
+      setup() {
+        const layout = useWippyLayout()
+        captured = layout
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    // First call seeds. Snapshot ref tracks shared state from this
+    // point — even if mockState.snapshot changes, the ref doesn't
+    // until @layout-change fires.
+    expect(captured.snapshot.value).toBeDefined()
+    w.unmount()
+  })
+
+  it('updates snapshot when @layout-change fires', () => {
+    let captured: any
+    const Comp = defineComponent({
+      setup() {
+        captured = useWippyLayout()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    const next = makeSnapshot({ activeBreakpoint: 'sm' })
+    fire('@layout-change', next)
+    expect(captured.snapshot.value).toBe(next)
+    expect(captured.activeBreakpoint.value).toBe('sm')
+    w.unmount()
+  })
+
+  it('isManaged tracks whether snapshot is null', () => {
+    let captured: any
+    const Comp = defineComponent({
+      setup() {
+        captured = useWippyLayout()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    fire('@layout-change', null)
+    expect(captured.isManaged.value).toBe(false)
+    fire('@layout-change', makeSnapshot())
+    expect(captured.isManaged.value).toBe(true)
+    w.unmount()
+  })
+
+  it('mutation methods call host.layout.* through', () => {
+    let captured: any
+    const Comp = defineComponent({
+      setup() {
+        captured = useWippyLayout()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    captured.resizePanel('files', '300px')
+    captured.collapsePanel('nav')
+    captured.expandPanel('nav')
+    captured.movePanel('a', { position: 'right' })
+    captured.removePanel('x')
+    captured.closeModal('m')
+    captured.removeFloating('f')
+
+    expect(mockState.hostLayoutMethods.resizePanel).toHaveBeenCalledWith('files', '300px')
+    expect(mockState.hostLayoutMethods.collapsePanel).toHaveBeenCalledWith('nav')
+    expect(mockState.hostLayoutMethods.expandPanel).toHaveBeenCalledWith('nav')
+    expect(mockState.hostLayoutMethods.movePanel).toHaveBeenCalledWith('a', { position: 'right' })
+    expect(mockState.hostLayoutMethods.removePanel).toHaveBeenCalledWith('x')
+    expect(mockState.hostLayoutMethods.closeModal).toHaveBeenCalledWith('m')
+    expect(mockState.hostLayoutMethods.removeFloating).toHaveBeenCalledWith('f')
+    w.unmount()
+  })
+})
+
+describe('useWippyPanel', () => {
+  it('returns panel def from snapshot.panels', () => {
+    let panelRef: any
+    const Comp = defineComponent({
+      setup() {
+        panelRef = useWippyPanel('editor')
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    fire('@layout-change', makeSnapshot({
+      panels: { editor: { kind: 'page', id: 'editor', route: '/foo' } },
+    }))
+    expect(panelRef.value).toMatchObject({ kind: 'page', id: 'editor', route: '/foo' })
+    w.unmount()
+  })
+
+  it('returns null when panel id is not in snapshot', () => {
+    let panelRef: any
+    const Comp = defineComponent({
+      setup() {
+        panelRef = useWippyPanel('ghost')
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    fire('@layout-change', makeSnapshot({ panels: {} }))
+    expect(panelRef.value).toBeNull()
+    w.unmount()
+  })
+
+  it('reacts to a Ref<string> id input', () => {
+    const id = ref('a')
+    let panelRef: any
+    const Comp = defineComponent({
+      setup() {
+        panelRef = useWippyPanel(id)
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    fire('@layout-change', makeSnapshot({
+      panels: {
+        a: { kind: 'page', id: 'a', route: '/aa' },
+        b: { kind: 'page', id: 'b', route: '/bb' },
+      },
+    }))
+    expect(panelRef.value).toMatchObject({ id: 'a' })
+    id.value = 'b'
+    expect(panelRef.value).toMatchObject({ id: 'b' })
+    w.unmount()
+  })
+
+  it('reacts to a getter id input', () => {
+    const id = ref('a')
+    let panelRef: any
+    const Comp = defineComponent({
+      setup() {
+        panelRef = useWippyPanel(() => id.value)
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    fire('@layout-change', makeSnapshot({
+      panels: {
+        a: { kind: 'page', id: 'a' },
+        b: { kind: 'page', id: 'b' },
+      },
+    }))
+    expect(panelRef.value?.id).toBe('a')
+    id.value = 'b'
+    expect(panelRef.value?.id).toBe('b')
+    w.unmount()
+  })
+})
+
+describe('useWippyBreakpoint', () => {
+  it('returns a ref', () => {
+    let bp: any
+    const Comp = defineComponent({
+      setup() {
+        bp = useWippyBreakpoint()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+    expect(isRef(bp)).toBe(true)
+    w.unmount()
+  })
+
+  it('updates from @layout-breakpoint event', () => {
+    let bp: any
+    const Comp = defineComponent({
+      setup() {
+        bp = useWippyBreakpoint()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+    fire('@layout-breakpoint', { name: 'lg', width: 1200 })
+    expect(bp.value).toBe('lg')
+    w.unmount()
+  })
+
+  it('also updates from @layout-change activeBreakpoint', () => {
+    let bp: any
+    const Comp = defineComponent({
+      setup() {
+        bp = useWippyBreakpoint()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+    fire('@layout-change', makeSnapshot({ activeBreakpoint: 'sm' }))
+    expect(bp.value).toBe('sm')
+    w.unmount()
+  })
+})
+
+describe('useWippyMainRoute', () => {
+  it('walks active-breakpoint tree to find main panel', () => {
+    let route: any
+    const Comp = defineComponent({
+      setup() {
+        route = useWippyMainRoute()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+
+    fire('@layout-change', makeSnapshot({
+      activeBreakpoint: 'default',
+      layouts: {
+        default: {
+          direction: 'horizontal',
+          children: [
+            { panel: 'sidebar', size: '200px' },
+            { panel: 'editor', size: '1fr', main: true },
+          ] as any,
+        },
+      },
+      panels: {
+        sidebar: { kind: 'component', tagName: 'x' },
+        editor: { kind: 'page', id: 'e1', route: '/edit' },
+      },
+    }))
+    expect(route.value).toBe('/edit')
+    w.unmount()
+  })
+
+  it('returns empty string when no main panel in active layout', () => {
+    let route: any
+    const Comp = defineComponent({
+      setup() {
+        route = useWippyMainRoute()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+    fire('@layout-change', makeSnapshot({
+      layouts: {
+        default: { direction: 'horizontal', children: [{ panel: 'a', size: '1fr' }] },
+      },
+      panels: { a: { kind: 'page', id: 'a' } },
+    }))
+    expect(route.value).toBe('')
+    w.unmount()
+  })
+
+  it('finds main inside a nested tree', () => {
+    let route: any
+    const Comp = defineComponent({
+      setup() {
+        route = useWippyMainRoute()
+        return () => h('div')
+      },
+    })
+    const w = mount(Comp)
+    fire('@layout-change', makeSnapshot({
+      layouts: {
+        default: {
+          direction: 'horizontal',
+          children: [
+            {
+              direction: 'vertical',
+              children: [{ panel: 'editor', size: '1fr', main: true }],
+            } as any,
+          ],
+        },
+      },
+      panels: { editor: { kind: 'page', id: 'e', route: '/deep' } },
+    }))
+    expect(route.value).toBe('/deep')
+    w.unmount()
+  })
+})
+
+describe('subscription sharing', () => {
+  it('multiple hooks across multiple components share ONE @layout-change listener', () => {
+    const before = listenerCount('@layout-change')
+
+    const Comp = defineComponent({
+      setup() {
+        useWippyLayout()
+        useWippyPanel('a')
+        useWippyMainRoute()
+        return () => h('div')
+      },
+    })
+    const w1 = mount(Comp)
+    const w2 = mount(Comp)
+
+    // Module-scope shared snapshot — same listener regardless of how
+    // many hooks / components consume it.
+    expect(listenerCount('@layout-change') - before).toBeLessThanOrEqual(2)
+    // (At most: snapshot listener + breakpoint listener, both module-scoped.)
+
+    w1.unmount()
+    w2.unmount()
+  })
+})

package/src/useWippyLayout.ts

@@ -0,0 +1,181 @@
+import type { LayoutSnapshot, PanelTarget } from '@wippy-fe/proxy'
+import type { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from 'vue'
+import { host, on } from '@wippy-fe/proxy'
+import { computed, shallowRef, toValue } from 'vue'
+
+/**
+ * Vue 3 reactive bindings for `host.layout.*`. Use from any component
+ * inside a Wippy iframe (managed-layout or compat). In compat mode
+ * `snapshot.value` stays `null` and mutations are silent no-ops.
+ *
+ * Boot-time seed comes from `host.layout.snapshot` (sync cache,
+ * populated from `AppContext.layout` in the child's `__WIPPY_INITIAL_CONFIG__`).
+ * Subsequent updates arrive via the `@layout-change` proxy topic —
+ * `events.ts` is the single writer that updates the cache and then
+ * fires the event, so reads here are always fresh.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * import { useWippyLayout } from '@wippy-fe/vue-host'
+ *
+ * const layout = useWippyLayout()
+ * // layout.snapshot — Ref<LayoutSnapshot | null>
+ * // layout.activeBreakpoint — ComputedRef<string>
+ * // layout.panels — ComputedRef<Record<string, unknown>>
+ * // layout.isManaged — ComputedRef<boolean>
+ *
+ * layout.resizePanel('files', '400px')
+ * layout.collapsePanel('sidebar')
+ * </script>
+ * ```
+ */
+export interface UseWippyLayout {
+  /** Live layout snapshot — null outside a managed-layout host. */
+  snapshot: Ref<LayoutSnapshot | null>
+  /** Currently-active breakpoint name. Empty string when no snapshot. */
+  activeBreakpoint: ComputedRef<string>
+  /** Live per-panel declaration map. Includes `route`, `props`, etc. */
+  panels: ComputedRef<Record<string, unknown>>
+  /** True when a managed-layout host is driving this iframe. */
+  isManaged: ComputedRef<boolean>
+
+  resizePanel: (panelId: string, size: string) => void
+  collapsePanel: (panelId: string) => void
+  expandPanel: (panelId: string) => void
+  movePanel: (panelId: string, target: PanelTarget) => void
+  removePanel: (panelId: string) => void
+  closeModal: (modalId: string) => void
+  removeFloating: (floatingId: string) => void
+}
+
+/**
+ * Module-scoped shared snapshot ref + subscription. Every hook in this
+ * package reads from the same `ShallowRef`, so a component using
+ * `useWippyLayout()` + `useWippyPanel('a')` + `useWippyBreakpoint()`
+ * pays for ONE `@layout-change` subscription, not three.
+ *
+ * The subscription is installed lazily on first call and lives for the
+ * iframe's lifetime — no per-component cleanup needed (one closure on
+ * a process-wide bus is cheap; in compat-mode hosts this never fires).
+ */
+let sharedSnapshot: ShallowRef<LayoutSnapshot | null> | null = null
+let sharedBreakpoint: ShallowRef<string> | null = null
+
+function getSharedSnapshot(): ShallowRef<LayoutSnapshot | null> {
+  if (sharedSnapshot)
+    return sharedSnapshot
+  const ref = shallowRef<LayoutSnapshot | null>(host.layout.snapshot)
+  on('@layout-change', (next) => {
+    ref.value = next
+  })
+  sharedSnapshot = ref
+  return ref
+}
+
+function getSharedBreakpoint(): ShallowRef<string> {
+  if (sharedBreakpoint)
+    return sharedBreakpoint
+  const ref = shallowRef<string>(host.layout.snapshot?.activeBreakpoint ?? '')
+  on('@layout-change', (snap) => {
+    if (snap?.activeBreakpoint)
+      ref.value = snap.activeBreakpoint
+  })
+  on('@layout-breakpoint', ({ name }) => {
+    ref.value = name
+  })
+  sharedBreakpoint = ref
+  return ref
+}
+
+export function useWippyLayout(): UseWippyLayout {
+  const snapshot = getSharedSnapshot()
+
+  return {
+    snapshot,
+    activeBreakpoint: computed(() => snapshot.value?.activeBreakpoint ?? ''),
+    panels: computed(() => (snapshot.value?.panels ?? {}) as Record<string, unknown>),
+    isManaged: computed(() => snapshot.value !== null),
+    resizePanel: (id, size) => host.layout.resizePanel(id, size),
+    collapsePanel: id => host.layout.collapsePanel(id),
+    expandPanel: id => host.layout.expandPanel(id),
+    movePanel: (id, t) => host.layout.movePanel(id, t),
+    removePanel: id => host.layout.removePanel(id),
+    closeModal: id => host.layout.closeModal(id),
+    removeFloating: id => host.layout.removeFloating(id),
+  }
+}
+
+/**
+ * Reactive ref to a single panel's live def. Returns `null` when the
+ * panel doesn't exist in the current snapshot (removed or not declared).
+ *
+ * `panelId` accepts a static string, a ref, or a getter — so a consumer
+ * passing `() => props.id` or a `Ref<string>` will see the panel def
+ * change reactively when the id input changes.
+ *
+ * Common use: read `panel.value?.route` inside an editor component to
+ * drive its internal router from the authoritative layout state.
+ */
+export function useWippyPanel(
+  panelId: MaybeRefOrGetter<string>,
+): ComputedRef<Record<string, unknown> | null> {
+  const snapshot = getSharedSnapshot()
+  return computed(() => {
+    const id = toValue(panelId)
+    const panels = snapshot.value?.panels as Record<string, unknown> | undefined
+    return (panels?.[id] as Record<string, unknown> | undefined) ?? null
+  })
+}
+
+/**
+ * Reactive active-breakpoint ref. Updates off both `@layout-change`
+ * and `@layout-breakpoint`; the latter fires immediately on each
+ * transition (no 50ms debounce), so UI that reacts to breakpoint
+ * transitions is responsive.
+ */
+export function useWippyBreakpoint(): Ref<string> {
+  return getSharedBreakpoint()
+}
+
+/**
+ * Reactive ref to the main panel's current route. Derived by walking
+ * the snapshot's active-breakpoint tree to find the slot with
+ * `main: true` and reading `panels[id].route`. Returns empty string
+ * when there's no main panel or no route set.
+ *
+ * Note: the active breakpoint may not have a main panel (e.g. an `sm`
+ * layout that drops the main entirely for a mobile-only view). In that
+ * case this ref returns ''. Bind to `useWippyPanel(<id>).value?.route`
+ * for a specific panel's route across breakpoints.
+ */
+export function useWippyMainRoute(): ComputedRef<string> {
+  const snapshot = getSharedSnapshot()
+  return computed(() => {
+    const snap = snapshot.value
+    if (!snap)
+      return ''
+    const layouts = snap.layouts as Record<string, unknown>
+    const tree = layouts[snap.activeBreakpoint ?? 'default'] ?? layouts.default
+    const mainId = findMainPanel(tree)
+    if (!mainId)
+      return ''
+    const panelDef = (snap.panels as Record<string, { route?: string }>)[mainId]
+    return panelDef?.route ?? ''
+  })
+}
+
+function findMainPanel(node: unknown): string | null {
+  if (!node || typeof node !== 'object')
+    return null
+  const n = node as { panel?: string, main?: boolean, children?: unknown[] }
+  if (typeof n.panel === 'string' && n.main === true)
+    return n.panel
+  if (Array.isArray(n.children)) {
+    for (const child of n.children) {
+      const found = findMainPanel(child)
+      if (found !== null)
+        return found
+    }
+  }
+  return null
+}