smbls 3.14.0 → 3.14.2

package/dist/cjs/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "main": "index.js"
+}

package/index.js

@@ -1,8 +1,8 @@
 'use strict'
 
-// v4 entry point - re-exports all framework packages
+// v3.14 entry point - re-exports all framework packages
 
-// Core v4 primitives (NEW)
+// Core v3.14 primitives (NEW)
 export * from '@symbo.ls/signal'
 export * from '@symbo.ls/css'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smbls",
-  "version": "3.14.0",
+  "version": "3.14.2",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "module": "./index.js",
@@ -20,6 +20,7 @@
     "src"
   ],
   "dependencies": {
+    "@symbo.ls/analyze": "^3.14.0",
     "@symbo.ls/signal": "^3.14.0",
     "@symbo.ls/element": "^3.14.0",
     "@symbo.ls/state": "^3.14.0",

package/src/createDomql.js

@@ -4,14 +4,10 @@ import { create as createElement } from '@symbo.ls/element'
 import * as uikit from '@symbo.ls/default-config/components'
 import { CSS_PROPS_REGISTRY } from 'css-in-props'
 
-import { isString, isNode, isObject, destringifyGlobalScope, deepDestringifyFunctions } from '@symbo.ls/utils'
+import { isString, isNode, isObject, destringifyGlobalScope, deepDestringifyFunctions, setActiveRootState } from '@symbo.ls/utils'
 import { defaultDefine } from './define.js'
 import { initRouter } from './router.js'
-import {
-  initializeExtend,
-  initializeNotifications,
-  initializeSync
-} from './syncExtend.js'
+import { initializeExtend } from './syncExtend.js'
 
 import {
   prepareComponents,
@@ -34,6 +30,8 @@ import { fetchPlugin } from '@symbo.ls/fetch'
 import { capsizePlugin, capsizeHandler } from '@symbo.ls/capsize'
 import { shorthandPlugin } from '@symbo.ls/shorthand'
 import { analyzePlugin, createAnalyzeState } from '@symbo.ls/analyze'
+import { syncPlugin, notificationsPlugin } from '@symbo.ls/sync'
+import { inspectPlugin } from '@symbo.ls/inspect'
 
 // hydrate utilities available for future true-hydration opt-in
 // import { hydrate, assignBrKeysFromRegistry } from './hydrate.js'
@@ -77,6 +75,12 @@ export const prepareContext = async (app, context = {}) => {
 
   const state = prepareState(app, context)
   context.state = state
+  // Register the active root state in the framework registry so
+  // `getRootState()` (called without `this`) can find it during early
+  // render. Eliminates the requirement that projects pre-set
+  // `window.smblsApp = { state }` in their `index.js` — the runner
+  // bypasses project-side index.js entirely, and now no longer needs to.
+  setActiveRootState(state)
   context.pages = preparePages(app, context)
   context.components = prepareComponents(context)
   context.utils = prepareUtils(context)
@@ -104,7 +108,7 @@ export const prepareContext = async (app, context = {}) => {
   // nominal type — invalid CSS for `transform`, dead listeners for
   // `onClick`, raw source code shown for `text`, etc. — which is the root
   // cause of every "works on dev / dead on remote" divergence we've ever
-  // seen for v4 published projects. Walks the same buckets prepareContext
+  // seen for v3.14 published projects. Walks the same buckets prepareContext
   // populated above, mutating each into a tree where every detectable
   // function-string has been `eval`'d back to a real function.
   // ESM-namespace-shaped buckets (`import * as functions from ...`) have
@@ -170,6 +174,36 @@ export const prepareContext = async (app, context = {}) => {
     context.plugins.push(analyzePlugin)
   }
 
+  // Sync plugin — HMR module for both transports (mermaid-served collab and
+  // runner-served local). Plugged ON by default; users opt out by setting
+  // `context.sync = false` (or `editor.liveSync = false`) or by removing
+  // syncPlugin from `context.plugins` before calling `create()`. With
+  // `context.sync = false` the plugin is never pushed, so SyncComponent
+  // never reaches `app.extends` and no socket connection is attempted.
+  if (context.sync !== false && !hasPlugin('sync')) {
+    context.plugins.push(syncPlugin)
+  }
+
+  // Inspect plugin — element inspector overlay. Default OFF. Opt-in by
+  // setting `context.inspect = true` (or a config object) — this auto-
+  // registers the plugin which adds Alt+Shift highlight + click capture.
+  // See `@symbo.ls/inspect` README for the shortcut + `editor.onInspect`
+  // callback contract.
+  if (context.inspect && !hasPlugin('inspect')) {
+    context.plugins.push(inspectPlugin)
+  }
+
+  // Notifications plugin — toast overlay for sync connect/disconnect.
+  // Default OFF. Opt-in via `context.notifications = true` (or the
+  // legacy `editor.verbose = true` for backwards compat). Plugin's
+  // beforeCreate filters again so flipping `context.notifications =
+  // false` short-circuits even if the plugin is pushed manually.
+  const notificationsOptIn = context.notifications === true ||
+    (context.editor && context.editor.verbose === true)
+  if (notificationsOptIn && context.notifications !== false && !hasPlugin('notifications')) {
+    context.plugins.push(notificationsPlugin)
+  }
+
   return context
 }
 
@@ -242,8 +276,20 @@ export const createDomqlElement = async (app, ctx) => {
     )
   }
 
-  initializeSync(app, ctx)
-  initializeNotifications(app, ctx)
+  // Run plugin `beforeCreate` lifecycle. All sync/notifications/inspect
+  // injection happens here — the framework knows nothing about which
+  // plugins run. Remove the relevant plugin from `ctx.plugins` (or set
+  // `context.sync = false` / `context.inspect = false` / etc) and no
+  // attach happens.
+  for (const plugin of ctx.plugins) {
+    if (typeof plugin.beforeCreate === 'function') {
+      try {
+        plugin.beforeCreate(app, ctx)
+      } catch (err) {
+        console.error(`[smbls] plugin "${plugin.name || '?'}" beforeCreate error:`, err)
+      }
+    }
+  }
 
   const doc = ctx.document
   if (!doc || !doc.createElement) return app
@@ -254,7 +300,7 @@ export const createDomqlElement = async (app, ctx) => {
     return fallbackRender(createElement, app, parentNode, ctx, win, ssrStyles)
   }
 
-  // v4: use @symbo.ls/element create directly
+  // v3.14: use @symbo.ls/element create directly
   const smblsApp = createElement(app, parentNode, ctx.key, {
     verbose: ctx.verbose,
     context: ctx,

package/src/hydrate.js

@@ -436,7 +436,7 @@ const bindEvents = (el) => {
 
   if (!el.__ref.__eventCleanup) el.__ref.__eventCleanup = []
 
-  // v4: event handlers are flat on element as onX properties
+  // v3.14: event handlers are flat on element as onX properties
   for (const key in el) {
     if (key.length <= 2 || key[0] !== 'o' || key[1] !== 'n') continue
     if (typeof el[key] !== 'function') continue

package/src/index.js

@@ -81,6 +81,36 @@ const resolveAndApplyTheme = (options) => {
   options.themeRoot = scopeRoot
 }
 
+// Read `<meta name="symbols-runtime" content="...">` from the served
+// document. This is how the runner signals its mode to the framework
+// without a window global — it injects the meta tag into the served
+// HTML, the framework reads it once at create() time and stamps the
+// matching `editor.runtime` so syncPlugin (and anyone else who cares)
+// can detect runner mode via context.
+const readRuntimeMeta = () => {
+  if (typeof document === 'undefined') return null
+  try {
+    const m = document.querySelector('meta[name="symbols-runtime"]')
+    const v = m && m.getAttribute('content')
+    return (typeof v === 'string' && v) ? v : null
+  } catch (_) {
+    return null
+  }
+}
+
+const stampRuntimeFromMeta = (options) => {
+  const runtime = readRuntimeMeta()
+  if (!runtime) return
+  if (!options.editor) options.editor = {}
+  // Don't clobber an explicit project setting — projects can override
+  // by setting `editor.runtime` themselves before calling create.
+  if (!options.editor.runtime) options.editor.runtime = runtime
+  // Default livesync on for runner mode unless the project disabled it.
+  if (runtime === 'runner' && typeof options.editor.livesync === 'undefined') {
+    options.editor.livesync = true
+  }
+}
+
 export const create = (
   App,
   options = DEFAULT_CREATE_OPTIONS,
@@ -91,6 +121,11 @@ export const create = (
     ...mergeWithLocalFile(options, optionsExternalFile)
   }
 
+  // Pick up runner-mode (or any future runtime tag) from the served HTML.
+  // Has to happen before `createDomqlElement` so syncPlugin's beforeCreate
+  // sees the stamped editor.runtime.
+  stampRuntimeFromMeta(redefinedOptions)
+
   // Resolve the active theme synchronously, before the async init chain,
   // and write `data-theme` to the scope's root element. This gives the
   // first paint the correct theme — no project-side setAttribute hack,
@@ -151,6 +186,12 @@ export const createSync = async (
     ...mergeWithLocalFile(options, optionsExternalFile)
   }
 
+  // Pick up runner-mode from the served HTML's meta tag — same path
+  // `create` uses. Required because projects often boot via createSync
+  // (e.g. starter-kit, docs/developers) and the runner needs to detect
+  // its mode regardless of which entry point the project chose.
+  stampRuntimeFromMeta(redefinedOptions)
+
   // const SYMBOLS_KEY = process.env.SYMBOLS_KEY
   const key = options.key
   await fetchSync(key, redefinedOptions)
@@ -195,3 +236,10 @@ export { defaultDefine, createDefine } from './define.js'
 // Polyglot i18n plugin
 export { polyglotPlugin, translate, setLang, getActiveLang, getLanguages, loadTranslations, upsertTranslation, initPolyglot, getLocalStateLang } from '@symbo.ls/polyglot'
 export { polyglotFunctions } from '@symbo.ls/polyglot/functions'
+
+// Theme switching — exposed on the IIFE bundle so project code can call
+// `Smbls.changeGlobalTheme('dark')` from within serialized handlers
+// (mermaid SSR runtime). Without an explicit re-export here, the bundler
+// tree-shakes the symbol out of dist/iife/index.js because nothing in the
+// smbls/src tree calls it directly.
+export { changeGlobalTheme } from '@symbo.ls/scratch'

package/src/prepare.js

@@ -18,7 +18,12 @@ import { init } from './init.js'
 import { getActiveConfig, createConfig, pushConfig, popConfig } from '@symbo.ls/scratch'
 import { DEFAULT_CONTEXT } from './options.js'
 
-import * as uikit from '@symbo.ls/default-config/components'
+// FT-FRAMEWORK-1: source from the explicit COMPONENTS manifest, not from
+// `import * as uikit`. Parcel under `sideEffects: false` was pruning entries
+// off the namespace import — projects ended up with atoms missing from
+// `context.components`. The manifest is a plain object literal so the
+// bundler can't mistake any entry for an unused import.
+import { COMPONENTS as uikit } from '@symbo.ls/default-config/components'
 import * as utils from './utilImports.js'
 import * as routerUtils from '@symbo.ls/router'
 
@@ -472,10 +477,15 @@ export const prepareState = (app, context) => {
   // Merge polyglot translations for active language into state
   const poly = context.polyglot
   if (poly?.translations) {
-    // Check localStorage for persisted language preference
-    const storedLang = typeof localStorage !== 'undefined'
-      ? (localStorage.getItem(poly.storageLangKey || 'smbls_lang') || localStorage.getItem('lang'))
-      : null
+    // Check localStorage for persisted language preference. Wrap the
+    // access — sandboxed iframes / Firefox storage-disabled mode throw on
+    // .getItem(), not just on .setItem().
+    let storedLang = null
+    try {
+      if (typeof localStorage !== 'undefined') {
+        storedLang = localStorage.getItem(poly.storageLangKey || 'smbls_lang') || localStorage.getItem('lang')
+      }
+    } catch (e) {}
     const lang = storedLang || state.lang || poly.defaultLang || 'en'
     if (storedLang && storedLang !== state.lang) state.lang = storedLang
     const langT = poly.translations[lang]

package/src/syncExtend.js

@@ -1,50 +1,17 @@
 'use strict'
 
-import { isObjectLike, isUndefined, isDevelopment, isArray } from '@symbo.ls/utils'
-import { SyncComponent, Inspect, Notifications } from '@symbo.ls/sync'
+import { isObjectLike } from '@symbo.ls/utils'
+
+// All sync-related auto-injection moved to plugins:
+//   - `syncPlugin` (HMR)            in `@symbo.ls/sync`
+//   - `notificationsPlugin` (toasts) in `@symbo.ls/sync`
+//   - `inspectPlugin` (overlay)      in `@symbo.ls/inspect`
+// The framework registers them through the generic `context.plugins`
+// mechanism in `prepareContext` (`./createDomql.js`). This file only
+// exposes the lone helper that survived: `initializeExtend`, which
+// normalises `app.extends` to an array before any plugin's
+// `beforeCreate` runs.
 
 export const initializeExtend = (app, ctx) => {
   return isObjectLike(app.extends) ? app.extends : []
 }
-
-export const initializeSync = (app, ctx) => {
-  const { editor } = ctx
-  if (!editor) return
-  const liveSync = isUndefined(editor.liveSync) ? isDevelopment() : editor.liveSync
-  if (liveSync) {
-    if (isArray(app.extends)) app.extends.push(SyncComponent)
-    else if (app.extends) {
-      app.extends = [app.extends, SyncComponent]
-    } else {
-      app.extends = [SyncComponent]
-    }
-  }
-}
-
-export const initializeInspect = (app, ctx) => {
-  const { editor } = ctx
-  if (!editor) return
-  const inspect = isUndefined(editor.inspect) ? isDevelopment() : editor.inspect
-  if (inspect) {
-    if (isArray(app.extends)) app.extends.push(Inspect)
-    else if (app.extends) {
-      app.extends = [app.extends, Inspect]
-    } else {
-      app.extends = [Inspect]
-    }
-  }
-}
-
-export const initializeNotifications = (app, ctx) => {
-  const { editor } = ctx
-  if (!editor) return
-  const verbose = isUndefined(editor.verbose) ? isDevelopment() || ctx.verbose : editor.verbose
-  if (verbose) {
-    if (isArray(app.extends)) app.extends.push(Notifications)
-    else if (app.extends) {
-      app.extends = [app.extends, Notifications]
-    } else {
-      app.extends = [Notifications]
-    }
-  }
-}