@symbo.ls/mermaid 3.14.1 → 3.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mermaid",
-  "version": "3.14.1",
+  "version": "3.14.4",
   "type": "module",
   "license": "CC-BY-NC-4.0",
   "description": "Self-sustaining server runner for Symbols projects from JSON. Renders DOMQL projects to HTML with optional brender SSR.",
@@ -29,7 +29,7 @@
     "mermaid": "./bin/start.js"
   },
   "dependencies": {
-    "@symbo.ls/utils": "^3.14.0",
+    "@symbo.ls/utils": "^3.14.2",
     "cors": "^2.8.5",
     "express": "^4.21.2"
   },

package/src/bundle.js

@@ -6,6 +6,15 @@ import smblsIife from 'smbls/iife-string';
 
 log.debug(`[BUNDLE] smbls IIFE loaded from smbls/iife-string (${smblsIife.length} bytes)`);
 
+// FRAMEWORK-6: any `<` in JSON that gets inlined into a `<script>` block can
+// terminate the wrapper (`</script>`) or trigger HTML-comment / CDATA modes
+// (`<!--`, `<![CDATA[`) inside the script-data state. Replacing every `<`
+// with the JS unicode escape `<` neutralizes HTML interpretation while
+// preserving the runtime string value — `<` decodes to `<` at JS parse
+// time, so the embedded object is identical to the original. Standard
+// mitigation: see OWASP §RULE-3.1, React's renderToString, Rails json_escape.
+const escapeJsonForScript = (s) => s.replace(/</g, '\\u003c');
+
 export function getSmblsIife() {
   return smblsIife;
 }
@@ -45,8 +54,10 @@ export function getBundleScript(appKey, data, req, { ProjectDataService } = {})
     log.error(`[BUNDLE] Failed to ensure merged data: ${mergeError.message}`);
   }
 
-  // Serialize the project data as JSON (same as templates __mockedData approach)
-  const jsonData = JSON.stringify(data);
+  // Serialize the project data as JSON (same as templates __mockedData approach).
+  // escapeJsonForScript: see FRAMEWORK-6 — any `</script>` (or `<!--`) inside a
+  // string value would break out of the inline `<script>` wrapper.
+  const jsonData = escapeJsonForScript(JSON.stringify(data));
 
   /*
    * Determine liveSync setting.
@@ -93,13 +104,13 @@ export function getBundleScript(appKey, data, req, { ProjectDataService } = {})
     (data && (data._id || data.projectId || data.id)) ||
     null;
   const settingsStr = isSymboLs
-    ? JSON.stringify({
+    ? escapeJsonForScript(JSON.stringify({
         ...data.settings,
         liveSync: !shouldDisableLiveSync,
         inspect: true,
         verbose: !shouldDisableLiveSync,
         projectId,
-      })
+      }))
     : 'null';
 
   // Generate the client script - same pattern as templates/start.js runFromJson
@@ -124,23 +135,55 @@ export function getBundleScript(appKey, data, req, { ProjectDataService } = {})
     var settings = ${settingsStr};
     if (settings) context.editor = settings;
 
-    // When brender pre-rendered this page, adopt the existing DOM nodes
-    // instead of tearing them down. The [data-ssr] wrapper is moved out of the
-    // way so pre-rendered children land at document.body level — matching the
-    // level at which DOMQL creates its own elements. The __BRENDER__ flag and
-    // __BR_REGISTRY__ map were injected into <head> by the server.
     // Theme initialization: set data-theme before app renders to avoid FOUC.
-    // 'auto' means "follow OS preference" — resolve through matchMedia and
-    // emit the concrete light/dark value. Writing the literal "auto" string
-    // would leave [data-theme="dark"] / [data-theme="light"] selectors
-    // unmatched + the page would render with system-default colors instead
-    // of the chosen theme. Matches resolveAndApplyTheme in smbls/src/index.js.
-    if (context.useDocumentTheme !== false) {
+    // Mirrors the precedence in resolveAndApplyTheme (packages/smbls/src/index.js):
+    //   1. URL param ?globalTheme=<name>           — embedded-iframe override
+    //   2. localStorage[themeStorageKey]           — persisted user choice
+    //   3. context.globalTheme                     — project's configured value
+    //   4. matchMedia(prefers-color-scheme: dark)  — OS fallback (when 'auto')
+    //
+    // Writing the literal 'auto' as data-theme would leave the
+    // [data-theme="dark"] / [data-theme="light"] CSS selectors unmatched and
+    // the page would render with system defaults instead of the chosen
+    // theme — so 'auto' is always resolved to a concrete light/dark value.
+    //
+    // PRIOR BUG: this script previously ignored context.globalTheme entirely
+    // and went straight to matchMedia after localStorage. A project with
+    // globalTheme: light in config.js would render in OS dark on a
+    // dark-mode device because the inline boot ran first and locked in
+    // dark before resolveAndApplyTheme could correct it.
+    //
+    // IDEMPOTENT GUARD: the SSR-side render in @symbo.ls/mermaid/render.js
+    // now bakes data-theme onto <html> for concrete-theme projects and
+    // emits an inline <head> script that runs synchronously before paint.
+    // When that path runs, data-theme is already set by the time the bundle
+    // executes — skip this block to avoid re-resolving and overwriting
+    // (which would race with URL/localStorage values the head script
+    // already honored). Kept as a safety net for older renders / cases
+    // where the head script couldn't run.
+    if (
+      context.useDocumentTheme !== false &&
+      !document.documentElement.hasAttribute('data-theme')
+    ) {
       (function() {
         try {
           var t = null;
-          var key = context.themeStorageKey;
-          if (key) { try { t = localStorage.getItem(key) } catch(e) {} }
+          // 1. URL param wins (used by preview/canvas iframe embedding).
+          try {
+            var p = new URLSearchParams(window.location.search).get('globalTheme');
+            if (p) t = p;
+          } catch(e) {}
+          // 2. localStorage — only consulted when no forcing source above.
+          if (!t) {
+            var key = context.themeStorageKey;
+            if (key) { try { t = localStorage.getItem(key) } catch(e) {} }
+          }
+          // 3. Project's configured globalTheme (config.js export). Honors an
+          // explicit 'light'/'dark'/<scheme> instead of falling through to OS.
+          if (!t && context.globalTheme && context.globalTheme !== 'auto') {
+            t = context.globalTheme;
+          }
+          // 4. OS preference fallback — only when nothing concrete chose.
           if (!t || t === 'auto') {
             t = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
           }
@@ -149,6 +192,11 @@ export function getBundleScript(appKey, data, req, { ProjectDataService } = {})
       })();
     }
 
+    // When brender pre-rendered this page, adopt the existing DOM nodes
+    // instead of tearing them down. The [data-ssr] wrapper is moved out of
+    // the way so pre-rendered children land at document.body level — matching
+    // the level at which DOMQL creates its own elements. The __BRENDER__ flag
+    // and __BR_REGISTRY__ map were injected into <head> by the server.
     var ssrShell = document.querySelector('[data-ssr]');
     if (window.__BRENDER__ && ssrShell) {
       // Move pre-rendered children to body before DOMQL skeleton creation

package/src/render.js

@@ -37,12 +37,22 @@ export { generateSitemap, prefetchPageData };
 // ── Default HTML template ───────────────────────────────────────────────────
 // Inlined so the plugin works in any runtime (Node, CF Workers, browser).
 // Mirrors src/template.html — keep in sync.
+//
+// ROOT_ATTRS + HEAD_BOOT eliminate the FOUC that used to happen between
+// HTML-parse-finish and the end-of-body bundle IIFE running (~1s on a
+// 2.5 MB bundle). For projects with a concrete `globalTheme` (e.g. 'light'),
+// SSR bakes `<html data-theme="light">` so first paint is on the right
+// theme. For 'auto' projects, the inline HEAD_BOOT script resolves URL
+// override / localStorage / matchMedia synchronously before any CSS
+// applies. The end-of-body IIFE in bundle.js is kept as an idempotent
+// safety net.
 export const DEFAULT_TEMPLATE_HTML = `<!doctype html>
-<html>
+<html'\${{{ ROOT_ATTRS }}}'>
   <head>
+    <meta charset="UTF-8" />
+    '\${{{ HEAD_BOOT }}}'
     '\${{{ META }}}'
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta charset="UTF-8" />
     '\${{{ IMPORTMAP }}}'
   </head>
   <body>
@@ -113,7 +123,12 @@ export function transpileFunctionStrings(obj, target = Array.isArray(obj) ? [] :
  * @param {object} options
  * @param {string} options.appkey — appkey identifier (for metadata, comments)
  * @param {string} options.pathname — request pathname
- * @param {string} [options.channel='production'] — 'production' | 'staging' | 'development'
+ * @param {string} [options.channel='production'] — sysEnv label (production|upcoming|next|...);
+ *   informational, used for metadata. NOT the same axis as userEnv — sysEnv is which
+ *   deployment served the request, userEnv is which version of project content.
+ * @param {string} [options.userEnv='production'] — projectEnv (production|staging|development|...);
+ *   drives the SSR-vs-CSR decision and the `<!-- symbols | … -->` comment. Defaults
+ *   to channel for back-compat with callers that haven't been updated.
  * @param {boolean} [options.isProd=false] — controls SEO indexing (custom domains only)
  * @param {object} [options.req] — full request object (Express-like) for getBundleScript context
  * @param {object} [options.query] — query params (when no req available)
@@ -131,6 +146,7 @@ export async function renderProjectHtml(data, options = {}) {
     appkey,
     pathname = '/',
     channel = 'production',
+    userEnv = channel,
     isProd = false,
     req,
     query,
@@ -156,7 +172,12 @@ export async function renderProjectHtml(data, options = {}) {
 
   const route = normalizeRoute(pathname);
   const resolved = resolvePageRoute(data.pages, pathname);
-  const shouldBrender = channel === 'production' || channel === 'staging';
+  // SSR is a projectEnv decision — render published (production) and pre-published
+  // (staging) slots server-side; render dev slot client-side. Was previously
+  // checking `channel` (sysEnv), which gave wrong answers on canonical hosts
+  // like *.upcoming.symbo.ls (sysEnv=upcoming, userEnv=production → was CSR
+  // when it should have been SSR).
+  const shouldBrender = userEnv === 'production' || userEnv === 'staging';
 
   // ── Brender / SSR ─────────────────────────────────────────────────────────
   let prerenderedBody = '';
@@ -359,13 +380,68 @@ export async function renderProjectHtml(data, options = {}) {
     ? `<script defer type="text/javascript">${editorBundle}</script>`
     : '';
 
+  // Comment label is the projectEnv (which version of the content is being
+  // served). Was previously `${channel}` (sysEnv) which mislabelled canonical
+  // *.upcoming.symbo.ls hosts as "upcoming" when the actual projectEnv is
+  // "production".
   const envComment = isProd
     ? `<!-- built with symbols.app -->\n`
-    : `<!-- symbols | ${appkey} | ${channel} | ${shouldBrender ? 'ssr' : 'csr'} | noindex -->\n`;
+    : `<!-- symbols | ${appkey} | ${userEnv} | ${shouldBrender ? 'ssr' : 'csr'} | noindex -->\n`;
+
+  // ── Theme: zero-flash boot ─────────────────────────────────────────────────
+  // Eliminates the dark→light (or light→dark) flash that used to happen
+  // between first paint and the end-of-body bundle IIFE setting data-theme.
+  // Two layers:
+  //   1. Concrete `globalTheme` ('light'|'dark'|<custom>) → bake `data-theme`
+  //      onto <html> server-side. Zero JS, perfect first paint.
+  //   2. URL ?globalTheme= override / localStorage user choice / 'auto' OS
+  //      pref → small inline <head> script resolves synchronously before
+  //      any CSS applies. Browser renders first paint with the resolved
+  //      data-theme, no flash.
+  // Layer 3 (existing end-of-body IIFE in bundle.js) is the back-compat
+  // safety net for cases the head script didn't reach.
+  const useDocumentTheme = data.useDocumentTheme !== false;
+  const concreteTheme =
+    data.globalTheme && data.globalTheme !== 'auto' ? String(data.globalTheme) : null;
+  const themeStorageKey = data.themeStorageKey ? String(data.themeStorageKey) : '';
+
+  // SSR-baked attribute on <html>. Only when the project has a concrete
+  // theme — for 'auto' we leave <html> bare so the head script (or
+  // CSS @media) can decide. Custom schemes (e.g. 'ocean') flow through.
+  const rootAttrs =
+    useDocumentTheme && concreteTheme ? ' data-theme="' + concreteTheme + '"' : '';
+
+  // Inline head boot. Runs synchronously during HTML parse, before any
+  // CSS applies. Order matches resolveAndApplyTheme in
+  // smbls/packages/smbls/src/index.js:
+  //   1. ?globalTheme= URL param  (preview/editor iframes push themes here)
+  //   2. localStorage[themeStorageKey]  (persisted user toggle)
+  //   3. concreteTheme baked from project config (for 'auto' projects this
+  //      is null and we fall to step 4)
+  //   4. matchMedia(prefers-color-scheme: dark) — OS fallback
+  // Skipped entirely when useDocumentTheme is false.
+  const headBoot = useDocumentTheme
+    ? '<script>(function(){try{var t=null;' +
+      "try{t=new URLSearchParams(location.search).get('globalTheme')}catch(e){}" +
+      (themeStorageKey
+        ? 'if(!t){try{t=localStorage.getItem(' +
+          JSON.stringify(themeStorageKey) +
+          ')}catch(e){}}'
+        : '') +
+      "if(!t||t==='auto'){" +
+      (concreteTheme
+        ? 't=' + JSON.stringify(concreteTheme) + ';'
+        : "try{t=window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light'}catch(e){}") +
+      '}' +
+      "if(t&&t!=='auto')document.documentElement.setAttribute('data-theme',t);" +
+      '}catch(e){}})();</script>\n    <meta name="color-scheme" content="light dark">'
+    : '';
 
   const html = replaceVariablesInFileSync(
     envComment + indexHtml,
     {
+      ROOT_ATTRS: rootAttrs,
+      HEAD_BOOT: headBoot,
       META: metaTags + '\n' + brenderStyles + '\n' + hydrationScript + '\n' + authScript,
       BUNDLE: bundle,
       BODY: prerenderedBody,

package/src/template.html

@@ -1,9 +1,10 @@
 <!doctype html>
-<html>
+<html'${{{ ROOT_ATTRS }}}'>
   <head>
+    <meta charset="UTF-8" />
+    '${{{ HEAD_BOOT }}}'
     '${{{ META }}}'
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta charset="UTF-8" />
     '${{{ IMPORTMAP }}}'
   </head>
   <body>