@mosetta/runtime 0.0.0-stage → 0.0.9

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,16 @@
-# Temporary Holding Version
+# @mosetta/runtime
 
-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 browser runtime of mosetta: `start()` reads the page's envelope, installs the version resolver
+on SystemJS (one copy of each singleton package per page, every tile at the base of the tile host
+its descriptor names), loads the page's tiles and their stylesheets, and hands the tree to the
+renderer. Framework-agnostic — the React mount lives in `@mosetta/react/start`.
+
+| Entry | What it holds |
+|---|---|
+| `@mosetta/runtime/bootstrap` | `start()` and the resolver prolog |
+| `@mosetta/runtime/resolver` | the version resolver |
+| `@mosetta/runtime/tile-loader` | `createTileLoader` |
+| `@mosetta/runtime/naming` | full tile names |
+| `@mosetta/runtime/client`, `./dom` | the browser's helpers |
+
+It ships to the browser as an ordinary package tile.

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@mosetta/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.9",
+  "license": "MIT",
+  "description": "mosetta browser runtime: start() (resolver prolog, tree loading, holder), version resolver, safe tile loader, asset runtime. Framework-agnostic — the react mount (startAndMount) lives in @mosetta/react/start. Ships as an ordinary package tile; the root export is the component-facing asset surface.",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/assetRuntime.js",
+    "./bootstrap": "./src/bootstrap.ts",
+    "./client": "./src/client/client.ts",
+    "./dom": "./src/domEvents.ts",
+    "./resolver": "./src/resolver.js",
+    "./tile-loader": "./src/tileLoader.js",
+    "./naming": "./src/naming.js"
+  },
+  "dependencies": {
+    "@mosetta/core": "0.0.9",
+    "@mosetta/di": "0.0.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/assetRuntime.js

@@ -0,0 +1,13 @@
+// The component-facing surface of @mosetta/runtime (the package ROOT export): built into the
+// dependency closure as a System artifact; asset imports resolve to `__asset(rel, import.meta.url)`.
+// Default: resolve the co-located asset against the module's own URL (relocatable, no baked origin).
+// Override app-wide via setAssetResolver (e.g. point assets at a CDN / a provider / transform).
+let resolver = (rel, base) => new URL(rel, base).href;
+
+export function setAssetResolver(fn) {
+  resolver = fn;
+}
+
+export function __asset(rel, base) {
+  return resolver(rel, base);
+}

package/src/bootstrap.ts

@@ -0,0 +1,363 @@
+// mosetta bootstrap — the browser start of a page. Deliberately
+// package-agnostic — it knows nothing about react/di/etc. It only: (1) installs the dependency
+// resolve hook from the app node's version settings — an IDEMPOTENT prolog, because
+// the loader artifact runs it too, (2) System.imports every module referenced by
+// the embedded page tree — each from ITS OWN provider (multi-provider), and (3) RETURNS
+// `{ rootEl, tree, holder }` — mounting is the caller's business (`@mosetta/react/start`
+// for the react default; a custom script facet brings its own).
+//
+// The HOST DISTRIBUTIVE ROOT is data: the shell stamps `hostBase` into the pageContent envelope
+// at render time (the STORED doc stays environment-agnostic). Absent → resolved relative to the
+// page's own URL ('.'), which covers SSG/static hosting where the page sits at the provider root.
+import { installResolver, versionedUrl } from './resolver.js';
+import { createTileLoader } from './tileLoader.js';
+
+const HOLDER = '__mosettaModules__';
+const PAGE_BOOT = '__mosettaPageBoot__';
+const STARTED = '__mosettaStarted__';
+
+interface IPageNode {
+  reference?: string;
+  lazy?: boolean;
+  children?: IPageNode[];
+}
+
+export interface ITileDescriptor {
+  id?: string;
+  assets?: string[];
+  dependencies?: string[];
+  /** SRI of the entity's main artifact — also its content address (versionedUrl) */
+  integrity?: string;
+  /** the key of the code source it lives with (the page's `providers` names its base); absent — the host */
+  provider?: string;
+}
+
+export interface IMosaicEnvelope extends IPageNode {
+  fallback?: string;
+  /** the page's code sources other than the host: key → public base (stamped by the shell) */
+  providers?: Record<string, string>;
+  settings?: { versions?: unknown };
+  // stamped by the SSR shell at render time; absent in SSG (relative hosting)
+  hostBase?: string;
+  // slice of the unified catalog: entities of the page's transitive closure — from it the
+  // runtime handles loading/css with the same structure the server shell uses
+  catalog?: Record<string, ITileDescriptor>;
+}
+
+export interface ILoadedTile {
+  reference: string;
+  module?: { Component?: unknown } & Record<string, unknown>;
+  error?: Error;
+}
+
+export interface ITilesHolder {
+  getModule(ref: string): ILoadedTile | undefined;
+  loadModule(ref: string, providerBase?: string): Promise<ILoadedTile>;
+  /**
+   * Make the realm ready for ANOTHER page's tree (a client-side move, ADR-0051): its catalog
+   * slice joins the realm's (content addresses and SRI for its artifacts, like the first page's),
+   * the css of its eager closure is injected and AWAITED, every eager module and the fallback are
+   * loaded. After it, swapping the tree in renders without a missing module.
+   */
+  prepare(tree: IMosaicEnvelope): Promise<void>;
+}
+
+export interface IStartResult {
+  rootEl: HTMLElement;
+  tree: IMosaicEnvelope;
+  holder: ITilesHolder;
+}
+
+const withSlash = (u: string): string => (u.endsWith('/') ? u : u + '/');
+
+/** a page's `providers` table (key → base) into the realm's, every base absolute */
+function addSources(into: Record<string, string>, table: Record<string, string> | undefined, base: string): void {
+  for (const [key, at] of Object.entries(table ?? {})) {
+    if (typeof at === 'string' && at) into[key] = withSlash(new URL(at, base).href);
+  }
+}
+
+/**
+ * The resolver PROLOG: read the `#pageContent` envelope, derive the host base and
+ * install the version resolver on the global System. Idempotent — the loader artifact executes it
+ * before any entry resolves, and `start()` reuses the cached result: several script facets on one
+ * page bootstrap once. `#pageContent` sits ABOVE the loader in head, so it is always parsed by
+ * the time any caller runs.
+ */
+export function installResolverFromPage(): { tree: IMosaicEnvelope; base: string; catalog: Record<string, ITileDescriptor>; sources: Record<string, string> } {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const g = globalThis as any;
+  if (g[PAGE_BOOT]) return g[PAGE_BOOT];
+  const el = document.getElementById('pageContent');
+  if (!el) throw new Error('[mosetta] #pageContent not found');
+  const tree = JSON.parse(el.textContent ?? '') as IMosaicEnvelope;
+
+  // host distributive root: stamped by the shell (`hostBase`), or the page's own directory —
+  // SSG serves the page at the provider root, so '.' resolves to it (|| — an empty stamp means
+  // "relative hosting" too)
+  const base = withSlash(new URL(tree.hostBase || '.', location.href).href);
+
+  // version alignment (singleton/pin) is DATA from the app node's settings — not baked in here.
+  // Artifact urls are content-addressed by the page's catalog slice (see versionedUrl): the same
+  // hashes the shell put on its preload links, so a preload and its use are one address. The
+  // slice is the REALM's catalog from here on: a later page's slice joins it (prepare), and the
+  // resolver reads it live
+  const catalog: Record<string, ITileDescriptor> = { ...(tree.catalog ?? {}) };
+  // the page's code sources other than the host (ADR-0070): an entity of the catalog that names one
+  // is read from its base — blocks, packages and singletons alike; later pages add theirs (prepare)
+  const sources: Record<string, string> = {};
+  addSources(sources, tree.providers, base);
+  // the catalog's word on where an entity lives: the base of the source its entry names, the
+  // host's when the entry names none (a host package imported by another source's block lies with
+  // the host — a tile palette is built over the host's tiles). An id the catalog does not know —
+  // undefined: the resolver co-locates it with its importer
+  const baseOf = (id: string): string | undefined => {
+    const entry = catalog[id];
+    if (!entry) return undefined;
+    return entry.provider ? sources[entry.provider] : base;
+  };
+  installResolver(g.System, { base, config: tree.settings && tree.settings.versions, integrityOf: (id: string) => catalog[id]?.integrity, baseOf });
+  g[PAGE_BOOT] = { tree, base, catalog, sources };
+  return g[PAGE_BOOT];
+}
+
+// Walk the tree → fill `acc` Map(reference → base url to ask from) for ALL nodes (so the holder can
+// load any of them later), and `lazy` Set of refs that should NOT be preloaded. The page never says
+// where its code lives: the base asked from is the host's, and the catalog names another source's
+// (sourceBaseOf). `lazy: true` on a node marks it and its whole subtree as load-on-demand. Deduped by
+// reference (first occurrence wins).
+function collect(node: IPageNode, base: string, acc: Map<string, string>, lazy: Set<string>, inheritedLazy: boolean): void {
+  if (!node || !node.reference) return;
+  const nodeLazy = inheritedLazy || node.lazy === true;
+  if (!acc.has(node.reference)) {
+    acc.set(node.reference, base);
+    if (nodeLazy) lazy.add(node.reference);
+  }
+  for (const child of node.children || []) collect(child, base, acc, lazy, nodeLazy);
+}
+
+async function run(): Promise<IStartResult> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const System = (globalThis as any).System;
+  const { tree, base, catalog: realmCatalog, sources } = installResolverFromPage();
+
+  // every reference the realm has seen → its provider base; lazy refs are not preloaded
+  const refBases = new Map<string, string>();
+
+  // Unified catalog: the page-closure slice arrives IN THE ENVELOPE (#pageContent) — there are
+  // no manifest fetches anymore. Entities outside the slice (editor insertion, lazy from a
+  // foreign provider) are fetched on demand via the co-located `<id>.json` descriptor
+  // (immutable, cacheable) with recursion over its edges. Css injection is part of the module
+  // LOAD path.
+  const catalog = new Map<string, ITileDescriptor | null>(Object.entries(realmCatalog));
+  const DEP_PREFIX = '_ns_package_t_package_n_';
+  // an entity lives with the code source its catalog entry names, the host when it names none; an
+  // entity outside the catalog — with the base it was asked from
+  const sourceBaseOf = (id: string, pb: string): string => {
+    const entry = catalog.get(id) ?? realmCatalog[id];
+    if (!entry) return pb;
+    return (entry.provider ? sources[entry.provider] : base) || pb;
+  };
+  const entityFileUrl = (id: string, file: string, pb: string): string => new URL('modules/' + id + '/' + file, sourceBaseOf(id, pb)).href; // flat layout
+  // an artifact of the realm's catalog is addressed by its content, exactly as the shell addressed
+  // it; an entity outside it (an editor's insertion) keeps its plain address — one url per
+  // entity in a realm, whichever way it is reached
+  const sliceIntegrity = (id: string): string | undefined => realmCatalog[id]?.integrity;
+  const artifactUrl = (id: string, file: string, pb: string): string => versionedUrl(entityFileUrl(id, file, pb), sliceIntegrity(id));
+  const fetched = new Map<string, Promise<ITileDescriptor | null>>();
+  const entityOf = (id: string, pb: string): Promise<ITileDescriptor | null> => {
+    if (catalog.has(id)) return Promise.resolve(catalog.get(id) ?? null);
+    if (!fetched.has(id)) {
+      fetched.set(id, fetch(entityFileUrl(id, id + '.json', pb))
+        .then((r) => (r.ok ? (r.json() as Promise<ITileDescriptor>) : null))
+        .catch(() => null));
+    }
+    return fetched.get(id)!;
+  };
+  // transitive closure of an entity over descriptor edges (BFS, id → entity|null and the base it
+  // was asked from); a dependency the catalog does not place is asked from where its importer lies
+  const closureOf = async (root: string, pb: string): Promise<Map<string, { entity: ITileDescriptor | null; at: string }>> => {
+    const seen = new Map<string, { entity: ITileDescriptor | null; at: string }>();
+    const queue: Array<[string, string]> = [[root, pb]];
+    while (queue.length) {
+      const [id, at] = queue.shift()!;
+      if (seen.has(id)) continue;
+      const entity = await entityOf(id, at);
+      seen.set(id, { entity, at });
+      for (const dep of entity?.dependencies ?? []) queue.push([dep, sourceBaseOf(id, at)]);
+    }
+    return seen;
+  };
+  // A stylesheet IN PLACE: applied, or given up on. A module must not render before its css is —
+  // the shell declares the first page's (render-blocking in the head), but a module loaded later
+  // (the editor's tree and canvas, a hosted form, a lazy block) rendered raw for as long as its css
+  // took to arrive: unstyled buttons, icons blown up to the width of the screen. A sheet that
+  // fails, or never answers, does not hold the page hostage — it is given up on after a while.
+  const STYLESHEET_PATIENCE_MS = 5000;
+  const sheetReady = (link: HTMLLinkElement): Promise<void> => {
+    if (link.sheet) return Promise.resolve(); // applied already (a cross-origin sheet still has one)
+    return new Promise<void>((resolve) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const done = (): void => {
+        clearTimeout(timer);
+        link.removeEventListener('load', done);
+        link.removeEventListener('error', done);
+        resolve();
+      };
+      timer = setTimeout(done, STYLESHEET_PATIENCE_MS);
+      link.addEventListener('load', done);
+      link.addEventListener('error', done);
+    });
+  };
+  // the SHELL declares the css of the whole non-lazy tree — compare by the
+  // RESOLVED url (the DOM `href` property is absolute even for relative SSG attributes). A sheet the
+  // shell declared is not waited for: it was render-blocking in the head, so it is applied — or it
+  // failed, and a failed one never says so again (waiting would hold every boot for the patience).
+  // A sheet THIS loader put in is waited for by everyone who needs it.
+  const injected = new Map<string, Promise<void>>();
+  const injectCssOnce = (href: string): Promise<void> => {
+    const ours = injected.get(href);
+    if (ours) return ours;
+    for (const existing of document.querySelectorAll('link[rel="stylesheet"]')) {
+      if ((existing as HTMLLinkElement).href === href) return Promise.resolve();
+    }
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = href;
+    const ready = sheetReady(link);
+    injected.set(href, ready);
+    document.head.appendChild(link);
+    return ready;
+  };
+  // one promise per module: whoever asks again waits for the same sheets
+  const cssReady = new Map<string, Promise<void>>();
+  const ensureCss = (ref: string, pb: string): Promise<void> => {
+    const known = cssReady.get(ref);
+    if (known) return known;
+    const ready = (async () => {
+      const closure = await closureOf(ref, pb);
+      // cascade order: dependency-entity css before the module's own (the module overrides) —
+      // the links go into the head in that order, and are waited for together
+      const sheets: Promise<void>[] = [];
+      const inject = (pkgLayer: boolean): void => {
+        for (const [id, { entity, at }] of closure) {
+          if (id.startsWith(DEP_PREFIX) !== pkgLayer) continue;
+          for (const a of entity?.assets ?? []) {
+            if (a.endsWith('.css')) sheets.push(injectCssOnce(artifactUrl(id, a, at)));
+          }
+        }
+      };
+      inject(true);
+      inject(false);
+      await Promise.all(sheets);
+    })().catch(() => undefined); // a closure that cannot be read styles nothing — the module still loads
+    cssReady.set(ref, ready);
+    return ready;
+  };
+  // load every referenced module from ITS provider via the SAFE loader. load() never rejects, so
+  // Promise.all can't blow up — a failed module lands as { error } inside its ILoadedTile and is isolated
+  // later by the React error boundary (→ fallback for that subtree only).
+  const loader = createTileLoader(System, (ref: string, pb: string) => artifactUrl(ref, ref + '.js', pb));
+  // What the React layer may see: a module HANDED OVER — loaded, with its stylesheets in place. The
+  // loader holds a module the moment its code is in, and a render in between (a Suspense boundary
+  // retried because a neighbour's sheets arrived first) found it there and drew it raw: the
+  // editor's canvas, with its icons the width of the screen, while its sheet was still on the way.
+  const handedOver = new Set<string>();
+
+  // A page's tree made ready in this realm: the first one at boot, every later one on a
+  // client-side move (ADR-0051). Its catalog slice joins the realm's; the css of its eager
+  // closure is injected and awaited (the shell declared the first page's — a later page's must
+  // be in place before its nodes render); every eager module and the fallback are loaded, a
+  // module that failed before is tried again. Lazy nodes load on demand (useTile → Suspense).
+  const prepare = async (page: IMosaicEnvelope): Promise<void> => {
+    addSources(sources, page.providers, base);
+    for (const [id, e] of Object.entries(page.catalog ?? {})) {
+      realmCatalog[id] = e;
+      catalog.set(id, e);
+    }
+    const bases = new Map<string, string>();
+    const lazy = new Set<string>();
+    collect(page, base, bases, lazy, false);
+    if (page.fallback && !bases.has(page.fallback)) bases.set(page.fallback, base);
+    for (const [ref, pb] of bases) if (!refBases.has(ref)) refBases.set(ref, pb);
+    const eager = [...bases].filter(([ref]) => !lazy.has(ref));
+    await Promise.all(eager.map(([ref, pb]) => ensureCss(ref, pb)));
+    for (const [ref] of eager) loader.forget(ref);
+    await Promise.all(eager.map(([ref, pb]) => loader.load(ref, pb)));
+    for (const [ref] of eager) handedOver.add(ref); // their css was awaited above
+  };
+  await prepare(tree);
+
+  // holder for the React layer — same ILoadedTile shape; loadModule enables later dynamic/lazy loads.
+  // A module loaded so is READY only with its stylesheets in place: the code and the css are
+  // fetched side by side, and the module is handed over once both are — getModule does not show
+  // it before (its Suspense boundary, or whoever awaits it, waits that long — never renders it
+  // raw). One promise per module while it is on its way: Suspense gets the same one every render.
+  const providerOf = (ref: string): string => refBases.get(ref) || base;
+  const handing = new Map<string, Promise<ILoadedTile>>();
+  const holder: ITilesHolder = {
+    getModule: (ref: string): ILoadedTile | undefined => (handedOver.has(ref) ? loader.get(ref) : undefined),
+    loadModule: (ref: string, pb?: string): Promise<ILoadedTile> => {
+      const ready = handedOver.has(ref) ? loader.get(ref) : undefined;
+      if (ready) return Promise.resolve(ready);
+      const pending = handing.get(ref);
+      if (pending) return pending;
+      const target = pb || providerOf(ref);
+      const handover = Promise.all([ensureCss(ref, target), loader.load(ref, target)]).then(([, loaded]) => {
+        handedOver.add(ref);
+        handing.delete(ref);
+        return loaded;
+      });
+      handing.set(ref, handover);
+      return handover;
+    },
+    prepare,
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (globalThis as any)[HOLDER] = holder;
+
+  // the root module is CRITICAL — its failure is fatal (nothing to mount); content failures stay
+  // isolated. Its SHAPE (the Component export) is the mounting caller's contract, not ours.
+  const rootModule = tree.reference ? holder.getModule(tree.reference) : undefined;
+  if (!rootModule || rootModule.error || !rootModule.module) {
+    throw new Error('[mosetta] root module failed: '
+      + (rootModule && rootModule.error ? rootModule.error.message : 'missing from the page tree'));
+  }
+
+  // #root sits at the END of body — a script-facet entry may execute before the parser got there
+  // in exotic hosts (a spike showed DOMContentLoaded-timing in browsers); the
+  // module preloads above already ran in parallel with parsing, only the mount target waits.
+  if (document.readyState === 'loading') {
+    await new Promise((r) => document.addEventListener('DOMContentLoaded', r, { once: true }));
+  }
+  const rootEl = document.getElementById('root');
+  if (!rootEl) throw new Error('[mosetta] #root not found');
+  rootEl.setAttribute('data-modules-holder', HOLDER);
+
+  return { rootEl, tree, holder };
+}
+
+// Fatal errors are handled HERE (log + visible message) so callers stay one-liners; a custom
+// script facet wanting different handling wraps start() itself.
+function reportFatal(e: unknown): void {
+  console.error('[mosetta] runtime failed', e);
+  const root = document.getElementById('root');
+  if (root) root.textContent = '[mosetta] runtime failed: ' + String((e as Error)?.message ?? e);
+}
+
+/**
+ * Boot the page: resolver prolog, tree module preloads, css, holder. Resolves to
+ * `{ rootEl, tree, holder }` for the mounting caller, or `null` after a reported fatal.
+ * Idempotent — several script facets on one page share a single boot.
+ */
+export function start(): Promise<IStartResult | null> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const g = globalThis as any;
+  if (!g[STARTED]) {
+    g[STARTED] = run().catch((e: unknown) => {
+      reportFatal(e);
+      return null;
+    });
+  }
+  return g[STARTED];
+}

package/src/client/appContainer.ts

@@ -0,0 +1,86 @@
+import { DiContainer } from '@mosetta/di';
+import type { IBlueprintNode, IBlueprint } from '@mosetta/core';
+import { DefaultPageManager, PAGE_MANAGER_TOKEN } from './pageManager';
+import { MemoryRefViews, REF_VIEWS_TOKEN } from './refs';
+import {
+  FULL_APP_PREVIEW,
+  ITilesHolder,
+  IMountPreview,
+  TILES_HOLDER_TOKEN,
+  PARENT_DI_TOKEN,
+  PREVIEW_TYPE_TOKEN,
+  SSR_RENDER_CHANNEL_TOKEN,
+} from './tokens';
+import { DomHeadWriter, HEAD_WRITER_TOKEN, IHeadWriter, ISsrRenderChannel } from './headWriter';
+import { browserRouterHost, ClientRouter, InertRouter, ROUTER_TOKEN } from './router';
+
+// The WELL-KNOWN global the modules holder lives under. The browser bootstrap
+// (@mosetta/runtime) publishes it, the server ssr module publishes its isolate twin — the app
+// container reads it by name in both worlds (an app Component renders on the server too, so it
+// cannot go through DOM attributes; SSR epic).
+export const MODULES_HOLDER_GLOBAL = '__mosettaModules__';
+
+interface IBrowserModulesHolder extends Record<string, ITilesHolder> {
+}
+
+// read the well-known holder global by name — works in the browser AND in the ssr isolate
+function extractClientModulesHolder(name: string): ITilesHolder {
+  const globalHolder = globalThis as unknown as IBrowserModulesHolder;
+
+  return globalHolder[name];
+}
+
+export interface ICreateAppContainerOptions {
+  moduleTreeNode: IBlueprintNode;
+  /** the container of the application that MOUNTED this one (IMountOptions.parentDi) */
+  parentDi?: DiContainer;
+  /** the host's word that this application is a specimen (IMountOptions.preview) */
+  preview?: IMountPreview;
+  // present ONLY during a server render — the ssr module threads its per-request head channel
+  // through the Component prop; pass the WHOLE props object so it rides along
+  ssrChannel?: ISsrRenderChannel;
+  /**
+   * Where the tree's head writes go, when the default is wrong. A page writes into its own
+   * document; a HOST that renders someone else's module inside ITS document (the editor
+   * previewing a block) must not let those writes reach its own head — see NullHeadWriter.
+   */
+  headWriter?: IHeadWriter;
+}
+
+// The BASE registrations every app root needs (modules holder + page manager). Created INSIDE the
+// app's Component via `useState(() => createAppContainer(...))` — a fresh container per mount,
+// which on the server means per request/render: nothing leaks between requests of a cached
+// isolate. App-specific services (e.g. registerServerActionClient) are added by the app right
+// after this call, in the same initializer. MUST stay pure: React StrictMode double-invokes
+// useState initializers in dev.
+export function createAppContainer({ moduleTreeNode, ssrChannel, headWriter, parentDi, preview }: ICreateAppContainerOptions): DiContainer {
+  const di = new DiContainer();
+  di.registerValueOfToken(TILES_HOLDER_TOKEN, extractClientModulesHolder(MODULES_HOLDER_GLOBAL));
+  // page manager → usePage()/the fallback path (ComponentErrorHandler reads page.fallback)
+  di.registerValueOfToken(PAGE_MANAGER_TOKEN, new DefaultPageManager(moduleTreeNode as IBlueprint));
+  // head writing: what the host asked for, else the server channel when rendering server-side,
+  // else the DOM twin
+  di.registerValueOfToken(HEAD_WRITER_TOKEN, headWriter ?? ssrChannel ?? new DomHeadWriter());
+  // the channel as plain DATA — lazily-wired slices read it to pick their env
+  di.registerValueOfToken(SSR_RENDER_CHANNEL_TOKEN, ssrChannel ?? null);
+  // the parent application's container, whole (the Unity-editor door; null for a page's own boot)
+  di.registerValueOfToken(PARENT_DI_TOKEN, parentDi ?? null);
+  // the editor's views of reference providers — empty unless an editor's bridge fills them
+  di.registerValueOfToken(REF_VIEWS_TOKEN, new MemoryRefViews());
+  // previewness is a container fact (PREVIEW_TYPE_TOKEN): the mount option wins — it speaks
+  // about THIS mounted specimen — the realm mark covers a whole preview iframe, the rest is live
+  const realmPreview = typeof window !== 'undefined'
+    && (window as { __mosettaPreview?: boolean }).__mosettaPreview === true;
+  di.registerValueOfToken(PREVIEW_TYPE_TOKEN, preview?.type ?? (realmPreview ? FULL_APP_PREVIEW : null));
+  // the facet-declared environment of a specimen: services that arrange the component's world
+  if (preview?.services?.length) di.registerServices(...preview.services);
+  // the client router (ADR-0051): alive for the page's OWN boot in a browser — not on the server,
+  // not in a preview realm (the agent lives in the tree, a move would unmount it), not in a
+  // hosted mount (a panel is not the page). Listening starts when the root mounts (attach)
+  const ownBoot = typeof window !== 'undefined' && !ssrChannel && !parentDi && !preview && !realmPreview;
+  const holder = di.getByToken(TILES_HOLDER_TOKEN);
+  di.registerValueOfToken(ROUTER_TOKEN, ownBoot && holder?.prepare
+    ? new ClientRouter(browserRouterHost(), di.getByToken(PAGE_MANAGER_TOKEN), holder, di.getByToken(HEAD_WRITER_TOKEN))
+    : new InertRouter());
+  return di;
+}

package/src/client/client.ts

@@ -0,0 +1,12 @@
+// browser-protocol layer (framework-agnostic half of the former @mosetta/client).
+// Lived in @mosetta/core until 2026-07: DI tokens belong next to the runtime that publishes
+// their values — moving them here broke the core↔di dependency cycle (core keeps pure models).
+export * from './tile';
+export * from './tokens';
+export * from './pageManager';
+export * from './headWriter';
+export * from './appContainer';
+export * from './serverRender';
+export * from './getIsClient';
+export * from './refs';
+export * from './router';

package/src/client/getIsClient.ts

@@ -0,0 +1,3 @@
+export function getIsClient() {
+  return typeof window !== 'undefined';
+}

package/src/client/headWriter.ts

@@ -0,0 +1,85 @@
+import { SingleDiToken } from '@mosetta/di';
+
+// The head-writing channel — ONE API, two worlds:
+// - during a server render the app receives the ssr module's per-request HeadChannel as the
+//   `ssrChannel` prop: writes are collected and shipped by HeadTags once the body settles;
+// - in the browser there is no channel prop and writes upsert document.head directly (head is
+//   NOT part of the hydrated tree — hydrateRoot holds #root only, so no mismatch is possible).
+
+export interface IHeadWriter {
+  /** key = tag identity: dedup, last write wins; `html` is RAW inner html — the CALLER escapes */
+  addToHead(key: string, tag: string, attributes: Record<string, string>, html?: string): void;
+  /** the tag under this key leaves the head — a client-side move sweeps what the next page has no use for */
+  removeFromHead?(key: string): void;
+  /** every key written so far (a render channel has no use for this; the DOM twin answers) */
+  headKeys?(): string[];
+}
+
+// what the server threads through the Component prop (the ssr module wraps its per-request
+// HeadChannel); the action counter and requestOrigin feed the server-actions slice
+export interface ISsrRenderChannel extends IHeadWriter {
+  beginAction(): void;
+  completeAction(): void;
+  /**
+   * What of a node's settings ships to the browser in the page envelope (useShippedSettings).
+   * Keyed by node id, last write wins — a component renders more than once while actions
+   * resolve. Optional: an older engine simply ships every node as it is.
+   */
+  shipSettings?(nodeId: string, settings: Record<string, unknown>): void;
+  // origin of the ORIGINAL request (the runner) — server-executed actions target the same
+  // HTTP endpoint the browser uses, but the isolate needs it absolute
+  readonly requestOrigin?: string;
+}
+
+export const HEAD_WRITER_TOKEN = new SingleDiToken<IHeadWriter>('HEAD_WRITER_TOKEN');
+
+// the server HeadTags render stamps the SAME key attribute on its tags, so a client re-write
+// REPLACES the server-rendered tag instead of duplicating it
+export const HEAD_KEY_ATTRIBUTE = 'data-mosetta-head-key';
+
+// Well-known FRAMEWORK head keys — module writes through useAddToHead are IGNORED (+warn).
+// The action cache script is written by the ssr recorder and read by hydration seeding; a
+// module upsert under the same key would clobber the shipped cache.
+export const ACTION_CACHE_HEAD_KEY = 'mosetta-action-cache';
+export const RESERVED_HEAD_KEYS: ReadonlySet<string> = new Set([ACTION_CACHE_HEAD_KEY]);
+
+/**
+ * Writes nothing. For a host that renders SOMEONE ELSE'S module inside its own document — the
+ * editor previewing a block from the catalog — where a `useAddToHead` in that module would
+ * otherwise retitle the host's page or overwrite its meta.
+ */
+export class NullHeadWriter implements IHeadWriter {
+  addToHead(): void {
+    // deliberate: the module renders, its head writes are dropped
+  }
+}
+
+export class DomHeadWriter implements IHeadWriter {
+  addToHead(key: string, tag: string, attributes: Record<string, string>, html?: string): void {
+    if (typeof document === 'undefined') return;
+    const next = document.createElement(tag);
+    next.setAttribute(HEAD_KEY_ATTRIBUTE, key);
+    for (const [name, value] of Object.entries(attributes)) next.setAttribute(name, value);
+    if (html !== undefined) next.innerHTML = html;
+    const existing = this.find(key);
+    if (existing) existing.replaceWith(next);
+    else document.head.appendChild(next);
+  }
+
+  removeFromHead(key: string): void {
+    this.find(key)?.remove();
+  }
+
+  headKeys(): string[] {
+    if (typeof document === 'undefined') return [];
+    return Array.from(document.head.querySelectorAll(`[${HEAD_KEY_ATTRIBUTE}]`))
+      .map((el) => el.getAttribute(HEAD_KEY_ATTRIBUTE))
+      .filter((key): key is string => key !== null);
+  }
+
+  private find(key: string): Element | undefined {
+    if (typeof document === 'undefined') return undefined;
+    return Array.from(document.head.querySelectorAll(`[${HEAD_KEY_ATTRIBUTE}]`))
+      .find((el) => el.getAttribute(HEAD_KEY_ATTRIBUTE) === key);
+  }
+}