@mosetta/runtime 0.0.0-stage → 0.0.9

package/src/client/router.ts

@@ -0,0 +1,453 @@
+import { SingleDiToken } from '@mosetta/di';
+import type { IBlueprint, IRouteMatch } from '@mosetta/core';
+import { DOCUMENT_QUERY_PARAM, isRightToLeft, languageScheme, matchPattern, parsePattern } from '@mosetta/core';
+import type { PageManager } from './pageManager';
+import type { IHeadWriter } from './headWriter';
+import type { ITilesHolder } from './tokens';
+
+// The CLIENT ROUTER (ADR-0051): a move to another address of the site without a document load.
+// The page's document is fetched as JSON from the same address (DOCUMENT_QUERY_PARAM), the realm
+// is made ready for its tree (modules, css), the tree is swapped under the running application
+// through the page manager — the very mechanism the editor's preview uses for live composition —
+// and history, scroll and the head follow. Nodes with the same id on both pages stay mounted:
+// a layout shared by two pages is one layout.
+//
+// Framework-agnostic: the react binding wraps it in `useRouter()` and `<Link>`. Alive only for
+// the page's own boot in a browser; in a preview realm, a hosted mount and on the server an
+// INERT twin answers "not mine" and a link behaves as a link.
+
+export interface INavigateOptions {
+  /** replace the current history entry instead of adding one */
+  readonly replace?: boolean;
+  /** scroll to the top (or to the hash) once the page is in; default true */
+  readonly scroll?: boolean;
+  /**
+   * SHALLOW: a new address of the SAME page — the route is re-read against the page's own pattern,
+   * no document is fetched (tabs and widths living in the query). Refused (answers false) when
+   * the address is not this page's.
+   */
+  readonly shallow?: boolean;
+}
+
+export interface IRouterSnapshot {
+  /** a move is in flight */
+  readonly pending: boolean;
+  /** the address the router last moved to (or was born at) — path, search and hash */
+  readonly href: string;
+}
+
+export interface IRouter {
+  /** whether moves happen in place here at all */
+  readonly active: boolean;
+  /**
+   * Move to an address. Resolves true when the router took the move (in place, or by starting a
+   * full load itself when the document could not be used); false when it is not the router's —
+   * another origin, an inert router — and the caller lets the browser go.
+   */
+  navigate(href: string, options?: INavigateOptions): Promise<boolean>;
+  /** one step back in history */
+  back(): void;
+  snapshot(): IRouterSnapshot;
+  /** the useSyncExternalStore contract */
+  subscribe(listener: () => void): () => void;
+  /** start listening to history; the returned function stops */
+  attach(): () => void;
+}
+
+export const ROUTER_TOKEN = new SingleDiToken<IRouter>('ROUTER_TOKEN');
+
+/** what a page's document carries beyond its tree, as the server answers DOCUMENT_QUERY_PARAM */
+export interface IPageDocument extends IBlueprint {
+  readonly meta?: { readonly title?: string; readonly description?: string } & Record<string, unknown>;
+  readonly hostBase?: string;
+  readonly settings?: { readonly versions?: unknown } & Record<string, unknown>;
+  readonly head?: readonly IHeadTagOfDocument[];
+}
+
+export interface IHeadTagOfDocument {
+  readonly key: string;
+  readonly tag: string;
+  readonly attributes: Record<string, string>;
+}
+
+/** the browser as the router sees it — a seam, so the router's logic is tested without one */
+export interface IRouterHost {
+  href(): string;
+  origin(): string;
+  pushState(state: unknown, url: string): void;
+  replaceState(state: unknown, url: string): void;
+  state(): unknown;
+  back(): void;
+  onPopState(listener: (state: unknown) => void): () => void;
+  /** the page's document at this address, or null when the answer is not one (a 404, a sign-in, html) */
+  fetchDocument(url: string): Promise<IPageDocument | null>;
+  /** a full document load */
+  assign(url: string): void;
+  scrollTo(x: number, y: number): void;
+  scrollPosition(): { x: number; y: number };
+  /** scroll to the element the hash names; false when there is none */
+  scrollToHash(hash: string): boolean;
+  /** the document's own words: title, description, the language of the html element */
+  describe(words: { title?: string; description?: string; lang?: string; rtl: boolean }): void;
+}
+
+/**
+ * The mark the router leaves on the history entries it makes: a number of its own, and the
+ * pattern of the page shown there — a pop onto an entry of the SAME page re-reads the route
+ * instead of fetching (a page whose pattern swallows addresses of other pages, `/x/{...rest}`,
+ * would otherwise claim them all on the way back).
+ */
+interface IRouterState {
+  readonly mosetta: { readonly seq: number; readonly pattern?: string };
+}
+
+function isRouterState(state: unknown): state is IRouterState {
+  return typeof state === 'object' && state !== null && 'mosetta' in state && typeof (state as IRouterState).mosetta === 'object';
+}
+
+/** path, search and hash of an address — what history is given and what `href` reports */
+const addressOf = (url: URL): string => url.pathname + url.search + url.hash;
+
+/** head keys written per NODE — swept when the node is gone with its page */
+const NODE_KEYED_HEAD = /^(styler|theme|theme-fonts):(.+)$/;
+const SEO_HEAD_PREFIX = 'seo:';
+
+/** every node id of a tree */
+function idsOf(page: IBlueprint): Set<string> {
+  const ids = new Set<string>();
+  const walk = (node: IBlueprint): void => {
+    if (node.id) ids.add(node.id);
+    for (const child of node.children ?? []) walk(child as IBlueprint);
+  };
+  walk(page);
+  return ids;
+}
+
+/**
+ * The route the page would carry at this address — when the address is this page's (its own
+ * pattern, in the same language); null when it is another page's. Params and the query come
+ * from the address, the language scheme stays the server's word.
+ */
+export function rerouteOf(page: IBlueprint, url: URL): IRouteMatch | null {
+  const route = page.route;
+  if (!route) return null;
+  const languages = route.addressing;
+  const read: { lang: string | undefined; path: string } = languages
+    ? languageScheme(languages.scheme).read(url.pathname, languages)
+    : { lang: undefined, path: url.pathname };
+  if ((read.lang ?? languages?.defaultLanguage) !== (route.lang ?? languages?.defaultLanguage)) return null;
+  const pattern = typeof route.pattern === 'string' ? route.pattern : page.pattern;
+  if (typeof pattern !== 'string') return null;
+  const target = new URL(url.href);
+  target.pathname = read.path;
+  let match: IRouteMatch | null;
+  try {
+    match = matchPattern(parsePattern(pattern), target);
+  } catch {
+    return null;
+  }
+  if (!match) return null;
+  const search: Record<string, string> = {};
+  url.searchParams.forEach((value, key) => {
+    if (key !== DOCUMENT_QUERY_PARAM) search[key] = value;
+  });
+  return { ...match, lang: route.lang, addressing: route.addressing, path: read.path, search };
+}
+
+/**
+ * The same realm serves both pages: one root module, one version policy, one host base — the
+ * last compared only when both documents name it (a page mounted by hand, a static build's,
+ * names none: the resolver installed at boot is what there is).
+ */
+function sameRealm(current: IPageDocument, next: IPageDocument): boolean {
+  return current.reference === next.reference
+    && (!current.hostBase || !next.hostBase || current.hostBase === next.hostBase)
+    && JSON.stringify(current.settings?.versions ?? null) === JSON.stringify(next.settings?.versions ?? null);
+}
+
+export class ClientRouter implements IRouter {
+  readonly active = true;
+
+  private readonly listeners = new Set<() => void>();
+
+  private seq = 0;
+
+  private pending = false;
+
+  private href: string;
+
+  /** the mark of the entry the browser is on, when this router made it; null on someone else's */
+  private ownSeq: number | null = null;
+
+  /** where each of the router's entries was scrolled to when it was left, by its mark */
+  private readonly scrolls = new Map<number, { x: number; y: number }>();
+
+  /** the snapshot as a VALUE: the same object until the state moves (useSyncExternalStore reads it by identity) */
+  private snap: IRouterSnapshot;
+
+  constructor(
+    private readonly host: IRouterHost,
+    private readonly manager: PageManager,
+    private readonly holder: ITilesHolder,
+    private readonly head: IHeadWriter,
+  ) {
+    this.href = addressOf(new URL(host.href()));
+    this.snap = { pending: false, href: this.href };
+  }
+
+  /**
+   * Start listening to history. The entry the page was loaded on gets the router's mark too
+   * (its address stays): a pop back onto it is then the router's to answer, like any other.
+   */
+  attach(): () => void {
+    const state = this.host.state();
+    if (!isRouterState(state)) {
+      const current = this.manager.getCurrentPage() as IPageDocument;
+      this.host.replaceState({ mosetta: { seq: this.seq, ...(current.route?.pattern !== undefined ? { pattern: current.route.pattern } : {}) } }, this.href);
+      this.ownSeq = this.seq;
+    } else {
+      this.ownSeq = state.mosetta.seq;
+    }
+    return this.host.onPopState((state) => this.onPopState(state));
+  }
+
+  snapshot(): IRouterSnapshot {
+    return this.snap;
+  }
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  back(): void {
+    this.host.back();
+  }
+
+  async navigate(href: string, options: INavigateOptions = {}): Promise<boolean> {
+    const target = new URL(href, this.host.href());
+    if (target.origin !== this.host.origin()) return false;
+    const current = this.manager.getCurrentPage() as IPageDocument;
+    if (options.shallow) {
+      const route = rerouteOf(current, target);
+      if (!route) return false;
+      this.rememberScroll();
+      this.commit(target, options.replace === true, route.pattern);
+      this.manager.setCurrentPage({ ...current, route });
+      this.notify();
+      return true;
+    }
+    await this.move(target, { history: options.replace ? 'replace' : 'push', scroll: options.scroll !== false ? 'top' : 'keep' });
+    return true;
+  }
+
+  /**
+   * A move onto an address: the document fetched and prepared, then history, the tree, the head
+   * and the scroll — in that order, so a listener of history sees the new tree. A later move
+   * supersedes this one at every await.
+   */
+  private async move(target: URL, how: { history: 'push' | 'replace' | 'none'; scroll: 'top' | 'keep' | { x: number; y: number } }): Promise<void> {
+    const seq = ++this.seq;
+    this.pending = true;
+    this.notify();
+    const current = this.manager.getCurrentPage() as IPageDocument;
+    const settle = (): void => {
+      if (seq !== this.seq) return;
+      this.pending = false;
+      this.notify();
+    };
+    let next: IPageDocument | null = null;
+    try {
+      next = await this.host.fetchDocument(this.documentUrl(target));
+    } catch {
+      next = null;
+    }
+    if (seq !== this.seq) return;
+    if (!next || !next.reference || !sameRealm(current, next)) {
+      // not a document of this realm — the browser loads it whole (a sign-in, a 404, another root)
+      settle();
+      this.host.assign(target.href);
+      return;
+    }
+    try {
+      await this.holder.prepare?.(next);
+    } catch {
+      settle();
+      this.host.assign(target.href);
+      return;
+    }
+    if (seq !== this.seq) return;
+    if (how.history !== 'none') {
+      this.rememberScroll();
+      this.commit(target, how.history === 'replace', next.route?.pattern);
+    } else {
+      this.href = addressOf(target);
+      const state = this.host.state();
+      this.ownSeq = isRouterState(state) ? state.mosetta.seq : null;
+    }
+    this.manager.setCurrentPage(next);
+    this.writeHead(next);
+    settle();
+    if (how.scroll === 'top') {
+      if (!target.hash || !this.host.scrollToHash(target.hash)) this.host.scrollTo(0, 0);
+    } else if (how.scroll !== 'keep') {
+      this.host.scrollTo(how.scroll.x, how.scroll.y);
+    }
+  }
+
+  private documentUrl(target: URL): string {
+    const url = new URL(target.href);
+    url.hash = '';
+    url.searchParams.set(DOCUMENT_QUERY_PARAM, '1');
+    return url.href;
+  }
+
+  /** the history entry for the address: marked as the router's own, with the page shown there */
+  private commit(target: URL, replace: boolean, pattern: string | undefined): void {
+    const state: IRouterState = { mosetta: { seq: this.seq, ...(pattern !== undefined ? { pattern } : {}) } };
+    const url = addressOf(target);
+    if (replace) this.host.replaceState(state, url);
+    else this.host.pushState(state, url);
+    this.href = url;
+    this.ownSeq = this.seq;
+  }
+
+  /**
+   * The scroll position of the entry being left, kept for the way back — read BEFORE anything
+   * renders, while the page is still where the reader left it (own entries only).
+   */
+  private rememberScroll(): void {
+    if (this.ownSeq !== null) this.scrolls.set(this.ownSeq, this.host.scrollPosition());
+  }
+
+  /**
+   * Back and forward. The router answers for the entries it marked — the one the page was
+   * loaded on, the ones its moves made; an entry someone else made (a shell with history of its
+   * own) is not its business.
+   */
+  private onPopState(state: unknown): void {
+    if (!isRouterState(state)) return;
+    // the entry being left: its scroll, while the page still shows it (the browser moved the
+    // history already — the mark remembered before this is the entry left)
+    this.rememberScroll();
+    const target = new URL(this.host.href());
+    const scroll = this.scrolls.get(state.mosetta.seq) ?? null;
+    const current = this.manager.getCurrentPage() as IPageDocument;
+    // the same page only when the entry says so: a pattern alone would let a catch-all page
+    // claim every address under it
+    const samePage = state.mosetta.pattern !== undefined && state.mosetta.pattern === current.route?.pattern;
+    const route = samePage ? rerouteOf(current, target) : null;
+    if (route) {
+      // the same page at another of its addresses: the route is re-read, nothing is fetched
+      this.seq++;
+      this.pending = false;
+      this.href = addressOf(target);
+      this.ownSeq = state.mosetta.seq;
+      this.manager.setCurrentPage({ ...current, route });
+      this.notify();
+      if (scroll) this.host.scrollTo(scroll.x, scroll.y);
+      return;
+    }
+    void this.move(target, { history: 'none', scroll: scroll ?? 'top' });
+  }
+
+  /** the document's words and the protocol's tags; what the page before left behind is swept */
+  private writeHead(next: IPageDocument): void {
+    const lang = next.route?.lang ?? next.route?.addressing?.defaultLanguage;
+    this.host.describe({ title: next.meta?.title, description: next.meta?.description, lang, rtl: isRightToLeft(lang) });
+    const keep = new Set<string>();
+    for (const tag of next.head ?? []) {
+      keep.add(tag.key);
+      this.head.addToHead(tag.key, tag.tag, tag.attributes);
+    }
+    const ids = idsOf(next);
+    for (const key of this.head.headKeys?.() ?? []) {
+      if (key.startsWith(SEO_HEAD_PREFIX) && !keep.has(key)) this.head.removeFromHead?.(key);
+      const node = NODE_KEYED_HEAD.exec(key);
+      if (node && !ids.has(node[2])) this.head.removeFromHead?.(key);
+    }
+  }
+
+  private notify(): void {
+    if (this.snap.pending !== this.pending || this.snap.href !== this.href) this.snap = { pending: this.pending, href: this.href };
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+const INERT_SNAPSHOT: IRouterSnapshot = { pending: false, href: '' };
+
+/** where moves do not happen in place: the server, a preview realm, a hosted mount */
+export class InertRouter implements IRouter {
+  readonly active = false;
+
+  navigate(): Promise<boolean> {
+    return Promise.resolve(false);
+  }
+
+  back(): void {
+    if (typeof history !== 'undefined') history.back();
+  }
+
+  snapshot(): IRouterSnapshot {
+    return INERT_SNAPSHOT;
+  }
+
+  subscribe(): () => void {
+    return () => undefined;
+  }
+
+  attach(): () => void {
+    return () => undefined;
+  }
+}
+
+/** the browser behind the router */
+export function browserRouterHost(): IRouterHost {
+  return {
+    href: () => window.location.href,
+    origin: () => window.location.origin,
+    pushState: (state, url) => window.history.pushState(state, '', url),
+    replaceState: (state, url) => window.history.replaceState(state, '', url),
+    state: (): unknown => window.history.state as unknown,
+    back: () => window.history.back(),
+    onPopState: (listener) => {
+      const handler = (event: PopStateEvent): void => listener(event.state);
+      window.addEventListener('popstate', handler);
+      return () => window.removeEventListener('popstate', handler);
+    },
+    fetchDocument: async (url) => {
+      const response = await fetch(url, { headers: { accept: 'application/json' }, credentials: 'same-origin' });
+      if (!response.ok || !(response.headers.get('content-type') ?? '').includes('application/json')) return null;
+      return response.json() as Promise<IPageDocument>;
+    },
+    assign: (url) => window.location.assign(url),
+    scrollTo: (x, y) => window.scrollTo(x, y),
+    scrollPosition: () => ({ x: window.scrollX, y: window.scrollY }),
+    scrollToHash: (hash) => {
+      const id = decodeURIComponent(hash.replace(/^#/, ''));
+      const el = id ? document.getElementById(id) : null;
+      if (!el) return false;
+      el.scrollIntoView();
+      return true;
+    },
+    describe: ({ title, description, lang, rtl }) => {
+      if (title !== undefined) document.title = title;
+      let meta = document.head.querySelector<HTMLMetaElement>('meta[name="description"]');
+      if (description) {
+        if (!meta) {
+          meta = document.createElement('meta');
+          meta.name = 'description';
+          document.head.appendChild(meta);
+        }
+        meta.content = description;
+      } else {
+        meta?.remove();
+      }
+      if (lang) document.documentElement.lang = lang;
+      if (rtl) document.documentElement.dir = 'rtl';
+      else document.documentElement.removeAttribute('dir');
+    },
+  };
+}

package/src/client/serverRender.ts

@@ -0,0 +1,12 @@
+// Effective-ssr — the pure half of the client gate (SSR epic stage 4; the react scope/gate live
+// in @mosetta/react). A node is server-rendered iff the branch is enabled AND neither the node
+// nor an ancestor opted out (ssr:false) or is lazy. The SAME rule the server's closure walk
+// applies (server router/closure.ts).
+export interface ISsrFlags {
+  ssr?: unknown;
+  lazy?: unknown;
+}
+
+export function isNodeServerRendered(node: ISsrFlags, inherited: boolean): boolean {
+  return inherited && node.ssr !== false && node.lazy !== true;
+}

package/src/client/tile.ts

@@ -0,0 +1,7 @@
+import { IWithError, IWithTileReference } from '@mosetta/core';
+
+// The unified module envelope every loader resolves to ({module} or {error} — never a reject);
+// the holder, useTile and the safe loaders all speak this shape. Framework-agnostic.
+export interface ILoadedTile<T = unknown> extends IWithTileReference, IWithError {
+  readonly module: T;
+}

package/src/client/tokens.ts

@@ -0,0 +1,70 @@
+import { SingleDiToken } from '@mosetta/di';
+import type { Constructable, DiContainer } from '@mosetta/di';
+import { ILoadedTile } from './tile';
+import type { ISsrRenderChannel } from './headWriter';
+
+export interface ITilesHolder {
+  // sync accessor for an already-loaded module (its failure, if any, travels in ILoadedTile.error)
+  getModule(moduleId: string): ILoadedTile;
+  // unified safe loader — always resolves to an ILoadedTile ({module} or {error}); used for dynamic/lazy
+  // loads on top of the same mechanism the initial bootstrap uses. Optional: a holder may be preload-only.
+  loadModule?(moduleId: string, providerBase?: string): Promise<ILoadedTile>;
+  /**
+   * The realm made ready for another page's tree (ADR-0051): its catalog slice joined, the css
+   * of its eager closure in place, its modules loaded. The browser bootstrap's holder has it;
+   * the server's twin and a host's do not — no client-side move happens there.
+   */
+  prepare?(tree: object): Promise<void>;
+}
+
+export const TILES_HOLDER_TOKEN = new SingleDiToken<ITilesHolder>('TILES_HOLDER_TOKEN');
+
+/**
+ * The HOST application's own container, when this application was MOUNTED by one
+ * (IMountOptions.parentDi); null for a page's own boot. The Unity-editor door: a mount is
+ * same-realm by construction (it takes a live DOM element), tokens are STRING-keyed with
+ * duck-typed guards (a foreign copy of the di package reads a foreign container fine), and
+ * in-realm "isolation" was only ever a convention — the enforced boundary is the realm (the
+ * canvas iframe). So editor-time code gets the parent environment whole, and what a host means
+ * to EXPOSE it registers in its own container under a named token (the settings draft).
+ */
+export const PARENT_DI_TOKEN = new SingleDiToken<DiContainer | null>('PARENT_DI_TOKEN');
+
+// The per-request ssr render channel AS DATA: createAppContainer always registers it
+// (null in the browser) so lazily-wired slices (useServerAction) can flip their server wiring
+// without the ROOT knowing about any optional feature. Zero feature code lives behind this token.
+export const SSR_RENDER_CHANNEL_TOKEN = new SingleDiToken<ISsrRenderChannel | null>('SSR_RENDER_CHANNEL_TOKEN');
+
+/** a whole preview realm — the canvas iframe, marked by its shell before bootstrap */
+export const FULL_APP_PREVIEW = 'fullApp';
+
+/** one mounted specimen — the palette's bubble (and the future storybook) */
+export const PALETTE_PREVIEW = 'palette';
+
+export type TPreviewType = typeof FULL_APP_PREVIEW | typeof PALETTE_PREVIEW;
+
+/**
+ * A host's word that the application it mounts is a SPECIMEN — a typed MOUNT OPTION
+ * (IMountOptions.preview), deliberately NOT a host contract: `host` is the bridge for data
+ * addressed to the hosted MODULES (read via HOST_CONTRACTS_TOKEN), while this is addressed to
+ * the CONTAINER — the type feeds PREVIEW_TYPE_TOKEN, and the services are DI classes no module
+ * may ever read as data.
+ */
+export interface IMountPreview {
+  readonly type: TPreviewType;
+  /**
+   * DI services that make the specimen's environment REAL ENOUGH for the live component to
+   * render (a seeded editing session, a canned data source) — registered into the specimen's
+   * container before anything renders. The preview stays the real component; these arrange its
+   * world, never its markup.
+   */
+  readonly services?: readonly Constructable[];
+}
+
+/**
+ * Previewness as a CONTAINER fact, not a flag smuggled through markup: createAppContainer
+ * computes it once per application — the mount option wins (it speaks about this one mounted
+ * specimen), the realm mark `__mosettaPreview` covers the whole preview iframe, and everything
+ * else is an ordinary live application (null).
+ */
+export const PREVIEW_TYPE_TOKEN = new SingleDiToken<TPreviewType | null>('PREVIEW_TYPE_TOKEN');

package/src/domEvents.ts

@@ -0,0 +1,118 @@
+import { DiContainer, SingleDiToken } from '@mosetta/di';
+
+/**
+ * Window-level custom events, built in the realm they are dispatched to.
+ *
+ * Take this instead of reaching for `new CustomEvent(...)` directly. An Event constructed in one
+ * realm is not an Event to a target in another — an iframe, a preview, jsdom under node — and the
+ * failure surfaces as a TypeError inside `dispatchEvent`, far from the code that picked the
+ * constructor. The rule is easy to state and easy to forget, so it lives here once: the event is
+ * built by the very window it is sent to.
+ *
+ * The window is a constructor parameter, so a test hands over a fake one instead of patching
+ * globals; left out, it is read from the environment at call time (a module may well be evaluated
+ * on the server, where there is no window at all).
+ */
+export class DomEventBus {
+  // `Window & typeof globalThis` and not a bare Window: the event CONSTRUCTORS live on the global
+  // scope of that window, and they are the whole point of this class
+  constructor(private readonly host?: Window & typeof globalThis) {}
+
+  /** send `detail` to everyone listening for `type` on this window */
+  emit<TDetail>(type: string, detail: TDetail): void {
+    const target = this.target();
+    target.dispatchEvent(new target.CustomEvent(type, { detail }));
+  }
+
+  /** listen for `type`; the returned callback stops listening */
+  on<TDetail>(type: string, listener: (detail: TDetail) => void): () => void {
+    const target = this.target();
+    const handler = (event: Event): void => listener((event as CustomEvent<TDetail>).detail);
+    target.addEventListener(type, handler);
+    return () => target.removeEventListener(type, handler);
+  }
+
+  private target(): Window & typeof globalThis {
+    return this.host ?? window;
+  }
+}
+
+/** the ambient window's bus — for modules that have no reason to own one */
+export const windowEvents = new DomEventBus();
+
+// ---- the URL QUERY as a DI-resolvable tool ----------------------------------------------------
+
+/**
+ * READ AND WRITE the page URL's query parameters — the address-bar face of workbench state that
+ * should survive a reload (e.g. which drafts are open in which canvas tabs). Writing goes through
+ * history.replaceState: the address changes, nothing navigates, nothing lands in history.
+ */
+export abstract class QueryParams {
+  abstract get(name: string): string | null;
+
+  /** set (or, with null, remove) one parameter — the rest of the URL stays as it was */
+  abstract set(name: string, value: string | null): void;
+}
+
+/**
+ * URLSearchParams SERIALIZES conservatively (form-urlencoding): it percent-encodes every character
+ * outside `A-Za-z0-9*-._`, turning a value like `20:(tree,palette)` into `20%3A%28tree%2C...` in
+ * the address bar — three times the length and none of the readability. RFC 3986 allows far more
+ * in a query RAW, and URLSearchParams DECODES those characters just fine, so writing goes through
+ * this minimal encoder instead: encodeURIComponent, with the query-legal punctuation restored.
+ * `+` stays out of the friendly set on purpose — a raw `+` form-decodes to a space.
+ */
+function queryText(part: string): string {
+  return encodeURIComponent(part)
+    .replace(/%2C/gi, ',')
+    .replace(/%3A/gi, ':')
+    .replace(/%3B/gi, ';')
+    .replace(/%40/gi, '@')
+    .replace(/%2F/gi, '/')
+    .replace(/%7E/gi, '~');
+}
+
+class LocationQueryParams extends QueryParams {
+  constructor(private readonly host: Window & typeof globalThis) {
+    super();
+  }
+
+  get(name: string): string | null {
+    return new this.host.URLSearchParams(this.host.location.search).get(name);
+  }
+
+  set(name: string, value: string | null): void {
+    const url = new this.host.URL(this.host.location.href);
+    const params = new this.host.URLSearchParams(url.search);
+    if (value === null) params.delete(name);
+    else params.set(name, value);
+    url.search = [...params].map(([key, item]) => `${queryText(key)}=${queryText(item)}`).join('&');
+    if (url.href === this.host.location.href) return;
+    try {
+      this.host.history.replaceState(this.host.history.state, '', url.href);
+    } catch {
+      // some browsers throttle replaceState (Safari: ~100 per 30s) and THROW past the limit —
+      // the address is a convenience, never correctness, so a dropped write stays dropped
+    }
+  }
+}
+
+/** the ambient window's query, or null where there is no address bar (server renders) */
+export function queryParamsOf(host?: Window & typeof globalThis): QueryParams | null {
+  const target = host ?? (typeof window === 'undefined' ? null : window);
+  return target ? new LocationQueryParams(target) : null;
+}
+
+export const QUERY_PARAMS_TOKEN = new SingleDiToken<QueryParams>('QUERY_PARAMS_TOKEN');
+
+/**
+ * The DI face: registered lazily by whoever asks first (the same pattern as the editing session),
+ * resolvable by everyone after — and overridable by a test or an environment that registers its
+ * own QueryParams before anyone ensures the ambient one. Null where there is no window.
+ */
+export function ensureQueryParams(di: DiContainer): QueryParams | null {
+  if (di.hasByToken(QUERY_PARAMS_TOKEN)) return di.getByToken(QUERY_PARAMS_TOKEN);
+  const params = queryParamsOf();
+  if (params) di.registerValueOfToken(QUERY_PARAMS_TOKEN, params);
+  return params;
+}

package/src/naming.d.ts

@@ -0,0 +1,6 @@
+// Types for the naming canon (plain JS — see resolver.d.ts for why they live here).
+export function normalizeSpecifier(specifier: string): string;
+export function normalizeVersion(version: string): string;
+export function dependencyFullId(specifier: string, version: string): string;
+export function parseDependencyFullId(id: string): { normSpecifier: string; normVersion: string } | null;
+export function isDependencyFullId(id: string): boolean;