@omega.js/web 0.1.0

package/dist/minify-html.js

@@ -0,0 +1,148 @@
+/**
+ * Production HTML minification — the UJM minifyHtml successor, as an
+ * Eleventy transform (engine.js mounts it for production builds only; dev
+ * and the test harness ship readable HTML). The Rust minifier
+ * (@minify-html/node) does the heavy lifting; three content classes are
+ * extracted first and restored after, exactly the legacy dance:
+ *
+ *   1. JSON-LD scripts — minified as JSON (parse → stringify; unparseable
+ *      blocks pass through verbatim), because the HTML minifier can mangle
+ *      structured data.
+ *   2. Inline scripts (no src, not JSON-LD) — minified with esbuild
+ *      (already a dependency; legacy used terser because minify-html's
+ *      built-in JS minifier was buggy — it stays off here too). A script
+ *      esbuild can't parse ships verbatim.
+ *   3. IE conditional comments — keep_comments is off, which would strip
+ *      them; they're restored verbatim (head.html still carries one).
+ *
+ * Ordinary comments go FIRST, before any of that, scanning left to right:
+ * a `<script` mentioned inside a comment is comment text, and a `<!--` inside
+ * a script body is script text. The extraction regexes alone could not tell
+ * (#762: a head comment saying "plain <script src> fetches" was read as a
+ * script running to the motion stamp's `</script>`, the comment's `-->` went
+ * with it, and the minifier ate every tag up to the next comment close).
+ *
+ * A page that fails to minify ships unminified — never a failed build. A
+ * placeholder the minifier lost counts as a failure: the page ships whole.
+ */
+const { minify } = require('@minify-html/node');
+const esbuild = require('esbuild');
+
+// UJM's proven option set. minify_js stays OFF: inline scripts are
+// extracted and esbuild-minified instead (minify-html's JS pass is buggy).
+const MINIFY_OPTIONS = {
+  keep_closing_tags: false,
+  keep_comments: false,
+  keep_html_and_head_opening_tags: false,
+  keep_spaces_between_attributes: false,
+  keep_ssi_comments: false,
+  minify_css: true,
+  minify_js: false,
+  remove_bangs: false,
+  remove_processing_instructions: false,
+};
+
+const JSON_LD_REGEX = /<script[^>]*type=(?:["']?application\/ld\+json["']?)[^>]*>([\s\S]*?)<\/script>/gi;
+// Inline scripts only: no src attribute, not JSON-LD (already extracted)
+const INLINE_SCRIPT_REGEX = /<script(?![^>]*type=(?:["']?application\/ld\+json["']?))(?![^>]*\bsrc=)([^>]*)>([\s\S]*?)<\/script>/gi;
+const CONDITIONAL_COMMENT_REGEX = /<!--\[if[\s\S]*?<!\[endif\]-->/gi;
+// One left-to-right scan: whichever of a comment, a script or a style starts
+// first owns everything up to its own close. Conditional comments are not
+// ordinary comments (the lookahead leaves them for step 3).
+const COMMENT_OR_RAW_TEXT_REGEX = /<!--(?!\[if)[\s\S]*?-->|<script\b[\s\S]*?<\/script>|<style\b[\s\S]*?<\/style>/gi;
+
+/**
+ * Drop every ordinary HTML comment, leaving script and style bodies alone.
+ * @param {string} html
+ * @returns {string}
+ */
+function stripComments(html) {
+  return html.replace(COMMENT_OR_RAW_TEXT_REGEX, (match) => (match.startsWith('<!--') ? '' : match));
+}
+
+/**
+ * Replace every regex match with an indexed placeholder token.
+ * @param {string} html
+ * @param {RegExp} regex
+ * @param {string} token - placeholder stem, e.g. 'JSON_LD'
+ * @param {function} capture - (match, ...groups) → string stored for restore
+ * @returns {{ content: string, extracted: string[] }}
+ */
+function extract(html, regex, token, capture) {
+  const extracted = [];
+  const content = html.replace(regex, (...args) => {
+    extracted.push(capture(...args));
+    return `__OMEGA_${token}_${extracted.length - 1}__`;
+  });
+  return { content, extracted };
+}
+
+/**
+ * Swap placeholder tokens back for their stored strings.
+ * @param {string} html
+ * @param {string} token
+ * @param {string[]} extracted
+ * @returns {string}
+ */
+function restore(html, token, extracted) {
+  return extracted.reduce((content, block, index) => {
+    const placeholder = `__OMEGA_${token}_${index}__`;
+    if (!content.includes(placeholder)) {
+      // The minifier ate the placeholder (a comment or raw-text context we
+      // failed to see swallowed it), so the page cannot be trusted: throw, and
+      // minifyHtml() ships it unminified rather than truncated (#762)
+      throw new Error(`minify-html lost ${placeholder}`);
+    }
+    return content.replace(placeholder, () => block);
+  }, html);
+}
+
+/**
+ * Minify one rendered HTML page. Synchronous — mounted directly as an
+ * Eleventy transform.
+ * @param {string} html
+ * @returns {string} minified page (or the input verbatim if minification throws)
+ */
+function minifyHtml(html) {
+  try {
+    // 0. Ordinary comments out for good (keep_comments is off anyway), so no
+    //    extraction below can match markup a comment merely talks about
+    const stripped = stripComments(html);
+
+    // 1. JSON-LD out (minified as JSON, not HTML)
+    const jsonLd = extract(stripped, JSON_LD_REGEX, 'JSON_LD', (match, body) => {
+      try {
+        return `<script type=application/ld+json>${JSON.stringify(JSON.parse(body))}</script>`;
+      } catch (error) {
+        return match;
+      }
+    });
+
+    // 2. Inline scripts out (esbuild-minified; attributes preserved)
+    const scripts = extract(jsonLd.content, INLINE_SCRIPT_REGEX, 'SCRIPT', (match, attrs, body) => {
+      if (!body.trim()) {
+        return match;
+      }
+      try {
+        const minified = esbuild.transformSync(body, { minify: true }).code.trimEnd();
+        return `<script${attrs}>${minified}</script>`;
+      } catch (error) {
+        return match;
+      }
+    });
+
+    // 3. IE conditional comments out (keep_comments: false would eat them)
+    const conditionals = extract(scripts.content, CONDITIONAL_COMMENT_REGEX, 'IE_COMMENT', (match) => match);
+
+    let minified = minify(Buffer.from(conditionals.content), MINIFY_OPTIONS).toString();
+
+    minified = restore(minified, 'IE_COMMENT', conditionals.extracted);
+    minified = restore(minified, 'SCRIPT', scripts.extracted);
+    minified = restore(minified, 'JSON_LD', jsonLd.extracted);
+    return minified;
+  } catch (error) {
+    return html;
+  }
+}
+
+module.exports = { minifyHtml };

package/dist/mode-helpers.js

@@ -0,0 +1,96 @@
+/**
+ * The environment surface ([#717](https://github.com/Omega-JS-Stack/omega/issues/717))
+ * — the same four calls the three sibling frameworks answer
+ * (@omega.js/backend's Manager, @omega.js/desktop's and @omega.js/extension's
+ * mode-helpers): `getEnvironment()` plus `isDevelopment()` / `isProduction()` /
+ * `isTesting()`. Web used to be the outlier: a bare `options.environment`
+ * string threaded positionally through the build, reachable from nothing.
+ *
+ * `getEnvironment()` is the SINGLE SOURCE OF TRUTH — the ONLY function that
+ * reads the raw signals and resolves them to exactly ONE of three
+ * mutually-exclusive values. The three is*() checks DERIVE from it, so they can
+ * never disagree with it: `isDevelopment()` is NOT true in testing, and
+ * `isProduction()` is a real positive check, never `!isDevelopment()`. Gate
+ * "anything non-production" with `!isProduction()` or `isDevelopment() ||
+ * isTesting()` intentionally.
+ *
+ * The vocabulary is @omega.js/config's (`ENV_ENVIRONMENTS`, #586) — the same
+ * three names the `.env.<environment>` overlay files are spelled with — so a
+ * `.env.development` and an `isDevelopment()` can never mean different things.
+ *
+ * Web's contexts are the plain options objects the build lanes already thread
+ * (`{ environment, consumerDir, … }`), not Manager instances, so the surface is
+ * called on one: `getEnvironment.call(options)`. It is mixed into web's Manager
+ * equivalent — the CLI Main class (src/cli.js) — by attachTo() below.
+ */
+const { ENV_ENVIRONMENTS } = require('./vendor/config/index.js');
+
+/**
+ * The running environment, resolved from every raw signal.
+ * Precedence: testing → the context's explicit environment → build signals →
+ * development.
+ * @returns {'development'|'testing'|'production'} exactly one of the three
+ */
+function getEnvironment() {
+  // 1. Testing wins — a test run is not development, whatever else says.
+  if (process.env.OMEGA_TEST_MODE === 'true') return 'testing';
+
+  // 2. The context's own environment: the deliberate value web's verbs already
+  //    thread (`omega build` → production, `omega dev` → development) and the
+  //    build lanes pass down. It beats the ambient signals, exactly as
+  //    @omega.js/desktop's config override beats its auto-detected packaged state.
+  if (this && ENV_ENVIRONMENTS.includes(this.environment)) return this.environment;
+
+  // 3. Build-time / Node signals.
+  if (process.env.OMEGA_BUILD_MODE === 'true') return 'production';
+  if (process.env.NODE_ENV === 'production') return 'production';
+  if (process.env.NODE_ENV === 'development') return 'development';
+
+  // 4. Default: development. Web's deployed artifact is static HTML emitted by
+  //    a build that CARRIED its signal (the production environment is baked
+  //    into build.json at emit time), so reaching here means a bare tooling
+  //    context, where development is the sensible answer. (Contrast
+  //    @omega.js/backend and @omega.js/desktop, whose deployed RUNTIME can
+  //    legitimately lack a signal, so they default to production.)
+  return 'development';
+}
+
+/**
+ * @returns {boolean} true only in development (never in testing)
+ */
+function isDevelopment() {
+  return getEnvironment.call(this) === 'development';
+}
+
+/**
+ * @returns {boolean} true only in production — a real positive check
+ */
+function isProduction() {
+  return getEnvironment.call(this) === 'production';
+}
+
+/**
+ * @returns {boolean} true only while web's test framework runs this process
+ */
+function isTesting() {
+  return getEnvironment.call(this) === 'testing';
+}
+
+/**
+ * Mix the surface into a Manager constructor's prototype AND the constructor
+ * itself, so `Manager.isTesting()` works statically too — the idiom
+ * @omega.js/desktop and @omega.js/extension attach with.
+ * @param {Function} Manager - the constructor to extend
+ */
+function attachTo(Manager) {
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.getEnvironment = getEnvironment;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+}
+
+module.exports = { attachTo, getEnvironment, isDevelopment, isProduction, isTesting };

package/dist/omega-bin.js

@@ -0,0 +1,7 @@
+// Entry for the `omega`/`omg` bins — dispatches to the framework that owns the
+// cwd's target (this one, or a sibling target's framework in a brand monorepo).
+// @omega.js/web serves src/ directly (no dist), so devkit resolves live here.
+require('./vendor/devkit/omega-bin.js').run({
+  hostName: '@omega.js/web',
+  hostRun: () => require('./cli-run.js').run(),
+});

package/dist/overrides.js

@@ -0,0 +1,190 @@
+/**
+ * The layered override map (#94) — what `omega customize --list` prints and
+ * what `omega customize <path>` materializes.
+ *
+ * A consumer overrides a framework file by OWNING the same relative path; until
+ * now nothing listed those paths, so restyling one section meant reading the
+ * theme source tree. This module answers both questions from the SAME layer
+ * chains the build resolves through (`resolveThemeLayers` + `collectProviders`
+ * in ./layers.js) — never a second table of layer order:
+ *
+ * - sections/components — consumer → active theme → base (engine.js hands
+ *   registerSectionTags exactly these bases; core owns no entries). Resolution
+ *   is per ENTRY, not per file: the layer owning `section.html` wins the whole
+ *   folder unless the winner declares `inherit` (docs/web/sections.md), so a
+ *   materialized asset file carries that note.
+ * - includes — consumer → theme layers → core (engine.js includeRoots).
+ * - css — ONLY `main.scss`, the one stylesheet the sass layer chain RESOLVES
+ *   (assets.js): the first layer that ships one wins, and it extends the layers
+ *   below with `@use 'omega:main'`. Page and layout sheets are deliberately
+ *   absent (#624): every layer's sheet for a key loads, so a consumer's copy
+ *   shadows nothing — materializing one would duplicate every rule it carries
+ *   rather than replace it. Every other stylesheet is reached by a bare relative
+ *   `@import`/`@use`, which Dart Sass resolves relative to the IMPORTING file
+ *   before any loadPath — a consumer copy of `css/base/_utilities.scss` never
+ *   loads. Listing either kind would hand a consumer a file that does the wrong
+ *   thing, so the map lists neither. Paths carry the `assets/` prefix because
+ *   the consumer's css layer root is `src/assets`.
+ * - pages — the URL-addressable default pages, straight from ./customize.js's
+ *   listCustomizable (the page lane keeps its own two materialize modes).
+ *
+ * Every non-page path in the map is CONSUMER-RELATIVE (`src/`), so the string
+ * `--list` prints is the string `omega customize <path>` takes and the place
+ * the copy lands.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { collectProviders, resolveThemeLayers } = require('./layers.js');
+const { listCustomizable } = require('./customize.js');
+const { PATHS } = require('./paths.js');
+
+// The one css lane the sass build RESOLVES by layer (assets.js).
+const CSS_MAIN = /^main\.scss$/;
+// Section entries are folders of these four files.
+const SECTION_ENTRY = /^(?:.*\/)?(section|component)\.(html|scss|js|json5)$/;
+
+/**
+ * The ordered layer roots per lane, labelled by owning layer.
+ * @param {object} options
+ * @param {string} options.consumerDir - the consumer's src dir
+ * @param {object} [options.siteData] - resolved config (theme.id names the active theme)
+ * @returns {Array<{ kind: string, subdirs: string[], prefix: string, roots: Array<{dir: string, layer: string}>, filter: RegExp|undefined }>}
+ */
+function overrideLanes({ consumerDir, siteData }) {
+  const themeRoots = resolveThemeLayers({
+    activeTheme: siteData?.theme?.id,
+    consumerDir,
+    themesDir: PATHS.themes,
+  }).map((dir) => ({ dir, layer: `theme:${path.basename(dir)}` }));
+
+  const consumer = { dir: consumerDir, layer: 'consumer' };
+  const consumerAssets = { dir: path.join(consumerDir, 'assets'), layer: 'consumer' };
+  const core = { dir: PATHS.core, layer: 'framework' };
+
+  return [
+    { kind: 'section', subdirs: ['_sections', '_components'], prefix: '', roots: [consumer, ...themeRoots], filter: SECTION_ENTRY },
+    { kind: 'include', subdirs: ['_includes'], prefix: '', roots: [consumer, ...themeRoots, core], filter: undefined },
+    // main.scss layers across the whole chain — the one sheet a consumer copy
+    // takes over rather than joins
+    { kind: 'css', subdirs: ['css'], prefix: 'assets/', roots: [consumerAssets, ...themeRoots, core], filter: CSS_MAIN },
+  ];
+}
+
+/**
+ * Every shadowable file, with its owning layer and whether the consumer
+ * already shadows it.
+ * @param {object} options
+ * @param {string} options.consumerDir - the consumer's src dir
+ * @param {object} [options.siteData]
+ * @returns {Array<object>} entries — { kind, path, layer, shadowed, source, shadows, target }
+ */
+function buildOverrideMap({ consumerDir, siteData }) {
+  const entries = [];
+
+  for (const lane of overrideLanes({ consumerDir, siteData })) {
+    const layerOf = new Map();
+    for (const root of lane.roots) {
+      for (const subdir of lane.subdirs) layerOf.set(path.join(root.dir, subdir), root.layer);
+    }
+
+    for (const subdir of lane.subdirs) {
+      const dirs = lane.roots.map((root) => path.join(root.dir, subdir));
+
+      for (const [rel, providers] of collectProviders(dirs, lane.filter)) {
+        const stack = providers.map(({ dir, file }) => ({ layer: layerOf.get(dir), file }));
+        const shadowPath = `${lane.prefix}${path.join(subdir, rel)}`;
+        const framework = stack.find((provider) => provider.layer !== 'consumer') || null;
+
+        entries.push({
+          kind: lane.kind,
+          path: shadowPath,
+          layer: stack[0].layer,
+          shadowed: stack[0].layer === 'consumer',
+          // What a materialize would copy: the file the consumer would shadow
+          source: framework && framework.file,
+          shadows: stack.slice(1).map((provider) => provider.layer),
+          target: path.join(consumerDir, shadowPath),
+        });
+      }
+    }
+  }
+
+  // Pages keep their own lane — URL-addressable, two materialize modes
+  for (const page of listCustomizable({ consumerDir, siteData })) {
+    entries.push({
+      kind: 'page',
+      path: page.url,
+      layer: page.owned ? 'consumer' : 'framework',
+      shadowed: Boolean(page.owned),
+      lane: page.lane,
+      source: null,
+      shadows: [],
+      target: page.owned || null,
+    });
+  }
+
+  return entries.sort((a, b) => a.kind.localeCompare(b.kind) || a.path.localeCompare(b.path));
+}
+
+/**
+ * The provenance header for a materialized file, in the file's own comment
+ * syntax. JSON carries no comments, so it gets none.
+ * The first line opens with the `omega:consumer-override:` marker on purpose
+ * ([#452](https://github.com/Omega-JS-Stack/omega/issues/452)): a materialize
+ * IS the deliberate consumer copy, so the omega:guard hook — which reads the
+ * first five lines — has to see it declared without anybody typing it back in.
+ * @param {object} entry - a map entry
+ * @param {string[]} [notes] - extra lines
+ * @returns {string} the header (empty when the format has no comment form)
+ */
+function provenanceHeader(entry, notes = []) {
+  const lines = [
+    `omega:consumer-override: materialized by omega customize ${entry.path} — a copy of the ${entry.layer} layer's file.`,
+    'This consumer file now SHADOWS it. Delete it to return to the framework\'s.',
+    ...notes,
+  ];
+  const extension = path.extname(entry.path);
+
+  if (['.html', '.liquid', '.md'].includes(extension)) {
+    return `{% comment %}\n${lines.map((line) => `  ${line}`).join('\n')}\n{% endcomment %}\n`;
+  }
+  if (['.scss', '.css', '.js', '.json5'].includes(extension)) {
+    return `${lines.map((line) => `// ${line}`).join('\n')}\n`;
+  }
+  return '';
+}
+
+/**
+ * Materialize ONE shadowable file into the consumer tree. Idempotent: an
+ * existing consumer file is never overwritten — the caller is told it exists.
+ * @param {object} options
+ * @param {string} options.path - a map path (`_includes/…`, `assets/css/…`)
+ * @param {string} options.consumerDir
+ * @param {object} [options.siteData]
+ * @returns {object} { status: 'created'|'exists'|'unknown', ... }
+ */
+function materializeOverride({ path: shadowPath, consumerDir, siteData }) {
+  const wanted = String(shadowPath || '').trim().replace(/^\.?\//, '');
+  const map = buildOverrideMap({ consumerDir, siteData });
+  const entry = map.find((candidate) => candidate.kind !== 'page' && candidate.path === wanted);
+
+  if (!entry) return { status: 'unknown', path: wanted, known: map.filter((c) => c.kind !== 'page').map((c) => c.path) };
+  if (entry.shadowed || fs.existsSync(entry.target)) return { ...entry, status: 'exists' };
+
+  // Sections resolve per entry: shadowing an asset lane alone changes nothing
+  // unless the winning section.html moves too (or declares inherit).
+  const notes = entry.kind === 'section' && !/\.html$/.test(entry.path)
+    ? [
+      'Sections resolve per ENTRY: the layer owning section.html wins the whole',
+      'folder. Shadow the entry\'s .html too, or declare `inherit` in its json5.',
+    ]
+    : [];
+
+  const header = provenanceHeader(entry, notes);
+  fs.mkdirSync(path.dirname(entry.target), { recursive: true });
+  fs.writeFileSync(entry.target, header + fs.readFileSync(entry.source, 'utf8'));
+
+  return { ...entry, status: 'created', headed: Boolean(header) };
+}
+
+module.exports = { buildOverrideMap, materializeOverride, overrideLanes };

package/dist/path-prefix.js

@@ -0,0 +1,167 @@
+/**
+ * Base-path support (#355) — the build-time half of serving a site under a URL
+ * PATH instead of a domain root (`https://<user>.github.io/<repo>/`, the
+ * GitHub Pages project-site case). Every URL the build writes is root-relative,
+ * so a site mounted under a path asks the DOMAIN root for its assets and 404s.
+ *
+ * The base path is a PUBLISHER input, never an end-user one: whatever machinery
+ * publishes the site knows its mount point (workkit's publish reads it off the
+ * Pages API) and exports `OMEGA_PATH_PREFIX` around `omega build`. Hosts that
+ * serve at the domain root (Netlify, Vercel, a custom domain) pass nothing.
+ *
+ * Three emit lanes carry it, one mechanism each:
+ *   HTML - the `omega-path-prefix` Eleventy transform (src/engine.js), which
+ *          rewrites the URL attributes of a rendered page and stamps the value
+ *          on <html> for the browser half. The asset MANIFEST stays
+ *          root-relative on purpose: it is an internal index, and the transform
+ *          is the ONE place its URLs become markup — prefixing both would
+ *          mount them twice.
+ *   CSS  - the emit step in src/assets.js (theme sheets carry
+ *          `url(/assets/fonts/…)`, which no HTML pass can reach).
+ *   JS   - core/js/libs/path-prefix.js, the browser helper that reads the
+ *          stamp; nothing is baked into a bundle.
+ *
+ * An unset (or `/`) prefix is a no-op everywhere — the transform is not even
+ * registered — so today's output is unchanged byte for byte.
+ */
+
+const { mapSrcset } = require('./srcset.js');
+
+// The attributes a browser resolves as a URL. The lookbehind keeps `data-src`,
+// `data-srcset` and friends out of scope (same guard cachebreak-html.js uses):
+// those are runtime-consumed values, and the browser half mounts them itself.
+const URL_ATTR_PATTERN = /(?<![-\w])(href|src|srcset|action)=(?:"([^"]*)"|'([^']*)')/gi;
+
+// A url() target in emitted CSS, with or without quotes.
+const CSS_URL_PATTERN = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^'")]*))\s*\)/gi;
+
+/**
+ * Normalize a publisher-supplied base path. External input, so it is treated
+ * defensively: leading slash ensured, trailing slashes stripped, inner doubles
+ * collapsed. `/` (and anything empty) means "serves at the domain root" and
+ * normalizes to '' — the no-op every lane tests for.
+ * @param {string|undefined|null} value - e.g. process.env.OMEGA_PATH_PREFIX
+ * @returns {string} '' (no prefix) or a normalized '/base' with no trailing slash
+ */
+function resolvePathPrefix(value) {
+  const trimmed = String(value == null ? '' : value).trim();
+  const prefix = `/${trimmed}`.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+
+  return prefix === '/' ? '' : prefix;
+}
+
+/**
+ * Mount one URL under the base path. Only ROOT-RELATIVE URLs move: absolute
+ * and protocol-relative URLs belong to another origin, and bare-relative ones
+ * (and anchors, mailto:, data: …) already resolve against the mounted page.
+ * @param {string} url
+ * @param {string} prefix - resolvePathPrefix output
+ * @returns {string}
+ */
+function prefixUrl(url, prefix) {
+  if (!prefix) return url;
+
+  const value = String(url);
+  if (!value.startsWith('/') || value.startsWith('//')) return value;
+
+  return `${prefix}${value}`;
+}
+
+/**
+ * The inverse of prefixUrl: the SITE-relative path of an already mounted URL.
+ * Post-build passes that reason about routes (the translation pass composes
+ * prefix-then-lang, #359) need the route the build knows, not the mounted one.
+ * A path that does not carry the prefix is returned as it came.
+ * @param {string} pathname - a root-relative path
+ * @param {string} prefix - resolvePathPrefix output
+ * @returns {string}
+ */
+function stripPathPrefix(pathname, prefix) {
+  const value = String(pathname);
+  if (!prefix || !(value === prefix || value.startsWith(`${prefix}/`))) return value;
+
+  return value.slice(prefix.length) || '/';
+}
+
+/**
+ * The base path a built page carries. prefixHtml stamps the mount point on
+ * <html> for the browser half, and that stamp is equally the record a
+ * post-build pass reads instead of re-plumbing the publisher's value.
+ * @param {string} html - a built page
+ * @returns {string} resolvePathPrefix output ('' when the page is unmounted)
+ */
+function readPathPrefixStamp(html) {
+  const match = /<html\b[^>]*\bdata-omega-path-prefix="([^"]*)"/i.exec(String(html));
+
+  return resolvePathPrefix(match ? match[1] : '');
+}
+
+/**
+ * The base path a whole BUILD carries, off the stamp `prefixHtml` leaves on
+ * <html> — one answer for the post-build passes that read a dist page by page
+ * (the #468 audit, the #430 link check). '' (an unmounted site) is what most
+ * builds answer, and the first stamped page settles it: one build, one mount.
+ * @param {Iterable<string>} pages - the built pages' HTML
+ * @returns {string} resolvePathPrefix output
+ */
+function readBuildPathPrefix(pages) {
+  for (const html of pages) {
+    const stamp = readPathPrefixStamp(html);
+    if (stamp) return stamp;
+  }
+
+  return '';
+}
+
+/**
+ * Rewrite a rendered page for a mounted site: every root-relative URL
+ * attribute moves under the base path, and <html> carries the value so the
+ * browser half (core/js/libs/path-prefix.js) can build URLs too.
+ * @param {string} html - rendered page
+ * @param {string} prefix - resolvePathPrefix output ('' → the page is returned as-is)
+ * @returns {string}
+ */
+function prefixHtml(html, prefix) {
+  if (!prefix) return html;
+
+  const mounted = String(html).replace(
+    URL_ATTR_PATTERN,
+    (attr, name, doubleQuoted, singleQuoted) => {
+      const value = doubleQuoted !== undefined ? doubleQuoted : singleQuoted;
+      const quote = doubleQuoted !== undefined ? '"' : "'";
+      const next = name.toLowerCase() === 'srcset'
+        ? mapSrcset(value, (url) => prefixUrl(url, prefix))
+        : prefixUrl(value, prefix);
+
+      return `${name}=${quote}${next}${quote}`;
+    },
+  );
+
+  // Stamped AFTER the rewrite, so the value itself can never be mounted twice.
+  return mounted.replace(/<html\b/i, `<html data-omega-path-prefix="${prefix}"`);
+}
+
+/**
+ * Rewrite an emitted stylesheet for a mounted site — the @font-face and
+ * background url() targets theme sheets write root-relative.
+ * @param {string} css - compiled stylesheet
+ * @param {string} prefix - resolvePathPrefix output ('' → the sheet is returned as-is)
+ * @returns {string}
+ */
+function prefixCss(css, prefix) {
+  if (!prefix) return css;
+
+  return String(css).replace(
+    CSS_URL_PATTERN,
+    (match, doubleQuoted, singleQuoted, bare) => {
+      const value = doubleQuoted ?? singleQuoted ?? bare;
+      const next = prefixUrl(value, prefix);
+      if (next === value) return match;
+
+      const quote = doubleQuoted !== undefined ? '"' : (singleQuoted !== undefined ? "'" : '');
+      return `url(${quote}${next}${quote})`;
+    },
+  );
+}
+
+module.exports = { resolvePathPrefix, prefixUrl, stripPathPrefix, readPathPrefixStamp, readBuildPathPrefix, prefixHtml, prefixCss };

package/dist/paths.js

@@ -0,0 +1,37 @@
+/**
+ * Packaged framework content locations — the theme layers, core assets
+ * (icons/logos/css/js), default pages, and the default-page translations that
+ * ship WITH @omega.js/web.
+ * Engine and build entry points default to these; tests and harnesses may
+ * override per call.
+ */
+const path = require('node:path');
+
+const PKG = path.resolve(__dirname, '..');
+
+const PATHS = {
+  themes: path.join(PKG, 'themes'),
+  core: path.join(PKG, 'core'),
+  defaults: path.join(PKG, 'defaults'),
+  scaffold: path.join(PKG, 'scaffold'),
+  runtime: path.join(PKG, 'runtime'),
+  // The default-page translations the framework ships (#621) — the cache
+  // src/translate/packaged-defaults.js reads and generate-defaults.js writes.
+  translations: path.join(PKG, 'translations'),
+};
+
+/**
+ * Resolve the @omega.js/client entry (the `@omega.js/client` esbuild alias target).
+ * In the monorepo this resolves the workspace package; published tarballs
+ * carry a vendored copy (publish wiring is a later gated step).
+ * @returns {string} absolute path to the client entry module
+ */
+function resolveClientEntry() {
+  try {
+    return require.resolve('@omega.js/client');
+  } catch (error) {
+    throw new Error('Could not resolve the @omega.js/client client package — reinstall @omega.js/web (npm install) and retry');
+  }
+}
+
+module.exports = { PATHS, resolveClientEntry };