@symbo.ls/mermaid 3.14.0

package/README.md

@@ -0,0 +1,75 @@
+# @symbo.ls/mermaid
+
+Self-sustaining server runner for Symbols projects. Renders DOMQL projects from JSON to HTML, with optional [brender](../brender) SSR.
+
+Works in three modes:
+
+1. **Standalone** — `mermaid` CLI / `createMermaidApp({ jsonPath })` Express app
+2. **Pure render** — `renderProjectHtml(data, opts)` returns an HTML string in any runtime
+3. **Pluggable data source** — `createMermaidApp({ getProjectData })` lets you wire KV / API / DB
+
+For the production hosting service (Cloudflare Workers + KV/API + custom domains), see [@symbo.ls/mermaid-server](../../../server/packages/mermaid-server) which builds on top of this package.
+
+## Quick start
+
+```bash
+# Run a project from a local JSON file
+npx mermaid --json ./app.json
+# open http://localhost:3333
+
+# Or as a library
+node -e "import('@symbo.ls/mermaid').then(m => m.createMermaidApp({ jsonPath: './app.json' }).listen(3333))"
+```
+
+## API
+
+### `createMermaidApp(options)`
+
+Returns an Express application.
+
+| Option           | Type     | Description                                                           |
+| ---------------- | -------- | --------------------------------------------------------------------- |
+| `jsonPath`       | string   | Path to local JSON file (or directory containing `app.json`)          |
+| `appkeyOverride` | string   | Force a specific appkey for all requests                              |
+| `channel`        | string   | `production` (default) \| `staging` \| `development`                  |
+| `getProjectData` | function | `async (req, ctx) => { data, appkey?, channel?, isProd? }`            |
+| `cors`           | boolean  | Enable CORS middleware (default `true`)                               |
+| `editor`         | object   | `{ bundle: string }` to inject `@symbo.ls/preview-editor` in non-prod |
+
+### `renderProjectHtml(data, options)`
+
+Pure runtime-agnostic renderer. Returns `{ html, status, contentType }`.
+
+| Option                  | Type    | Description                                            |
+| ----------------------- | ------- | ------------------------------------------------------ |
+| `appkey`                | string  | identifier for metadata + comments                     |
+| `pathname`              | string  | request pathname                                       |
+| `channel`               | string  | `production` \| `staging` \| `development`             |
+| `isProd`                | boolean | controls SEO indexing (custom domains only)            |
+| `req`                   | object  | Express-like request (used by bundle context)          |
+| `userId`                | string  | injects `window.__SYMBOLS_AUTH__`                      |
+| `smblsIife`             | string  | preloaded smbls IIFE source (CF Workers / build-time)  |
+| `editorBundle`          | string  | preview-editor bundle to inject (non-prod only)        |
+| `analyzedScript`        | string  | analytics tracking `<script>` to inject                |
+| `indexHtml`             | string  | override the index.html template                       |
+| `ssrCache`              | object  | pre-computed SSR cache (skips runtime brender)         |
+| `ProjectDataService`    | object  | passed to `getBundleScript` for shared-library merging |
+
+### `loadJsonData(jsonPath)`
+
+Synchronously load and parse a project JSON file.
+
+### Other exports
+
+`renderNotPublishedHtml`, `transpileFunctionStrings`, `getBundleScript`, `getSmblsIife`, `normalizeRoute`, `resolvePageRoute`, `extractRouteParams`, `STATIC_EXT`, `deepDestringifyFunctions`, `stripFunctionStrings`, `generateSitemap` (if brender is available), `replaceVariablesInFileSync`, `transpileFuncql`.
+
+## Environment variables
+
+| Variable    | Default                            | Description                  |
+| ----------- | ---------------------------------- | ---------------------------- |
+| `PORT`      | `3333`                             | HTTP port (CLI only)         |
+| `JSON_PATH` | `./app.json`                       | JSON data path (CLI only)    |
+| `APPKEY`    | —                                  | Override appkey (CLI only)   |
+| `NODE_ENV`  | `development`                      | Channel selection            |
+| `LOG_LEVEL` | `debug` (dev) / `info` (prod)      | Log verbosity                |
+| `BRENDER`   | enabled                            | Set to `false` to skip SSR   |

package/bin/start.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * mermaid CLI — start a standalone Symbols project server from a JSON file.
+ *
+ *   mermaid                              # serve ./app.json on :3333
+ *   mermaid --json ./project-data.json   # custom JSON path
+ *   mermaid --port 4000                  # custom port
+ *   mermaid --appkey demo/site           # force a specific appkey
+ *
+ * Env:
+ *   PORT, JSON_PATH, APPKEY, NODE_ENV, LOG_LEVEL
+ */
+
+import { createMermaidApp, loadJsonData } from '../src/server.js';
+import log from '../src/utils/logger.js';
+
+const args = process.argv.slice(2);
+function arg(name, fallback) {
+  const i = args.indexOf(`--${name}`);
+  return i !== -1 ? args[i + 1] : fallback;
+}
+
+const PORT = parseInt(arg('port', process.env.PORT || '3333'), 10);
+const JSON_PATH = arg('json', process.env.JSON_PATH || './app.json');
+const APPKEY = arg('appkey', process.env.APPKEY || null);
+const NODE_ENV = process.env.NODE_ENV || 'development';
+const LOG_LEVEL = process.env.LOG_LEVEL || (NODE_ENV === 'production' ? 'info' : 'debug');
+
+log.level = LOG_LEVEL;
+
+log.info(`[MERMAID] Starting standalone runner...`);
+log.info(`[MERMAID] Environment: ${NODE_ENV}`);
+log.info(`[MERMAID] JSON: ${JSON_PATH}`);
+if (APPKEY) log.info(`[MERMAID] Locked to appkey: ${APPKEY}`);
+
+try {
+  // Validate JSON exists up front
+  loadJsonData(JSON_PATH);
+} catch (err) {
+  log.error(`[MERMAID] ${err.message}`);
+  process.exit(1);
+}
+
+const app = createMermaidApp({
+  jsonPath: JSON_PATH,
+  appkeyOverride: APPKEY,
+  channel: NODE_ENV === 'production' ? 'production' : 'development',
+});
+
+const server = app.listen(PORT, () => {
+  log.info(`[MERMAID] Running on http://localhost:${PORT}`);
+});
+
+const shutdown = (signal) => {
+  log.info(`[MERMAID] ${signal} received, shutting down...`);
+  server.close();
+  process.exit(0);
+};
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));

package/index.js

@@ -0,0 +1,21 @@
+/**
+ * @symbo.ls/mermaid — self-sustaining server runner for Symbols projects.
+ *
+ * Renders DOMQL projects from JSON to HTML, with optional brender SSR.
+ * Works as an Express server, a pure render function, or in CF Workers.
+ */
+
+export { createMermaidApp, loadJsonData } from './src/server.js';
+export {
+  renderProjectHtml,
+  renderNotPublishedHtml,
+  transpileFunctionStrings,
+  generateSitemap,
+  prefetchPageData,
+} from './src/render.js';
+export { getBundleScript, getSmblsIife } from './src/bundle.js';
+export { normalizeRoute, resolvePageRoute, extractRouteParams, STATIC_EXT } from './src/route.js';
+export { deepDestringifyFunctions, stripFunctionStrings } from './src/utils/deepDestringify.js';
+export { transpile as transpileFuncql } from './src/utils/funcql-transpile.js';
+export { default as replaceVariablesInFileSync } from './src/utils/vartranformer.js';
+export { default as log } from './src/utils/logger.js';

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@symbo.ls/mermaid",
+  "version": "3.14.0",
+  "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.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./server": "./src/server.js",
+    "./render": "./src/render.js",
+    "./bundle": "./src/bundle.js",
+    "./route": "./src/route.js",
+    "./utils/deepDestringify": "./src/utils/deepDestringify.js",
+    "./utils/funcql-transpile": "./src/utils/funcql-transpile.js",
+    "./utils/vartranformer": "./src/utils/vartranformer.js",
+    "./utils/logger": "./src/utils/logger.js",
+    "./template.html": "./src/template.html"
+  },
+  "files": ["index.js", "src", "README.md"],
+  "scripts": {
+    "start": "node bin/start.js"
+  },
+  "bin": {
+    "mermaid": "./bin/start.js"
+  },
+  "dependencies": {
+    "@symbo.ls/utils": "^3.14.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2"
+  },
+  "optionalDependencies": {
+    "@symbo.ls/brender": "^3.14.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bundle.js

@@ -0,0 +1,118 @@
+import log from './utils/logger.js';
+// The smbls IIFE source as a string. Single source of truth — generated by
+// `smbls build:iife` and exported from the smbls package itself, so this works
+// identically in Node, CF Workers, and any other runtime as a static import.
+import smblsIife from 'smbls/iife-string';
+
+log.debug(`[BUNDLE] smbls IIFE loaded from smbls/iife-string (${smblsIife.length} bytes)`);
+
+export function getSmblsIife() {
+  return smblsIife;
+}
+
+/**
+ * Generate the client-side bundle script that creates the Smbls app.
+ * Uses the same approach as templates/start.js runFromJson:
+ *   Smbls.deepDestringifyFunctions(data) -> Smbls.create(app, context)
+ */
+export function getBundleScript(appKey, data, req, { ProjectDataService } = {}) {
+  log.debug(`[BUNDLE] getBundleScript started for ${appKey}`);
+
+  if (!data) {
+    log.warn('[BUNDLE] No data provided, returning empty');
+    return '';
+  }
+
+  // Ensure data is fully merged before bundling
+  try {
+    if (data.merged) {
+      Object.assign(data, data.merged);
+      log.debug(`[BUNDLE] Applied precomputed merged data for project ${data.id}`);
+    } else if (
+      ProjectDataService &&
+      Array.isArray(data.sharedLibraries) &&
+      data.sharedLibraries.length > 0
+    ) {
+      const mergedData = ProjectDataService.mergeSharedLibraries(
+        data,
+        data.sharedLibraries,
+        data.projectType,
+      );
+      Object.assign(data, mergedData);
+      log.debug(`[BUNDLE] Merged ${data.sharedLibraries.length} shared libraries`);
+    }
+  } catch (mergeError) {
+    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);
+
+  // Determine liveSync setting
+  const release = req?.query?.release || false;
+  const version = req?.query?.version;
+  const isSymboLs = typeof appKey === 'string' && appKey.endsWith('symbo.ls');
+  const shouldDisableLiveSync = Boolean(release) || Boolean(version) || !isSymboLs;
+
+  const settingsStr = isSymboLs
+    ? JSON.stringify({ ...data.settings, liveSync: !shouldDisableLiveSync, inspect: true })
+    : 'null';
+
+  // Generate the client script - same pattern as templates/start.js runFromJson
+  const script = `
+    var context = Smbls.deepDestringifyFunctions(${jsonData});
+    context.packageManager = 'esm.sh';
+    if (context.db && context.db.createClient) delete context.db.createClient;
+    if (context.fetch && context.fetch.createClient) delete context.fetch.createClient;
+
+    // Runtime defaults (these are baked into the starter-kit/frank but missing from server data)
+    if (context.useReset === undefined) context.useReset = true;
+    if (context.useVariable === undefined) context.useVariable = true;
+    if (context.useFontImport === undefined) context.useFontImport = true;
+    if (context.useIconSprite === undefined) context.useIconSprite = true;
+    if (context.useSvgSprite === undefined) context.useSvgSprite = true;
+    if (context.useDefaultConfig === undefined) context.useDefaultConfig = true;
+    if (context.useDocumentTheme === undefined) context.useDocumentTheme = true;
+    if (!context.routerOptions) context.routerOptions = { scrollToTop: true };
+
+    var app = context.app || {};
+    delete context.app;
+    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
+    if (context.useDocumentTheme !== false) {
+      (function() {
+        try {
+          var t = null;
+          var key = context.themeStorageKey;
+          if (key) { try { t = localStorage.getItem(key) } catch(e) {} }
+          if (!t) t = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+          if (t) document.documentElement.setAttribute('data-theme', t);
+        } catch(e) {}
+      })();
+    }
+
+    var ssrShell = document.querySelector('[data-ssr]');
+    if (window.__BRENDER__ && ssrShell) {
+      // Move pre-rendered children to body before DOMQL skeleton creation
+      var frag = document.createDocumentFragment();
+      while (ssrShell.firstChild) frag.appendChild(ssrShell.firstChild);
+      document.body.insertBefore(frag, ssrShell);
+      ssrShell.remove();
+    } else if (ssrShell) {
+      // No brender hydration — remove empty/stale SSR shell
+      ssrShell.remove();
+    }
+
+    Smbls.create(app, context);
+  `;
+
+  log.debug(`[BUNDLE] Script generated (${script.length} bytes)`);
+  return script;
+}