@omega.js/web 0.1.0

package/dist/vendor/devkit/deploy.js

@@ -0,0 +1,286 @@
+/**
+ * Deploy executor — the ONE dispatch path for deliberate deploys (D13/D9).
+ *
+ * Commits never auto-publish: scaffolded workflows carry no push triggers, so
+ * publishing is an explicit dispatch of the SAME CI build — from the local
+ * CLI (`omega deploy`), a server-side action (the admin post route's
+ * content-publish), or any plain HTTP caller. All three converge here: a
+ * GitHub REST `workflow_dispatch` call (native fetch, no gh-CLI dependency —
+ * Cloud Functions and laptops share the code path; locally the token can
+ * still come from `gh auth token`).
+ */
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+const { findBrandRoot, discoverTargets, frameworkPackagesOf } = require('./local.js');
+
+const API_BASE = 'https://api.github.com';
+
+/**
+ * Parse a git remote URL into { owner, repo }.
+ * Handles ssh (git@github.com:o/r.git), https (https://github.com/o/r.git),
+ * and .git-less forms.
+ * @param {string} url - remote URL
+ * @returns {{ owner: string, repo: string }|null}
+ */
+function parseRemoteUrl(url) {
+  const match = (url || '').trim().match(/github\.com[/:]([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+/**
+ * The repo a CI dispatch addresses: the BRAND's own repo, from its config
+ * ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)). Every framework's
+ * deploy verb asks this instead of `resolveRepo` above, because a git remote
+ * answers the repo the working tree sits in: inside a brand monorepo nested in
+ * another repo (a brand inside the framework monorepo, a target checked out
+ * under someone else's tree) that is the ENCLOSING repo, so the dispatch went to
+ * a workflow that was never there.
+ *
+ * Half an address addresses nothing, so it throws rather than POST to
+ * `undefined/<name>`.
+ *
+ * @param {object} config - Composed omega config for the target being deployed.
+ * @returns {{ owner: string, repo: string }} the brand repo's owner and bare name
+ * @throws {Error} when the config names no repo
+ */
+function dispatchRepo(config) {
+  const { brandRepo } = require('../config/index.js');
+  const { owner, name } = brandRepo(config);
+
+  if (!owner || !name) {
+    throw new Error('Could not determine the brand repo to dispatch on. Set repo.providers.github.org (and repo.providers.github.repo when the repo name is not <brand.id>-omega) in config/omega.json5.');
+  }
+
+  return { owner, repo: name };
+}
+
+/**
+ * Resolve the GitHub repo for a working directory from its origin remote.
+ * @param {object} [options]
+ * @param {string} [options.cwd] - repo directory (default: process.cwd())
+ * @param {string} [options.remote] - remote name (default: origin)
+ * @param {function} [options.execFn] - injectable exec (tests)
+ * @returns {{ owner: string, repo: string }}
+ */
+function resolveRepo(options = {}) {
+  const execFn = options.execFn || ((cmd, opts) => execSync(cmd, opts).toString());
+  const url = execFn(`git config --get remote.${options.remote || 'origin'}.url`, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const parsed = parseRemoteUrl(url);
+  if (!parsed) {
+    throw new Error(`Cannot parse a GitHub repo from remote url: ${String(url).trim() || '(none)'}`);
+  }
+  return parsed;
+}
+
+/**
+ * Resolve a GitHub token: GH_TOKEN → GITHUB_TOKEN → `gh auth token`.
+ * @param {object} [options]
+ * @param {object} [options.env] - env map (default: process.env)
+ * @param {function} [options.execFn] - injectable exec (tests)
+ * @returns {string|null}
+ */
+function resolveToken(options = {}) {
+  const env = options.env || process.env;
+  if (env.GH_TOKEN) return env.GH_TOKEN;
+  if (env.GITHUB_TOKEN) return env.GITHUB_TOKEN;
+
+  const execFn = options.execFn || ((cmd, opts) => execSync(cmd, opts).toString());
+  try {
+    const token = execFn('gh auth token', { stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return token || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Build a workflow_dispatch plan — the exact REST call a deploy will make.
+ * This IS the dry-run output: everything except the send.
+ * @param {object} options
+ * @param {string} options.owner - repo owner
+ * @param {string} options.repo - repo name
+ * @param {string} options.workflow - workflow file name (e.g. build.yml)
+ * @param {string} [options.ref] - branch/tag to run on (default: main)
+ * @param {object} [options.inputs] - workflow_dispatch inputs
+ * @returns {{ method: string, url: string, body: object, runsUrl: string }}
+ */
+function buildDispatch(options) {
+  for (const key of ['owner', 'repo', 'workflow']) {
+    if (!options[key]) throw new Error(`buildDispatch: missing ${key}`);
+  }
+  const body = { ref: options.ref || 'main' };
+  if (options.inputs && Object.keys(options.inputs).length > 0) body.inputs = options.inputs;
+
+  return {
+    method: 'POST',
+    url: `${API_BASE}/repos/${options.owner}/${options.repo}/actions/workflows/${options.workflow}/dispatches`,
+    body: body,
+    runsUrl: `https://github.com/${options.owner}/${options.repo}/actions/workflows/${options.workflow}`,
+  };
+}
+
+/**
+ * Send a dispatch plan to GitHub (204 = accepted).
+ * @param {object} plan - buildDispatch() result
+ * @param {object} options
+ * @param {string} options.token - GitHub token
+ * @param {function} [options.fetchFn] - injectable fetch (tests)
+ * @returns {Promise<object>} the plan, on success
+ */
+async function dispatchWorkflow(plan, options = {}) {
+  if (!options.token) {
+    throw new Error('No GitHub token — set GH_TOKEN in .env or sign in with `gh auth login`');
+  }
+  const fetchFn = options.fetchFn || fetch;
+  const response = await fetchFn(plan.url, {
+    method: plan.method,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${options.token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'omega-deploy',
+    },
+    body: JSON.stringify(plan.body),
+  });
+
+  if (response.status !== 204) {
+    const text = await response.text().catch(() => '');
+    throw new Error(`workflow_dispatch failed (${response.status}): ${text || response.statusText || 'unknown error'}`);
+  }
+  return plan;
+}
+
+/**
+ * The one deploy path: resolve repo + token, build the plan, dispatch — or
+ * return the plan untouched when dryRun is set.
+ * @param {object} options
+ * @param {string} options.workflow - workflow file name
+ * @param {string} [options.cwd] - repo dir for remote resolution
+ * @param {string} [options.owner] - explicit owner (skips git resolution)
+ * @param {string} [options.repo] - explicit repo (skips git resolution)
+ * @param {string} [options.ref] - branch (default main)
+ * @param {object} [options.inputs] - workflow inputs
+ * @param {boolean} [options.dryRun] - build the plan but never send
+ * @param {object} [options.env] - env map for token resolution
+ * @param {function} [options.fetchFn] - injectable fetch
+ * @param {function} [options.execFn] - injectable exec
+ * @returns {Promise<{ plan: object, dispatched: boolean }>}
+ */
+async function deployViaDispatch(options) {
+  const target = options.owner && options.repo
+    ? { owner: options.owner, repo: options.repo }
+    : resolveRepo({ cwd: options.cwd, execFn: options.execFn });
+
+  const plan = buildDispatch({
+    owner: target.owner,
+    repo: target.repo,
+    workflow: options.workflow,
+    ref: options.ref,
+    inputs: options.inputs,
+  });
+
+  if (options.dryRun) {
+    return { plan, dispatched: false };
+  }
+
+  const token = options.token || resolveToken({ env: options.env, execFn: options.execFn });
+  await dispatchWorkflow(plan, { token, fetchFn: options.fetchFn });
+  return { plan, dispatched: true };
+}
+
+/**
+ * Find every `file:` @omega.js spec in the brand tree. npm resolves the
+ * WHOLE workspace tree on any install, so one linked sibling target breaks a
+ * CI install even when the deploying target is clean (the cp194 lesson —
+ * linking is tree-wide, so detection is too). Deploy verbs use this to
+ * AUTO-SELECT their local-artifact lane (mirrored rule, Ian 2026-07-20:
+ * a linked brand ships the LOCAL framework — build here, ship the artifact;
+ * CI dispatch is only for registry-clean trees).
+ * @param {object} [options]
+ * @param {string} [options.dir] - Any directory inside the brand (default cwd).
+ * @returns {string[]} One line per offender: `<manifest> → <name>: <spec>`.
+ */
+function findLocalSpecs(options = {}) {
+  const brandRoot = findBrandRoot(options.dir || process.cwd());
+  const offenders = [];
+
+  for (const targetDir of discoverTargets(brandRoot)) {
+    for (const entry of frameworkPackagesOf(targetDir)) {
+      if (entry.spec.startsWith('file:')) {
+        const manifest = path.relative(brandRoot, path.join(targetDir, 'package.json')) || 'package.json';
+        offenders.push(`${manifest} → ${entry.name}: ${entry.spec}`);
+      }
+    }
+  }
+
+  return offenders;
+}
+
+/**
+ * Throw when the brand tree carries `file:` @omega.js specs — for lanes with
+ * no local-artifact fallback where dispatching would only burn a CI run.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Any directory inside the brand (default cwd).
+ * @throws {Error} Listing every file:-spec'd @omega.js dependency, per target.
+ */
+function assertNoLocalSpecs(options = {}) {
+  const offenders = findLocalSpecs(options);
+  if (offenders.length > 0) {
+    throw new Error(
+      'Local file: packages are linked somewhere in this brand — CI cannot install them.\n'
+      + `  ${offenders.join('\n  ')}\n`
+      + 'Deploy from the local-artifact lane, or restore registry specs first (omega i live).'
+    );
+  }
+}
+
+/**
+ * Commit + push the working tree before a dispatch deploy (D13: the push
+ * itself triggers NOTHING — scaffolded workflows carry no push triggers).
+ * Plain git via argument arrays: universal on consumer machines and
+ * injection-safe for the message.
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Repo directory (default process.cwd()).
+ * @param {string} [options.message] - Commit message (default 'Deploy').
+ * @param {object} [options.logger] - Logger with log (silent when omitted).
+ */
+function syncWorkingTree(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const message = options.message || 'Deploy';
+
+  execFileSync('git', ['add', '-A'], { cwd, stdio: 'inherit' });
+
+  // `git diff --cached --quiet` exits 1 exactly when something is staged
+  let hasStaged = false;
+  try {
+    execFileSync('git', ['diff', '--cached', '--quiet'], { cwd, stdio: 'ignore' });
+  } catch (e) {
+    hasStaged = true;
+  }
+
+  if (hasStaged) {
+    execFileSync('git', ['commit', '-m', message], { cwd, stdio: 'inherit' });
+  } else if (options.logger) {
+    options.logger.log('Working tree clean — nothing to commit');
+  }
+
+  execFileSync('git', ['push'], { cwd, stdio: 'inherit' });
+}
+
+module.exports = {
+  parseRemoteUrl,
+  dispatchRepo,
+  resolveRepo,
+  resolveToken,
+  buildDispatch,
+  dispatchWorkflow,
+  deployViaDispatch,
+  findLocalSpecs,
+  assertNoLocalSpecs,
+  syncWorkingTree,
+};

package/dist/vendor/devkit/env-watch.js

@@ -0,0 +1,132 @@
+/**
+ * env-watch — the `.env` chain as a WATCH INPUT for the dev lanes
+ * ([#681](https://github.com/Omega-JS-Stack/omega/issues/681)).
+ *
+ * The backend's stage watch has treated the cascade as an input since #678: an
+ * edit to the brand root's `.env` re-stages `dist/.env` and the running
+ * emulator picks it up (`envWatchInputs`,
+ * packages/backend/src/cli/utils/stage-functions.js). Web, desktop and
+ * extension read the cascade once at CLI/gulp boot and never noticed an edit —
+ * one target live-reloaded env, three did not. This is that same resolution for
+ * the three process.env lanes.
+ *
+ * Every layer of the chain is watched — company ← brand ← target — and each
+ * layer is TWO files, its `.env` and the `.env.<environment>` overlay that wins
+ * over it (#586), exactly the set `loadEnv` reads. DIRECTORIES are watched, not
+ * the files: an editor's save replaces the inode (a file watch does not survive
+ * it), and a layer's `.env` may not exist yet.
+ *
+ * Values NEVER reach a log line — a `.env` is all secrets, so the one line a
+ * reload prints names the FILE that changed.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveEnvChain, envLayerFiles, envEnvironment, reloadEnv } = require('../config/index.js');
+
+// Long enough to collapse an editor's save burst into one reload — the same
+// settle the other dev watchers use.
+const DEBOUNCE_MS = 250;
+
+/**
+ * The `.env` files a dev watcher treats as inputs, weakest layer first: each
+ * layer of the chain and the `.env.<environment>` overlay that wins over it.
+ * Existence is not checked here — a layer's file can appear mid-session.
+ *
+ * Named for the CHAIN it resolves, because the backend's stage watch has its
+ * own `envWatchInputs` (stage-functions.js) with a different contract — brand
+ * and company only, no overlays, no target layer
+ * ([#723](https://github.com/Omega-JS-Stack/omega/issues/723)).
+ *
+ * @param {string} projectDir - The target root (its .env is the local layer).
+ * @param {object} [options]
+ * @param {string} [options.environment] - The environment whose overlay counts
+ *   (defaults to the running one, the same answer loadEnv resolves).
+ * @returns {Array<{ layer: 'company'|'brand'|'target', path: string }>} Absolute paths.
+ */
+function envChainWatchInputs(projectDir, { environment = envEnvironment() } = {}) {
+  const chain = resolveEnvChain(projectDir);
+
+  return [
+    ...envLayerFiles(chain.company, environment).map((file) => ({ layer: 'company', path: file })),
+    ...envLayerFiles(chain.brand, environment).map((file) => ({ layer: 'brand', path: file })),
+    ...envLayerFiles(chain.local, environment).map((file) => ({ layer: 'target', path: file })),
+  ];
+}
+
+/**
+ * Watch the whole `.env` chain and reload the cascade into process.env on a
+ * change, so the NEXT rebuild reads the new values.
+ *
+ * SCOPE, exactly: a NEW key AND an EDITED value both land on that next rebuild,
+ * and a key dropped from the file is dropped from the process — what a file
+ * layer owns, the reload re-reads. A SHELL-set value always wins, whatever any
+ * file now says ([#724](https://github.com/Omega-JS-Stack/omega/issues/724)).
+ *
+ * One `fs.watch` per DIRECTORY (a standalone brand's layers can share one),
+ * filtered to the file names that directory contributes — a sibling file's
+ * churn never reloads anything. A directory that does not exist is skipped, the
+ * same rule the backend's stage watch applies.
+ *
+ * The reload is `reloadEnv`, which keeps the cascade's own precedence: the shell
+ * wins over every file, and a strictly stronger layer wins over a weaker one.
+ *
+ * @param {object} options
+ * @param {string} options.projectDir - The target root.
+ * @param {string} [options.target] - Target name ('web', 'desktop', 'extension')
+ *   — delivers the schema's `deliverAs` renames, exactly as the boot load did.
+ * @param {string} [options.environment] - The environment whose overlay is an
+ *   input (defaults to the running one).
+ * @param {function} [options.log] - Line logger (silent by default).
+ * @param {number} [options.debounceMs]
+ * @returns {{ inputs: Array<{ layer: string, path: string }>, close: function }}
+ */
+function watchEnvChain(options) {
+  const projectDir = options.projectDir;
+  const environment = options.environment || envEnvironment();
+  const log = options.log || (() => {});
+  const debounceMs = options.debounceMs || DEBOUNCE_MS;
+  const inputs = envChainWatchInputs(projectDir, { environment });
+
+  // dir → the file names that dir contributes to the chain
+  const byDir = new Map();
+  for (const input of inputs) {
+    const dir = path.dirname(input.path);
+    if (!byDir.has(dir)) byDir.set(dir, new Set());
+    byDir.get(dir).add(path.basename(input.path));
+  }
+
+  const watchers = [];
+  let timer = null;
+
+  for (const [dir, names] of byDir) {
+    if (!fs.existsSync(dir)) continue;
+
+    const watcher = fs.watch(dir, (event, filename) => {
+      if (!names.has(filename)) return;
+
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        reloadEnv(projectDir, { target: options.target, environment });
+        log(`Reloaded the .env cascade — ${path.join(dir, filename)} changed`);
+      }, debounceMs);
+    });
+
+    // UNREF'd: this watch rides ALONG with a dev lane, it never IS one. An
+    // open fs.watch holds the event loop, so a ref'd handle would leave gulp
+    // running forever after the app it served quits (desktop's `serve` ends
+    // its task on electron's exit, and nothing else keeps that process up).
+    watcher.unref();
+    watchers.push(watcher);
+  }
+
+  return {
+    inputs,
+    close: () => {
+      clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+    },
+  };
+}
+
+module.exports = { envChainWatchInputs, watchEnvChain, DEBOUNCE_MS };

package/dist/vendor/devkit/framework-deps.js

@@ -0,0 +1,46 @@
+// framework-deps — the ONE reader of a framework's declared dependency set (#87).
+//
+// The contract it serves: a CONSUMER may import any library the framework declares
+// by BARE specifier, and it resolves from the FRAMEWORK's own installation — the
+// framework's copy wins (one copy per bundle, shared with the framework code that
+// uses it), and anything the framework does not declare is untouched and fails with
+// the bundler's normal resolution error.
+//
+// `bundle.js` wires the esbuild resolve hook around this reader, so every
+// framework bundling through it gets the contract (it was @omega.js/web's own
+// hook in packages/web/src/assets.js until #736). @omega.js/desktop bundles
+// through the same hook since #737, @omega.js/extension since #738 — where it
+// replaced webpack's `resolve.modules` ordering, which also won for the
+// transitives the framework merely carries, a trade this reader does NOT make.
+// See docs/devkit/index.md and #87.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * The set of libraries a consumer may import by BARE specifier: every package the
+ * framework declares as a dependency — no hand-curated list, the declared set IS
+ * the list. `@omega.js/*` deps are excluded: the client is wired explicitly by each
+ * framework and the private packages are vendored, so neither resolves through
+ * node_modules here.
+ * @param {string} frameworkRoot - the framework package's root (the dir holding its package.json)
+ * @returns {string[]} dependency names
+ */
+function frameworkDependencyNames(frameworkRoot) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(frameworkRoot, 'package.json'), 'utf8'));
+  return Object.keys(pkg.dependencies || {}).filter((name) => !name.startsWith('@omega.js/'));
+}
+
+/**
+ * A matcher for those names: the bare specifier and any subpath of it
+ * (`chart.js`, `chart.js/auto`), and nothing else — so the hook stays off every
+ * other import the bundler resolves.
+ * @param {string[]} names - dependency names
+ * @returns {RegExp} the matcher
+ */
+function frameworkDepsPattern(names) {
+  const escaped = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`^(${escaped.join('|')})(/|$)`);
+}
+
+module.exports = { frameworkDependencyNames, frameworkDepsPattern };

package/dist/vendor/devkit/icons.js

@@ -0,0 +1,178 @@
+/**
+ * Font Awesome build-side helpers (C4 cp111/112) — ONE implementation for
+ * every target that assembles an icon set at build time (web site builds,
+ * extension dist builds; desktop resolves at runtime in its own main lib).
+ *
+ * Root resolution, best-first:
+ *
+ *   1. OMEGA_FONTAWESOME_ROOT — a fontawesome.com "Pro for Web" download
+ *      dir (contains svgs/ + metadata/); no npm token needed.
+ *   2. @fortawesome/fontawesome-pro — installed by the brand with its own
+ *      FA npm token. NEVER a dependency of any omega package (license).
+ *   3. @fortawesome/fontawesome-free — the declared-dependency floor
+ *      (web, desktop, extension all declare it).
+ *
+ * Every available rung stays in the chain, so a partial supply (an old
+ * solid-only download) never loses icons a lower rung has. Preference
+ * order itself is icon-core's PACKAGES — shared with desktop's runtime
+ * icon server and the browser renderer so no surface can drift.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  PACKAGES, ICONS_DIR, candidateRelPaths, buildAliasMap,
+} = require('@omega.js/client/modules/icon-core.js');
+
+/**
+ * Resolve the icon roots for a build.
+ *
+ * @param {object} [env] - Environment map (injectable for tests).
+ * @returns {{ svgsDirs: string[], aliasFile: string, source: 'env'|'pro'|'free' }}
+ *   svgsDirs — ordered svgs/ dirs (brand set first when present, free last);
+ *   aliasFile — the richest icon-families.json available;
+ *   source — where the winning set came from.
+ */
+function resolveFontAwesomeRoots(env = process.env) {
+  const roots = [];
+  let source = 'free';
+
+  const envRoot = env.OMEGA_FONTAWESOME_ROOT;
+  if (envRoot && fs.existsSync(path.join(envRoot, 'svgs'))) {
+    roots.push(envRoot);
+    source = 'env';
+  }
+
+  try {
+    roots.push(path.dirname(require.resolve(`${PACKAGES[0]}/package.json`)));
+    if (source === 'free') source = 'pro';
+  } catch (e) {
+    // Pro npm set not installed — the normal case for brands without a token
+  }
+
+  roots.push(path.dirname(require.resolve(`${PACKAGES[PACKAGES.length - 1]}/package.json`)));
+
+  const aliasRoot = roots.find((root) => fs.existsSync(path.join(root, 'metadata', 'icon-families.json')))
+    || roots[roots.length - 1];
+  return {
+    svgsDirs: roots.map((root) => path.join(root, 'svgs')),
+    aliasFile: path.join(aliasRoot, 'metadata', 'icon-families.json'),
+    source,
+  };
+}
+
+/**
+ * Emit the merged icon set into a build output — feeds the browser-side
+ * auto-render (@omega.js/client icon-renderer): web fetches from the
+ * site's own /assets/icons/, extension pages from
+ * chrome.runtime.getURL('assets/icons/…'). Only icons a page actually uses
+ * ever transfer.
+ *
+ * @param {object} options
+ * @param {string} options.outDir - Build output dir (_site, dist).
+ * @param {string} [options.coreIconsDir] - Curated core icons (highest priority).
+ * @param {string[]} [options.svgsDirs] - Ordered svgs dirs, best-first
+ *   (defaults to the resolved chain).
+ * @returns {{ files: number, dest: string }} Emitted file count + dir.
+ */
+function emitIcons(options) {
+  const svgsDirs = options.svgsDirs || resolveFontAwesomeRoots().svgsDirs;
+  const dest = path.join(options.outDir, 'assets', ICONS_DIR);
+
+  // Lowest priority first — later copies overwrite, so the chain's best
+  // source (and finally the curated core set) wins per file.
+  const sources = [...svgsDirs].reverse();
+  if (options.coreIconsDir && fs.existsSync(options.coreIconsDir)) {
+    sources.push(options.coreIconsDir);
+  }
+
+  for (const dir of sources) {
+    if (fs.existsSync(dir)) {
+      fs.cpSync(dir, dest, { recursive: true, force: true });
+    }
+  }
+
+  let files = 0;
+  for (const entry of fs.readdirSync(dest, { recursive: true, withFileTypes: true })) {
+    if (entry.isFile()) files++;
+  }
+  return { files, dest };
+}
+
+/**
+ * The flag set carries hardcoded width/height="512" on the root — strip them
+ * so icon-core's standard 1em inline-icon sizing applies (Font Awesome
+ * sources never carry dimensions; the flags are the exception).
+ *
+ * @param {string} svg - Raw SVG source.
+ * @returns {string} SVG with any root width/height removed.
+ */
+function stripRootSize(svg) {
+  return svg.replace(/<svg([^>]*)>/, (match, attrs) => `<svg${attrs.replace(/\s(?:width|height)="[^"]*"/g, '')}>`);
+}
+
+/**
+ * A build-time icon reader over a resolved chain — the file-reading half of
+ * icon-core, which owns every decision ABOUT the files (candidate order,
+ * aliases) but reads none of them. Web's build-time inlining pass
+ * (@omega.js/web src/inline-icons.js) is the caller; the browser reads the
+ * SAME bytes at runtime out of what `emitIcons` shipped.
+ *
+ * Aliases and file contents are cached for the process — a site inlines the
+ * same chrome icons on every one of its pages.
+ *
+ * @param {object} options
+ * @param {string[]} options.svgsDirs - Ordered icon roots, best-first (each
+ *   holding `<style>/<name>.svg`).
+ * @param {string} [options.aliasFile] - icon-families.json for alias
+ *   resolution ('search' → 'magnifying-glass').
+ * @returns {function(string, string): (string|null)} (name, style) → raw SVG.
+ */
+function createIconLoader(options) {
+  const dirs = options.svgsDirs || [];
+  const cache = new Map();
+  let aliases = null;
+
+  const aliasFor = (name) => {
+    if (!aliases) {
+      aliases = new Map();
+      try {
+        aliases = buildAliasMap(JSON.parse(fs.readFileSync(options.aliasFile, 'utf8')));
+      } catch {
+        // No (readable) metadata in this chain — resolve without aliases.
+      }
+    }
+    return aliases.get(name) || null;
+  };
+
+  return function loadIcon(name, style) {
+    const key = `${style}/${name}`;
+    if (cache.has(key)) return cache.get(key);
+
+    const alias = aliasFor(name);
+    let svg = null;
+
+    for (const dir of dirs) {
+      for (const candidate of (alias ? [name, alias] : [name])) {
+        for (const rel of candidateRelPaths(candidate, style)) {
+          try {
+            svg = fs.readFileSync(path.join(dir, rel), 'utf8');
+          } catch {
+            continue;
+          }
+          break;
+        }
+        if (svg) break;
+      }
+      if (svg) break;
+    }
+
+    if (svg) svg = stripRootSize(svg);
+    cache.set(key, svg);
+    return svg;
+  };
+}
+
+// ICONS_DIR is icon-core's, re-exported here so the build side has one import
+// for the whole icon contract.
+module.exports = { ICONS_DIR, resolveFontAwesomeRoots, emitIcons, createIconLoader };