runtime.ts

/**
 * Pyodide loader for DataLab-Web.
 *
 * This module owns the single Pyodide instance and the Sigima Python
 * namespace.  All calls into Python go through a tiny typed wrapper so the
 * rest of the codebase never touches the Pyodide API directly.
 */

import bootstrapSource from "./bootstrap.py?raw";
import processorSource from "./processor.py?raw";
import dlwMainSource from "./dlw_main.py?raw";
import dlwPluginsSource from "./dlw_plugins.py?raw";
import dlwWheelsSource from "./dlw_wheels.py?raw";
import dlwApplicationsSource from "./dlw_applications.py?raw";
import dlwH5BrowserSource from "./dlw_h5browser.py?raw";
import dlwInteractiveFitSource from "./dlw_interactive_fit.py?raw";
import dlwMacroLintSource from "./dlw_macro_lint.py?raw";
import dlwProvenanceSource from "./dlw_provenance.py?raw";
import macroProxySource from "./macro_proxy.py?raw";
// Tiny module that installs Sigima's ``PlaceholderTitleFormatter`` as the
// default; pushed into every Pyodide instance (main runtime + workers)
// so processed objects carry the same placeholder titles (later resolved
// to source ``oid``s by ``bootstrap.patch_title_with_ids``).
import dlwTitleFormatSource from "./dlw_title_format.py?raw";
// Guidata 3.15 provides the JSON Schema exporter natively. This tracked
// compatibility patch only adds FloatArrayItem hints used by the browser
// array editor and may be dropped once a later guidata release ships them.
import guidataJsonSchemaShim from "./_guidata_jsonschema_shim.py?raw";
import {
  DATALAB_CAPSULE_INSTALL_SPEC,
  GUIDATA_INSTALL_SPEC,
  SIGIMA_INSTALL_SPEC,
} from "./dependencyConfig";
// Resolve the Pyodide ``LANG`` from the active UI locale so that
// Sigima/guidata gettext labels match the rest of the interface. Import
// from the React-free ``locale`` module to avoid pulling the provider in.
import { pyodideLang } from "../i18n/locale";
import { t } from "../i18n/translate";
import {
  readWasmHeapBytes,
  readJsMemory,
  type MemoryUsage,
  type PyodideModuleLike,
} from "../utils/memory";
import { OpfsObjectStore } from "../storage/opfsObjectStore";
import type { ObjectByteStore } from "../storage/opfsObjectStore";
import { isDiskStorageSupported } from "./storageCapabilities";
import { OpfsSyncObjectStore } from "../storage/opfsSyncObjectStore";
import {
  PluginWheelStore,
  type StoredPluginWheel,
  type UserPluginWheelRecord,
} from "../storage/pluginWheelStore";
import { hashBytes } from "../plugins/trustStore";
// Default set of packages whose installed versions are worth surfacing for
// diagnostics and the shim version audit (see ``shims/registry.ts``).
import { PACKAGE_VERSION_SOURCES } from "./shims/registry";
import { fetchBundledPluginWheels } from "./bundledPlugins";
import { currentRuntimeLabels, type RuntimeLabels } from "./runtimeLabels";
import {
  DISK_SWEEP_CALLS,
  MUTATES_HEAVY,
  MUTATING_PY_FUNCTIONS,
  pageInPlan,
  REFUSABLE,
  REPLACES_MODEL,
} from "./pyCallPolicy";
import {
  ScientificRefusalError,
  type ScientificRefusal,
} from "./workerProtocol";

// Re-export the structural runtime contract so consumers can keep their
// existing ``from "../runtime/runtime"`` import path while depending on
// the interface (``RuntimeApi``) instead of the concrete class — the
// decoupling that lets a worker-backed implementation be swapped in later.
export type { RuntimeApi } from "./RuntimeApi";

// Bundle the portable ``datalab.*`` shim package — every .py file under
// src/sigima/dlplugins/ is mirrored to Pyodide's site-packages at startup
// so plugins can ``from datalab.plugins import PluginBase`` unmodified.
const shimSources = import.meta.glob("./dlplugins/**/*.py", {
  query: "?raw",
  import: "default",
  eager: true,
}) as Record<string, string>;

const builtinPluginSources = import.meta.glob("./builtin_plugins/*.py", {
  query: "?raw",
  import: "default",
  eager: true,
}) as Record<string, string>;

// Pyodide is loaded from a CDN <script> tag in index.html; the
// ``window.loadPyodide`` global is declared in
// ``src/types/pyodide-global.d.ts`` (shared with the bench).

export interface PyodideAPI {
  runPythonAsync: (code: string) => Promise<unknown>;
  loadPackage: (names: string | string[]) => Promise<void>;
  globals: {
    get: (name: string) => PyProxy | undefined;
  };
  FS: {
    writeFile: (path: string, data: string | Uint8Array) => void;
    mkdirTree?: (path: string) => void;
    unlink?: (path: string) => void;
  };
  /** Emscripten module backing the WASM heap. Used by
   *  {@link DataLabRuntime.getMemoryUsage} to read the linear-heap size
   *  (``_module.HEAPU8.length``) for the memory indicator. */
  _module?: PyodideModuleLike;
  // Pyodide exposes more, but the MVP only needs the above.
}

export interface PyProxy {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (...args: any[]): unknown;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  callKwargs?: (...args: any[]) => unknown;
  toJs?: (opts?: {
    dict_converter?: (entries: Iterable<[unknown, unknown]>) => unknown;
  }) => unknown;
  destroy?: () => void;
}

const PYODIDE_VERSION = "v0.26.4";
const PYODIDE_INDEX = `https://cdn.jsdelivr.net/pyodide/${PYODIDE_VERSION}/full/`;

export interface PythonDistributionInfo {
  name: string;
  version: string;
}

/** JSON-safe snapshot of the live Python environment. */
export interface PythonEnvironmentInfo {
  pythonVersion: string;
  pythonImplementation: string;
  pythonPlatform: string;
  platform: string;
  machine: string;
  pyodideVersion: string | null;
  packages: PythonDistributionInfo[];
}

export interface PythonDistributionInfo {
  name: string;
  version: string;
}

/** JSON-safe snapshot of the live Python environment. */
export interface PythonEnvironmentInfo {
  pythonVersion: string;
  pythonImplementation: string;
  pythonPlatform: string;
  platform: string;
  machine: string;
  pyodideVersion: string | null;
  packages: PythonDistributionInfo[];
}

export interface SignalMeta {
  id: string;
  uuid: string | null;
  title: string;
  size: number;
  xlabel: string;
  ylabel: string;
  xunit: string;
  yunit: string;
}

/** Optional per-curve style read from PlotPy/Sigima metadata.  Honoured
 *  by :class:`SignalPlot` when overlaying multiple signals; falls back
 *  to the auto-cycling palette when fields are absent. */
export interface SignalStyle {
  color: string | null;
  /** PlotPy linestyle name (``SolidLine``, ``DashLine`` …) or Plotly
   *  ``line.dash`` value — :func:`plotlyDash` normalises both. */
  linestyle: string | null;
  linewidth: number | null;
  /** PlotPy curve display mode (``Lines``, ``Sticks``, ``Steps``,
   *  ``Dots``, ``NoCurve``) — :func:`normalizeCurveStyle` normalises. */
  curvestyle: string | null;
}

export interface SignalData extends SignalMeta {
  /** X / Y samples.  The front-end requests the ``bytes`` encoding, so
   *  these are normally zero-copy ``Float64Array`` views over a single
   *  buffer shipped across the Pyodide bridge.  The legacy ``list``
   *  encoding (Python tests, notebook display) yields plain arrays. */
  x: Float64Array | number[];
  y: Float64Array | number[];
  style?: SignalStyle;
}

/** Bounded head/tail sample used by the Properties panel. */
export interface SignalDataPreview {
  size: number;
  indices: number[];
  x: number[];
  y: number[];
}

export interface ProcessingDescriptor {
  id: string;
  label: string;
  has_params: boolean;
}

/** One input of the processing that produced an object, in call order. */
export interface ProcessingInput {
  /** Input role: ``source``, ``operand`` or ``sources`` (aggregation). */
  role: string;
  /** Object id, or the persistent UUID of a deleted input. */
  id: string;
  /** Current title of the input, or ``null`` when it was deleted. */
  title: string | null;
}

/** Snapshot returned by ``get_last_processing(oid)``: identifies the
 *  feature that produced *oid* and exposes its (optional) parameter
 *  schema with the values used in the latest invocation. */
export interface LastProcessingInfo {
  feature_id: string;
  label: string;
  menu_path: string;
  /** Feature pattern (``1_to_1``, ``2_to_1`` or ``n_to_1``). */
  pattern?: string;
  source_ids: string[];
  operand_id: string | null;
  /** Every input in call order, repetitions included. */
  inputs?: ProcessingInput[];
  missing_source_ids: string[];
  missing_operand_id: string | null;
  /** Why the processing cannot be applied again here, if so. */
  unavailable_reason?: string | null;
  has_params: boolean;
  schema: SchemaWithValues["schema"] | null;
  values: Record<string, unknown> | null;
}

/** Workspace provenance ledger (DataLab-Capsule ``ledger-1`` document). */
export interface ProvenanceLedger {
  schema: string;
  schema_version: number;
  workspace_id: string;
  environments: Record<string, Record<string, unknown>>;
  states: Record<string, Record<string, unknown>>;
  activities: Record<string, unknown>[];
}

/** Snapshot returned by ``get_provenance_ledger()``.  ``available`` is
 *  false (and ``ledger`` null) when DataLab-Capsule is not installed. */
export interface ProvenanceLedgerInfo {
  available: boolean;
  reason: string | null;
  ledger: ProvenanceLedger | null;
  state_status: Record<string, string>;
  /** Per activity recording analysis results: whether each result is still
   *  the one it produced (``available``), was overwritten by a later result
   *  (``replaced``) or is gone (``missing``). */
  artifact_status: Record<
    string,
    {
      object_uuid: string;
      key: string;
      status: "available" | "replaced" | "missing";
    }[]
  >;
  /** Activities imported from processing records of a workspace saved
   *  without provenance (never replayed), with the issues found at import. */
  legacy: {
    activities: number;
    issues: Record<string, number>;
    items: {
      activity_id: string;
      object_uuid: string;
      key: string;
      operation: string | null;
      pattern: string | null;
      inputs: string[];
      issues: string[];
    }[];
  } | null;
  capture_failures: number;
  notices: string[];
  /** ``"loaded"`` or ``"absent"`` after opening a workspace file, else null. */
  file_status: "loaded" | "absent" | null;
  /** Capsule the workspace was opened from (the parent of a revision
   *  exported later), else null. */
  capsule_origin: {
    fingerprint: string;
    name: string;
    /** Attachment names of that capsule: a child revision does not copy
     *  them. */
    attachments?: string[];
  } | null;
}

/** Light file attached to a capsule export (declared in the manifest,
 *  never executed). */
export interface CapsuleAttachmentInput {
  name: string;
  data: Uint8Array;
  /** Media type, e.g. ``text/plain``. */
  media_type: string;
  description?: string | null;
}

/** Options of a capsule export. */
export interface CapsuleExportOptions {
  description?: string | null;
  /** Manifest fingerprint of the parent revision. */
  revisionOf?: string | null;
  /** Light files selected by the user.  Their bytes are moved to the
   *  runtime (detached in worker mode). */
  attachments?: CapsuleAttachmentInput[];
}

/** One input or output of an activity, in a capsule summary. */
export interface CapsuleBinding {
  role: string;
  position: number;
  /** State or artifact entity (``#state-<id>``), or null. */
  target: string | null;
  /** Object bound by a legacy activity (state unknown). */
  object_uuid?: string;
  /** Digest of an analysis result. */
  result_digest?: string | null;
}

/** Summary of a capsule manifest (``inspect_manifest``). */
export interface CapsuleSummary {
  name: string;
  description: string;
  license: string;
  date_published: string;
  profiles: string[];
  fingerprint: string;
  revision_of: string | null;
  workspace: {
    id: string;
    referenced: boolean;
    sha256: string;
    size: string;
  };
  /** Attachments declared in the manifest (size in bytes as a string,
   *  SHA-256 without prefix). */
  attachments: {
    name: string;
    media_type: string;
    size: string;
    sha256: string;
    description: string | null;
  }[];
  activities: {
    id: string;
    type: string;
    name: string;
    replayable: boolean;
    instrument: string[];
    origin: string;
    inputs: CapsuleBinding[];
    outputs: CapsuleBinding[];
    parameters: Record<string, unknown>;
    limits: string[];
    x_alignment: Record<string, unknown> | null;
    legacy: Record<string, unknown> | null;
    observed_state: string | null;
  }[];
  states: {
    id: string;
    kind: string;
    object_uuid: string;
    fingerprint: string | null;
    locator: string | null;
    roi: unknown;
    produced_by: string | null;
    consumed_by: string[];
  }[];
  fan_out: string[];
}

/** Status of one supplied report or review. */
export interface CapsuleDocumentStatus {
  /** ``"valid"``, or the problem found. */
  status: string;
  activity_id?: string | null;
  verdict?: string | null;
  fingerprint?: string | null;
}

/** Result of {@link DataLabRuntime.inspectWorkspaceCapsule}. */
export interface CapsuleInspection {
  summary: CapsuleSummary | null;
  /** The manifest itself (kept for comparison and reviews), or null. */
  manifest: Record<string, unknown> | null;
  /** Integrity of the capsule: computed from the files, never a replay. */
  integrity: {
    valid: boolean;
    fingerprint: string | null;
    /** ``verified``, ``integrity_only`` or ``not_available`` (referenced
     *  workspace not supplied). */
    workspace: string | null;
    states_located: number | null;
    states_altered: string[];
    problems: string[];
  };
  /** Checks of the supplied reports and reviews: their verdicts are what
   *  their authors claim, not recomputed.  Null when the capsule is invalid. */
  documents: {
    reports: CapsuleDocumentStatus[];
    reviews: CapsuleDocumentStatus[];
    unreadable: { kind: "report" | "review"; index: number; status: string }[];
  } | null;
}

/** One change between two capsule manifests. */
export interface CapsuleChange {
  change: "added" | "removed" | "changed";
  item: string;
  id: string;
  field?: string;
  old?: unknown;
  new?: unknown;
}

/** Result of {@link DataLabRuntime.diffCapsuleManifests}. */
export interface CapsuleDiff {
  old: string;
  new: string;
  revision_of_old: boolean;
  identical: boolean;
  /** ``none_detected``: the recorded activities and states agree but the
   *  workspace files or the attachment contents differ, so equality is not
   *  established. */
  scientific_conclusion: "differences" | "none" | "none_detected";
  scientific: CapsuleChange[];
  presentation: CapsuleChange[];
  /** Workspace file (SHA-256, size, included or referenced) and locators:
   *  different bytes do not show a scientific change. */
  storage: CapsuleChange[];
  environment: CapsuleChange[];
  /** Attachments added, removed or changed; their content is not
   *  interpreted (it may matter scientifically). */
  attachments: CapsuleChange[];
}

export type CapsuleReviewVerdict = "endorsed" | "disputed" | "comment";

/** Review of one capsule revision (DataLab-Capsule ``review-1`` document). */
export interface CapsuleReview {
  review: string;
  review_version: number;
  target: string;
  reviewer: { name: string; identifier: string | null };
  date: string;
  statement: string;
  verdict: CapsuleReviewVerdict | null;
  reports: { activity_id: string; verdict: string }[];
  review_fingerprint: string;
}

/** Comparison of one output of a replayed activity (``report-1`` ``outputs``). */
export interface ProvenanceOutputComparison {
  role: string;
  /** What the activity recorded: a state, an analysis result or no result. */
  recorded: "state" | "artifact" | "none";
  state_id?: string;
  artifact?: { object_uuid: string; key: string };
  status: string;
  verdict: string;
  rule: Record<string, unknown> | null;
  observed: Record<string, unknown> | null;
  detail?: string | null;
}

/** Verification report (DataLab-Capsule ``report-1`` document). Eligibility
 *  codes and verdicts are those of DataLab Desktop (shared recorder). */
export interface ProvenanceReport {
  report: string;
  report_version: number;
  activity_id: string;
  restoration: string;
  eligibility: string;
  reason?: string | null;
  context?: Record<string, unknown>;
  inputs: Record<string, unknown>[];
  reference: Record<string, unknown> | null;
  environment: Record<string, unknown>;
  verdict: string;
  rule: Record<string, unknown> | null;
  observed: Record<string, unknown> | null;
  outputs?: ProvenanceOutputComparison[];
  verification_activity: Record<string, unknown> | null;
}

/** Current name of an object named in a provenance description (added by
 *  the runtime: the ledger knows persistent UUIDs only). */
export interface ProvenanceObjectName {
  object_uuid: string;
  /** Current object id, or ``null`` when the object was deleted. */
  id: string | null;
  /** Current title, or ``null`` when the object was deleted. */
  title: string | null;
  /** Kind of the current object, or ``null`` when it was deleted. */
  object_kind?: "signal" | "image" | null;
}

/** One input of a recorded activity (``inspection`` projection). */
export interface ProvenanceInput extends ProvenanceObjectName {
  position: number;
  role: string;
  /** Recorded input state, or ``null`` for an old (legacy) record. */
  state_id: string | null;
  object_present: boolean;
  produced_by: string | null;
  /** True when the input can be expanded to its own production. */
  has_ancestors: boolean;
  cycle: boolean;
  /** ``unchecked`` until the data are checked, then ``available``,
   *  ``changed``, ``altered``, ``missing``, ``unavailable``... */
  data: string;
}

/** One recorded output of an activity: a state or an analysis result. */
export interface ProvenanceOutput extends ProvenanceObjectName {
  role: string;
  recorded: "state" | "artifact";
  state_id?: string;
  kind?: string;
  key?: string;
  object_present?: boolean;
  status: string;
}

/** Description of one recorded activity (``inspection`` projection). */
export interface ProvenanceActivity {
  activity_id: string;
  command_id: string | null;
  origin: string;
  edition: string | null;
  status: string | null;
  started_at: string | null;
  finished_at: string | null;
  operation: { id: string; contract_version: number } | null;
  opaque: boolean;
  implementation: Record<string, unknown> | null;
  parameters: Record<string, unknown> | null;
  input_count: number;
  inputs: ProvenanceInput[];
  outputs: ProvenanceOutput[];
  no_result: boolean;
  context: Record<string, unknown>;
  environment: Record<string, unknown> | null;
  limits: string[];
  support: { function: string; verification: string; reason: string | null };
  legacy: Record<string, unknown> | null;
  /** Analyses only: the analysed state. */
  analysed_state_id?: string | null;
}

/** Provenance of an object or of one of its recorded states. */
export interface ProvenanceDescription {
  available: boolean;
  reason?: string | null;
  inspection?: number;
  object?: ProvenanceObjectName & { present: boolean };
  state?: Record<string, unknown> | null;
  anchor?: { latest: boolean; content: string; file_status: string | null };
  production?: ProvenanceActivity | null;
  object_states?: {
    state_id: string;
    sequence: number;
    produced_by: string | null;
  }[];
  legacy?: ProvenanceActivity[];
  analyses?: ProvenanceActivity[];
  limits?: string[];
}

export type Pattern = "1_to_1" | "2_to_1" | "n_to_1";

export interface FeatureDescriptor {
  id: string;
  label: string;
  menu_path: string;
  pattern: Pattern;
  icon: string | null;
  has_params: boolean;
  operand_label: string;
  object_kind: PanelKind;
  /** Destination panel for results.  Equals ``object_kind`` for the vast
   *  majority of features; differs for cross-kind features such as image
   *  profiles / projections / histogram (image → signal) and
   *  ``signals_to_image`` (signal → image). */
  output_kind: PanelKind;
  /** Whether the feature can run speculatively on a private source copy. */
  preview_enabled: boolean;
}

/** Temporary, non-published result returned by ``preview_feature``. */
export type ProcessingPreviewResult =
  { kind: "signal"; data: SignalData } | { kind: "image"; data: ImageData };

/** One entry of the "Processing > Fitting > Interactive fitting" submenu. */
export interface InteractiveFitInfo {
  id: string;
  label: string;
  /** ``polynomial_fit`` exposes a ``degree`` extra; everything else is
   *  parameterless. */
  needs_degree: boolean;
}

/** One adjustable parameter of an interactive fit (slider row). */
export interface InteractiveFitParam {
  name: string;
  /** Pretty label for display (Greek letters etc.). */
  label: string;
  value: number;
  min: number;
  max: number;
}

/** Payload returned by :meth:`DataLabRuntime.initInteractiveFit`. */
export interface InteractiveFitInit {
  fit_id: string;
  label: string;
  /** Source signal X / Y arrays (full range). */
  x: number[];
  y: number[];
  /** X / Y restricted to the active ROI (== full range when no ROI). */
  x_roi: number[];
  y_roi: number[];
  params: InteractiveFitParam[];
  /** Fit evaluated on the full X axis with the initial parameters. */
  y_fit: number[];
  needs_degree: boolean;
  extras: Record<string, unknown>;
}

/** Payload returned by :meth:`DataLabRuntime.autoFitInteractive`. */
export interface InteractiveFitAuto {
  values: Record<string, number>;
  y_fit: number[];
  residual_rms: number;
}

export interface PluginInfoMeta {
  id: string;
  name: string;
  version: string;
  description: string;
  icon: string | null;
  capabilities: Array<"processing" | "io" | "visualization" | "application">;
  documentation_url: string | null;
}

export interface PluginRecipeSummary {
  id: string;
  version: string;
  title: string;
  description: string;
  inputs: PluginRecipeSlot[];
  has_params: boolean;
}

export interface PluginExampleSummary {
  id: string;
  title: string;
  description: string;
  /** Recipes the example is designed for; empty for a plain dataset. */
  recipe_ids: string[];
  expected_checks: string[];
}

/** Selection a plugin tool needs (names follow menu select conditions). */
export type PluginToolSelection =
  "none" | "exactly_one" | "at_least_one" | "at_least_two";

export interface PluginToolSummary {
  id: string;
  title: string;
  description: string;
  /** ``launcher``: plugin code; ``instrument``: window drawn by DataLab. */
  kind: "launcher" | "instrument";
  /** Panel of the objects the tool works on; ``null`` for both panels. */
  object_type: PanelKind | null;
  selection: PluginToolSelection;
}

/** What an instrument window shows when it opens. */
export interface PluginInstrumentSession {
  plugin_id: string;
  tool_id: string;
  title: string;
  settings: SchemaWithValues;
  live_interval_ms: number;
  /** Default state of the "New group" option, set by the instrument. */
  new_group: boolean;
}

/** Live frame of an instrument: signals drawn together, or one image. */
export type PluginInstrumentFrame = (
  | { kind: "signals"; items: SignalData[] }
  | { kind: "image"; items: ImageData[] }
) & {
  summary: string;
  /** Fixed Y range of signals, or color range of the image. */
  value_range: [number, number] | null;
};

export interface PluginInstrumentAcquisition {
  panel: PanelKind;
  group_id: string;
  group_title: string;
  object_ids: string[];
}

export interface PluginWheelInspection {
  filename: string;
  distribution: string;
  version: string;
  summary: string;
  sha256: string;
  size_bytes: number;
  requires_python: string | null;
  tags: string[];
  entry_points: Array<{
    name: string;
    module: string;
    attribute: string;
  }>;
  top_level_packages: string[];
  dependencies: Array<{
    requirement: string;
    applies: boolean;
    installed_version: string | null;
    compatible: boolean;
  }>;
}

export interface PluginRecord {
  name: string;
  record_id: string;
  filename: string;
  module: string;
  source: "bundled-wheel" | "user-wheel" | "builtin-source" | "user-source";
  artifact_id: string | null;
  artifact_filename: string | null;
  plugin_id: string | null;
  distribution: string | null;
  version: string | null;
  sha256: string | null;
  trust: "verified" | "unverified";
  entry_point: string | null;
  enabled: boolean;
  loaded: boolean;
  error: string | null;
  info: PluginInfoMeta | null;
  recipes: PluginRecipeSummary[];
  examples: PluginExampleSummary[];
  tools: PluginToolSummary[];
  operations: {
    can_enable: boolean;
    can_disable: boolean;
    can_remove: boolean;
    can_reload: boolean;
  };
}

export interface PluginRecipeSlot {
  id: string;
  title: string;
  description: string;
  object_type: "signal" | "image";
  cardinality: "one" | "many";
  required: boolean;
  min_count: number;
  metadata: Array<{ key: string; description: string; required: boolean }>;
}

export interface PluginRecipeCandidate {
  id: string;
  kind: "signal" | "image";
  title: string;
  compatible_slots: string[];
  /** Required metadata keys the candidate lacks, per compatible slot. */
  missing_metadata: Record<string, string[]>;
}

export type PluginRecipeIssueCode =
  | "missing"
  | "ambiguous"
  | "too_few"
  | "too_many"
  | "wrong_type"
  | "missing_metadata"
  | "duplicate";

export interface PluginRecipeInputIssue {
  code: PluginRecipeIssueCode;
  slot_id: string;
  details: {
    count?: number;
    min_count?: number;
    key?: string;
    titles?: string[];
  };
}

export type PluginRecipeReadinessStatus =
  "no_input" | "needs_assignment" | "not_ready" | "warnings" | "ready";

export interface PluginRecipeReadiness {
  status: PluginRecipeReadinessStatus;
  bindings: Record<string, string[]>;
  issues: PluginRecipeInputIssue[];
  diagnostics: PluginRecipeDiagnostic[];
}

/** Readiness of one recipe, or the error raised while assessing it. */
export type PluginRecipeAssessment =
  PluginRecipeReadiness | { status: "error"; error: string };

export interface PluginRecipePreparation {
  plugin_id: string;
  recipe_id: string;
  title: string;
  description: string;
  slots: PluginRecipeSlot[];
  candidates: PluginRecipeCandidate[];
  bindings: Record<string, string[]>;
  ambiguous_slots: string[];
  missing_slots: string[];
  readiness: PluginRecipeReadiness;
  parameters: SchemaWithValues | null;
}

export interface PluginRecipeObject {
  output_id: string;
  id: string;
  kind: "signal" | "image";
  title: string;
}

export interface PluginRecipeResult {
  output_id: string;
  anchor_output_id: string;
  anchor_id: string;
  metadata_key: string;
}

export interface PluginRecipeDiagnostic {
  level: "info" | "warning" | "error";
  code: string;
  message: string;
  details: Record<string, unknown>;
}

export interface PluginRecipeCommit {
  plugin_id: string;
  recipe_id: string;
  run_id: string;
  objects: PluginRecipeObject[];
  results: PluginRecipeResult[];
  diagnostics: PluginRecipeDiagnostic[];
}

export interface PluginExampleOpenResult extends WorkspaceLoadResult {
  plugin_id: string;
  example_id: string;
  /** Recipe the example was opened for (requested, or its first one). */
  recipe_id: string | null;
  recipe_ids: string[];
  filename: string | null;
  panel: "signal" | "image" | null;
  selected_ids: string[];
  current_id: string | null;
  dirty: boolean;
  /** Parameter values suited to the example, per recipe ID. */
  parameter_values: Record<string, Record<string, unknown>>;
}

export interface PluginMenuAction {
  action_id: string;
  title: string;
  menu_path: string[];
  select_condition: string;
  separator_before: boolean;
  icon: string | null;
  tip: string | null;
  origin: string | null;
  object_kind: PanelKind;
}

export type PanelKind = "signal" | "image";

export interface ObjectNode extends SignalMeta {
  kind: PanelKind;
}

export interface GroupNode {
  gid: string;
  name: string;
  objects: ObjectNode[];
}

export interface PanelTree {
  kind: PanelKind;
  groups: GroupNode[];
}

/** Editable metadata fields of a signal object (Phase 4). */
export interface ObjectMeta {
  title: string;
  xlabel: string;
  ylabel: string;
  xunit: string;
  yunit: string;
}

/** Plotly shapes/annotations payload persisted alongside a signal. */
export interface PlotlyAnnotations {
  shapes: unknown[];
  annotations: unknown[];
}

export type AnnotationTextAnchor =
  | "top-left"
  | "top"
  | "top-right"
  | "left"
  | "center"
  | "right"
  | "bottom-left"
  | "bottom"
  | "bottom-right";

export type AnnotationJsonValue =
  | null
  | string
  | number
  | boolean
  | AnnotationJsonValue[]
  | { [key: string]: AnnotationJsonValue };

export interface GraphicalAnnotationStyle {
  stroke: {
    color: string | null;
    width: number;
    opacity: number;
    dash: string | number[];
  };
  fill: { color: string | null; opacity: number };
  marker: { symbol: string; size: number; color: string | null };
  text: {
    family: string | null;
    size: number;
    bold: boolean;
    italic: boolean;
    color: string;
    background_color: string | null;
    background_opacity: number;
  };
}

export interface GraphicalAnnotationLabel {
  text: string;
  visible: boolean;
  anchor: AnnotationTextAnchor;
  offset: [number, number];
}

interface GraphicalAnnotationCommon {
  format: "sigima.annotation";
  version: "1.0";
  id: string;
  visible: boolean;
  locked: boolean;
  z_index: number;
  title: string;
  style: GraphicalAnnotationStyle;
  label: GraphicalAnnotationLabel | null;
  metadata: Record<string, AnnotationJsonValue>;
  extensions: Record<string, AnnotationJsonValue>;
}

export type GraphicalAnnotation = GraphicalAnnotationCommon &
  (
    | { kind: "point"; x: number; y: number }
    | {
        kind: "segment";
        x0: number;
        y0: number;
        x1: number;
        y1: number;
      }
    | {
        kind: "rectangle";
        x: number;
        y: number;
        width: number;
        height: number;
        angle: number;
      }
    | { kind: "circle"; cx: number; cy: number; radius: number }
    | {
        kind: "ellipse";
        cx: number;
        cy: number;
        radius_x: number;
        radius_y: number;
        angle: number;
      }
    | { kind: "polyline"; points: Array<[number, number]> }
    | { kind: "polygon"; points: Array<[number, number]> }
    | {
        kind: "text";
        text: string;
        x: number;
        y: number;
        coordinate_space: "data" | "axes";
        anchor: AnnotationTextAnchor;
        offset: [number, number];
      }
    | {
        kind: "cursor";
        orientation: "horizontal" | "vertical" | "crosshair";
        position: number | [number, number];
      }
    | { kind: "range"; axis: "x" | "y"; start: number; end: number }
  );

export interface PlotlyOverlaySpec {
  traces: Array<Record<string, unknown>>;
  shapes: Array<Record<string, unknown>>;
  annotations: Array<Record<string, unknown>>;
}

export interface GraphicalAnnotationsBundle {
  items: GraphicalAnnotation[];
  overlay: PlotlyOverlaySpec;
}

/** A single ROI segment on a 1D signal (Phase 5). */
export interface SignalRoiSegment {
  xmin: number;
  xmax: number;
  title?: string;
}

/** A single ROI on a 2D image — discriminated union by ``geometry``.
 *  All coordinates are physical (matching the image's ``x0``/``y0``/
 *  ``dx``/``dy``).  ``inverse`` flips the masking logic (default false). */
export type ImageRoiSegment =
  | {
      geometry: "rectangle";
      title?: string;
      inverse?: boolean;
      x0: number;
      y0: number;
      dx: number;
      dy: number;
    }
  | {
      geometry: "circle";
      title?: string;
      inverse?: boolean;
      xc: number;
      yc: number;
      r: number;
    }
  | {
      geometry: "polygon";
      title?: string;
      inverse?: boolean;
      points: [number, number][];
    };

/** Image data payload returned by ``get_image_data``. */
export interface ImageData {
  id: string;
  title: string;
  width: number;
  height: number;
  /** Pixel grid.  When the runtime requests ``encoding="bytes"``
   *  (the default for the front-end), this is an array of
   *  ``Float32Array`` rows, one per image line.  Plotly accepts
   *  typed-array rows directly as ``z``. */
  data: Float32Array[] | number[][];
  dtype: string;
  /** Center of the first pixel (Sigima convention) and pixel spacing: pixel
   *  ``(i, j)`` is centered on ``(x0 + i·dx, y0 + j·dy)``, so the image spans
   *  ``[x0 - dx/2, x0 + (width - ½)·dx]``. */
  x0: number;
  y0: number;
  dx: number;
  dy: number;
  /** ``false`` for images carrying explicit per-column / per-row pixel-center
   *  coordinates (``xcoords``/``ycoords``).  When ``false``, ``x0``/``dx`` are
   *  meaningless and the viewer must render variable-width cells from the
   *  coordinate arrays.  Defaults to uniform when omitted. */
  is_uniform_coords?: boolean;
  /** Per-column pixel-center X coordinates (non-uniform images only). */
  xcoords?: number[];
  /** Per-row pixel-center Y coordinates (non-uniform images only). */
  ycoords?: number[];
  /** Pre-computed extrema, used to bound the contrast slider. */
  data_min: number;
  data_max: number;
  /** Default LUT range with histogram outlier tails removed (mirrors
   *  DataLab desktop's ``ima_eliminate_outliers`` auto-contrast).  Used as the
   *  default colour range; ``data_min``/``data_max`` still bound the slider.
   *  Falls back to ``[data_min, data_max]`` when omitted. */
  lut_default?: [number, number];
  xlabel: string;
  ylabel: string;
  zlabel: string;
  xunit: string;
  yunit: string;
  zunit: string;
  /** Optional Plotly colorscale name persisted in the image's metadata
   *  (``"Viridis"``, ``"Jet"``, ``"Gray"`` …).  When ``null``, the
   *  viewer falls back to the :class:`ImagePlot` default. */
  colormap?: string | null;
  /** Reverse the colormap (appends ``_r`` to the Plotly colorscale). */
  invert_colormap?: boolean;
  /** Resampling method used when the viewer downsamples the display
   *  bitmap (large images zoomed out): ``"nearest"`` (decimation,
   *  default), ``"max"`` (preserve hot pixels) or ``"mean"`` (smooth).
   *  Persisted in the image's metadata; never affects profiles /
   *  statistics, which always read full-resolution data. */
  resample_method?: string | null;
}

/** Legacy synthetic image parameters (kept for backwards compatibility). */
export interface ImageCreationParams {
  kind: "gauss" | "ramp" | "random";
  title: string;
  width: number;
  height: number;
  a?: number;
  sigma?: number;
}

/** One entry of the image "Create" menu, mirrors :class:`SignalCreationType`. */
export interface ImageCreationType {
  value: string;
  label: string;
  icon: string;
  separator_before: boolean;
}

/** Diagnostic info returned by ``openWorkspaceHdf5``. */
export interface WorkspaceLoadResult {
  signals: number;
  images: number;
  groups: number;
  /** Set when a file holding provenance was appended: its provenance is not
   *  imported (see ``workspaceHasProvenance``). */
  provenance_notice?: string;
}

/** Parameters of the Text Import Wizard (mirrors
 *  :class:`datalab.widgets.textimport.SignalImportParam`). */
export interface TextImportParams {
  delimiter: string;
  decimal: string;
  comment: string;
  skipRows: number;
  maxRows: number | null;
  /** ``"infer"`` (auto), ``"none"`` (no header) or ``"first"`` (first row). */
  header: "infer" | "none" | "first";
  transpose: boolean;
  firstColIsX: boolean;
  dtypeStr: string;
}

/** Preview payload returned by :meth:`DataLabRuntime.parseTextImport`. */
export interface TextImportPreview {
  headers: string[];
  /** First N rows of the parsed matrix; NaN cells are encoded as
   *  ``"NaN"`` strings. */
  preview_rows: (number | string)[][];
  nrows: number;
  ncols: number;
  /** Candidate signal titles (after applying ``firstColIsX``). */
  signal_titles: string[];
  error: string | null;
}

/** Candidate-signal payload for the wizard's graphical preview page. */
export interface TextImportSignal {
  title: string;
  x: number[];
  y: number[];
  xlabel: string;
  ylabel: string;
}

export interface TextImportSignals {
  signals: TextImportSignal[];
  error: string | null;
}

/** Final wizard payload (selection + shared labels). */
export interface TextImportCommitOptions {
  selectedIndices: number[];
  title?: string;
  xlabel?: string;
  ylabel?: string;
  xunit?: string;
  yunit?: string;
  groupId?: string | null;
}

/** Default parameters for the Text Import Wizard. */
export function defaultTextImportParams(): TextImportParams {
  return {
    delimiter: ",",
    decimal: ".",
    comment: "#",
    skipRows: 0,
    maxRows: null,
    header: "infer",
    transpose: false,
    firstColIsX: true,
    dtypeStr: "float64",
  };
}

/** Convert a TextImportParams object to bootstrap.py kwargs. */
export function textImportToPyKwargs(
  params: TextImportParams,
): Record<string, unknown> {
  return {
    delimiter: params.delimiter,
    decimal: params.decimal,
    comment: params.comment,
    skip_rows: params.skipRows,
    max_rows: params.maxRows,
    header: params.header,
    transpose: params.transpose,
    first_col_is_x: params.firstColIsX,
    dtype_str: params.dtypeStr,
  };
}

/** One node of the HDF5 browser tree (mirrors Qt H5TreeWidget rows). */
export interface H5BrowserNode {
  id: string;
  name: string;
  icon_name: string;
  shape_str: string;
  dtype_str: string;
  text: string;
  description: string;
  is_supported: boolean;
  is_array: boolean;
  is_group: boolean;
  /** ``"group" | "scalar" | "text" | "array" | "compound" | "signal" | "image"``. */
  kind: string;
  children: H5BrowserNode[];
}

/** Result of opening one HDF5 file in the browser dialog. */
export interface H5BrowserFile {
  file_id: string;
  filename: string;
  root: H5BrowserNode;
}

/** Attributes pane payload for one selected node. */
export interface H5BrowserNodeAttrs {
  path: string;
  name: string;
  description: string;
  text_preview: string;
  attributes: Record<string, unknown>;
}

/** Preview data for the right-side Plotly pane. */
export type H5BrowserPreview =
  | { kind: "unsupported"; error?: string }
  | { kind: "signal"; title: string; x: number[]; y: number[] }
  | {
      kind: "image";
      title: string;
      width: number;
      height: number;
      data: number[][];
    };

/** Raw array payload for the "Show array" spreadsheet view. */
export interface H5BrowserArray {
  shape: number[];
  dtype: string;
  data: unknown;
}

/** Result of importing selected HDF5 nodes into the live model. */
export interface H5BrowserImportResult {
  oids: string[];
  /** True when integer values could not all be represented exactly
   *  (beyond 2**53). */
  inexact_values: boolean;
}

/**
 * JSON Schema 2020-12 document augmented with ``x-guidata-*`` extensions,
 * as produced by :func:`guidata.dataset.dataset_to_schema`.
 *
 * Treated as a loose dictionary on the JS side: each frontend widget
 * inspects only the keys it cares about. The shape is documented in
 * ``guidata/dataset/jsonschema.py``.
 */
export type JsonSchema = Record<string, unknown>;

export interface SchemaWithValues {
  schema: JsonSchema;
  values: Record<string, unknown>;
}

export interface DynamicChoice {
  value: unknown;
  label: string;
  icon?: string;
}

/** Read-only stats summary returned by
 *  :meth:`DataLabRuntime.getObjectStats`. */
export type ObjectStats =
  | {
      kind: "signal";
      n_points: number;
      x_dtype: string;
      y_dtype: string;
      x_min: number | null;
      x_max: number | null;
      y_min: number | null;
      y_max: number | null;
      y_mean: number | null;
      y_std: number | null;
      y_median: number | null;
    }
  | {
      kind: "image";
      shape: number[];
      dtype: string;
      min: number | null;
      max: number | null;
      mean: number | null;
      std: number | null;
      median: number | null;
    };

/** Atomic payload needed to render one signal selection. */
export interface SignalResultBundle {
  signalId: string;
  results: AnalysisResult[];
}

export interface SignalViewSnapshot {
  kind: "signal";
  current: SignalData;
  extras: SignalData[];
  annotations: PlotlyAnnotations;
  graphical_annotations: GraphicalAnnotationsBundle;
  roi: SignalRoiSegment[];
  results: AnalysisResult[];
  extra_results: SignalResultBundle[];
}

/** Atomic payload needed to render one image selection. */
export interface ImageViewSnapshot {
  kind: "image";
  mode: "single" | "multi";
  images: ImageData[];
  annotations: PlotlyAnnotations;
  graphical_annotations: GraphicalAnnotationsBundle;
  roi: ImageRoiSegment[];
  lut_range: [number, number] | null;
  results: AnalysisResult[];
}

/** Atomic payload needed by the Properties side panel. */
export interface PropertiesSnapshot {
  oid: string;
  schema: SchemaWithValues;
  stats: ObjectStats;
  signal_preview: SignalDataPreview | null;
}

/** Discriminator for the metadata-editor widgets. */
export type MetadataValueType = "string" | "number" | "bool" | "json";

/** One row of the metadata editor (returned by
 *  :meth:`DataLabRuntime.listObjectMetadata`). */
export interface MetadataEntry {
  key: string;
  value_type: MetadataValueType;
  value: string;
}

/** One entry of the "Create" menu, returned by
 *  :meth:`DataLabRuntime.listSignalCreationTypes`. */
export interface SignalCreationType {
  /** Stable id (matches a ``SignalTypes`` enum value on the Python side). */
  value: string;
  /** Translated, human-readable label. */
  label: string;
  /** Bare SVG filename (e.g. ``"sine.svg"``) — the React UI maps it to a
   *  bundled URL via Vite's ``import.meta.glob``. */
  icon: string;
  /** When true, draw a separator *before* this entry in the menu (mirrors
   *  the desktop "Create" menu's grouping). */
  separator_before: boolean;
}

/** One I/O format descriptor returned by
 *  :meth:`DataLabRuntime.listSignalIoFormats`. */
export interface SignalIoFormat {
  name: string;
  extensions: string[];
}

export interface SignalIoFormats {
  read: SignalIoFormat[];
  write: SignalIoFormat[];
  all_read_extensions: string[];
  all_write_extensions: string[];
}

/** Image I/O catalogue — identical shape to :class:`SignalIoFormats`. */
export type ImageIoFormats = SignalIoFormats;

/** Menu descriptor for one entry of the "Analysis" menu. */
export interface SignalAnalysisDescriptor {
  /** Stable id (e.g. ``"fwhm"``).  Matches the Sigima function name. */
  id: string;
  label: string;
  /** Bare SVG filename or ``""`` for icon-less entries. */
  icon: string;
  /** Insert a separator above this entry (mirrors DataLab desktop). */
  separator_before: boolean;
  /** ``true`` when the analysis exposes a parameter DataSet. */
  has_params: boolean;
  /** Optional submenu (folder) this entry belongs to, e.g. ``"Blob
   *  detection"``; ``null``/absent for top-level Analysis entries. */
  submenu?: string | null;
}

/** Optional plot overlay attached to a result (currently only emitted
 *  by pulse-features tables — segments for baselines/plateau and
 *  vertical markers for x₀ / x₅₀ / x₁₀₀). */
export type AnalysisOverlay =
  | {
      kind: "segment";
      x0: number;
      y0: number;
      x1: number;
      y1: number;
      label?: string;
      color?: string;
    }
  | { kind: "vline"; x: number; label?: string; color?: string }
  | { kind: "hline"; y: number; label?: string; color?: string };

/** Per-row geometry / table payload (one of two ``category`` values). */
export interface AnalysisResultBase {
  metadata_key: string;
  title: string;
  func_name: string | null;
  headers: string[];
  roi_indices: number[] | null;
  /** Optional plot overlays (segments, vlines) supplementing the
   *  numerical result.  Currently emitted for pulse-features tables. */
  overlays?: AnalysisOverlay[];
  /** Set by image detection analyses (peak / blob / hough / contour) when
   *  the ``create_rois`` parameter caused fresh ROIs to be attached to
   *  the source object.  The UI uses this flag to refresh the ROI overlay
   *  without re-fetching everything. */
  roi_modified?: boolean;
}

export interface GeometryAnalysisResult extends AnalysisResultBase {
  category: "geometry";
  /** ``"point" | "marker" | "segment" | "rectangle" | "circle" | "ellipse" | "polygon"``. */
  kind: string;
  /** N×K array of physical coordinates (K depends on ``kind``).  Used to
   *  draw the plot overlays (segments, markers, …) — not shown verbatim
   *  in the results table. */
  coords: number[][];
  /** Displayed table rows, aligned with ``headers``.  Mirrors DataLab
   *  desktop (Qt): a segment collapses to a single Δx / Δy / length
   *  column rather than the four raw x0/y0/x1/y1 coordinates.  Falls
   *  back to ``coords`` when absent (legacy payloads). */
  data?: (number | string | null)[][];
}

export interface TableAnalysisResult extends AnalysisResultBase {
  category: "table";
  kind: string;
  data: (number | string | null)[][];
}

export type AnalysisResult = GeometryAnalysisResult | TableAnalysisResult;

/** One plottable analysis-result category, returned by
 *  :meth:`DataLabRuntime.getPlotResultsSchemas`.  Describes the data the
 *  "Plot results" dialog needs to let the user pick X/Y columns. */
export interface PlotResultsSchemaEntry {
  /** Result category key (e.g. ``"fwhm"`` or ``"shape_circle"``). */
  category: string;
  /** Result kind value (e.g. ``"fwhm"``, ``"circle"``). */
  kind: string;
  /** ``true`` for geometry results, ``false`` for table results. */
  is_geometry: boolean;
  /** Human-readable result title (Sigima-localised). */
  label: string;
  /** Numeric column names selectable for the X / Y axes. */
  numeric_headers: string[];
  /** Default plot kind (``"one_curve_per_object"`` when any result holds
   *  more than one row, otherwise ``"one_curve_per_title"``). */
  default_kind: "one_curve_per_object" | "one_curve_per_title";
}

export interface SignalCreationParams {
  kind: "sine" | "cosine" | "gauss" | "noise";
  title: string;
  size: number;
  xmin: number;
  xmax: number;
  a?: number;
  freq?: number;
  phase?: number;
  mu?: number;
  sigma?: number;
}

/** Lightweight macro entry returned by ``listMacros`` (no code). */
export interface MacroMeta {
  id: string;
  title: string;
}

/** Full macro record (with source code). */
export interface MacroRecord extends MacroMeta {
  code: string;
}

/** One issue or proxy call reported by :meth:`DataLabRuntime.lintMacro`. */
export interface MacroLintLocation {
  name: string;
  line: number;
  col: number;
}

export interface MacroLintProxyCall extends MacroLintLocation {
  awaited: boolean;
  is_async: boolean;
}

/** Result of statically linting a macro source. */
/** Captured output of a macro run by :meth:`DataLabRuntime.runMacroCode`. */
export interface MacroRunOutput {
  stdout: string;
  stderr: string;
  status: "ok" | "error" | "stopped";
  error?: string;
}

export interface MacroLintResult {
  ok: boolean;
  syntax_error: { line: number; col: number; message: string } | null;
  unknown_methods: MacroLintLocation[];
  missing_await: MacroLintLocation[];
  proxy_calls: MacroLintProxyCall[];
}

/** Lightweight notebook entry returned by ``listNotebooks`` (no content). */
export interface NotebookMeta {
  id: string;
  title: string;
}

/** Full notebook record (with raw nbformat v4.5 JSON content). */
export interface NotebookRecord extends NotebookMeta {
  /** Serialised nbformat v4.5 JSON document (opaque to Python). */
  content: string;
}

/** Convert a PyProxy result into a plain JS value (recursively). */
function toJs(value: unknown): unknown {
  if (value && typeof value === "object" && "toJs" in value) {
    const proxy = value as PyProxy;
    const result = proxy.toJs?.({
      dict_converter: (entries) =>
        Object.fromEntries(entries as Iterable<[string, unknown]>),
    });
    proxy.destroy?.();
    return result;
  }
  return value;
}

/** Map ``undefined`` (Pyodide's conversion of ``None``) back to JSON ``null``. */
function restoreJsonNulls(value: unknown): unknown {
  if (value === undefined) return null;
  if (Array.isArray(value)) return value.map(restoreJsonNulls);
  if (value !== null && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value).map(([key, item]) => [key, restoreJsonNulls(item)]),
    );
  }
  return value;
}

/** Normalise bytes returned by Python into a ``Uint8Array``. */
function asBytes(value: unknown): Uint8Array {
  if (value instanceof Uint8Array) return value;
  if (value instanceof ArrayBuffer) return new Uint8Array(value);
  return Uint8Array.from(value as number[]);
}

/** Read a selected file (or pass bytes through). */
async function readBytes(data: Blob | Uint8Array): Promise<Uint8Array> {
  return data instanceof Uint8Array
    ? data
    : new Uint8Array(await data.arrayBuffer());
}

/**
 * Reshape a flat ``Float32`` byte buffer into a list of typed-array
 * rows that Plotly's ``heatmap`` trace consumes directly as ``z``.
 *
 * When the Python helper was asked to encode the image as bytes it
 * returns ``data`` either as a :class:`Uint8Array` (Pyodide's default
 * for ``bytes``) or as a memoryview-like object exposing a ``buffer``.
 * Either way we end up with ``H`` rows of ``W`` floats with zero
 * structural copies — only the typed-array views are allocated.
 *
 * Inputs already in the legacy ``number[][]`` form (Python tests, the
 * notebook display path) are returned unchanged.
 */
export function decodeImagePayload<
  T extends { encoding?: string; data: unknown; width: number; height: number },
>(payload: T): T {
  if (payload.encoding !== "f32") return payload;
  const raw = payload.data as ArrayBufferView | ArrayBuffer;
  const view =
    raw instanceof ArrayBuffer
      ? new Float32Array(raw)
      : new Float32Array(
          raw.buffer,
          raw.byteOffset,
          raw.byteLength / Float32Array.BYTES_PER_ELEMENT,
        );
  const w = payload.width;
  const h = payload.height;
  const rows: Float32Array[] = new Array(h);
  for (let j = 0; j < h; j += 1) {
    // ``subarray`` shares the underlying buffer — no per-row copy.
    rows[j] = view.subarray(j * w, (j + 1) * w);
  }
  return { ...payload, data: rows };
}

/**
 * Decode the ``bytes`` encoding of ``get_signal_xy`` into zero-copy
 * ``Float64Array`` views.  The Python helper ships the X / Y arrays as
 * raw little-endian ``float64`` byte strings (a single ``Uint8Array``
 * memcpy across the Pyodide bridge) instead of marshalling every sample
 * as a JSON number, which is one to two orders of magnitude cheaper for
 * large signals.  Payloads already in the legacy ``list`` form (Python
 * tests, notebook display) are returned unchanged.
 */
export function decodeSignalPayload(
  payload: SignalData & {
    encoding?: string;
    x_bytes?: ArrayBufferView | ArrayBuffer;
    y_bytes?: ArrayBufferView | ArrayBuffer;
  },
): SignalData {
  if (payload.encoding !== "f64") return payload;
  const toF64 = (raw: ArrayBufferView | ArrayBuffer): Float64Array =>
    raw instanceof ArrayBuffer
      ? new Float64Array(raw)
      : new Float64Array(
          raw.buffer,
          raw.byteOffset,
          raw.byteLength / Float64Array.BYTES_PER_ELEMENT,
        );
  const { x_bytes, y_bytes, ...rest } = payload;
  return {
    ...rest,
    x: x_bytes ? toF64(x_bytes) : payload.x,
    y: y_bytes ? toF64(y_bytes) : payload.y,
  };
}

/** Outcome of {@link DataLabRuntime.freeMemory}. */
export interface FreeMemoryResult {
  /** Unreachable objects reclaimed by ``gc.collect``. */
  collected: number;
  /** Tracked Python objects before the collection pass. */
  objects_before: number;
  /** Tracked Python objects after the collection pass. */
  objects_after: number;
  /** WASM heap size (bytes) before collection, or ``null`` if unknown. */
  wasmBefore: number | null;
  /** WASM heap size (bytes) after collection, or ``null`` if unknown. */
  wasmAfter: number | null;
}

/**
 * Runtime storage mode.
 *
 * ``"ram"`` (default) keeps every signal/image array resident in the
 * Pyodide WASM heap — fastest, but the working set is capped by the
 * ~2 GB wasm32 ceiling. ``"disk"`` spills each object's heavy array to
 * the Origin Private File System and pages it back in only for the
 * duration of the call that needs it, so the heap stays flat and the
 * dataset is bounded by disk quota instead of RAM.
 */
export type StorageMode = "ram" | "disk";

/** Pyodide loader signature — ``window.loadPyodide`` or, in a worker, a
 *  dynamic-``import()`` wrapper around the ESM Pyodide build. */
export type PyodideLoader = (opts: { indexURL: string }) => Promise<unknown>;

/**
 * Options for {@link DataLabRuntime.load}.
 *
 * All fields are optional and default to the historical main-thread
 * behaviour, so existing callers (``DataLabRuntime.load(onProgress)``) are
 * unaffected. They exist so the same boot sequence can run inside a
 * Dedicated Web Worker, where there is no ``window``/DOM: the worker injects
 * a Pyodide ``loader`` and the locale-derived values that the DOM-less
 * ``i18n`` layer cannot compute on its own.
 */
export interface RuntimeLoadOptions {
  /** Pyodide loader; defaults to ``window.loadPyodide``. */
  loadPyodide?: PyodideLoader;
  /** ``LANG`` for the Pyodide environment; defaults to ``pyodideLang()``. */
  lang?: string;
  /** Locale-dependent strings pushed into ``bootstrap.py``; default to those
   *  of the active UI locale (English in a DOM-less worker, which therefore
   *  receives them from the main thread). */
  labels?: RuntimeLabels;
}

export class DataLabRuntime {
  private constructor(
    private readonly py: PyodideAPI,
    private readonly pluginWheelStore: PluginWheelStore | null = null,
  ) {}

  private mutationListeners: Set<(name: string) => void> = new Set();
  private storageErrorListeners: Set<(message: string) => void> = new Set();

  /**
   * Subscribe to durable-workspace mutations. The callback fires *after*
   * any ``callPy`` invocation that mutates the workspace state.
   *
   * Returns an unsubscribe function. Listeners must not throw (errors
   * are logged and otherwise ignored to keep the runtime queue clean).
   */
  onWorkspaceMutation(listener: (name: string) => void): () => void {
    this.mutationListeners.add(listener);
    return () => {
      this.mutationListeners.delete(listener);
    };
  }

  /**
   * Subscribe to the on-disk storage errors following a successful call.
   *
   * Such a call is not failed (it would be applied twice if retried): the
   * objects that could not be stored on disk stay in memory with their data.
   * An error is reported once, until the store works again. Returns an
   * unsubscribe function; listeners must not throw.
   */
  onStorageError(listener: (message: string) => void): () => void {
    this.storageErrorListeners.add(listener);
    return () => {
      this.storageErrorListeners.delete(listener);
    };
  }

  private emitStorageError(message: string): void {
    for (const cb of this.storageErrorListeners) {
      try {
        cb(message);
      } catch (err) {
        console.warn("[runtime] storage-error listener threw", err);
      }
    }
  }

  private emitWorkspaceMutation(name: string): void {
    if (this.mutationListeners.size === 0) return;
    for (const cb of this.mutationListeners) {
      try {
        cb(name);
      } catch (err) {
        console.warn("[runtime] workspace-mutation listener threw", err);
      }
    }
  }

  static async load(
    onProgress?: (msg: string) => void,
    opts: RuntimeLoadOptions = {},
  ): Promise<DataLabRuntime> {
    // The Pyodide loader is injectable so the runtime can boot both on the
    // main thread (where ``window.loadPyodide`` is provided by the
    // index.html <script>) and inside a Dedicated Web Worker (where the
    // ``kernelWorker`` passes a dynamic-``import()`` loader for the ESM
    // Pyodide build — there is no ``window`` there). Default preserves the
    // historical main-thread behaviour exactly.
    const loadPyodide =
      opts.loadPyodide ??
      (typeof window !== "undefined" ? window.loadPyodide : undefined);
    if (typeof loadPyodide !== "function") {
      throw new Error(
        "Pyodide failed to load from the CDN. Check the browser console " +
          "and your network / Content-Security-Policy settings.",
      );
    }
    onProgress?.(t("Loading Pyodide runtime…"));
    const py = (await loadPyodide({
      indexURL: PYODIDE_INDEX,
    })) as PyodideAPI;
    let pluginWheelStore: PluginWheelStore | null = null;
    const storedPluginWheels: StoredPluginWheel[] = [];
    if (PluginWheelStore.isSupported()) {
      try {
        pluginWheelStore = new PluginWheelStore();
        await pluginWheelStore.init();
        for (const metadata of pluginWheelStore.list()) {
          try {
            storedPluginWheels.push({
              metadata,
              bytes: await pluginWheelStore.readBytes(metadata.sha256),
            });
          } catch (error) {
            console.error(
              `[plugins] failed to restore ${metadata.filename}`,
              error,
            );
            storedPluginWheels.push({
              metadata,
              bytes: new Uint8Array(),
            });
          }
        }
      } catch (error) {
        pluginWheelStore = null;
        console.error(
          "[plugins] failed to initialise persistent storage",
          error,
        );
      }
    }

    // ---------------------------------------------------------------
    // Pin the Pyodide locale *before* any ``guidata`` / ``sigima``
    // import.
    //
    // Why: Sigima exposes user-facing labels (e.g. ``SignalTypes`` /
    // ``ImageTypes`` enum entries shown in the ``Create`` menu, plus
    // processing labels and parameter labels) wrapped in ``gettext
    // _()``. ``guidata.configtools.get_translation`` reads
    // ``os.environ["LANG"]`` and loads the matching ``.mo`` catalog
    // (shipped inside the Sigima/guidata wheels) at first import.
    //
    // We derive ``LANG`` from the active UI locale via
    // ``pyodideLang()``: ``C`` for English (POSIX "no translation",
    // returns the original ``msgid`` strings), or the locale code (e.g.
    // ``fr``) to surface the translated catalog — keeping the Python
    // labels consistent with the React UI. Switching language reloads
    // the page, so a fresh Pyodide instance always boots with the right
    // ``LANG``.
    //
    // This MUST run before ``loadPackage``/``micropip.install`` of
    // ``guidata`` and before any ``runPythonAsync`` that touches the
    // guidata shims, otherwise the translation object is cached at
    // import time and the language change comes too late.
    // ---------------------------------------------------------------
    const lang = opts.lang ?? pyodideLang();
    await py.runPythonAsync(`
import os
os.environ["LANG"] = ${JSON.stringify(lang)}
os.environ["LANGUAGE"] = ${JSON.stringify(lang)}
`);

    onProgress?.(t("Loading scientific stack (numpy, scipy, h5py)…"));
    await py.loadPackage([
      "numpy",
      "scipy",
      "h5py",
      "pandas",
      "pillow",
      "micropip",
    ]);

    onProgress?.(t("Installing Sigima…"));
    // Pyodide's ``scikit-image`` package omits Pillow and tifffile from its
    // dependency metadata even though ``skimage.io`` imports both. Pillow is
    // loaded from the Pyodide distribution above; ``tifffile`` is pulled from
    // PyPI explicitly so importing Sigima and TIFF read/write both work.
    // Capped ``<2025`` because tifffile 2025+ requires ``numpy>=2.1`` while
    // the pinned Pyodide (0.26.4) ships numpy 1.26.4 — lift the cap when
    // ``PYODIDE_VERSION`` bumps to a build with numpy>=2.1.
    // DataLab-Capsule (provenance) is optional and only needed by the runtime
    // that owns the workspace (main thread or kernel worker).
    const bootRequirements = [
      SIGIMA_INSTALL_SPEC,
      GUIDATA_INSTALL_SPEC,
      "tifffile<2025",
      ...(DATALAB_CAPSULE_INSTALL_SPEC ? [DATALAB_CAPSULE_INSTALL_SPEC] : []),
    ];
    await py.runPythonAsync(`
import micropip
await micropip.install(${JSON.stringify(bootRequirements)})
`);

    onProgress?.(t("Initialising Sigima namespace…"));
    await py.runPythonAsync(guidataJsonSchemaShim);
    // Mirror the portable ``datalab.*`` shim into Pyodide site-packages.
    DataLabRuntime.installShim(py, shimSources);
    // Verified pure-Python plugin wheels are explicit build assets. They are
    // added directly to ``sys.path``; no package index or Desktop entry point
    // discovery participates in browser startup.
    const bundledPluginWheels = await fetchBundledPluginWheels();
    py.FS.mkdirTree?.("/home/pyodide/plugin-wheels");
    const bundledWheelSpecs = bundledPluginWheels.map(({ wheel, bytes }) => {
      const path = `/home/pyodide/plugin-wheels/${wheel.sha256}.whl`;
      py.FS.writeFile(path, bytes);
      return { ...wheel, path };
    });
    const userWheelSpecs = storedPluginWheels.map(({ metadata, bytes }) => {
      const path = `/home/pyodide/plugin-wheels/user-${metadata.sha256}.whl`;
      py.FS.writeFile(path, bytes);
      return { ...metadata, path };
    });
    // Make ``processor.py``/``dlw_main.py``/``dlw_plugins.py`` importable.
    py.FS.writeFile("/home/pyodide/dlw_processor.py", processorSource);
    py.FS.writeFile("/home/pyodide/dlw_main.py", dlwMainSource);
    py.FS.writeFile("/home/pyodide/dlw_wheels.py", dlwWheelsSource);
    py.FS.writeFile("/home/pyodide/dlw_plugins.py", dlwPluginsSource);
    py.FS.writeFile("/home/pyodide/dlw_applications.py", dlwApplicationsSource);
    py.FS.writeFile("/home/pyodide/dlw_h5browser.py", dlwH5BrowserSource);
    py.FS.writeFile(
      "/home/pyodide/dlw_interactive_fit.py",
      dlwInteractiveFitSource,
    );
    py.FS.writeFile("/home/pyodide/dlw_title_format.py", dlwTitleFormatSource);
    py.FS.writeFile("/home/pyodide/dlw_provenance.py", dlwProvenanceSource);
    // ``macro_proxy.py`` is normally only loaded into worker Pyodides,
    // but the main instance needs the source so :mod:`dlw_macro_lint`
    // can introspect the ``_Proxy`` API surface.
    py.FS.writeFile("/home/pyodide/macro_proxy.py", macroProxySource);
    py.FS.writeFile("/home/pyodide/dlw_macro_lint.py", dlwMacroLintSource);
    await py.runPythonAsync(bootstrapSource);
    await py.runPythonAsync(`
  import dlw_plugins
  for _wheel in ${JSON.stringify(bundledWheelSpecs)}:
    dlw_plugins.load_plugin_wheel(
      _wheel["path"],
      filename=_wheel["filename"],
      source="bundled-wheel",
      sha256=_wheel["sha256"],
      trust="verified",
    )
  for _wheel in ${JSON.stringify(userWheelSpecs)}:
    _records = dlw_plugins.load_plugin_wheel(
      _wheel["path"],
      filename=_wheel["filename"],
      source="user-wheel",
      sha256=_wheel["sha256"],
      trust="unverified",
    )
    for _record in _records:
      if (
        _record["loaded"]
        and _record["plugin_id"] not in _wheel["enabledPluginIds"]
      ):
        dlw_plugins.set_plugin_enabled(_record["record_id"], False)
  import dlw_applications
  dlw_applications.install_host(
    _MODEL,
    _object_uuid,
    open_workspace_from_bytes,
    ${JSON.stringify(import.meta.env.VITE_APP_VERSION)},
    reset_all,
    signal_payload=_signal_data_payload,
    image_payload=_image_data_payload,
  )
  from dlw_applications import (
    acquire_plugin_instrument,
    assess_plugin_recipes,
    check_plugin_recipe_bindings,
    get_plugin_recipe_schema,
    launch_plugin_tool,
    open_plugin_example,
    open_plugin_instrument,
    prepare_plugin_recipe,
    preview_plugin_instrument,
    resolve_plugin_instrument_active,
    resolve_plugin_recipe_active,
    resolve_plugin_recipe_callbacks,
    resolve_plugin_recipe_choices,
    run_plugin_recipe,
  )
  `);

    // Bridge DataLab-Web's own (non-gettext) strings into Python: the "Group"
    // prefix for auto-created groups, the "Untitled" macro/notebook title and
    // the strings of its own dialogs. Sigima/guidata labels are translated via
    // gettext (``LANG`` above), but ``bootstrap.py`` is our own code, so the
    // React side owns these translations and pushes them in here. In worker
    // mode the DOM-less ``t()`` falls back to English, so the labels are
    // passed in explicitly (computed on the main thread) to keep i18n correct.
    const labels = opts.labels ?? currentRuntimeLabels();
    await py.runPythonAsync(
      `set_default_labels(${JSON.stringify(labels.group)}, ${JSON.stringify(
        labels.untitled,
      )})`,
    );
    // Passed as an argument, not inlined in source code: Pyodide cannot
    // tokenize a line as long as a whole catalog (MemoryError).
    const setWebTranslations = py.globals.get("set_web_translations");
    if (!setWebTranslations) {
      throw new Error("bootstrap.py does not define set_web_translations");
    }
    try {
      (setWebTranslations as unknown as (t: Record<string, string>) => void)(
        labels.translations,
      );
    } finally {
      setWebTranslations.destroy?.();
    }
    await py.runPythonAsync(
      `set_provenance_edition_version(${JSON.stringify(
        String(import.meta.env.VITE_APP_VERSION ?? "dev"),
      )})`,
    );

    onProgress?.(t("Ready."));
    const runtime = new DataLabRuntime(py, pluginWheelStore);
    runtime.installDialogBridge();
    await runtime.installBuiltinPlugins(builtinPluginSources);
    return runtime;
  }

  /**
   * Mirror the portable ``datalab.*`` shim into Pyodide's site-packages.
   *
   * Each entry in *sources* is keyed by the workspace-relative path
   * (``./dlplugins/datalab/plugins/base.py``); we strip the leading
   * ``./dlplugins/`` and write to ``/home/pyodide/<rest>``.
   */
  private static installShim(
    py: PyodideAPI,
    sources: Record<string, string>,
  ): void {
    const seenDirs = new Set<string>();
    for (const [path, source] of Object.entries(sources)) {
      const rel = path.replace(/^\.\/dlplugins\//, "");
      const target = `/home/pyodide/${rel}`;
      const dir = target.slice(0, target.lastIndexOf("/"));
      if (!seenDirs.has(dir)) {
        py.FS.mkdirTree?.(dir);
        seenDirs.add(dir);
      }
      py.FS.writeFile(target, source);
    }
  }

  /** Install the JS callback that Python uses for async dialogs. */
  private installDialogBridge(): void {
    const handler = async (kind: unknown, payload: unknown) => {
      const fn = this.dialogHandler;
      if (fn === null) {
        throw new Error(
          `Dialog requested (${String(kind)}) but no handler is registered. ` +
            "Call sigima.setDialogHandler(...) on the JS side first.",
        );
      }
      // Python side converts dict payloads to plain JS objects via
      // ``pyodide.ffi.to_js`` before calling us, so ``payload`` is normally
      // a JS object already.  Keep the legacy ``toJs`` fallback for safety
      // (e.g. if a Python caller forgets the conversion), but never call
      // ``destroy()`` on the proxy: Pyodide registers it with its own
      // ``FinalizationRegistry`` after the awaited call resolves, and an
      // explicit early destroy would race with that registration and abort
      // the WASM runtime ("Object has already been destroyed").
      const proxy = payload as PyProxy | null | undefined;
      let data: unknown = payload;
      if (typeof proxy?.toJs === "function") {
        data = proxy.toJs({
          dict_converter: (entries) =>
            Object.fromEntries(entries as Iterable<[string, unknown]>),
        });
      }
      return fn(String(kind), data);
    };
    const setBridge = this.py.globals.get("set_dialog_bridge");
    if (setBridge) {
      try {
        // Pyodide auto-wraps JS functions into PyProxy callables.
        (setBridge as unknown as (cb: typeof handler) => void)(handler);
      } finally {
        setBridge.destroy?.();
      }
    }
  }

  /** JS-side callback invoked for every async dialog request from Python. */
  private dialogHandler:
    ((kind: string, payload: unknown) => Promise<unknown>) | null = null;

  setDialogHandler(
    handler: ((kind: string, payload: unknown) => Promise<unknown>) | null,
  ): void {
    this.dialogHandler = handler;
  }

  /** Evaluate ``display.active`` for the dataset currently shown by the
   *  bridge ``edit_dataset`` dialog (macros / plugins / remote control /
   *  interactive flows). Returns ``{itemName: boolean}`` so the bridge form
   *  greys out widgets whose enabling condition is unmet, mirroring the Qt
   *  UI; returns ``{}`` when no bridge dialog is open. */
  async resolveBridgeActive(
    values: Record<string, unknown>,
  ): Promise<Record<string, boolean>> {
    // Not queued: the Python call that opened the dialog is suspended awaiting it.
    return await this.invokePy<Record<string, boolean>>(
      "resolve_bridge_active",
      { values },
    );
  }

  /** Run an item's ``display`` callback for the dataset shown by the dialog
   *  bridge and return the refreshed values (``{}`` when none is open). */
  async resolveBridgeCallbacks(
    itemName: string,
    values: Record<string, unknown>,
  ): Promise<Record<string, unknown>> {
    // Not queued, like resolveBridgeActive; it only computes on a dataset copy.
    return await this.invokePy<Record<string, unknown>>(
      "resolve_bridge_callbacks",
      { item_name: itemName, values },
    );
  }

  /**
   * Serialisation queue for all Pyodide calls.
   *
   * Pyodide is single-threaded: two concurrent ``callPy`` invocations would
   * interleave reads/writes of the bootstrap globals (``_STORE``, etc.) and
   * corrupt the Python state.  Every ``callPy`` chains on this promise so
   * the Python side observes a strictly serial sequence of requests.  A
   * failure in one call must not poison subsequent ones, so the chain is
   * rebuilt with ``.catch(() => undefined)``.
   */
  private _queue: Promise<unknown> = Promise.resolve();
  /** Latest generation requested for each coalesced read family. */
  private readonly _latestReadGenerations = new Map<string, number>();

  // ------------------------------------------------------------------
  // On-disk storage mode state (OPFS spill / page-in)
  // ------------------------------------------------------------------

  /** Active storage mode. ``"ram"`` keeps the legacy behaviour with no
   *  OPFS code path engaged at all (guards below are no-ops). */
  private storageMode: StorageMode = "ram";
  /** Lazily-created OPFS byte store; only allocated in ``"disk"`` mode.
   *  Either the async {@link OpfsObjectStore} (main thread) or the faster
   *  synchronous-handle ``OpfsSyncObjectStore`` (when running in a worker). */
  private opfsStore: ObjectByteStore | null = null;
  /** JS mirror of bootstrap's ``_SPILLED`` set — object ids whose heavy
   *  array currently lives on disk rather than in the WASM heap. */
  private readonly spilledOids = new Set<string>();
  /** Whether the on-disk store failed after the last call that used it: a
   *  storage error is reported once, until the store works again. */
  private storageFailing = false;
  /** Cache of {@link getCapsuleSizeLimit} (undefined until read). */
  private capsuleSizeLimit: number | null | undefined;

  /**
   * Invoke a bootstrap.py callable **without** queueing.
   *
   * This is the raw Pyodide call (kwargs marshalling, coroutine await,
   * ``toJs`` conversion, mutation-listener notification). It must only
   * be called from within the serialised section (see {@link callPy})
   * or from the disk-mode guard, which already runs inside it.
   */
  private async invokePy<T = unknown>(
    name: string,
    kwargs: Record<string, unknown> = {},
    options: { silent?: boolean } = {},
  ): Promise<T> {
    const refusable = REFUSABLE.has(name);
    const fn = this.py.globals.get(refusable ? `bridge_${name}` : name);
    if (!fn) {
      throw new Error(`Python function not found: ${name}`);
    }
    if (typeof fn.callKwargs !== "function") {
      fn.destroy?.();
      throw new Error(
        `PyProxy for ${name} does not support callKwargs — Pyodide >= 0.22 required.`,
      );
    }
    try {
      // In Pyodide, callKwargs must receive the kwargs dict as its LAST
      // argument.  All our helpers in bootstrap.py are called with kwargs
      // only, so the kwargs dict is also the only argument.
      const result = fn.callKwargs(kwargs);
      // ``result`` may be: (a) a plain JS value, (b) a JS Promise, or
      // (c) a Pyodide PyProxy of a coroutine (when the bootstrap
      // function is ``async def``).  The latter is "thenable" but is
      // **not** an ``instanceof Promise``, so we must detect it via
      // duck typing on ``.then`` to await it correctly — otherwise we
      // end up running ``toJs`` on the live coroutine proxy, which
      // gets destroyed mid-conversion and throws "Object has already
      // been destroyed".
      const isThenable =
        result != null &&
        (result instanceof Promise ||
          typeof (result as { then?: unknown }).then === "function");
      const awaited = isThenable ? await result : result;
      let value = toJs(awaited) as T;
      if (refusable) {
        const reply = value as { value?: T; refused?: ScientificRefusal };
        if (reply.refused) throw new ScientificRefusalError(reply.refused);
        value = reply.value as T;
      }
      // Notify workspace-mutation listeners *after* the Python side
      // returns successfully — failed mutations don't dirty the
      // workspace. ``silent`` lets panel bootstrap code seed default
      // content without surfacing it as a user edit.
      if (!options.silent && MUTATING_PY_FUNCTIONS.has(name)) {
        this.emitWorkspaceMutation(name);
      }
      return value;
    } catch (err) {
      if (!options.silent) {
        console.error(`[runtime] ${name} failed`, err);
      }
      throw err;
    } finally {
      fn.destroy?.();
    }
  }

  /** Call a Python function declared in bootstrap.py with keyword args.
   *
   *  Serialised through {@link _queue} so the single-threaded Python
   *  side observes a strict request order. In disk mode the call is
   *  wrapped by a page-in/spill guard so referenced objects are made
   *  resident for its duration and dropped again afterwards. */
  private async callPy<T = unknown>(
    name: string,
    kwargs: Record<string, unknown> = {},
    options: { silent?: boolean } = {},
  ): Promise<T> {
    const doCall = () => this.executePyCall<T>(name, kwargs, options);
    const next = this._queue.then(doCall, doCall);
    // Keep the chain alive even if this call rejects.
    this._queue = next.catch(() => undefined);
    return next;
  }

  /**
   * Queue a read for which only the latest request still waiting matters.
   *
   * A request that has already entered Python always finishes. Superseded
   * requests still waiting in {@link _queue} return ``null`` immediately,
   * before disk paging or Python execution. Ordinary {@link callPy} calls are
   * never inspected, skipped, or reordered, so mutations retain their strict
   * serial semantics.
   */
  private async callPyLatest<T = unknown>(
    key: string,
    name: string,
    kwargs: Record<string, unknown> = {},
  ): Promise<T | null> {
    const generation = (this._latestReadGenerations.get(key) ?? 0) + 1;
    this._latestReadGenerations.set(key, generation);
    const doCall = async (): Promise<T | null> => {
      if (this._latestReadGenerations.get(key) !== generation) return null;
      return this.executePyCall<T>(name, kwargs);
    };
    const next = this._queue.then(doCall, doCall);
    this._queue = next.catch(() => undefined);
    return next;
  }

  /** Execute one call after its position in the serial queue is acquired. */
  private async executePyCall<T>(
    name: string,
    kwargs: Record<string, unknown>,
    options: { silent?: boolean } = {},
  ): Promise<T> {
    if (this.storageMode !== "disk") {
      return this.invokePy<T>(name, kwargs, options);
    }
    const pagedIn = await this.diskGuardBefore(name, kwargs);
    let value: T;
    try {
      value = await this.invokePy<T>(name, kwargs, options);
    } catch (err) {
      // Return what we paged in to disk when the call throws, so a failed
      // operation never leaves the WASM heap inflated, and spill what it may
      // have produced before raising (e.g. the results of a first group).
      await this.diskGuardFailsafe(name, pagedIn);
      throw err;
    }
    await this.diskGuardAfter(name, kwargs, pagedIn);
    return value;
  }

  // ------------------------------------------------------------------
  // Disk-mode guard (runs inside the serialised section)
  //
  // What each call pages in, and after which calls the on-disk store is
  // reconciled with the model, is declared in ``pyCallPolicy.ts``.
  // ------------------------------------------------------------------

  private requireStore(): ObjectByteStore {
    if (!this.opfsStore) {
      throw new Error("OPFS store not initialised (storage mode is 'disk')");
    }
    return this.opfsStore;
  }

  /** Page a batch of spilled objects back into the heap.
   *
   *  The OPFS reads run in parallel (I/O bound, independent files);
   *  the ``attach_object_array`` calls stay strictly sequential because
   *  the Python heap is single-threaded.  Returns the ids actually
   *  paged in, so they can be re-spilled afterwards (direct, unqueued). */
  private async pageInBatch(oids: string[]): Promise<string[]> {
    const targets = Array.from(new Set(oids)).filter((oid) =>
      this.spilledOids.has(oid),
    );
    if (targets.length === 0) return [];
    const store = this.requireStore();
    const buffers = await Promise.all(targets.map((oid) => store.get(oid)));
    const pagedIn: string[] = [];
    for (let i = 0; i < targets.length; i += 1) {
      const oid = targets[i];
      await this.invokePy("attach_object_array", {
        oid,
        payload: buffers[i],
      });
      this.spilledOids.delete(oid);
      pagedIn.push(oid);
    }
    return pagedIn;
  }

  /** Spill object *oid* to disk, serialising it afresh (direct, unqueued).
   *
   *  The Python side drops the array when it serialises it: if the bytes
   *  cannot be persisted (quota exceeded, write error...), they are attached
   *  back before the error is propagated, so that the object stays resident
   *  with its data and both registries agree it is not spilled. */
  private async spillDirect(oid: string): Promise<boolean> {
    if (this.spilledOids.has(oid)) return false;
    const bytes = (await this.invokePy("detach_object_array", {
      oid,
    })) as Uint8Array | null;
    if (!bytes || bytes.byteLength === 0) return false;
    await this.persistOrRestore(oid, bytes);
    this.spilledOids.add(oid);
    return true;
  }

  /** Persist the *bytes* just detached from object *oid*, or attach them
   *  back to the object if they cannot be persisted (and rethrow). A copy
   *  left partially written on disk is deleted (best effort): the object is
   *  no longer spilled, so it would never be read anyway. */
  private async persistOrRestore(
    oid: string,
    bytes: Uint8Array,
  ): Promise<void> {
    const store = this.requireStore();
    try {
      await store.put(oid, bytes);
    } catch (err) {
      await this.invokePy("attach_object_array", {
        oid,
        payload: bytes,
        on_disk: false,
      });
      await store.delete(oid).catch(() => undefined);
      throw err;
    }
  }

  /** Return a paged-in object to disk once the call that needed it is over
   *  (direct, unqueued). Its on-disk copy is rewritten only when the call
   *  changed its data (always when *rewrite* is set), and deleted when the
   *  object left the model; otherwise the array is just dropped. */
  private async settleDirect(oid: string, rewrite: boolean): Promise<void> {
    if (rewrite) {
      await this.spillDirect(oid);
      return;
    }
    const settled = await this.invokePy<{
      state: "released" | "rewritten" | "spilled" | "gone";
      payload?: Uint8Array;
    }>("settle_object_array", { oid });
    if (settled.state === "gone") {
      await this.requireStore().delete(oid);
      return;
    }
    if (settled.state === "rewritten") {
      // The changed data is attached back if it cannot replace the on-disk
      // copy: the object then stays resident (see ``persistOrRestore``)
      await this.persistOrRestore(oid, settled.payload as Uint8Array);
    }
    this.spilledOids.add(oid);
  }

  /** Make the objects the call reads resident before the call. Returns
   *  the ids that were actually paged in, so they can be re-spilled. */
  private async diskGuardBefore(
    name: string,
    kwargs: Record<string, unknown>,
  ): Promise<string[]> {
    const plan = pageInPlan(name, kwargs);
    switch (plan.kind) {
      case "none":
        return [];
      case "all":
        return this.pageInBatch(Array.from(this.spilledOids));
      case "resolve":
        return this.pageInBatch(
          await this.invokePy<string[]>(plan.helper, plan.kwargs),
        );
      default:
        return this.pageInBatch(plan.oids);
    }
  }

  /** Return paged-in objects to disk and reconcile the on-disk store with
   *  the model after a call adding, deleting or replacing objects.
   *
   *  Never throws: the call has already succeeded, so a storage failure must
   *  not report it as failed (it would be applied twice if retried). Each step
   *  is attempted even if a previous one failed. An object whose data cannot
   *  be written stays resident with its data (see ``persistOrRestore``), and
   *  a later sweep tries again to store it on disk. Failures are logged, and
   *  reported to the {@link onStorageError} listeners. */
  private async diskGuardAfter(
    name: string,
    kwargs: Record<string, unknown>,
    pagedIn: string[],
  ): Promise<void> {
    let used = false;
    let failure: unknown;
    const attempt = async <R>(
      step: () => Promise<R>,
    ): Promise<R | undefined> => {
      used = true;
      try {
        return await step();
      } catch (err) {
        console.error(`[runtime] on-disk storage after ${name} failed`, err);
        if (failure === undefined) failure = err;
        return undefined;
      }
    };
    const rewrite = MUTATES_HEAVY.has(name);
    for (const oid of pagedIn) {
      await attempt(() => this.settleDirect(oid, rewrite));
    }
    if (REPLACES_MODEL.has(name) && kwargs.replace !== false) {
      // A replaced model forgets the old store at once; an appended file
      // keeps the current objects and their on-disk copies.
      this.spilledOids.clear();
      await attempt(() => this.requireStore().clear());
    }
    const swept =
      DISK_SWEEP_CALLS.has(name) &&
      (await attempt(() => this.diskSweepDirect())) === true;
    // Reclaim heap pages freed by the placeholders so later allocations
    // reuse them instead of growing the heap.
    if (pagedIn.length || swept) {
      await attempt(() => this.invokePy("collect_garbage"));
    }
    if (!used) return;
    if (failure === undefined) {
      this.storageFailing = false;
    } else if (!this.storageFailing) {
      this.storageFailing = true;
      // ``DOMException`` (quota exceeded...) is not an ``Error`` everywhere
      const message = (failure as { message?: unknown } | null)?.message;
      this.emitStorageError(
        typeof message === "string" ? message : String(failure),
      );
    }
  }

  /** Best-effort counterpart of {@link diskGuardAfter} on the error path
   *  (never throws). Objects that a failed call produced before raising stay
   *  in the workspace: they are spilled as on success. */
  private async diskGuardFailsafe(
    name: string,
    pagedIn: string[],
  ): Promise<void> {
    for (const oid of pagedIn) {
      if (this.spilledOids.has(oid)) continue;
      try {
        await this.settleDirect(oid, false);
      } catch {
        // Swallow — we're already on an error path.
      }
    }
    if (DISK_SWEEP_CALLS.has(name)) {
      try {
        await this.diskSweepDirect();
      } catch {
        // Swallow — we're already on an error path.
      }
    }
  }

  /** Reconcile the on-disk store with the model (direct, unqueued): delete
   *  the on-disk copy of every object that left the model or whose data was
   *  replaced (e.g. by a macro), then spill every object left in memory
   *  (created, loaded or replaced). Returns whether anything moved. */
  private async diskSweepDirect(): Promise<boolean> {
    const state = await this.invokePy<{
      spilled: string[];
      resident: string[];
    }>("disk_sweep_state");
    const live = new Set(state.spilled);
    let moved = false;
    for (const oid of Array.from(this.spilledOids)) {
      if (!live.has(oid)) {
        this.spilledOids.delete(oid);
        await this.requireStore().delete(oid);
        moved = true;
      }
    }
    for (const oid of state.resident) {
      if (await this.spillDirect(oid)) moved = true;
    }
    return moved;
  }

  /** Spill every resident object (direct, unqueued). */
  private async spillAllResidentDirect(): Promise<void> {
    const candidates = (await this.invokePy("spillable_objects")) as Array<{
      oid: string;
    }>;
    let any = false;
    for (const c of candidates) {
      if (await this.spillDirect(c.oid)) any = true;
    }
    if (any) await this.invokePy("collect_garbage");
  }

  /** Page every spilled object back in (direct, unqueued). */
  private async pageInAllDirect(): Promise<void> {
    await this.pageInBatch(Array.from(this.spilledOids));
  }

  // ------------------------------------------------------------------
  // On-disk storage mode — public API
  // ------------------------------------------------------------------

  /** Whether the on-disk storage mode can be enabled in this context. */
  static isDiskStorageSupported(): boolean {
    return isDiskStorageSupported();
  }

  /**
   * Instance accessor mirroring {@link DataLabRuntime.isDiskStorageSupported}.
   *
   * Unlike the static, this is part of the {@link RuntimeApi} surface, so it
   * is reachable through the worker-backed façade ({@link WorkerRuntimeProxy})
   * regardless of the active runtime mode — where it reports the capability of
   * the thread actually hosting the store (the worker in ``worker`` mode).
   */
  isDiskStorageSupported(): boolean {
    return DataLabRuntime.isDiskStorageSupported();
  }

  /** Return the active storage mode. */
  getStorageMode(): StorageMode {
    return this.storageMode;
  }

  /**
   * Switch the runtime storage mode.
   *
   * ``"disk"`` spills every resident array to OPFS (keeping only
   * metadata in the heap); ``"ram"`` pages every spilled array back in
   * and clears the on-disk store. Both transitions are queued so they
   * never interleave with in-flight Python calls. No-op when already in
   * the requested mode. A switch to ``"disk"`` that fails (store
   * unavailable, write error) leaves the runtime in ``"ram"`` mode with
   * every array resident (see {@link revertSpillAllDirect}).
   */
  async setStorageMode(mode: StorageMode): Promise<void> {
    if (mode === this.storageMode) return;
    if (mode === "disk" && !OpfsObjectStore.isSupported()) {
      throw new Error(
        "on-disk storage mode is unavailable in this browser/context",
      );
    }
    const run = async (): Promise<void> => {
      if (mode === "disk") {
        if (!this.opfsStore) {
          // Prefer the synchronous-handle store when the runtime runs in a
          // worker (4–7× faster spills, see ``opfs_sync_spike``); fall back
          // to the async ``createWritable`` store on the main thread.
          const store = OpfsSyncObjectStore.isSupported()
            ? new OpfsSyncObjectStore()
            : new OpfsObjectStore();
          // Kept only once initialised, so that a failed initialisation
          // (e.g. storage denied) may be retried by the next switch.
          await store.init();
          this.opfsStore = store;
        }
        try {
          await this.spillAllResidentDirect();
        } catch (err) {
          await this.revertSpillAllDirect();
          throw err;
        }
        this.storageMode = "disk";
        this.storageFailing = false;
      } else {
        await this.pageInAllDirect();
        this.storageMode = "ram";
        if (this.opfsStore) await this.opfsStore.clear();
      }
    };
    const next = this._queue.then(run, run);
    this._queue = next.catch(() => undefined);
    return next as Promise<void>;
  }

  /** Undo a switch to the on-disk mode that could not spill every object
   *  (direct, unqueued): the objects already spilled are paged back in and
   *  the store is emptied, so that the runtime stays in RAM mode. If they
   *  cannot all be read back, the runtime switches to the on-disk mode
   *  anyway: the objects left on disk need it to be paged in. */
  private async revertSpillAllDirect(): Promise<void> {
    try {
      await this.pageInAllDirect();
    } catch (err) {
      console.error("[runtime] cannot page spilled objects back in", err);
      this.storageMode = "disk";
      return;
    }
    await this.opfsStore?.clear().catch(() => undefined);
  }

  /** Total bytes currently spilled to the OPFS store (0 in RAM mode). */
  getDiskStoreBytes(): number {
    return this.opfsStore?.totalBytes() ?? 0;
  }

  /** Number of objects whose array currently lives on disk. */
  getSpilledCount(): number {
    return this.spilledOids.size;
  }

  async createSignal(params: SignalCreationParams): Promise<string> {
    const id = (await this.callPy(
      "create_signal",
      params as unknown as Record<string, unknown>,
    )) as string;
    return id;
  }

  /** Create a signal from raw X / Y arrays (used by the macro proxy
   *  bridge — mirrors :func:`bootstrap.add_signal_from_arrays`). */
  async addSignalFromArrays(params: {
    title: string;
    xdata: number[] | Float32Array | Float64Array;
    ydata: number[] | Float32Array | Float64Array;
    xunit?: string;
    yunit?: string;
    xlabel?: string;
    ylabel?: string;
    group_id?: string | null;
    dtype?: string;
  }): Promise<string> {
    return (await this.callPy(
      "add_signal_from_arrays",
      params as unknown as Record<string, unknown>,
    )) as string;
  }

  /** Create an image from a raw 2D array (mirrors
   *  :func:`bootstrap.add_image_from_array`). */
  async addImageFromArray(params: {
    title: string;
    data: number[][] | Float32Array | Float64Array | Uint8Array;
    xunit?: string;
    yunit?: string;
    zunit?: string;
    xlabel?: string;
    ylabel?: string;
    zlabel?: string;
    group_id?: string | null;
    width?: number;
    height?: number;
    dtype?: string;
  }): Promise<string> {
    return (await this.callPy(
      "add_image_from_array",
      params as unknown as Record<string, unknown>,
    )) as string;
  }

  /** Add an object sent by a macro (base-64 pickle of a ``SignalObj`` /
   *  ``ImageObj``) to the *kind* panel and return its id (mirrors
   *  :func:`bootstrap.add_object_pickled`). */
  async addObjectPickled(
    pickledB64: string,
    kind: PanelKind,
    groupId: string | null = null,
  ): Promise<string> {
    return (await this.callPy("add_object_pickled", {
      pickled_b64: pickledB64,
      kind,
      group_id: groupId,
    })) as string;
  }

  /** Replace the object a macro sent back (base-64 pickle), matched by its
   *  UUID, and return its id (mirrors :func:`bootstrap.set_object_pickled`). */
  async setObjectPickled(pickledB64: string): Promise<string> {
    return (await this.callPy("set_object_pickled", {
      pickled_b64: pickledB64,
    })) as string;
  }

  /** List the supported signal-generation types (mirrors DataLab's
   *  desktop "Create" menu).  Every entry maps to a guidata
   *  ``NewSignalParam`` subclass on the Python side. */
  async listSignalCreationTypes(): Promise<SignalCreationType[]> {
    return (await this.callPy(
      "list_signal_creation_types",
    )) as SignalCreationType[];
  }

  /** Create a signal of the given type with default parameters and
   *  return the new object id.  The originating ``NewSignalParam``
   *  instance is cached so it can be edited via the Creation panel. */
  async createSignalTyped(stype: string, groupId?: string): Promise<string> {
    return (await this.callPy("create_signal_typed", {
      stype,
      group_id: groupId ?? null,
    })) as string;
  }

  /** Return the JSON Schema + values for the cached creation
   *  parameters of *id*, or ``null`` when the object was not created
   *  through ``createSignalTyped``. */
  async getCreationParamSchema(
    id: string,
  ): Promise<(SchemaWithValues & { stype: string }) | null> {
    return (await this.callPy("get_creation_param_schema", {
      oid: id,
    })) as (SchemaWithValues & { stype: string }) | null;
  }

  /** Apply *values* to the cached creation parameters and rebuild the
   *  signal in place. */
  async updateSignalCreationParams(
    id: string,
    values: Record<string, unknown>,
  ): Promise<{ size: number; title: string }> {
    return (await this.callPy("update_signal_creation_params", {
      oid: id,
      values,
    })) as { size: number; title: string };
  }

  /** Return the JSON Schema + values for the underlying object DataSet
   *  itself (used by the "Properties" side panel). */
  async getObjectPropertySchema(id: string): Promise<SchemaWithValues> {
    return (await this.callPy("get_object_property_schema", {
      oid: id,
    })) as SchemaWithValues;
  }

  /** Apply *values* directly to the underlying object DataSet. */
  async setObjectPropertyValues(
    id: string,
    values: Record<string, unknown>,
  ): Promise<void> {
    await this.callPy("set_object_property_values", { oid: id, values });
  }

  /** Read-only stats summary (dtype / shape / min / max / mean / std)
   *  of the underlying object array.  Used by the Properties panel. */
  async getObjectStats(id: string): Promise<ObjectStats> {
    return (await this.callPy("get_object_stats", { oid: id })) as ObjectStats;
  }

  /** Fetch all lightweight Properties-panel data in one bridge crossing. */
  async getPropertiesSnapshot(id: string): Promise<PropertiesSnapshot | null> {
    return (await this.callPyLatest(
      "properties-view",
      "get_properties_snapshot",
      {
        oid: id,
      },
    )) as PropertiesSnapshot | null;
  }

  /** Visible metadata entries of *id* (sorted, internal keys filtered out). */
  async listObjectMetadata(id: string): Promise<MetadataEntry[]> {
    return (await this.callPy("list_object_metadata", {
      oid: id,
    })) as MetadataEntry[];
  }

  /** Add or update a metadata entry on *id*. */
  async setObjectMetadataValue(
    id: string,
    key: string,
    valueType: MetadataValueType,
    value: string,
  ): Promise<void> {
    await this.callPy("set_object_metadata_value", {
      oid: id,
      key,
      value_type: valueType,
      value,
    });
  }

  /** Remove *key* from *id*'s metadata.  Returns ``true`` when the key
   *  was present, ``false`` otherwise. */
  async deleteObjectMetadataKey(id: string, key: string): Promise<boolean> {
    return (await this.callPy("delete_object_metadata_key", {
      oid: id,
      key,
    })) as boolean;
  }

  /** Copy *id*'s metadata into the panel clipboard (mirrors DataLab
   *  desktop's "Copy metadata"). */
  async copyObjectMetadata(id: string): Promise<boolean> {
    return (await this.callPy("copy_object_metadata", {
      oid: id,
    })) as boolean;
  }

  /** Return ``true`` when the metadata clipboard holds a payload that
   *  "Paste metadata" can apply. */
  async hasMetadataInClipboard(): Promise<boolean> {
    return (await this.callPy("has_metadata_in_clipboard")) as boolean;
  }

  /** Paste the clipboard metadata onto every object of *ids* (shows a
   *  parameter dialog).  Returns ``false`` when cancelled or empty. */
  async pasteObjectMetadata(ids: string[]): Promise<boolean> {
    return (await this.callPy("paste_object_metadata", {
      oids: ids,
    })) as boolean;
  }

  /** Add a metadata item to every object of *ids* (shows a parameter
   *  dialog).  Returns ``false`` when cancelled. */
  async addObjectMetadata(ids: string[]): Promise<boolean> {
    return (await this.callPy("add_object_metadata", {
      oids: ids,
    })) as boolean;
  }

  /** Return ``true`` when any object of *ids* carries a region of
   *  interest (used to decide whether to prompt before deleting). */
  async objectsHaveRoi(ids: string[]): Promise<boolean> {
    return (await this.callPy("objects_have_roi", { oids: ids })) as boolean;
  }

  /** Delete all metadata of every object of *ids*.  When *keepRoi* is
   *  ``true`` the regions of interest survive the reset. */
  async deleteObjectMetadata(
    ids: string[],
    keepRoi: boolean,
  ): Promise<boolean> {
    return (await this.callPy("delete_object_metadata", {
      oids: ids,
      keep_roi: keepRoi,
    })) as boolean;
  }

  /** Serialise *id*'s metadata to ``.dlabmeta`` (JSON) bytes for
   *  download. */
  async exportObjectMetadataBytes(id: string): Promise<Uint8Array> {
    const result = (await this.callPy("export_object_metadata_bytes", {
      oid: id,
    })) as Uint8Array | ArrayBuffer | number[];
    if (result instanceof Uint8Array) return result;
    if (result instanceof ArrayBuffer) return new Uint8Array(result);
    return Uint8Array.from(result as number[]);
  }

  /** Replace *id*'s metadata from previously exported ``.dlabmeta``
   *  bytes. */
  async importObjectMetadataBytes(
    id: string,
    bytes: Uint8Array,
  ): Promise<void> {
    await this.callPy("import_object_metadata_bytes", {
      oid: id,
      data: bytes,
    });
  }

  /** Return ``true`` when "Paste ROI" can run for the given panel *kind*
   *  (the clipboard must hold a ROI of the matching signal/image type). */
  async hasRoiInClipboard(kind: "signal" | "image"): Promise<boolean> {
    return (await this.callPy("has_roi_in_clipboard", {
      kind,
    })) as boolean;
  }

  /** Copy *id*'s ROI into the panel clipboard.  Returns ``false`` when the
   *  object has no ROI. */
  async copyObjectRoi(id: string): Promise<boolean> {
    return (await this.callPy("copy_object_roi", { oid: id })) as boolean;
  }

  /** Paste the clipboard ROI onto every object of *ids* (merged with any
   *  existing ROI).  Returns the number of objects updated. */
  async pasteObjectRoi(ids: string[]): Promise<number> {
    return (await this.callPy("paste_object_roi", { oids: ids })) as number;
  }

  /** Serialise *id*'s ROI to ``.dlabroi`` (JSON) bytes for download. */
  async exportObjectRoiBytes(id: string): Promise<Uint8Array> {
    const result = (await this.callPy("export_object_roi_bytes", {
      oid: id,
    })) as Uint8Array | ArrayBuffer | number[];
    if (result instanceof Uint8Array) return result;
    if (result instanceof ArrayBuffer) return new Uint8Array(result);
    return Uint8Array.from(result as number[]);
  }

  /** Merge a previously exported ``.dlabroi`` ROI into object *id*. */
  async importObjectRoiBytes(id: string, bytes: Uint8Array): Promise<void> {
    await this.callPy("import_object_roi_bytes", {
      oid: id,
      data: bytes,
    });
  }

  /** Return an indented text tree of *kind*'s groups and object titles
   *  (mirrors DataLab desktop's "Copy titles to clipboard"). */
  async getPanelTitlesText(kind: "signal" | "image"): Promise<string> {
    return (await this.callPy("get_panel_titles_text", { kind })) as string;
  }

  /** List every signal I/O format supported by Sigima.  Used to drive
   *  the "Open"/"Save" file dialog accept lists. */
  async listSignalIoFormats(): Promise<SignalIoFormats> {
    return (await this.callPy("list_signal_io_formats")) as SignalIoFormats;
  }

  /** Decode *bytes* as a signal file and add the resulting signals to
   *  the model.  Returns the new object ids. */
  async openSignalFromBytes(
    filename: string,
    bytes: Uint8Array,
    groupId?: string,
  ): Promise<string[]> {
    return (await this.callPy("open_signal_from_bytes", {
      filename,
      data: bytes,
      group_id: groupId ?? null,
    })) as string[];
  }

  /** Serialise *id* into the format implied by *filename*'s extension.
   *  Returns a ``Uint8Array`` ready to hand to a browser ``Blob``. */
  async saveSignalToBytes(id: string, filename: string): Promise<Uint8Array> {
    const result = (await this.callPy("save_signal_to_bytes", {
      oid: id,
      filename,
    })) as Uint8Array | ArrayBuffer | number[];
    if (result instanceof Uint8Array) return result;
    if (result instanceof ArrayBuffer) return new Uint8Array(result);
    return Uint8Array.from(result as number[]);
  }

  /** Image-side counterpart of :meth:`listSignalIoFormats`. */
  async listImageIoFormats(): Promise<ImageIoFormats> {
    return (await this.callPy("list_image_io_formats")) as ImageIoFormats;
  }

  /** Image-side counterpart of :meth:`openSignalFromBytes`. */
  async openImageFromBytes(
    filename: string,
    bytes: Uint8Array,
    groupId?: string,
  ): Promise<string[]> {
    return (await this.callPy("open_image_from_bytes", {
      filename,
      data: bytes,
      group_id: groupId ?? null,
    })) as string[];
  }

  /** Image-side counterpart of :meth:`saveSignalToBytes`. */
  async saveImageToBytes(id: string, filename: string): Promise<Uint8Array> {
    const result = (await this.callPy("save_image_to_bytes", {
      oid: id,
      filename,
    })) as Uint8Array | ArrayBuffer | number[];
    if (result instanceof Uint8Array) return result;
    if (result instanceof ArrayBuffer) return new Uint8Array(result);
    return Uint8Array.from(result as number[]);
  }

  /** Open every file from a single directory in one Python round-trip.
   *
   *  Mirrors the per-subfolder branch of DataLab desktop's
   *  ``BaseDataPanel.load_from_directory``: individual read failures are
   *  swallowed (parity with ``ignore_errors=True``) and the group is
   *  created only if at least one object was successfully read.
   */
  async openFromDirectoryChunk(
    kind: "signal" | "image",
    groupName: string,
    files: Array<{ name: string; data: Uint8Array }>,
  ): Promise<{ gid?: string; oids: string[]; errors: number }> {
    // ``gid`` is absent (``undefined``) when no object was successfully
    // read — Pyodide converts Python ``None`` to JS ``undefined``.
    return (await this.callPy("open_from_directory_chunk", {
      kind,
      group_name: groupName,
      files,
    })) as { gid?: string; oids: string[]; errors: number };
  }

  /** Build basenames for *oids* using DataLab's filename pattern syntax
   *  (``{title}``, ``{index}``, ``{count}``, axis placeholders, …).
   *  Mirrors the desktop "Save to directory…" preview helper. */
  async formatSignalBasenames(
    oids: string[],
    pattern: string,
  ): Promise<string[]> {
    return (await this.callPy("format_signal_basenames", {
      oids,
      fmt: pattern,
    })) as string[];
  }

  /** List every entry of the signal "Analysis" menu (DataLab parity). */
  async listSignalAnalysis(): Promise<SignalAnalysisDescriptor[]> {
    return (await this.callPy(
      "list_signal_analysis",
    )) as SignalAnalysisDescriptor[];
  }

  /** Return the parameter schema (with cached values pre-filled) for the
   *  given analysis function, or ``null`` for parameter-less analyses. */
  async getSignalAnalysisParamSchema(
    id: string,
    funcId: string,
  ): Promise<unknown | null> {
    const schema = await this.callPy("get_signal_analysis_param_schema", {
      oid: id,
      func_id: funcId,
    });
    return schema ?? null;
  }

  /** Run analysis *funcId* on signal *id* and persist the result on the
   *  signal's metadata.  Returns ``null`` when the function legitimately
   *  produced no result (e.g. FWHM on a flat curve). */
  async runSignalAnalysis(
    id: string,
    funcId: string,
    params?: Record<string, unknown> | null,
  ): Promise<AnalysisResult | null> {
    const out = await this.callPy("run_signal_analysis", {
      oid: id,
      func_id: funcId,
      params: params ?? null,
    });
    return (out ?? null) as AnalysisResult | null;
  }

  /** Return every analysis result currently attached to signal *id*. */
  async listSignalResults(id: string): Promise<AnalysisResult[]> {
    return (await this.callPy("list_signal_results", {
      oid: id,
    })) as AnalysisResult[];
  }

  /** Drop one (or all) analysis result(s) from signal *id*'s metadata. */
  async clearSignalResults(id: string, metadataKey?: string): Promise<number> {
    return (await this.callPy("clear_signal_results", {
      oid: id,
      metadata_key: metadataKey ?? null,
    })) as number;
  }

  /** Describe the plottable analysis-result categories shared by *ids*
   *  (mirrors DataLab desktop's "Analysis ▸ Plot results").  Returns an
   *  empty list when the selection carries no plottable result. */
  async getPlotResultsSchemas(
    ids: string[],
  ): Promise<PlotResultsSchemaEntry[]> {
    return (await this.callPy("get_plot_results_schemas", {
      oids: ids,
    })) as PlotResultsSchemaEntry[];
  }

  /** Aggregate analysis results of *category* across *ids* into new result
   *  signals (placed in a get-or-create signal group *groupName*) and
   *  return the ids of the created signals. */
  async plotResults(params: {
    ids: string[];
    category: string;
    kind: string;
    xaxis: string;
    yaxis: string;
    groupName: string;
  }): Promise<string[]> {
    return (await this.callPy("plot_results", {
      oids: params.ids,
      category: params.category,
      kind: params.kind,
      xaxis: params.xaxis,
      yaxis: params.yaxis,
      group_name: params.groupName,
    })) as string[];
  }

  async listSignals(): Promise<SignalMeta[]> {
    return (await this.callPy("list_signals")) as SignalMeta[];
  }

  /** Flat ``{id, title}`` list of every stored image. */
  async listImages(): Promise<{ id: string; title: string }[]> {
    return (await this.callPy("list_images")) as {
      id: string;
      title: string;
    }[];
  }

  /** Minimal ``{id, kind, title}`` descriptor for a single object. */
  async getObject(
    id: string,
  ): Promise<{ id: string; kind: PanelKind; title: string }> {
    return (await this.callPy("get_object", { oid: id })) as {
      id: string;
      kind: PanelKind;
      title: string;
    };
  }

  /** Ids of every object hosted by *panel* (``"signal"`` or ``"image"``). */
  async getObjectUuids(panel: string): Promise<string[]> {
    return (await this.callPy("get_object_uuids", { panel })) as string[];
  }

  /** Compute a private 1-to-1 result without publishing it to the workspace. */
  async previewFeature(
    featureId: string,
    sourceId: string,
    params: Record<string, unknown>,
    previewToken: string | null = null,
  ): Promise<ProcessingPreviewResult> {
    const result = (await this.callPy("preview_feature", {
      feature_id: featureId,
      source_id: sourceId,
      params,
      preview_token: previewToken,
    })) as
      | {
          kind: "signal";
          data: SignalData & {
            encoding?: string;
            x_bytes?: ArrayBufferView | ArrayBuffer;
            y_bytes?: ArrayBufferView | ArrayBuffer;
          };
        }
      | {
          kind: "image";
          data: ImageData & { encoding?: string; data: unknown };
        };
    if (result.kind === "signal") {
      return { kind: "signal", data: decodeSignalPayload(result.data) };
    }
    return {
      kind: "image",
      data: decodeImagePayload(result.data) as ImageData,
    };
  }

  /** Release an unpublished result that was not handed to ``applyFeature``. */
  async releasePreviewResult(previewToken: string): Promise<void> {
    await this.callPy("release_preview_result", {
      preview_token: previewToken,
    });
  }

  async getSignalData(id: string): Promise<SignalData> {
    const raw = (await this.callPy("get_signal_xy", {
      oid: id,
      encoding: "bytes",
    })) as SignalData & { encoding?: string };
    return decodeSignalPayload(raw);
  }

  /** Return at most ``head + tail`` rows without transferring the full signal. */
  async getSignalDataPreview(
    id: string,
    head = 5,
    tail = 5,
  ): Promise<SignalDataPreview> {
    return (await this.callPy("get_signal_data_preview", {
      oid: id,
      head,
      tail,
    })) as SignalDataPreview;
  }

  /** Overwrite the X / Y arrays of signal *id* with edited values
   *  (used by the Properties > Data array editor). */
  async setSignalData(id: string, x: number[], y: number[]): Promise<void> {
    await this.callPy("set_signal_xydata", { oid: id, x, y });
  }

  /** Binary variant of :meth:`getSignalData` — used by the remote
   *  bridge to ship large signals across the iframe boundary as a
   *  pair of ``Uint8Array`` (raw float64 little-endian) instead of
   *  serialising every sample as a JSON number. */
  async getSignalDataBinary(id: string): Promise<unknown> {
    return await this.callPy("get_signal_xy", {
      oid: id,
      encoding: "bytes",
    });
  }

  /** Batched fetch for multi-signal overlay.  Returns one entry per
   *  resolved id (unknown ids are silently skipped server-side). */
  async getSignalsData(ids: string[]): Promise<SignalData[]> {
    if (ids.length === 0) return [];
    const raw = (await this.callPy("get_signals_xy", {
      oids: ids,
      encoding: "bytes",
    })) as Array<SignalData & { encoding?: string }>;
    return raw.map(decodeSignalPayload);
  }

  /** Fetch and atomically decode every payload for the selected signal view. */
  async getSignalViewSnapshot(
    currentId: string,
    selectedIds: string[],
  ): Promise<SignalViewSnapshot | null> {
    const raw = (await this.callPyLatest(
      "selection-view",
      "get_signal_view_snapshot",
      {
        current_oid: currentId,
        selected_oids: selectedIds,
        encoding: "bytes",
      },
    )) as
      | (Omit<SignalViewSnapshot, "current" | "extras" | "extra_results"> & {
          current: SignalData & { encoding?: string };
          extras: Array<SignalData & { encoding?: string }>;
          extra_results: Array<{
            signal_id: string;
            results: AnalysisResult[];
          }>;
        })
      | null;
    if (raw === null) return null;
    return {
      ...raw,
      current: decodeSignalPayload(raw.current),
      extras: raw.extras.map(decodeSignalPayload),
      extra_results: raw.extra_results.map((bundle) => ({
        signalId: bundle.signal_id,
        results: bundle.results,
      })),
    };
  }

  /** Persist per-curve render style on a signal.  Each field follows
   *  the "``null`` clears the override" rule honoured by
   *  :func:`bootstrap.set_signal_style`; pass an explicit value to
   *  override.  Omitted fields default to ``null`` (clear). */
  async setSignalStyle(
    oid: string,
    style: Partial<SignalStyle>,
  ): Promise<void> {
    await this.callPy("set_signal_style", {
      oid,
      color: style.color ?? null,
      linestyle: style.linestyle ?? null,
      linewidth: style.linewidth ?? null,
      curvestyle: style.curvestyle ?? null,
    });
  }

  // ------------------------------------------------------------------
  // Object model (groups + objects per panel kind)
  // ------------------------------------------------------------------

  async getPanelTree(kind: PanelKind = "signal"): Promise<PanelTree> {
    return (await this.callPy("get_panel_tree", { kind })) as PanelTree;
  }

  async createGroup(
    kind: PanelKind = "signal",
    name?: string,
  ): Promise<string> {
    return (await this.callPy("create_group", {
      kind,
      name: name ?? null,
    })) as string;
  }

  async renameGroup(
    gid: string,
    name: string,
    kind: PanelKind = "signal",
  ): Promise<void> {
    await this.callPy("rename_group", { gid, name, kind });
  }

  async deleteGroup(gid: string, kind: PanelKind = "signal"): Promise<void> {
    await this.callPy("delete_group", { gid, kind });
  }

  async renameObject(oid: string, name: string): Promise<void> {
    await this.callPy("rename_object", { oid, name });
  }

  async moveObject(
    oid: string,
    targetGroupId: string,
    targetIndex = -1,
  ): Promise<void> {
    await this.callPy("move_object", {
      oid,
      target_group_id: targetGroupId,
      target_index: targetIndex,
    });
  }

  async moveObjects(
    oids: string[],
    targetGroupId: string,
    targetIndex = -1,
  ): Promise<void> {
    await this.callPy("move_objects", {
      oids,
      target_group_id: targetGroupId,
      target_index: targetIndex,
    });
  }

  async moveObjectInGroup(oid: string, delta: number): Promise<void> {
    await this.callPy("move_object_in_group", { oid, delta });
  }

  async duplicateObject(oid: string): Promise<string> {
    return (await this.callPy("duplicate_object", { oid })) as string;
  }

  async deleteObject(oid: string): Promise<void> {
    await this.callPy("delete_object", { oid });
  }

  /**
   * Delete every object and group of *kind*'s panel, keeping a single
   * empty default group. Equivalent of DataLab desktop's "Delete all
   * groups and objects".
   */
  async deleteAllObjects(kind: PanelKind = "signal"): Promise<void> {
    await this.callPy("delete_all_objects", { kind });
  }

  /**
   * Wipe every signal/image/macro/notebook from the in-Pyodide model.
   *
   * Used by the E2E worker-scoped fixture that reuses a single Pyodide
   * instance across multiple tests; production UI never calls this.
   */
  async resetAll(): Promise<void> {
    await this.callPy("reset_all");
  }

  // ------------------------------------------------------------------
  // Metadata & annotations (Phase 4)
  // ------------------------------------------------------------------

  async getObjectMeta(oid: string): Promise<ObjectMeta> {
    return (await this.callPy("get_object_meta", { oid })) as ObjectMeta;
  }

  async setObjectMeta(oid: string, fields: Partial<ObjectMeta>): Promise<void> {
    await this.callPy("set_object_meta", { oid, fields });
  }

  async getPlotlyAnnotations(oid: string): Promise<PlotlyAnnotations> {
    return (await this.callPy("get_plotly_annotations", {
      oid,
    })) as PlotlyAnnotations;
  }

  async setPlotlyAnnotations(
    oid: string,
    payload: PlotlyAnnotations,
  ): Promise<void> {
    await this.callPy("set_plotly_annotations", { oid, payload });
  }

  /** Persisted LUT range ``[zmin, zmax]`` for an image, or ``null`` when
   *  no override has been stored (in which case the UI falls back to the
   *  image's intrinsic ``data_min``/``data_max``). */
  async getLutRange(oid: string): Promise<[number, number] | null> {
    const result = (await this.callPy("get_lut_range", { oid })) as
      [number, number] | null;
    if (!result || result.length !== 2) return null;
    return [Number(result[0]), Number(result[1])];
  }

  /** Persist an LUT range ``[zmin, zmax]`` override. Pass ``null`` to
   *  clear it (returns to the intrinsic data range). */
  async setLutRange(
    oid: string,
    payload: [number, number] | null,
  ): Promise<void> {
    await this.callPy("set_lut_range", { oid, payload });
  }

  /** Persist the colormap (Plotly named colorscale + invert flag) on
   *  image *oid*.  Pass ``name=null`` to clear the override and let the
   *  viewer fall back to its built-in default. */
  async setColormap(
    oid: string,
    name: string | null,
    inverted = false,
  ): Promise<void> {
    await this.callPy("set_colormap", { oid, name, inverted });
  }

  /** Persist the display resampling method (``"nearest"`` | ``"max"`` |
   *  ``"mean"``) on image *oid*.  Pass ``null`` to clear the override.
   *  Only affects the downsampled display bitmap, never profiles or
   *  statistics. */
  async setResampleMethod(oid: string, method: string | null): Promise<void> {
    await this.callPy("set_resample_method", { oid, method });
  }

  // ------------------------------------------------------------------
  // Signal ROI (Phase 5)
  // ------------------------------------------------------------------

  async getSignalRoi(oid: string): Promise<SignalRoiSegment[]> {
    return (await this.callPy("get_signal_roi", { oid })) as SignalRoiSegment[];
  }

  async setSignalRoi(oid: string, segments: SignalRoiSegment[]): Promise<void> {
    await this.callPy("set_signal_roi", { oid, segments });
  }

  async deleteSignalRoiAt(oid: string, index: number): Promise<void> {
    await this.callPy("delete_signal_roi_at", { oid, index });
  }

  async extractSignalRois(
    oids: string | string[],
    merged: boolean,
  ): Promise<string[]> {
    return (await this.callPy("extract_signal_rois", {
      oids,
      merged,
    })) as string[];
  }

  // ------------------------------------------------------------------
  // Workspace HDF5 + CSV I/O
  // ------------------------------------------------------------------

  /** Serialise the full object model to a DataLab-compatible HDF5 file.
   *  The returned bytes are ready to wrap in a ``Blob`` for download and
   *  round-trip through Qt DataLab's "Open HDF5 workspace" feature. */
  async saveWorkspaceHdf5(): Promise<Uint8Array> {
    const result = (await this.callPy("save_workspace_to_bytes")) as
      Uint8Array | ArrayBuffer | number[];
    if (result instanceof Uint8Array) return result;
    if (result instanceof ArrayBuffer) return new Uint8Array(result);
    return Uint8Array.from(result as number[]);
  }

  /** Load *bytes* (a DataLab-compatible HDF5 workspace) into the model.
   *  When *replace* is true (default), the current model is wiped first.
   *
   *  Pass ``silent: true`` when the caller probes whether a file is a
   *  workspace and intends to fall back to plain HDF5 import; in that
   *  case the expected ``Not a DataLab HDF5 workspace`` Python error
   *  should not be logged as a runtime error. */
  async openWorkspaceHdf5(
    filename: string,
    bytes: Uint8Array,
    replace: boolean = true,
    options: { silent?: boolean } = {},
  ): Promise<WorkspaceLoadResult> {
    return (await this.callPy(
      "open_workspace_from_bytes",
      {
        filename,
        data: bytes,
        replace,
      },
      { silent: options.silent },
    )) as WorkspaceLoadResult;
  }

  /** Return true if *bytes* (an HDF5 workspace) hold a provenance block, so
   *  that a caller about to append the file can warn that its provenance
   *  will not be imported. Nothing is loaded. */
  async workspaceHasProvenance(bytes: Uint8Array): Promise<boolean> {
    return Boolean(
      await this.callPy("workspace_has_provenance", { data: bytes }),
    );
  }

  /** Return a workspace capsule (``.dlcapsule``): the HDF5 workspace and an
   *  RO-Crate manifest of its provenance.  Requires DataLab-Capsule.
   *  ``revisionOf`` names the parent revision (its manifest fingerprint). */
  async exportWorkspaceCapsule(
    name: string | null = null,
    options: CapsuleExportOptions = {},
  ): Promise<Uint8Array> {
    return asBytes(
      await this.callPy("export_workspace_capsule", {
        name,
        description: options.description ?? null,
        revision_of: options.revisionOf ?? null,
        attachments: options.attachments ?? [],
      }),
    );
  }

  /** Return a capsule that references its workspace at ``workspaceRef`` (an
   *  absolute IRI), and that workspace: the user publishes it there.  The
   *  capsule records its SHA-256 and size. */
  async exportReferencedCapsule(
    workspaceRef: string,
    name: string | null = null,
    options: CapsuleExportOptions = {},
  ): Promise<{ capsule: Uint8Array; workspace: Uint8Array }> {
    const result = (await this.callPy("export_referenced_capsule", {
      workspace_ref: workspaceRef,
      name,
      description: options.description ?? null,
      revision_of: options.revisionOf ?? null,
      attachments: options.attachments ?? [],
    })) as { capsule: unknown; workspace: unknown };
    return {
      capsule: asBytes(result.capsule),
      workspace: asBytes(result.workspace),
    };
  }

  /** Refuse a capsule over the runtime's size limit, before reading it.
   *  The same limit applies to the workspace a capsule references
   *  (``workspace``): the Python size policy of the browser uses it for
   *  the archive and for the workspace. */
  private async checkCapsuleSize(
    size: number,
    part: "capsule" | "workspace" = "capsule",
  ): Promise<void> {
    const limit = await this.getCapsuleSizeLimit();
    if (limit !== null && size > limit) {
      // Round the size up and the limit down so they never look equal.
      const mib = (bytes: number, round: (x: number) => number) =>
        (round((bytes / 1024 ** 2) * 10) / 10).toFixed(1);
      const values = {
        size: mib(size, Math.ceil),
        limit: mib(limit, Math.floor),
      };
      throw new Error(
        part === "capsule"
          ? t("Capsule too large: {size} MiB (limit: {limit} MiB)", values)
          : t(
              "Referenced workspace too large: {size} MiB (limit: {limit} MiB)",
              values,
            ),
      );
    }
  }

  /** Check the sizes of a capsule and of the workspace it references, if
   *  supplied, before either is read or transferred. */
  private async checkCapsuleSizes(
    data: Blob | Uint8Array,
    workspace: Blob | Uint8Array | null,
  ): Promise<void> {
    const size = (bytes: Blob | Uint8Array) =>
      bytes instanceof Uint8Array ? bytes.byteLength : bytes.size;
    await this.checkCapsuleSize(size(data));
    if (workspace !== null) {
      await this.checkCapsuleSize(size(workspace), "workspace");
    }
  }

  /** Largest capsule size (bytes) the runtime opens, or null without
   *  DataLab-Capsule.  Fixed for a runtime, so read once. */
  async getCapsuleSizeLimit(): Promise<number | null> {
    if (this.capsuleSizeLimit === undefined) {
      this.capsuleSizeLimit = (await this.callPy("get_capsule_size_limit")) as
        number | null;
    }
    return this.capsuleSizeLimit;
  }

  /** Validate a workspace capsule, then open its workspace (replacing the
   *  current one by default).  Pass the selected ``File`` (a ``Blob``): its
   *  size is checked before its contents are read or transferred.  When the
   *  capsule references its workspace, pass the file the user selected as
   *  ``workspace``: it must match the manifest, and its size is checked
   *  first too. */
  async openWorkspaceCapsule(
    filename: string,
    data: Blob | Uint8Array,
    replace: boolean = true,
    workspace: Blob | Uint8Array | null = null,
  ): Promise<WorkspaceLoadResult> {
    await this.checkCapsuleSizes(data, workspace);
    return (await this.callPy("open_workspace_capsule", {
      filename,
      data: await readBytes(data),
      replace,
      workspace: workspace === null ? null : await readBytes(workspace),
    })) as WorkspaceLoadResult;
  }

  /** Inspect a capsule without opening it; nothing is computed.  The result
   *  keeps apart the integrity of the capsule and the checks of the reports
   *  and reviews supplied with it (JSON texts); neither is a replay. */
  async inspectWorkspaceCapsule(
    data: Blob | Uint8Array,
    options: {
      workspace?: Blob | Uint8Array | null;
      reports?: string[];
      reviews?: string[];
    } = {},
  ): Promise<CapsuleInspection> {
    const workspace = options.workspace ?? null;
    await this.checkCapsuleSizes(data, workspace);
    return restoreJsonNulls(
      await this.callPy("inspect_workspace_capsule", {
        data: await readBytes(data),
        workspace: workspace === null ? null : await readBytes(workspace),
        reports: options.reports ?? [],
        reviews: options.reviews ?? [],
      }),
    ) as CapsuleInspection;
  }

  /** Check a manifest and reviews retrieved from a registry (JSON texts):
   *  the manifest must be valid and have the requested fingerprint; each
   *  review is reported ``valid`` or with the reason it is not. */
  async checkRegistryRevision(
    manifest: string,
    fingerprint: string,
    reviews: string[] = [],
  ): Promise<{
    summary: CapsuleSummary;
    manifest: Record<string, unknown>;
    reviews: { review: CapsuleReview | null; status: string }[];
  }> {
    return restoreJsonNulls(
      await this.callPy("check_registry_revision", {
        manifest,
        fingerprint,
        reviews,
      }),
    ) as {
      summary: CapsuleSummary;
      manifest: Record<string, unknown>;
      reviews: { review: CapsuleReview | null; status: string }[];
    };
  }

  /** Return the bytes of one capsule attachment, checked against the
   *  manifest, for an explicit download.  The attachment is never opened.
   *  The capsule bytes are moved to the runtime (pass a copy to keep them). */
  async getCapsuleAttachment(
    data: Blob | Uint8Array,
    name: string,
  ): Promise<Uint8Array> {
    await this.checkCapsuleSize(
      data instanceof Uint8Array ? data.byteLength : data.size,
    );
    return asBytes(
      await this.callPy("get_capsule_attachment", {
        data: await readBytes(data),
        name,
      }),
    );
  }

  /** Compare two capsule manifests (scientific, presentation, environment). */
  async diffCapsuleManifests(
    oldManifest: Record<string, unknown>,
    newManifest: Record<string, unknown>,
  ): Promise<CapsuleDiff> {
    return restoreJsonNulls(
      await this.callPy("diff_capsule_manifests", {
        old: oldManifest,
        new: newManifest,
      }),
    ) as CapsuleDiff;
  }

  /** Write a review of one capsule revision: a separate JSON document that
   *  never changes the capsule. */
  async createCapsuleReview(
    manifest: Record<string, unknown>,
    reviewer: string,
    statement: string,
    verdict: CapsuleReviewVerdict | null,
    reports: ProvenanceReport[] = [],
  ): Promise<CapsuleReview> {
    return restoreJsonNulls(
      await this.callPy("create_capsule_review", {
        manifest,
        reviewer,
        statement,
        verdict,
        reports,
      }),
    ) as CapsuleReview;
  }

  /** Prepare typed bindings and parameters for one active plugin recipe. */
  async preparePluginRecipe(
    pluginId: string,
    recipeId: string,
    candidateIds: string[],
    parameterValues: Record<string, unknown> = {},
  ): Promise<PluginRecipePreparation> {
    return (await this.callPy("prepare_plugin_recipe", {
      plugin_id: pluginId,
      recipe_id: recipeId,
      candidate_ids: candidateIds,
      parameter_values: parameterValues,
    })) as PluginRecipePreparation;
  }

  /** Assess whether each recipe of a plugin can run on candidate objects. */
  async assessPluginRecipes(
    pluginId: string,
    candidateIds: string[],
    parameterValues: Record<string, Record<string, unknown>> = {},
  ): Promise<Record<string, PluginRecipeAssessment>> {
    return (await this.callPy("assess_plugin_recipes", {
      plugin_id: pluginId,
      candidate_ids: candidateIds,
      parameter_values: parameterValues,
    })) as Record<string, PluginRecipeAssessment>;
  }

  /** Assess bindings edited by the user, without running the recipe. */
  async checkPluginRecipeBindings(
    pluginId: string,
    recipeId: string,
    bindings: Record<string, string[]>,
    parameterValues: Record<string, unknown> = {},
  ): Promise<PluginRecipeReadiness> {
    return (await this.callPy("check_plugin_recipe_bindings", {
      plugin_id: pluginId,
      recipe_id: recipeId,
      bindings,
      parameter_values: parameterValues,
    })) as PluginRecipeReadiness;
  }

  /** Return the live guidata parameter schema for one plugin recipe. */
  async getPluginRecipeSchema(
    pluginId: string,
    recipeId: string,
  ): Promise<SchemaWithValues | null> {
    return (await this.callPy("get_plugin_recipe_schema", {
      plugin_id: pluginId,
      recipe_id: recipeId,
    })) as SchemaWithValues | null;
  }

  /** Resolve conditional parameter visibility for one plugin recipe. */
  async resolvePluginRecipeActive(
    pluginId: string,
    recipeId: string,
    values: Record<string, unknown>,
  ): Promise<Record<string, boolean>> {
    return (await this.callPy("resolve_plugin_recipe_active", {
      plugin_id: pluginId,
      recipe_id: recipeId,
      values,
    })) as Record<string, boolean>;
  }

  /** Resolve one dynamic choice list for recipe parameters. */
  async resolvePluginRecipeChoices(
    pluginId: string,
    recipeId: string,
    itemName: string,
    values: Record<string, unknown>,
  ): Promise<DynamicChoice[]> {
    return (await this.callPy("resolve_plugin_recipe_choices", {
      plugin_id: pluginId,
      recipe_id: recipeId,
      item_name: itemName,
      values,
    })) as DynamicChoice[];
  }

  /** Run one guidata display callback for recipe parameters. */
  async resolvePluginRecipeCallbacks(
    pluginId: string,
    recipeId: string,
    itemName: string,
    values: Record<string, unknown>,
  ): Promise<Record<string, unknown>> {
    return (await this.callPy("resolve_plugin_recipe_callbacks", {
      plugin_id: pluginId,
      recipe_id: recipeId,
      item_name: itemName,
      values,
    })) as Record<string, unknown>;
  }

  /** Execute and transactionally commit one active plugin recipe. */
  async runPluginRecipe(
    pluginId: string,
    recipeId: string,
    bindings: Record<string, string[]>,
    parameterValues: Record<string, unknown> = {},
  ): Promise<PluginRecipeCommit> {
    return (await this.callPy("run_plugin_recipe", {
      plugin_id: pluginId,
      recipe_id: recipeId,
      bindings,
      parameter_values: parameterValues,
    })) as PluginRecipeCommit;
  }

  /** Open one packaged or generated example from an active plugin. */
  async openPluginExample(
    pluginId: string,
    exampleId: string,
    replace: boolean = true,
    recipeId: string | null = null,
  ): Promise<PluginExampleOpenResult> {
    return (await this.callPy("open_plugin_example", {
      plugin_id: pluginId,
      example_id: exampleId,
      replace,
      recipe_id: recipeId,
    })) as PluginExampleOpenResult;
  }

  /** Run the launcher of a plugin tool on the selected objects.
   *
   *  Returns the IDs of the objects the tool added, per panel. */
  async launchPluginTool(
    pluginId: string,
    toolId: string,
    selectedIds: string[],
  ): Promise<{ signal: string[]; image: string[] }> {
    return (await this.callPy("launch_plugin_tool", {
      plugin_id: pluginId,
      tool_id: toolId,
      selected_ids: selectedIds,
    })) as { signal: string[]; image: string[] };
  }

  /** Return the title, settings and live period of a plugin instrument. */
  async openPluginInstrument(
    pluginId: string,
    toolId: string,
  ): Promise<PluginInstrumentSession> {
    return (await this.callPy("open_plugin_instrument", {
      plugin_id: pluginId,
      tool_id: toolId,
    })) as PluginInstrumentSession;
  }

  /** Return a live frame of a plugin instrument for edited settings. */
  async previewPluginInstrument(
    pluginId: string,
    toolId: string,
    values: Record<string, unknown>,
  ): Promise<PluginInstrumentFrame> {
    const raw = (await this.callPy("preview_plugin_instrument", {
      plugin_id: pluginId,
      tool_id: toolId,
      values,
    })) as {
      kind: "signals" | "image";
      items: Array<Record<string, unknown>>;
      summary: string;
      value_range: [number, number] | null;
    };
    const common = { summary: raw.summary, value_range: raw.value_range };
    if (raw.kind === "image") {
      return {
        ...common,
        kind: "image",
        items: raw.items.map(
          (item) =>
            decodeImagePayload(
              item as unknown as ImageData & { encoding?: string },
            ) as ImageData,
        ),
      };
    }
    return {
      ...common,
      kind: "signals",
      items: raw.items.map((item) =>
        decodeSignalPayload(
          item as unknown as SignalData & { encoding?: string },
        ),
      ),
    };
  }

  /** Add an acquisition of a plugin instrument to the workspace: to the
   *  current group *currentGroupId* when *newGroup* is false and this group
   *  belongs to the panel of the acquired objects, otherwise to a new group. */
  async acquirePluginInstrument(
    pluginId: string,
    toolId: string,
    values: Record<string, unknown>,
    newGroup = true,
    currentGroupId: string | null = null,
  ): Promise<PluginInstrumentAcquisition> {
    return (await this.callPy("acquire_plugin_instrument", {
      plugin_id: pluginId,
      tool_id: toolId,
      values,
      new_group: newGroup,
      current_group_id: currentGroupId,
    })) as PluginInstrumentAcquisition;
  }

  /** Resolve which instrument settings are active for edited values. */
  async resolvePluginInstrumentActive(
    pluginId: string,
    toolId: string,
    values: Record<string, unknown>,
  ): Promise<Record<string, boolean>> {
    return (await this.callPy("resolve_plugin_instrument_active", {
      plugin_id: pluginId,
      tool_id: toolId,
      values,
    })) as Record<string, boolean>;
  }

  // ------------------------------------------------------------------
  // Foreign HDF5 browser (Phase 2)
  // ------------------------------------------------------------------

  /** Open *bytes* as an HDF5 file in the browser dialog.  The returned
   *  ``file_id`` must later be passed to ``closeH5Browser`` to free the
   *  underlying ``h5py.File`` handle and temp file. */
  async openH5Browser(
    filename: string,
    bytes: Uint8Array,
  ): Promise<H5BrowserFile> {
    return (await this.callPy("h5_browser_open", {
      filename,
      data: bytes,
    })) as H5BrowserFile;
  }

  /** Close one open HDF5 browser file. */
  async closeH5Browser(fileId: string): Promise<void> {
    await this.callPy("h5_browser_close", { file_id: fileId });
  }

  /** Close every open HDF5 browser file (use on dialog dismissal). */
  async closeAllH5Browsers(): Promise<void> {
    await this.callPy("h5_browser_close_all");
  }

  async getH5BrowserNodeAttrs(
    fileId: string,
    nodeId: string,
  ): Promise<H5BrowserNodeAttrs> {
    return (await this.callPy("h5_browser_node_attrs", {
      file_id: fileId,
      node_id: nodeId,
    })) as H5BrowserNodeAttrs;
  }

  async getH5BrowserPreview(
    fileId: string,
    nodeId: string,
  ): Promise<H5BrowserPreview> {
    return (await this.callPy("h5_browser_preview", {
      file_id: fileId,
      node_id: nodeId,
    })) as H5BrowserPreview;
  }

  async getH5BrowserArray(
    fileId: string,
    nodeId: string,
  ): Promise<H5BrowserArray> {
    return (await this.callPy("h5_browser_array", {
      file_id: fileId,
      node_id: nodeId,
    })) as H5BrowserArray;
  }

  async importH5BrowserNodes(
    fileId: string,
    nodeIds: string[],
    groupId?: string | null,
  ): Promise<H5BrowserImportResult> {
    return (await this.callPy("h5_browser_import", {
      file_id: fileId,
      node_ids: nodeIds,
      group_id: groupId ?? null,
    })) as H5BrowserImportResult;
  }

  async exportSignalCsv(oid: string, separator: string = ","): Promise<string> {
    return (await this.callPy("export_signal_csv", {
      oid,
      separator,
    })) as string;
  }

  async importSignalCsv(
    content: string,
    title: string | null = null,
    separator: string = ",",
  ): Promise<string> {
    return (await this.callPy("import_signal_csv", {
      content,
      title,
      separator,
    })) as string;
  }

  // ------------------------------------------------------------------
  // Text Import Wizard (mirrors datalab.widgets.textimport)
  // ------------------------------------------------------------------

  async parseTextImport(
    content: string,
    params: TextImportParams,
    previewRows: number = 200,
  ): Promise<TextImportPreview> {
    return (await this.callPy("parse_text_import", {
      content,
      preview_rows: previewRows,
      ...textImportToPyKwargs(params),
    })) as TextImportPreview;
  }

  async buildTextImportSignals(
    content: string,
    params: TextImportParams,
  ): Promise<TextImportSignals> {
    return (await this.callPy("build_text_import_signals", {
      content,
      ...textImportToPyKwargs(params),
    })) as TextImportSignals;
  }

  async commitTextImport(
    content: string,
    params: TextImportParams,
    selection: TextImportCommitOptions,
  ): Promise<string[]> {
    return (await this.callPy("commit_text_import", {
      content,
      ...textImportToPyKwargs(params),
      selected_indices: selection.selectedIndices,
      title: selection.title ?? "",
      xlabel: selection.xlabel ?? "",
      ylabel: selection.ylabel ?? "",
      xunit: selection.xunit ?? "",
      yunit: selection.yunit ?? "",
      group_id: selection.groupId ?? null,
    })) as string[];
  }

  // ------------------------------------------------------------------
  // Image panel
  // ------------------------------------------------------------------

  async createImage(params: ImageCreationParams): Promise<string> {
    return (await this.callPy(
      "create_image",
      params as unknown as Record<string, unknown>,
    )) as string;
  }

  async getImageData(oid: string): Promise<ImageData> {
    const raw = (await this.callPy("get_image_data", {
      oid,
      encoding: "bytes",
    })) as ImageData & { encoding?: string };
    return decodeImagePayload(raw);
  }

  /** Overwrite the 2D data array of image *oid* with edited values
   *  (used by the Properties > Data array editor). */
  async setImageData(oid: string, data: number[][]): Promise<void> {
    await this.callPy("set_image_data", { oid, data });
  }

  /** Batched fetch for multi-image grid display.  Returns one entry per
   *  resolved id (unknown ids are silently skipped server-side).
   *  Mirrors :meth:`getSignalsData` for the image panel.
   *
   *  ``maxSize`` instructs Pyodide to decimate each image so its
   *  largest dimension is at most that many pixels.  The grid uses
   *  cells of a few hundred pixels wide, so a default of 512
   *  shrinks the bridge payload by 1–2 orders of magnitude on
   *  default ``1024×1024`` images while remaining visually
   *  indistinguishable. */
  async getImagesData(ids: string[], maxSize?: number): Promise<ImageData[]> {
    if (ids.length === 0) return [];
    const raw = (await this.callPy("get_images_data", {
      oids: ids,
      max_size: maxSize ?? null,
      encoding: "bytes",
    })) as Array<ImageData & { encoding?: string }>;
    return raw.map(decodeImagePayload);
  }

  /** Fetch and atomically decode every payload for the selected image view. */
  async getImageViewSnapshot(
    currentId: string,
    selectedIds: string[],
  ): Promise<ImageViewSnapshot | null> {
    const raw = (await this.callPyLatest(
      "selection-view",
      "get_image_view_snapshot",
      {
        current_oid: currentId,
        selected_oids: selectedIds,
        max_size: 512,
        encoding: "bytes",
      },
    )) as
      | (Omit<ImageViewSnapshot, "images"> & {
          images: Array<ImageData & { encoding?: string }>;
        })
      | null;
    if (raw === null) return null;
    return { ...raw, images: raw.images.map(decodeImagePayload) };
  }

  /** Return the catalog of image creation types (mirrors signals). */
  async listImageCreationTypes(): Promise<ImageCreationType[]> {
    return (await this.callPy(
      "list_image_creation_types",
    )) as ImageCreationType[];
  }

  /** Create an image of *stype* with default parameters. */
  async createImageTyped(stype: string, groupId?: string): Promise<string> {
    return (await this.callPy("create_image_typed", {
      stype,
      group_id: groupId ?? null,
    })) as string;
  }

  /** Update cached image creation parameters and rebuild the image. */
  async updateImageCreationParams(
    oid: string,
    values: Record<string, unknown>,
  ): Promise<{ shape: [number, number]; title: string }> {
    return (await this.callPy("update_image_creation_params", {
      oid,
      values,
    })) as { shape: [number, number]; title: string };
  }

  // ------------------------------------------------------------------
  // Image ROI (Phase 13) — physical coordinates
  // ------------------------------------------------------------------

  async getImageRoi(oid: string): Promise<ImageRoiSegment[]> {
    return (await this.callPy("get_image_roi", { oid })) as ImageRoiSegment[];
  }

  async setImageRoi(oid: string, segments: ImageRoiSegment[]): Promise<void> {
    await this.callPy("set_image_roi", { oid, segments });
  }

  async deleteImageRoiAt(oid: string, index: number): Promise<void> {
    await this.callPy("delete_image_roi_at", { oid, index });
  }

  async extractImageRois(
    oids: string | string[],
    merged: boolean,
  ): Promise<string[]> {
    return (await this.callPy("extract_image_rois", {
      oids,
      merged,
    })) as string[];
  }

  /** Erase one or more areas of image *oid* (defined by *segments*) and
   *  return the id of the new result image. The source image's own ROI
   *  list is left untouched. */
  async eraseImageArea(
    oid: string,
    segments: ImageRoiSegment[],
  ): Promise<string> {
    return (await this.callPy("erase_image_area", {
      oid,
      segments,
    })) as string;
  }

  // ------------------------------------------------------------------
  // Image analysis (Phase 13) — same payload shape as signal analysis.
  // ------------------------------------------------------------------

  async listImageAnalysis(): Promise<SignalAnalysisDescriptor[]> {
    return (await this.callPy(
      "list_image_analysis",
    )) as SignalAnalysisDescriptor[];
  }

  async getImageAnalysisParamSchema(
    id: string,
    funcId: string,
  ): Promise<unknown | null> {
    const schema = await this.callPy("get_image_analysis_param_schema", {
      oid: id,
      func_id: funcId,
    });
    return schema ?? null;
  }

  async runImageAnalysis(
    id: string,
    funcId: string,
    params?: Record<string, unknown> | null,
  ): Promise<AnalysisResult | null> {
    const out = await this.callPy("run_image_analysis", {
      oid: id,
      func_id: funcId,
      params: params ?? null,
    });
    return (out ?? null) as AnalysisResult | null;
  }

  async listImageResults(id: string): Promise<AnalysisResult[]> {
    return (await this.callPy("list_image_results", {
      oid: id,
    })) as AnalysisResult[];
  }

  async clearImageResults(id: string, metadataKey?: string): Promise<number> {
    return (await this.callPy("clear_image_results", {
      oid: id,
      metadata_key: metadataKey ?? null,
    })) as number;
  }

  // ------------------------------------------------------------------
  // Feature catalogue & processing dispatch
  // ------------------------------------------------------------------

  async listFeatures(): Promise<FeatureDescriptor[]> {
    return (await this.callPy("list_features")) as FeatureDescriptor[];
  }

  async getFeatureSchema(
    featureId: string,
    sourceOid?: string,
  ): Promise<SchemaWithValues | null> {
    return (await this.callPy("get_feature_schema", {
      feature_id: featureId,
      source_oid: sourceOid ?? null,
    })) as SchemaWithValues | null;
  }

  async resolveFeatureChoices(
    featureId: string,
    itemName: string,
    values: Record<string, unknown>,
    sourceOid?: string,
  ): Promise<DynamicChoice[]> {
    return (await this.callPy("resolve_feature_choices", {
      feature_id: featureId,
      item_name: itemName,
      values,
      source_oid: sourceOid ?? null,
    })) as DynamicChoice[];
  }

  async resolveFeatureCallbacks(
    featureId: string,
    itemName: string,
    values: Record<string, unknown>,
    sourceOid?: string,
  ): Promise<Record<string, unknown>> {
    return (await this.callPy("resolve_feature_callbacks", {
      feature_id: featureId,
      item_name: itemName,
      values,
      source_oid: sourceOid ?? null,
    })) as Record<string, unknown>;
  }

  /** Evaluate ``display.active`` for every parameter of *featureId* given
   *  the current *values*. Returns ``{itemName: boolean}`` so the form can
   *  grey out widgets whose enabling condition is unmet (e.g. the
   *  blob-detection ``min_circularity`` gated by ``filter_by_circularity``),
   *  mirroring the Qt UI. */
  async resolveFeatureActive(
    featureId: string,
    values: Record<string, unknown>,
  ): Promise<Record<string, boolean>> {
    return (await this.callPy("resolve_feature_active", {
      feature_id: featureId,
      values,
    })) as Record<string, boolean>;
  }

  /** Counterpart of {@link resolveFeatureActive} for Analysis-menu
   *  features (1→0), which live in a separate Python catalogue. */
  async resolveAnalysisActive(
    kind: "signal" | "image",
    funcId: string,
    values: Record<string, unknown>,
  ): Promise<Record<string, boolean>> {
    return (await this.callPy("resolve_analysis_active", {
      kind,
      func_id: funcId,
      values,
    })) as Record<string, boolean>;
  }

  async applyFeature(
    featureId: string,
    sourceIds: string[],
    operandId: string | null = null,
    params: Record<string, unknown> | null = null,
    groupIds: string[] = [],
    previewToken: string | null = null,
    commandId: string | null = null,
  ): Promise<string[]> {
    return (await this.callPy("apply_feature", {
      feature_id: featureId,
      source_ids: sourceIds,
      operand_id: operandId,
      params,
      group_ids: groupIds,
      preview_token: previewToken,
      command_id: commandId,
    })) as string[];
  }

  /** Refuse, before computing anything, inputs that {@link applyFeature}
   *  would refuse (e.g. X alignment): a command applied one object at a
   *  time is then applied entirely or not at all. Throws
   *  {@link ScientificRefusalError} on refusal. */
  async checkFeatureInputs(
    featureId: string,
    sourceIds: string[],
    operandId: string | null = null,
    params: Record<string, unknown> | null = null,
  ): Promise<void> {
    await this.callPy("check_feature_inputs", {
      feature_id: featureId,
      source_ids: sourceIds,
      operand_id: operandId,
      params,
    });
  }

  // ------------------------------------------------------------------
  // Image-only panel operations (modify selected images in place)
  // ------------------------------------------------------------------

  /** Return the JSON schema + default values for ``GridParam`` (used by
   *  the "Distribute on a grid" dialog). */
  async getImageGridParamSchema(): Promise<SchemaWithValues> {
    return (await this.callPy(
      "get_image_grid_param_schema",
    )) as SchemaWithValues;
  }

  /** Evaluate ``display.active`` for ``GridParam`` items (cols/rows are
   *  gated by the direction radio choice). */
  async resolveImageGridActive(
    values: Record<string, unknown>,
  ): Promise<Record<string, boolean>> {
    return (await this.callPy("resolve_image_grid_active", {
      values,
    })) as Record<string, boolean>;
  }

  /** Lay out *sourceIds* images side-by-side on a grid (in place). */
  async distributeImagesOnGrid(
    sourceIds: string[],
    params: Record<string, unknown> | null = null,
  ): Promise<void> {
    await this.callPy("distribute_images_on_grid", {
      source_ids: sourceIds,
      params,
    });
  }

  /** Re-anchor every image of *sourceIds* on the first image's origin. */
  async resetImagePositions(sourceIds: string[]): Promise<void> {
    await this.callPy("reset_image_positions", { source_ids: sourceIds });
  }

  /** Return the JSON schema + default values for ``ROIGridParam`` (used
   *  by the "Create ROI grid" dialog of the image panel). */
  async getRoiGridParamSchema(): Promise<SchemaWithValues> {
    return (await this.callPy("get_roi_grid_param_schema")) as SchemaWithValues;
  }

  /** Replace the ROI of *oid* with a generated grid of rectangular ROIs.
   *  Returns the refreshed segments so the caller can update its state
   *  in a single round-trip. */
  async createImageRoiGrid(
    oid: string,
    params: Record<string, unknown> | null = null,
  ): Promise<ImageRoiSegment[]> {
    return (await this.callPy("create_image_roi_grid", {
      oid,
      params,
    })) as ImageRoiSegment[];
  }

  // ------------------------------------------------------------------
  // Interactive fitting (Processing > Fitting > Interactive fitting)
  // ------------------------------------------------------------------

  /** List the available interactive fit kinds (linear, gaussian, …). */
  async listInteractiveFits(): Promise<InteractiveFitInfo[]> {
    return (await this.callPy("list_interactive_fits")) as InteractiveFitInfo[];
  }

  /** Initialise an interactive fit on signal *oid* and return the
   *  initial parameter slider values, the bounds, and the fit curve. */
  async initInteractiveFit(
    oid: string,
    fitId: string,
    extras: Record<string, unknown> | null = null,
  ): Promise<InteractiveFitInit> {
    return (await this.callPy("init_interactive_fit", {
      oid,
      fit_id: fitId,
      extras,
    })) as InteractiveFitInit;
  }

  /** Re-evaluate the model at *x* with the user-tweaked *values*.
   *  Called on every slider drag — fast pure-NumPy evaluation. */
  async evaluateInteractiveFit(
    fitId: string,
    x: number[],
    values: Record<string, number>,
    extras: Record<string, unknown> | null = null,
  ): Promise<number[]> {
    return (await this.callPy("evaluate_interactive_fit", {
      fit_id: fitId,
      x,
      values,
      extras,
    })) as number[];
  }

  /** Run the auto-fitter (scipy.optimize.curve_fit) and return the
   *  optimised parameters + the new fit curve. */
  async autoFitInteractive(
    oid: string,
    fitId: string,
    extras: Record<string, unknown> | null = null,
  ): Promise<InteractiveFitAuto> {
    return (await this.callPy("auto_fit_interactive", {
      oid,
      fit_id: fitId,
      extras,
    })) as InteractiveFitAuto;
  }

  /** Commit the current parameter values: add the fitted curve as a
   *  new signal in the same group as *oid*; return the new object id. */
  async commitInteractiveFit(
    oid: string,
    fitId: string,
    values: Record<string, number>,
    extras: Record<string, unknown> | null = null,
  ): Promise<string> {
    return (await this.callPy("commit_interactive_fit", {
      oid,
      fit_id: fitId,
      values,
      extras,
    })) as string;
  }

  async listProcessings(): Promise<ProcessingDescriptor[]> {
    return (await this.callPy("list_processings")) as ProcessingDescriptor[];
  }

  async getProcessingSchema(
    processingId: string,
  ): Promise<SchemaWithValues | null> {
    return (await this.callPy("get_processing_schema", {
      processing_id: processingId,
    })) as SchemaWithValues | null;
  }

  async resolveProcessingChoices(
    processingId: string,
    itemName: string,
    values: Record<string, unknown>,
  ): Promise<DynamicChoice[]> {
    return (await this.callPy("resolve_processing_choices", {
      processing_id: processingId,
      item_name: itemName,
      values,
    })) as DynamicChoice[];
  }

  async applyProcessing(
    id: string,
    processingId: string,
    params?: Record<string, unknown>,
  ): Promise<string> {
    return (await this.callPy("apply_processing", {
      oid: id,
      processing_id: processingId,
      params: params ?? null,
    })) as string;
  }

  /** Return the last processing applied to produce *id*, or ``null``
   *  when the object was created (not produced by a feature) or the
   *  feature is no longer registered.  Drives the "Processing" side
   *  panel tab. */
  async getLastProcessing(id: string): Promise<LastProcessingInfo | null> {
    return (await this.callPy("get_last_processing", {
      oid: id,
    })) as LastProcessingInfo | null;
  }

  /** Re-run the last processing applied to *id* with *values* and
   *  replace its data in place.  Returns the same id.  The recorded
   *  source ids are passed along so that on-disk sources are paged in. */
  async reapplyLastProcessing(
    id: string,
    values: Record<string, unknown> | null,
  ): Promise<string> {
    const record = await this.getLastProcessing(id);
    return (await this.callPy("reapply_last_processing", {
      oid: id,
      values,
      ...(record
        ? { source_ids: record.source_ids, operand_id: record.operand_id }
        : {}),
    })) as string;
  }

  /** Return the workspace provenance ledger and its runtime status. */
  async getProvenanceLedger(): Promise<ProvenanceLedgerInfo> {
    return restoreJsonNulls(
      await this.callPy("get_provenance_ledger"),
    ) as ProvenanceLedgerInfo;
  }

  /** Verify a recorded activity by recomputing it as a separate candidate.
   *  The workspace and the ledger are left unchanged. */
  async replayActivity(activityId: string): Promise<ProvenanceReport> {
    return restoreJsonNulls(
      await this.callPy("replay_activity", { activity_id: activityId }),
    ) as ProvenanceReport;
  }

  /** Describe the provenance of an object (or of one of its recorded states
   *  with ``stateId``). Consulting never reads arrays; ``checkData`` compares
   *  the data with their recorded states without computing, and reports
   *  arrays that are not resident as unavailable (they are not paged in). */
  async describeObjectProvenance(
    objectId: string,
    options: { stateId?: string; checkData?: boolean; trail?: string[] } = {},
  ): Promise<ProvenanceDescription> {
    return restoreJsonNulls(
      await this.callPy("describe_object_provenance", {
        object_id: objectId,
        state_id: options.stateId ?? null,
        check_data: options.checkData ?? false,
        trail: options.trail ?? [],
      }),
    ) as ProvenanceDescription;
  }

  /** Describe one recorded activity (see {@link describeObjectProvenance}). */
  async describeProvenanceActivity(
    activityId: string,
    checkData = false,
  ): Promise<{
    available: boolean;
    reason?: string | null;
    activity?: ProvenanceActivity;
  }> {
    return restoreJsonNulls(
      await this.callPy("describe_provenance_activity", {
        activity_id: activityId,
        check_data: checkData,
      }),
    ) as {
      available: boolean;
      reason?: string | null;
      activity?: ProvenanceActivity;
    };
  }

  // ---------------------------------------------------------------------
  // Plugin system
  // ---------------------------------------------------------------------

  /** Write bundled built-in plugins to a dedicated directory and load them. */
  async installBuiltinPlugins(sources: Record<string, string>): Promise<void> {
    const dir = "/home/pyodide/builtin_plugins";
    this.py.FS.mkdirTree?.(dir);
    for (const [path, source] of Object.entries(sources)) {
      const name = path.split("/").pop() ?? "plugin.py";
      this.py.FS.writeFile(`${dir}/${name}`, source);
    }
    try {
      await this.discoverPluginsInDir(dir, "builtin-source");
    } catch (err) {
      console.error("[plugins] failed to load built-in plugins", err);
    }
  }

  async loadPluginSource(
    filename: string,
    source: string,
  ): Promise<PluginRecord> {
    return (await this.callPy("load_plugin_source", {
      filename,
      source,
    })) as PluginRecord;
  }

  async loadPluginFile(path: string): Promise<PluginRecord> {
    return (await this.callPy("load_plugin_file", { path })) as PluginRecord;
  }

  async loadPluginWheel(
    path: string,
    filename: string,
    sha256: string,
    source: "bundled-wheel" | "user-wheel" = "user-wheel",
    trust: "verified" | "unverified" = "unverified",
  ): Promise<PluginRecord[]> {
    return (await this.callPy("load_plugin_wheel", {
      path,
      filename,
      source,
      sha256,
      trust,
    })) as PluginRecord[];
  }

  private writePluginWheel(sha256: string, bytes: Uint8Array): string {
    const dir = "/home/pyodide/plugin-wheels";
    this.py.FS.mkdirTree?.(dir);
    const path = `${dir}/user-${sha256}.whl`;
    this.py.FS.writeFile(path, bytes);
    return path;
  }

  /** Inspect a local wheel with the live Pyodide package inventory, no import. */
  async inspectPluginWheel(
    filename: string,
    bytes: Uint8Array,
  ): Promise<PluginWheelInspection> {
    const sha256 = await hashBytes(bytes);
    const path = this.writePluginWheel(sha256, bytes);
    const inspection = (await this.callPy("inspect_plugin_wheel", {
      path,
      filename,
    })) as PluginWheelInspection;
    if (inspection.sha256 !== sha256) {
      throw new Error("Plugin wheel changed while it was being inspected");
    }
    return inspection;
  }

  /** Install an already-consented local wheel transactionally into OPFS. */
  async installPluginWheel(
    filename: string,
    bytes: Uint8Array,
  ): Promise<PluginRecord[]> {
    if (!this.pluginWheelStore) {
      throw new Error("Persistent plugin storage requires OPFS");
    }
    const inspection = await this.inspectPluginWheel(filename, bytes);
    const sha256 = inspection.sha256;
    const artifactId = `sha256:${sha256}`;
    const path = this.writePluginWheel(sha256, bytes);
    await this.pluginWheelStore.stage(sha256, bytes);
    let records: PluginRecord[] = [];
    try {
      records = await this.loadPluginWheel(
        path,
        filename,
        sha256,
        "user-wheel",
        "unverified",
      );
      if (records.length === 0 || records.some((record) => !record.loaded)) {
        throw new Error(
          records.find((record) => record.error)?.error ??
            "Plugin wheel did not register a Web plugin",
        );
      }
      const pluginIds = records.map((record) => record.plugin_id as string);
      const metadata: UserPluginWheelRecord = {
        artifactId,
        sha256,
        filename,
        sizeBytes: bytes.byteLength,
        distribution: inspection.distribution,
        version: inspection.version,
        pluginIds,
        enabledPluginIds: [...pluginIds],
        installedAt: new Date().toISOString(),
      };
      await this.pluginWheelStore.commit(metadata);
      return records;
    } catch (error) {
      for (const record of records) {
        await this.unloadPlugin(record.record_id);
      }
      await this.pluginWheelStore.rollback(sha256);
      throw error;
    }
  }

  async unloadPlugin(
    name: string,
  ): Promise<{ name: string; removed: boolean }> {
    return (await this.callPy("unload_plugin", { name })) as {
      name: string;
      removed: boolean;
    };
  }

  async setPluginEnabled(
    name: string,
    enabled: boolean,
  ): Promise<PluginRecord> {
    const before = (await this.listPlugins()).find(
      (record) => record.record_id === name || record.plugin_id === name,
    );
    const result = (await this.callPy("set_plugin_enabled", {
      name,
      enabled,
    })) as PluginRecord;
    if (
      result.source === "user-wheel" &&
      result.artifact_id &&
      this.pluginWheelStore
    ) {
      try {
        const records = (await this.listPlugins()).filter(
          (record) => record.artifact_id === result.artifact_id,
        );
        await this.pluginWheelStore.setEnabledPluginIds(
          result.artifact_id,
          records
            .filter((record) => record.enabled)
            .map((record) => record.plugin_id as string),
        );
      } catch (error) {
        if (before) {
          await this.callPy("set_plugin_enabled", {
            name: result.record_id,
            enabled: before.enabled,
          });
        }
        throw error;
      }
    }
    return result;
  }

  async removeUserPluginWheel(artifactId: string): Promise<void> {
    if (!this.pluginWheelStore) {
      throw new Error("Persistent plugin storage requires OPFS");
    }
    const records = (await this.listPlugins()).filter(
      (record) => record.artifact_id === artifactId,
    );
    if (records.some((record) => record.source !== "user-wheel")) {
      throw new Error("Bundled plugin wheels cannot be removed");
    }
    for (const record of records) {
      await this.unloadPlugin(record.record_id);
    }
    await this.pluginWheelStore.remove(artifactId);
  }

  async reloadPlugins(): Promise<PluginRecord[]> {
    return (await this.callPy("reload_plugins")) as PluginRecord[];
  }

  async discoverPluginsInDir(
    directory: string,
    source: "builtin-source" | "user-source" = "user-source",
  ): Promise<PluginRecord[]> {
    return (await this.callPy("discover_plugins_in_dir", {
      directory,
      source,
    })) as PluginRecord[];
  }

  // ---------------------------------------------------------------------
  // Macro execution (used by the AI Assistant ``create_and_run_macro``
  // tool — keeps a single shared :class:`MacroRuntime` instance to
  // amortise the Pyodide worker cold-start across calls).
  // ---------------------------------------------------------------------

  /** Last buffered output from :meth:`runMacroCode`, read through
   *  :meth:`getLastMacroOutput` (a public *field* would not cross the
   *  worker boundary: the worker-backed façade only forwards methods). */
  private _lastMacroOutput: MacroRunOutput | null = null;

  private _macroRuntime: import("./MacroRuntime").MacroRuntime | null = null;

  private async ensureMacroRuntime(): Promise<
    import("./MacroRuntime").MacroRuntime
  > {
    if (this._macroRuntime) return this._macroRuntime;
    const { MacroRuntime } = await import("./MacroRuntime");
    this._macroRuntime = new MacroRuntime(this);
    return this._macroRuntime;
  }

  /** Return the buffered output of the last macro run through
   *  :meth:`runMacroCode` (or ``null`` if no macro has run yet through
   *  this runtime). Surfaced to the LLM via the
   *  ``get_macro_console_output`` tool — useful when the previous call
   *  truncated its output. */
  async getLastMacroOutput(): Promise<MacroRunOutput | null> {
    return this._lastMacroOutput;
  }

  /** Run *code* as a transient macro and resolve once it completes
   *  with the captured stdout/stderr.  The macro is NOT persisted in
   *  the workspace's macro panel: the AI Assistant UI saves it on user
   *  demand through the Macros panel. Output is also kept for
   *  :meth:`getLastMacroOutput`. */
  async runMacroCode(
    code: string,
    name = "AI Assistant macro",
  ): Promise<MacroRunOutput> {
    const macro = await this.ensureMacroRuntime();
    return new Promise((resolve, reject) => {
      let stdout = "";
      let stderr = "";
      macro
        .run(code, name, {
          onStream: (kind, text) => {
            if (kind === "stdout") stdout += text;
            else if (kind === "stderr") stderr += text;
          },
          onFinished: (status, error) => {
            const out = { stdout, stderr, status, error };
            this._lastMacroOutput = out;
            resolve(out);
          },
        })
        .catch(reject);
    });
  }

  async listPlugins(): Promise<PluginRecord[]> {
    return (await this.callPy("list_plugins")) as PluginRecord[];
  }

  /**
   * List every menu action recorded by plugin shims (one snapshot per call).
   */
  async listPluginMenuActions(): Promise<PluginMenuAction[]> {
    return (await this.runPython(`
from datalab.registries import EXTRA_MENU_ACTIONS
[{
    "action_id": entry.action_id,
    "title": entry.title,
    "menu_path": entry.menu_path,
    "select_condition": entry.select_condition,
    "separator_before": entry.separator_before,
    "icon": entry.icon,
    "tip": entry.tip,
    "origin": entry.origin,
    "object_kind": kind,
} for kind in ("signal", "image") for entry in EXTRA_MENU_ACTIONS[kind]]
`)) as PluginMenuAction[];
  }

  /** Trigger a plugin-supplied menu action by its id.
   *
   * Returns the UUIDs of objects that were newly added to each panel
   * during the action's execution. The desktop `LocalProxy.add_object`
   * implicitly selects the freshly-created object; the browser bridge
   * has no live selection model, so we expose the diff to let the UI
   * select the new objects after a refresh.
   */
  async triggerPluginAction(
    actionId: string,
  ): Promise<{ signal: string[]; image: string[] }> {
    return (await this.callPy("trigger_plugin_action", {
      action_id: actionId,
    })) as { signal: string[]; image: string[] };
  }

  // ---------------------------------------------------------------------
  // Macros (mirrors DataLab Qt's MacroPanel state).
  // ---------------------------------------------------------------------

  async listMacros(): Promise<MacroMeta[]> {
    return (await this.callPy("list_macros")) as MacroMeta[];
  }

  async getMacro(macroId: string): Promise<MacroRecord> {
    return (await this.callPy("get_macro", {
      macro_id: macroId,
    })) as MacroRecord;
  }

  async createMacro(
    title?: string,
    code?: string,
    options: { silent?: boolean } = {},
  ): Promise<MacroRecord> {
    return (await this.callPy(
      "create_macro",
      {
        title: title ?? null,
        code: code ?? null,
      },
      options,
    )) as MacroRecord;
  }

  async setMacroCode(macroId: string, code: string): Promise<void> {
    await this.callPy("set_macro_code", { macro_id: macroId, code });
  }

  /** Statically lint *code* against the proxy API surface. */
  async lintMacro(code: string): Promise<MacroLintResult> {
    return (await this.callPy("lint_macro", { code })) as MacroLintResult;
  }

  async renameMacro(macroId: string, title: string): Promise<void> {
    await this.callPy("rename_macro", { macro_id: macroId, title });
  }

  async deleteMacro(macroId: string): Promise<void> {
    await this.callPy("delete_macro", { macro_id: macroId });
  }

  async duplicateMacro(macroId: string): Promise<MacroRecord> {
    return (await this.callPy("duplicate_macro", {
      macro_id: macroId,
    })) as MacroRecord;
  }

  async reorderMacros(macroIds: string[]): Promise<void> {
    await this.callPy("reorder_macros", { macro_ids: macroIds });
  }

  async replaceMacros(
    records: MacroRecord[],
    options: { silent?: boolean } = {},
  ): Promise<void> {
    await this.callPy("replace_macros", { records }, options);
  }

  // ---------------------------------------------------------------------
  // Notebooks (mirror of the macro API — see above).
  //
  // Notebooks are stored on the Python side as opaque nbformat v4.5
  // JSON strings; Python never parses them.  This keeps ``bootstrap.py``
  // schema-agnostic and lets the JS notebook UI remain the sole owner
  // of the nbformat representation.
  // ---------------------------------------------------------------------

  async listNotebooks(): Promise<NotebookMeta[]> {
    return (await this.callPy("list_notebooks")) as NotebookMeta[];
  }

  async getNotebook(notebookId: string): Promise<NotebookRecord> {
    return (await this.callPy("get_notebook", {
      notebook_id: notebookId,
    })) as NotebookRecord;
  }

  async createNotebook(
    title?: string,
    content?: string,
    options: { silent?: boolean } = {},
  ): Promise<NotebookRecord> {
    return (await this.callPy(
      "create_notebook",
      {
        title: title ?? null,
        content: content ?? null,
      },
      options,
    )) as NotebookRecord;
  }

  async setNotebookContent(notebookId: string, content: string): Promise<void> {
    await this.callPy("set_notebook_content", {
      notebook_id: notebookId,
      content,
    });
  }

  async renameNotebook(notebookId: string, title: string): Promise<void> {
    await this.callPy("rename_notebook", { notebook_id: notebookId, title });
  }

  async deleteNotebook(notebookId: string): Promise<void> {
    await this.callPy("delete_notebook", { notebook_id: notebookId });
  }

  async duplicateNotebook(notebookId: string): Promise<NotebookRecord> {
    return (await this.callPy("duplicate_notebook", {
      notebook_id: notebookId,
    })) as NotebookRecord;
  }

  async reorderNotebooks(notebookIds: string[]): Promise<void> {
    await this.callPy("reorder_notebooks", { notebook_ids: notebookIds });
  }

  async replaceNotebooks(records: NotebookRecord[]): Promise<void> {
    await this.callPy("replace_notebooks", { records });
  }

  // ---------------------------------------------------------------------
  // Debug helpers (use from the browser DevTools console — see README).
  // ---------------------------------------------------------------------

  /** Run an arbitrary Python snippet and return its result as a JS value. */
  async runPython(code: string): Promise<unknown> {
    return toJs(await this.py.runPythonAsync(code));
  }

  /**
   * Resolve the versions actually installed in the live Pyodide instance.
   *
   * Reads ``importlib.metadata.version`` for each requested package and
   * returns a ``{ name: version | null }`` map (``null`` when the package
   * is not importable). This is the **ground-truth** counterpart to the
   * network-based shim audit (``tests/ts/shims/shim-audit.spec.ts``),
   * which infers versions from PyPI / the Pyodide lockfile without booting
   * Pyodide. Useful for diagnostics (About dialog, bug reports) and for an
   * end-to-end audit probe.
   *
   * @param packages Package names to query; defaults to the packages listed
   *  in ``PACKAGE_VERSION_SOURCES`` for shim audits and diagnostics
   *  (``guidata``, ``sigima``, ``numpy``, ``scipy``, ``h5py``).
   */
  async getInstalledVersions(
    packages: readonly string[] = Object.keys(PACKAGE_VERSION_SOURCES),
  ): Promise<Record<string, string | null>> {
    const names = JSON.stringify([...packages]);
    const result = await this.py.runPythonAsync(`
import json
from importlib.metadata import version, PackageNotFoundError

def _resolve(_names):
    out = {}
    for _name in _names:
        try:
            out[_name] = version(_name)
        except PackageNotFoundError:
            out[_name] = None
    return out

json.dumps(_resolve(json.loads(${JSON.stringify(names)})))
`);
    return JSON.parse(result as string) as Record<string, string | null>;
  }

  /** Return a complete, JSON-safe snapshot of the live Python runtime. */
  async getPythonEnvironmentInfo(): Promise<PythonEnvironmentInfo> {
    const result = await this.py.runPythonAsync(`
import json
import platform
import sys
from importlib.metadata import distributions

try:
    import pyodide as _pyodide
    _pyodide_version = getattr(_pyodide, "__version__", None)
except ImportError:
    _pyodide_version = None

_packages = []
for _dist in distributions():
    _name = _dist.metadata.get("Name")
    if _name:
        _packages.append({"name": _name, "version": _dist.version})
_packages.sort(key=lambda _item: _item["name"].casefold())

json.dumps({
  "pythonVersion": platform.python_version(),
    "pythonImplementation": platform.python_implementation(),
    "pythonPlatform": sys.platform,
    "platform": platform.platform(),
    "machine": platform.machine(),
    "pyodideVersion": _pyodide_version,
    "packages": _packages,
})
`);
    return JSON.parse(result as string) as PythonEnvironmentInfo;
  }

  /**
   * Re-execute the bootstrap source against the live Pyodide instance.
   *
   * Useful when iterating on the Python side without paying the 30-second
   * Pyodide cold-start again.  The in-memory ``_STORE`` is preserved if the
   * new bootstrap leaves it untouched (e.g. you only changed a helper).
   */
  async reloadBootstrap(source: string = bootstrapSource): Promise<void> {
    await this.py.runPythonAsync(source);
    console.info("[runtime] bootstrap.py re-executed (store preserved)");
  }

  /**
   * Update ``dlw_processor`` in Pyodide's filesystem and ask the live
   * bootstrap to refresh its catalogue.  Called by the Python HMR handler
   * when ``processor.py`` is edited.
   */
  async reloadProcessor(source: string = processorSource): Promise<void> {
    this.py.FS.writeFile("/home/pyodide/dlw_processor.py", source);
    await this.py.runPythonAsync(`
import importlib
import dlw_processor
importlib.reload(dlw_processor)
import sys
if "__main__" in sys.modules:
    pass
# Refresh the bootstrap-side catalog reference in-place.
_CATALOG.clear()
_CATALOG.update(dlw_processor.build_signal_catalog())
`);
    console.info("[runtime] dlw_processor.py reloaded; catalog refreshed");
  }

  /**
   * Read the current memory footprint of the runtime.
   *
   * The headline figure is the Pyodide **WASM linear-heap** size
   * (``_module.HEAPU8.length``), available in every browser and the
   * best predictor of an out-of-memory crash. On Chromium we also
   * surface the JS heap via ``performance.memory`` (``null`` elsewhere).
   *
   * Pure synchronous reads — this does **not** go through the Python
   * call queue, so it is safe to poll on a timer without serialising
   * behind in-flight computations.
   */
  getMemoryUsage(): MemoryUsage {
    const wasmBytes = readWasmHeapBytes(this.py._module);
    const { jsUsedBytes, jsLimitBytes } = readJsMemory();
    return { wasmBytes, dataBytes: null, jsUsedBytes, jsLimitBytes };
  }

  /**
   * Read the total byte size of the signal/image arrays currently held
   * by the object model. Unlike the WASM heap this responds to deletes,
   * so the indicator can show the user that clearing objects had an
   * effect. Routed through the Python call queue (cheap O(n) sum, no
   * data copy); returns ``null`` if the runtime cannot report it.
   */
  async getDataMemoryBytes(): Promise<number | null> {
    try {
      const r = (await this.callPy("get_data_memory")) as {
        data_bytes?: number;
      };
      return typeof r?.data_bytes === "number" ? r.data_bytes : null;
    } catch {
      return null;
    }
  }

  /**
   * Run a full Python garbage-collection pass and report its effect.
   *
   * The WASM heap never shrinks back to the OS, so the goal is not to
   * lower ``wasmBytes`` but to drop dangling Python references so later
   * allocations reuse freed heap pages instead of growing the heap.
   * Returns the WASM heap size before/after plus the object counts and
   * the number of unreachable objects reclaimed by ``gc.collect``.
   */
  async freeMemory(): Promise<FreeMemoryResult> {
    const wasmBefore = this.getMemoryUsage().wasmBytes;
    const result = (await this.callPy("collect_garbage")) as {
      collected: number;
      objects_before: number;
      objects_after: number;
    };
    const wasmAfter = this.getMemoryUsage().wasmBytes;
    return { ...result, wasmBefore, wasmAfter };
  }
}