@graphty/cytoscape-extensions 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/cytoscape-extensions",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Graphty layouts, algorithms, graph generators, sample datasets and file import/export as Cytoscape.js extensions",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -71,9 +71,9 @@
   },
   "homepage": "https://graphty.app/docs/cytoscape-extensions/",
   "dependencies": {
-    "@graphty/graph-io": "^0.3.42",
-    "@graphty/graph-samples": "^0.1.35",
-    "@graphty/webgpu-graph-algorithms": "^0.6.57"
+    "@graphty/graph-io": "^0.3.44",
+    "@graphty/webgpu-graph-algorithms": "^0.6.59",
+    "@graphty/graph-samples": "^0.1.37"
   },
   "peerDependencies": {
     "@graphty/algorithms": "^3.0.0",
@@ -103,9 +103,9 @@
     "typescript": "^5.9.3",
     "vite": "^7.0.5",
     "vitest": "4.1.11",
-    "@graphty/algorithms": "^3.4.10",
-    "@graphty/graph-format": "^1.4.3",
-    "@graphty/layout": "^2.5.6"
+    "@graphty/algorithms": "^3.4.12",
+    "@graphty/graph-format": "^1.4.5",
+    "@graphty/layout": "^2.5.8"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && vite build --config vite.bundle.config.ts --mode cdn --logLevel warn && vite build --config vite.bundle.config.ts --logLevel warn",

package/src/elements.ts

@@ -5,6 +5,7 @@
  */
 
 import { type Column, type ColumnInput, fromEdgeArrays, type GraphSnapshot } from "@graphty/graph-format";
+import { writtenPositions } from "@graphty/graph-io/positions";
 import type { Collection, ElementDefinition } from "cytoscape";
 
 /**
@@ -54,18 +55,26 @@ interface RenamedColumn {
  * @param snapshot - the snapshot
  * @param onRename - told about each column renamed because its name is reserved
  * @param onIdDropped - told about each edge id dropped, and whether a node or an earlier edge has it
+ * @param styled - whether the file's styles are read as a stylesheet: then the columns that hold styles (a GEXF
+ *     `viz:color`, `viz:size`, `viz:shape`, its image and `viz:thickness`) are left out of data, because the
+ *     stylesheet carries them
  * @returns the nodes, then the edges
  */
 export function snapshotToElements(
     snapshot: GraphSnapshot,
     onRename?: (renamed: RenamedColumn) => void,
     onIdDropped?: (id: string, takenBy: "node" | "edge") => void,
+    styled = false,
 ): ElementDefinition[] {
     const ids: string[] = [];
     for (let i = 0; i < snapshot.nodeCount; i++) {
         ids.push(String(snapshot.ids.idOf(i)));
     }
-    return [...nodeElements(snapshot, ids, onRename), ...edgeElements(snapshot, ids, onRename, onIdDropped)];
+    const keep = styled ? (c: Column): boolean => kept(c) && !holdsStyle(c) : kept;
+    return [
+        ...nodeElements(snapshot, ids, onRename, keep),
+        ...edgeElements(snapshot, ids, onRename, onIdDropped, keep),
+    ];
 }
 
 /**
@@ -77,6 +86,19 @@ function kept(c: Column): boolean {
     return c.meta.role !== "id" && c.meta.role !== "parent";
 }
 
+/** The roles of the columns that hold styles, which graph-io reads as a file's styles. */
+const STYLE_ROLES: ReadonlySet<string> = new Set(["color", "size", "shape", "thickness"]);
+
+/**
+ * Whether a column holds styles: one with a style role, or GEXF's image of an `image` shape.
+ * @param c - the column
+ * @returns true for a style column
+ */
+function holdsStyle(c: Column): boolean {
+    const { role, name, origin } = c.meta;
+    return (role !== null && STYLE_ROLES.has(role)) || (name === "shape.uri" && origin?.namespace === "viz");
+}
+
 /**
  * The data field name of each column: its own, or for a reserved name `<name>#<origin id>` (`<name>#2`, `#3`, ...
  * without one, or when that is taken), the rule graph-io follows when two attributes share a name.
@@ -137,14 +159,16 @@ function rowData(cols: readonly Column[], row: number, fieldOf: (c: Column) => s
  * @param snapshot - the snapshot
  * @param ids - the node ids as strings, by node index
  * @param onRename - told about each renamed column
+ * @param keep - whether a column becomes a data field
  * @returns one element per node
  */
 function nodeElements(
     snapshot: GraphSnapshot,
     ids: readonly string[],
     onRename: ((renamed: RenamedColumn) => void) | undefined,
+    keep: (c: Column) => boolean,
 ): ElementDefinition[] {
-    const nodeCols = [...snapshot.nodes].filter(kept);
+    const nodeCols = [...snapshot.nodes].filter(keep);
     const position = nodeCols.find((c) => c.meta.role === "position" && c.meta.components >= 2);
     const nodeData = nodeCols.filter((c) => c !== position);
     const names = fieldNames(nodeData, "node", onRename);
@@ -173,6 +197,7 @@ function nodeElements(
  * @param ids - the node ids as strings, by node index
  * @param onRename - told about each renamed column
  * @param onIdDropped - told about each dropped edge id
+ * @param keep - whether a column becomes a data field
  * @returns one element per edge
  */
 function edgeElements(
@@ -180,8 +205,9 @@ function edgeElements(
     ids: readonly string[],
     onRename: ((renamed: RenamedColumn) => void) | undefined,
     onIdDropped: ((id: string, takenBy: "node" | "edge") => void) | undefined,
+    keep: (c: Column) => boolean,
 ): ElementDefinition[] {
-    const edgeCols = [...snapshot.edges].filter(kept);
+    const edgeCols = [...snapshot.edges].filter(keep);
     const named = edgeCols.some((c) => c.meta.name === "weight");
     const weightColumn = edgeCols.find((c) => c.meta.role === "weight");
     const names = fieldNames(edgeCols, "edge", onRename);
@@ -286,6 +312,16 @@ function columns(records: readonly Record<string, unknown>[]): Record<string, Co
     return out;
 }
 
+/**
+ * The edges of a collection that elementsToSnapshot() writes, in its order: those whose two ends are in it.
+ * @param eles - the collection
+ * @returns the edges
+ */
+export function exportedEdges(eles: Collection): Collection {
+    const ids = new Set(eles.nodes().map((n) => n.id()));
+    return eles.edges().filter((e) => ids.has(e.source().id()) && ids.has(e.target().id()));
+}
+
 /**
  * A snapshot of a collection with every data field as a column and every node's position as a "position" column
  * (y negated: graph-io's y grows upward), for an exporter. Edges whose endpoints are not both in the collection are left out. A numeric edge field named
@@ -298,6 +334,8 @@ function columns(records: readonly Record<string, unknown>[]): Record<string, Co
  * @param options.directed - write a directed graph (default false)
  * @param options.integerIds - when every node id is a non-negative integer written plainly ("0", "17"), give the
  * snapshot number ids, so a format that holds only integer ids (GML, CX2) writes them as they are (default false)
+ * @param options.format - the format the snapshot is written in: the positions are spelled as its writer expects
+ * them (GML and Pajek draw y downward); without it they are graph-io's neutral form, y up
  * @returns the snapshot
  */
 export function elementsToSnapshot(
@@ -305,6 +343,7 @@ export function elementsToSnapshot(
     options: {
         readonly directed?: boolean | undefined;
         readonly integerIds?: boolean | undefined;
+        readonly format?: string | undefined;
     } = {},
 ): GraphSnapshot {
     const nodes = eles.nodes();
@@ -315,19 +354,26 @@ export function elementsToSnapshot(
     });
     const integers = options.integerIds === true && names.every((id) => /^(?:0|[1-9]\d{0,14})$/.test(id));
     const ids: (string | number)[] = integers ? names.map(Number) : names;
-    const edges = eles.edges().filter((e) => index.has(e.source().id()) && index.has(e.target().id()));
+    const edges = exportedEdges(eles);
     const src = new Uint32Array(edges.length);
     const dst = new Uint32Array(edges.length);
     edges.forEach((e, k) => {
         src[k] = index.get(e.source().id()) ?? 0;
         dst[k] = index.get(e.target().id()) ?? 0;
     });
-    const xy = new Float64Array(nodes.length * 2);
+    const xyz = new Float64Array(nodes.length * 3);
     nodes.forEach((n, i) => {
         const p = n.position();
-        xy[2 * i] = p.x;
-        xy[2 * i + 1] = flipY(p.y);
+        xyz[3 * i] = p.x;
+        xyz[3 * i + 1] = flipY(p.y);
     });
+    // spelled as the format's writer expects its position column (GML and Pajek: y down)
+    const written = options.format === undefined ? xyz : writtenPositions(options.format, xyz);
+    const xy = new Float64Array(nodes.length * 2);
+    for (let i = 0; i < nodes.length; i++) {
+        xy[2 * i] = written[3 * i];
+        xy[2 * i + 1] = written[3 * i + 1];
+    }
     const parents = nodes.map((n) => index.get(n.parent().first().id()) ?? null);
     const edgeColumns = columns(edges.map((e) => e.data() as Record<string, unknown>));
     let weights: Float64Array<ArrayBuffer> | undefined;

package/src/graph-data.ts

@@ -9,7 +9,7 @@ import type { FetchDatasetOptions } from "@graphty/graph-samples";
 import type { Collection, CollectionReturnValue, Core, ElementDefinition } from "cytoscape";
 
 import { coreDestroyedError } from "./gpu.js";
-import type { ExportFormat, ExportOptions, ImportFormat, ImportOptions } from "./io.js";
+import type { CytoscapeStylesheetRule, ExportFormat, ExportOptions, ImportFormat, ImportOptions } from "./io.js";
 import { loadPart } from "./lazy.js";
 import type { GeneratorName, GeneratorOptions } from "./samples.js";
 
@@ -21,12 +21,26 @@ export interface AddedGraph {
     readonly directed: boolean;
 }
 
+/** The part of a core's live style graphtyImport appends rules with, which Cytoscape's typings leave out. */
+interface AppendableStyle {
+    selector(s: string): { style(props: object): AppendableStyle };
+    update(): void;
+}
+
 /** What graphtyImport adds to the core. */
 export interface ImportedGraph extends AddedGraph {
     /** The format the input was read as. */
     readonly format: string;
     /** graph-io's report: counts, warnings, and what could not be represented. */
     readonly report: ImportReport;
+    /**
+     * With `styles: true`, the file's styles as a Cytoscape.js stylesheet whose every rule applies only to this
+     * import's elements (they hold its id in `data.graphty_import`). `applyStyles: true` has already appended it to
+     * the core's stylesheet; otherwise append it yourself, rule by rule:
+     * `for (const r of stylesheet) cy.style().selector(r.selector).style(r.style); cy.style().update()`.
+     * Absent without `styles`.
+     */
+    readonly stylesheet?: CytoscapeStylesheetRule[];
 }
 
 /** The core methods `cytoscape.use(graphtyCytoscape)` adds for getting graphs in and out. */
@@ -49,8 +63,14 @@ export interface GraphtyGraphData {
     /**
      * Adds the graph in a file: GEXF, GraphML, GML, DOT, Pajek, CSV, JSON, Neo4j, XGMML, CX2, CX, OBO or a
      * Cytoscape session (`.cys`, as bytes). Every attribute becomes a data field, and positions in the file become
-     * node positions (y negated for the formats whose y grows upward: GEXF, GML, DOT, Pajek). Throws, adding
+     * node positions, the way up the program that wrote the file draws them (a yEd box's top-left corner is
+     * moved to its center). Throws, adding
      * nothing, when the core already holds one of the graph's node ids.
+     * `{ styles: true }` also reads the file's colors, sizes, shapes, ... and returns them as `stylesheet`;
+     * `{ styles: true, applyStyles: true }` draws them too (the core needs `styleEnabled` when headless).
+     * Without `styles`, a GEXF `viz:color`, `viz:size`, `viz:shape` and `viz:thickness` also become data fields;
+     * these fields are deprecated and are removed in the next major release: use `styles: true`, which leaves
+     * them out of data and draws them through the stylesheet.
      */
     graphtyImport(
         input: ImportInput | ArrayBuffer,
@@ -60,7 +80,8 @@ export interface GraphtyGraphData {
     /**
      * Writes the graph as a file's text: every data field, each node's position and parent, and each edge's id, as
      * far as the format holds them (`options.onLoss` hears about the rest). Hidden elements are written too. On a
-     * collection: its nodes, and those of its edges whose two ends are among them.
+     * collection: its nodes, and those of its edges whose two ends are among them. `{ styles: true }` also writes
+     * how the core draws each element, so graphtyImport with `styles: true` draws the file the same.
      */
     graphtyExport(format: ExportFormat, options?: ExportOptions): Promise<string>;
 }
@@ -129,6 +150,20 @@ function addTo(cy: Core, elements: ElementDefinition[]): CollectionReturnValue {
     return cy.add(elements);
 }
 
+/**
+ * An import id no element of the core holds yet.
+ * @param cy - the core
+ * @returns the id
+ */
+function freeImportId(cy: Core): string {
+    const taken = new Set(cy.elements("[graphty_import]").map((e) => String(e.data("graphty_import"))));
+    let k = taken.size + 1;
+    while (taken.has(String(k))) {
+        k++;
+    }
+    return String(k);
+}
+
 /**
  * Registers graphtyGenerate, graphtyDataset, graphtyImport and graphtyExport.
  * @param cytoscape - the cytoscape function
@@ -150,8 +185,37 @@ export function registerGraphData(cytoscape: Register): void {
         "graphtyImport",
         async function (this: Core, input: ImportInput | ArrayBuffer, format?: ImportFormat, options?: ImportOptions) {
             const { importElements } = await loadPart(import("./io.js"), "graphtyImport");
-            const r = await importElements(input, format, options);
-            return { elements: addTo(this, r.elements), directed: r.directed, format: r.format, report: r.report };
+            const styled = options?.styles !== undefined && options.styles !== false;
+            const r = await importElements(input, format, {
+                ...options,
+                ...(styled && options.importId === undefined ? { importId: freeImportId(this) } : {}),
+            });
+            const apply = options?.applyStyles === true && r.stylesheet !== undefined;
+            if (apply) {
+                r.bypass?.forEach((b, i) => {
+                    if (b !== null) {
+                        r.elements[i].style = b;
+                    }
+                });
+            }
+            const elements = addTo(this, r.elements);
+            const style = this.style() as unknown as AppendableStyle | undefined;
+            if (apply && r.stylesheet !== undefined && style !== undefined) {
+                // appended rule by rule: a round trip through style.json() turns the core's own function-valued
+                // properties into the string "fn", which Cytoscape then rejects
+                let s = style;
+                for (const rule of r.stylesheet) {
+                    s = s.selector(rule.selector).style(rule.style);
+                }
+                s.update();
+            }
+            return {
+                elements,
+                directed: r.directed,
+                format: r.format,
+                report: r.report,
+                ...(r.stylesheet === undefined ? {} : { stylesheet: r.stylesheet }),
+            };
         },
     );
     const exportFn = async (eles: Collection, format: ExportFormat, options?: ExportOptions): Promise<string> => {

package/src/index.ts

@@ -40,7 +40,14 @@ export {
 } from "./algorithms.js";
 export { type Backend, configureWebGpu, GPU_SIZE_FLOOR, type GpuMode, type WebGpuOptions } from "./gpu.js";
 export { type AddedGraph, type GraphtyGraphData, IdTakenError, type ImportedGraph } from "./graph-data.js";
-export type { ExportFormat, ExportOptions, ImportFormat, ImportOptions, LossNote } from "./io.js";
+export type {
+    CytoscapeStylesheetRule,
+    ExportFormat,
+    ExportOptions,
+    ImportFormat,
+    ImportOptions,
+    LossNote,
+} from "./io.js";
 export {
     type GraphtyLayoutName,
     type GraphtyLayoutOptions,

package/src/io.ts

@@ -4,9 +4,10 @@
  * exports a file never downloads the parsers.
  */
 
+import type { GraphSnapshot } from "@graphty/graph-format";
 import {
     checkExport,
-    type ExportGraphOptions,
+    type CommonExportOptions,
     exportGraphToString,
     ImportError,
     importGraph,
@@ -15,10 +16,20 @@ import {
     type ImportIssue,
     type ImportReport,
     type LossNote,
+    registry,
 } from "@graphty/graph-io";
-import type { Collection, ElementDefinition } from "cytoscape";
+import { extractPositions } from "@graphty/graph-io/positions";
+import {
+    type CytoscapeStylesheetRule,
+    type ExtractedStyles,
+    readCytoscapeStyles,
+    STYLE_ISSUE,
+    type StyleNote,
+    toCytoscapeStylesheet,
+} from "@graphty/graph-io/styles";
+import type { Collection, Core, ElementDefinition } from "cytoscape";
 
-import { elementsToSnapshot, flipY, snapshotToElements } from "./elements.js";
+import { elementsToSnapshot, exportedEdges, flipY, snapshotToElements } from "./elements.js";
 
 /** One thing graphtyExport's format cannot hold: `code`, `message`, the data field (`column`) and how many values. */
 export type { LossNote } from "@graphty/graph-io";
@@ -46,8 +57,28 @@ export type ImportFormat =
 /** The formats graphtyExport writes. XGMML is the one Cytoscape desktop opens as a network file. */
 export type ExportFormat = "gexf" | "graphml" | "gml" | "dot" | "pajek" | "csv" | "json" | "neo4j" | "xgmml" | "cx2";
 
-/** Options of graphtyImport: graph-io's import options (`filename`, `graphIndex`, format-specific ones, ...). */
-export type ImportOptions = Omit<ImportGraphOptions, "format">;
+/** One rule of a Cytoscape.js stylesheet: a selector and its properties. */
+export type { CytoscapeStylesheetRule } from "@graphty/graph-io/styles";
+
+/**
+ * Options of graphtyImport: graph-io's import options (`filename`, `graphIndex`, format-specific ones, ...).
+ * `styles: true` also reads the file's styles (its colors, sizes, shapes, ...) as a Cytoscape.js stylesheet,
+ * returned as `stylesheet`; a property the file leaves to the program that wrote it gets that program's default
+ * (`styles: { toolDefaults: false }` leaves them out).
+ */
+export type ImportOptions = Omit<ImportGraphOptions, "format"> & {
+    /**
+     * With `styles`, graphtyImport also appends the file's stylesheet to the core's own and gives each element the
+     * per-element overrides that make it exact. Default false: the stylesheet is only returned.
+     */
+    readonly applyStyles?: boolean | undefined;
+    /**
+     * With `styles`, the value of the `graphty_import` data field every imported element gets and every rule of the
+     * stylesheet tests, so a second import into the same core never restyles the first one's elements. Default: a
+     * new one for each import.
+     */
+    readonly importId?: string | undefined;
+};
 
 /**
  * Options of graphtyExport: graph-io's export options for the format, plus whether to write a directed graph.
@@ -58,7 +89,17 @@ export type ImportOptions = Omit<ImportGraphOptions, "format">;
  * JSON is written as Cytoscape JSON (`dialect: "cytoscape"`, the shape `cy.json()` and `cy.add()` use), which keeps
  * edge ids, compound parents and positions; pass `dialect: "node-link"` for the NetworkX shape.
  */
-export interface ExportOptions extends ExportGraphOptions {
+export interface ExportOptions extends CommonExportOptions {
+    /**
+     * Write the core's styles too: its stylesheet's rules, with what the core draws for each element as the truth
+     * (a function-valued property is written per element and reported as W_STYLE_LAYER_FLATTENED). Each format
+     * keeps as much of them as it can, so importing the file with `styles: true` draws the same; `onLoss` hears
+     * about the rest (W_STYLE_ codes). Default false: without it `onLoss` hears W_STYLES_NOT_EXPORTED when the core
+     * has a stylesheet of its own.
+     */
+    readonly styles?: boolean | undefined;
+    /** Format-specific options, passed to graph-io as they are. */
+    readonly [formatOption: string]: unknown;
     /** Write the graph as directed. Default false. */
     readonly directed?: boolean | undefined;
     /**
@@ -78,10 +119,44 @@ export interface ImportedElements {
     readonly format: string;
     /** graph-io's report: counts, warnings, and what could not be represented. */
     readonly report: ImportReport;
+    /**
+     * With `styles`, the file's styles as a Cytoscape.js stylesheet scoped to this import; append it to the core's
+     * rule by rule (`cy.style().selector(r.selector).style(r.style)` for each, then `cy.style().update()`). Absent
+     * without `styles`.
+     */
+    readonly stylesheet?: CytoscapeStylesheetRule[];
+    /**
+     * With `styles`, per element (in the order of `elements`) the style overrides that make it draw exactly as the
+     * file says where the stylesheet alone does not, or null; give them as each definition's `style`.
+     */
+    readonly bypass?: (Readonly<Record<string, string | number>> | null)[];
+}
+
+/** How many imports have read styles: the default import ids. */
+let imports = 0;
+
+/**
+ * A style note as a report warning.
+ * @param n - the note
+ * @returns the issue
+ */
+function styleIssue(n: StyleNote): ImportIssue {
+    return {
+        category: "unsupported",
+        severity: "warning",
+        code: n.code,
+        message: n.message,
+        line: null,
+        element: n.params.property,
+    };
 }
 
 /**
  * Reads a graph file into Cytoscape element definitions.
+ * Without `styles`, a GEXF `viz:color`, `viz:size`, `viz:shape` and `viz:thickness` also become data fields
+ * (`data.color` as four numbers from 0 to 1, `data.size`, `data.shape`, `data.thickness`); these fields are
+ * deprecated and are removed in the next major release: import with `styles: true`, whose stylesheet draws them.
+ * With `styles: true` they are left out of data.
  * @param input - the file as text, bytes, a stream or chunks
  * @param format - the format, or "auto" to sniff it
  * @param options - graph-io's import options
@@ -94,7 +169,11 @@ export async function importElements(
     options: ImportOptions = {},
 ): Promise<ImportedElements> {
     // fetch().arrayBuffer() and File.arrayBuffer() give an ArrayBuffer, which graph-io does not take
-    const r = await importGraph(input instanceof ArrayBuffer ? new Uint8Array(input) : input, { ...options, format });
+    const { applyStyles: _apply, importId, ...graphOptions } = options;
+    const r = await importGraph(input instanceof ArrayBuffer ? new Uint8Array(input) : input, {
+        ...graphOptions,
+        format,
+    });
     // most text sniffs as CSV, so a file that is not a graph at all reads as an empty one with errors
     if (r.snapshot.nodeCount === 0 && r.report.errorCount > 0) {
         const first = r.report.issues.find((i) => i.severity === "error");
@@ -125,13 +204,32 @@ export async function importElements(
                 line: null,
                 element: id,
             }),
+        r.styles !== undefined && r.styles !== null,
     );
-    // graph-io stores positions with y growing upward; Cytoscape's y grows downward
-    for (const el of elements) {
-        if (el.position !== undefined) {
-            el.position.y = flipY(el.position.y);
+    // each format spells its coordinates its own way (yEd: a box's top-left corner, y down; Gephi: the
+    // center, y up); graph-io's extractPositions reads them all as the center with y up, and Cytoscape's y
+    // grows downward
+    const positions = extractPositions(registry.importer(r.format), r.snapshot, r.report);
+    for (let i = 0; i < r.snapshot.nodeCount; i++) {
+        const el = elements[i];
+        const x = positions?.usable === true ? positions.coords[3 * i] : Number.NaN;
+        if (Number.isNaN(x)) {
+            delete el.position;
+        } else {
+            el.position = { x, y: flipY(positions?.coords[3 * i + 1] ?? 0) };
         }
     }
+    let styled: Pick<ImportedElements, "stylesheet" | "bypass"> = {};
+    if (r.styles !== undefined && r.styles !== null) {
+        imports++;
+        const em = toCytoscapeStylesheet(r.styles, { importId: importId ?? String(imports) });
+        const n = r.snapshot.nodeCount;
+        const at = <T>(per: { node: readonly T[]; edge: readonly T[] }, i: number): T =>
+            i < n ? per.node[i] : per.edge[i - n];
+        elements.forEach((el, i) => Object.assign(el.data, at(em.elementData, i)));
+        styled = { stylesheet: em.stylesheet, bypass: elements.map((_el, i) => at(em.bypass, i)) };
+        warnings.push(...em.notes.map(styleIssue));
+    }
     const report =
         warnings.length === 0
             ? r.report
@@ -140,7 +238,7 @@ export async function importElements(
                   issues: [...r.report.issues, ...warnings],
                   warningCount: r.report.warningCount + warnings.length,
               };
-    return { elements, directed: r.snapshot.directed, format: r.format, report };
+    return { elements, directed: r.snapshot.directed, format: r.format, report, ...styled };
 }
 
 /** The loss notes about something graphtyImport always gives back (see lostForCytoscape). */
@@ -174,6 +272,107 @@ function lostForCytoscape(n: LossNote): boolean {
     return !(n.code === "W_ROLE_DROPPED" && n.column === "label");
 }
 
+/** What this module reads of a core's style, which Cytoscape's typings leave out. */
+interface LiveStyle {
+    json(): unknown[];
+}
+
+/**
+ * The core a collection belongs to (`eles.cy()`, which Cytoscape's typings leave out).
+ * @param eles - the collection
+ * @returns the core
+ */
+function coreOf(eles: Collection): Core {
+    return (eles as unknown as { cy(): Core }).cy();
+}
+
+/**
+ * A core's style.
+ * @param cy - the core
+ * @returns the style, or undefined when the core has styles disabled (headless without `styleEnabled`)
+ */
+function styleOf(cy: Core): LiveStyle | undefined {
+    return cy.style() as unknown as LiveStyle | undefined;
+}
+
+/**
+ * The styles of a collection as its core draws them: the core's stylesheet, with each element's `ele.style()` as
+ * the truth.
+ * @param eles - the collection
+ * @param snapshot - the collection as elementsToSnapshot() wrote it
+ * @returns the styles, or null when the core has styles disabled (a headless core without `styleEnabled`)
+ */
+function coreStyles(eles: Collection, snapshot: GraphSnapshot): ExtractedStyles | null {
+    const style = styleOf(coreOf(eles));
+    if (style === undefined) {
+        return null;
+    }
+    const nodes = eles.nodes();
+    const edges = exportedEdges(eles);
+    return readCytoscapeStyles({
+        elements: { nodes: nodes.jsons(), edges: edges.jsons() },
+        style: style.json(),
+        rendered: [...nodes.map((n) => n.style()), ...edges.map((e) => e.style())],
+        snapshot,
+    });
+}
+
+/**
+ * W_STYLE_LAYER_FLATTENED for each property written per element instead of as a rule (a function-valued one).
+ * @param extracted - the core's styles
+ * @returns the notes
+ */
+function flattened(extracted: ExtractedStyles): LossNote[] {
+    return extracted.styles.notes
+        .filter((n) => n.code === STYLE_ISSUE.LAYER_FLATTENED)
+        .map((n) => ({
+            code: n.code,
+            message: n.message,
+            column: null,
+            count: n.params.count,
+            ...(n.params.target === "node" || n.params.target === "edge"
+                ? { style: { target: n.params.target, property: n.params.property as never } }
+                : {}),
+        }));
+}
+
+/**
+ * W_STYLES_NOT_EXPORTED when the core has a stylesheet of its own (one a new core does not have), or when styles were
+ * asked for and the core has none to give (a headless core without `styleEnabled`).
+ * @param cy - the core
+ * @param asked - whether the export asked for the styles
+ * @returns the note, or none
+ */
+function notExported(cy: Core, asked: boolean): LossNote[] {
+    const style = styleOf(cy);
+    if (style === undefined) {
+        return asked
+            ? [
+                  {
+                      code: STYLE_ISSUE.NOT_EXPORTED,
+                      message:
+                          "no styles are written: the core has styles disabled; create it with { styleEnabled: true }",
+                      column: null,
+                      count: null,
+                  },
+              ]
+            : [];
+    }
+    const fresh = new (cy.constructor as new (options: object) => Core)({ headless: true, styleEnabled: true });
+    const own = JSON.stringify(style.json()) !== JSON.stringify(styleOf(fresh)?.json());
+    fresh.destroy();
+    return own
+        ? [
+              {
+                  code: STYLE_ISSUE.NOT_EXPORTED,
+                  message: "the core's stylesheet is not written; export with { styles: true } to write it",
+                  column: null,
+                  count: null,
+              },
+          ]
+        : [];
+}
+
 /** The formats that hold only integer node ids: a graph whose ids are all integers is written with them as they are. */
 const INTEGER_ID_FORMATS: ReadonlySet<ExportFormat> = new Set(["gml", "cx2"]);
 
@@ -196,18 +395,24 @@ export async function exportElements(
             "exportElements needs a Cytoscape collection; wrap element definitions with cytoscape({ headless: true, elements }).elements()",
         );
     }
-    const { directed, onLoss, ...rest } = options;
+    const { directed, onLoss, styles, ...rest } = options;
     const snapshot = elementsToSnapshot(eles, {
         directed,
+        format,
         integerIds: INTEGER_ID_FORMATS.has(format),
     });
+    const extracted = styles === true ? coreStyles(eles, snapshot) : null;
     const graphOptions = {
         sanitizeIds: "mangle" as const,
         ...(format === "json" ? { dialect: "cytoscape" } : {}),
         ...rest,
+        ...(extracted === null ? {} : { styles: extracted }),
     };
     if (onLoss !== undefined) {
-        const notes = checkExport(snapshot, format, graphOptions).filter(lostForCytoscape);
+        const notes = [
+            ...(extracted === null ? notExported(coreOf(eles), styles === true) : flattened(extracted)),
+            ...checkExport(snapshot, format, graphOptions).filter(lostForCytoscape),
+        ];
         if (notes.length > 0) {
             onLoss(notes);
         }