@symbo.ls/sdk 3.2.3 → 3.2.7

package/src/utils/CollabClient.js

@@ -1,7 +1,5 @@
 import { io } from 'socket.io-client'
 import * as Y from 'yjs'
-import { IndexeddbPersistence } from 'y-indexeddb'
-import Dexie from 'dexie'
 import { nanoid } from 'nanoid'
 import environment from '../config/environment.js'
 // import gzip from 'gzip-js' // reserved for future compression features
@@ -11,6 +9,8 @@ import { diffJson, applyOpsToJson } from './jsonDiff.js'
 
 /* eslint-disable no-use-before-define, no-new, no-promise-executor-return */
 
+// Dexie and IndexeddbPersistence will be conditionally imported in browser environments
+
 export class CollabClient {
   /* public fields */
   socket = null
@@ -24,7 +24,7 @@ export class CollabClient {
   _buffer = []
   _flushTimer = null
   _clientId = nanoid()
-  _outboxStore = null // Dexie table
+  _outboxStore = createMemoryOutbox() // Dexie table fallback
   _readyResolve
   ready = new Promise(res => (this._readyResolve = res))
 
@@ -33,10 +33,35 @@ export class CollabClient {
 
     /* 1️⃣  create Yjs doc + offline persistence */
     this.ydoc = new Y.Doc()
-    new IndexeddbPersistence(`${projectId}:${branch}`, this.ydoc)
 
-    /* 2️⃣  init Dexie for outbox */
-    this._outboxStore = createDexieOutbox(`${projectId}:${branch}`)
+    // Only use IndexeddbPersistence in browser environments
+    const hasIndexedDB = typeof globalThis.indexedDB !== 'undefined'
+
+    if (typeof window === 'undefined' || !hasIndexedDB) {
+      // In Node.js (or when indexedDB is not available), skip persistence
+      console.log('[CollabClient] IndexedDB not available – skipping offline persistence')
+    } else {
+      // Dynamically import IndexeddbPersistence only when indexedDB exists
+      import('y-indexeddb')
+        .then(({ IndexeddbPersistence }) => {
+          new IndexeddbPersistence(`${projectId}:${branch}`, this.ydoc)
+        })
+        .catch(err => {
+          console.warn('[CollabClient] Failed to load IndexeddbPersistence:', err)
+        })
+    }
+
+    /* 2️⃣  init Dexie for outbox (browser only) */
+    if (typeof window !== 'undefined' && hasIndexedDB) {
+      // In browser environments, use Dexie
+      createDexieOutbox(`${projectId}:${branch}`)
+        .then(outboxStore => {
+          this._outboxStore = outboxStore
+        })
+        .catch(err => {
+          console.warn('[CollabClient] Failed to load Dexie:', err)
+        })
+    }
 
     /* 3️⃣  WebSocket transport */
     this.socket = io(environment.socketUrl, {
@@ -52,9 +77,9 @@ export class CollabClient {
       .on('snapshot', this._onSnapshot)
       .on('ops', this._onOps)
       .on('commit', this._onCommit)
-      .on('liveMode', flag => { this.live = flag })
+      .on('liveMode', this._onLiveMode)
       .on('connect', this._onConnect)
-      .on('error', e => console.warn('[collab] socket error', e))
+      .on('error', this._onError)
 
     /* Track last known JSON representation so we can compute granular diffs. */
     this._prevJson = this.ydoc.getMap('root').toJSON()
@@ -84,8 +109,12 @@ export class CollabClient {
 
   /* ---------- private handlers ---------- */
   _onSnapshot = ({ data /* Uint8Array */ }) => {
-    // first paint; trust server compressed payload (≤256 kB)
-    Y.applyUpdate(this.ydoc, Uint8Array.from(data))
+    if (Array.isArray(data) ? data.length : (data && data.byteLength)) {
+      // First paint; trust server compressed payload (≤256 kB)
+      Y.applyUpdate(this.ydoc, Uint8Array.from(data))
+    } else {
+      console.warn('[collab] Received empty snapshot – skipping applyUpdate')
+    }
 
     // Store current state as baseline for future diffs.
     this._prevJson = this.ydoc.getMap('root').toJSON()
@@ -151,10 +180,68 @@ export class CollabClient {
     })
     this._buffer.length = 0
   }
+
+  dispose () {
+    clearTimeout(this._flushTimer)
+    this._flushTimer = null
+    this._buffer.length = 0
+
+    if (this._outboxStore?.clear) {
+      try {
+        const result = this._outboxStore.clear()
+        if (result && typeof result.catch === 'function') {
+          result.catch(() => {})
+        }
+      } catch (error) {
+        console.warn('[CollabClient] Failed to clear outbox store during dispose:', error)
+      }
+    }
+
+    if (this.socket) {
+      this.socket.off('snapshot', this._onSnapshot)
+      this.socket.off('ops', this._onOps)
+      this.socket.off('commit', this._onCommit)
+      this.socket.off('liveMode', this._onLiveMode)
+      this.socket.off('connect', this._onConnect)
+      this.socket.off('error', this._onError)
+      this.socket.removeAllListeners()
+      this.socket.disconnect()
+      this.socket = null
+    }
+
+    if (this.ydoc) {
+      this.ydoc.destroy()
+      this.ydoc = null
+    }
+
+    if (typeof this._readyResolve === 'function') {
+      this._readyResolve()
+      this._readyResolve = null
+    }
+  }
+
+  _onLiveMode = (flag) => {
+    this.live = flag
+  }
+
+  _onError = (e) => {
+    console.warn('[collab] socket error', e)
+  }
+}
+
+/* ---------- Memory storage helper for Node.js ---------- */
+function createMemoryOutbox () {
+  const store = new Map()
+  return {
+    put: (item) => store.set(item.id, item),
+    toArray: () => Array.from(store.values()),
+    clear: () => store.clear()
+  }
 }
 
-/* ---------- Dexie helper ---------- */
-function createDexieOutbox (name) {
+/* ---------- Dexie helper for browser ---------- */
+async function createDexieOutbox (name) {
+  const { default: Dexie } = await import('dexie')
   const db = new Dexie(`collab-${name}`)
   db.version(1).stores({ outbox: 'id, ops' })
   return db.table('outbox')

package/src/utils/TokenManager.js

@@ -6,7 +6,7 @@ export class TokenManager {
   constructor (options = {}) {
     this.config = {
       storagePrefix: 'symbols_',
-      storageType: 'localStorage', // 'localStorage' | 'sessionStorage' | 'memory'
+      storageType: (typeof window === 'undefined' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'testing') ? 'memory' : 'localStorage', // 'localStorage' | 'sessionStorage' | 'memory'
       refreshBuffer: 60 * 1000, // Refresh 1 minute before expiry
       maxRetries: 3,
       apiUrl: options.apiUrl || '/api',
@@ -52,13 +52,30 @@ export class TokenManager {
       return this._memoryStorage
     }
 
+    // Guard against environments where accessing storage throws (e.g., opaque origins)
+    const safeGetStorage = (provider) => {
+      try {
+        const storage = provider()
+        // Try a simple set/remove cycle to ensure it is usable
+        const testKey = `${this.config.storagePrefix}__tm_test__`
+        storage.setItem(testKey, '1')
+        storage.removeItem(testKey)
+        return storage
+      } catch {
+        return null
+      }
+    }
+
+    const localStorageInstance = safeGetStorage(() => window.localStorage)
+    const sessionStorageInstance = safeGetStorage(() => window.sessionStorage)
+
     switch (this.config.storageType) {
       case 'sessionStorage':
-        return window.sessionStorage
+        return sessionStorageInstance || this._memoryStorage
       case 'memory':
         return this._memoryStorage
       default:
-        return window.localStorage
+        return localStorageInstance || this._memoryStorage
     }
   }
 

package/src/utils/changePreprocessor.js

@@ -0,0 +1,239 @@
+
+import { diffJson } from './jsonDiff.js'
+import { computeOrdersForTuples } from './ordering.js'
+
+function isPlainObject (val) {
+  return val && typeof val === 'object' && !Array.isArray(val)
+}
+
+function getByPathSafe (root, path) {
+  if (!root || typeof root.getByPath !== 'function') { return null }
+  try { return root.getByPath(path) } catch { return null }
+}
+
+// Given the original high-level tuples and a fully qualified path, resolve the
+// "next" value that the change set intends to write at that path.
+// This walks tuples from last to first so that later changes win, and supports
+// nested paths where the tuple only targets a parent container, e.g.:
+//   ['update', ['components', 'CanvasLogoDropdown'], { ... }]
+// for a granular path like:
+//   ['components', 'CanvasLogoDropdown', 'ProjectNav', 'ListInDropdown', 'children']
+function resolveNextValueFromTuples (tuples, path) {
+  if (!Array.isArray(tuples) || !Array.isArray(path)) { return null }
+
+  // Walk from the end to honour the latest change
+  for (let i = tuples.length - 1; i >= 0; i--) {
+    const t = tuples[i]
+    if (!Array.isArray(t) || t.length < 3) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    const [action, tuplePath, tupleValue] = t
+    if ((action !== 'update' && action !== 'set') || !Array.isArray(tuplePath)) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    if (tuplePath.length > path.length) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+
+    // Ensure tuplePath is a prefix of the requested path
+    let isPrefix = true
+    for (let j = 0; j < tuplePath.length; j++) {
+      if (tuplePath[j] !== path[j]) {
+        isPrefix = false
+        break
+      }
+    }
+    if (!isPrefix) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+
+    // Direct match: the tuple already targets the exact path
+    if (tuplePath.length === path.length) {
+      return tupleValue
+    }
+
+    // Nested match: drill into the tuple value using the remaining segments
+    let current = tupleValue
+    for (let j = tuplePath.length; j < path.length; j++) {
+      if (current == null) { return null }
+      current = current[path[j]]
+    }
+    if (current !== null) {
+      return current
+    }
+  }
+
+  return null
+}
+
+/**
+ * Preprocess broad project changes into granular changes and ordering metadata.
+ * - Expands top-level object updates (e.g. ['update', ['components'], {...}])
+ *   into fine-grained ['update'|'delete', [...], value] tuples using a diff
+ *   against the current state when available
+ * - Preserves schema paths as-is
+ * - Filters out explicit deletes targeting __order keys
+ * - Appends any extra tuples from options.append
+ * - Computes stable orders for impacted parent containers
+ * - IMPORTANT: When the tuple represents creation of a brand-new entity
+ *   (e.g. ['update', ['components', key], {...}] where the path did not exist
+ *   before, or the corresponding ['schema', ...] path is new), we DO NOT
+ *   expand it into many granular changes. We keep the original change to avoid
+ *   generating noisy diffs for creates.
+ */
+export function preprocessChanges (root, tuples = [], options = {}) {
+  const expandTuple = (t) => {
+    const [action, path, value] = t || []
+    const isSchemaPath = Array.isArray(path) && path[0] === 'schema'
+    const isFilesPath = Array.isArray(path) && path[0] === 'files'
+    if (action === 'delete') { return [t] }
+
+    const canConsiderExpansion = (
+      action === 'update' &&
+      Array.isArray(path) &&
+      (
+        path.length === 1 ||
+        path.length === 2 ||
+        (isSchemaPath && path.length === 3)
+      ) &&
+      isPlainObject(value)
+    )
+    if (!canConsiderExpansion || isFilesPath || (value && value.type === 'files')) { return [t] }
+
+    // Detect brand-new entity creation:
+    // - Non-schema entities typically come as ['update', [type, key], {...}]
+    // - Schema entries as ['update', ['schema', type, key], {...}]
+    // If the exact path does not exist yet, treat it as a "create" operation and
+    // do NOT expand into granular leaf updates.
+    const prevRaw = getByPathSafe(root, path)
+    const isCreatePath = (
+      (Array.isArray(path)) &&
+      action === 'update' &&
+      (
+        // e.g. ['update', ['components', 'NewKey'], {...}]
+        (!isSchemaPath && path.length === 2) ||
+        // e.g. ['update', ['schema', 'components', 'NewKey'], {...}]
+        (isSchemaPath && path.length === 3)
+      ) &&
+      (prevRaw === null || typeof prevRaw === 'undefined')
+    )
+    if (isCreatePath) { return [t] }
+
+    const prev = prevRaw || {}
+    const next = value || {}
+    if (!isPlainObject(prev) || !isPlainObject(next)) { return [t] }
+
+    const ops = diffJson(prev, next, [])
+    // If diff yields no nested ops, preserve the original tuple as a fallback
+    // (e.g. when value equality or missing previous state prevents expansion).
+    if (!ops.length) { return [t] }
+
+    const out = []
+    for (let i = 0; i < ops.length; i++) {
+      const op = ops[i]
+      const fullPath = [...path, ...op.path]
+      const last = fullPath[fullPath.length - 1]
+      if (op.action === 'set') {
+        out.push(['update', fullPath, op.value])
+      } else if (op.action === 'del') {
+        if (last !== '__order') { out.push(['delete', fullPath]) }
+      }
+    }
+    // Prefer granular leaf operations only to minimize payload duplication.
+    return out
+  }
+
+  const minimizeTuples = (input) => {
+    const out = []
+    const seen = new Set()
+    for (let i = 0; i < input.length; i++) {
+      const expanded = expandTuple(input[i])
+      for (let k = 0; k < expanded.length; k++) {
+        const tuple = expanded[k]
+        const isDelete = Array.isArray(tuple) && tuple[0] === 'delete'
+        const isOrderKey = (
+          isDelete &&
+          Array.isArray(tuple[1]) &&
+          tuple[1][tuple[1].length - 1] === '__order'
+        )
+        if (!isOrderKey) {
+          const key = JSON.stringify(tuple)
+          if (!seen.has(key)) { seen.add(key); out.push(tuple) }
+        }
+      }
+    }
+    return out
+  }
+
+  const granularChanges = (() => {
+    try {
+      const res = minimizeTuples(tuples)
+      if (options.append && options.append.length) { res.push(...options.append) }
+      return res
+    } catch {
+      // Fallback to original tuples if anything goes wrong
+      return Array.isArray(tuples) ? tuples.slice() : []
+    }
+  })()
+
+  const hydratedGranularChanges = granularChanges.map(t => {
+    if (!Array.isArray(t) || t.length < 3) { return t }
+    const [action, path] = t
+    if ((action !== 'update' && action !== 'set') || !Array.isArray(path)) {
+      return t
+    }
+
+    const nextValue = resolveNextValueFromTuples(tuples, path)
+    if (nextValue === null) {
+      return t
+    }
+
+    return [action, path, nextValue]
+  })
+
+  // Base orders from granular changes/state
+  const baseOrders = computeOrdersForTuples(root, hydratedGranularChanges)
+
+  // Prefer explicit order for containers updated via ['update', [type], value] or ['update', [type, key], value]
+  const preferOrdersMap = new Map()
+  for (let i = 0; i < tuples.length; i++) {
+    const t = tuples[i]
+    if (!Array.isArray(t) || t.length < 3) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    const [action, path, value] = t
+    const isFilesPath = Array.isArray(path) && path[0] === 'files'
+    if (
+      action !== 'update' ||
+      !Array.isArray(path) ||
+      (path.length !== 1 && path.length !== 2) ||
+      !isPlainObject(value) ||
+      isFilesPath ||
+      (value && value.type === 'files')
+    ) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    const keys = Object.keys(value).filter(k => k !== '__order')
+    const key = JSON.stringify(path)
+    preferOrdersMap.set(key, { path, keys })
+  }
+
+  const mergedOrders = []
+  const seen = new Set()
+  // Add preferred top-level orders first
+  preferOrdersMap.forEach((v, k) => { seen.add(k); mergedOrders.push(v) })
+  // Add remaining base orders
+  for (let i = 0; i < baseOrders.length; i++) {
+    const v = baseOrders[i]
+    const k = JSON.stringify(v.path)
+    if (!seen.has(k)) { seen.add(k); mergedOrders.push(v) }
+  }
+
+  return { granularChanges: hydratedGranularChanges, orders: mergedOrders }
+}

package/src/utils/jsonDiff.js

@@ -7,12 +7,47 @@ function isPlainObject (o) {
 }
 
 function deepEqual (a, b) {
-  try {
-    return JSON.stringify(a) === JSON.stringify(b)
-  } catch (err) {
-    console.warn('deepEqual error', err)
-    return false
+  // Fast path for strict equality (handles primitives and same refs)
+  if (Object.is(a, b)) { return true }
+
+  // Functions: compare source text to detect semantic change
+  if (typeof a === 'function' && typeof b === 'function') {
+    try { return a.toString() === b.toString() } catch { return false }
   }
+
+  // One is function and the other is not
+  if (typeof a === 'function' || typeof b === 'function') { return false }
+
+  // Dates
+  if (a instanceof Date && b instanceof Date) { return a.getTime() === b.getTime() }
+
+  // RegExp
+  if (a instanceof RegExp && b instanceof RegExp) { return String(a) === String(b) }
+
+  // Arrays
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) { return false }
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) { return false }
+    }
+    return true
+  }
+
+  // Objects (including plain objects when we get here)
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    const aKeys = Object.keys(a)
+    const bKeys = Object.keys(b)
+    if (aKeys.length !== bKeys.length) { return false }
+    for (let i = 0; i < aKeys.length; i++) {
+      const key = aKeys[i]
+      if (!Object.hasOwn(b, key)) { return false }
+      if (!deepEqual(a[key], b[key])) { return false }
+    }
+    return true
+  }
+
+  // Fallback for different types
+  return false
 }
 
 import * as Y from 'yjs'