@pilotiq/pilotiq 0.17.0 → 0.18.0

package/.turbo/turbo-build.log

@@ -1,8 +1,8 @@
 
-> @pilotiq/pilotiq@0.17.0 build /home/runner/work/pilotiq/pilotiq/packages/pilotiq
+> @pilotiq/pilotiq@0.18.0 build /home/runner/work/pilotiq/pilotiq/packages/pilotiq
 > tsc -p tsconfig.build.json && pnpm run copy-assets
 
 
-> @pilotiq/pilotiq@0.17.0 copy-assets /home/runner/work/pilotiq/pilotiq/packages/pilotiq
+> @pilotiq/pilotiq@0.18.0 copy-assets /home/runner/work/pilotiq/pilotiq/packages/pilotiq
 > mkdir -p dist/styles && cp -R src/styles/*.css dist/styles/
 

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @pilotiq/pilotiq
 
+## 0.18.0
+
+### Minor Changes
+
+- 1b8c1bc: feat(pilotiq): extract `onProviderSynced(provider, fn)` helper for the seed-on-synced collab lifecycle pattern
+
+  Adapter packages that bind to a collab room (Tiptap-backed editors, the CodeMirror collab adapter) all need the same choreography on mount: if the provider's already streamed in the initial room state, run the seed callback now; otherwise register `provider.once('synced', fn)` and clean up via `provider.off?.('synced', fn)`. That gate was implemented separately in 4 renderers (`CollabTextRenderer`, `MarkdownEditor`, `TiptapEditor` in `@pilotiq/tiptap`; `CollabCodeMirrorEditor` in `@pilotiq/codemirror`).
+
+  This change extracts the pattern into a single helper in `@pilotiq/pilotiq/react` so future bug fixes in the gate logic (StrictMode double-fire, missing-off-method providers, etc.) fix in one place and so adapters from outside this monorepo can adopt the same pattern with one import.
+
+  **New public surface on `@pilotiq/pilotiq/react`:**
+
+  - `onProviderSynced(provider, fn): () => void` — runs `fn` synchronously if `provider.synced`, otherwise registers `provider.once('synced', fn)`. Returns a cleanup that safely unregisters via `try { provider.off?.('synced', fn) } catch {}`. Null/undefined provider returns a no-op cleanup.
+  - `SyncedProviderLike` — structural type with `synced?: boolean`, `once?(event: 'synced', fn): void`, `off?(event: 'synced', fn): void`. No yjs / y-websocket peer dep — callers cast their concrete provider via `provider as SyncedProviderLike`.
+
+  **Adapter package changes (patch-grade):**
+
+  - `@pilotiq/tiptap`: `CollabTextRenderer`, `MarkdownEditor`, and `TiptapEditor` each replace their ~10-line gate block with `return onProviderSynced(provider, trySeed)` (still inside the existing `useEffect`).
+  - `@pilotiq/codemirror`: `CollabCodeMirrorEditor` stores the cleanup and invokes it alongside `view.destroy()` inside the mount effect's combined cleanup.
+
+  Behavior is unchanged — no double-fire risk, no missed-cleanup risk, no API changes for callers of any of the affected renderers.
+
+  Test coverage: 6 new unit tests in `packages/pilotiq/src/react/onProviderSynced.test.ts` cover synced-now, defer-until-synced, cleanup-before-synced, null provider, off-throws, and provider-missing-once/off.
+
 ## 0.17.0
 
 ### Minor Changes

package/dist/react/CollabRoomContext.d.ts

@@ -34,4 +34,31 @@ export interface CollabRoom {
 export declare const CollabRoomContext: import("react").Context<CollabRoom | null>;
 /** Read the active collab room for the surrounding record, or `null`. */
 export declare function useCollabRoom(): CollabRoom | null;
+/**
+ * Minimal structural shape every collab provider exposes for the
+ * "initial room state has streamed in" signal. Kept structural so callers
+ * (`@pilotiq/tiptap`, `@pilotiq/codemirror`, future adapters) can pass
+ * `provider as unknown as SyncedProviderLike` without taking a hard peer
+ * dep on yjs / y-websocket / y-webrtc.
+ */
+export interface SyncedProviderLike {
+    synced?: boolean;
+    once?(event: 'synced', fn: () => void): void;
+    off?(event: 'synced', fn: () => void): void;
+}
+/**
+ * Run `fn` once the collab provider's initial room state has streamed in.
+ * If the provider is already synced, `fn` fires synchronously; otherwise
+ * it's registered via `provider.once('synced', fn)`. The returned cleanup
+ * unregisters the once handler safely (idempotent + try/catch) so callers
+ * can wire it directly into a React effect's cleanup return.
+ *
+ * Useful for the brand-new-record seed pattern: editors mounting against
+ * a freshly-created record want to push the SSR-rendered default into
+ * the empty `Y.Text` / `Y.XmlFragment` exactly once after sync, before
+ * the user types. Race caveat: two peers simultaneously mounting against
+ * a brand-new record can both see `length === 0` and both seed —
+ * accepted today across every adapter's seed path.
+ */
+export declare function onProviderSynced(provider: SyncedProviderLike | null | undefined, fn: () => void): () => void;
 //# sourceMappingURL=CollabRoomContext.d.ts.map

package/dist/react/CollabRoomContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CollabRoomContext.d.ts","sourceRoot":"","sources":["../../src/react/CollabRoomContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,IAAI,EAAO,OAAO,CAAA;IAClB,4DAA4D;IAC5D,QAAQ,EAAG,OAAO,CAAA;IAClB,+EAA+E;IAC/E,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAG,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,4CAAyC,CAAA;AAEvE,yEAAyE;AACzE,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD"}
+{"version":3,"file":"CollabRoomContext.d.ts","sourceRoot":"","sources":["../../src/react/CollabRoomContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,IAAI,EAAO,OAAO,CAAA;IAClB,4DAA4D;IAC5D,QAAQ,EAAG,OAAO,CAAA;IAClB,+EAA+E;IAC/E,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAG,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,4CAAyC,CAAA;AAEvE,yEAAyE;AACzE,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAC5C,GAAG,CAAC,CAAC,KAAK,EAAG,QAAQ,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC7C;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,EAC/C,EAAE,EAAQ,MAAM,IAAI,GACnB,MAAM,IAAI,CAUZ"}

package/dist/react/CollabRoomContext.js

@@ -9,4 +9,34 @@ export const CollabRoomContext = createContext(null);
 export function useCollabRoom() {
     return useContext(CollabRoomContext);
 }
+const NOOP_CLEANUP = () => { };
+/**
+ * Run `fn` once the collab provider's initial room state has streamed in.
+ * If the provider is already synced, `fn` fires synchronously; otherwise
+ * it's registered via `provider.once('synced', fn)`. The returned cleanup
+ * unregisters the once handler safely (idempotent + try/catch) so callers
+ * can wire it directly into a React effect's cleanup return.
+ *
+ * Useful for the brand-new-record seed pattern: editors mounting against
+ * a freshly-created record want to push the SSR-rendered default into
+ * the empty `Y.Text` / `Y.XmlFragment` exactly once after sync, before
+ * the user types. Race caveat: two peers simultaneously mounting against
+ * a brand-new record can both see `length === 0` and both seed —
+ * accepted today across every adapter's seed path.
+ */
+export function onProviderSynced(provider, fn) {
+    if (!provider)
+        return NOOP_CLEANUP;
+    if (provider.synced) {
+        fn();
+        return NOOP_CLEANUP;
+    }
+    provider.once?.('synced', fn);
+    return () => {
+        try {
+            provider.off?.('synced', fn);
+        }
+        catch { /* ignore */ }
+    };
+}
 //# sourceMappingURL=CollabRoomContext.js.map

package/dist/react/CollabRoomContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"CollabRoomContext.js","sourceRoot":"","sources":["../../src/react/CollabRoomContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AA+BjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAoB,IAAI,CAAC,CAAA;AAEvE,yEAAyE;AACzE,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC,iBAAiB,CAAC,CAAA;AACtC,CAAC"}
+{"version":3,"file":"CollabRoomContext.js","sourceRoot":"","sources":["../../src/react/CollabRoomContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AA+BjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAoB,IAAI,CAAC,CAAA;AAEvE,yEAAyE;AACzE,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC,iBAAiB,CAAC,CAAA;AACtC,CAAC;AAeD,MAAM,YAAY,GAAG,GAAS,EAAE,GAAE,CAAC,CAAA;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA+C,EAC/C,EAAoB;IAEpB,IAAI,CAAC,QAAQ;QAAE,OAAO,YAAY,CAAA;IAClC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,EAAE,EAAE,CAAA;QACJ,OAAO,YAAY,CAAA;IACrB,CAAC;IACD,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IAC7B,OAAO,GAAG,EAAE;QACV,IAAI,CAAC;YAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAC7D,CAAC,CAAA;AACH,CAAC"}

package/dist/react/index.d.ts

@@ -6,7 +6,7 @@ export { registerFieldLabelSlot, getFieldLabelSlot, type FieldLabelSlotProps } f
 export { registerPendingSuggestionOverlay, getPendingSuggestionOverlay, type PendingSuggestionOverlayProps, } from './PendingSuggestionOverlayRegistry.js';
 export { PendingSuggestionsContext, usePendingSuggestions, usePendingSuggestionsForField, type PendingSuggestion, type PendingSuggestionOrigin, type PendingSuggestionsApi, } from './PendingSuggestionsContext.js';
 export { registerPendingSuggestionApplier, getPendingSuggestionApplier, type PendingSuggestionApplier, } from './PendingSuggestionApplierRegistry.js';
-export { CollabRoomContext, useCollabRoom, type CollabRoom, } from './CollabRoomContext.js';
+export { CollabRoomContext, useCollabRoom, onProviderSynced, type CollabRoom, type SyncedProviderLike, } from './CollabRoomContext.js';
 export { registerCollabExtensions, getCollabExtensions, type CollabExtensionFactory, type CollabExtensionFactoryArgs, } from './CollabExtensionFactoryRegistry.js';
 export { registerCollabTextRenderer, getCollabTextRenderer, type CollabTextRenderer, type CollabTextRendererProps, } from './CollabTextRendererRegistry.js';
 export { registerMarkdownEditor, getMarkdownEditor, type MarkdownEditor, type MarkdownEditorProps, } from './MarkdownEditorRegistry.js';

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,UAAU,EACV,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAChG,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjH,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,KAAK,6BAA6B,GACnC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,6BAA6B,EAC7B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,KAAK,UAAU,GAChB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,GAChC,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,KAAK,kBAAkB,GACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,kBAAkB,GACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AACzG,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEtF,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAA;AAE9E,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAExD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,uBAAuB,GAC7B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAY,oBAAoB,CAAA;AACxD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,KAAK,WAAW,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAW,gBAAgB,CAAA;AAE/C,OAAO,EACL,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAG7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,KAAK,aAAa,IAAI,eAAe,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,UAAU,EACV,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAChG,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjH,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,KAAK,6BAA6B,GACnC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,6BAA6B,EAC7B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,gCAAgC,EAChC,2BAA2B,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,GAChC,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,KAAK,kBAAkB,GACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,kBAAkB,GACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AACzG,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEtF,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAA;AAE9E,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAExD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,uBAAuB,GAC7B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAY,oBAAoB,CAAA;AACxD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,KAAK,WAAW,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAW,gBAAgB,CAAA;AAE/C,OAAO,EACL,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAG7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,KAAK,aAAa,IAAI,eAAe,EAAE,MAAM,eAAe,CAAA"}

package/dist/react/index.js

@@ -6,7 +6,7 @@ export { registerFieldLabelSlot, getFieldLabelSlot } from './FieldLabelSlotRegis
 export { registerPendingSuggestionOverlay, getPendingSuggestionOverlay, } from './PendingSuggestionOverlayRegistry.js';
 export { PendingSuggestionsContext, usePendingSuggestions, usePendingSuggestionsForField, } from './PendingSuggestionsContext.js';
 export { registerPendingSuggestionApplier, getPendingSuggestionApplier, } from './PendingSuggestionApplierRegistry.js';
-export { CollabRoomContext, useCollabRoom, } from './CollabRoomContext.js';
+export { CollabRoomContext, useCollabRoom, onProviderSynced, } from './CollabRoomContext.js';
 export { registerCollabExtensions, getCollabExtensions, } from './CollabExtensionFactoryRegistry.js';
 export { registerCollabTextRenderer, getCollabTextRenderer, } from './CollabTextRendererRegistry.js';
 export { registerMarkdownEditor, getMarkdownEditor, } from './MarkdownEditorRegistry.js';

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAsB,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,UAAU,GAEX,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,cAAc,EAEd,UAAU,GAEX,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAA2B,MAAM,eAAe,CAAA;AAChG,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA4B,MAAM,6BAA6B,CAAA;AACjH,OAAO,EACL,gCAAgC,EAChC,2BAA2B,GAE5B,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,6BAA6B,GAI9B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,gCAAgC,EAChC,2BAA2B,GAE5B,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,iBAAiB,EACjB,aAAa,GAEd,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GAGpB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,GAGtB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAGlB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GAMrB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAE1B,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,GAGtB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GAEjB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,iBAAiB,GAElB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GAErB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,qBAAqB,GAGtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAInB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAElB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,GAId,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAA2B,MAAM,uBAAuB,CAAA;AACzG,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,uBAAuB,CAAA;AAEtF,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAmB,MAAM,eAAe,CAAA;AAE9E,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAExD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,GAId,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,GAEvB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,uBAAuB,GAGxB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,YAAY,GAEb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAY,oBAAoB,CAAA;AACxD,OAAO,EACL,iBAAiB,EACjB,eAAe,GAGhB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,mBAAmB,EACnB,cAAc,GAEf,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAW,gBAAgB,CAAA;AAE/C,OAAO,EACL,eAAe,GAKhB,MAAM,sBAAsB,CAAA;AAG7B,iHAAiH;AACjH,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,mBAAmB;AACnB,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAyC,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/pilotiq",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "View-based admin panel for RudderJS",
   "license": "MIT",
   "repository": {

package/src/react/CollabRoomContext.ts

@@ -40,3 +40,47 @@ export const CollabRoomContext = createContext<CollabRoom | null>(null)
 export function useCollabRoom(): CollabRoom | null {
   return useContext(CollabRoomContext)
 }
+
+/**
+ * Minimal structural shape every collab provider exposes for the
+ * "initial room state has streamed in" signal. Kept structural so callers
+ * (`@pilotiq/tiptap`, `@pilotiq/codemirror`, future adapters) can pass
+ * `provider as unknown as SyncedProviderLike` without taking a hard peer
+ * dep on yjs / y-websocket / y-webrtc.
+ */
+export interface SyncedProviderLike {
+  synced?: boolean
+  once?(event: 'synced', fn: () => void): void
+  off?(event:  'synced', fn: () => void): void
+}
+
+const NOOP_CLEANUP = (): void => {}
+
+/**
+ * Run `fn` once the collab provider's initial room state has streamed in.
+ * If the provider is already synced, `fn` fires synchronously; otherwise
+ * it's registered via `provider.once('synced', fn)`. The returned cleanup
+ * unregisters the once handler safely (idempotent + try/catch) so callers
+ * can wire it directly into a React effect's cleanup return.
+ *
+ * Useful for the brand-new-record seed pattern: editors mounting against
+ * a freshly-created record want to push the SSR-rendered default into
+ * the empty `Y.Text` / `Y.XmlFragment` exactly once after sync, before
+ * the user types. Race caveat: two peers simultaneously mounting against
+ * a brand-new record can both see `length === 0` and both seed —
+ * accepted today across every adapter's seed path.
+ */
+export function onProviderSynced(
+  provider: SyncedProviderLike | null | undefined,
+  fn:       () => void,
+): () => void {
+  if (!provider) return NOOP_CLEANUP
+  if (provider.synced) {
+    fn()
+    return NOOP_CLEANUP
+  }
+  provider.once?.('synced', fn)
+  return () => {
+    try { provider.off?.('synced', fn) } catch { /* ignore */ }
+  }
+}

package/src/react/index.ts

@@ -35,7 +35,9 @@ export {
 export {
   CollabRoomContext,
   useCollabRoom,
+  onProviderSynced,
   type CollabRoom,
+  type SyncedProviderLike,
 } from './CollabRoomContext.js'
 export {
   registerCollabExtensions,

package/src/react/onProviderSynced.test.ts

@@ -0,0 +1,90 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { onProviderSynced, type SyncedProviderLike } from './CollabRoomContext.js'
+
+/** Bare provider double — captures `once` registrations and supports
+ *  flipping `synced` so we can assert the deferred path. */
+function mockProvider(initialSynced = false): SyncedProviderLike & {
+  fire(): void
+  registered: number
+  unregistered: number
+  offThrows: boolean
+} {
+  let synced = initialSynced
+  let pending: (() => void) | null = null
+  const inst = {
+    get synced() { return synced },
+    set synced(v: boolean) { synced = v },
+    once(event: 'synced', fn: () => void) {
+      assert.equal(event, 'synced', 'only synced is registered')
+      pending = fn
+      inst.registered++
+    },
+    off(event: 'synced', fn: () => void) {
+      assert.equal(event, 'synced', 'only synced is unregistered')
+      if (inst.offThrows) throw new Error('boom')
+      if (pending === fn) pending = null
+      inst.unregistered++
+    },
+    fire() { if (pending) { const f = pending; pending = null; f() } },
+    registered:   0,
+    unregistered: 0,
+    offThrows:    false,
+  }
+  return inst
+}
+
+describe('onProviderSynced', () => {
+  it('fires fn synchronously when provider is already synced', () => {
+    const provider = mockProvider(true)
+    let calls = 0
+    const cleanup = onProviderSynced(provider, () => { calls++ })
+    assert.equal(calls, 1, 'fn ran synchronously')
+    assert.equal(provider.registered, 0, 'once never registered')
+    cleanup()
+    assert.equal(provider.unregistered, 0, 'no-op cleanup did not call off')
+  })
+
+  it('defers fn until synced event when provider not yet synced', () => {
+    const provider = mockProvider(false)
+    let calls = 0
+    const cleanup = onProviderSynced(provider, () => { calls++ })
+    assert.equal(calls, 0, 'fn not yet called')
+    assert.equal(provider.registered, 1, 'once was registered')
+    provider.fire()
+    assert.equal(calls, 1, 'fn ran after synced fired')
+    cleanup()
+    assert.equal(provider.unregistered, 1, 'cleanup called off')
+  })
+
+  it('cleanup unregisters the once handler when called before synced fires', () => {
+    const provider = mockProvider(false)
+    let calls = 0
+    const cleanup = onProviderSynced(provider, () => { calls++ })
+    cleanup()
+    assert.equal(provider.unregistered, 1, 'off was called')
+    provider.fire()
+    assert.equal(calls, 0, 'fn never fired after cleanup')
+  })
+
+  it('returns a no-op cleanup when provider is null or undefined', () => {
+    const noopCleanup = onProviderSynced(null, () => { throw new Error('unreachable') })
+    assert.doesNotThrow(() => noopCleanup())
+    const noopCleanup2 = onProviderSynced(undefined, () => { throw new Error('unreachable') })
+    assert.doesNotThrow(() => noopCleanup2())
+  })
+
+  it('swallows errors thrown by provider.off so cleanup never breaks an effect', () => {
+    const provider = mockProvider(false)
+    provider.offThrows = true
+    const cleanup = onProviderSynced(provider, () => {})
+    assert.doesNotThrow(cleanup, 'cleanup did not propagate the throw')
+  })
+
+  it('gracefully handles a provider missing once/off methods', () => {
+    const sparse: SyncedProviderLike = { synced: false }
+    const cleanup = onProviderSynced(sparse, () => {})
+    assert.doesNotThrow(cleanup, 'cleanup is safe when off is undefined')
+  })
+})