react-cheminfo 0.51.0 → 0.53.0

package/src/host/core/protocol.ts

@@ -0,0 +1,197 @@
+/**
+ * The cheminfo host protocol, version 1: what a page that frames a tool — an
+ * electronic lab notebook, a course — and the tool say to each other.
+ *
+ * Two messages travel between the windows — `hello`, from the tool, and
+ * `connect`, the host's answer carrying a private `MessagePort` — and everything
+ * else goes through that port: the host's requests (`load`, `get`) and the
+ * tool's `result` for each. This module only spells the messages, and reads
+ * what arrives as the untrusted input it is.
+ */
+
+/** The version a tool speaks; a `connect` naming another is ignored. */
+export const PROTOCOL_VERSION = 1;
+
+/** Posted to the parent frame or the opener at start-up: who the tool is. */
+export const HELLO_TYPE = 'cheminfo:hello';
+
+/** The host's answer to `hello`, carrying the port the rest goes through. */
+export const CONNECT_TYPE = 'cheminfo:connect';
+
+/** How many items one request may carry; the rest are dropped. */
+export const MAX_ITEMS = 64;
+
+/** How long a label may be, in characters; a longer one is cut. */
+export const MAX_LABEL_LENGTH = 80;
+
+/** One typed value crossing the frame boundary. */
+export interface HostItem {
+  /** A kind name, e.g. `'chem.molfile.2d'`. */
+  kind: string;
+  /** Checked against the kind before anything reads it. */
+  value: unknown;
+  /**
+   * The host's name for it, opaque here, e.g. an attachment.
+   * @default undefined
+   */
+  id?: string;
+  /**
+   * The tool input it is meant for.
+   * @default undefined — any input that accepts its kind
+   */
+  key?: string;
+  /**
+   * What a notice calls it, e.g. `'Ethylbenzene'`.
+   * @default undefined
+   */
+  label?: string;
+}
+
+/** One value the tool takes. */
+export interface ToolInput {
+  key: string;
+  /** Kinds in order of preference; a category accepts every kind under it. */
+  kinds: readonly string[];
+}
+
+/** One value the tool can hand back. */
+export interface ToolOutput {
+  key: string;
+  kind: string;
+}
+
+/** What the tool is and takes, as `hello` announces it. */
+export interface ToolInterface {
+  name: string;
+  inputs: readonly ToolInput[];
+  outputs: readonly ToolOutput[];
+}
+
+/** What `hello` carries: public, readable by any origin. */
+export interface HelloMessage {
+  type: typeof HELLO_TYPE;
+  version: typeof PROTOCOL_VERSION;
+  tool: ToolInterface & {
+    /** The tool's origin, e.g. `'https://3d.cheminfo.org'`. */
+    origin: string;
+    /** The build that is running, as the About states it, or `null`. */
+    build: unknown;
+  };
+}
+
+/** `load`: the host's data, for one document. */
+export interface LoadRequest {
+  type: 'load';
+  id: string;
+  /** What the data belongs to; the same document twice is applied once. */
+  document: string;
+  items: HostItem[];
+}
+
+/** `get`: the current value of some outputs. */
+export interface GetRequest {
+  type: 'get';
+  id: string;
+  keys: string[];
+}
+
+/** A request the host sends through the port. */
+export type HostRequest = LoadRequest | GetRequest;
+
+/** Why a request could not be served. */
+export type HostErrorCode = 'invalid' | 'unreadable' | 'no-input' | 'no-output';
+
+/** What a failed request is answered with. */
+export interface HostError {
+  code: HostErrorCode;
+  /** One sentence, in English. */
+  message: string;
+  /**
+   * What the schema found, as `'chem.ocl.id /idCode: must be string'`.
+   * @default undefined
+   */
+  errors?: string[];
+}
+
+/** Which item an input took. */
+export interface UsedItem {
+  key: string;
+  kind: string;
+}
+
+/** The answer to one request, carrying its `id`. */
+export type ResultMessage =
+  | { type: 'result'; id: string; ok: true; used: UsedItem[] }
+  | { type: 'result'; id: string; ok: false; error: HostError };
+
+/**
+ * Read a message that arrived through the port.
+ *
+ * Anything that is not a well-formed `load` or `get` is `null`, and goes
+ * unanswered: an unknown request is a newer host talking, not an error. An item
+ * without a string `kind` is dropped, and a label is cut to
+ * {@link MAX_LABEL_LENGTH}.
+ * @param data - What the port delivered.
+ * @returns The request, or `null`.
+ */
+export function parseRequest(data: unknown): HostRequest | null {
+  if (!isRecord(data) || typeof data.id !== 'string') return null;
+  if (data.type === 'load') {
+    if (typeof data.document !== 'string' || !Array.isArray(data.items)) {
+      return null;
+    }
+    return {
+      type: 'load',
+      id: data.id,
+      document: data.document,
+      items: readItems(data.items),
+    };
+  }
+  if (data.type === 'get') {
+    return { type: 'get', id: data.id, keys: readStrings(data.keys) };
+  }
+  return null;
+}
+
+/**
+ * Whether a window message is the host's answer to `hello`, in this version.
+ * @param data - What the window delivered.
+ * @returns `true` for a `connect` of {@link PROTOCOL_VERSION}.
+ */
+export function isConnect(data: unknown): boolean {
+  return (
+    isRecord(data) &&
+    data.type === CONNECT_TYPE &&
+    data.version === PROTOCOL_VERSION
+  );
+}
+
+function readItems(values: readonly unknown[]): HostItem[] {
+  const items: HostItem[] = [];
+  const count = Math.min(values.length, MAX_ITEMS);
+  for (let index = 0; index < count; index++) {
+    const value = values[index];
+    if (!isRecord(value) || typeof value.kind !== 'string') continue;
+    const item: HostItem = { kind: value.kind, value: value.value };
+    if (typeof value.id === 'string') item.id = value.id;
+    if (typeof value.key === 'string') item.key = value.key;
+    if (typeof value.label === 'string') {
+      item.label = value.label.slice(0, MAX_LABEL_LENGTH);
+    }
+    items.push(item);
+  }
+  return items;
+}
+
+function readStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const strings: string[] = [];
+  for (const entry of value) {
+    if (typeof entry === 'string') strings.push(entry);
+  }
+  return strings;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/host/testing/sciPeaks.ts

@@ -0,0 +1,66 @@
+/**
+ * What SciPeaks sends a tool, byte for byte: the `load` its tool tab —
+ * visualizer-helper's `eln/toolTab` — writes for the ethylbenzene sample its own
+ * tests read (`eln/__tests__/data/sample.json`). Both repositories pin this
+ * message, so a change on either side that the other does not expect fails a
+ * test rather than a notebook.
+ *
+ * The sample is a real one, and so are its quirks: its molfile is V2000 with
+ * every atom at the origin, its title is blank so the label is its first name,
+ * and its formula travels as a kind no structure input reads.
+ */
+
+import type { LoadRequest } from '../core/protocol.ts';
+
+/** How SciPeaks' tool tab introduces itself in `connect`. */
+export const SCIPEAKS_HOST_NAME = 'SciPeaks';
+
+/** The molfile SciPeaks stores for ethylbenzene: every atom at the origin. */
+export const SCIPEAKS_ETHYLBENZENE_MOLFILE = [
+  '',
+  'Actelion Java MolfileCreator 1.0',
+  '',
+  '  8  8  0  0  0  0  0  0  0  0999 V2000',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '  1  2  1  0  0  0  0',
+  '  1  3  1  0  0  0  0',
+  '  2  4  2  0  0  0  0',
+  '  2  5  1  0  0  0  0',
+  '  4  6  1  0  0  0  0',
+  '  5  7  2  0  0  0  0',
+  '  6  8  2  0  0  0  0',
+  '  7  8  1  0  0  0  0',
+  'M  END',
+  '',
+].join('\n');
+
+/** The first `load` the tool tab sends for that sample, with `accept`. */
+export const SCIPEAKS_ETHYLBENZENE_LOAD: LoadRequest & { accept: string[] } = {
+  type: 'load',
+  id: 'load-1',
+  document: 'eln:1315a6d895f431497538cb6d834feab5',
+  items: [
+    {
+      kind: 'chem.molfile.2d',
+      value: { molfile: SCIPEAKS_ETHYLBENZENE_MOLFILE },
+      label: 'Ethylbenzene',
+    },
+    {
+      kind: 'chem.ocl.id',
+      value: {
+        idCode: 'daD@@DjUZxHH@@',
+        coordinates: String.raw`!BbOvw?_x@?g?~_{\Bm?t`,
+      },
+      label: 'Ethylbenzene',
+    },
+    { kind: 'chem.mf', value: { mf: 'C8H10' } },
+  ],
+  accept: [],
+};

package/src/host/testing/standInHost.ts

@@ -0,0 +1,116 @@
+/**
+ * A whole host, for a tool's end-to-end tests: a page on another origin that
+ * frames the tool, answers its `hello` with a private port, sends it requests,
+ * and records what comes back.
+ *
+ * It is written the way an electronic lab notebook would write one: it checks
+ * that `hello` came from its frame and from the tool's origin, and connects
+ * only then. A real server serves it on `127.0.0.1` while the tool runs on
+ * `localhost`, so every message crosses a real origin boundary — and it has to
+ * be a real server: Chrome takes a page that Playwright answers itself for a
+ * public one, and a public page may not frame a local site.
+ */
+
+import type { Server } from 'node:http';
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import type { HelloMessage } from '../core/protocol.ts';
+
+/** A running stand-in host. */
+export interface StandInHost {
+  /** Where the host page is served, e.g. `http://127.0.0.1:53211`. */
+  origin: string;
+  /**
+   * The address of a host page that frames `toolUrl` in `#tool` and, once the
+   * tool has said `hello`, sends `requests` through the port it hands over.
+   * @param toolUrl - The tool's address, `?embed=1` included.
+   * @param requests - What to send on the port, in order.
+   * @returns The address to open.
+   */
+  pageUrl: (toolUrl: string, requests: readonly unknown[]) => string;
+  /** Stop serving. */
+  close: () => Promise<void>;
+}
+
+/** What the host page recorded, read with {@link readStandInHostLog}. */
+export interface StandInHostLog {
+  /** The tool's `hello`, or `null` before it came. */
+  hello: HelloMessage | null;
+  /** Every message the tool sent on the port, in order. */
+  results: unknown[];
+}
+
+/**
+ * Serve the host page on a free port of `127.0.0.1`.
+ * @returns The host; close it when the tests are done.
+ */
+export async function startStandInHost(): Promise<StandInHost> {
+  const server: Server = createServer((_request, response) => {
+    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+    response.end(HOST_PAGE);
+  });
+  await new Promise<void>((resolve) => {
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const { port } = server.address() as AddressInfo;
+  const origin = `http://127.0.0.1:${port}`;
+
+  return {
+    origin,
+    pageUrl: (toolUrl, requests) => {
+      const setup = encodeURIComponent(JSON.stringify({ toolUrl, requests }));
+      return `${origin}/?setup=${setup}`;
+    },
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      }),
+  };
+}
+
+/**
+ * Read what the host page recorded. Runs in the page: hand it to Playwright's
+ * `page.evaluate`, as `page.evaluate(readStandInHostLog)`.
+ * @returns The log.
+ */
+export function readStandInHostLog(): StandInHostLog {
+  return (globalThis as unknown as { hostLog: StandInHostLog }).hostLog;
+}
+
+/**
+ * The page. Its setup is its own `?setup=`, so one page serves every test, and
+ * it listens before it frames, so the tool's `hello` cannot be missed.
+ */
+const HOST_PAGE = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Stand-in host</title></head>
+<body>
+<iframe id="tool" title="The framed tool" style="width: 1280px; height: 800px"></iframe>
+<script>
+const { toolUrl, requests } = JSON.parse(new URLSearchParams(location.search).get('setup'));
+const toolOrigin = new URL(toolUrl).origin;
+const frame = document.querySelector('#tool');
+globalThis.hostLog = { hello: null, results: [] };
+globalThis.addEventListener('message', (event) => {
+  if (event.source !== frame.contentWindow || event.origin !== toolOrigin) return;
+  if (event.data?.type !== 'cheminfo:hello') return;
+  globalThis.hostLog.hello = event.data;
+  const channel = new MessageChannel();
+  channel.port1.onmessage = (answer) => {
+    globalThis.hostLog.results.push(answer.data);
+  };
+  frame.contentWindow.postMessage(
+    { type: 'cheminfo:connect', version: 1, host: { name: 'Stand-in host' } },
+    toolOrigin,
+    [channel.port2],
+  );
+  for (const request of requests) channel.port1.postMessage(request);
+});
+frame.src = toolUrl;
+</script>
+</body>
+</html>`;

package/src/host/ui/index.ts

@@ -0,0 +1,2 @@
+export type { HostHandlers } from './useHostConnection.ts';
+export { useHostConnection } from './useHostConnection.ts';

package/src/host/ui/useHostConnection.ts

@@ -0,0 +1,85 @@
+/**
+ * Connect a tool to the page that frames it, when there is one.
+ *
+ * The protocol and its schemas are fetched only then, so a visitor on the site
+ * itself never downloads them.
+ */
+
+import { useEffect, useRef } from 'react';
+
+import type { LoadedInput } from '../core/connectHost.ts';
+import type { ToolInterface } from '../core/protocol.ts';
+
+/** What a tool does with what its host sends, and what it says about itself. */
+export interface HostHandlers {
+  /**
+   * Show the inputs of a new document. Throwing means they could not be read:
+   * the error's message goes back to the host, and nothing should have changed
+   * on screen.
+   */
+  load: (inputs: readonly LoadedInput[]) => void;
+  /**
+   * The build that is running — `BUILD_INFO` from `react-cheminfo/build-info`
+   * — so a host can record which version produced what it stores.
+   * @default null
+   */
+  build?: unknown;
+}
+
+/** Once per page: React may mount the caller twice, the host is greeted once. */
+let started = false;
+
+/**
+ * Introduce the tool to its parent frame, or to the window that opened it, and
+ * serve that host for the life of the page.
+ *
+ * Call it after the hook that applies the address: effects run in order, so
+ * the address has been applied by the time the host is greeted, and a host's
+ * structure replaces the one the frame's link named rather than the reverse.
+ * The latest `load` is always the one called, so it may close over state.
+ * @param tool - What the tool takes and gives.
+ * @param handlers - See {@link HostHandlers}.
+ */
+export function useHostConnection(
+  tool: ToolInterface,
+  handlers: HostHandlers,
+): void {
+  const latest = useRef(handlers);
+  useEffect(() => {
+    latest.current = handlers;
+  });
+
+  useEffect(() => {
+    if (started) return;
+    const host = hostWindow();
+    if (host === null) return;
+    started = true;
+    import('../core/connectHost.ts')
+      .then(({ connectHost }) => {
+        connectHost({
+          host,
+          listen: (listener) => {
+            globalThis.addEventListener('message', listener);
+            return () => {
+              globalThis.removeEventListener('message', listener);
+            };
+          },
+          tool,
+          origin: globalThis.location.origin,
+          build: latest.current.build ?? null,
+          load: (inputs) => {
+            latest.current.load(inputs);
+          },
+        });
+      })
+      .catch(() => {
+        started = false;
+      });
+  }, [tool]);
+}
+
+function hostWindow(): Window | null {
+  const { parent, opener } = globalThis.window;
+  if (parent !== globalThis.window) return parent;
+  return (opener as Window | null) ?? null;
+}

package/src/host-testing.ts

@@ -0,0 +1,18 @@
+/**
+ * A stand-in host for a tool's end-to-end tests, and the messages SciPeaks
+ * sends. Node only: it serves a page.
+ */
+
+export type {
+  StandInHost,
+  StandInHostLog,
+} from './host/testing/standInHost.ts';
+export {
+  readStandInHostLog,
+  startStandInHost,
+} from './host/testing/standInHost.ts';
+export {
+  SCIPEAKS_ETHYLBENZENE_LOAD,
+  SCIPEAKS_ETHYLBENZENE_MOLFILE,
+  SCIPEAKS_HOST_NAME,
+} from './host/testing/sciPeaks.ts';

package/src/host.ts

@@ -0,0 +1,11 @@
+/**
+ * The host protocol: a page that frames a tool — an electronic lab notebook, a
+ * course — hands it typed data, checked against pipeline.cheminfo.org's kinds.
+ *
+ * Its own door because the schemas are checked with ajv. `useHostConnection`
+ * fetches ajv and the connection only when the page is framed, so a site that
+ * calls it ships nothing extra to a visitor who opened it directly.
+ */
+
+export * from './host/core/index.ts';
+export * from './host/ui/index.ts';

package/src/language/ui/siteLanguageContext.ts

@@ -1,5 +1,6 @@
 import { createContext, use } from 'react';
 
+import { pageLocation } from '../../router/core/pageAddress.ts';
 import { readLanguageParam } from '../core/languageParam.ts';
 
 /** What a site declares the page is being read in. */
@@ -16,5 +17,5 @@ export const SiteLanguageContext = createContext<string | undefined>(undefined);
 export function useSiteLanguage(): string | undefined {
   const declared = use(SiteLanguageContext);
   if (declared !== undefined) return declared;
-  return readLanguageParam(globalThis.location?.search ?? '');
+  return readLanguageParam(pageLocation()?.search ?? '');
 }

package/src/locales/de.json

@@ -54,6 +54,8 @@
   "share.layout": "Darstellung",
   "share.embed": "In eine andere Seite einbetten",
   "share.embedHint": "Lässt Kopfzeile und Navigation der Website weg, damit die Seite in einer Seite von Ihnen sitzt.",
+  "share.protect": "Diesen Link schützen",
+  "share.protectHint": "Die Klasse kann weder lesen noch ändern, was der Link einstellt, und die Adresse der Seite bleibt fest. Die Seite wird eingebettet.",
   "share.on": "Ein",
   "share.off": "Aus",
   "share.showOnPage": "Auf der Seite zeigen",
@@ -76,6 +78,9 @@
   "share.copyIframe": "Iframe kopieren",
   "share.copyIframeHelpTitle": "Die Seite in Ihre einbauen",
   "share.copyIframeHelp": "Ein HTML-Schnipsel, das dort eingefügt wird, wo das HTML Ihrer Seite bearbeitet wird: das Werkzeug läuft dann darin.",
+  "seal.refusedTitle": "Dieser Link lässt sich nicht öffnen",
+  "seal.refusedBody": "Er wurde nach dem Erstellen verändert oder ist unvollständig, daher wurde nichts geöffnet. Bitten Sie erneut um den Link.",
+  "seal.openWithout": "Das Werkzeug ohne den Link öffnen",
   "cite.button": "Zitieren",
   "cite.copyReferenceAs": "Literaturangabe kopieren als",
   "cite.pleaseCiteBoth": "Bitte zitieren Sie beide Arbeiten",

package/src/locales/en.json

@@ -54,6 +54,8 @@
   "share.layout": "Layout",
   "share.embed": "Embed in another page",
   "share.embedHint": "Drops the site header and its navigation, so the page sits inside a page of your own.",
+  "share.protect": "Protect this link",
+  "share.protectHint": "The class can neither read nor change what the link sets up, and the page's address stays fixed. The page is embedded.",
   "share.on": "On",
   "share.off": "Off",
   "share.showOnPage": "Show on the page",
@@ -76,6 +78,9 @@
   "share.copyIframe": "Copy the iframe",
   "share.copyIframeHelpTitle": "Put the page inside yours",
   "share.copyIframeHelp": "A snippet of HTML to paste where your own page's HTML is edited: the tool then runs inside it.",
+  "seal.refusedTitle": "This link cannot be opened",
+  "seal.refusedBody": "It was changed after it was made, or it is incomplete, so nothing was opened. Ask for the link again.",
+  "seal.openWithout": "Open the tool without it",
   "cite.button": "Cite",
   "cite.copyReferenceAs": "Copy the reference as",
   "cite.pleaseCiteBoth": "Please cite both works",

package/src/locales/es.json

@@ -54,6 +54,8 @@
   "share.layout": "Disposición",
   "share.embed": "Incrustar en otra página",
   "share.embedHint": "Quita la cabecera del sitio y su navegación, para que la página quede dentro de una página suya.",
+  "share.protect": "Proteger este enlace",
+  "share.protectHint": "La clase no puede leer ni cambiar lo que configura el enlace, y la dirección de la página queda fija. La página se integra.",
   "share.on": "Sí",
   "share.off": "No",
   "share.showOnPage": "Mostrar en la página",
@@ -76,6 +78,9 @@
   "share.copyIframe": "Copiar el iframe",
   "share.copyIframeHelpTitle": "Poner la página dentro de la tuya",
   "share.copyIframeHelp": "Un fragmento de HTML para pegar donde se edita el HTML de tu página: la herramienta funciona dentro de él.",
+  "seal.refusedTitle": "Este enlace no se puede abrir",
+  "seal.refusedBody": "Se modificó después de crearse, o está incompleto, así que no se abrió nada. Pide el enlace de nuevo.",
+  "seal.openWithout": "Abrir la herramienta sin el enlace",
   "cite.button": "Citar",
   "cite.copyReferenceAs": "Copiar la referencia como",
   "cite.pleaseCiteBoth": "Por favor, cite ambos trabajos",

package/src/locales/fr.json

@@ -54,6 +54,8 @@
   "share.layout": "Disposition",
   "share.embed": "Intégrer dans une autre page",
   "share.embedHint": "Retire l'en-tête du site et sa navigation, pour que la page prenne place dans une page à vous.",
+  "share.protect": "Protéger ce lien",
+  "share.protectHint": "La classe ne peut ni lire ni modifier ce que le lien règle, et l'adresse de la page reste fixe. La page est intégrée.",
   "share.on": "Oui",
   "share.off": "Non",
   "share.showOnPage": "Afficher sur la page",
@@ -76,6 +78,9 @@
   "share.copyIframe": "Copier l'iframe",
   "share.copyIframeHelpTitle": "Mettre la page dans la vôtre",
   "share.copyIframeHelp": "Un extrait de HTML à coller là où le HTML de votre page s'édite : l'outil s'exécute alors à l'intérieur.",
+  "seal.refusedTitle": "Ce lien ne peut pas être ouvert",
+  "seal.refusedBody": "Il a été modifié après sa création, ou il est incomplet : rien n'a été ouvert. Demandez à nouveau le lien.",
+  "seal.openWithout": "Ouvrir l'outil sans ce lien",
   "cite.button": "Citer",
   "cite.copyReferenceAs": "Copier la référence en",
   "cite.pleaseCiteBoth": "Merci de citer les deux travaux",

package/src/locales/it.json

@@ -54,6 +54,8 @@
   "share.layout": "Disposizione",
   "share.embed": "Incorporare in un'altra pagina",
   "share.embedHint": "Toglie l'intestazione del sito e la sua navigazione, così la pagina sta dentro una pagina propria.",
+  "share.protect": "Proteggi questo link",
+  "share.protectHint": "La classe non può né leggere né modificare ciò che il link imposta, e l'indirizzo della pagina resta fisso. La pagina viene incorporata.",
   "share.on": "Sì",
   "share.off": "No",
   "share.showOnPage": "Mostra nella pagina",
@@ -76,6 +78,9 @@
   "share.copyIframe": "Copia l'iframe",
   "share.copyIframeHelpTitle": "Mettere la pagina dentro la tua",
   "share.copyIframeHelp": "Un frammento di HTML da incollare dove si modifica l'HTML della tua pagina: lo strumento funziona al suo interno.",
+  "seal.refusedTitle": "Questo link non può essere aperto",
+  "seal.refusedBody": "È stato modificato dopo la creazione, o è incompleto, quindi non si è aperto nulla. Chiedi di nuovo il link.",
+  "seal.openWithout": "Apri lo strumento senza il link",
   "cite.button": "Cita",
   "cite.copyReferenceAs": "Copia il riferimento come",
   "cite.pleaseCiteBoth": "Si prega di citare entrambi i lavori",

package/src/router/core/history.ts

@@ -2,13 +2,15 @@
  * The tab router bound to the browser: read the address on screen, write a new
  * one through the History API, and hear every move.
  *
- * The router itself stays pure. Everything here reads `globalThis.location` and
- * writes `globalThis.history`, and does nothing where neither exists, so a
- * prerender script can import a module that uses it.
+ * The router itself stays pure. Everything here reads and writes the address
+ * through `pageLocation` and `pageHistory` — the browser's, or the one a sealed
+ * link holds in memory — and does nothing where neither exists, so a prerender
+ * script can import a module that uses it.
  */
 
 import { EMBED_PARAM, HIDE_PARAM } from '../../share/core/config.ts';
 
+import { pageHistory, pageLocation } from './pageAddress.ts';
 import type { QueryEntry } from './query.ts';
 import { formatQueryEntries } from './query.ts';
 import type { TabRoute, TabRouteInput, TabRouter } from './tabRouter.ts';
@@ -34,7 +36,7 @@ export function readRoute<Tab extends string>(
   const address = currentAddress();
   const adopted = router.legacyAddress(address);
   if (adopted === null) return router.parse(address);
-  const history = browserHistory();
+  const history = pageHistory();
   history?.replaceState(history.state, '', adopted);
   globalThis.dispatchEvent?.(new Event(ROUTE_CHANGE_EVENT));
   return router.parse(adopted);
@@ -78,8 +80,8 @@ export function writeRoute<Tab extends string>(
 ): string {
   const current = currentAddress();
   const address = withKeptParams(router, route, current, options.keep ?? []);
-  const location = browserLocation();
-  const history = browserHistory();
+  const location = pageLocation();
+  const history = pageHistory();
   if (location === undefined || history === undefined) return address;
 
   const shown =
@@ -126,7 +128,7 @@ export function subscribeToRoute<Tab extends string>(
  * @returns It, or `/` where there is no browser.
  */
 export function currentAddress(): string {
-  const location = browserLocation();
+  const location = pageLocation();
   if (location === undefined) return '/';
   return `${location.pathname}${location.search}${location.hash}`;
 }
@@ -150,11 +152,3 @@ function withKeptParams<Tab extends string>(
   const separator = target.includes('?') ? '&' : '?';
   return `${target}${separator}${formatQueryEntries(kept)}`;
 }
-
-function browserLocation(): Location | undefined {
-  return globalThis.location;
-}
-
-function browserHistory(): History | undefined {
-  return globalThis.history;
-}