@symbiotejs/symbiote 3.5.1 → 3.5.2

package/CHANGELOG.md

@@ -1,12 +1,28 @@
 # Changelog
 
+## 3.5.2
+
+### Fixed
+
+- **`devMode` flag is now cross-module safe.** Moved to `globalThis.__SYMBIOTE_DEV_MODE` so it works correctly across CDN/importmap module scopes (same pattern as `PubSub.globalStore`).
+
+### Improved
+
+- **`warn.js` — minimal core dispatcher.** Stripped to just `devState`, `warnMsg`, and `errMsg`. All formatting, messages, and styling logic moved to `devMessages.js` via `globalThis.__SYMBIOTE_DEV_LOG` handler. No messages map or `Array.isArray` in core.
+
+- **Colored console output.** `devMessages.js` now renders styled badges in browser consoles: purple `Symbiote` badge, amber/red code badge, violet `<component-name>`, and dimmed doc links. Falls back to plain text in Node.js.
+
+- **Doc references in all warnings.** Every message now includes a `→` link to the relevant GitHub docs page.
+
+- **`devMessages.js` auto-enables `devMode`.** Importing the module sets `globalThis.__SYMBIOTE_DEV_MODE = true` — one import for the full dev experience.
+
 ## 3.5.0
 
 ### Added
 
 - **External dev messages module (`core/devMessages.js`).** All warning and error message strings have been extracted from core files into an optional module. Core files now emit short numeric codes (e.g. `[Symbiote W5]`). Import `@symbiotejs/symbiote/core/devMessages.js` once to get full human-readable messages. This reduces the core bundle size by removing all formatting strings from `PubSub.js`, `Symbiote.js`, `tpl-processors.js`, `AppRouter.js`, `html.js`, and both itemize processors.
 
-- **`core/warn.js` — lightweight message dispatcher.** Exports `warnMsg(code, ...args)`, `errMsg(code, ...args)`, and `registerMessages(map)`. All core files now use this dispatcher instead of inline `console.warn`/`console.error` calls.
+- **`core/warn.js` — lightweight message dispatcher.** Exports `warnMsg(code, ...args)` and `errMsg(code, ...args)`. All core files now use this dispatcher instead of inline `console.warn`/`console.error` calls.
 
 - **AppRouter: `title` accepts functions.** Route descriptors and `setDefaultTitle()` now accept `() => String` in addition to plain strings. The function is called at navigation time, enabling dynamic or localized page titles:
   ```js

package/core/Symbiote.js

@@ -430,7 +430,7 @@ export class Symbiote extends HTMLElement {
           if (Symbiote.devMode && this.sharedCtx.has(sharedName)) {
             let existing = this.sharedCtx.read(sharedName);
             if (existing !== sharedVal && typeof sharedVal !== 'function') {
-              warnMsg(7, sharedName);
+              warnMsg(7, this.localName, sharedName);
             }
           }
           this.sharedCtx.add(sharedName, sharedVal);

package/core/devMessages.js

@@ -1,58 +1,102 @@
-import { registerMessages } from './warn.js';
-
 globalThis.__SYMBIOTE_DEV_MODE = true;
 
-registerMessages(new Map([
+let isBrowser = !globalThis.process;
+
+// CSS styles for browser console
+let S = {
+  badge: 'background:#7c3aed;color:#fff;border-radius:3px;padding:1px 4px;font-weight:bold',
+  code: 'background:#f59e0b;color:#000;border-radius:3px;padding:1px 4px;font-weight:bold',
+  errCode: 'background:#ef4444;color:#fff;border-radius:3px;padding:1px 4px;font-weight:bold',
+  tag: 'color:#7c3aed;font-weight:bold',
+  dim: 'color:#888',
+  reset: 'color:inherit',
+};
+
+let DOCS = 'https://github.com/symbiotejs/symbiote.js/blob/main/docs/';
+
+/**
+ * @param {string} code - e.g. 'W1' or 'E15'
+ * @param {string} body - message body
+ * @param {string} doc - doc page name
+ * @param {string} [tag] - component tag name
+ */
+function fmt(code, body, doc, tag) {
+  if (!isBrowser) {
+    return `[Symbiote ${code}]${tag ? ` <${tag}>:` : ''} ${body}\n→ ${DOCS}${doc}.md`;
+  }
+  let isErr = code.startsWith('E');
+  let parts = `%cSymbiote%c${code}%c`;
+  let styles = [S.badge, isErr ? S.errCode : S.code, S.reset];
+  if (tag) {
+    parts += ` %c<${tag}>%c`;
+    styles.push(S.tag, S.reset);
+  }
+  parts += ` ${body} %c→ ${doc}`;
+  styles.push(S.dim);
+  return [parts, ...styles];
+}
+
+/** @type {Map<number, (...args: any[]) => (string | any[])>} */
+let messages = new Map([
   // PubSub
   [1, (uid, action, prop) =>
-    `[Symbiote] PubSub (${uid}): cannot ${action}. Property: "${prop}"`],
+    fmt('W1', `PubSub (${uid}): cannot ${action}. Property: "${prop}"`, 'pubsub')],
   [2, (uid, prop, prevType, newType, prev, next) =>
-    `[Symbiote] PubSub (${uid}): type change for "${prop}" [${prevType} → ${newType}].\n`
-    + `Previous: ${prev}\nNew: ${next}`],
+    fmt('W2', `PubSub (${uid}): type change for "${prop}" [${prevType} → ${newType}]. Previous: ${prev} | New: ${next}`, 'pubsub')],
   [3, (uid) =>
-    `[Symbiote] PubSub: context "${uid}" is already registered. Returning existing instance.`],
+    fmt('W3', `PubSub: context "${uid}" is already registered. Returning existing instance.`, 'context')],
   [4, (uid, keys) =>
-    `[Symbiote] PubSub: context "${uid}" not found.\n`
-    + `Available contexts: [${keys}]`],
+    fmt('W4', `PubSub: context "${uid}" not found. Available: [${keys}]`, 'context')],
 
   // Symbiote
   [5, (localName, selector) =>
-    `[Symbiote] <${localName}>: custom template "${selector}" not found.`],
+    fmt('W5', `custom template "${selector}" not found.`, 'templates', localName)],
   [6, (localName, sharedName) =>
-    `[Symbiote] "${localName}" uses *${sharedName} without ctx attribute or --ctx CSS variable. `
-    + 'Set ctx="name" or --ctx to share state.'],
-  [7, (sharedName) =>
-    `[Symbiote] Shared prop "${sharedName}" already has value. Keeping existing.`],
+    fmt('W6', `uses *${sharedName} without ctx attribute or --ctx CSS variable. Set ctx="name" or --ctx to share state.`, 'context', localName)],
+  [7, (localName, sharedName) =>
+    fmt('W7', `shared prop "${sharedName}" already has value. Keeping existing.`, 'context', localName)],
   [8, (tagName, existingClass, newClass) =>
-    `[Symbiote] <${tagName}> is already registered (class: ${existingClass}).\n`
-    + `Attempted re-registration with class "${newClass}" — skipped.`],
+    fmt('W8', `already registered (class: ${existingClass}). Re-registration with "${newClass}" — skipped.`, 'get-started', tagName)],
   [9, (localName, propName) =>
-    `[Symbiote] <${localName}>: CSS data parse error for "${propName}". Check that the CSS custom property is defined.`],
+    fmt('W9', `CSS data parse error for "${propName}". Check that the CSS custom property is defined.`, 'css-data', localName)],
   [10, (localName, propName) =>
-    `[Symbiote dev] <${localName}>: CSS data binding "${propName}" will not read computed styles during SSR. `
-    + 'The init value will be used instead.'],
+    fmt('W10', `CSS data binding "${propName}" will not read computed styles during SSR. The init value will be used instead.`, 'css-data', localName)],
 
   // tpl-processors
   [11, (localName, valKey, knownKeys) =>
-    `[Symbiote dev] <${localName}>: binding key "${valKey}" not found in init$ (auto-initialized to null).\n`
-    + `Known keys: [${knownKeys}]`],
+    fmt('W11', `binding key "${valKey}" not found in init$ (auto-initialized to null). Known keys: [${knownKeys}]`, 'properties', localName)],
   [12, (localName, prop) =>
-    `[Symbiote dev] <${localName}>: text-node binding "{{${prop}}}" has no hydration attribute. `
-    + 'In ssrMode/isoMode it will be rendered by the server but won\'t update on the client. '
-    + 'Use property binding (${{textContent: \'' + prop + '\'}}) for hydratable text.'],
+    fmt('W12', `text-node binding "{{${prop}}}" has no hydration attribute. `
+      + 'In ssrMode/isoMode it will be rendered by the server but won\'t update on the client. '
+      + 'Use property binding (${{textContent: \'' + prop + '\'}}) for hydratable text.', 'ssr', localName)],
 
   // AppRouter
   [13, (msg) =>
-    `[Symbiote > AppRouter] ${msg}`],
+    fmt('W13', msg, 'routing')],
   [14, () =>
-    '[Symbiote > AppRouter] History API is not available.'],
+    fmt('W14', 'History API is not available.', 'routing')],
 
   // html
   [15, (val) =>
-    `[Symbiote > html] \`this\` used in template interpolation (value: ${val}).\n`
-    + 'Templates are context-free — use ${{ prop: \'stateKey\' }} binding syntax instead.'],
+    fmt('E15', `\`this\` used in template interpolation (value: ${val}). `
+      + 'Templates are context-free — use ${{ prop: \'stateKey\' }} binding syntax instead.', 'templates')],
 
   // itemizeProcessor
   [16, (localName, dataType, data) =>
-    `[Symbiote] <${localName}>: itemize data must be Array or Object, got ${dataType}: ${data}`],
-]));
+    fmt('W16', `itemize data must be Array or Object, got ${dataType}: ${data}`, 'list-rendering', localName)],
+]);
+
+/**
+ * @param {'warn' | 'error'} type
+ * @param {number} code
+ * @param {any[]} args
+ */
+globalThis.__SYMBIOTE_DEV_LOG = (type, code, args) => {
+  let formatter = messages.get(code);
+  if (formatter) {
+    let result = formatter(...args);
+    Array.isArray(result) ? console[type](...result) : console[type](result);
+  } else {
+    console[type](`[Symbiote ${type === 'error' ? 'E' : 'W'}${code}]`);
+  }
+};

package/core/warn.js

@@ -1,6 +1,3 @@
-/** @type {Map<number, (...args: any[]) => string>} */
-let messages = globalThis.__SYMBIOTE_DEV_MESSAGES || (globalThis.__SYMBIOTE_DEV_MESSAGES = new Map());
-
 /** @type {{ devMode: boolean }} */
 export let devState = {
   get devMode() {
@@ -11,13 +8,17 @@ export let devState = {
   },
 };
 
+/** @param {string} type @param {number} code */
+function _log(type, code) {
+  console[type](`[Symbiote ${type === 'error' ? 'E' : 'W'}${code}]`);
+}
+
 /**
  * @param {number} code
  * @param  {...any} args
  */
 export function warnMsg(code, ...args) {
-  let fmt = messages.get(code);
-  console.warn(fmt ? fmt(...args) : `[Symbiote W${code}]`);
+  (globalThis.__SYMBIOTE_DEV_LOG || _log)('warn', code, args);
 }
 
 /**
@@ -25,14 +26,5 @@ export function warnMsg(code, ...args) {
  * @param  {...any} args
  */
 export function errMsg(code, ...args) {
-  let fmt = messages.get(code);
-  console.error(fmt ? fmt(...args) : `[Symbiote E${code}]`);
+  (globalThis.__SYMBIOTE_DEV_LOG || _log)('error', code, args);
 }
-
-/** @param {Map<number, (...args: any[]) => string>} map */
-export function registerMessages(map) {
-  for (let [code, fmt] of map) {
-    messages.set(code, fmt);
-  }
-}
-

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@symbiotejs/symbiote",
-  "version": "3.5.1",
+  "version": "3.5.2",
   "description": "Symbiote.js - zero-dependency close-to-platform frontend library to build super-powered web components",
   "author": "team@rnd-pro.com",
   "license": "MIT",
@@ -158,6 +158,7 @@
   "keywords": [
     "web components",
     "SSR",
+    "SSG",
     "server side rendering for web components",
     "ui library",
     "data flow",
@@ -182,7 +183,8 @@
     "https imports",
     "reactive html attributes",
     "MIT",
-    "JSDA"
+    "JSDA",
+    "jsda-kit"
   ],
   "devDependencies": {
     "@playwright/test": "^1.58.2",

package/types/core/devMessages.d.ts

@@ -1,2 +1,13 @@
-export {};
+declare function fmt(code: string, body: string, doc: string, tag?: string): string | string[];
+declare let isBrowser: boolean;
+declare namespace S {
+    let badge: string;
+    let code: string;
+    let errCode: string;
+    let tag: string;
+    let dim: string;
+    let reset: string;
+}
+declare let DOCS: string;
+declare let messages: Map<number, (...args: any[]) => (string | any[])>;
 //# sourceMappingURL=devMessages.d.ts.map

package/types/core/devMessages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devMessages.d.ts","sourceRoot":"","sources":["../../core/devMessages.js"],"names":[],"mappings":""}
+{"version":3,"file":"devMessages.d.ts","sourceRoot":"","sources":["../../core/devMessages.js"],"names":[],"mappings":"AAsBA,2BALW,MAAM,QACN,MAAM,OACN,MAAM,QACN,MAAM,qBAgBhB;AAlCD,+BAAoC;;;;;;;;;AAYpC,yBAAuE;AAyBvE,sBADW,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAgDzD"}

package/types/core/warn.d.ts

@@ -1,6 +1,5 @@
 export function warnMsg(code: number, ...args: any[]): void;
 export function errMsg(code: number, ...args: any[]): void;
-export function registerMessages(map: Map<number, (...args: any[]) => string>): void;
 export let devState: {
     devMode: boolean;
 };

package/types/core/warn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warn.d.ts","sourceRoot":"","sources":["../../core/warn.js"],"names":[],"mappings":"AAiBA,8BAHW,MAAM,WACF,GAAG,EAAA,QAKjB;AAMD,6BAHW,MAAM,WACF,GAAG,EAAA,QAKjB;AAGD,sCADY,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,QAKlD;AAhCD,qBADW;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAQ7B"}
+{"version":3,"file":"warn.d.ts","sourceRoot":"","sources":["../../core/warn.js"],"names":[],"mappings":"AAmBA,8BAHW,MAAM,WACF,GAAG,EAAA,QAIjB;AAMD,6BAHW,MAAM,WACF,GAAG,EAAA,QAIjB;AA5BD,qBADW;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAQ7B"}