@pilotiq/pilotiq 0.7.2 → 0.8.1

package/src/react/AppShell.tsx

@@ -10,10 +10,12 @@ import type { RightPanelRegistry } from './right-panel-registry.js'
 import { RightPanelRegistryProvider } from './right-panel-registry.js'
 import { RightSidebarProvider, useRightSidebarOptional } from './RightSidebarContext.js'
 import { RightSidebar } from './RightSidebar.js'
+import { RecordWrapperGate } from './RecordWrapperGate.js'
 import { useIsMobile } from './hooks/use-mobile.js'
 import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta } from '../pageData.js'
 import type { RenderHookMap } from '../RenderHook.js'
 import { RenderHookSlot } from './RenderHookSlot.js'
+import type { ComponentSlotRegistry } from './component-slots.js'
 
 export interface AppShellProps {
   panel: {
@@ -73,6 +75,13 @@ export interface AppShellProps {
    * default — chrome renders without any extra wrapping.
    */
   layoutProviderRegistry?: ReadonlyArray<React.ComponentType<{ children: React.ReactNode; basePath?: string }>>
+  /**
+   * Build-time chrome-slot overrides from the Vite plugin. Populated
+   * when the panel module calls `Pilotiq.components({ nav, … })`.
+   * Sparse `{}` is the no-op default. Currently only `nav` is honored;
+   * additional slots will land as concrete consumers ask.
+   */
+  componentSlotRegistry?: ComponentSlotRegistry
   children: React.ReactNode
 }
 
@@ -110,12 +119,29 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
   const hooks = props.panel.renderHooks
   const rightSidebarMeta = props.panel.rightSidebar
 
+  // Record-scoped wrapper (collab room, audit trail, …) — pass-through
+  // when no plugin registered a wrapper or when the URL isn't a
+  // record-edit page. Wrapping `children` before forwarding to `Layout`
+  // mounts the wrapper around the page content area only, leaving the
+  // sidebar / topbar chrome outside.
+  const layoutProps = {
+    ...props,
+    children: (
+      <RecordWrapperGate
+        basePath={props.basePath}
+        {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
+      >
+        {props.children}
+      </RecordWrapperGate>
+    ),
+  }
+
   const inner = (
     <ToasterProvider {...toasterProps}>
       <CommandPaletteProvider setOpen={setPaletteOpen}>
         <RenderHookSlot name="panels::body.start" hooks={hooks} />
         <RightSidebarLayoutFrame>
-          <Layout {...props} />
+          <Layout {...layoutProps} />
         </RightSidebarLayoutFrame>
         <RenderHookSlot name="panels::body.end" hooks={hooks} />
         <CommandPalette {...paletteProps} />

package/src/react/CollabExtensionFactoryRegistry.ts

@@ -0,0 +1,55 @@
+/**
+ * Module-level registry slot for the Tiptap extension factory that turns
+ * a collab room into editor-attachable extensions (`Collaboration` +
+ * `CollaborationCursor`).
+ *
+ * Wiring posture (mirrors `PendingSuggestionOverlayRegistry`):
+ *   - `@pilotiq-pro/collab`'s plugin calls `registerCollabExtensions(...)`
+ *     once at boot from inside `register(panel)`. The factory closes over
+ *     the `@tiptap/extension-collaboration` + `-cursor` imports, so pilotiq
+ *     core (and `@pilotiq/tiptap`) never carry those as peer deps.
+ *   - `@pilotiq/tiptap`'s `TiptapEditor` calls `getCollabExtensions()` at
+ *     mount; if non-null AND a `useCollabRoom()` value is present, it calls
+ *     the factory and spreads the returned array into the editor's
+ *     `extensions` slot. If either is missing, plain Tiptap + History runs.
+ *
+ * `unknown[]` return type is deliberate — pilotiq core has zero `@tiptap/*`
+ * imports and treats the returned values as opaque editor-extension refs.
+ * The Tiptap host trusts them and spreads them in.
+ */
+export interface CollabExtensionFactoryArgs {
+  /** `Y.Doc` for the surrounding record. Opaque to pilotiq core. */
+  ydoc:      unknown
+  /** `WebsocketProvider` for the same room. Opaque to pilotiq core. */
+  provider:  unknown
+  /**
+   * Field name — becomes the `Y.XmlFragment` selector
+   * (`Collaboration.configure({ field: fieldName })`) so multiple
+   * collab editors on the same record write to distinct fragments
+   * inside one shared ydoc.
+   */
+  fieldName: string
+  /** Presence info forwarded to `CollaborationCursor`. Sparse. */
+  user?: {
+    name?:  string
+    color?: string
+  }
+}
+
+export type CollabExtensionFactory = (args: CollabExtensionFactoryArgs) => unknown[]
+
+let _factory: CollabExtensionFactory | null = null
+
+/**
+ * Register the factory that builds collab extensions for one field +
+ * room. Called once at boot by `@pilotiq-pro/collab`'s plugin. No-op when
+ * no plugin registers — Tiptap renderers fall back to plain editing.
+ */
+export function registerCollabExtensions(factory: CollabExtensionFactory): void {
+  _factory = factory
+}
+
+/** Returns the registered factory, or `null`. */
+export function getCollabExtensions(): CollabExtensionFactory | null {
+  return _factory
+}

package/src/react/CollabRoomContext.ts

@@ -0,0 +1,42 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-record realtime-collab room — a Y.Doc plus its WebsocketProvider,
+ * shared across every collaborative field in the same form. Mirrors the
+ * Tiptap "Collaborative Fields" pattern: one ydoc per record, each editor
+ * scopes itself to its own `Y.XmlFragment` via the field's `name`.
+ *
+ * Pilotiq core does NOT instantiate the room — implementation lives in
+ * `@pilotiq-pro/collab`, which mounts the context with real Yjs values
+ * via `<RecordCollabRoom>`. Core just owns the shape so any field
+ * renderer (Tiptap, in-house, third-party) can subscribe through one
+ * open-core seam without taking a hard peer dep on Yjs.
+ *
+ * `ydoc` and `provider` are typed `unknown` deliberately — the consumer
+ * (typically `@pilotiq/tiptap`) hands them straight to a registered
+ * `CollabExtensionFactory` and never touches them directly, so pilotiq
+ * core stays Yjs-free.
+ */
+export interface CollabRoom {
+  /** `Y.Doc` instance. Opaque to pilotiq core. */
+  ydoc:      unknown
+  /** `WebsocketProvider` instance. Opaque to pilotiq core. */
+  provider:  unknown
+  /** Presence info for cursors / avatars. Forwarded to the extension factory. */
+  user?: {
+    name?:  string
+    color?: string
+  }
+}
+
+/**
+ * `null` default — fields read the context, and a null result means
+ * "no collab room mounted, fall back to local-only editing." This is
+ * the 99% case (collab plugin not installed).
+ */
+export const CollabRoomContext = createContext<CollabRoom | null>(null)
+
+/** Read the active collab room for the surrounding record, or `null`. */
+export function useCollabRoom(): CollabRoom | null {
+  return useContext(CollabRoomContext)
+}

package/src/react/FormCollabBindingRegistry.ts

@@ -0,0 +1,72 @@
+import type { CollabRoom } from './CollabRoomContext.js'
+
+/**
+ * Binding contract that a collab plugin returns from
+ * `registerFormCollabBinding` — wraps a single form's value map in a
+ * shared CRDT type (typically a `Y.Map` on the surrounding record's
+ * `Y.Doc`) so every field on the form syncs across clients.
+ *
+ * Pilotiq's `FormStateProvider` calls into this contract when a
+ * `<RecordCollabRoom>` is mounted up-tree:
+ *
+ *   - `get()` is read once on mount to overlay any already-synced
+ *     state on top of the form's SSR-rendered defaults.
+ *   - `set(name, v)` is called from `setValue` after the local React
+ *     state update — every controlled field's edit lands in the CRDT.
+ *   - `subscribe(fn)` registers a listener that fires when REMOTE
+ *     changes land; `fn(snapshot)` receives the full updated map.
+ *     The provider re-applies this snapshot onto its React state.
+ *   - `destroy()` is called on unmount — gives the plugin a chance to
+ *     remove its CRDT observer.
+ *
+ * `unknown` payloads keep pilotiq core Yjs-free; the binding owns its
+ * own type knowledge. Same posture as `CollabExtensionFactory`.
+ */
+export interface FormCollabBinding {
+  /** Snapshot of the current synced values. Called once on mount. */
+  get():        Record<string, unknown>
+  /** Write the local edit to the CRDT. Triggers a broadcast to peers. */
+  set(name: string, value: unknown): void
+  /** Subscribe to remote changes. Returns an unsubscribe function. */
+  subscribe(fn: (snapshot: Record<string, unknown>) => void): () => void
+  /** Cleanup hook called when the form unmounts. */
+  destroy():    void
+}
+
+export interface FormCollabBindingFactoryArgs {
+  /** Active collab room — provides `ydoc`, `provider`, `user`. Opaque to pilotiq core. */
+  room:    CollabRoom
+  /**
+   * Form identifier — used by the binding to partition CRDT state when
+   * multiple forms render against the same room (e.g. a record page that
+   * shows a primary form plus a side-mounted action form). Most pages
+   * only have one form, so most bindings use this as the `Y.Map` name.
+   */
+  formId:  string
+  /**
+   * Initial values from pilotiq's normal SSR resolution. The binding
+   * uses these to perform the idempotent "first-load seed" (`!ymap.has(k)`
+   * gated write) so the first client to open a record populates the
+   * Y.Map with the DB-derived defaults; subsequent clients find the
+   * map already populated and skip.
+   */
+  initial: Record<string, unknown>
+}
+
+export type FormCollabBindingFactory = (args: FormCollabBindingFactoryArgs) => FormCollabBinding
+
+let _factory: FormCollabBindingFactory | null = null
+
+/**
+ * Register the form-level CRDT binding factory. Called once at boot by
+ * `@pilotiq-pro/collab`'s plugin. No-op when no plugin registers —
+ * `FormStateProvider` falls back to its plain local-state path.
+ */
+export function registerFormCollabBinding(factory: FormCollabBindingFactory): void {
+  _factory = factory
+}
+
+/** Returns the registered binding factory, or `null`. */
+export function getFormCollabBinding(): FormCollabBindingFactory | null {
+  return _factory
+}

package/src/react/FormStateContext.tsx

@@ -17,6 +17,8 @@ import {
 } from './formStateHelpers.js'
 import { runJsHandler } from './fieldJsHandler.js'
 import { useToast } from './Toaster.js'
+import { useCollabRoom } from './CollabRoomContext.js'
+import { getFormCollabBinding, type FormCollabBinding } from './FormCollabBindingRegistry.js'
 
 export type FieldStatus = 'idle' | 'pending'
 
@@ -58,6 +60,19 @@ export function useFormState(): FormStateApi | null {
  */
 export const FormIdContext = createContext<string>('')
 
+/**
+ * Phase F2 — returns `true` iff the named field has explicitly opted out
+ * of realtime collab via `Field.collab(false)`. Sparse meta — absent =
+ * inherit the panel default (collab on). Walks the form meta tree the
+ * same way `findFieldMeta` does; cheap because it only runs on the
+ * per-write path (already a hot path, but every check is one map
+ * lookup + one boolean compare).
+ */
+function fieldOptsOutOfCollab(formMeta: ElementMeta, name: string): boolean {
+  const meta = findFieldMeta(formMeta, name) as { collab?: boolean } | undefined
+  return meta?.collab === false
+}
+
 export interface UseFieldStateResult {
   /** True when the field is inside a controlled form (live fields enabled).
    *  Renderers should fall back to their `defaultValue` path when false.
@@ -184,6 +199,62 @@ export function FormStateProvider({
   useEffect(() => { formMetaRef.current = formMeta }, [formMeta])
 
   const stateUrl = (formMeta as { stateUrl?: string })['stateUrl']
+  const formId   = (formMeta as { formId?: string })['formId'] ?? ''
+
+  // Phase F2 — collab binding. When `<RecordCollabRoom>` is mounted up-tree
+  // AND `@pilotiq-pro/collab` registered a `FormCollabBinding` factory, we
+  // construct a binding for this form, lift any already-synced state on
+  // top of the SSR-rendered defaults, and proxy every local write through
+  // it. Remote writes flow back via `subscribe`. Outside a room (or with
+  // no factory registered), `bindingRef` stays null and the plain
+  // local-state path runs unchanged.
+  const collabRoom     = useCollabRoom()
+  const bindingFactory = getFormCollabBinding()
+  const bindingRef     = useRef<FormCollabBinding | null>(null)
+
+  useEffect(() => {
+    if (!collabRoom || !bindingFactory || !formId) return
+
+    const binding = bindingFactory({ room: collabRoom, formId, initial: valuesRef.current })
+    bindingRef.current = binding
+
+    // Lift any state already in the room (subsequent joiners — first
+    // mover sees an empty snapshot here and the local SSR defaults
+    // stay authoritative). Shallow merge so fields the binding doesn't
+    // know about (defaults the seed skipped, dotted-path Repeater rows
+    // we don't sync in F2) survive.
+    const synced = binding.get()
+    if (Object.keys(synced).length > 0) {
+      setValuesState((prev) => ({ ...prev, ...synced }))
+    }
+
+    // Subscribe to remote changes. Local writes ALSO trigger this
+    // (Yjs observers fire on local transactions too) — the per-key
+    // Object.is short-circuit below collapses them into no-op renders.
+    const unsubscribe = binding.subscribe((snapshot) => {
+      setValuesState((prev) => {
+        let changed = false
+        const next: Record<string, unknown> = { ...prev }
+        for (const [k, v] of Object.entries(snapshot)) {
+          if (!Object.is(prev[k], v)) {
+            next[k] = v
+            changed = true
+          }
+        }
+        return changed ? next : prev
+      })
+    })
+
+    return () => {
+      unsubscribe()
+      binding.destroy()
+      bindingRef.current = null
+    }
+    // `valuesRef.current` is intentionally read once at mount — initial
+    // values seed the binding; subsequent edits flow through `setValue`
+    // and remote changes flow through `subscribe`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collabRoom, bindingFactory, formId])
 
   /**
    * Tier-2 follow-up to Plan #5 — fire `Field.afterStateUpdatedJs(body)`
@@ -238,6 +309,14 @@ export function FormStateProvider({
       if (Object.is(prev[name], value)) return prev
       return { ...prev, [name]: value }
     })
+    // Phase F2 — proxy the write through the collab binding when active
+    // AND the field hasn't opted out via `.collab(false)`. Dotted-path
+    // names (Repeater / Builder row leaves) stay local-only in v1; their
+    // syncing belongs to Phase F.5 (`Y.Array<Y.Map>` row identity).
+    const binding = bindingRef.current
+    if (binding && !name.includes('.') && !fieldOptsOutOfCollab(formMetaRef.current, name)) {
+      binding.set(name, value)
+    }
     // Fire the client-side JS hook synchronously after the state write.
     // Dotted-name fields don't go through here (their setter is a no-op
     // in `useFieldState`); they fire JS via `triggerLive` instead so we
@@ -311,6 +390,18 @@ export function FormStateProvider({
         const serverValues = (data.form as { values?: Record<string, unknown> }).values
         if (serverValues) {
           setValuesState((prev) => ({ ...prev, ...serverValues }))
+          // Phase F2 (Q2) — derived fields propagate to peers via the
+          // collab binding so every client sees the auto-`slug` / etc.
+          // without each peer roundtripping the server. Skip dotted-path
+          // names + fields that opted out.
+          const binding = bindingRef.current
+          if (binding) {
+            for (const [k, v] of Object.entries(serverValues)) {
+              if (k.includes('.')) continue
+              if (fieldOptsOutOfCollab(data.form, k)) continue
+              binding.set(k, v)
+            }
+          }
         }
         setErrors({})
       }

package/src/react/RecordWrapperGate.tsx

@@ -0,0 +1,40 @@
+import { type ReactNode } from 'react'
+import { getRecordWrapper } from './RecordWrapperRegistry.js'
+import { parseRecordEditUrl } from './parseRecordEditUrl.js'
+
+export interface RecordWrapperGateProps {
+  currentPath?: string
+  basePath:     string
+  children:     ReactNode
+}
+
+/**
+ * Conditionally wraps the page tree with the plugin-registered
+ * `RecordWrapper` when the current URL resolves to a record-bound edit
+ * page. Pass-through in every other case:
+ *
+ *   - no plugin registered a wrapper (`getRecordWrapper() === null`)
+ *   - the URL isn't a record-edit URL (list / create / view / dashboard / …)
+ *   - `currentPath` not yet known on the very first SSR render
+ *
+ * Mounted once inside `AppShell` around the page content area so
+ * record-scoped plugins (collab room, audit trail, …) get one
+ * lifetimed mount per record-view-or-edit without each plugin having
+ * to thread URL parsing into its own provider.
+ *
+ * Scope limited to `/edit` URLs in v1; view-page support (read-only
+ * collab cursors on `ViewPage`) is a follow-up.
+ */
+export function RecordWrapperGate({ currentPath, basePath, children }: RecordWrapperGateProps) {
+  const Wrapper = getRecordWrapper()
+  if (!Wrapper || !currentPath) return <>{children}</>
+
+  const identity = parseRecordEditUrl(currentPath, basePath)
+  if (!identity) return <>{children}</>
+
+  return (
+    <Wrapper resourceSlug={identity.resourceSlug} recordId={identity.recordId}>
+      {children}
+    </Wrapper>
+  )
+}

package/src/react/RecordWrapperRegistry.ts

@@ -0,0 +1,39 @@
+import type { ComponentType, ReactNode } from 'react'
+
+/**
+ * Props the page-record wrapper receives from `RecordWrapperGate` when
+ * the current URL resolves to a record-bound edit page (`${base}/.../:id/edit`).
+ *
+ * The wrapper is responsible for whatever record-scoped context the
+ * plugin owns — `@pilotiq-pro/collab` mounts a `<RecordCollabRoom>`
+ * here so every collab field inside the page shares one Y.Doc + WS
+ * connection. Other plugins could mount per-record presence, audit
+ * logging, or anything else that's record-bound rather than panel-bound.
+ *
+ * `resourceSlug` is the slash-joined slug-path (cluster-prefixed for
+ * clustered resources, parent-prefixed for nested-relation edits) so
+ * two URLs that target different records always produce distinct
+ * wrapper keys / room names.
+ */
+export interface RecordWrapperProps {
+  resourceSlug: string
+  recordId:     string
+  children:     ReactNode
+}
+
+let _component: ComponentType<RecordWrapperProps> | null = null
+
+/**
+ * Register a component that wraps the page tree on every record-edit
+ * route. Called once at boot by a plugin (e.g. `@pilotiq-pro/collab`).
+ * No-op when no plugin registers — `RecordWrapperGate` passes through
+ * unchanged.
+ */
+export function registerRecordWrapper(C: ComponentType<RecordWrapperProps>): void {
+  _component = C
+}
+
+/** Returns the registered wrapper component, or `null`. */
+export function getRecordWrapper(): ComponentType<RecordWrapperProps> | null {
+  return _component
+}