driftlet 0.1.0

package/src/kit.js

@@ -0,0 +1,76 @@
+// driftlet/kit: porcelain. Helpers that read and write plain device-definition data, so a
+// device can be set up from familiar quantities. Nothing here changes what a device means: each
+// helper returns an ordinary spec value (a dipole, a zeroCharge, …) that you can inspect.
+
+import { DeviceError } from './errors.js';
+import { FARADAY } from './constants.js';
+
+export { build, combine, layer, ohmic, bath } from './stack.js';
+export { parseEquation, stoichiometry, half, SHE, level } from './equation.js';
+export { traces, speciesRole, typeset } from './traces.js';
+export { live } from './live.js';
+export { describe, unitWarnings } from './describe.js';
+export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * One material seen from vacuum: a level inside it (the anchor) and how far above that level,
+ * in electron energy, the vacuum level just outside lies (the offset, V). So
+ * V_vac = V_anchor − offset.
+ * @typedef {object} VacuumSide
+ * @property {string} material material name in the definition
+ * @property {string} anchor a charged species present there (its standard level
+ *   V°_i = φ + μ°_i/(z_i F): a band edge for e⁻ or h⁺), or 'phi' (the inner potential itself)
+ * @property {number} offset V: an electron affinity, ionisation energy, Trasatti's 4.44 V, …
+ */
+
+/**
+ * A material's vacuum level relative to its own φ, V_vac − φ, in volts.
+ * @param {object} def device definition (its `species` and `materials` are read)
+ * @param {VacuumSide} side
+ * @param {string} [path] for error messages
+ */
+export function vacuumLevel(def, side, path = 'vacuum') {
+  if (!isObject(side)) fail(`${path} must be { material, anchor, offset }`);
+  const mat = def?.materials?.[side.material];
+  if (!isObject(mat)) fail(`${path}.material: unknown material ${JSON.stringify(side.material)}`);
+  if (mat.conductor !== undefined) fail(`${path}.material: '${side.material}' is a conductor, with no φ; use vacuumZeroCharge with its work function`);
+  if (!Number.isFinite(side.offset)) fail(`${path}.offset must be a finite number (V)`);
+  if (side.anchor === 'phi') return -side.offset;
+  const sp = (def.species ?? []).find((s) => s.name === side.anchor);
+  if (!sp) fail(`${path}.anchor must be 'phi' or a charged species, got ${JSON.stringify(side.anchor)}`);
+  if (!(sp.z !== 0)) fail(`${path}.anchor: '${side.anchor}' is neutral, so it has no level in volts`);
+  const entry = mat.species?.[side.anchor];
+  if (!isObject(entry)) fail(`${path}.anchor: '${side.anchor}' is absent from '${side.material}'`);
+  if (!Number.isFinite(entry.mu0)) fail(`${path}.anchor: '${side.anchor}' in '${side.material}' has no mu0`);
+  return entry.mu0 / (sp.z * FARADAY) - side.offset;
+}
+
+/**
+ * The vacuum-level (Anderson-type) estimate of a face's alignment: the two sides' vacuum levels
+ * are taken to coincide. Returns the face's `dipole`, φ_R − φ_L in volts.
+ * @param {object} def device definition
+ * @param {VacuumSide} left
+ * @param {VacuumSide} right
+ */
+export function vacuumDipole(def, left, right) {
+  return vacuumLevel(def, left, 'vacuumDipole: left') - vacuumLevel(def, right, 'vacuumDipole: right');
+}
+
+/**
+ * The vacuum-level (Schottky–Mott-type) estimate of a `zeroCharge` where a conductor meets a
+ * material: at a conductor region's face, or a contact's capacitive or dipole law. The conductor's
+ * vacuum level sits its work function W beyond its Fermi level, so
+ * zeroCharge = V_F − φ_edge at zero charge = W + (V_vac − φ)_inside.
+ * @param {object} def device definition
+ * @param {number} workFunction V
+ * @param {VacuumSide} inside the material across the face
+ */
+export function vacuumZeroCharge(def, workFunction, inside) {
+  if (!Number.isFinite(workFunction)) fail('vacuumZeroCharge: workFunction must be a finite number (V)');
+  return workFunction + vacuumLevel(def, inside, 'vacuumZeroCharge: inside');
+}

package/src/live.js

@@ -0,0 +1,217 @@
+// A live device for sliders, for driftlet/kit. Changes arrive faster than a device can solve
+// them, so they're merged while a solve runs and only the latest is solved next; each solve
+// starts warm from the last; a change that fails from there is ramped to from the last good
+// state, then tried from scratch; and if it still fails, the last good solution stays. Optionally the solving runs in a
+// Web Worker, keeping the page responsive.
+
+import { Device } from './index.js';
+import { merge } from './merge.js';
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !ArrayBuffer.isView(v);
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+// A point on the way from definition a to b (0 ≤ s ≤ 1): every finite number that differs is
+// interpolated, everything else is b's.
+export function between(a, b, s) {
+  if (typeof a === 'number' && typeof b === 'number' && Number.isFinite(a) && Number.isFinite(b)) return a + s * (b - a);
+  if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) return b.map((v, k) => between(a[k], v, s));
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const out = {};
+    for (const k of Object.keys(b)) out[k] = k in a ? between(a[k], b[k], s) : b[k];
+    return out;
+  }
+  return b;
+}
+
+/**
+ * What a live device does with each change, on whichever thread solves it: apply, solve warm,
+ * ramp from the last good state if that fails, and fall back to the last good solution.
+ */
+export class Session {
+  /** @param {object} def device definition */
+  constructor(def, { maxRamp = 32 } = {}) {
+    this.device = new Device(def);
+    this.maxRamp = maxRamp;
+    this.good = null; // { cp, sol }: the last converged state
+  }
+
+  /**
+   * Apply changes in order, then solve once. Each change is applied on its own, so an invalid
+   * one is refused (its message in `errors`) without losing the others.
+   * @param {object[]} patches each merged into the definition, as by Device.set()
+   * @returns {{ solution: object | null, errors: (string | undefined)[], info: { ms: number, ramp: number, failed: boolean, error?: string, warnings?: string[] } }}
+   */
+  update(patches) {
+    const t0 = now();
+    const errors = patches.map(() => undefined);
+    let ramp = 0;
+    const done = (sol, info) => ({ solution: sol, errors, info: { ms: now() - t0, ramp, ...info } });
+    patches.forEach((patch, k) => {
+      try {
+        this.device.set(patch); // a change that fails leaves the device as it was
+      } catch (e) {
+        errors[k] = e.message;
+      }
+    });
+    if (this.good && errors.every(Boolean)) return done(this.good.sol, { failed: true }); // nothing changed
+    const target = this.device.def;
+    try {
+      let sol = this.device.solve();
+      // Ramp from the last good state in more and more steps.
+      for (let n = 2; !sol.converged && this.good && n <= this.maxRamp; n *= 2) {
+        ramp = n;
+        this.device._rollback(this.good.cp);
+        const from = this.good.cp.def;
+        for (let k = 1; k <= n; k++) {
+          this.device.set(between(from, target, k / n));
+          sol = this.device.solve();
+          if (!sol.converged) break;
+        }
+      }
+      if (!sol.converged) {
+        // Last, from scratch (with the solver's own continuations).
+        const fresh = new Device(target);
+        const cold = fresh.solve();
+        if (cold.converged) {
+          this.device = fresh;
+          sol = cold;
+        }
+      }
+      if (sol.converged) {
+        this.good = { cp: this.device._checkpoint(), sol };
+        return done(sol, { failed: false });
+      }
+      if (this.good) this.device._rollback(this.good.cp);
+      return done(this.good?.sol ?? sol, { failed: true, warnings: sol.warnings });
+    } catch (e) {
+      // Something the definition's checks can't see, found while building or solving.
+      if (this.good) this.device._rollback(this.good.cp);
+      return done(this.good?.sol ?? null, { failed: true, error: e.message });
+    }
+  }
+}
+
+/**
+ * A live device.
+ * @typedef {object} Live
+ * @property {(patch: object) => Promise<{ solution: object | null, info: object }>} set merge a change
+ *   (as Device.set()) and solve it, after the solve under way; changes made meanwhile are merged
+ *   and solved once, and all their promises resolve with that solution
+ * @property {Promise<{ solution: object | null, info: object }>} ready the first solve
+ * @property {object | null} solution the last good solution
+ * @property {() => void} close stop the worker, if any
+ */
+
+/**
+ * A device for live demos: `live.set(patch)` as often as a slider moves, and draw what comes
+ * back (or in `onsolution`). Solves run one at a time, each warm from the last, letting the page
+ * paint in between; changes made during a solve are merged and solved together.
+ *
+ * On failure, the solution is the last good one, with `info.failed` (and `info.error` for an
+ * invalid change, `info.warnings` for one that didn't converge). `info.ramp` says how many steps
+ * a ramp from the last good state took (0: none needed), and `info.ms` the time.
+ *
+ * With `worker: true`, solving happens in a Web Worker (module workers are needed, as in every
+ * current browser). A function returning a Worker-like object can be given instead.
+ * @param {object} def device definition
+ * @param {{ worker?: boolean | (() => any), onsolution?: (solution: object, info: object) => void, maxRamp?: number }} [opts]
+ * @returns {Live}
+ */
+export function live(def, { worker = false, onsolution, maxRamp = 32 } = {}) {
+  const engine = worker ? workerEngine(def, worker, maxRamp) : localEngine(def, maxRamp);
+  let pending = [], busy = false;
+  const api = {
+    solution: null,
+    set(patch) {
+      const p = new Promise((resolve) => pending.push({ patch, resolve }));
+      if (!busy) pump();
+      return p;
+    },
+    close: () => engine.close(),
+  };
+  function pump() {
+    if (pending.length === 0) return;
+    busy = true;
+    const batch = pending;
+    pending = [];
+    engine
+      .run(batch.map((b) => b.patch))
+      .catch((e) => ({ solution: api.solution, errors: [], info: { ms: 0, ramp: 0, failed: true, error: String(e?.message ?? e) } }))
+      .then((res) => {
+        if (res.solution && !res.info.failed) api.solution = res.solution;
+        batch.forEach((b, k) => {
+          const own = res.errors?.[k];
+          b.resolve({ solution: res.solution, info: own ? { ...res.info, failed: true, error: own } : res.info });
+        });
+        busy = false;
+        pump();
+        if (onsolution && res.solution) {
+          try {
+            onsolution(res.solution, res.info);
+          } catch (e) {
+            // The page's own error: reported (as an uncaught error would be, in a browser) without
+            // stopping the device.
+            if (typeof globalThis.reportError === 'function') globalThis.reportError(e);
+            else console.error(e);
+          }
+        }
+      });
+  }
+  api.ready = api.set({});
+  return api;
+}
+
+// Solving on this thread, one macrotask per solve so the page can paint and take input.
+function localEngine(def, maxRamp) {
+  let session = null, error = null;
+  try {
+    session = new Session(def, { maxRamp });
+  } catch (e) {
+    error = e;
+  }
+  return {
+    run: (patches) =>
+      new Promise((resolve) =>
+        setTimeout(() => resolve(session ? session.update(patches) : { solution: null, errors: [], info: { ms: 0, ramp: 0, failed: true, error: error.message } }), 0),
+      ),
+    close() {},
+  };
+}
+
+// Solving in a worker running worker.js; replies come back in order.
+function workerEngine(def, worker, maxRamp) {
+  const w = typeof worker === 'function' ? worker() : startWorker();
+  const queue = [];
+  const failAll = (message) => {
+    while (queue.length) queue.shift()({ solution: null, errors: [], info: { ms: 0, ramp: 0, failed: true, error: message } });
+  };
+  w.onmessage = (e) => queue.shift()?.(e.data);
+  w.onerror = (e) => failAll(`the worker failed: ${e?.message ?? e}`);
+  w.postMessage({ type: 'init', def, maxRamp });
+  return {
+    run(patches) {
+      return new Promise((resolve) => {
+        queue.push(resolve);
+        try {
+          w.postMessage({ type: 'update', patches });
+        } catch (e) {
+          // A change that can't be posted (a function, such as custom statistics).
+          queue.pop();
+          resolve({ solution: null, errors: patches.map(() => `can't be sent to a worker: ${e.message}`), info: { ms: 0, ramp: 0, failed: true } });
+        }
+      });
+    },
+    close: () => w.terminate(),
+  };
+}
+
+function startWorker() {
+  const url = new URL('./worker.js', import.meta.url);
+  try {
+    return new Worker(url, { type: 'module' });
+  } catch {
+    // Cross-origin (the library loaded from a CDN): a same-origin stub that imports it.
+    const blob = new Blob([`import ${JSON.stringify(url.href)};`], { type: 'text/javascript' });
+    return new Worker(URL.createObjectURL(blob), { type: 'module' });
+  }
+}

package/src/merge.js

@@ -0,0 +1,11 @@
+// Deep merge of plain objects, as Device.set() applies a patch: plain objects merge key by key,
+// and arrays, typed arrays and every other value are replaced wholesale.
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !ArrayBuffer.isView(v);
+
+export function merge(base, patch) {
+  if (!isPlainObject(base) || !isPlainObject(patch)) return patch;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(patch)) out[k] = isPlainObject(v) && isPlainObject(base[k]) ? merge(base[k], v) : v;
+  return out;
+}

package/src/plot.js

@@ -0,0 +1,267 @@
+// driftlet/plot: a level diagram as an SVG string, with no dependencies and no DOM, so it
+// works the same in a page, a Web Worker or Node. Put it in a page with
+// `element.innerHTML = bandDiagram(sol)`. For your own plotting, `traces()` in driftlet/kit gives
+// the same lines as data.
+//
+// The theme (explained in docs/visualization.md): species voltages V_i are thick solid lines and standard levels
+// V°_i thin solid ones, in the species' colour; redox levels are thick dashed lines and their
+// standard levels thin dashed ones; φ is thin, dotted and grey. Electrons are steel blue, cations
+// (holes too) warm colours, anions cool ones, redox levels blue-violets; each colour follows its
+// species. A species drawn with a display offset carries a ⌇ mark. The colours are CSS custom
+// properties (--driftlet-electron, --driftlet-cation-1 …, --driftlet-anion-1 …,
+// --driftlet-redox-1 …, --driftlet-ink, …) with light and dark defaults of no specificity, so any
+// rule on the page restyles them.
+
+import { traces } from './traces.js';
+
+// Colours by role, light and dark (validated together for colour-vision deficiency; line weight,
+// dash and the legend carry identity too). A role with more members than colours cycles.
+export const THEME = Object.freeze({
+  light: { electron: ['#3a74b4'], cation: ['#d1362f', '#c8650f', '#b8417a', '#8a5a12'], anion: ['#11968a', '#0a9bbd', '#2e8b57'], redox: ['#5a4bc6', '#9a3fae', '#3f5fa8'] },
+  dark: { electron: ['#5b95d6'], cation: ['#e8584f', '#d0772a', '#d65d95', '#b88a3e'], anion: ['#219c8f', '#2aa5bb', '#3aa874'], redox: ['#8b7ff0', '#a86bc9', '#7a9ae0'] },
+});
+const ROLES = ['electron', 'cation', 'anion', 'redox'];
+
+/**
+ * The colour of a trace's role and slot (a CSS colour), for drawing other charts in the same
+ * colours as the level diagrams.
+ * @param {'electron' | 'cation' | 'anion' | 'redox'} role
+ * @param {number} slot
+ * @param {{ dark?: boolean }} [opts]
+ */
+export function themeColor(role, slot, { dark = false } = {}) {
+  const list = THEME[dark ? 'dark' : 'light'][role];
+  return list[slot % list.length];
+}
+
+// Line weight and dash by kind (thick: what carriers feel; thin: standard levels).
+const STROKE = {
+  level: { width: 2.8, dash: '' },
+  standard: { width: 1.3, dash: '' },
+  redox: { width: 2.8, dash: '8 5' },
+  'redox-standard': { width: 1.3, dash: '6 4' },
+  phi: { width: 1.3, dash: '1.5 3' },
+};
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/**
+ * A label split into plain and subscript runs. Labels mark subscripts TeX-style: `V_{e⁻}`, or
+ * `C_ox` for a run of letters, digits and charge signs. Everything else is literal.
+ * @param {string} label
+ * @returns {{ text: string, sub: boolean }[]}
+ */
+export function labelParts(label) {
+  const out = [];
+  const re = /_(?:\{([^}]*)\}|([\p{L}\p{N}⁺⁻]+))/gu;
+  let at = 0;
+  for (const m of String(label).matchAll(re)) {
+    if (m.index > at) out.push({ text: label.slice(at, m.index), sub: false });
+    out.push({ text: m[1] ?? m[2], sub: true });
+    at = m.index + m[0].length;
+  }
+  if (at < label.length) out.push({ text: label.slice(at), sub: false });
+  return out;
+}
+// The label as plain text (for titles and accessible names): braces dropped, `_` kept.
+const plain = (label) => labelParts(label).map((p) => (p.sub ? `_${p.text}` : p.text)).join('');
+// The label as SVG text content, subscripts lowered and shrunk (`dy`, which every browser
+// supports, rather than baseline-shift).
+const rich = (label, font) => {
+  const dy = Math.round(0.3 * font * 10) / 10;
+  let low = false;
+  return labelParts(label)
+    .map((p) => {
+      const shift = p.sub === low ? '' : ` dy="${p.sub ? dy : -dy}"`;
+      low = p.sub;
+      return p.sub ? `<tspan${shift} font-size="${0.75 * font}">${esc(p.text)}</tspan>` : shift ? `<tspan${shift}>${esc(p.text)}</tspan>` : esc(p.text);
+    })
+    .join('');
+};
+// Its width in characters, for layout.
+const span = (label) => labelParts(label).reduce((n, p) => n + (p.sub ? 0.75 : 1) * [...p.text].length, 0);
+
+function ticks(a, b, n) {
+  const step0 = (b - a) / n;
+  const mag = 10 ** Math.floor(Math.log10(step0));
+  const step = [1, 2, 5, 10].map((m) => m * mag).find((s) => s >= step0) ?? 10 * mag;
+  const out = [];
+  for (let t = Math.ceil(a / step) * step; t <= b + 1e-9 * step; t += step) out.push(Math.abs(t) < 1e-9 * step ? 0 : t);
+  return out;
+}
+const fmt = (v) => String(+v.toPrecision(4));
+
+// The range of the lines within [xs, xe], padded.
+function fit(tr, xs, xe) {
+  let lo = Infinity, hi = -Infinity;
+  for (const s of tr.series) {
+    for (let g = 0; g < tr.x.length; g++) {
+      if (tr.x[g] < xs || tr.x[g] > xe || !Number.isFinite(s.y[g])) continue;
+      lo = Math.min(lo, s.y[g]);
+      hi = Math.max(hi, s.y[g]);
+    }
+  }
+  if (!(hi > lo)) return tr.range;
+  const pad = 0.06 * (hi - lo);
+  return [lo - pad, hi + pad];
+}
+
+// Length unit for the x axis, from the device's extent.
+function lengthUnit(L) {
+  if (L >= 1e-3) return { scale: 1e3, name: 'mm' };
+  if (L >= 1e-6) return { scale: 1e6, name: 'µm' };
+  return { scale: 1e9, name: 'nm' };
+}
+
+const style = (id) => {
+  const vars = (mode) => ROLES.flatMap((role) => THEME[mode][role].map((c, k) => `--driftlet-${role}${role === 'electron' ? '' : `-${k + 1}`}:${c};`)).join('');
+  const light = `${vars('light')}--driftlet-ink:#0b0b0b;--driftlet-muted:#52514e;--driftlet-grid:#e4e3df;--driftlet-band:#f1f0ec;--driftlet-face:#a8a7a1`;
+  const dark = `${vars('dark')}--driftlet-ink:#ffffff;--driftlet-muted:#c3c2b7;--driftlet-grid:#3a3a37;--driftlet-band:#262624;--driftlet-face:#6b6a64`;
+  return (
+    `<style>` +
+    `:where(#${id}){${light}}` +
+    `@media (prefers-color-scheme: dark){:where(:root:not([data-theme="light"]) #${id}){${dark}}}` +
+    `:where(:root[data-theme="dark"] #${id}){${dark}}` +
+    `</style>`
+  );
+};
+
+let counter = 0;
+// Ids unique on a page, even with two copies of this module loaded (a CDN one and a local one).
+const instance = Math.random().toString(36).slice(2, 8);
+
+/**
+ * Line chart of level-diagram traces as an SVG string.
+ * @param {ReturnType<typeof traces>} tr from `traces()`
+ * @param {{ width?: number, height?: number, ylabel?: string, range?: [number, number], xlim?: [number, number], title?: string, ytick?: (v: number) => string }} [opts]
+ *   `xlim` (m) zooms into part of the device; the range then fits what's shown. `ytick` writes
+ *   the y axis's tick labels, say as powers of ten for lines that are log₁₀ of something
+ * @returns {string}
+ */
+export function levelChart(tr, { width = 640, height = 360, ylabel = 'voltage (V)', range, xlim, title, ytick = fmt } = {}) {
+  const id = `driftlet-plot-${instance}-${++counter}`;
+  const { x, series, regions } = tr;
+  const xs = xlim ? xlim[0] : x[0], xe = xlim ? xlim[1] : x[x.length - 1];
+  const [y0, y1] = range ?? (xlim ? fit(tr, xs, xe) : tr.range);
+  const unit = lengthUnit(xe - xs);
+
+  // Legend entries, flowed into rows above the plot.
+  const font = 12, charW = 0.6 * font;
+  const rows = [[]];
+  let rowW = 0;
+  for (const s of series) {
+    const w = 28 + span(s.label) * charW + 14;
+    if (rowW + w > width - 16 && rows[rows.length - 1].length) {
+      rows.push([]);
+      rowW = 0;
+    }
+    rows[rows.length - 1].push({ s, x: 8 + rowW });
+    rowW += w;
+  }
+  const legendH = series.length > 1 ? rows.length * 18 + 8 : 0;
+  const pad = { l: 56, r: 14, t: legendH + (title ? 22 : 8) + 16, b: 40 };
+  const pw = width - pad.l - pad.r, ph = height - pad.t - pad.b;
+  const px = (v) => pad.l + ((v - xs) / (xe - xs)) * pw;
+  const py = (v) => pad.t + (1 - (v - y0) / (y1 - y0)) * ph;
+  const r2 = (v) => Math.round(v * 100) / 100;
+
+  const out = [];
+  out.push(
+    `<svg id="${id}" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" style="max-width:100%;height:auto" role="img" ` +
+      `aria-label="${esc(`${title ? `${plain(title)}: ` : ''}${series.map((s) => plain(s.label)).join(', ')} against x`)}" ` +
+      `font-family="system-ui, sans-serif" font-size="${font}">`,
+  );
+  out.push(style(id));
+  if (title) out.push(`<text x="8" y="16" fill="var(--driftlet-ink)" font-weight="600">${rich(title, font)}</text>`);
+
+  // Region bands (every other one shaded) with their materials, and the faces between them.
+  regions.forEach((r, k) => {
+    if (r.x1 <= xs || r.x0 >= xe) return;
+    const a = px(Math.max(r.x0, xs)), b = px(Math.min(r.x1, xe));
+    if (k % 2 === 1) out.push(`<rect x="${r2(a)}" y="${pad.t}" width="${r2(b - a)}" height="${ph}" fill="var(--driftlet-band)"/>`);
+    // A region's own name where it was given one (not the default 'region k'), with its material.
+    const label = r.name && !/^region \d+$/.test(r.name) && r.name !== r.material ? `${r.name} (${r.material})` : r.material;
+    const named = r.name && !/^region \d+$/.test(r.name) ? r.name : r.material;
+    const shown = [label, named, r.material].find((t) => b - a > t.length * charW + 4) ?? null;
+    if (shown) out.push(`<text x="${r2((a + b) / 2)}" y="${pad.t - 5}" text-anchor="middle" fill="var(--driftlet-muted)">${esc(shown)}</text>`);
+  });
+  // Grid and axes.
+  for (const t of ticks(y0, y1, 5)) {
+    out.push(`<line x1="${pad.l}" x2="${pad.l + pw}" y1="${r2(py(t))}" y2="${r2(py(t))}" stroke="var(--driftlet-grid)"/>`);
+    out.push(`<text x="${pad.l - 6}" y="${r2(py(t) + 4)}" text-anchor="end" fill="var(--driftlet-muted)">${esc(ytick(t))}</text>`);
+  }
+  for (const t of ticks(xs * unit.scale, xe * unit.scale, 6)) {
+    out.push(`<text x="${r2(px(t / unit.scale))}" y="${pad.t + ph + 16}" text-anchor="middle" fill="var(--driftlet-muted)">${fmt(t)}</text>`);
+  }
+  for (const f of tr.faces.filter((f) => f > xs && f < xe)) out.push(`<line x1="${r2(px(f))}" x2="${r2(px(f))}" y1="${pad.t}" y2="${pad.t + ph}" stroke="var(--driftlet-face)" stroke-dasharray="2 3"/>`);
+  out.push(`<text x="${r2(pad.l + pw / 2)}" y="${height - 8}" text-anchor="middle" fill="var(--driftlet-ink)">x (${unit.name})</text>`);
+  out.push(`<text transform="translate(14 ${r2(pad.t + ph / 2)}) rotate(-90)" text-anchor="middle" fill="var(--driftlet-ink)">${rich(ylabel, font)}</text>`);
+
+  // Lines, clipped to the plot, broken where undefined.
+  out.push(`<clipPath id="${id}-clip"><rect x="${pad.l}" y="${pad.t}" width="${pw}" height="${ph}"/></clipPath>`);
+  out.push(`<g clip-path="url(#${id}-clip)" fill="none" stroke-linejoin="round">`);
+  const colour = (s) => {
+    if (s.role === 'phi' || !s.role) return 'var(--driftlet-muted)';
+    if (s.role === 'electron') return 'var(--driftlet-electron)';
+    return `var(--driftlet-${s.role}-${(s.slot % THEME.light[s.role].length) + 1})`;
+  };
+  const stroke = (s) => {
+    const st = STROKE[s.kind] ?? STROKE.level;
+    return `stroke="${colour(s)}" stroke-width="${st.width}"${st.dash ? ` stroke-dasharray="${st.dash}"` : ''}`;
+  };
+  // Thin lines first, so the thick ones the carriers feel sit on top.
+  const order = [...series].sort((a, b) => (STROKE[a.kind]?.width ?? 2) - (STROKE[b.kind]?.width ?? 2));
+  const marks = [];
+  for (const s of order) {
+    let d = '', pen = false;
+    for (let g = 0; g < x.length; g++) {
+      const v = s.y[g];
+      if (!Number.isFinite(v)) {
+        pen = false;
+        continue;
+      }
+      d += `${pen ? 'L' : 'M'}${r2(px(x[g]))} ${r2(py(v))}`;
+      pen = true;
+    }
+    if (d) out.push(`<path d="${d}" ${stroke(s)}><title>${esc(plain(s.label))}</title></path>`);
+    // A species drawn with a display offset: a small zigzag across its V_i, near the left.
+    if (s.shift && s.kind === 'level') {
+      const g = [...x.keys()].find((k) => x[k] >= xs + 0.04 * (xe - xs) && Number.isFinite(s.y[k]) && s.y[k] >= y0 && s.y[k] <= y1);
+      if (g !== undefined) marks.push({ x: px(x[g]), y: py(s.y[g]), s });
+    }
+  }
+  for (const m of marks) {
+    const zz = `M${r2(m.x - 3)} ${r2(m.y - 9)}l6 4.5l-6 4.5l6 4.5l-6 4.5`;
+    out.push(`<path d="${zz}" stroke="var(--driftlet-ink)" stroke-width="1.6" fill="none"><title>${esc(plain(m.s.label))}</title></path>`);
+  }
+  out.push(`</g>`);
+  if (series.some((s) => s.shift)) {
+    out.push(`<text x="${pad.l + pw - 6}" y="${pad.t + ph - 6}" text-anchor="end" fill="var(--driftlet-muted)">⌇ = per-species offset</text>`);
+  }
+  out.push(`<rect x="${pad.l}" y="${pad.t}" width="${pw}" height="${ph}" fill="none" stroke="var(--driftlet-face)"/>`);
+
+  // Legend (two or more lines): a swatch in each line's colour and dash, its label in ink.
+  if (series.length > 1) {
+    rows.forEach((row, k) => {
+      const yy = (title ? 22 : 0) + 14 + k * 18;
+      for (const { s, x: xx } of row) {
+        out.push(`<line x1="${xx}" x2="${xx + 22}" y1="${yy - 4}" y2="${yy - 4}" ${stroke(s)}/>`);
+        out.push(`<text x="${xx + 28}" y="${yy}" fill="var(--driftlet-ink)">${rich(s.label, font)}</text>`);
+      }
+    });
+  }
+  out.push(`</svg>`);
+  return out.join('');
+}
+
+/**
+ * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
+ * standard level (thin), regions as bands. Options are those of `traces()` and `levelChart()`.
+ * @param {import('./types.js').Solution} sol
+ * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
+ * @returns {string}
+ */
+export function bandDiagram(sol, opts = {}) {
+  const { width, height, ylabel, range, xlim, title, ytick, ...pick } = opts;
+  return levelChart(traces(sol, pick), { width, height, ylabel, range, xlim, title, ytick });
+}