@symbo.ls/sync 3.14.9 → 3.14.11

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @symbo.ls/sync
 
+## 3.14.11
+
+### Patch Changes
+
+- Manual patch bump triggered via workflow_dispatch (scope: @symbo.ls).
+  No source change behind this bump — released to refresh dist or
+  coordinate a cross-package version line.
+- Updated dependencies
+  - @symbo.ls/default-config@3.14.15
+  - @symbo.ls/router@3.14.10
+  - @symbo.ls/scratch@3.14.13
+  - @symbo.ls/utils@3.14.15
+
+## 3.14.10
+
+### Patch Changes
+
+- Manual patch bump triggered via workflow_dispatch (scope: @symbo.ls).
+  No source change behind this bump — released to refresh dist or
+  coordinate a cross-package version line.
+- Updated dependencies
+  - @symbo.ls/default-config@3.14.12
+  - @symbo.ls/router@3.14.9
+  - @symbo.ls/scratch@3.14.10
+  - @symbo.ls/utils@3.14.11
+
 ## 3.14.9
 
 ### Patch Changes

package/SyncNotifications.js

@@ -0,0 +1,120 @@
+'use strict'
+
+// const ANIMATION = {
+//   fadeInUp: {
+//     from: {
+//       transform: 'translate3d(0, 12.5%, 1px)',
+//       opacity: 0
+//     },
+//     to: {
+//       transform: 'translate3d(0, 0, 1px)',
+//       opacity: 1
+//     }
+//   },
+//   fadeOutDown: {
+//     from: {
+//       transform: 'translate3d(0, 0, 1px)',
+//       opacity: 1
+//     },
+//     to: {
+//       transform: 'translate3d(0, 12.5%, 1px)',
+//       opacity: 0
+//     }
+//   }
+// }
+
+// const COLOR = {
+//   black: '#000000',
+//   blue: '#3686F7'
+// }
+
+// set({
+//   COLOR,
+//   ANIMATION
+// })
+
+const NOTIF_COLORS = {
+  success: 'green',
+  error: 'red',
+  warning: 'yellow'
+}
+
+export const connectedToSymbols = (clients, element, state) => {
+  if (clients.symbols) {
+    if (!state.connected) {
+      state.notifications.connected = {
+        title: 'Connected',
+        message: 'to the Symbols live server'
+      }
+
+      state.update({ connected: true })
+
+      const t = setTimeout(() => {
+        delete state.notifications.connected
+        element.notifications.content.connected.update({
+          animation: 'fadeOutDown'
+        })
+        state.update({ connected: true })
+        clearTimeout(t)
+      }, 3000)
+    }
+  } else {
+    if (state.connected) {
+      state.notifications.connected = {
+        title: 'Disconnected',
+        type: 'error'
+      }
+
+      state.update({ connected: false })
+
+      const t = setTimeout(() => {
+        delete state.notifications.connected
+        if (element.notifications.content.connected) {
+          element.notifications.content.connected.update({
+            animation: 'fadeOutDown'
+          })
+        }
+        state.update({ connected: true })
+        clearTimeout(t)
+      }, 3000)
+    }
+  }
+}
+
+export const Notifications = {
+  state: {
+    notifications: []
+  },
+
+  Notifications: {
+    position: 'fixed',
+    left: 'A2',
+    bottom: 'Z2',
+    zIndex: '999',
+    childExtends: 'Notification',
+    childProps: ({ state }) => ({
+      animationDuration: 'C',
+      background: NOTIF_COLORS[state.type || 'success'],
+      icon: null,
+      Flex: {
+        Title: {
+          text: '{{ title }}'
+        },
+        P: {
+          text: '{{ title }}'
+        }
+      },
+      onRender: (e, el, s) => {
+        el.update({ animation: 'fadeInUp' })
+      },
+      onClick: (e, el, s) => {
+        delete s.notifications[el.key]
+        el.update({ animation: 'fadeOutDown' })
+        if (s.onClose) s.onClose(e, el, s)
+      }
+    }),
+    IconText: null,
+    childrenAs: 'state',
+    children: ({ state }) => state.notifications
+  }
+}

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'
+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

@@ -0,0 +1,258 @@
+import { router } from '@symbo.ls/router'
+import { io } from 'socket.io-client'
+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'
+
+const defaultBaseUrl = () =>
+  isLocal ? 'http://localhost:8080' : 'https://api.symbols.app'
+
+/*
+ * 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 }
+  }
+  if (ctx && ctx.editor && ctx.editor.runtime === 'runner') {
+    return { mode: 'runner', baseUrl: null }
+  }
+  return { mode: null, baseUrl: null }
+}
+
+const fetchServiceToken = async (baseUrl) => {
+  try {
+    const urlBase = baseUrl || defaultBaseUrl()
+    const res = await window.fetch(`${urlBase}/service-token`, {
+      method: 'GET'
+    })
+
+    // Attempt to parse JSON first – recent versions return `{ token: "..." }`
+    // Fall back to treating the response as raw text for backward-compatibility.
+    let txt
+    try {
+      const json = await res.clone().json()
+      if (json && typeof json.token === 'string') {
+        return json.token.trim()
+      }
+      // If json parsing succeeds but no token field, fall back to text below.
+      txt = await res.text()
+    } catch {
+      // Response is not JSON – treat as plain text token.
+      txt = await res.text()
+    }
+
+    return (txt || '').replace(/\s+/gu, '') || void 0
+  } catch (e) {
+    console.error('[sync] Failed to fetch service-token', e)
+  }
+}
+
+/**
+ * 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)
+  })
+}
+
+const connectCollab = async (el, s, ctx, baseUrl) => {
+  const token = await fetchServiceToken(baseUrl)
+  if (!token) {
+    console.warn('[sync] no service token — collab disabled')
+    return null
+  }
+  const projectKey = ctx.key
+  if (!projectKey) {
+    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 socket = io(baseUrl, {
+    path: '/collab-socket',
+    transports: ['websocket'],
+    auth: {
+      token,
+      projectId,
+      projectKey,
+      branch: 'main',
+      live: true,
+      clientType: 'platform'
+    },
+    reconnectionAttempts: Infinity,
+    reconnectionDelayMax: 4000
+  })
+
+  socket.on('connect', () => {
+    if (ctx.editor?.verbose) console.info('[sync] connected (collab)')
+  })
+  attachApplier(socket, el, s, ctx)
+  return socket
+}
+
+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('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 = {
+  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, 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)
+  }
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@symbo.ls/sync",
-  "version": "3.14.9",
+  "version": "3.14.11",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "gitHead": "9fc1b79b41cdc725ca6b24aec64920a599634681",
   "files": [
     "dist",
+    "*.js",
     "*.md",
     "LICENSE"
   ],
@@ -44,10 +45,10 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@symbo.ls/router": "^3.14.8",
-    "@symbo.ls/utils": "^3.14.10",
-    "@symbo.ls/scratch": "^3.14.9",
-    "@symbo.ls/default-config": "^3.14.11",
+    "@symbo.ls/router": "^3.14.10",
+    "@symbo.ls/utils": "^3.14.15",
+    "@symbo.ls/scratch": "^3.14.13",
+    "@symbo.ls/default-config": "^3.14.15",
     "chalk": "^5.4.1",
     "socket.io-client": "^4.8.1"
   },