@mosetta/runtime 0.0.0-stage → 0.0.9

package/src/naming.js

@@ -0,0 +1,25 @@
+// Canonical name encoding + external-dependency identity.
+// Pure & browser-safe (no imports) — single source of truth shared by the build (src/*) and
+// the runtime resolver (runtime/resolver.js), so they can never disagree on how ids are formed.
+
+export const normalizeSpecifier = (s) => s.replace(/^@/, 'a_').replace(/[\\/]/g, '_');
+
+export const normalizeVersion = (v) => String(v).trim().replace(/[^a-zA-Z0-9]/g, '_');
+
+// Version-qualified id of an external dependency artifact: identity is (specifier, version).
+export const dependencyFullId = (specifier, version) =>
+  `_ns_package_t_package_n_${normalizeSpecifier(specifier)}_v_${normalizeVersion(version)}`;
+
+const DEP_PREFIX = '_ns_package_t_package_n_';
+
+// Split a dependency full-id back into its normalized parts (version = last `_v_` segment,
+// which is unambiguous because a normalized version never itself contains `_v_`).
+export function parseDependencyFullId(id) {
+  if (typeof id !== 'string' || !id.startsWith(DEP_PREFIX)) return null;
+  const body = id.slice(DEP_PREFIX.length);
+  const i = body.lastIndexOf('_v_');
+  if (i < 0) return null;
+  return { normSpecifier: body.slice(0, i), normVersion: body.slice(i + 3) };
+}
+
+export const isDependencyFullId = (id) => parseDependencyFullId(id) !== null;

package/src/resolver.d.ts

@@ -0,0 +1,29 @@
+// Types for the plain-JS resolver: this package ships JS on purpose (node imports it
+// untranspiled), so its types live beside it — a consumer in another package must not have to
+// declare them again. They used to be an ambient shim inside @mosetta/server, invisible to
+// everyone else.
+export interface IRuntimeResolver {
+  resolveUrl(id: string, parentUrl?: string): string | null;
+  setConfig(cfg: unknown): void;
+  readonly shared: Record<string, unknown>;
+}
+
+export interface IResolverOptions {
+  base?: string;
+  config?: unknown;
+  warn?: (message: string) => void;
+  /** the artifact's integrity when known — the url is then content-addressed (`?v=`) */
+  integrityOf?: (id: string) => string | undefined;
+  /** the base of the code source the catalog places the id with; undefined — the default rules */
+  baseOf?: (id: string) => string | undefined;
+}
+
+export function createResolver(opts?: IResolverOptions): IRuntimeResolver;
+
+export function installResolver(system: unknown, opts?: IResolverOptions): IRuntimeResolver;
+
+/** the url-safe version token of an integrity (`sha256-…`); null without one */
+export function versionTokenOf(integrity: string | undefined | null): string | null;
+
+/** `url` addressed by its content: `?v=<token>` appended when the integrity is known */
+export function versionedUrl(url: string, integrity: string | undefined | null): string;

package/src/resolver.js

@@ -0,0 +1,137 @@
+// Runtime dependency resolver. Replaces the enumerated import map: id→URL is a pure
+// formula over the version-qualified full-id, so the only real data is policy (singleton/pin).
+// The resolver is package-agnostic: it bakes in NO package names. Version-alignment policy is data,
+// supplied by the caller — it lives in the app node's settings in the page tree (content-manager
+// configured in the editor), not in this runtime.
+import {
+  normalizeSpecifier,
+  normalizeVersion,
+  dependencyFullId,
+  parseDependencyFullId,
+  isDependencyFullId,
+} from './naming.js';
+
+// CONTENT-ADDRESSED ARTIFACT URLS. An artifact's address carries its integrity: `…/<id>.js?v=<hash>`.
+// A versioned folder alone is not enough — a rebuild under an unchanged version (every deploy
+// of a 0.0.1 distribution) replaces the bytes behind the same address, and a cache that still
+// holds the old ones (the CDN edge, the browser) serves them against a page that pins the new
+// digest: the browser refuses them. With the hash in the address new bytes are a new address.
+// The version token is the integrity digest itself, url-safe and short — the SAME function builds
+// the shell's preload links, its boot scripts and every url the browser loader resolves, so a
+// preloaded script and the script that uses it are one address.
+/** the url-safe version token of an integrity (`sha256-…`); null without one */
+export function versionTokenOf(integrity) {
+  if (typeof integrity !== 'string' || !integrity) return null;
+  const digest = integrity.replace(/^sha\d+-/, '').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  return digest ? digest.slice(0, 16) : null;
+}
+
+/** `url` addressed by its content: `?v=<token>` appended when the integrity is known */
+export function versionedUrl(url, integrity) {
+  const token = versionTokenOf(integrity);
+  if (!token) return url;
+  return `${url}${url.includes('?') ? '&' : '?'}v=${token}`;
+}
+
+// Distributive root of the importer: artifacts live at <root>/{modules,dependencies,runtime}/...
+// Derived from parentUrl so an ISOLATED dep resolves against its importer's OWN provider
+// (multi-provider co-location), falling back to a configured base for top-level imports (no parent).
+function providerRootOf(parentUrl, fallbackBase) {
+  if (parentUrl) {
+    let best = -1;
+    for (const seg of ['/modules/', '/runtime/']) {
+      const i = parentUrl.lastIndexOf(seg);
+      if (i > best) best = i;
+    }
+    if (best >= 0) return parentUrl.slice(0, best + 1); // keep the leading slash → ends with '/'
+  }
+  return fallbackBase;
+}
+
+// Apply version policy to an incoming dep full-id. Returns the canonical full-id to load plus flags:
+// - singleton: must be ONE instance per page → resolve against the host origin (base), not parentUrl.
+// - version remap (pin/version): every version of the pkg collapses to the canonical one.
+// A pkg absent from `shared` is isolatable: identity + co-located origin (multiple versions coexist).
+function applyPolicy(id, shared) {
+  const parsed = parseDependencyFullId(id);
+  if (!parsed) return { target: id, singleton: false };
+  for (const key of Object.keys(shared)) {
+    if (parsed.normSpecifier !== normalizeSpecifier(key)) continue;
+    const rule = shared[key] || {};
+    const ver = rule.pin || rule.version; // explicit canonical version, if declared
+    return {
+      target: ver ? dependencyFullId(key, ver) : id,
+      singleton: rule.singleton === true,
+      key,
+      requested: parsed.normVersion,
+      canonical: ver ? normalizeVersion(ver) : parsed.normVersion,
+    };
+  }
+  return { target: id, singleton: false };
+}
+
+/**
+ * Create a resolver. `base` is the host distributive root (where the page/app module is served) —
+ * SINGLETONS resolve against it so every component, regardless of its own provider origin, shares
+ * one instance. `config` is `{ shared }`. `setConfig` lets the bootstrap refine policy before
+ * importing page modules.
+ *
+ * `integrityOf(id)` — the artifact's integrity when known: the url is then content-addressed.
+ *
+ * `baseOf(id)` — where the page's catalog says the entity lives (the base of its code source, when
+ * it is not the host's): an id the catalog places is read THERE, singleton or not — a site's code
+ * may come from several sources, and a package one source's blocks import may lie with another.
+ * An id it does not place falls back to the rules above.
+ *
+ * @param {{ base?: string, config?: { shared?: Record<string, unknown> }, warn?: (m: string) => void, integrityOf?: (id: string) => string | undefined, baseOf?: (id: string) => string | undefined }} [options]
+ */
+export function createResolver({ base, config, warn = (m) => console.warn(m), integrityOf, baseOf } = {}) {
+  let shared = { ...(config && config.shared) };
+  const warned = new Set();
+
+  function maybeWarn(p, parentUrl) {
+    if (p.requested === p.canonical) return;
+    const k = `${p.key}:${p.requested}->${p.canonical}`;
+    if (warned.has(k)) return;
+    warned.add(k);
+    const major = (v) => v.split('_')[0];
+    const sev = major(p.requested) !== major(p.canonical)
+      ? 'major mismatch — likely incompatible'
+      : 'version substitution';
+    const dot = (v) => v.replace(/_/g, '.');
+    warn(`[mosetta] singleton ${p.key}: ${dot(p.requested)} → ${dot(p.canonical)} (${sev})`
+      + (parentUrl ? ` for ${parentUrl}` : ''));
+  }
+
+  return {
+    setConfig(cfg) {
+      shared = { ...(cfg && cfg.shared) };
+    },
+    get shared() {
+      return shared;
+    },
+    // returns a resolved URL for a dep full-id, or null if `id` is not ours (caller falls back)
+    resolveUrl(id, parentUrl) {
+      if (!isDependencyFullId(id)) return null;
+      const p = applyPolicy(id, shared);
+      // where the catalog places the (canonical) id; else singleton → canonical HOST origin (base)
+      // so cross-provider components dedup to one instance; isolated → co-located with the importer
+      const root = (baseOf && baseOf(p.target)) || (p.singleton ? base : providerRootOf(parentUrl, base));
+      if (p.singleton) maybeWarn(p, parentUrl);
+      // content-addressed when the caller knows the artifact's integrity (the browser, from the
+      // page's catalog); the server links by address and passes none
+      return versionedUrl(new URL(`modules/${p.target}/${p.target}.js`, root).href, integrityOf ? integrityOf(p.target) : undefined);
+    },
+  };
+}
+
+// Install the resolver as a SystemJS `resolve` hook (instance-level, leaves other instances alone).
+export function installResolver(System, opts = {}) {
+  const resolver = createResolver(opts);
+  const orig = System.resolve.bind(System);
+  System.resolve = (id, parentUrl) => {
+    const url = resolver.resolveUrl(id, parentUrl);
+    return url !== null ? url : orig(id, parentUrl);
+  };
+  return resolver;
+}

package/src/tileLoader.js

@@ -0,0 +1,42 @@
+// Safe, shared module loader. The ONE mechanism for loading a module —
+// used both by the initial bootstrap preload and by later dynamic loads. `load()` ALWAYS resolves
+// to an ILoadedTile: { reference, module } on success, { reference, module: undefined, error } on
+// failure — it NEVER rejects. So Promise.all over many loads can't blow up the app, and the React
+// layer consumes the very same ILoadedTile shape. Results are cached per reference (dedup + reuse).
+export function createTileLoader(System, urlOf) {
+  const pending = new Map(); // ref -> Promise<ILoadedTile> (in flight)
+  const resolved = new Map(); // ref -> ILoadedTile (settled)
+
+  function load(ref, providerBase) {
+    const done = resolved.get(ref);
+    if (done) return Promise.resolve(done);
+    const inflight = pending.get(ref);
+    if (inflight) return inflight;
+
+    const p = Promise.resolve()
+      .then(() => System.import(urlOf(ref, providerBase)))
+      .then(
+        (ns) => ({ reference: ref, module: ns.default, error: undefined }),
+        (error) => ({ reference: ref, module: undefined, error }),
+      )
+      .then((im) => {
+        resolved.set(ref, im);
+        pending.delete(ref);
+        return im;
+      });
+
+    pending.set(ref, p);
+    return p;
+  }
+
+  return {
+    load, // (ref, providerBase?) => Promise<ILoadedTile> — always resolves
+    get: (ref) => resolved.get(ref), // ILoadedTile | undefined — sync accessor for the holder
+    // a settled FAILURE is forgotten, so the next load tries again (a later page asking for a
+    // module the first one could not reach); a success stays
+    forget: (ref) => {
+      const done = resolved.get(ref);
+      if (done && done.error) resolved.delete(ref);
+    },
+  };
+}