@symbo.ls/sync 3.8.9 → 3.14.1

package/SyncNotifications.js

@@ -51,8 +51,9 @@ export const connectedToSymbols = (clients, element, state) => {
 
       const t = setTimeout(() => {
         delete state.notifications.connected
-        element.notifications.content.connected
-          .setProps({ animation: 'fadeOutDown' })
+        element.notifications.content.connected.update({
+          animation: 'fadeOutDown'
+        })
         state.update({ connected: true })
         clearTimeout(t)
       }, 3000)
@@ -69,8 +70,9 @@ export const connectedToSymbols = (clients, element, state) => {
       const t = setTimeout(() => {
         delete state.notifications.connected
         if (element.notifications.content.connected) {
-          element.notifications.content.connected
-            .setProps({ animation: 'fadeOutDown' })
+          element.notifications.content.connected.update({
+            animation: 'fadeOutDown'
+          })
         }
         state.update({ connected: true })
         clearTimeout(t)
@@ -103,11 +105,11 @@ export const Notifications = {
         }
       },
       onRender: (e, el, s) => {
-        el.setProps({ animation: 'fadeInUp' })
+        el.update({ animation: 'fadeInUp' })
       },
       onClick: (e, el, s) => {
         delete s.notifications[el.key]
-        el.setProps({ animation: 'fadeOutDown' })
+        el.update({ animation: 'fadeOutDown' })
         if (s.onClose) s.onClose(e, el, s)
       }
     }),

package/applier.js

@@ -0,0 +1,71 @@
+// Pure ops applier — Node-safe, zero DOM coupling. Both browser handlers
+// (onSnapshot/onOps in `./handlers.js`) and server-side test code import
+// from here. Anything DOM-touching (init(designSystem), s.update(...)
+// re-renders, el.call('router', …)) lives in handlers.js.
+
+// Forbidden path segments — block prototype-pollution writes coming over
+// any sync transport. Without the filter, a remote
+// `setPath(ctx, ['__proto__', 'isAdmin'], true)` would pollute
+// Object.prototype across the whole runtime.
+export const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype'])
+
+export const isSafePath = (path) => {
+  if (!Array.isArray(path)) return false
+  for (let i = 0; i < path.length; i++) {
+    if (FORBIDDEN_SEGMENTS.has(path[i])) return false
+  }
+  return true
+}
+
+export const deletePath = (obj, path) => {
+  if (!obj || !isSafePath(path)) return
+  path.reduce((acc, v, i, arr) => {
+    if (acc && v in acc) {
+      if (i !== arr.length - 1) return acc[v]
+      delete acc[v]
+    }
+    return void 0
+  }, obj)
+}
+
+export const setPath = (obj, path, value, createNestedObjects = false) => {
+  if (!obj || !isSafePath(path)) return
+  path.reduce((acc, v, i, arr) => {
+    if (!acc) return void 0
+    if (i !== arr.length - 1) {
+      if (!acc[v] && createNestedObjects) acc[v] = {}
+      return acc[v]
+    }
+    acc[v] = value
+    return void 0
+  }, obj)
+}
+
+/**
+ * Apply a batch of `[action, path, value]` ops to a context object.
+ * Returns the set of top-level keys that changed so the caller can decide
+ * which downstream re-render side-effects to run.
+ *
+ * Supported actions: 'set', 'update' (alias for set), 'delete'.
+ * Empty paths are skipped — replace at the root needs a snapshot, not an op.
+ */
+export const applyOpsToCtx = (ctx, changes) => {
+  const topLevelChanged = new Set()
+  if (!Array.isArray(changes)) return topLevelChanged
+  for (const [action, path, change] of changes) {
+    if (!Array.isArray(path) || !path.length) continue
+    topLevelChanged.add(path[0])
+    switch (action) {
+      case 'delete':
+        deletePath(ctx, path)
+        break
+      case 'update':
+      case 'set':
+        setPath(ctx, path, change, true)
+        break
+      default:
+        break
+    }
+  }
+  return topLevelChanged
+}

package/handlers.js

@@ -0,0 +1,83 @@
+// Browser-only sync handlers. Imports `init` from smbls (which transitively
+// loads scratch and touches `document`), so this module must not be imported
+// from server-side code paths. Server-side tests/utilities should import from
+// `./applier.js` instead — that's the pure ops layer.
+
+import { init } from 'smbls/src/init.js'
+import { overwriteShallow } from '@symbo.ls/utils'
+import { applyOpsToCtx } from './applier.js'
+
+export const onSnapshot =
+  (el, s, ctx) =>
+  (payload = {}) => {
+    let { data } = payload
+    const { schema } = payload
+    if (!data) return
+
+    data = el.call(
+      'deepDestringifyFunctions',
+      data,
+      Array.isArray(data) ? [] : {}
+    )
+
+    Object.entries(data).forEach(([key, val]) => {
+      if (ctx[key] && typeof ctx[key] === 'object') {
+        if (key === 'designSystem') {
+          init(val)
+        } else {
+          overwriteShallow(ctx[key], val)
+        }
+      } else {
+        ctx[key] = val
+      }
+    })
+
+    if (schema) ctx.schema = schema
+  }
+
+export const onOps =
+  (el, s, ctx) =>
+  (payload = {}) => {
+    let { changes } = payload
+    if (!changes || !Array.isArray(changes) || !changes.length) return
+
+    changes = el.call(
+      'deepDestringifyFunctions',
+      changes,
+      Array.isArray(changes) ? [] : {}
+    )
+
+    const changed = applyOpsToCtx(ctx, changes)
+
+    // State changes → re-run state. Editor-driven navigation now goes
+    // through explicit `el.router(route)` calls (or a dedicated `navigate`
+    // event) instead of writing `state.route` as a side-effect channel.
+    if (changed.has('state')) {
+      s.update(ctx.state)
+    }
+
+    // Source-section changes → soft reload at the current location so the
+    // new component bodies are picked up without a full page refresh.
+    // `assets` triggers the same rerender so updated variant URLs (e.g.
+    // a `?v=<mtime>` bump on a replaced image) propagate into the rendered
+    // <img>/<source> tags — without this, byte-edits to assets would
+    // refresh the manifest in ctx but never re-render the DOM.
+    if (
+      ['pages', 'components', 'snippets', 'functions', 'assets'].some((k) =>
+        changed.has(k)
+      )
+    ) {
+      const { pathname, search, hash } = ctx.window.location
+      el.call(
+        'router',
+        pathname + search + hash,
+        el.__ref.root,
+        {},
+        { scrollToTop: false }
+      )
+    }
+
+    if (changed.has('designSystem')) {
+      init(ctx.designSystem)
+    }
+  }

package/index.js

@@ -1,83 +1,67 @@
-import { router } from '@domql/router'
-import { init } from 'smbls/src/init.js'
+import { router } from '@symbo.ls/router'
 import { io } from 'socket.io-client'
-import { window, overwriteShallow, overwriteDeep } from '@domql/utils'
-import { connectedToSymbols, Notifications } from './SyncNotifications'
-import { Inspect } from './Inspect'
-export { Inspect, Notifications }
+import { window } from '@symbo.ls/utils'
+import {
+  FORBIDDEN_SEGMENTS,
+  isSafePath,
+  deletePath,
+  setPath,
+  applyOpsToCtx
+} from './applier.js'
+import { onSnapshot, onOps } from './handlers.js'
+import { connectedToSymbols, Notifications } from './SyncNotifications.js'
+export { Notifications }
+export {
+  FORBIDDEN_SEGMENTS,
+  isSafePath,
+  deletePath,
+  setPath,
+  applyOpsToCtx,
+  onSnapshot,
+  onOps
+}
 
 const isLocal = process.env.NODE_ENV === 'local'
 
-// ---------------------------------------------
-// Utility helpers to apply ops
+const defaultBaseUrl = () =>
+  isLocal ? 'http://localhost:8080' : 'https://api.symbols.app'
 
-const deletePath = (obj, path) => {
-  if (!obj || !Array.isArray(path)) {
-    return
+/*
+ * Detect which transport this page should speak. Two modes:
+ *
+ *   collab — page was rendered by mermaid (hosted dev/staging/prod
+ *     deploys). `ctx.editor.socketUrl` is injected at render time and
+ *     points at the per-channel realtime API. Auth is a service token
+ *     fetched from `${socketUrl}/service-token`; room is keyed by
+ *     `ctx.key` (project key, or `editor.projectId` when present).
+ *
+ *   runner — page was rendered by `@symbo.ls/runner` locally. The
+ *     runner's HTTP server exposes a same-origin socket.io endpoint at
+ *     the default `/socket.io` path with no auth. Detection:
+ *     `ctx.editor.runtime === 'runner'` — the runner's boot script
+ *     stamps that onto `context.editor` before calling `Smbls.create`.
+ *     No window globals.
+ *
+ * Both modes attach the same applier handlers (onSnapshot/onOps) so the
+ * server-side wire format is interchangeable. Production builds (no
+ * socketUrl, no runner runtime) skip sync entirely.
+ */
+const detectTransport = (ctx) => {
+  const socketUrl =
+    (ctx && ctx.editor && ctx.editor.socketUrl) ||
+    (ctx && ctx.settings && ctx.settings.socketUrl)
+  if (typeof socketUrl === 'string' && socketUrl) {
+    return { mode: 'collab', baseUrl: socketUrl }
   }
-  path.reduce((acc, v, i, arr) => {
-    if (acc && v in acc) {
-      if (i !== arr.length - 1) {
-        return acc[v]
-      }
-      delete acc[v]
-    }
-    return void 0
-  }, obj)
-}
-
-const setPath = (obj, path, value, createNestedObjects = false) => {
-  if (!obj || !Array.isArray(path)) {
-    return
+  if (ctx && ctx.editor && ctx.editor.runtime === 'runner') {
+    return { mode: 'runner', baseUrl: null }
   }
-  path.reduce((acc, v, i, arr) => {
-    if (!acc) {
-      return void 0
-    }
-    if (i !== arr.length - 1) {
-      if (!acc[v] && createNestedObjects) {
-        acc[v] = {}
-      }
-      return acc[v]
-    }
-    acc[v] = value
-    return void 0
-  }, obj)
+  return { mode: null, baseUrl: null }
 }
 
-const applyOpsToCtx = (ctx, changes) => {
-  const topLevelChanged = new Set()
-  if (!Array.isArray(changes)) {
-    return topLevelChanged
-  }
-  for (const [action, path, change] of changes) {
-    if (!Array.isArray(path) || !path.length) {
-      continue
-    }
-    topLevelChanged.add(path[0])
-    switch (action) {
-      case 'delete':
-        deletePath(ctx, path)
-        break
-      case 'update':
-      case 'set':
-        setPath(ctx, path, change, true)
-        break
-      default:
-        // Unsupported action – ignore
-        break
-    }
-  }
-  return topLevelChanged
-}
-
-// ---------------------------------------------
-
-const fetchServiceToken = async () => {
+const fetchServiceToken = async (baseUrl) => {
   try {
-    const urlBase = isLocal
-      ? 'http://localhost:8080'
-      : 'https://api.symbols.app'
+    const urlBase = baseUrl || defaultBaseUrl()
     const res = await window.fetch(`${urlBase}/service-token`, {
       method: 'GET'
     })
@@ -103,117 +87,42 @@ const fetchServiceToken = async () => {
   }
 }
 
-const onSnapshot =
-  (el, s, ctx) =>
-  (payload = {}) => {
-    let { data } = payload
-    const { schema } = payload
-    if (!data) {
-      return
-    }
-
-    data = el.call(
-      'deepDestringifyFunctions',
-      data,
-      Array.isArray(data) ? [] : {}
-    )
-
-    // Overwrite high-level objects shallowly so references are preserved
-    Object.entries(data).forEach(([key, val]) => {
-      if (ctx[key] && typeof ctx[key] === 'object') {
-        if (key === 'designSystem') {
-          init(val)
-        } else {
-          overwriteShallow(ctx[key], val)
-        }
-      } else {
-        ctx[key] = val
-      }
-    })
-
-    // Optionally make schema available on ctx
-    if (schema) {
-      ctx.schema = schema
-    }
-  }
-
-const onOps =
-  (el, s, ctx) =>
-  (payload = {}) => {
-    let { changes } = payload
-    if (!changes || !Array.isArray(changes) || !changes.length) {
-      return
-    }
-
-    changes = el.call(
-      'deepDestringifyFunctions',
-      changes,
-      Array.isArray(changes) ? [] : {}
-    )
-
-
-    const changed = applyOpsToCtx(ctx, changes)
-
-    // React to specific top-level changes
-    if (changed.has('state')) {
-      const route = ctx.state?.route
-      if (route) {
-        el.call(
-          'router',
-          route.replace('/state', '') || '/',
-          el.__ref.root,
-          {},
-          { scrollToTop: false }
-        )
-      } else {
-        s.update(ctx.state)
-      }
-    }
-
-    if (
-      ['pages', 'components', 'snippets', 'functions'].some((k) =>
-        changed.has(k)
-      )
-    ) {
-      const { pathname, search, hash } = ctx.window.location
-      el.call(
-        'router',
-        pathname + search + hash,
-        el.__ref.root,
-        {},
-        { scrollToTop: false }
-      )
-    }
-
-    if (changed.has('designSystem')) {
-      init(ctx.designSystem)
-    }
-  }
+/**
+ * Wire the shared applier handlers onto a connected socket. Used by both
+ * collab and runner transports so the snapshot/ops protocol is uniform.
+ */
+const attachApplier = (socket, el, s, ctx) => {
+  socket.on('snapshot', onSnapshot(el, s, ctx))
+  socket.on('ops', onOps(el, s, ctx))
+  socket.on('clients', (data) => {
+    if (ctx.editor?.verbose) connectedToSymbols(data, el, s)
+  })
+  socket.on('disconnect', (reason) => {
+    if (ctx.editor?.verbose) console.info('[sync] disconnected', reason)
+  })
+}
 
-export const connectToSocket = async (el, s, ctx) => {
-  const token = await fetchServiceToken()
+const connectCollab = async (el, s, ctx, baseUrl) => {
+  const token = await fetchServiceToken(baseUrl)
   if (!token) {
-    console.warn('[sync] No service token – live collaboration disabled')
+    console.warn('[sync] no service token — collab disabled')
     return null
   }
-
   const projectKey = ctx.key
   if (!projectKey) {
-    console.warn(
-      '[sync] ctx.key missing – cannot establish collaborative connection'
-    )
+    console.warn('[sync] ctx.key missing — collab cannot authenticate')
     return null
   }
+  // The server prefers `projectId` (mongo _id) over `projectKey` lookup;
+  // mermaid injects it via `editor.projectId` to skip a 404-prone roundtrip.
+  const projectId = ctx.editor?.projectId || null
 
-  const socketBaseUrl = isLocal
-    ? 'http://localhost:8080'
-    : 'https://api.symbols.app'
-
-  const socket = io(socketBaseUrl, {
+  const socket = io(baseUrl, {
     path: '/collab-socket',
     transports: ['websocket'],
     auth: {
       token,
+      projectId,
       projectKey,
       branch: 'main',
       live: true,
@@ -224,33 +133,126 @@ export const connectToSocket = async (el, s, ctx) => {
   })
 
   socket.on('connect', () => {
-    if (ctx.editor?.verbose) {
-      console.info('[sync] Connected to collab socket')
-    }
+    if (ctx.editor?.verbose) console.info('[sync] connected (collab)')
   })
+  attachApplier(socket, el, s, ctx)
+  return socket
+}
 
-  socket.on('snapshot', onSnapshot(el, s, ctx))
-  socket.on('ops', onOps(el, s, ctx))
-
-  socket.on('clients', (data) => {
-    if (ctx.editor?.verbose) {
-      connectedToSymbols(data, el, s)
-    }
+const connectRunner = (el, s, ctx) => {
+  // Same-origin /socket.io (default path), no auth — the runner is a
+  // local-only dev surface. Auto-reconnect so a server restart doesn't
+  // require a browser refresh.
+  const socket = io({
+    transports: ['websocket', 'polling'],
+    reconnectionAttempts: Infinity,
+    reconnectionDelayMax: 4000
   })
-
-  socket.on('disconnect', (reason) => {
-    if (ctx.editor?.verbose) {
-      console.info('[sync] Disconnected from collab socket', reason)
+  socket.on('connect', () => {
+    if (ctx.editor?.verbose !== false) console.info('[sync] connected (runner)')
+  })
+  attachApplier(socket, el, s, ctx)
+  // Runner emits `reload` when something the wire format can't express
+  // changes (importmap shift, add/remove of dependencies). The browser
+  // must do a full reload to pick up the new HTML scaffold.
+  socket.on('reload', () => {
+    if (typeof window !== 'undefined' && window.location) {
+      window.location.reload()
     }
   })
-
   return socket
 }
 
+export const connectToSocket = async (el, s, ctx) => {
+  const { mode, baseUrl } = detectTransport(ctx)
+  if (!mode) return null
+  if (mode === 'collab') return connectCollab(el, s, ctx, baseUrl)
+  if (mode === 'runner') return connectRunner(el, s, ctx)
+  return null
+}
+
+// `onInitSync` was a custom lifecycle name that v3.14 never actually fires —
+// `initSync` is registered in LIFECYCLE_EVENTS but no code triggers it, so the
+// handler stayed dead and the realtime socket never opened on deployed pages.
+// `onInit` is a fired root-element lifecycle: when SyncComponent is pushed
+// into the app's `extends` (only on the root by initializeSync), this runs
+// once at app boot and connects to the collab/mermaid backend.
 export const SyncComponent = {
-  onInitSync: connectToSocket
+  onInit: connectToSocket
 }
 
+// `Inspect` moved to `@symbo.ls/inspect`. Compose it manually if you want
+// the legacy DefaultSyncApp shape:
+//   import { Inspect } from '@symbo.ls/inspect'
+//   const DefaultApp = { extends: [SyncComponent, Inspect, Notifications] }
 export const DefaultSyncApp = {
-  extends: [SyncComponent, Inspect, Notifications]
+  extends: [SyncComponent, Notifications]
+}
+
+const isUndef = (v) => typeof v === 'undefined'
+const hasCollab = (ctx) => !!(ctx?.editor?.socketUrl || ctx?.settings?.socketUrl)
+const hasRunner = (ctx) => ctx?.editor?.runtime === 'runner'
+
+const attachExtend = (app, component) => {
+  if (Array.isArray(app.extends)) app.extends.push(component)
+  else if (app.extends) app.extends = [app.extends, component]
+  else app.extends = [component]
+}
+
+/**
+ * @symbo.ls/sync as a regular smbls plugin. Auto-registered by
+ * `prepareContext` in `packages/smbls/src/createDomql.js` (default-on);
+ * users opt out by setting `context.sync = false` or by removing it from
+ * `context.plugins` before calling `Smbls.create(...)`.
+ *
+ * The `beforeCreate(app, ctx)` lifecycle runs after `initializeExtend`
+ * has set the root `app.extends` array but before DOMQL element creation,
+ * so attaching SyncComponent here causes its `onInit` to fire as a normal
+ * root-element lifecycle event against the resolved app — no window
+ * globals, no Promise race.
+ */
+export const syncPlugin = {
+  name: 'sync',
+  beforeCreate (app, ctx) {
+    const editor = ctx && ctx.editor
+
+    // Precedence:
+    //   explicit editor.liveSync → wins
+    //   else: editor.socketUrl (collab) OR editor.runtime === 'runner'
+    //   else: off (production / static dist)
+    const liveSync = editor && !isUndef(editor.liveSync)
+      ? editor.liveSync
+      : (hasCollab(ctx) || hasRunner(ctx))
+    if (!liveSync) return
+
+    // Collab transport requires ctx.key for socket auth. Runner doesn't.
+    if (hasCollab(ctx) && !hasRunner(ctx) && !ctx?.key) return
+
+    attachExtend(app, SyncComponent)
+  }
+}
+
+/**
+ * Notifications overlay (toast stack at bottom-left). Visualises sync
+ * connect/disconnect events surfaced by `connectedToSymbols`. Lives in
+ * `@symbo.ls/sync` rather than its own package because the helper that
+ * fires notifications is owned by sync's collab transport.
+ *
+ * Auto-registered by `prepareContext` only when the user opts in
+ * (default OFF). Two opt-in shapes for backwards compatibility:
+ *   1. `context.notifications = true` (preferred — same shape as
+ *      `context.sync` / `context.inspect`)
+ *   2. `context.editor.verbose = true` (legacy — historic behaviour
+ *      where auto-on-in-dev also turned this on)
+ */
+export const notificationsPlugin = {
+  name: 'notifications',
+  beforeCreate (app, ctx) {
+    if (!ctx) return
+    const explicit = !isUndef(ctx.notifications) ? ctx.notifications : null
+    const editorVerbose = ctx.editor && ctx.editor.verbose === true
+    const enabled = explicit === true || (explicit !== false && editorVerbose)
+    if (!enabled) return
+    attachExtend(app, Notifications)
+  }
 }