@omega.js/client 0.1.0

package/dist/modules/icon-core.js

@@ -0,0 +1,226 @@
+/**
+ * icon-core — the ONE place Font Awesome icon semantics live (C4 cp108).
+ *
+ * Pure functions, zero runtime assumptions: no DOM, no fs, no transport.
+ * Web's build-time inlining pass (@omega.js/web src/inline-icons.js) and
+ * @omega.js/desktop's main-process icon server both consume THIS module, so
+ * lookup rules and rendered SVG markup can never drift between surfaces
+ * again. File reading stays with each consumer (build tags read at build
+ * time, desktop main reads at runtime) — this module owns every decision
+ * ABOUT the files: valid names/styles, candidate lookup order, the inline
+ * root attributes, the package preference order (Pro when the brand
+ * supplies it, free floor), and alias mapping from the icon set's own
+ * metadata ('search' → 'magnifying-glass').
+ *
+ * CJS on purpose: template-kit and Electron main require() it directly (via
+ * the package's dist exports); browser modules import it with standard
+ * interop.
+ */
+
+// Icon asset packages, best-first (cp111): a brand that supplies Font
+// Awesome Pro gets it automatically; the free set is the always-present
+// floor (a declared dependency of web + desktop). Pro is NEVER a dependency
+// of any omega package — redistribution is a license violation — each brand
+// brings its own licensed copy (npm token install, or a fontawesome.com
+// download dir via OMEGA_FONTAWESOME_ROOT).
+const PACKAGES = ['@fortawesome/fontawesome-pro', '@fortawesome/fontawesome-free'];
+
+// The ONE emitted directory name, every surface: a site serves it at
+// /assets/icons/<style>/<name>.svg, an extension packs it at
+// assets/icons/… ([#619](https://github.com/Omega-JS-Stack/omega/issues/619)).
+// `icons` and not `fa` because flags ride the same tree as a second
+// namespace, and nothing about the channel is Font Awesome specific. It lives
+// HERE with the rest of the lookup rules — the build side re-exports it
+// (@omega.js/devkit/icons) and every browser transport derives its base from
+// it, so the name can never drift between what a build emits and what a page
+// fetches. (The extension manifest's web_accessible_resources stays a literal:
+// manifest.json is static JSON, read by Chrome, not by us.)
+const ICONS_DIR = 'icons';
+
+// The free set's svgs/ directories. Pro supplies more (light, thin,
+// duotone, sharp-*, …) — validation is by shape, not this list, so new
+// Pro families work without this module tracking Font Awesome's catalog.
+const STYLES = ['solid', 'regular', 'brands'];
+
+// Style dirs are path segments too — same traversal rule as names, so an
+// unknown style can only ever be a file-not-found, never an escape.
+const STYLE_REGEX = /^[a-z][a-z-]*$/;
+
+// Lowercase slug names only — lookups build file paths, so this whitelist
+// is also what keeps callers (like desktop's IPC channel) from ever reading
+// outside the icon directories.
+const NAME_REGEX = /^[a-z0-9-]+$/;
+
+// Attributes injected on the <svg> root at serve time: icons size to the
+// surrounding font and inherit its color. overflow="visible" mirrors FA's
+// own kit CSS (.svg-inline--fa { overflow: visible }) — FA 7 glyphs may
+// draw OUTSIDE their viewBox (fa-lock's shackle peaks at y=-32 in a
+// 0 0 384 512 box) and the SVG-root default of overflow:hidden clips them.
+const SVG_ATTRIBUTES = [
+  ['width', 'width="1em"'],
+  ['height', 'height="1em"'],
+  ['fill', 'fill="currentColor"'],
+  ['aria-hidden', 'aria-hidden="true"'],
+  ['focusable', 'focusable="false"'],
+  ['overflow', 'overflow="visible"'],
+];
+
+/**
+ * Whether a value is a valid icon slug ('magnifying-glass').
+ *
+ * @param {*} name - Candidate icon name.
+ * @returns {boolean} True for lowercase slug strings.
+ */
+function isValidIconName(name) {
+  return typeof name === 'string' && NAME_REGEX.test(name);
+}
+
+/**
+ * Whether a value is a plausible icon style ('solid', 'duotone',
+ * 'sharp-light'). Shape-validated (path-safe slug), not whitelist-validated:
+ * whether the style actually exists in the supplied icon set is decided by
+ * the file lookup — a bogus style is a missing icon, never a crash or an
+ * escape from the icon directories.
+ *
+ * @param {*} style - Candidate style.
+ * @returns {boolean} True for lowercase path-safe style slugs.
+ */
+function isValidStyle(style) {
+  return typeof style === 'string' && STYLE_REGEX.test(style);
+}
+
+/**
+ * Inject the shared root attributes into a raw icon SVG string — each one
+ * only when the root doesn't already carry it, so hand-authored SVGs keep
+ * their own sizing/fill.
+ *
+ * @param {string} svg - Raw SVG source.
+ * @returns {string} SVG with the inline-icon root attributes.
+ */
+function injectSvgAttributes(svg) {
+  if (typeof svg !== 'string' || !svg.includes('<svg')) return svg;
+
+  // No comment survives into the injected markup: Font Awesome ships its
+  // license comment inside every glyph, and that comment's `-->` TERMINATES
+  // any HTML comment the icon happens to sit inside — a commented-out block
+  // carrying an icon (body.html's parked flash-sale banner) rendered on every
+  // page. Attribution stays with the set: the emitted /assets/icons/ files
+  // are copies of the originals, comments intact.
+  return svg.replace(/<!--[\s\S]*?-->/g, '').replace(/<svg([^>]*)>/, (match, existingAttrs) => {
+    const toAdd = SVG_ATTRIBUTES
+      .filter(([attr]) => !existingAttrs.includes(`${attr}=`))
+      .map(([, pair]) => pair);
+
+    return toAdd.length ? `<svg${existingAttrs} ${toAdd.join(' ')}>` : match;
+  }).trim();
+}
+
+/**
+ * Relative candidate paths for an icon, in lookup order: the requested
+ * style first, then the brands fallback — so logos like 'apple' resolve
+ * without callers knowing which side of the set they live on.
+ *
+ * @param {string} name - Icon slug.
+ * @param {string} style - Requested style.
+ * @returns {string[]} Relative paths to try against each icon root.
+ */
+function candidateRelPaths(name, style) {
+  const candidates = [`${style}/${name}.svg`];
+  if (style !== 'brands') {
+    candidates.push(`brands/${name}.svg`);
+  }
+  return candidates;
+}
+
+// Font Awesome's class model: a base WEIGHT class, an optional FAMILY
+// prefix class, and everything else is a modifier or the icon name.
+const BASE_STYLE_CLASSES = {
+  'fa-solid': 'solid', fas: 'solid',
+  'fa-regular': 'regular', far: 'regular',
+  'fa-light': 'light', fal: 'light',
+  'fa-thin': 'thin', fat: 'thin',
+  'fa-brands': 'brands', fab: 'brands',
+};
+const FAMILY_CLASSES = { 'fa-sharp': 'sharp', 'fa-duotone': 'duotone', fad: 'duotone', 'fa-sharp-duotone': 'sharp-duotone' };
+
+// fa-* classes that are modifiers (style/size/animation/layout), not icon names.
+// The size roster is the sheet's $fa-sizes map, all 12 of it (@omega.js/web
+// core/css/core/_custom-font-awesome.scss). A shipped size class this list
+// misses reads as an icon NAME and the renderer hunts for a glyph called '4xl'.
+const MODIFIER_REGEX = /^fa-(?:solid|brands|regular|light|thin|duotone|sharp-duotone|sharp|fw|2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl|5xl|6xl|[0-9]+x|spin|spin-pulse|spin-reverse|pulse|beat|fade|beat-fade|bounce|shake|flip(?:-horizontal|-vertical|-both)?|rotate-(?:90|180|270|by)|inverse|border|pull-left|pull-right|stack(?:-1x|-2x)?|li|ul|sr-only)$/;
+
+// Country flags are the SECOND namespace on this pipeline (#619) — not Font
+// Awesome, but the same markup shape, the same lookup, the same emitted tree:
+// `<i class="omega-flag omega-flag-us">` is `flags/us.svg`.
+const FLAG_CLASS_REGEX = /^omega-flag-([a-z0-9-]+)$/;
+
+/**
+ * Parse an element's class list the way Font Awesome does:
+ * `fa-sharp fa-light fa-play me-2` → { name: 'play', style: 'sharp-light' }.
+ * Weight defaults to solid; a family class prefixes it (duotone-solid lives
+ * in the bare `duotone` dir). A flag class (`omega-flag-us`) is the one
+ * non-FA namespace and resolves to the `flags` style. Null when no icon name
+ * is present.
+ *
+ * @param {Iterable<string>} classList - Element class names.
+ * @returns {{ name: string, style: string }|null} Parsed lookup, or null.
+ */
+function parseIconClasses(classList) {
+  let base = 'solid';
+  let family = '';
+  let name = null;
+
+  for (const cls of classList) {
+    const flag = FLAG_CLASS_REGEX.exec(cls);
+    if (flag) {
+      return { name: flag[1], style: 'flags' };
+    }
+    if (BASE_STYLE_CLASSES[cls]) {
+      base = BASE_STYLE_CLASSES[cls];
+    } else if (FAMILY_CLASSES[cls]) {
+      family = FAMILY_CLASSES[cls];
+    } else if (!name && cls.startsWith('fa-') && !MODIFIER_REGEX.test(cls)) {
+      name = cls.slice(3);
+    }
+  }
+  if (!name) {
+    return null;
+  }
+
+  const style = (base === 'brands' || !family) ? base
+    : (family === 'duotone' && base === 'solid') ? 'duotone'
+      : `${family}-${base}`;
+  return { name, style };
+}
+
+/**
+ * Build the alias → canonical name map from fontawesome-free's
+ * metadata/icon-families.json ('search' → 'magnifying-glass').
+ *
+ * @param {object} iconFamilies - Parsed icon-families.json content.
+ * @returns {Map<string, string>} Alias slug → canonical slug.
+ */
+function buildAliasMap(iconFamilies) {
+  const map = new Map();
+  for (const [canonical, entry] of Object.entries(iconFamilies || {})) {
+    for (const alias of entry?.aliases?.names || []) {
+      map.set(alias, canonical);
+    }
+  }
+  return map;
+}
+
+module.exports = {
+  PACKAGES,
+  ICONS_DIR,
+  STYLES,
+  STYLE_REGEX,
+  NAME_REGEX,
+  SVG_ATTRIBUTES,
+  isValidIconName,
+  isValidStyle,
+  injectSvgAttributes,
+  candidateRelPaths,
+  parseIconClasses,
+  buildAliasMap,
+};

package/dist/modules/icon-renderer.js

@@ -0,0 +1,149 @@
+/**
+ * icon-renderer — the ONE Font Awesome DOM auto-render (C4 cp112), shared
+ * by every browser surface: desktop renderers, web pages, and extension
+ * pages when one appears. Authoring is plain Font Awesome markup:
+ *
+ *   <i class="fa-solid fa-rocket"></i>          — static HTML
+ *   <i class="omega-flag omega-flag-us"></i>    — the flags namespace (#619)
+ *   el.className = 'fa-sharp fa-light fa-play'  — set or CHANGED via JS,
+ *                                                  any time; both render.
+ *
+ * The module owns everything except transport: scanning, the
+ * MutationObserver (insertions AND class changes), class parsing
+ * (icon-core's parseIconClasses), SVG root attributes, caching, and
+ * re-render/clear semantics. The caller injects ONE function — where SVG
+ * text comes from:
+ *
+ *   desktop  →  (name, style) => ipc.invoke('desktop:fontawesome:get', …)
+ *   web      →  (name, style) => fetch(`/assets/icons/${style}/${name}.svg`)
+ *   extension→  (name, style) => fetch(chrome.runtime.getURL(…))
+ *
+ * Rendered elements carry data-omega-fa="<style>/<name>". Unknown icons
+ * leave the element empty (marked) — a missing icon is a content problem,
+ * never a crash, and never a wrong-style fallback.
+ */
+
+const { parseIconClasses, isValidIconName, isValidStyle, injectSvgAttributes } = require('./icon-core.js');
+
+// Both namespaces the class parser understands (#619): Font Awesome's fa-*
+// and the country flags' omega-flag-*.
+const ICON_SELECTOR = 'i[class*="fa-"], i[class*="omega-flag-"]';
+const RENDERED_SELECTOR = `${ICON_SELECTOR}, i[data-omega-fa]`;
+
+/**
+ * Create an icon renderer bound to a transport.
+ *
+ * @param {object} options
+ * @param {function(string, string): Promise<string|null>} options.resolve -
+ *   Icon transport: (name, style) → raw SVG text or null.
+ * @returns {{ start: function, stop: function, scan: function }}
+ */
+function createIconRenderer(options) {
+  const cache = new Map(); // 'style/name' → Promise<string|null>
+  let observer = null;
+  let started = false;
+
+  const resolve = (name, style) => {
+    const key = `${style}/${name}`;
+    if (!cache.has(key)) {
+      cache.set(key, Promise.resolve()
+        .then(() => options.resolve(name, style))
+        .then((svg) => (svg ? injectSvgAttributes(svg) : null))
+        .catch(() => null));
+    }
+    return cache.get(key);
+  };
+
+  const render = (el) => {
+    const parsed = parseIconClasses(el.classList);
+    if (!parsed || !isValidIconName(parsed.name) || !isValidStyle(parsed.style)) {
+      // No (valid) icon classes left — clear a previously rendered icon.
+      if (el.dataset.omegaFa) {
+        delete el.dataset.omegaFa;
+        el.innerHTML = '';
+      }
+      return;
+    }
+
+    const key = `${parsed.style}/${parsed.name}`;
+    if (el.dataset.omegaFa === key) {
+      return;
+    }
+
+    el.dataset.omegaFa = key;
+    el.innerHTML = '';
+    resolve(parsed.name, parsed.style).then((svg) => {
+      // Stale guard: classes may have changed again while resolving.
+      if (svg && el.isConnected && el.dataset.omegaFa === key && !el.querySelector('svg')) {
+        el.innerHTML = svg;
+      }
+    });
+  };
+
+  const scan = (root) => {
+    if (root.matches?.(ICON_SELECTOR)) {
+      render(root);
+    }
+    root.querySelectorAll?.(ICON_SELECTOR).forEach(render);
+  };
+
+  /**
+   * Scan the document and observe it for inserted icons AND class changes
+   * on existing ones. Idempotent.
+   *
+   * @param {Document} [doc] - Defaults to the global document.
+   */
+  const start = (doc = typeof document !== 'undefined' ? document : null) => {
+    if (!doc || started) {
+      return;
+    }
+    started = true;
+
+    const begin = () => {
+      observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.type === 'attributes') {
+            if (mutation.target.matches?.(RENDERED_SELECTOR)) {
+              render(mutation.target);
+            }
+            continue;
+          }
+          mutation.addedNodes.forEach((node) => {
+            if (node.nodeType === 1) {
+              scan(node);
+            }
+          });
+        }
+      });
+      observer.observe(doc.documentElement, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['class'],
+      });
+
+      scan(doc.documentElement);
+    };
+
+    // Deferred until the document exists — preload-time callers (the
+    // desktop test harness) run before documentElement is built.
+    if (doc.documentElement && doc.readyState !== 'loading') {
+      begin();
+    } else {
+      doc.addEventListener('DOMContentLoaded', begin, { once: true });
+    }
+  };
+
+  const stop = () => {
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+    started = false;
+    cache.clear();
+  };
+
+  return { start, stop, scan };
+}
+
+module.exports = { createIconRenderer };

package/dist/modules/live-page.js

@@ -0,0 +1,235 @@
+/**
+ * live-page — the primitives a page that REFRESHES ITSELF needs, ported from
+ * the workkit tower's page runtime.
+ *
+ * A live page is polled: it re-reads its feeds on a timer and re-renders with
+ * the answers. The naive shape of that — write the whole body on every tick —
+ * repaints identical markup ten times a minute, which blinks the cards, drops
+ * the scroll position inside a scrolling strip and closes whatever `details`
+ * was open. And before the first answer arrives the same render draws an empty
+ * region, so a slow feed looks like an empty one.
+ *
+ * Three primitives, one rule each:
+ *   - `swap(host, markup)` writes ONLY when the markup differs from what was
+ *     written last, so an unchanged section is left alone — DOM, focus, scroll
+ *     and all.
+ *   - `loading(message)` is what a section shows while its feed has never
+ *     answered: a first paint says which read it is waiting on, never a blank.
+ *   - `createFeedPoller(options)` owns the declared feed table, the in-flight
+ *     count and the keep-last-good rule — a refresh that fails leaves the last
+ *     good answer on screen, marked stale with the reason.
+ *
+ * Transport-free, like `icon-renderer` and `motion`: nothing here fetches. The
+ * poller takes its fetcher as an ARGUMENT — an `omega.request`-shaped function
+ * (resolves with the body, throws an Error carrying `.code`) — so the embedding
+ * page passes `omega.request` and a non-singleton context (desktop main, the
+ * extension service worker) passes its own `createRequest(...)` instance, the
+ * same seam `request.js` already offers.
+ */
+
+import Utilities from './utilities.js';
+
+// Escaping is utilities' job, never this module's. The helpers are pure — they
+// touch no manager state — so a manager-free instance is the whole dependency.
+const { escapeHTML } = new Utilities();
+
+/** What swap last wrote into each host, keyed by the element itself. */
+const written = new WeakMap();
+
+/**
+ * The markup a section shows while its feed has not answered yet.
+ *
+ * The theme's spinner, in the muted voice a "nothing here" line uses.
+ *
+ * @param {string} message - what is being read, in the page's own words
+ * @returns {string} markup
+ */
+export function loading(message) {
+  return `<div class="d-flex align-items-center gap-2 text-body-secondary">
+  <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
+  <span class="classy-micro" aria-live="polite">${escapeHTML(message)}</span>
+</div>`;
+}
+
+/**
+ * Write markup into a host, but only when it is not already there.
+ *
+ * The comparison is against what swap itself last wrote, held in a WeakMap, and
+ * NOT against `host.innerHTML` — the browser re-serializes what it parses
+ * (attribute order, entities, void tags), so reading it back never matches the
+ * string that produced it and every tick would count as a change.
+ *
+ * @param {{innerHTML: string}} host - the element to draw into
+ * @param {string} markup - what the render produced this time
+ * @returns {boolean} true when the DOM was written, false when it was left
+ *   alone — the caller's post-draw work (charts, listeners) hangs off this
+ */
+export function swap(host, markup) {
+  if (written.get(host) === markup) {
+    return false;
+  }
+
+  written.set(host, markup);
+  host.innerHTML = markup;
+
+  return true;
+}
+
+/**
+ * Boot a feed poller over a declared feed table.
+ *
+ * The cadence is the poller's own: it stops while the page is hidden (a covered
+ * tab) and resumes on the way back with one immediate read. There is no option
+ * for it.
+ *
+ * @param {object} options
+ * @param {Object<string, {path: string, every: number, fresh?: string}>} options.feeds -
+ *   every feed this page reads: where it lives, how often it is re-read, and
+ *   the optional path a user-triggered refresh uses instead (a cache bypass)
+ * @param {(path: string) => Promise<any>} options.fetcher - an
+ *   `omega.request`-shaped function: resolves with the body, throws on failure
+ * @param {() => void} [options.onChange] - called at every state transition (a
+ *   read starting, a read landing), which is when the page repaints
+ * @returns {{state: object, read: Function, readAll: Function, staleFeeds: Function, start: Function, stop: Function}}
+ */
+export function createFeedPoller(options) {
+  if (typeof options.fetcher !== 'function') {
+    throw new Error('createFeedPoller requires a fetcher');
+  }
+
+  const feeds = options.feeds || {};
+  const names = Object.keys(feeds);
+  const onChange = options.onChange || (() => {});
+
+  // `pending` is how many reads are in flight, which a page's chrome draws its
+  // spinner from: a refresh is visible while it happens, and the page under it
+  // keeps showing the data it already has.
+  const state = { feeds: {}, pending: 0, stamp: '' };
+
+  let timers = [];
+  let started = false;
+
+  // The hidden-tab rule needs a document to read: a poller running where there
+  // is none (the extension service worker the fetcher seam exists for) has no
+  // tab that can be covered, and just keeps its cadence.
+  const page = typeof document === 'undefined' ? null : document;
+
+  // The fetcher throws; a feed result never does. Every way a read can let a
+  // page down lands in the same four-key shape, told apart by status and reason.
+  const ask = async (path) => {
+    try {
+      return { ok: true, data: await options.fetcher(path), status: null, reason: null };
+    } catch (error) {
+      return { ok: false, data: null, status: error?.code ?? null, reason: error?.message || 'the read failed' };
+    }
+  };
+
+  const read = async (name, fresh) => {
+    const spec = feeds[name];
+    if (!spec) {
+      throw new Error(`createFeedPoller: no feed named "${name}"`);
+    }
+
+    state.pending += 1;
+    onChange();
+
+    const answer = await ask(fresh && spec.fresh ? spec.fresh : spec.path);
+    const previous = state.feeds[name];
+    state.pending -= 1;
+
+    // A refresh that fails does not take the page down with it. The last good
+    // answer stays on screen, marked stale so the chrome can say a feed is
+    // unavailable — replacing a full board with an error line because one poll
+    // missed is the "clearing to empty" this module exists to prevent.
+    state.feeds[name] = !answer.ok && previous && previous.ok
+      ? { ...previous, stale: answer.reason }
+      : answer;
+    state.stamp = `updated ${new Date().toLocaleTimeString()}`;
+    onChange();
+  };
+
+  const readAll = (fresh) => Promise.all(names.map((name) => read(name, fresh)));
+
+  /**
+   * Every feed that is not currently telling the truth — one that failed
+   * outright, and one showing a last-good answer behind a failed refresh.
+   *
+   * @returns {Array<{name: string, reason: string}>}
+   */
+  const staleFeeds = () => Object.entries(state.feeds)
+    .filter(([, result]) => result && (!result.ok || result.stale))
+    .map(([name, result]) => ({ name, reason: result.stale || result.reason }));
+
+  const arm = () => {
+    timers = names.map((name) => setInterval(() => { read(name, false); }, feeds[name].every));
+  };
+
+  const disarm = () => {
+    timers.forEach((timer) => clearInterval(timer));
+    timers = [];
+  };
+
+  // A covered TAB reads nothing. Polling a page nobody is looking at spends the
+  // device's battery and the backend's quota on answers that are thrown away,
+  // so the intervals are cleared while the page is hidden and re-armed when it
+  // comes back — with ONE immediate read, because whatever is on screen is as
+  // old as the time the tab spent covered.
+  //
+  // `document.hidden` on purpose, and never focus: a visible-but-unfocused
+  // window is still being WATCHED — a board on a second monitor is the case
+  // this module exists for — and keeps its cadence.
+  const onVisibilityChange = () => {
+    if (!started) {
+      return;
+    }
+
+    if (page.hidden) {
+      disarm();
+      return;
+    }
+
+    // Armed already means this was not a return from hidden (a browser can say
+    // "visible" to a page that never left), and there is nothing to catch up on.
+    if (timers.length) {
+      return;
+    }
+
+    readAll(false);
+    arm();
+  };
+
+  const start = async () => {
+    if (started) {
+      return;
+    }
+    started = true;
+
+    await readAll(false);
+
+    // Armed AFTER the first pass so a slow first read is never overlapped by
+    // its own timer. A stop() during that first pass flips `started` back off
+    // before this line runs — arming anyway would leave intervals nothing can
+    // ever clear, so the re-check is what makes stop() final.
+    if (!started) {
+      return;
+    }
+
+    page?.addEventListener('visibilitychange', onVisibilityChange);
+
+    // A start in a tab that is ALREADY covered arms nothing: the listener above
+    // is what gives the page its cadence when it comes into view.
+    if (page?.hidden) {
+      return;
+    }
+
+    arm();
+  };
+
+  const stop = () => {
+    page?.removeEventListener('visibilitychange', onVisibilityChange);
+    disarm();
+    started = false;
+  };
+
+  return { state, read, readAll, staleFeeds, start, stop };
+}

package/dist/modules/logger.js

@@ -0,0 +1,36 @@
+/**
+ * The client's runtime log tag — the ONE identity tag every OMEGA surface
+ * prints: `[@omega.js/client:<module>]` ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
+ *
+ * No timestamp on purpose: devtools already stamps runtime lines. The
+ * build-time twin (`@omega.js/devkit/logger`) is the one that prefixes
+ * `[HH:MM:SS]` before the same tag.
+ *
+ * Every client module logs through this factory — no module hand-writes a tag,
+ * so the shape can never drift again.
+ */
+
+// The package segment — this file IS @omega.js/client, so it is a literal.
+const PACKAGE = '@omega.js/client';
+
+// Create a tagged console for one module, e.g. createLogger('push').
+export function createLogger(module) {
+  const tag = `[${PACKAGE}:${module}]`;
+
+  // GETTERS returning a BOUND console method, not wrapper arrows: devtools
+  // attributes a line to the frame that called console, so a wrapper would make
+  // every line in the app read as coming from this file. Binding hands the real
+  // call site back. Resolution stays at ACCESS time, so a test (or a consumer)
+  // that swaps console[method] still sees its own stub.
+  const logger = { tag };
+  for (const method of ['log', 'info', 'warn', 'error', 'debug']) {
+    Object.defineProperty(logger, method, {
+      get: () => console[method].bind(console, tag),
+      enumerable: true,
+    });
+  }
+
+  return logger;
+}
+
+export default createLogger;