@graphty/graph-io 0.3.24 → 0.3.26

package/dist/src/formats/cys/exporter.js

@@ -0,0 +1,1072 @@
+/**
+ * The Cytoscape session exporter: writes a snapshot as a `.cys` file that Cytoscape Desktop 3.x
+ * opens as a session holding one network (one collection with one registered subnetwork).
+ *
+ * The archive holds what Cytoscape's session reader needs and nothing more:
+ * - `CytoscapeSession/3.0.0.version`, the empty marker that makes Cytoscape read a 3.x session;
+ * - `networks/<root>-<name>.xgmml`, the topology: one root network holding one registered
+ *   subnetwork, its nodes and edges by SUID, each edge with `cy:directed`;
+ * - `tables/<subnetwork>-<name>/LOCAL_ATTRS-org.cytoscape.model.Cy{Node,Edge,Network}-*.cytable`,
+ *   every column as a CyCSV table keyed by SUID (a session network file carries no attributes:
+ *   Cytoscape ignores atts on the nodes and edges of a 3.x session), with the label in `name`,
+ *   which Cytoscape's default style shows; plus the root network's own table with its name;
+ * - `views/<subnetwork>-<view>-<name>.xgmml`, the node coordinates (y negated back to screen
+ *   coordinates), only when the snapshot has positions: graph-io computes no layout.
+ *
+ * Styles, the network list, properties and thumbnails are not written; Cytoscape gives the view
+ * its default style. Entries are stored, not compressed. Every SUID comes from one counter, above
+ * the node ids that are kept as SUIDs; Cytoscape renumbers them all on load.
+ */
+import { GraphFormatError } from "@graphty/graph-format";
+import { DictHeuristic } from "../../common/attributes.js";
+import { pairFolding } from "../../common/direction.js";
+import { escapeXmlAttribute, quoteCsvCell } from "../../common/escape.js";
+import { capabilities, checkCapabilities, LOSS } from "../../common/export.js";
+import { formatDecimal, formatF32, formatF64 } from "../../common/format.js";
+import { resolveExportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
+import { explicitWeights } from "../../common/weights.js";
+import { hasIllegalXmlChar } from "../../common/xml.js";
+import { writeZip } from "../../common/zip.js";
+import { ORIGINAL_ID_ATTRIBUTE } from "../graphml/constants.js";
+import { CY_NAMESPACE, EDGE_ID_COLUMN, GRAPHICS_COLUMN, NESTED_NETWORK_COLUMN, NETWORK_POINTER_COLUMN, NETWORKS_COLUMN, PARENT_COLUMN, PARENTS_COLUMN, POSITION_COLUMN, SUBGRAPH_COLUMN, XGMML_NAMESPACE, XLINK_NAMESPACE, Z_COLUMN, } from "../xgmml/constants.js";
+import { FORMAT } from "./constants.js";
+/**
+ * The loss notes the session exporter's check() returns, by name. A key is the code without its
+ * severity and format prefixes.
+ * @category Built-in formats
+ */
+export const CYS_LOSS = Object.freeze({
+    /** CyCSV has no unset text cell: an unset cell of a text column reads back as "". */
+    UNSET_AS_EMPTY_STRING: "W_CYS_UNSET_AS_EMPTY_STRING",
+    /**
+     * List cells CyCSV cannot hold exactly: an unset or empty list of text reads back as [""], an
+     * empty list of numbers or booleans reads back unset, trailing empty text items vanish, and an
+     * item holding a newline splits in two.
+     */
+    LIST_ITEMS: "W_CYS_LIST_ITEMS",
+    /** A text cell starting with "=" is a formula to Cytoscape (an error cell there); graph-io reads it back as text. */
+    TEXT_AS_EQUATION: "W_CYS_TEXT_AS_EQUATION",
+    /** A nested (json) column is written as a text column holding its JSON text. */
+    JSON_AS_STRING: "W_CYS_JSON_AS_STRING",
+    /** A position that cannot be written as it is: another shape, a non-finite coordinate, a z read back in the z column. */
+    POSITION: "W_CYS_POSITION",
+    /**
+     * An attribute with a role (for example, the label) is written where the format keeps that role, and reads back under the
+     * name the format's importer gives it.
+     */
+    COLUMN_NAME_CHANGED: LOSS.COLUMN_NAME_CHANGED,
+    /**
+     * An attribute without a role is written where the format keeps a role (for example, a `name` column as the label), and
+     * reads back with that role.
+     */
+    ROLE_ASSUMED: LOSS.ROLE_ASSUMED,
+    /** A mutual pair is written as two directed edges without its mark. */
+    MUTUAL_EXPANDED: LOSS.MUTUAL_EXPANDED,
+    /** Node ids that are numbers read back as their text. */
+    ID_TEXT_TYPE: LOSS.ID_TEXT_TYPE,
+    /**
+     * Two node ids would be written as the same text (the number 5 and the text "5"); the save fails with
+     * E_INVALID_ID.
+     */
+    ID_TEXT_COLLISION: LOSS.ID_TEXT_COLLISION,
+    /**
+     * Node ids the format cannot write, under `sanitizeIds: "error"`; the save fails with E_INVALID_ID. Pass
+     * `sanitizeIds: "mangle"` to rewrite them.
+     */
+    ID_CHARSET: LOSS.ID_CHARSET,
+    /** Node ids that are not positive integers under sanitizeIds "mangle": renumbered, originals kept. */
+    ID_MANGLED: LOSS.ID_MANGLED,
+    /** Edges without a usable id get generated SUIDs. */
+    EDGE_IDS_GENERATED: LOSS.EDGE_IDS_GENERATED,
+    /**
+     * An attribute type Cytoscape stores as a wider one (a 32-bit float as Double, a byte as Integer), or a label that
+     * is not text and is written as text; it reads back with the Cytoscape type.
+     */
+    DTYPE_UNSUPPORTED: LOSS.DTYPE,
+    /** A column whose every cell is unset (and which is not text) vanishes. */
+    EMPTY_COLUMN_DROPPED: LOSS.EMPTY_COLUMN,
+    /**
+     * A text attribute reads back as a dictionary attribute, or the reverse, because the importer chooses by how often
+     * its values repeat. The values are the same.
+     */
+    STORAGE_CLASS_CHANGED: LOSS.STORAGE_CLASS,
+    /** A plain `weight` edge column reads back as the edge weight. */
+    WEIGHT_KEY_CLASH: LOSS.WEIGHT_KEY_CLASH,
+    /** A parent / parents column: groups are not written. */
+    HIERARCHY_DROPPED: LOSS.HIERARCHY,
+    /** A start / end / timestamp column: sessions have no time. */
+    TEMPORAL_DROPPED: LOSS.TEMPORAL,
+    /** An attribute with a role the format has no place for is written as a plain attribute; the role is lost. */
+    ROLE_DROPPED: LOSS.ROLE,
+    /** An extension table the session cannot carry. */
+    EXTENSION_TABLE_DROPPED: LOSS.EXTENSION_TABLE,
+});
+/**
+ * What a Cytoscape session keeps: mixed direction, parallel edges and self-loops, integer SUIDs
+ * for nodes and edges, String / Double / Integer / Long / Boolean columns and lists of them,
+ * graph columns and positions. Groups, defaults, styles and time are not written.
+ * @category Built-in formats
+ */
+export const CYS_CAPABILITIES = capabilities({
+    mixedDirection: true,
+    multiEdges: true,
+    selfLoops: true,
+    edgeIds: "required",
+    idCharset: "integer",
+    dtypes: ["string", "dict", "f64", "i32", "bool", "list"],
+    components: false,
+    lists: true,
+    json: false,
+    defaults: false,
+    options: false,
+    hierarchy: false,
+    temporal: "none",
+    graphAttributes: true,
+    positions: true,
+    viz: false,
+});
+/** The roles with a slot (the label as `name`, the edge id as the SUID, positions in the view) and their read-back names. */
+const SLOT_ROLES = new Set(["label", "id", "position"]);
+const ROLE_NAMES = Object.freeze({
+    label: "name",
+    id: EDGE_ID_COLUMN,
+    position: POSITION_COLUMN,
+});
+/** Roles whose columns are not written as table columns (structure, or reported dropped by checkCapabilities). */
+const SKIPPED_ROLES = new Set([
+    "directed",
+    "pair",
+    "mutual",
+    "weight",
+    "timeText",
+    "parent",
+    "parents",
+    "start",
+    "end",
+    "timestamp",
+    "timestamps",
+    "spells",
+    "open",
+    "spellsOpen",
+    "position",
+    "color",
+    "size",
+    "shape",
+    "thickness",
+]);
+/** The Java classes of the columns Cytoscape creates in every table, by lower-case name. */
+const BUILT_IN = {
+    node: new Map([
+        ["name", "java.lang.String"],
+        ["shared name", "java.lang.String"],
+        ["selected", "java.lang.Boolean"],
+    ]),
+    edge: new Map([
+        ["name", "java.lang.String"],
+        ["shared name", "java.lang.String"],
+        ["interaction", "java.lang.String"],
+        ["shared interaction", "java.lang.String"],
+        ["selected", "java.lang.Boolean"],
+    ]),
+    network: new Map([
+        ["name", "java.lang.String"],
+        ["shared name", "java.lang.String"],
+        ["selected", "java.lang.Boolean"],
+        ["__annotations", "java.util.List<java.lang.String>"],
+    ]),
+};
+/** Column names graph-io's session importer gives its own columns; a table column of such a name reads back renamed. */
+const IMPORTER_NAMES = {
+    node: new Set([
+        POSITION_COLUMN,
+        Z_COLUMN,
+        GRAPHICS_COLUMN,
+        PARENT_COLUMN,
+        PARENTS_COLUMN,
+        SUBGRAPH_COLUMN,
+        NESTED_NETWORK_COLUMN,
+        NETWORK_POINTER_COLUMN,
+        NETWORKS_COLUMN,
+    ]),
+    edge: new Set([EDGE_ID_COLUMN, GRAPHICS_COLUMN]),
+    network: new Set([GRAPHICS_COLUMN]),
+};
+const STRING = "java.lang.String";
+const DOUBLE = "java.lang.Double";
+const INTEGER = "java.lang.Integer";
+const LONG = "java.lang.Long";
+const BOOLEAN = "java.lang.Boolean";
+const I32_MAX = 2147483647;
+/** The folder every entry lives under (Cytoscape needs one; the name is free). */
+const ROOT_FOLDER = "CytoscapeSession/";
+/** The default network name. */
+const DEFAULT_NAME = "Network";
+// ============================================================ ids
+/** Positive integer text a Long holds exactly. */
+const SUID_TEXT = /^[1-9]\d*$/;
+/**
+ * The SUID a node id can keep, or null: a positive safe integer, or its canonical digits.
+ * @param id - the id
+ * @returns the SUID, or null
+ */
+function suidOf(id) {
+    if (typeof id === "number") {
+        return Number.isSafeInteger(id) && id > 0 ? id : null;
+    }
+    if (SUID_TEXT.test(id)) {
+        const n = Number(id);
+        return Number.isSafeInteger(n) ? n : null;
+    }
+    return null;
+}
+/**
+ * The SUIDs node ids keep (the first of two ids naming one SUID keeps it).
+ * @param snapshot - the snapshot
+ * @returns the kept SUIDs and the nodes without one
+ */
+function keptNodeSuids(snapshot) {
+    const kept = [];
+    const bad = [];
+    const used = new Set();
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        const suid = suidOf(snapshot.ids.idOf(i));
+        if (suid === null || used.has(suid)) {
+            kept.push(0);
+            bad.push(i);
+        }
+        else {
+            used.add(suid);
+            kept.push(suid);
+        }
+    }
+    return { kept, bad };
+}
+/**
+ * The edge SUIDs the id role column keeps: positive integers, distinct, and not node SUIDs.
+ * @param snapshot - the snapshot
+ * @param nodeSuids - the SUIDs nodes keep
+ * @returns the kept SUID of each edge, 0 where one is generated
+ */
+function keptEdgeSuids(snapshot, nodeSuids) {
+    const column = snapshot.edges.byRole("id");
+    const out = new Array(snapshot.edgeCount).fill(0);
+    if (column === null) {
+        return out;
+    }
+    const used = new Set();
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        const value = column.isSet(e) ? column.value(e) : null;
+        const suid = typeof value === "number" || typeof value === "string" ? suidOf(value) : null;
+        if (suid !== null && !used.has(suid) && !nodeSuids.has(suid)) {
+            used.add(suid);
+            out[e] = suid;
+        }
+    }
+    return out;
+}
+// ============================================================ columns
+/**
+ * The Java class of a scalar dtype.
+ * @param column - the column (for the long origin and the u32 range)
+ * @param dtype - the dtype (a list's item dtype)
+ * @returns the class text
+ */
+function scalarClass(column, dtype) {
+    switch (dtype) {
+        case "bool":
+            return BOOLEAN;
+        case "i32":
+        case "u8":
+            return INTEGER;
+        case "u32":
+            return maxValue(column) > I32_MAX ? LONG : INTEGER;
+        case "f32":
+        case "f64":
+            return /long$/i.test(column.meta.origin?.type ?? "") && allSafeIntegers(column) ? LONG : DOUBLE;
+        default:
+            return STRING;
+    }
+}
+/**
+ * The items of a set cell: a list's items, or the scalar itself.
+ * @param column - the column
+ * @param row - the row
+ * @returns the values
+ */
+function itemsOf(column, row) {
+    return column.dtype === "list" ? [...column.sliceOf(row)] : [column.value(row)];
+}
+/**
+ * Whether every set value of a numeric column (or of its list items) is a safe integer.
+ * @param column - the column
+ * @returns true when Long can carry every value
+ */
+function allSafeIntegers(column) {
+    for (let r = 0; r < column.length; r++) {
+        if (column.isSet(r) && !itemsOf(column, r).every((v) => typeof v === "number" && Number.isSafeInteger(v))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The largest value of a numeric column (or of its list items).
+ * @param column - the column
+ * @returns the maximum, 0 when empty
+ */
+function maxValue(column) {
+    let max = 0;
+    for (let r = 0; r < column.length; r++) {
+        if (column.isSet(r)) {
+            for (const v of itemsOf(column, r)) {
+                if (typeof v === "number" && v > max) {
+                    max = v;
+                }
+            }
+        }
+    }
+    return max;
+}
+/**
+ * The CyCSV text of one value of a class.
+ * @param value - the value
+ * @param javaClass - the scalar class
+ * @param dtype - the dtype it came from
+ * @returns the text Cytoscape's `valueOf` reads back
+ */
+function valueText(value, javaClass, dtype) {
+    if (javaClass === BOOLEAN) {
+        return value === true ? "true" : "false";
+    }
+    if (javaClass === DOUBLE) {
+        return formatDecimal(value, dtype === "f32" ? "f32" : "f64");
+    }
+    if (javaClass === INTEGER || javaClass === LONG) {
+        return String(value);
+    }
+    return textOf(value);
+}
+/**
+ * A value as text: strings as they are, numbers in their shortest form, anything else as JSON.
+ * @param value - the value
+ * @returns the text
+ */
+function textOf(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return formatF64(value);
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (ArrayBuffer.isView(value)) {
+        return JSON.stringify(Array.from(value).map(finiteOrText));
+    }
+    return JSON.stringify(value) ?? "";
+}
+/**
+ * A number for JSON text (JSON has no NaN or infinities: those are written as their names).
+ * @param v - the number
+ * @returns the number or its name
+ */
+function finiteOrText(v) {
+    return Number.isFinite(v) ? v : String(v);
+}
+/**
+ * A snapshot column as a table candidate: its class and cell texts.
+ * @param column - the column
+ * @param name - the name it wants
+ * @returns the candidate
+ */
+function candidateOf(column, name) {
+    const { meta } = column;
+    if (column.dtype === "list") {
+        const item = meta.itemDtype;
+        const itemClass = scalarClass(column, item === "json" ? null : item);
+        return {
+            name,
+            source: column,
+            javaClass: `java.util.List<${itemClass}>`,
+            cell: (row) => column.isSet(row)
+                ? [...column.sliceOf(row)].map((v) => valueText(v, itemClass, item)).join("\n")
+                : null,
+        };
+    }
+    const javaClass = meta.dtype === "json" || meta.components > 1 ? STRING : scalarClass(column, meta.dtype);
+    return {
+        name,
+        source: column,
+        javaClass,
+        cell: (row) => (column.isSet(row) ? valueText(column.value(row), javaClass, meta.dtype) : null),
+    };
+}
+/**
+ * Settle the names of a table's columns: case-insensitively unique, `SUID` and Cytoscape's own
+ * columns of another class renamed `<name>#2`, `#3`...
+ * @param domain - the table
+ * @param candidates - the columns in order
+ * @param note - the recorder
+ * @returns the table's columns (the SUID key first)
+ */
+function settleNames(domain, candidates, note) {
+    const taken = new Set(["suid"]);
+    const out = [];
+    for (const c of candidates) {
+        const lower = c.name.toLowerCase();
+        const builtIn = BUILT_IN[domain].get(lower);
+        let { name } = c;
+        const clash = builtIn !== undefined && builtIn !== c.javaClass ? builtIn : null;
+        if (taken.has(lower) || clash !== null) {
+            let k = 2;
+            while (taken.has(`${lower}#${k}`)) {
+                k++;
+            }
+            name = `${c.name}#${k}`;
+            const why = renameReason(lower, clash);
+            const set = c.source === null ? null : c.source.length - c.source.nullCount;
+            note(LOSS.COLUMN_NAME_CHANGED, `${domain} column "${c.name}" is written as "${name}": ${why}`, c.name, set);
+        }
+        else if (c.source !== null && IMPORTER_NAMES[domain].has(c.name)) {
+            note(LOSS.COLUMN_NAME_CHANGED, `${domain} column "${c.name}" is written to the session's table and reads back as "${c.name}#2": graph-io's session reader makes a "${c.name}" column of its own`, c.name, c.source.length - c.source.nullCount);
+        }
+        taken.add(name.toLowerCase());
+        out.push({ name, javaClass: c.javaClass, cell: c.cell });
+    }
+    return out;
+}
+/**
+ * Why a column is renamed.
+ * @param lower - the column name, lower-cased
+ * @param clash - the Java class of Cytoscape's own column of that name when it holds another, else null
+ * @returns the reason
+ */
+function renameReason(lower, clash) {
+    if (lower === "suid") {
+        return "SUID is Cytoscape's key column";
+    }
+    if (clash !== null) {
+        return `Cytoscape's own "${lower}" column holds ${clash}`;
+    }
+    return "its name is taken (Cytoscape column names ignore case)";
+}
+/**
+ * Java's `String.split("\n")`: trailing empty items are removed.
+ * @param text - the cell
+ * @returns the items
+ */
+function javaSplit(text) {
+    if (!text.includes("\n")) {
+        return [text];
+    }
+    const items = text.split("\n");
+    while (items.at(-1) === "") {
+        items.pop();
+    }
+    return items;
+}
+/**
+ * The notes of one written column: what CyCSV cannot hold of its cells.
+ * @param domain - the table
+ * @param c - the candidate
+ * @param rows - the row count
+ * @param note - the recorder
+ */
+function cellNotes(domain, c, rows, note) {
+    const { source } = c;
+    if (source === null) {
+        return;
+    }
+    const label = `${domain} column "${source.meta.name}"`;
+    const { name } = source.meta;
+    const text = c.javaClass === STRING;
+    const { unset, equations, lists, set, heuristic } = cellCounts(c, source, rows);
+    if (source.dtype === "json") {
+        note(CYS_LOSS.JSON_AS_STRING, `${label} holds nested values; written as their JSON text`, name, set);
+    }
+    if (set === 0 && (!text || rows === 0)) {
+        note(LOSS.EMPTY_COLUMN, `${label} has no value; it is not in the re-import`, name, null);
+        return;
+    }
+    if (text && unset > 0) {
+        note(CYS_LOSS.UNSET_AS_EMPTY_STRING, `${label}: ${unset} unset cell${plural(unset)} ${agree(unset, "is", "are")} written empty and read back as ""`, name, unset);
+    }
+    if (lists > 0) {
+        note(CYS_LOSS.LIST_ITEMS, `${label}: ${lists} list cell${plural(lists)} ${agree(lists, "reads", "read")} back changed (an unset or empty list of text as [""], an empty list of numbers unset, trailing empty items dropped, items holding a newline split)`, name, lists);
+    }
+    if (equations > 0) {
+        note(CYS_LOSS.TEXT_AS_EQUATION, `${label}: ${equations} cell${plural(equations)} start with "=", which Cytoscape reads as a formula (an error cell); graph-io reads them back as text`, name, equations);
+    }
+    if (text && (source.dtype === "string" || source.dtype === "dict")) {
+        const readsAs = heuristic.decide();
+        if (readsAs !== source.dtype) {
+            note(LOSS.STORAGE_CLASS, `${label} reads back as ${readsAs} (the cardinality heuristic)`, name, null);
+        }
+    }
+}
+/**
+ * Count what CyCSV changes in a column's cells: unset cells, text read as a formula, lists that
+ * read back changed; and feed the text cells to the dict heuristic.
+ * @param c - the candidate
+ * @param source - its column
+ * @param rows - the row count
+ * @returns the counts and the heuristic
+ */
+function cellCounts(c, source, rows) {
+    const text = c.javaClass === STRING;
+    const stringList = c.javaClass === `java.util.List<${STRING}>`;
+    const counts = { unset: 0, equations: 0, lists: 0, set: 0, heuristic: new DictHeuristic() };
+    for (let r = 0; r < rows; r++) {
+        const cell = c.cell(r);
+        if (cell === null) {
+            counts.unset++;
+        }
+        else {
+            counts.set++;
+        }
+        const written = cell ?? "";
+        if (text && !counts.heuristic.decided) {
+            counts.heuristic.observe(written);
+        }
+        if (written.startsWith("=")) {
+            counts.equations++;
+        }
+        else if (source.dtype === "list" && listChanges(source, r, cell, stringList)) {
+            counts.lists++;
+        }
+    }
+    return counts;
+}
+/**
+ * Whether a list cell reads back changed from the text CyCSV writes for it.
+ * @param source - the list column
+ * @param r - the row
+ * @param cell - the written text, or null when unset
+ * @param stringList - whether Cytoscape reads the column as a list of text
+ * @returns true when it changes
+ */
+function listChanges(source, r, cell, stringList) {
+    const written = cell ?? "";
+    let back = null;
+    if (stringList) {
+        back = written.length === 0 ? [""] : javaSplit(written);
+    }
+    else if (written.length > 0) {
+        back = javaSplit(written).filter((item) => item.length > 0);
+    }
+    const items = cell === null ? null : [...source.sliceOf(r)].map((v) => valueText(v, "", null));
+    if (back === null || items === null) {
+        return back !== items;
+    }
+    return back.length !== items.length || (stringList && back.some((b, i) => b !== items[i]));
+}
+/**
+ * Whether a column is the z slot (a role-less f64 `z` column, as the importer makes it).
+ * @param column - the column
+ * @returns true for the z column
+ */
+function isZ(column) {
+    return column.meta.name === Z_COLUMN && column.meta.dtype === "f64" && column.meta.role === null;
+}
+/**
+ * The candidates of the node or edge table: the label as `name`, then the exporter's own columns,
+ * then every other column in order.
+ * @param snapshot - the snapshot
+ * @param domain - node or edge
+ * @param own - the exporter's columns after the label
+ * @param skip - columns written elsewhere
+ * @param note - the recorder
+ * @returns the candidates
+ */
+function elementCandidates(snapshot, domain, own, skip, note) {
+    const table = domain === "node" ? snapshot.nodes : snapshot.edges;
+    const label = table.byRole("label");
+    const out = [];
+    if (label !== null) {
+        const c = candidateOf(label, "name");
+        out.push({ ...c, javaClass: STRING, cell: (row) => (label.isSet(row) ? textOf(label.value(row)) : null) });
+        if (label.dtype !== "string" && label.dtype !== "dict") {
+            note(LOSS.DTYPE, `${domain} label column "${label.meta.name}" (${label.dtype}) is written as text and reads back as string`, label.meta.name, label.length - label.nullCount);
+        }
+    }
+    out.push(...own);
+    for (const column of table) {
+        const { role } = column.meta;
+        if (column === label || (role !== null && (SKIPPED_ROLES.has(role) || role === "id")) || skip(column)) {
+            continue;
+        }
+        out.push(candidateOf(column, column.meta.name));
+        if (label === null &&
+            role === null &&
+            column.meta.name === "name" &&
+            scalarClass(column, column.dtype) === STRING) {
+            note(LOSS.ROLE_ASSUMED, `${domain} column "name" is Cytoscape's name and reads back as the label`, "name", column.length - column.nullCount);
+        }
+    }
+    return out;
+}
+/**
+ * Settle a table and record the notes of its cells.
+ * @param domain - the table
+ * @param candidates - its columns
+ * @param rows - its row count
+ * @param note - the recorder
+ * @returns the columns
+ */
+function planTable(domain, candidates, rows, note) {
+    for (const c of candidates) {
+        cellNotes(domain, c, rows, note);
+    }
+    return settleNames(domain, candidates, note);
+}
+/**
+ * Note the node ids whose text changes on the way back: numbers read back as text, and the error
+ * for two ids with the same text.
+ * @param snapshot - the snapshot
+ * @param note - the recorder
+ * @returns the error the save throws for a collision, or null
+ */
+function idTextNotes(snapshot, note) {
+    let collisions = 0;
+    let numeric = 0;
+    const texts = new Set();
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        const id = snapshot.ids.idOf(i);
+        numeric += typeof id === "number" ? 1 : 0;
+        const text = String(id);
+        if (texts.has(text)) {
+            collisions++;
+        }
+        texts.add(text);
+    }
+    let fatal = null;
+    if (collisions > 0) {
+        note(LOSS.ID_TEXT_COLLISION, `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id (a number and a string); the save fails with E_INVALID_ID`, null, collisions);
+        fatal = new GraphFormatError("E_INVALID_ID", `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id`, { reason: "collision", count: collisions });
+    }
+    if (numeric > 0) {
+        note(LOSS.ID_TEXT_TYPE, `${numeric} numeric node id${plural(numeric)} ${agree(numeric, "reads", "read")} back as their text`, null, numeric);
+    }
+    return fatal;
+}
+/**
+ * Note the node ids that are not positive integers: renumbered under "mangle", else refused.
+ * @param snapshot - the snapshot
+ * @param bad - the indices of those ids
+ * @param mangle - whether sanitizeIds is "mangle"
+ * @param note - the recorder
+ * @returns the error the save throws, or null under "mangle"
+ */
+function badIdNotes(snapshot, bad, mangle, note) {
+    if (mangle) {
+        note(LOSS.ID_MANGLED, `${bad.length} node id${plural(bad.length)} that ${agree(bad.length, "is", "are")} not positive integers ${agree(bad.length, "is", "are")} renumbered, since Cytoscape ids are positive integers; the originals are kept in the "${ORIGINAL_ID_ATTRIBUTE}" column (restored by restoreMangledIds)`, null, bad.length);
+        return null;
+    }
+    note(LOSS.ID_CHARSET, `${bad.length} node id${plural(bad.length)} ${agree(bad.length, "is", "are")} not positive integers, which Cytoscape requires; the save fails unless sanitizeIds is "mangle"`, null, bad.length);
+    const first = snapshot.ids.idOf(bad[0]);
+    return new GraphFormatError("E_INVALID_ID", `${bad.length} node id${plural(bad.length)} cannot be written as Cytoscape ids, which are positive integers (first: ${JSON.stringify(first)} at index ${bad[0]}); pass sanitizeIds: "mangle" to rewrite them`, { reason: "charset", charset: "integer", count: bad.length, index: bad[0] });
+}
+/**
+ * The SUIDs: node ids that are positive integers keep them, the others get new ones (or refuse
+ * under sanitizeIds "error"); edge ids likewise, from the id role column. Every new SUID comes
+ * from one counter above the kept ones.
+ * @param snapshot - the snapshot
+ * @param common - the resolved common options
+ * @param note - the recorder
+ * @returns the SUIDs
+ */
+function planIds(snapshot, common, note) {
+    const { kept, bad } = keptNodeSuids(snapshot);
+    const collision = idTextNotes(snapshot, note);
+    const charset = bad.length > 0 ? badIdNotes(snapshot, bad, common.sanitizeIds === "mangle", note) : null;
+    const fatal = collision ?? charset;
+    const nodeSet = new Set(kept.filter((s) => s > 0));
+    const edgeKept = keptEdgeSuids(snapshot, nodeSet);
+    let next = 1;
+    for (const s of [...nodeSet, ...edgeKept]) {
+        next = Math.max(next, s + 1);
+    }
+    const nodeSuids = kept.map((s) => (s > 0 ? s : next++));
+    const idColumn = snapshot.edges.byRole("id");
+    let generated = 0;
+    const edgeSuids = edgeKept.map((s) => {
+        if (s > 0) {
+            return s;
+        }
+        generated++;
+        return next++;
+    });
+    if (idColumn !== null && generated > 0) {
+        note(LOSS.EDGE_IDS_GENERATED, `${generated} edge${plural(generated)} ${agree(generated, "has", "have")} no distinct positive integer id in "${idColumn.meta.name}"; they are written with new positive integer ids`, idColumn.meta.name, generated);
+    }
+    if (idColumn !== null && idColumn.dtype !== "string") {
+        note(LOSS.DTYPE, `edge id column "${idColumn.meta.name}" is ${idColumn.dtype}; edge ids read back as text`, idColumn.meta.name, snapshot.edgeCount - idColumn.nullCount);
+    }
+    return { nodeSuids, edgeSuids, next, fatal, mangled: common.sanitizeIds === "mangle" && bad.length > 0 };
+}
+/**
+ * The columns of the network's own table: its name (from meta.name unless a text graph column
+ * holds it), its description, and the graph columns.
+ * @param snapshot - the snapshot
+ * @param name - the network name
+ * @returns the candidates
+ */
+function networkCandidates(snapshot, name) {
+    const out = [];
+    const graphName = snapshot.graph.get("name");
+    if (graphName === null || (graphName.dtype !== "string" && graphName.dtype !== "dict")) {
+        out.push({ name: "name", source: null, javaClass: STRING, cell: () => name });
+    }
+    const { description } = snapshot.meta;
+    if (description !== null && snapshot.graph.get("description") === null) {
+        out.push({ name: "description", source: null, javaClass: STRING, cell: () => description });
+    }
+    for (const column of snapshot.graph) {
+        out.push(candidateOf(column, column.meta.name));
+    }
+    return out;
+}
+/**
+ * Plan an export: the notes, the fatal condition, the SUIDs and the tables.
+ * @param snapshot - the snapshot
+ * @param common - the resolved common options
+ * @returns the plan
+ */
+function plan(snapshot, common) {
+    const notes = [];
+    const note = (code, message, column = null, count = null) => {
+        notes.push(Object.freeze({ code, message, column, count }));
+    };
+    for (const gen of checkCapabilities(snapshot, CYS_CAPABILITIES, common, {
+        roles: SLOT_ROLES,
+        roleNames: ROLE_NAMES,
+        positionDtype: "f32",
+    })) {
+        // json is reported per column below; ids by the SUID rule (positive integers)
+        if (gen.code !== LOSS.JSON && gen.code !== LOSS.ID_CHARSET && gen.code !== LOSS.ID_MANGLED) {
+            notes.push(gen);
+        }
+    }
+    const ids = planIds(snapshot, common, note);
+    const { nodeSuids, edgeSuids, mangled, fatal } = ids;
+    let { next } = ids;
+    const rootSuid = next++;
+    const subSuid = next++;
+    // direction
+    const folding = pairFolding(snapshot);
+    if (folding.mutualCount > 0) {
+        note(LOSS.MUTUAL_EXPANDED, `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed edges; the mutual mark is lost`, null, folding.mutualCount);
+    }
+    // positions
+    const position = snapshot.nodes.byRole("position");
+    const z = [...snapshot.nodes].find(isZ) ?? null;
+    const positionZ = position !== null && z === null;
+    if (position !== null) {
+        positionNotes(position, z, note);
+    }
+    const placed = (position !== null && position.nullCount < position.length) || (z !== null && z.nullCount < z.length);
+    const viewSuid = placed ? next++ : null;
+    const viewNodeBase = next;
+    // node table
+    const nodeOwn = mangled
+        ? [
+            {
+                name: ORIGINAL_ID_ATTRIBUTE,
+                source: null,
+                javaClass: STRING,
+                // every node carries its original, so an empty id ("") is told apart from an unset cell
+                cell: (row) => String(snapshot.ids.idOf(row)),
+            },
+        ]
+        : [];
+    const nodeTable = planTable("node", elementCandidates(snapshot, "node", nodeOwn, (c) => placed && c === z, note), snapshot.nodeCount, note);
+    // edge table
+    const weights = explicitWeights(snapshot);
+    const plainWeight = snapshot.edges.get("weight");
+    if (plainWeight !== null && plainWeight.meta.role === null && !weights.weighted) {
+        note(LOSS.WEIGHT_KEY_CLASH, `edge column "weight" reads back as the edge weight`, "weight", null);
+    }
+    const edgeOwn = weights.weighted
+        ? [
+            {
+                name: "weight",
+                source: null,
+                javaClass: DOUBLE,
+                cell: (e) => (weights.isExplicit(e) ? formatDecimal(weights.value(e)) : null),
+            },
+        ]
+        : [];
+    const edgeRows = snapshot.edgeCount;
+    const edgeTable = planTable("edge", elementCandidates(snapshot, "edge", edgeOwn, () => false, note), edgeRows, note);
+    const name = snapshot.meta.name ?? DEFAULT_NAME;
+    const networkTable = planTable("network", networkCandidates(snapshot, name), 1, note);
+    const rootTable = [{ name: "name", javaClass: STRING, cell: () => name }];
+    return {
+        notes,
+        fatal,
+        nodeSuids,
+        edgeSuids,
+        rootSuid,
+        subSuid,
+        viewSuid,
+        viewNodeBase,
+        name,
+        folding,
+        nodeTable,
+        edgeTable,
+        networkTable,
+        rootTable,
+        position,
+        z: placed ? z : null,
+        positionZ,
+    };
+}
+/**
+ * The notes of the position column: its shape, non-finite coordinates, and a z that reads back
+ * in the z column.
+ * @param position - the position column
+ * @param z - the z column, or null
+ * @param note - the recorder
+ */
+function positionNotes(position, z, note) {
+    const { name, components } = position.meta;
+    if (components !== 3) {
+        note(CYS_LOSS.POSITION, `position column "${name}" has ${components} component${plural(components)} and reads back with 3`, name, null);
+    }
+    let nonFinite = 0;
+    let depth = 0;
+    for (let r = 0; r < position.length; r++) {
+        if (!position.isSet(r)) {
+            continue;
+        }
+        const xyz = Array.from(position.value(r));
+        if (xyz.slice(0, 2).some((v) => !Number.isFinite(v))) {
+            nonFinite++;
+        }
+        else if ((xyz[2] ?? 0) !== 0) {
+            depth++;
+        }
+    }
+    if (nonFinite > 0) {
+        note(CYS_LOSS.POSITION, `${nonFinite} position${plural(nonFinite)} with a non-finite coordinate ${agree(nonFinite, "is", "are")} not written`, name, nonFinite);
+    }
+    if (depth > 0) {
+        note(CYS_LOSS.POSITION, z === null
+            ? `${depth} position${plural(depth)} ${agree(depth, "has", "have")} a z; it is written as the view's z and reads back in the z column`
+            : `${depth} position${plural(depth)} ${agree(depth, "has", "have")} a z, but the view's z holds the z column; the position z is lost`, name, depth);
+    }
+}
+// ============================================================ writing
+/**
+ * Cytoscape's `SessionUtil.escape`: Java's `URLEncoder.encode(text, "UTF-8")` (letters, digits
+ * and `.-*_` kept, space as `+`, everything else `%XX`), then `-` as `%2D`.
+ * @param text - the text
+ * @returns the escaped text
+ * @category Plugin helpers
+ */
+export function sessionEscape(text) {
+    const wellFormed = text.replaceAll(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+    return encodeURIComponent(wellFormed)
+        .replaceAll(/[!~'()]/g, (c) => `%${(c.codePointAt(0) ?? 0).toString(16).toUpperCase()}`)
+        .replaceAll("%20", "+")
+        .replaceAll("-", "%2D");
+}
+/**
+ * One CyCSV table (schema version 1): the key column SUID, then the columns.
+ * @param title - the table title
+ * @param columns - the columns
+ * @param rows - the SUID of each row, with its row index
+ * @yields the table text
+ * @returns nothing
+ */
+function* cyTable(title, columns, rows) {
+    const line = (cells) => `${cells.map((c) => quoteCsvCell(c)).join(",")}\n`;
+    yield line(["CyCSV-Version", "1"]);
+    yield line(["SUID", ...columns.map((c) => c.name)]);
+    yield line([LONG, ...columns.map((c) => c.javaClass)]);
+    yield line(["", ...columns.map(() => "mutable")]);
+    yield line([title, ""]);
+    for (const [suid, row] of rows) {
+        yield line([String(suid), ...columns.map((c) => c.cell(row) ?? "")]);
+    }
+}
+/** The XML declaration and the namespaces of a session XGMML document. */
+const XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+const NAMESPACES = `xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xlink="${XLINK_NAMESPACE}" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:cy="${CY_NAMESPACE}" xmlns="${XGMML_NAMESPACE}"`;
+/**
+ * The network file: the root network holding the one registered subnetwork, nodes and edges by
+ * SUID. No attributes: a 3.x session keeps them in the tables.
+ * @param snapshot - the snapshot
+ * @param p - the plan
+ * @yields the document's text
+ * @returns nothing
+ */
+function* networkFile(snapshot, p) {
+    const label = !hasIllegalXmlChar(p.name) ? ` label="${escapeXmlAttribute(p.name)}"` : "";
+    yield XML_DECLARATION;
+    yield `<graph id="${p.rootSuid}"${label} directed="${snapshot.directed ? "1" : "0"}" cy:view="0" cy:registered="0" cy:documentVersion="3.0" ${NAMESPACES}>\n`;
+    yield `  <att>\n    <graph id="${p.subSuid}"${label} cy:registered="1">\n`;
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        yield `      <node id="${p.nodeSuids[i]}"/>\n`;
+    }
+    const { src, dst } = snapshot.edgeList();
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (p.folding.folded(e)) {
+            continue;
+        }
+        const directed = snapshot.directed && p.folding.sourceDirected(e);
+        yield `      <edge id="${p.edgeSuids[e]}" source="${p.nodeSuids[src[e]]}" target="${p.nodeSuids[dst[e]]}" cy:directed="${directed ? "1" : "0"}"/>\n`;
+    }
+    yield "    </graph>\n  </att>\n</graph>\n";
+}
+/**
+ * The view file: one view node per placed node, x and y (y negated back to screen coordinates)
+ * and z.
+ * @param snapshot - the snapshot
+ * @param p - the plan
+ * @param viewSuid - the view's SUID
+ * @yields the document's text
+ * @returns nothing
+ */
+function* viewFile(snapshot, p, viewSuid) {
+    yield XML_DECLARATION;
+    yield `<graph id="${viewSuid}" label="${viewSuid}" cy:view="1" cy:networkId="${p.subSuid}" cy:visualStyle="default" cy:rendererId="org.cytoscape.ding" cy:documentVersion="3.0" ${NAMESPACES}>\n`;
+    let view = p.viewNodeBase;
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        const coords = viewCoords(p, i);
+        if (coords.length > 0) {
+            yield `  <node id="${view++}" cy:nodeId="${p.nodeSuids[i]}">\n    <graphics ${coords.join(" ")}/>\n  </node>\n`;
+        }
+    }
+    yield "</graph>\n";
+}
+/**
+ * The graphics attributes of one node's view: x and y (y down, as Cytoscape draws), and z.
+ * @param p - the plan
+ * @param i - the node
+ * @returns the attributes, none when the node has no position
+ */
+function viewCoords(p, i) {
+    const coords = [];
+    if (p.position?.isSet(i) === true) {
+        const [x, y, z] = Array.from(p.position.value(i));
+        if (Number.isFinite(x) && Number.isFinite(y)) {
+            coords.push(`x="${formatF32(x)}"`, `y="${formatF32(y === 0 ? 0 : -y)}"`);
+        }
+        if (Number.isFinite(x) &&
+            Number.isFinite(y) &&
+            p.positionZ &&
+            z !== undefined &&
+            z !== 0 &&
+            Number.isFinite(z)) {
+            coords.push(`z="${formatF32(z)}"`);
+        }
+    }
+    if (p.z?.isSet(i) === true) {
+        coords.push(`z="${formatDecimal(p.z.value(i))}"`);
+    }
+    return coords;
+}
+/**
+ * The text of string parts, UTF-8 encoded.
+ * @param parts - the parts
+ * @returns the bytes
+ */
+function encode(parts) {
+    let text = "";
+    for (const part of parts) {
+        text += part;
+    }
+    return new TextEncoder().encode(text);
+}
+/**
+ * The archive's entries, each built when the zip writer asks for it.
+ * @param snapshot - the snapshot
+ * @param p - the plan
+ * @yields the entries
+ * @returns nothing
+ */
+function* entries(snapshot, p) {
+    if (p.fatal !== null) {
+        throw p.fatal;
+    }
+    const name = sessionEscape(p.name);
+    const tables = `${ROOT_FOLDER}tables/${p.subSuid}-${name}/LOCAL_ATTRS-org.cytoscape.model.`;
+    const rowsOf = (suids, skip) => suids.flatMap((suid, row) => (skip?.(row) === true ? [] : [[suid, row]]));
+    const nodeTable = `${p.name} default node`;
+    const edgeTable = `${p.name} default edge`;
+    const networkTable = `${p.name} default network`;
+    yield { name: `${ROOT_FOLDER}3.0.0.version`, data: new Uint8Array(0) };
+    yield { name: `${ROOT_FOLDER}networks/${p.rootSuid}-${name}.xgmml`, data: encode(networkFile(snapshot, p)) };
+    yield {
+        name: `${tables}CyNode-${sessionEscape(nodeTable)}.cytable`,
+        data: encode(cyTable(nodeTable, p.nodeTable, rowsOf(p.nodeSuids))),
+    };
+    yield {
+        name: `${tables}CyEdge-${sessionEscape(edgeTable)}.cytable`,
+        data: encode(cyTable(edgeTable, p.edgeTable, rowsOf(p.edgeSuids, (e) => p.folding.folded(e)))),
+    };
+    yield {
+        name: `${tables}CyNetwork-${sessionEscape(networkTable)}.cytable`,
+        data: encode(cyTable(networkTable, p.networkTable, [[p.subSuid, 0]])),
+    };
+    yield {
+        name: `${ROOT_FOLDER}tables/${p.rootSuid}-${name}/LOCAL_ATTRS-org.cytoscape.model.CyNetwork-${p.rootSuid}+default+network.cytable`,
+        data: encode(cyTable(`${p.rootSuid} default network`, p.rootTable, [[p.rootSuid, 0]])),
+    };
+    if (p.viewSuid !== null) {
+        yield {
+            name: `${ROOT_FOLDER}views/${p.subSuid}-${p.viewSuid}-${name}.xgmml`,
+            data: encode(viewFile(snapshot, p, p.viewSuid)),
+        };
+    }
+}
+/**
+ * The archive as byte chunks.
+ * @param snapshot - the snapshot
+ * @param options - the options
+ * @yields the bytes
+ * @returns nothing
+ */
+async function* write(snapshot, options) {
+    const p = plan(snapshot, resolveExportOptions(options));
+    await Promise.resolve();
+    yield* writeZip(entries(snapshot, p));
+}
+/**
+ * The Cytoscape session exporter.
+ * @category Built-in formats
+ */
+export const cysExporter = Object.freeze({
+    format: FORMAT,
+    options: Object.freeze([]),
+    capabilities: CYS_CAPABILITIES,
+    /**
+     * Pre-flight: what export() would lose, without writing anything.
+     * @param snapshot - the snapshot
+     * @param options - the common options
+     * @returns the notes, empty when the export is exact
+     */
+    check(snapshot, options) {
+        return Object.freeze([...plan(snapshot, resolveExportOptions(options)).notes]);
+    },
+    /**
+     * Write the session as zip bytes (stored entries, one at a time).
+     * @param snapshot - the snapshot
+     * @param options - the common options
+     * @returns the bytes
+     */
+    export(snapshot, options) {
+        return write(snapshot, options);
+    },
+    /**
+     * A session is a zip archive, not text: always rejects with E_UNSUPPORTED (use exportGraphToBytes() or exportGraphToBlob()).
+     * @returns never
+     */
+    exportToString() {
+        return Promise.reject(new GraphFormatError("E_UNSUPPORTED", "a Cytoscape session is a zip file, not text; use exportGraphToBytes() or exportGraphToBlob()", { reason: "binary" }));
+    },
+});
+//# sourceMappingURL=exporter.js.map