@mosetta/build 0.0.0-stage → 0.0.10

package/CHANGELOG.md

@@ -0,0 +1,160 @@
+# @mosetta/build
+
+## 0.0.10
+
+### Patch Changes
+
+- 95b93d5: The build's node host is an entry of the build: `@mosetta/build/node` gives the real file system,
+  the framework's files resolved from the installed build, and `buildDirectory(root, …)` — the build
+  of a palette that lies on disk with its dependencies installed, by the build installed for it. The
+  CLI builds with it, and so does a platform's build container: a palette is built by the framework
+  version its lock names. `systemjs`, whose files the build mixes into a page, is a dependency of the
+  build now, not of the CLI.
+  - @mosetta/router@0.0.10
+  - @mosetta/runtime@0.0.10
+  - @mosetta/server@0.0.10
+  - @mosetta/server-action@0.0.10
+  - @mosetta/tar@0.0.10
+
+## 0.0.9
+
+### Patch Changes
+
+- Updated dependencies
+  - @mosetta/runtime@0.0.9
+  - @mosetta/server@0.0.9
+  - @mosetta/server-action@0.0.9
+  - @mosetta/router@0.0.9
+  - @mosetta/tar@0.0.9
+
+## 0.0.8
+
+### Patch Changes
+
+- A project's own tile palette. The registry keeps the palettes a project's site takes tiles from;
+  the factory reads each one's tile host after the platform's, and takes a tile of a host other than
+  the primary only with its integrity. The rule a site's tile hosts merge by lives in
+  `@mosetta/core` (`mergeTileHosts`), so the editor offers the blocks of every tile host of the site
+  by the same rule (`TILE_HOSTS_TOKEN` in `@mosetta/server-action`). The platform's API publishes
+  into `palettes/<brand>` for the members of the project of that namespace, with the palette's stores
+  granted to that one request. `mosetta build --released <descriptor>` leaves out what a platform
+  already holds; `checkPaletteBuild` says what a palette may hold. The CLI's and the build's output
+  speaks the vocabulary: tile palettes, tiles, package tiles.
+- Updated dependencies
+  - @mosetta/server@0.0.8
+  - @mosetta/server-action@0.0.8
+  - @mosetta/runtime@0.0.8
+  - @mosetta/router@0.0.8
+  - @mosetta/tar@0.0.8
+
+## 0.0.7
+
+### Patch Changes
+
+- One vocabulary: code is tiles, content is blueprints, running requests is the factory, and a tile and a
+  blueprint made in the factory give a mosaic. A tile is a folder under `tiles/` (was `modules/`) whose
+  files are its sides, each defined with `define<Side>Side` — `defineComponentSide`, `defineEditorSide`,
+  `defineFallbackSide`, `defineRootComponentSide`, `defineServerSide`, `defineSsrSide` (were
+  `define…Module`); `useTile` (was `useModule`), `markInternalTile`, `BlueprintRoot`,
+  `BlueprintNodeRenderer`. `mosetta.json` names the tile `brand` (was `namespace`; a config that still
+  says `namespace` is refused with the word to use). The store connectors' package is `@mosetta/stores`
+  (was `@mosetta/provider`): `IStoreConnector`, `StoreConnectors`, `tileHostsOf`. The server's runner
+  is the factory gate (`@mosetta/server/factoryGate`, was `/runner`). Nothing on the wire moves: tile
+  ids keep `_ns_`, a build keeps `modules/<id>/`, stored JSON keeps its fields.
+- Updated dependencies
+  - @mosetta/server-action@0.0.7
+  - @mosetta/runtime@0.0.7
+  - @mosetta/server@0.0.7
+  - @mosetta/router@0.0.7
+  - @mosetta/tar@0.0.7
+
+## 0.0.6
+
+### Patch Changes
+
+- A site's code may come from several sources — the host's stores, a project's own distributions, another vendor's. A
+  store of the registry names its source (`source`; none — the host's), and the runner reads every source's public and
+  private catalogs into one: a namespace belongs to the first source holding it, a package to the first that has it
+  (other bytes under its id are said, the first stands). Every entity is read from the source its catalog entry names —
+  blocks, packages and singletons alike, by the runner, the site's renderer and the browser: the page envelope carries a
+  `providers` table (key → base) and the catalog slice the key of each entity. The page no longer says where its code
+  lives: the node's `provider` is gone. A server module runs only when a private catalog of the site names it; a site
+  whose catalogs were never read runs none (503). A build into a target leaves what the target already holds: released
+  library roots and published packages are not built again.
+- Updated dependencies
+  - @mosetta/server@0.0.6
+  - @mosetta/runtime@0.0.6
+  - @mosetta/router@0.0.6
+  - @mosetta/server-action@0.0.6
+  - @mosetta/tar@0.0.6
+
+## 0.0.5
+
+### Patch Changes
+
+- 92417dc: Who may call a server action is the action's to say: every action has an `authorize` (abstract — an action without it
+  does not compile), run after the input is validated and before the action; refused, the call is a 401 when nobody is
+  vouched for and a 403 otherwise. It decides by the input, the request and the caller — what the host vouches for, in
+  the host's own words: the framework passes the identity header's JSON object through whole and knows no roles. The
+  mosetta platform says `{ via, login, email?, roles? }` (`roles: ['editor']` for the site's editors, on server actions);
+  `mosetta dev` vouches for the developer at the machine as an editor. `<name>.public.ts` and the runner's check of it
+  are gone: the platform's gate no longer decides for actions, and only keeps a visitor's calls within bounds.
+- Updated dependencies [92417dc]
+  - @mosetta/server-action@0.0.5
+  - @mosetta/server@0.0.5
+  - @mosetta/router@0.0.5
+  - @mosetta/runtime@0.0.5
+  - @mosetta/tar@0.0.5
+
+## 0.0.4
+
+### Patch Changes
+
+- 7577aa3: A server module named `<name>.public.ts` answers visitors of the site, not only its editors: it is built, named and
+  called like any server module, and its private descriptor says `public`. A host lets a non-editor's call on as a
+  visitor's — with no identity, limited per site, module and address, a form's size at most — and the runner answers it
+  from a public module only. Opening or closing a module under a version already released is refused.
+- Updated dependencies [7577aa3]
+- Updated dependencies [7577aa3]
+  - @mosetta/server-action@0.0.4
+  - @mosetta/server@0.0.4
+  - @mosetta/router@0.0.4
+  - @mosetta/runtime@0.0.4
+  - @mosetta/tar@0.0.4
+
+## 0.0.3
+
+### Patch Changes
+
+- 1330d5d: Code is published THROUGH a platform: `mosetta push` describes the build (both catalogs, every file with its SHA-256,
+  the commit it comes from), asks the platform's API for a plan and sends the files it asks for — no store key on the
+  publisher's side. The release rules check a fresh module's bytes against the catalog entry that vouches for them, on
+  either path. A runner can grant stores to server actions only (found by name), never read for its own modules — how
+  the platform's API writes code stores whose keys stay with its host; the host names the publish target in a header of
+  its own, beside the caller's identity.
+- 886c43a: The release rules live in `@mosetta/build/release`, portable, for every publisher: `mosetta deploy` runs them against a
+  provider registry, a platform can run them on its side. A release writes each catalog over exactly the copy it planned
+  from and a module file only where none is, so two deploys into one store at once can no longer drop each other's
+  entries — the one overtaken plans again. A provider write takes a condition (`ifMatch`, `ifNoneMatch: '*'`), answered
+  412 when someone else got there first.
+- Updated dependencies [1330d5d]
+- Updated dependencies [842344f]
+  - @mosetta/server@0.0.3
+  - @mosetta/server-action@0.0.3
+  - @mosetta/router@0.0.3
+  - @mosetta/runtime@0.0.3
+  - @mosetta/tar@0.0.3
+
+## 0.0.2
+
+### Patch Changes
+
+- The first versioned release. A deployed version never changes, and the stores keep every version
+  deployed. A page runs one copy of each framework package — the newest its blocks were built with,
+  or the version its root pins; the Framework distribution's updater lifts a page to its framework.
+- Updated dependencies
+  - @mosetta/server@0.0.2
+  - @mosetta/router@0.0.2
+  - @mosetta/runtime@0.0.2
+  - @mosetta/server-action@0.0.2
+  - @mosetta/tar@0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mosetta contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @mosetta/build
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The core of the tile forge: builds a tile palette — its tile side artifacts, their dependency
+closure, the tile host descriptor (`modules.json`) — and holds the release rules every publisher
+runs. Environment-agnostic: the file system and the bundling engine are supplied from outside, so
+the same build runs in node (`@mosetta/cli`), in CI or in a platform's build container.
+
+## Entry points
+
+| Entry | What it holds |
+|---|---|
+| `@mosetta/build` | `build(root, options)` |
+| `@mosetta/build/release` | the release rules: a released version never changes, descriptors only grow, a descriptor is written over exactly the copy the plan was made from; `planRelease`, `release`, the push manifest, `checkPaletteBuild` |
+| `@mosetta/build/archive` | a build from a packed archive of sources, lock and packages |
+| `@mosetta/build/fileSystem`, `./scanner`, `./packagesResolver`, `./artifactCache` | the ports and helpers a host builds with |

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@mosetta/build",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.10",
+  "license": "MIT",
+  "description": "The core of the tile forge: builds a tile palette — its tile side artifacts, their dependency closure, the tile host descriptor. Environment-agnostic — the file system and the bundling engine are supplied from outside.",
+  "type": "module",
+  "exports": {
+    ".": "./src/build.mjs",
+    "./artifactCache": "./src/artifactCache.mjs",
+    "./fileSystem": "./src/fileSystem.mjs",
+    "./packagesResolver": "./src/packagesResolver.mjs",
+    "./scanner": "./src/scanner.mjs",
+    "./archive": "./src/archive.mjs",
+    "./release": "./src/release.mjs",
+    "./node": "./src/node.mjs"
+  },
+  "dependencies": {
+    "@pnpm/dependency-path": "^1000.0.9",
+    "@rollup/plugin-commonjs": "^28.0.9",
+    "@rollup/plugin-replace": "^6.0.3",
+    "cjs-module-lexer": "^2.2.0",
+    "postcss": "^8.5.15",
+    "postcss-value-parser": "^4.2.0",
+    "react": "*",
+    "react-dom": "*",
+    "resolve.exports": "^2.0.3",
+    "scheduler": "*",
+    "systemjs": "^6.15.1",
+    "yaml": "^2.9.0",
+    "@mosetta/router": "0.0.10",
+    "@mosetta/runtime": "0.0.10",
+    "@mosetta/server": "0.0.10",
+    "@mosetta/tar": "0.0.10",
+    "@mosetta/server-action": "0.0.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/archive.mjs

@@ -0,0 +1,140 @@
+import { path } from './nodeApi.mjs';
+import { parseTar, gunzip } from '@mosetta/tar';
+import { MemoryFileSystem } from './memoryFileSystem.mjs';
+import { PackagesResolver } from './packagesResolver.mjs';
+import { scanCatalog, scanToolingCatalog, BUILD_CONFIG_FILE } from './scanner.mjs';
+import { build, INERT_BUILD_CONFIG } from './build.mjs';
+import { bundleBuildConfig } from './configBundle.mjs';
+
+export { CONFIG_MODULE, bundleBuildConfig, buildConfigFrom } from './configBundle.mjs';
+export { BUILD_CONFIG_FILE } from './scanner.mjs';
+
+/**
+ * The build-action body — ONE BINARY tar container, no text encoding:
+ *
+ *   scan.json      — manifest: { root, frameworkDir, framework, mode, unpack: [{entry,dir,strip}] }
+ *   sources.tgz    — distributive sources (+ its lock) — the form GitHub serves them in
+ *   packages/*.tgz — archives of the closure's packages — the form the registry serves them in
+ *   meta.tgz       — package.json/locks of the walk-up contexts (ancestors of the root)
+ *
+ * The outer container is NOT compressed (its entries are already gzip) — the platform
+ * concatenates ready-made archives without repacking anything. Each entry unpacks into the
+ * memory FS at its `dir` (virtual paths mirror the layout relative to the lock — the graph's
+ * relative paths match the disk, so the artifacts are byte-identical). `strip` cuts the top
+ * name segments (a GitHub archive's `<repo>-<sha>/` folder, an npm package's `package/`).
+ *
+ * From there it is exactly the CLI pipeline: scan (lock + sources, already INSIDE the isolate) →
+ * catalog-backed resolver → build(). `mosetta.build.mjs` is NOT executed here by construction
+ * (executing a foreign file is an environment capability): the config is always INERT, and a
+ * distributive with node plugins is built the traditional way.
+ */
+
+export { MemoryFileSystem } from './memoryFileSystem.mjs';
+export { parseTar, writeTar, gzip, gunzip } from '@mosetta/tar';
+
+export const SCAN_ENTRY = 'scan.json';
+
+const stripSegments = (name, n) => name.split('/').slice(n).join('/');
+
+/** Unpack the container: { manifest, fileSystem } — a memory FS with the build's virtual world. */
+export async function unpackArchive(bytes) {
+  const outer = parseTar(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+  const byName = new Map(outer.map((e) => [e.name, e]));
+  const scanEntry = byName.get(SCAN_ENTRY);
+  if (!scanEntry) throw new Error(`container has no ${SCAN_ENTRY} — this is not a build-action body`);
+  const manifest = JSON.parse(new TextDecoder().decode(scanEntry.data));
+  const fileSystem = new MemoryFileSystem();
+  for (const u of manifest.unpack ?? []) {
+    const entry = byName.get(u.entry);
+    if (!entry) throw new Error(`manifest declares ${u.entry}, but the container has no such entry`);
+    for (const f of parseTar(await gunzip(entry.data))) {
+      const rel = stripSegments(f.name, u.strip ?? 0);
+      if (rel) fileSystem.set(path.join(u.dir, rel), f.data);
+    }
+  }
+  return { manifest, fileSystem };
+}
+
+/**
+ * RECOMPOSITION prep, the framework half: if the distributive has a build config — bundle it
+ * into a module and collect its wasm assets, so the caller (the action) only has to pack this
+ * into the response to the runner. The config is NOT executed here.
+ *
+ * The config's closure is the TOOLING one (`scanToolingCatalog`): devDependencies are allowed,
+ * because build tooling is exactly what they contain; the product catalog does not see it.
+ * Returns `{ code, wasm: [{ name, bytes }] }`, or null when there is no config.
+ */
+export async function prepareConfigRecompose({ manifest, fileSystem, engine }) {
+  if (!fileSystem.exists(path.join(manifest.root, BUILD_CONFIG_FILE))) return null;
+  const resolver = new PackagesResolver({
+    fileSystem,
+    catalog: {
+      ...scanToolingCatalog({ fileSystem, root: manifest.root, frameworkDir: manifest.frameworkDir }),
+      framework: manifest.framework ?? {},
+    },
+  });
+  const code = await bundleBuildConfig(fileSystem, resolver, {
+    engine, root: manifest.root, frameworkDir: manifest.frameworkDir,
+  });
+  // the config's wasm is declared as DATA (`buildConfigWasm` in mosetta.json): phase 1 does not
+  // execute the config and has no other way to learn its needs
+  const wasm = [];
+  let cfg = null;
+  try {
+    cfg = fileSystem.readJson(path.join(manifest.root, 'mosetta.json'));
+  } catch { /* no mosetta.json — no knob either */ }
+  for (const [name, specifier] of Object.entries(cfg?.buildConfigWasm ?? {})) {
+    wasm.push({ name, bytes: fileSystem.readFile(resolver.resolve(specifier, manifest.root, null)) });
+  }
+  return { code, wasm };
+}
+
+/**
+ * The action's full cycle: container → memory FS → scan → build(). Returns build()'s result.
+ *
+ * `released` — the ids the target's catalog already holds: released libraries and published
+ * packages there are not built again (`build`).
+ *
+ * `evaluate` — the host's way to run a module the build bundled (a block's settings schema); absent
+ * (an isolate), the schemas are skipped with a line in the log, as in any build without it.
+ *
+ * `buildConfig` — the tenant's hooks, ALREADY made executable through recomposition (the config
+ * module was added by the runner into the isolate's bundle, the action imported it and passed it
+ * here). If the config EXISTS in the sources but no hooks were passed, a build without them
+ * would produce artifacts different from local ones, so the refusal is LOUD: the caller must
+ * either go through recomposition or build the traditional way.
+ */
+export async function buildFromArchive(bytes, options) {
+  return buildUnpacked(await unpackArchive(bytes), options);
+}
+
+/** The same build over a container already unpacked (`unpackArchive`) — a host that looked inside first does not unpack twice. */
+export async function buildUnpacked({ manifest, fileSystem }, { engine, log = () => {}, buildConfig = null, evaluate = undefined, released = null }) {
+  if (!buildConfig && fileSystem.exists(path.join(manifest.root, BUILD_CONFIG_FILE))) {
+    throw new Error('the tile palette uses mosetta.build.mjs (build hooks), but no executable hooks '
+      + 'were passed: go through recomposition or build the traditional way (CLI)');
+  }
+  const mode = manifest.mode === 'production' ? 'production' : 'development';
+  const resolver = new PackagesResolver({
+    fileSystem,
+    catalog: {
+      ...scanCatalog({
+        fileSystem,
+        root: manifest.root,
+        frameworkDir: manifest.frameworkDir,
+        includeDev: mode !== 'production',
+        log,
+      }),
+      framework: manifest.framework ?? {},
+    },
+  });
+  return build(manifest.root, {
+    mode, log, fileSystem, resolver, engine,
+    frameworkDir: manifest.frameworkDir,
+    buildConfig: buildConfig ?? INERT_BUILD_CONFIG,
+    // a host that may run the code it built (a container, node) describes the blocks' settings
+    ...(evaluate ? { evaluate } : {}),
+    // what the target already holds is not built again
+    ...(released ? { released } : {}),
+  });
+}

package/src/artifactCache.mjs

@@ -0,0 +1,78 @@
+/**
+ * Artifact cache ACROSS build iterations (dev server).
+ *
+ * The artifact model could not fit this better: every artifact is built by its own graph, is
+ * self-contained and links at runtime by name — so editing one file must rebuild only the
+ * artifacts whose graphs include it, not all 44. Before the cache, every save in dev rebuilt
+ * EVERYTHING, including dependency artifacts whose sources live in node_modules and could not
+ * have changed.
+ *
+ * The validity key is the mtime of the artifact's source graph (`watchFiles`, collected by the
+ * port plugins). Such a key behaves correctly in a monorepo by itself — both ours and a
+ * consumer's: graph paths are dereferenced (`realPath`), so a workspace package is seen as the
+ * real file (`packages/react/src/...`), not a symlink inside node_modules, and editing it
+ * honestly invalidates everyone who pulled it in. A missing file yields `-1` — also a
+ * divergence, also a rebuild.
+ *
+ * What graph mtime does NOT catch is whatever changes the build as a whole rather than through
+ * files: mode, `mosetta.build.mjs` hooks, the package catalog (a reinstall/`pnpm add` changes
+ * resolution while sources do not) and the composition inputs (`mosetta.json`, the roots'
+ * `package.json`, `config.json`). That is the "epoch": changing it wipes the cache entirely.
+ * Cheaper and more reliable than weaving all of that into every key.
+ *
+ * The cache is SUPPLIED FROM OUTSIDE (the build has no environment defaults) — the long-lived
+ * dev server creates it. A one-shot prod build passes no cache: every build there is the first
+ * and the last.
+ */
+
+export const mtimeStamp = (fileSystem, files) =>
+  files.map((f) => `${f}:${fileSystem.mtimeMs(f) ?? -1}`).join('|');
+
+export class ArtifactCache {
+  #fileSystem;
+  #entries = new Map(); // key -> { value, files, stamp }
+  #epoch = null;
+
+  constructor(fileSystem) {
+    this.#fileSystem = fileSystem;
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Declare the build epoch. If it changed, the whole cache is invalid.
+   */
+  epoch(stamp) {
+    if (stamp === this.#epoch) return;
+    this.#epoch = stamp;
+    this.#entries.clear();
+  }
+
+  /**
+   * Serve the artifact from cache if no file of its graph changed; otherwise build and remember.
+   * `filesOf` — how to extract the graph from the result (default `watchFiles`).
+   */
+  async memo(key, produce, filesOf = (v) => v.watchFiles ?? []) {
+    const hit = this.#entries.get(key);
+    if (hit && mtimeStamp(this.#fileSystem, hit.files) === hit.stamp) {
+      this.hits++;
+      return hit.value;
+    }
+    const value = await produce();
+    const files = [...new Set(filesOf(value))];
+    this.#entries.set(key, { value, files, stamp: mtimeStamp(this.#fileSystem, files) });
+    this.misses++;
+    return value;
+  }
+
+  /**
+   * Counters for the LAST iteration — the dev server prints them to the log so that "only what
+   * changed got rebuilt" is visible, not assumed.
+   */
+  take() {
+    const stats = { hits: this.hits, misses: this.misses, size: this.#entries.size };
+    this.hits = 0;
+    this.misses = 0;
+    return stats;
+  }
+}

package/src/browserField.mjs

@@ -0,0 +1,90 @@
+import { path } from './nodeApi.mjs';
+import { packageDirOf } from './packageMeta.mjs';
+
+/**
+ * Legacy `browser` field in package.json.
+ *
+ * This is NOT an `exports` condition but an older, entirely different mechanism — a substitution
+ * map inside the package:
+ *
+ *     "browser": { "./lib/node.js": "./lib/browser.js", "crypto": false }
+ *
+ * The value `false` means "this does not exist in the browser, substitute a stub". There is also
+ * a string form (`"browser": "./dist/browser.js"`) — an alternative package ENTRY; it applies
+ * only when there is no `exports` map, because `exports` is more modern and overrides the
+ * legacy fields.
+ *
+ * This used to be handled by `@rollup/plugin-node-resolve({ browser: true })`. After moving
+ * resolution onto the port the mechanism got lost: nothing in the current closure uses it
+ * (otherwise the artifact comparison would not have matched), but on a new dependency it would
+ * misfire as quietly as zod's conditional `exports` did.
+ *
+ * Lives OUTSIDE the port: it only needs `readJson` and the upward walk (`packageMeta`), so it
+ * works with any port implementation.
+ */
+
+/** Stub specifier: `"…": false` in the map. The plugin serves an empty module for it. */
+export const BROWSER_EMPTY = '\0mosetta-browser-empty';
+
+const EXTENSIONS = ['', '.mjs', '.js', '.ts', '.tsx', '.json'];
+
+function readPackage(fileSystem, dir) {
+  try {
+    return fileSystem.readJson(path.join(dir, 'package.json'));
+  } catch {
+    return null;
+  }
+}
+
+// map keys are written inconsistently: './lib/x.js', 'lib/x.js', './lib/x' — normalize both sides
+function lookup(map, relative) {
+  const candidates = [relative, relative.replace(/^\.\//, '')];
+  for (const base of candidates) {
+    for (const ext of EXTENSIONS) {
+      const withExt = base.endsWith(ext) ? base : base + ext;
+      for (const key of [withExt, `./${withExt.replace(/^\.\//, '')}`]) {
+        if (Object.hasOwn(map, key)) return map[key];
+      }
+    }
+    // and the reverse case: the map has the path WITHOUT an extension, we have it with one
+    const stripped = base.replace(/\.(mjs|js|ts|tsx|json)$/, '');
+    for (const key of [stripped, `./${stripped.replace(/^\.\//, '')}`]) {
+      if (Object.hasOwn(map, key)) return map[key];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Apply the owning package's `browser` map to an already resolved ABSOLUTE path.
+ * Returns the path (possibly substituted), or `BROWSER_EMPTY` for `false`.
+ * Without the `browser` condition in the set — identity.
+ */
+export function applyBrowserField(fileSystem, file, conditions) {
+  if (!conditions?.includes('browser')) return file;
+  const dir = packageDirOf(fileSystem, file);
+  if (!dir) return file;
+  const pkg = readPackage(fileSystem, dir);
+  const map = pkg?.browser;
+  if (!map || typeof map !== 'object') return file;
+  const relative = `./${path.relative(dir, file).split(path.sep).join('/')}`;
+  const hit = lookup(map, relative);
+  if (hit === undefined) return file;
+  if (hit === false) return BROWSER_EMPTY;
+  return path.resolve(dir, hit);
+}
+
+/**
+ * The string form — an alternative package entry. Applies only to the ROOT specifier
+ * (`'lodash'` but not `'lodash/get'`) and only when there is no `exports` map.
+ */
+export function applyBrowserEntry(fileSystem, specifier, file, conditions) {
+  if (!conditions?.includes('browser')) return file;
+  if (specifier.startsWith('.') || path.isAbsolute(specifier)) return file;
+  const dir = packageDirOf(fileSystem, file);
+  if (!dir) return file;
+  const pkg = readPackage(fileSystem, dir);
+  if (!pkg || pkg.exports || typeof pkg.browser !== 'string') return file;
+  if (pkg.name && specifier !== pkg.name) return file; // subpath — the root entry does not apply
+  return path.resolve(dir, pkg.browser);
+}