@graphty/graph-io 0.3.39 → 0.3.41

package/src/formats/gml/importer.ts

@@ -518,31 +518,50 @@ class GmlImport {
             if (key === "graph" && !record && scalarGraph < 0) {
                 scalarGraph = v;
             }
-            if (key === "graph" && record) {
-                if (this.graphCount++ === this.which) {
-                    this.graphOpen = v;
-                    this.scanGraph(v);
-                }
-            } else if (key === "Creator" && !record && this.creatorToken < 0) {
-                this.creatorToken = v;
-            } else if (key === "Version" && !record && this.versionToken < 0) {
-                this.versionToken = v;
-            } else {
-                this.observe(this.topSchema, "graph", key, v, TOP_SEQ);
-            }
+            this.scanTopPair(key, record, v);
         }
         if (this.graphOpen < 0) {
-            if (scalarGraph >= 0) {
-                this.report.fail(
-                    NO_GRAPH_CODE,
-                    `the graph key at line ${t.line[scalarGraph]} holds ${describeValue(t, scalarGraph)}, not a [ ... ] block; the input contains no graph block`,
-                    { line: t.line[scalarGraph] },
-                );
+            this.failNoGraph(t, scalarGraph);
+        }
+    }
+
+    /**
+     * Handle one top-level pair other than a scalar `graph`.
+     * @param key - the key
+     * @param record - whether the value is a `[ ... ]` block
+     * @param v - the value token
+     */
+    private scanTopPair(key: string, record: boolean, v: number): void {
+        if (key === "graph" && record) {
+            if (this.graphCount++ === this.which) {
+                this.graphOpen = v;
+                this.scanGraph(v);
             }
-            this.report.fail(NO_GRAPH_CODE, "the input contains no graph [ ... ] block", { line: null });
+        } else if (key === "Creator" && !record && this.creatorToken < 0) {
+            this.creatorToken = v;
+        } else if (key === "Version" && !record && this.versionToken < 0) {
+            this.versionToken = v;
+        } else {
+            this.observe(this.topSchema, "graph", key, v, TOP_SEQ);
         }
     }
 
+    /**
+     * Fail because the input holds no graph block.
+     * @param t - the tokens
+     * @param scalarGraph - the token of a scalar `graph` key, or -1
+     */
+    private failNoGraph(t: ReturnType<GmlImport["requireTokens"]>, scalarGraph: number): void {
+        if (scalarGraph >= 0) {
+            this.report.fail(
+                NO_GRAPH_CODE,
+                `the graph key at line ${t.line[scalarGraph]} holds ${describeValue(t, scalarGraph)}, not a [ ... ] block; the input contains no graph block`,
+                { line: t.line[scalarGraph] },
+            );
+        }
+        this.report.fail(NO_GRAPH_CODE, "the input contains no graph [ ... ] block", { line: null });
+    }
+
     /**
      * Walk the graph block for the schema.
      * @param open - the index of the block's `[`
@@ -592,31 +611,43 @@ class GmlImport {
         const close = t.match[open];
         const seq = this.seq++;
         const schema = domain === "node" ? this.nodeSchema : this.edgeSchema;
-        const { weightFrom, restoreMangledIds } = this.options;
         for (let p = open + 1; p < close; p = t.nextPair(p)) {
             const key = t.textOf(p);
             const v = p + 1;
-            if (domain === "node") {
-                if (key === "id") {
-                    continue;
-                }
-                if (key === ORIGINAL_ID_KEY && restoreMangledIds) {
-                    this.hasOriginalId = true;
-                    continue;
-                }
-            } else {
-                if (key === "source" || key === "target" || key === "directed") {
-                    continue;
-                }
-                if (key === weightFrom) {
-                    this.weightKinds |= kindBit(t, v);
-                    continue;
-                }
+            if (this.skipsKey(domain, key, v)) {
+                continue;
             }
             this.observe(schema, domain, key, v, seq);
         }
     }
 
+    /**
+     * Whether a key of a node or edge block is structural (id, endpoints, weight, original id), not
+     * a column; notes the original id and the weight's kinds on the way.
+     * @param domain - node or edge
+     * @param key - the key
+     * @param v - the value token
+     * @returns true when the key is not a column
+     */
+    private skipsKey(domain: "node" | "edge", key: string, v: number): boolean {
+        const { weightFrom, restoreMangledIds } = this.options;
+        if (domain === "node") {
+            if (key === ORIGINAL_ID_KEY && restoreMangledIds) {
+                this.hasOriginalId = true;
+                return true;
+            }
+            return key === "id";
+        }
+        if (key === "source" || key === "target" || key === "directed") {
+            return true;
+        }
+        if (key === weightFrom) {
+            this.weightKinds |= kindBit(this.requireTokens(), v);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Record one value of one key in a table's schema.
      * @param schema - the table's schema
@@ -816,26 +847,12 @@ class GmlImport {
     }
 
     /**
-     * The plan of one schema entry.
+     * Warn about a key that mixes numbers and strings, or holds integers beyond 2^53.
      * @param domain - the table
      * @param entry - the schema entry
-     * @param top - whether the key is a top-level one (graph table)
-     * @returns the plan
+     * @param asText - whether the integers are kept as text
      */
-    private planOf(domain: "node" | "edge" | "graph", entry: KeySchema, top = false): ColumnPlan {
-        // long: "string" keeps every digit of an integer key that holds values beyond 2^53, as text
-        const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
-        const kind = asText ? "string" : kindOf(entry);
-        let scalar: ScalarDtype = dtypeOfKind(kind, entry);
-        if (
-            scalar === "string" &&
-            !entry.list &&
-            entry.dict !== null &&
-            entry.kinds === KIND_STRING &&
-            entry.dict.decide() === "dict"
-        ) {
-            scalar = "dict";
-        }
+    private warnKinds(domain: "node" | "edge" | "graph", entry: KeySchema, asText: boolean): void {
         if (
             (entry.kinds & KIND_STRING) !== 0 &&
             (entry.kinds & (KIND_INT | KIND_REAL)) !== 0 &&
@@ -858,6 +875,54 @@ class GmlImport {
                 `${PRECISION_CODE}:${domain}:${entry.key}`,
             );
         }
+    }
+
+    /**
+     * The plan of a node `graphics` record: the plan plus its position and rest columns.
+     * @param plan - the record's plan
+     * @param entry - the schema entry
+     * @returns the plan with its position (and rest) plans
+     */
+    private graphicsPlan(plan: ColumnPlan, entry: KeySchema): ColumnPlan {
+        const taken = (candidate: string): boolean =>
+            this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
+        const position: ColumnPlan = {
+            ...plan,
+            name: uniqueColumnName("position", "graphics", taken),
+            dtype: "f64",
+            itemDtype: null,
+            kind: "real",
+            list: false,
+            role: "position",
+        };
+        const rest: ColumnPlan | null = entry.rest
+            ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false }
+            : null;
+        return { ...plan, position, rest };
+    }
+
+    /**
+     * The plan of one schema entry.
+     * @param domain - the table
+     * @param entry - the schema entry
+     * @param top - whether the key is a top-level one (graph table)
+     * @returns the plan
+     */
+    private planOf(domain: "node" | "edge" | "graph", entry: KeySchema, top = false): ColumnPlan {
+        // long: "string" keeps every digit of an integer key that holds values beyond 2^53, as text
+        const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
+        const kind = asText ? "string" : kindOf(entry);
+        let scalar: ScalarDtype = dtypeOfKind(kind, entry);
+        if (
+            scalar === "string" &&
+            !entry.list &&
+            entry.dict !== null &&
+            entry.kinds === KIND_STRING &&
+            entry.dict.decide() === "dict"
+        ) {
+            scalar = "dict";
+        }
+        this.warnKinds(domain, entry, asText);
         const name = domain === "graph" ? this.uniqueGraphName(entry.key) : entry.key;
         let itemDtype: ScalarDtype | null = null;
         if (entry.list) {
@@ -880,21 +945,7 @@ class GmlImport {
             seq: Number.NEGATIVE_INFINITY,
         };
         if (domain === "node" && entry.key === "graphics" && this.positions && (entry.kinds & KIND_RECORD) !== 0) {
-            const taken = (candidate: string): boolean =>
-                this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
-            const position: ColumnPlan = {
-                ...plan,
-                name: uniqueColumnName("position", "graphics", taken),
-                dtype: "f64",
-                itemDtype: null,
-                kind: "real",
-                list: false,
-                role: "position",
-            };
-            const rest: ColumnPlan | null = entry.rest
-                ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false }
-                : null;
-            return { ...plan, position, rest };
+            return this.graphicsPlan(plan, entry);
         }
         return plan;
     }

package/src/formats/gml/syntax.ts

@@ -583,14 +583,7 @@ export function parseRecord(tokens: GmlTokens, open: number): Record<string, unk
         const key = tokens.textOf(p);
         const v = p + 1;
         if (tokens.kind[v] === TOKEN_STRING) {
-            const text = tokens.stringOf(v);
-            if (text === LIST_START_MARKER) {
-                frame.record[key] = [];
-                frame.listKeys ??= new Set();
-                frame.listKeys.add(key);
-                continue;
-            }
-            storeValue(frame, key, text === EMPTY_LIST_TEXT || text === EMPTY_TUPLE_TEXT ? [] : text);
+            storeString(frame, key, tokens.stringOf(v));
         } else if (tokens.kind[v] === TOKEN_OPEN) {
             stack.push({
                 record: Object.create(null) as Record<string, unknown>,
@@ -606,6 +599,23 @@ export function parseRecord(tokens: GmlTokens, open: number): Record<string, unk
     return root;
 }
 
+/**
+ * Store a string value: the list-start marker opens an empty list for the key, the empty list and
+ * tuple texts store an empty list, anything else stores the text.
+ * @param frame - the open record
+ * @param key - the key
+ * @param text - the string
+ */
+function storeString(frame: RecordFrame, key: string, text: string): void {
+    if (text === LIST_START_MARKER) {
+        frame.record[key] = [];
+        frame.listKeys ??= new Set();
+        frame.listKeys.add(key);
+        return;
+    }
+    storeValue(frame, key, text === EMPTY_LIST_TEXT || text === EMPTY_TUPLE_TEXT ? [] : text);
+}
+
 /**
  * Store one value under a key: appended to the key's list when the key is a list, paired with the
  * earlier value when the key repeats, set otherwise.

package/src/formats/graphml/exporter.ts

@@ -1153,6 +1153,30 @@ function writeTreeData(keyId: string, value: unknown, indent: string, out: strin
     out.push(`\n${indent}</data>`);
 }
 
+/**
+ * Append the `<default>` element of a key.
+ * @param key - the key
+ * @param column - the key's column
+ * @param inner - the indentation of the element
+ * @param parts - where to append
+ */
+function pushDefault(key: KeyPlan, column: Column, inner: string, parts: string[]): void {
+    if (key.yfilesType === null) {
+        parts.push(`\n${inner}<default>${escapeXmlText(defaultText(column, key.attrType) ?? "")}</default>`);
+        return;
+    }
+    const value = column.meta.default;
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        parts.push(`\n${inner}<default>`);
+        writeXmlTree(value, `${inner}  `, parts);
+        parts.push(`\n${inner}</default>`);
+    } else {
+        const tree: string[] = [];
+        writeXmlTree(value, inner, tree);
+        parts.push(`\n${inner}<default>${tree.join("")}</default>`);
+    }
+}
+
 /**
  * The `<key>` element of a plan.
  * @param key - the key plan
@@ -1183,20 +1207,7 @@ function keyElement(key: KeyPlan, indent: string): string {
         parts.push(`\n${inner}<desc>${escapeXmlText(desc)}</desc>`);
     }
     if (hasDefault) {
-        if (key.yfilesType !== null) {
-            const value = column.meta.default;
-            if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-                parts.push(`\n${inner}<default>`);
-                writeXmlTree(value, `${inner}  `, parts);
-                parts.push(`\n${inner}</default>`);
-            } else {
-                const tree: string[] = [];
-                writeXmlTree(value, inner, tree);
-                parts.push(`\n${inner}<default>${tree.join("")}</default>`);
-            }
-        } else {
-            parts.push(`\n${inner}<default>${escapeXmlText(defaultText(column, key.attrType) ?? "")}</default>`);
-        }
+        pushDefault(key, column, inner, parts);
     }
     parts.push(`\n${indent}</key>\n`);
     return parts.join("");
@@ -1307,11 +1318,13 @@ function* writeGraphml(snapshot: GraphSnapshot, plan: Plan): Generator<string, v
     // nodes in containment order, children nested under their parent
     const { hierarchy } = plan;
     const nested = hierarchy.childList.length > 0;
-    const stackNode: number[] = [];
-    const stackCursor: number[] = [];
-    const written = nested ? new Uint8Array(snapshot.nodeCount) : null;
+    const walk: SubtreeWalk = {
+        stackNode: [],
+        stackCursor: [],
+        written: nested ? new Uint8Array(snapshot.nodeCount) : null,
+    };
     for (const rootNode of hierarchy.roots) {
-        yield* writeNodeSubtree(rootNode, plan, ids, i2, step, stackNode, stackCursor, written);
+        yield* writeNodeSubtree(rootNode, plan, ids, i2, step, walk);
     }
 
     // edges: primaries only, in index order
@@ -1378,6 +1391,16 @@ function portText(column: Column | null, e: number): string | null {
     return typeof value === "string" ? value : String(value);
 }
 
+/** The state a subtree walk reuses from one top-level node to the next. */
+interface SubtreeWalk {
+    /** A reusable stack of open nodes. */
+    readonly stackNode: number[];
+    /** A reusable stack of child cursors. */
+    readonly stackCursor: number[];
+    /** Nodes already written (null when nothing is nested). */
+    readonly written: Uint8Array | null;
+}
+
 /**
  * Write a top-level node and, nested, every node contained in it (iteratively, so a deep chain
  * cannot overflow the call stack).
@@ -1386,9 +1409,7 @@ function portText(column: Column | null, e: number): string | null {
  * @param ids - the sanitised ids
  * @param indent - the indentation of top-level nodes
  * @param step - one indentation step
- * @param stackNode - a reusable stack of open nodes
- * @param stackCursor - a reusable stack of child cursors
- * @param written - nodes already written (null when nothing is nested)
+ * @param walk - the reusable walk state
  * @yields the node elements
  * @returns nothing
  */
@@ -1398,10 +1419,9 @@ function* writeNodeSubtree(
     ids: SanitizedIds,
     indent: string,
     step: string,
-    stackNode: number[],
-    stackCursor: number[],
-    written: Uint8Array | null,
+    walk: SubtreeWalk,
 ): Generator<string, void, undefined> {
+    const { stackNode, stackCursor, written } = walk;
     const { hierarchy } = plan;
     const hasChildren = (u: number): boolean => hierarchy.childStart[u + 1] > hierarchy.childStart[u];
     const openNode = (u: number, depth: number): string => {
@@ -1418,9 +1438,8 @@ function* writeNodeSubtree(
         }
         if (hasChildren(u)) {
             parts.splice(open, 0, ">");
-            parts.push(
-                `\n${pad}${step}<graph id="${escapeXmlAttribute(`${String(ids.idAt(u))}:`)}" edgedefault="${plan.edgedefault}">`,
-            );
+            const graphId = `${String(ids.idAt(u))}:`;
+            parts.push(`\n${pad}${step}<graph id="${escapeXmlAttribute(graphId)}" edgedefault="${plan.edgedefault}">`);
             return parts.join("");
         }
         if (parts.length === open) {

package/src/formats/graphml/importer.ts

@@ -1126,9 +1126,6 @@ class GraphmlReader implements XmlHandler {
         known: ReadonlySet<string>,
         line: number,
     ): void {
-        if (attrs.size === 0) {
-            return;
-        }
         for (const name of attrs.keys()) {
             if (known.has(name) || name === "xmlns" || /^(xmlns|xml|xsi):/.test(name)) {
                 continue;
@@ -1150,14 +1147,7 @@ class GraphmlReader implements XmlHandler {
             if (names.size > MAX_UNKNOWN_ATTRIBUTE_NAMES && !hint) {
                 continue;
             }
-            let message: string;
-            if (hint) {
-                message = `the <${kind}> parse hint ${name} is ignored`;
-            } else if (SCHEMA_ATTRIBUTES.has(name)) {
-                message = `the <${kind}> attribute ${name} is not kept`;
-            } else {
-                message = `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`;
-            }
+            const message = unreadAttributeMessage(kind, name, hint);
             this.report.warning("unsupported", code, message, { line, element: name });
         }
     }
@@ -2462,9 +2452,10 @@ class GraphmlReader implements XmlHandler {
      */
     private expandStar(hyperedge: HyperedgeState, where: Where): void {
         this.hyperedgeCount++;
-        let hubId = hyperedge.id ?? `hyperedge${this.hyperedgeCount}`;
+        const baseId = hyperedge.id ?? `hyperedge${this.hyperedgeCount}`;
+        let hubId = baseId;
         for (let n = 2; this.sink.indexOf(hubId) !== INVALID_INDEX; n++) {
-            hubId = `${hyperedge.id ?? `hyperedge${this.hyperedgeCount}`}#${n}`;
+            hubId = `${baseId}#${n}`;
         }
         const hub = this.sink.addNode(hubId);
         this.declared.add(hub);
@@ -2728,3 +2719,20 @@ function unknownElementMessage(name: string): string {
         ? `element <${name}> is not allowed at this place in a GraphML file and was skipped`
         : `element <${name}> is not GraphML and was skipped`;
 }
+
+/**
+ * The warning text for an attribute the importer does not keep.
+ * @param kind - the element name
+ * @param name - the attribute name
+ * @param hint - whether the attribute is a `parse.*` hint
+ * @returns the message
+ */
+function unreadAttributeMessage(kind: string, name: string, hint: boolean): string {
+    if (hint) {
+        return `the <${kind}> parse hint ${name} is ignored`;
+    }
+    if (SCHEMA_ATTRIBUTES.has(name)) {
+        return `the <${kind}> attribute ${name} is not kept`;
+    }
+    return `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`;
+}

package/src/formats/graphml/tree.ts

@@ -270,18 +270,7 @@ function writeElements(name: string, value: unknown, indent: string, out: string
         return;
     }
     const object = value as XmlTreeObject;
-    let attrs = "";
-    let text: string | null = null;
-    let hasChildren = false;
-    for (const [key, child] of Object.entries(object)) {
-        if (key === TEXT_KEY) {
-            text = scalarText(child);
-        } else if (key.startsWith(ATTRIBUTE_PREFIX)) {
-            attrs += ` ${key.slice(ATTRIBUTE_PREFIX.length)}="${escapeXmlAttribute(scalarText(child))}"`;
-        } else {
-            hasChildren = true;
-        }
-    }
+    const { attrs, text, hasChildren } = scanElement(object);
     if (!hasChildren) {
         out.push(
             text === null || text.length === 0
@@ -303,6 +292,27 @@ function writeElements(name: string, value: unknown, indent: string, out: string
     out.push(`\n${indent}</${name}>`);
 }
 
+/**
+ * Split an element object into its attribute text, its text content and whether it has children.
+ * @param object - the element object
+ * @returns the attribute text, the text content (null when absent) and the children flag
+ */
+function scanElement(object: XmlTreeObject): { attrs: string; text: string | null; hasChildren: boolean } {
+    let attrs = "";
+    let text: string | null = null;
+    let hasChildren = false;
+    for (const [key, child] of Object.entries(object)) {
+        if (key === TEXT_KEY) {
+            text = scalarText(child);
+        } else if (key.startsWith(ATTRIBUTE_PREFIX)) {
+            attrs += ` ${key.slice(ATTRIBUTE_PREFIX.length)}="${escapeXmlAttribute(scalarText(child))}"`;
+        } else {
+            hasChildren = true;
+        }
+    }
+    return { attrs, text, hasChildren };
+}
+
 /**
  * The text of a scalar tree value.
  * @param value - a string, number, boolean or null

package/src/formats/graphml/yfiles.ts

@@ -109,16 +109,7 @@ export function staleGraphicsRows(column: Column, table: Iterable<Column>, domai
     }
     let stale = 0;
     for (let r = 0; r < column.length; r++) {
-        const wants = new Set<string>();
-        for (const tree of trees) {
-            const want = graphicsValues(domain, tree.values[r]).find(([f]) => f === field);
-            if (want !== undefined) {
-                wants.add(JSON.stringify(want[1]));
-            }
-        }
-        if (wants.size === 0) {
-            wants.add(JSON.stringify(undefined));
-        }
+        const wants = wantedGraphics(trees, domain, field, r);
         const value = column.value(r);
         const have = column.meta.components > 1 && value !== undefined ? Array.from(value as ArrayLike<number>) : value;
         if (!wants.has(JSON.stringify(have))) {
@@ -128,6 +119,28 @@ export function staleGraphicsRows(column: Column, table: Iterable<Column>, domai
     return stale;
 }
 
+/**
+ * The serialized values the trees want for one row of a mapped column.
+ * @param trees - the yFiles tree columns of the table
+ * @param domain - node or edge
+ * @param field - the mapped field name
+ * @param r - the row
+ * @returns the wanted values as JSON text; just `undefined`'s when no tree wants one
+ */
+function wantedGraphics(trees: JsonColumn[], domain: "node" | "edge", field: string, r: number): Set<string> {
+    const wants = new Set<string>();
+    for (const tree of trees) {
+        const want = graphicsValues(domain, tree.values[r]).find(([f]) => f === field);
+        if (want !== undefined) {
+            wants.add(JSON.stringify(want[1]));
+        }
+    }
+    if (wants.size === 0) {
+        wants.add(JSON.stringify(undefined));
+    }
+    return wants;
+}
+
 /**
  * The mapped values of one `<data>` tree of a yFiles key: a ShapeNode's for a node, a
  * PolyLineEdge's for an edge; nothing for any other graphics (GenericNode, BezierEdge, ...).

package/src/formats/json/exporter.ts

@@ -1609,7 +1609,6 @@ function* writeCytoscape(snapshot: GraphSnapshot, p: Plan): Generator<string, vo
     const c: Cursor = { w: new JsonWriter(resolved.indent), ids: snapshot.ids, nonfinite: { count: 0 } };
     const { w } = c;
     const parentSlots: ReadonlySet<Slot> = new Set(["parent"]);
-    const positionSlots: ReadonlySet<Slot> = new Set(["cytoscapePosition"]);
     w.open("{");
     w.key("elements");
     w.open("{");
@@ -1625,18 +1624,7 @@ function* writeCytoscape(snapshot: GraphSnapshot, p: Plan): Generator<string, vo
         writeSlots(c, p.nodes, i, parentSlots);
         writeSlots(c, p.nodes, i, ATTRIBUTE_SLOTS);
         w.close("}");
-        for (const item of p.nodes) {
-            if (positionSlots.has(item.slot) && item.column.isSet(i)) {
-                const value = item.column.value(i) as ArrayLike<number>;
-                const f32 = item.column.dtype === "f32";
-                w.key("position");
-                w.open("{");
-                w.member("x", numberText(value[0], f32, c.nonfinite));
-                // stored y-up; Cytoscape's y grows downward
-                w.member("y", numberText(flipY(value[1]), f32, c.nonfinite));
-                w.close("}");
-            }
-        }
+        writeCytoscapePosition(c, p.nodes, i);
         writeSlots(c, p.nodes, i, ELEMENT_SLOTS);
         w.close("}");
         yield w.take();
@@ -1673,18 +1661,49 @@ function* writeCytoscape(snapshot: GraphSnapshot, p: Plan): Generator<string, vo
         w.key("data");
         writeGraphObject(c, p);
     }
-    const extra = resolved.shape.cytoscape;
-    if (extra !== undefined) {
-        for (const key of Object.keys(extra)) {
-            if (key !== "elements" && key !== "data") {
-                w.member(key, valueText(extra[key], false, c.nonfinite));
-            }
-        }
-    }
+    writeCytoscapeExtra(c, resolved.shape.cytoscape);
     w.close("}");
     yield w.take();
 }
 
+/**
+ * Write a node's `position` member (Cytoscape.js), when its position is set.
+ * @param c - the cursor
+ * @param items - the node plan items
+ * @param i - the node index
+ */
+function writeCytoscapePosition(c: Cursor, items: readonly ColumnPlan[], i: number): void {
+    const { w } = c;
+    for (const item of items) {
+        if (item.slot === "cytoscapePosition" && item.column.isSet(i)) {
+            const value = item.column.value(i) as ArrayLike<number>;
+            const f32 = item.column.dtype === "f32";
+            w.key("position");
+            w.open("{");
+            w.member("x", numberText(value[0], f32, c.nonfinite));
+            // stored y-up; Cytoscape's y grows downward
+            w.member("y", numberText(flipY(value[1]), f32, c.nonfinite));
+            w.close("}");
+        }
+    }
+}
+
+/**
+ * Write the extra top-level members of a Cytoscape.js document, beyond `elements` and `data`.
+ * @param c - the cursor
+ * @param extra - the extra members, when any
+ */
+function writeCytoscapeExtra(c: Cursor, extra: Readonly<Record<string, unknown>> | undefined): void {
+    if (extra === undefined) {
+        return;
+    }
+    for (const key of Object.keys(extra)) {
+        if (key !== "elements" && key !== "data") {
+            c.w.member(key, valueText(extra[key], false, c.nonfinite));
+        }
+    }
+}
+
 /**
  * A generator of canonical `e<index>` edge ids for the edges without one (design section 4.6),
  * skipping any text a node id or an explicit edge id already uses (Cytoscape ids share one