react-cheminfo 0.64.1 → 0.65.0

package/lib/worker/core/workerChannelTypes.d.ts

@@ -59,11 +59,55 @@ export interface WorkerChannelOptions<TRequest, TResponse, TProgress = never> {
     cooperativeCancel?: boolean;
     /**
      * The same job run on this thread, used instead of the worker where the page
-     * has no `Worker` at all — Node.js, a unit test. Only a channel built from a
-     * function that creates the worker falls back to it.
+     * has no `Worker` at all — Node.js, a unit test — or where creating one
+     * throws, as a browser refuses a page framed under an opaque origin a worker
+     * from its own server; every later job then runs here too. Only a channel
+     * built from a function that creates the worker falls back to it.
      * @default undefined — every job goes to the worker
      */
     runInProcess?: (request: TRequest, context: WorkerJobContext<TProgress>) => Promise<TResponse>;
+    /**
+     * Turn what went wrong into the error the requests reject with, so a page
+     * can say it in its own words — a translated message, an error class of its
+     * own. Answering `undefined` keeps the default error. Cancellations and
+     * timeouts are not failures: they keep their own error classes.
+     * @default undefined — the job's message, or `<name> failed: …`
+     */
+    failure?: (failure: WorkerFailure) => Error | undefined;
+    /**
+     * Post a job again, once, on a fresh worker when its worker failed before
+     * answering, rather than reporting the failure: a worker whose module graph
+     * was still loading when the channel replaced it dies without having run
+     * anything. A job posted with buffers to transfer is not posted twice. Only
+     * a channel built from a function that creates the worker can do it.
+     * @default false
+     */
+    retryAfterWorkerFailure?: boolean;
+}
+/** What went wrong, before it becomes the error a request rejects with. */
+export interface WorkerFailure {
+    /**
+     * `job`: the job failed — its worker answered with a failure, or its
+     * in-process run threw. `worker`: the worker itself failed outright; an
+     * empty `message` means it never ran at all, its module graph not loading.
+     * `start`: creating the worker threw, and no in-process run stood in.
+     */
+    kind: 'job' | 'worker' | 'start';
+    /** The channel's name, e.g. `conformers`. */
+    name: string;
+    /** What was said: the job's message, the error event's, or the thrown error's. */
+    message: string;
+    /**
+     * The `detail` a failed answer carried, as `serveWorkerRequests` was told to
+     * write it — the key of a translatable message, say.
+     * @default undefined
+     */
+    detail?: unknown;
+    /**
+     * What the failure came with: the failed answer the worker posted, the error
+     * the in-process run threw, the error event, or what the factory threw.
+     */
+    cause: unknown;
 }
 /** What one call may ask of the channel. */
 export interface WorkerRequestOptions<TProgress = never> {

package/lib/worker/core/workerChannelTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workerChannelTypes.d.ts","sourceRoot":"","sources":["../../../src/worker/core/workerChannelTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB,CAAC,SAAS,GAAG,KAAK;IACjD;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,cAAc,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;CAC/C;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK;IAC1E;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,KACjC,OAAO,CAAC,SAAS,CAAC,CAAC;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB,CAAC,SAAS,GAAG,KAAK;IACrD;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK;IACnE;;;;;OAKG;IACH,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,KACtC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB"}
+{"version":3,"file":"workerChannelTypes.d.ts","sourceRoot":"","sources":["../../../src/worker/core/workerChannelTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB,CAAC,SAAS,GAAG,KAAK;IACjD;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,cAAc,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;CAC/C;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK;IAC1E;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,KACjC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,GAAG,SAAS,CAAC;IACxD;;;;;;;OAOG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACjC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB,CAAC,SAAS,GAAG,KAAK;IACrD;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK;IACnE;;;;;OAKG;IACH,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,KACtC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB"}

package/lib/worker/core/workerSlot.d.ts

@@ -0,0 +1,66 @@
+import type { WorkerLike } from './messages.ts';
+import type { Outcome } from './workerChannelParts.ts';
+import type { WorkerFailure, WorkerJobContext, WorkerSource } from './workerChannelTypes.ts';
+/**
+ * The one worker a channel posts to, kept, replaced and listened to.
+ *
+ * Handed a worker, the slot holds it until it is terminated. Handed a function,
+ * it creates the worker on first use and again after one failed or was let go,
+ * and runs the jobs on this thread instead — where there is no `Worker`, or
+ * where creating one throws — when the channel was given an in-process run.
+ * What a worker posts is heard only while it is the slot's current one, so a
+ * worker already let go cannot settle a job it no longer runs.
+ * @param source - The worker, or the function that creates it.
+ * @param options - What the slot reports to, and how failures are worded.
+ * @returns The slot.
+ */
+export declare function createWorkerSlot<TRequest, TResponse, TProgress>(source: WorkerSource, options: WorkerSlotOptions<TRequest, TResponse, TProgress>): WorkerSlot<TRequest, TResponse, TProgress>;
+/** What a slot is told about its channel. */
+export interface WorkerSlotOptions<TRequest, TResponse, TProgress> {
+    /** The channel's name, for its errors. */
+    name: string;
+    /**
+     * The job run on this thread instead of a worker.
+     * @default undefined — every job goes to the worker
+     */
+    runInProcess?: (request: TRequest, context: WorkerJobContext<TProgress>) => Promise<TResponse>;
+    /**
+     * The channel's own wording of a failure.
+     * @default undefined — the default errors
+     */
+    failure?: (failure: WorkerFailure) => Error | undefined;
+    /** Whether somebody still waits for a request. */
+    isWaited: (id: number) => boolean;
+    /** Where what the current worker posts goes. */
+    report: {
+        /** News about a running job. */
+        progress: (id: number, progress: unknown) => void;
+        /** The end of a job. */
+        answer: (id: number, outcome: Outcome<TResponse>) => void;
+        /** The worker failed outright, and a factory's was let go. */
+        failure: (error: Error) => void;
+    };
+}
+/** The worker of a channel; see {@link createWorkerSlot}. */
+export interface WorkerSlot<TRequest, TResponse, TProgress> {
+    /** Whether the slot creates its workers, and can therefore replace one. */
+    readonly hasFactory: boolean;
+    /** The worker posted to now, if there is one. */
+    readonly current: WorkerLike | null;
+    /**
+     * The worker a job goes to, created if need be.
+     * @returns It, or `null` when the job runs on this thread instead.
+     * @throws {CancelledRequestError} When a worker handed over was terminated.
+     * @throws {Error} What creating the worker threw, worded by the channel.
+     */
+    acquire: () => WorkerLike | null;
+    /** Run a job on this thread, as the channel's in-process run. */
+    runLocally: (payload: TRequest, context: WorkerJobContext<TProgress>) => Promise<TResponse>;
+    /** The error an in-process run that failed rejects with. */
+    jobFailed: (error: Error) => Error;
+    /** End a factory's worker, so the next job starts on a fresh one. */
+    abandon: () => void;
+    /** End the worker, whatever made it. */
+    terminate: () => void;
+}
+//# sourceMappingURL=workerSlot.d.ts.map

package/lib/worker/core/workerSlot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerSlot.d.ts","sourceRoot":"","sources":["../../../src/worker/core/workerSlot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAyB,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAKvD,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAC7D,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,iBAAiB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,GACzD,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CA6F5C;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS;IAC/D,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,KACjC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,GAAG,SAAS,CAAC;IACxD,kDAAkD;IAClD,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,gDAAgD;IAChD,MAAM,EAAE;QACN,gCAAgC;QAChC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;QAClD,wBAAwB;QACxB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;QAC1D,8DAA8D;QAC9D,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;KACjC,CAAC;CACH;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;IACjC,iEAAiE;IACjE,UAAU,EAAE,CACV,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,KACjC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,4DAA4D;IAC5D,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC;IACnC,qEAAqE;IACrE,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,wCAAwC;IACxC,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB"}

package/lib/worker/core/workerSlot.js

@@ -0,0 +1,107 @@
+import { errorMessage } from "../../error/core/toError.js";
+import { CancelledRequestError } from "./errors.js";
+import { defaultFailureError, subscribeToWorker, } from "./workerChannelParts.js";
+/**
+ * The one worker a channel posts to, kept, replaced and listened to.
+ *
+ * Handed a worker, the slot holds it until it is terminated. Handed a function,
+ * it creates the worker on first use and again after one failed or was let go,
+ * and runs the jobs on this thread instead — where there is no `Worker`, or
+ * where creating one throws — when the channel was given an in-process run.
+ * What a worker posts is heard only while it is the slot's current one, so a
+ * worker already let go cannot settle a job it no longer runs.
+ * @param source - The worker, or the function that creates it.
+ * @param options - What the slot reports to, and how failures are worded.
+ * @returns The slot.
+ */
+export function createWorkerSlot(source, options) {
+    const { name, runInProcess, failure, isWaited, report } = options;
+    const factory = typeof source === 'function' ? source : undefined;
+    let worker = null;
+    let local = factory !== undefined && !('Worker' in globalThis)
+        ? runInProcess
+        : undefined;
+    if (typeof source !== 'function') {
+        worker = source;
+        listen(source);
+    }
+    function fail(described) {
+        return failure?.(described) ?? defaultFailureError(described);
+    }
+    function acquire() {
+        if (local !== undefined)
+            return null;
+        if (worker !== null)
+            return worker;
+        if (factory === undefined) {
+            throw new CancelledRequestError(`${name} was terminated`);
+        }
+        try {
+            worker = factory();
+        }
+        catch (error) {
+            if (runInProcess === undefined) {
+                const message = errorMessage(error);
+                throw fail({ kind: 'start', name, message, cause: error });
+            }
+            local = runInProcess;
+            return null;
+        }
+        listen(worker);
+        return worker;
+    }
+    function outcomeOf(id, message) {
+        if (message.ok) {
+            return { ok: true, response: message.response };
+        }
+        if (!isWaited(id))
+            return { ok: false, error: new Error(message.message) };
+        const { detail } = message;
+        const described = { kind: 'job', name, message: message.message };
+        return { ok: false, error: fail({ ...described, detail, cause: message }) };
+    }
+    function listen(target) {
+        subscribeToWorker(target, {
+            progress: (id, progress) => {
+                if (target === worker)
+                    report.progress(id, progress);
+            },
+            answer: (id, message) => {
+                if (target === worker)
+                    report.answer(id, outcomeOf(id, message));
+            },
+            failure: (detail, event) => {
+                if (target !== worker)
+                    return;
+                if (factory !== undefined) {
+                    target.terminate();
+                    worker = null;
+                }
+                report.failure(fail({ kind: 'worker', name, message: detail, cause: event }));
+            },
+        });
+    }
+    return {
+        hasFactory: factory !== undefined,
+        get current() {
+            return worker;
+        },
+        acquire,
+        runLocally: (payload, context) => local === undefined
+            ? Promise.reject(new Error(`${name} has no in-process run`))
+            : local(payload, context),
+        jobFailed: (error) => fail({ kind: 'job', name, message: error.message, cause: error }),
+        abandon: () => {
+            if (factory === undefined || worker === null)
+                return;
+            worker.terminate();
+            worker = null;
+        },
+        terminate: () => {
+            worker?.terminate();
+            if (factory !== undefined)
+                worker = null;
+        },
+    };
+}
+//# sourceMappingURL=workerSlot.js.map

package/lib/worker/core/workerSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerSlot.js","sourceRoot":"","sources":["../../../src/worker/core/workerSlot.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.64.1",
+  "version": "0.65.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",
@@ -16,8 +16,10 @@
   ],
   "exports": {
     "./build-info": "./lib/build-info.js",
+    "./card": "./lib/card.js",
     "./conformers": "./lib/conformers.js",
     "./core": "./lib/core.js",
+    "./formula": "./lib/formula.js",
     "./host": "./lib/host.js",
     "./host-testing": "./lib/host-testing.js",
     "./ir": "./lib/ir.js",
@@ -76,9 +78,12 @@
     "intl-messageformat": "^11.2.15",
     "ir-spectrum": "^4.2.0",
     "leven": "^4.1.0",
+    "mf-parser": "^3.9.3",
     "ml-spectra-processing": "^14.35.1",
+    "ml-xsadd": "^3.0.1",
     "openchemlib": "^9.25.0",
     "react-markdown": "^10.1.0",
+    "react-mf": "^3.1.1",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
     "semver": "^7.8.5",
@@ -87,6 +92,7 @@
   "devDependencies": {
     "@blueprintjs/core": "^6.18.0",
     "@fastify/static": "^10.1.6",
+    "@fastify/type-provider-typebox": "^6.3.0",
     "@playwright/test": "^1.62.1",
     "@storybook/addon-docs": "^10.5.8",
     "@storybook/react-vite": "^10.5.8",
@@ -98,6 +104,7 @@
     "@zakodium/tsconfig": "^1.0.5",
     "benchmark": "^2.1.4",
     "chemical-elements": "^2.3.2",
+    "cheminfo-mcp-server": "^0.6.2",
     "eslint": "^9.39.5",
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
@@ -123,6 +130,8 @@
   "peerDependencies": {
     "@blueprintjs/core": "^6.18.0",
     "@fastify/static": "^10.0.0",
+    "@fastify/type-provider-typebox": "^6.0.0",
+    "cheminfo-mcp-server": "^0.6.2",
     "fastify": "^5.0.0",
     "ml-pca": "^4.1.1",
     "ml-signal-processing": "^2.2.2",
@@ -147,6 +156,12 @@
     "@fastify/static": {
       "optional": true
     },
+    "@fastify/type-provider-typebox": {
+      "optional": true
+    },
+    "cheminfo-mcp-server": {
+      "optional": true
+    },
     "fastify": {
       "optional": true
     },

package/src/card/core/cardAddress.ts

@@ -0,0 +1,100 @@
+/**
+ * The card of an answer, as its address says it.
+ *
+ * A chat shows a tool's answer twice: inline, as a card drawing only what the
+ * question asked, and over the full screen, as the site's page. The card is
+ * that page with `card` in its query, always with `embed`, so the card and
+ * the page behind it read the same parameters and can never disagree about
+ * what was asked. `card` is read by its presence: `?card` and `?card=1` both
+ * ask for it.
+ *
+ * Pure string work: the page reads these addresses, and the tool server
+ * writes them, in Node.
+ */
+
+import { parseQueryEntries } from '../../router/core/query.ts';
+import { EMBED_PARAM, HIDE_PARAM } from '../../share/core/config.ts';
+
+/** The parameter asking for the answer's card instead of the page. */
+export const CARD_PARAM = 'card';
+
+/**
+ * Whether an address asks for a card.
+ * @param search - The query string, with or without its leading `?`.
+ * @returns True when it names `card`, with a value or bare.
+ */
+export function isCardAddress(search: string): boolean {
+  for (const [key] of parseQueryEntries(search)) {
+    if (key === CARD_PARAM) return true;
+  }
+  return false;
+}
+
+/**
+ * The address a card is at: `globalThis.location`, a `URL`, or any record of
+ * the three parts.
+ */
+export interface CardLocation {
+  /** Its origin, e.g. `https://equilibrium.cheminfo.org`. */
+  readonly origin: string;
+  /** Its path, the mount and a language prefix included. */
+  readonly pathname: string;
+  /** Its query string, with or without its `?`. */
+  readonly search: string;
+}
+
+/** How {@link sitePageUrl} tells the card's parameters from the page's. */
+export interface SitePageOptions {
+  /**
+   * The parameters only the site's card reads, beside `card` itself: what a
+   * card draws beyond the page, e.g. `['rows']`, `['scale', 'ph']`.
+   * @default []
+   */
+  cardParams?: readonly string[];
+  /**
+   * Read a `+` in a key as a plus rather than as a space, as
+   * `parseQueryEntries` does. A key carries no `+` on any site of the family,
+   * so this only matters to a site that writes its own addresses with
+   * `URLSearchParams`.
+   * @default true
+   */
+  literalPlus?: boolean;
+  /**
+   * A parameter the page at a given path does not read, though another page
+   * of the site does: a tutorial step reads no InChI, the converter does.
+   * @default undefined - nothing beyond `card`, `embed`, `hide` and
+   *   `cardParams` is left out
+   */
+  isCardOnly?: (key: string, pathname: string) => boolean;
+}
+
+/**
+ * The site's own page a card stands for, with its chrome: the card's address
+ * without `card`, `embed`, `hide` and what only the card reads. Every other
+ * parameter is kept exactly as it was written, so the `+` of a charged atom
+ * stays a plus and the commas of a list stay commas. This is the address an
+ * answer's `link` names, and the one the card's Details button opens.
+ * @param location - The card's address: `globalThis.location`, or
+ *   `new URL(href)` for an address held as text.
+ * @param options - What only the site's card reads.
+ * @returns The page's absolute address, without a fragment.
+ */
+export function sitePageUrl(
+  location: CardLocation,
+  options: SitePageOptions = {},
+): string {
+  const { cardParams = [], literalPlus = true, isCardOnly } = options;
+  const dropped = new Set([CARD_PARAM, EMBED_PARAM, HIDE_PARAM, ...cardParams]);
+  const kept: string[] = [];
+  const search = location.search.startsWith('?')
+    ? location.search.slice(1)
+    : location.search;
+  for (const part of search.split('&')) {
+    const [entry] = parseQueryEntries(part, { literalPlus });
+    if (entry === undefined || dropped.has(entry[0])) continue;
+    if (isCardOnly?.(entry[0], location.pathname)) continue;
+    kept.push(part);
+  }
+  const query = kept.join('&');
+  return `${location.origin}${location.pathname}${query === '' ? '' : `?${query}`}`;
+}

package/src/card/core/cardPageUrl.ts

@@ -0,0 +1,97 @@
+/**
+ * The two addresses a chat frames for one answer: the card, inline, and the
+ * page itself, over the full screen. Both are the site's page under `embed`,
+ * so neither carries the site's chrome; the card adds `card` and what only it
+ * reads.
+ */
+
+import type { QueryEntry } from '../../router/core/query.ts';
+import { formatQueryEntries } from '../../router/core/query.ts';
+import { EMBED_PARAM, HIDE_PARAM } from '../../share/core/config.ts';
+
+import { CARD_PARAM } from './cardAddress.ts';
+
+/** How {@link framedPageUrl} frames a page. */
+export interface FramedPageOptions {
+  /**
+   * The parts of the page left out, on the card and on the full page alike:
+   * keys of the site's `hide` vocabulary, written `hide=a,b`.
+   * @default []
+   */
+  hide?: readonly string[];
+}
+
+/** What {@link cardPageUrl} adds to the framed page. */
+export interface CardPageOptions extends FramedPageOptions {
+  /**
+   * What `card` carries, for a site whose page draws more than one card:
+   * wikidata's `card=infobox`.
+   * @default '1'
+   */
+  card?: string;
+  /**
+   * What only the card reads, written after `card` in the order given, e.g.
+   * `{ rows: '10' }`. A value left `undefined` or empty is not written.
+   * @default {}
+   */
+  extra?: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * The page under `embed=1`, and `hide` when parts are left out: what a chat
+ * shows over the full screen when the reader asks for more than the card.
+ * @param page - The site's page as people open it, with its own query and
+ *   without `embed`, `hide` or `card`; absolute, or a path.
+ * @param options - The parts left out.
+ * @returns The framed page's address.
+ */
+export function framedPageUrl(
+  page: string,
+  options: FramedPageOptions = {},
+): string {
+  const { hide = [] } = options;
+  const entries: QueryEntry[] = [[EMBED_PARAM, '1']];
+  if (hide.length > 0) entries.push([HIDE_PARAM, hide.join(',')]);
+  return withQueryEntries(page, entries);
+}
+
+/**
+ * The card of an answer: the framed page with `card`, and what only the card
+ * reads after it.
+ * @param page - The site's page as people open it, with its own query and
+ *   without `embed`, `hide` or `card`; absolute, or a path.
+ * @param options - The parts left out, and what the card draws.
+ * @returns The card's address.
+ */
+export function cardPageUrl(
+  page: string,
+  options: CardPageOptions = {},
+): string {
+  const { card = '1', extra = {} } = options;
+  const entries: QueryEntry[] = [[CARD_PARAM, card]];
+  for (const [key, value] of Object.entries(extra)) {
+    if (value !== undefined && value !== '') entries.push([key, value]);
+  }
+  return withQueryEntries(framedPageUrl(page, options), entries);
+}
+
+/**
+ * Append parameters to an address, before its fragment.
+ * @param address - The address, with or without a query.
+ * @param entries - The parameters, in the order they are written.
+ * @returns The address carrying them.
+ */
+function withQueryEntries(
+  address: string,
+  entries: readonly QueryEntry[],
+): string {
+  const hashIndex = address.indexOf('#');
+  const head = hashIndex === -1 ? address : address.slice(0, hashIndex);
+  const fragment = hashIndex === -1 ? '' : address.slice(hashIndex);
+  const separator = head.includes('?')
+    ? head.endsWith('?') || head.endsWith('&')
+      ? ''
+      : '&'
+    : '?';
+  return `${head}${separator}${formatQueryEntries(entries)}${fragment}`;
+}

package/src/card/core/index.ts

@@ -0,0 +1,6 @@
+export type { CardLocation, SitePageOptions } from './cardAddress.ts';
+export { CARD_PARAM, isCardAddress, sitePageUrl } from './cardAddress.ts';
+export type { CardPageOptions, FramedPageOptions } from './cardPageUrl.ts';
+export { cardPageUrl, framedPageUrl } from './cardPageUrl.ts';
+export type { OpenPanel } from './panelRoom.ts';
+export { roomForPanels } from './panelRoom.ts';

package/src/card/core/panelRoom.ts

@@ -0,0 +1,66 @@
+/**
+ * Room in the frame for a panel a card opens over itself.
+ *
+ * A chat sizes the frame of a card from the card's own height, and a popover
+ * or a dialog opened from the card — the panel that copies or saves a figure,
+ * the notations of a structure — is drawn over the card inside that frame.
+ * Taller than the card, it would be cut off at the frame's edge, its Copy
+ * button with it. So while one is open the card is made as tall as the panel
+ * needs, which grows the frame with it.
+ */
+
+/** What one open panel needs of the frame. */
+export interface OpenPanel {
+  /**
+   * `dialog`: centred in the frame; `popover`: hung beside or under the
+   * control that opened it.
+   */
+  kind: 'dialog' | 'popover';
+  /**
+   * Its height with nothing scrolled away, in pixels: a dialog's body scrolls
+   * past 70 % of the frame, which is no height at all in a frame of 260. A
+   * dialog's margins are counted in.
+   */
+  height: number;
+  /**
+   * Where a popover ends as it is placed, in pixels from the top of the card:
+   * one opened at the pointer, or from a control outside the card, hangs lower
+   * than the control it is reckoned from.
+   * @default undefined - reckoned from the control alone
+   */
+  bottom?: number;
+}
+
+/**
+ * Between a popover and its control, arrow included, and under the popover:
+ * enough for one hung under its control, and a margin for one beside it.
+ */
+const POPOVER_SPACE = 24;
+
+/** Under a popover placed where it is, so that its shadow is not cut. */
+const POPOVER_GAP = 8;
+
+/**
+ * How tall the card must be for every open panel to fit in its frame.
+ * @param panels - The panels on screen.
+ * @param anchor - Where the lowest control whose popover is open ends, in
+ *   pixels from the top of the card; a popover hangs from it.
+ * @returns The least height of the card, or 0 when no panel is open.
+ */
+export function roomForPanels(
+  panels: readonly OpenPanel[],
+  anchor: number,
+): number {
+  let room = 0;
+  for (const panel of panels) {
+    let needed = panel.height;
+    if (panel.kind === 'popover') {
+      needed = anchor + panel.height + POPOVER_SPACE;
+      if (panel.bottom !== undefined && panel.bottom + POPOVER_GAP > needed) {
+        needed = panel.bottom + POPOVER_GAP;
+      }
+    }
+    if (needed > room) room = needed;
+  }
+  return Math.ceil(room);
+}