@graphty/graph-io 0.3.48 → 0.3.50

package/src/sources/sparql/query.ts

@@ -0,0 +1,216 @@
+/**
+ * The SPARQL the source sends: the caller's CONSTRUCT or DESCRIBE with the paging the source
+ * adds (`ORDER BY` the template's variables, `LIMIT` and `OFFSET`), and the generated queries of
+ * "all", "neighborhood" and expand (`VALUES ?s { ... }`).
+ */
+
+/** Characters an IRIREF may not hold. */
+const NOT_IRI = /[\s<>"{}|^`\\]/;
+
+/** A language tag a filter may name. */
+const LANGUAGE = /^[a-z]{1,8}(-[a-z\d]{1,8})*$/i;
+
+/** The query forms, as the first keyword after the prologue. */
+type QueryForm = "construct" | "describe" | "select" | "ask" | null;
+
+/** What paging the caller's query takes. */
+interface UserQuery {
+    /** Its form. */
+    readonly form: QueryForm;
+    /** Whether it sets its own LIMIT or OFFSET, so the source sends it as written. */
+    readonly ownLimit: boolean;
+    /** Whether it orders its solutions itself. */
+    readonly ordered: boolean;
+    /** The variables of a CONSTRUCT template, in order, for ORDER BY. */
+    readonly templateVars: readonly string[];
+}
+
+/**
+ * The query with IRIs, strings and comments blanked out, so keywords and braces can be found.
+ * @param query - the query
+ * @returns the bare text
+ */
+function bare(query: string): string {
+    return query
+        .replaceAll(/<[^<>\s]*>/g, "<>")
+        .replaceAll(/"""[\s\S]*?"""|'''[\s\S]*?'''|"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, '""')
+        .replaceAll(/#[^\n]*/g, "");
+}
+
+/** The keywords of SPARQL Update, which a query this source sends never holds. */
+const UPDATE_KEYWORDS = /\b(INSERT|DELETE|LOAD|CLEAR|DROP|CREATE|ADD|MOVE|COPY|WITH)\b/i;
+
+/** One declaration of the prologue, as `bare` leaves it: `BASE <>` or `PREFIX ex: <>`. */
+const DECLARATION = /^\s*(?:BASE|PREFIX\s*[^\s:<]*:)\s*<>/i;
+
+/**
+ * Bare text after its prologue, one declaration at a time.
+ * @param text - the bare text
+ * @returns what follows the prologue
+ */
+function afterPrologue(text: string): string {
+    let rest = text;
+    for (let found = DECLARATION.exec(rest); found !== null; found = DECLARATION.exec(rest)) {
+        rest = rest.slice(found[0].length);
+    }
+    return rest;
+}
+
+/**
+ * The bare text with variables and prefixed names blanked too, so a name such as `ex:LIMIT` or
+ * `?DELETE` is never read as a keyword.
+ * @param text - the bare text after the prologue
+ * @returns the text holding only keywords, punctuation and blanks
+ */
+function keywordsOnly(text: string): string {
+    // one run of name characters at a time: a run holding a colon is a prefixed name
+    return text.replaceAll(/[?$]\w+/g, "?v").replaceAll(/[\w.%:-]+/g, (run) => (run.includes(":") ? "_" : run));
+}
+
+/**
+ * Whether bare text holds a `;` outside every brace: SPARQL Update separates its operations so, and
+ * a query never holds one there.
+ * @param text - the text
+ * @returns true when it does
+ */
+function semicolonOutside(text: string): boolean {
+    let depth = 0;
+    for (const char of text) {
+        if (char === "{") {
+            depth++;
+        } else if (char === "}") {
+            depth--;
+        } else if (char === ";" && depth <= 0) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Read what paging a caller's query takes. Its form is the first keyword after the prologue; a
+ * text that holds an update keyword, or a `;` outside braces, has no form, so it is refused.
+ * @param query - the query
+ * @returns its form, its own modifiers and its template variables
+ */
+export function readQuery(query: string): UserQuery {
+    const body = afterPrologue(bare(query));
+    const text = keywordsOnly(body);
+    const first = /^\s*([A-Za-z]+)/.exec(text)?.[1]?.toUpperCase() ?? "";
+    const update = UPDATE_KEYWORDS.test(text) || semicolonOutside(text);
+    const form = !update && ["CONSTRUCT", "DESCRIBE", "SELECT", "ASK"].includes(first) ? first.toLowerCase() : null;
+    // the solution modifiers follow the last closing brace (a trailing VALUES block is not handled)
+    const tail = text.slice(text.lastIndexOf("}") + 1);
+    let templateVars: string[] = [];
+    if (form === "construct") {
+        const template = /\bCONSTRUCT\s*\{([^}]*)\}/i.exec(body)?.[1] ?? "";
+        templateVars = [...new Set(template.match(/[?$]\w+/g) ?? [])].map((v) => `?${v.slice(1)}`);
+    }
+    return {
+        form: form as QueryForm,
+        ownLimit: /\b(LIMIT|OFFSET)\b/i.test(tail),
+        ordered: /\bORDER\s+BY\b/i.test(tail),
+        templateVars,
+    };
+}
+
+/**
+ * The caller's query with one page's modifiers added.
+ * @param query - the query
+ * @param shape - what readQuery found
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query to send
+ */
+export function pagedQuery(query: string, shape: UserQuery, limit: number, offset: number): string {
+    const order = shape.ordered || shape.templateVars.length === 0 ? "" : `\nORDER BY ${shape.templateVars.join(" ")}`;
+    const skip = offset > 0 ? ` OFFSET ${String(offset)}` : "";
+    return `${query.trimEnd()}${order}\nLIMIT ${String(limit)}${skip}`;
+}
+
+/**
+ * An IRI as a SPARQL term, or null when it cannot be one.
+ * @param id - the id
+ * @returns `<iri>`, or null
+ */
+export function iriTerm(id: unknown): string | null {
+    const text = String(id);
+    return /^[a-z][\w+.-]*:/i.test(text) && !NOT_IRI.test(text) ? `<${text}>` : null;
+}
+
+/** What generated queries keep: literals in a language, edges along some predicates. */
+interface TripleFilter {
+    /** Keep literals tagged with this language or untagged; "" keeps every literal. */
+    readonly language: string;
+    /** Keep edges whose predicate starts with one of these IRIs; empty keeps every edge. */
+    readonly predicates: readonly string[];
+}
+
+/**
+ * The FILTERs of generated queries, or "" for none. Both values are checked by the caller.
+ * @param filter - the language and the predicate prefixes
+ * @returns the FILTER clauses
+ */
+function filters(filter: TripleFilter): string {
+    const { language, predicates } = filter;
+    const lang =
+        language === "" ? "" : ` FILTER(!isLiteral(?o) || lang(?o) = "" || langMatches(lang(?o), "${language}"))`;
+    const along = predicates.map((p) => `STRSTARTS(STR(?p), "${p}")`).join(" || ");
+    return predicates.length === 0 ? lang : `${lang} FILTER(isLiteral(?o) || ${along})`;
+}
+
+/**
+ * Whether a language tag may go into a FILTER.
+ * @param language - the tag
+ * @returns whether it is well formed
+ */
+export function validLanguage(language: string): boolean {
+    return LANGUAGE.test(language);
+}
+
+/**
+ * Mode "all": every triple, ordered so pages are stable.
+ * @param filter - what to keep
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query
+ */
+export function allQuery(filter: TripleFilter, limit: number, offset: number): string {
+    return pagedQuery(
+        `CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o .${filters(filter)} }`,
+        { form: "construct", ownLimit: false, ordered: false, templateVars: ["?s", "?p", "?o"] },
+        limit,
+        offset,
+    );
+}
+
+/**
+ * The triples around some IRIs: out (`VALUES ?s`), in (`VALUES ?o`) or both.
+ * @param iris - the IRIs as terms
+ * @param direction - which triples
+ * @param filter - what to keep
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query
+ */
+export function aroundQuery(
+    iris: readonly string[],
+    direction: "out" | "in" | "both",
+    filter: TripleFilter,
+    limit: number,
+    offset: number,
+): string {
+    const values = iris.join(" ");
+    const out = `{ VALUES ?s { ${values} } ?s ?p ?o .${filters(filter)} }`;
+    const inward = `{ VALUES ?o { ${values} } ?s ?p ?o .${filters({ ...filter, language: "" })} }`;
+    let where = `${out} UNION ${inward}`;
+    if (direction !== "both") {
+        where = direction === "out" ? out : inward;
+    }
+    return pagedQuery(
+        `CONSTRUCT { ?s ?p ?o } WHERE { ${where} }`,
+        { form: "construct", ownLimit: false, ordered: false, templateVars: ["?s", "?p", "?o"] },
+        limit,
+        offset,
+    );
+}

package/src/sources/types.ts

@@ -223,6 +223,18 @@ export interface RetryOptions {
     readonly maxDelayMs?: number | undefined;
 }
 
+/**
+ * How much a source holds for a load, as it counted it, so a caller can show "100 of 28,455".
+ * Experimental.
+ * @category Network sources
+ */
+export interface SourceTotal {
+    /** The nodes the load's params match at the source. */
+    readonly nodes?: number | undefined;
+    /** The edges the load's params match at the source. */
+    readonly edges?: number | undefined;
+}
+
 /**
  * Facts a source reports with `ctx.finish()`. Experimental.
  * @category Network sources
@@ -243,6 +255,8 @@ export interface SourceFinish {
         | undefined;
     /** What lets a later call tell whether the data changed. */
     readonly validators?: SourceValidators | undefined;
+    /** What the source holds for this load, when it counted: the nodes and edges it matches. */
+    readonly total?: SourceTotal | undefined;
 }
 
 /**
@@ -357,6 +371,39 @@ export interface SourceSample {
         | undefined;
     /** false: too big to load whole; start from a neighborhood. */
     readonly whole?: boolean | undefined;
+    /**
+     * A node cap for loading the sample when the caller gives none, for a sample too big to load
+     * whole that pages: the load stops at the first page past it, and its cursor reads on.
+     */
+    readonly firstPage?: number | undefined;
+}
+
+/**
+ * One credential a source takes, as its descriptor declares it: a name a project file records
+ * instead of the credential, the kind, whether a load needs it, and for an API key how it is sent.
+ * `credentials.forSlot(slot, value)` makes the credential it describes. Experimental.
+ * @category Network sources
+ */
+export interface SourceCredentialSlot {
+    /** The slot's name, recorded as a load's `credentialSlot` ("api_key", "default"). */
+    readonly name: string;
+    /** The credential kind it takes. */
+    readonly kind: CredentialKind;
+    /** Whether a load needs it. @defaultValue false */
+    readonly required?: boolean | undefined;
+    /** Its default name; catalog data an application may replace by name. */
+    readonly plainName?: string | undefined;
+    /** For an API key: the query parameter or request header it is sent in. */
+    readonly send?:
+        | {
+              /** The query parameter the key is sent in. */
+              readonly query: string;
+          }
+        | {
+              /** The request header the key is sent in. */
+              readonly header: string;
+          }
+        | undefined;
 }
 
 /**
@@ -377,6 +424,25 @@ export interface SourceDescriptor {
     readonly auth?: readonly CredentialKind[] | undefined;
     /** Whether a credential is needed. @defaultValue "none" */
     readonly authRequired?: "required" | "optional" | "none" | undefined;
+    /**
+     * The credential slots it takes. A source that takes a credential (`auth`) and declares none
+     * has one slot, `default`: `credentialSlots(descriptor)` reads either. @defaultValue []
+     */
+    readonly credentials?: readonly SourceCredentialSlot[] | undefined;
+    /**
+     * Where an `api-key` credential goes, for a form that asks for the key alone: pass it to
+     * `credentials.apiKey(descriptor.apiKey, key)`. Absent when the caller must say.
+     */
+    readonly apiKey?:
+        | {
+              /** The request header that carries the key. */
+              readonly header: string;
+          }
+        | {
+              /** The query parameter that carries the key. */
+              readonly query: string;
+          }
+        | undefined;
     /** The endpoint used when the caller names none. @defaultValue null */
     readonly defaultEndpoint?: string | null | undefined;
     /** Where it runs; a runtime marked unsupported is refused with E_SOURCE_RUNTIME before any request. */
@@ -584,6 +650,8 @@ export interface SourceReportInfo {
         | undefined;
     /** What lets a later call tell whether the data changed. */
     readonly validators?: SourceValidators | undefined;
+    /** What the source holds for this load, when it counted: the nodes and edges it matches. */
+    readonly total?: SourceTotal | undefined;
 }
 
 /**

package/src/styles/annotations.ts

@@ -33,12 +33,21 @@ export interface AnnotationBase {
     readonly z: number;
 }
 
+/**
+ * How far an annotation is turned about its box's center, in degrees, clockwise as seen on screen (0: not turned).
+ * Shapes, texts and pictures carry it; Cytoscape saves it as `rotation`.
+ */
+interface RotatedAnnotation {
+    /** The turn in degrees, clockwise on screen. */
+    readonly rotation: number;
+}
+
 /**
  * A filled, outlined shape.
  * @category Styles
  */
-export interface ShapeAnnotation extends AnnotationBase {
-    /** Which kind of annotation this is: always "shape". */
+export interface ShapeAnnotation extends AnnotationBase, RotatedAnnotation {
+    /** What the annotation is: always `"shape"` for a shape. */
     readonly kind: "shape";
     /** The box's center. */
     readonly center: AnnotationPoint;
@@ -64,8 +73,8 @@ export interface ShapeAnnotation extends AnnotationBase {
  * A line of text.
  * @category Styles
  */
-export interface TextAnnotation extends AnnotationBase {
-    /** Which kind of annotation this is: always "text". */
+export interface TextAnnotation extends AnnotationBase, RotatedAnnotation {
+    /** What the annotation is: always `"text"` for a line of text. */
     readonly kind: "text";
     /** The text. */
     readonly text: string;
@@ -92,7 +101,7 @@ export interface TextAnnotation extends AnnotationBase {
  * @category Styles
  */
 export interface ArrowAnnotation extends AnnotationBase {
-    /** Which kind of annotation this is: always "arrow". */
+    /** What the annotation is: always `"arrow"` for an arrow. */
     readonly kind: "arrow";
     /** Where the line starts. */
     readonly from: AnnotationPoint;
@@ -112,6 +121,46 @@ export interface ArrowAnnotation extends AnnotationBase {
     readonly sourceSize: number;
     /** The end's arrowhead size as a factor of the normal size. */
     readonly targetSize: number;
+    /** The arrowhead color at the start. */
+    readonly sourceColor: StyleColor;
+    /** The arrowhead color at the end. */
+    readonly targetColor: StyleColor;
+    /**
+     * How long the start's arrowhead is along the line, in the units of the points, size included; absent, the
+     * drawing program's own length for the line's width.
+     */
+    readonly sourceHeadLength?: number;
+    /** How wide the start's arrowhead is across the line, as `sourceHeadLength` says. */
+    readonly sourceHeadWidth?: number;
+    /** How long the end's arrowhead is along the line, as `sourceHeadLength` says. */
+    readonly targetHeadLength?: number;
+    /** How wide the end's arrowhead is across the line, as `sourceHeadLength` says. */
+    readonly targetHeadWidth?: number;
+}
+
+/**
+ * A picture placed in a box, which `readImageAnnotations()` reads.
+ * @category Styles
+ */
+export interface ImageAnnotation extends AnnotationBase, RotatedAnnotation {
+    /** What the annotation is: always `"image"` for a picture. */
+    readonly kind: "image";
+    /** The box's center. */
+    readonly center: AnnotationPoint;
+    /** The box's width; the picture is stretched to it. */
+    readonly width: number;
+    /** The box's height. */
+    readonly height: number;
+    /** Where the picture is, as the file names it. */
+    readonly url: string;
+    /** The picture's opacity, 0..1. */
+    readonly opacity: number;
+    /** The outline's color. */
+    readonly borderColor: StyleColor;
+    /** The outline's opacity, 0..1 (0 draws none). */
+    readonly borderOpacity: number;
+    /** The outline's width (0 draws none). */
+    readonly borderWidth: number;
 }
 
 /**
@@ -151,11 +200,13 @@ const SHAPES: ReadonlyMap<string, StyleNodeShape> = new Map<string, StyleNodeSha
     ["parallelogram", "parallelogram"],
     ["star5", "star"],
     ["star6", "star"],
+    ["v", "vee"],
 ]);
 
 /**
- * Cytoscape's annotation arrowheads, by the position in its `ArrowType` list (older sessions) and by name (newer
- * ones), lowercase.
+ * Cytoscape's annotation arrowheads, by the number it saves (the declaration order of ding's
+ * `ArrowAnnotationImpl.ArrowType` in 3.10: Circle, Closed Arrow, Concave Arrow, Diamond, Open Arrow, No Arrow,
+ * X Arrow, Triangular Head, T-Shape) and by its display name, lowercase.
  */
 const ARROW_ORDER: readonly StyleArrowShape[] = [
     "circle",
@@ -164,13 +215,18 @@ const ARROW_ORDER: readonly StyleArrowShape[] = [
     "diamond",
     "triangle-open",
     "none",
-    "tee",
-    "triangle",
-    "triangle",
+    "other:x",
     "triangle",
     "tee",
-    "other:x",
 ];
+/**
+ * How long along its line each of Cytoscape's annotation arrowheads is drawn at size 1, by its `ArrowType` position,
+ * every one 10 wide whatever the line's width (measured on Cytoscape 3.10.5's SVG of `specimen-images-charts-p6`):
+ * the Closed, Concave, Diamond and Open Arrows 17, the Circle and the X 10, the Triangular Head 5, the T a bar across.
+ */
+const ARROW_LENGTHS: readonly number[] = [10, 17, 17, 17, 17, 0, 10, 5, 0];
+/** How wide across its line every Cytoscape annotation arrowhead is at size 1. */
+const ARROW_WIDTH = 10;
 const ARROW_NAMES: ReadonlyMap<string, StyleArrowShape> = new Map<string, StyleArrowShape>([
     ["circle", "circle"],
     ["closed arrow", "triangle"],
@@ -181,7 +237,10 @@ const ARROW_NAMES: ReadonlyMap<string, StyleArrowShape> = new Map<string, StyleA
     ["pipe", "tee"],
     ["triangle", "triangle"],
     ["t", "tee"],
+    ["t-shape", "tee"],
+    ["triangular head", "triangle"],
     ["x", "other:x"],
+    ["x arrow", "other:x"],
 ]);
 
 /**
@@ -209,6 +268,49 @@ export function readAnnotations(snapshot: GraphSnapshot): FileAnnotations {
     return { annotations, skipped: [...skipped] };
 }
 
+/**
+ * The pictures a graph's annotations place, from the column Cytoscape desktop keeps them in: the annotations
+ * `readAnnotations()` lists as skipped `ImageAnnotation`s.
+ * @param snapshot - the graph
+ * @returns the pictures, in the file's order; none when the graph has none
+ * @category Styles
+ */
+export function readImageAnnotations(snapshot: GraphSnapshot): ImageAnnotation[] {
+    const { graph } = snapshot;
+    const cell = graph.has(CYTOSCAPE_ANNOTATIONS_COLUMN) ? graph.value(CYTOSCAPE_ANNOTATIONS_COLUMN, 0) : null;
+    return cellStrings(cell).flatMap((entry, i) => {
+        const f = parseEntry(entry);
+        const url = f.get("URL") ?? "";
+        if ((f.get("type") ?? "").replace(TYPE_PREFIX, "") !== "ImageAnnotation" || url === "") {
+            return [];
+        }
+        const zoom = positive(f.get("zoom")) ?? 1;
+        const x = num(f.get("x")) ?? 0;
+        const y = num(f.get("y")) ?? 0;
+        const width = (positive(f.get("width")) ?? 0) / zoom;
+        const height = (positive(f.get("height")) ?? 0) / zoom;
+        const border = javaColor(f.get("edgeColor")) ?? { color: "#000000", alpha: 1 };
+        const opacity = num(f.get("opacity"));
+        return [
+            {
+                id: f.get("uuid") ?? String(i),
+                layer: f.get("canvas") === "background" ? "background" : "foreground",
+                z: num(f.get("z")) ?? 0,
+                kind: "image",
+                rotation: num(f.get("rotation")) ?? 0,
+                center: { x: x + width / 2, y: -(y + height / 2) },
+                width,
+                height,
+                url,
+                opacity: opacity === null ? 1 : Math.min(1, Math.max(0, opacity)),
+                borderColor: border.color,
+                borderOpacity: border.alpha * percent(f.get("edgeOpacity")),
+                borderWidth: (num(f.get("edgeThickness")) ?? 0) / zoom,
+            },
+        ];
+    });
+}
+
 /**
  * A cell's strings: a list cell's items, or the lines of a text cell.
  * @param cell - the cell
@@ -292,6 +394,7 @@ function shapeOf(f: ReadonlyMap<string, string>, base: AnnotationBase, zoom: num
     return {
         ...base,
         kind: "shape",
+        rotation: num(f.get("rotation")) ?? 0,
         center: { x: x + width / 2, y: -(y + height / 2) },
         width,
         height,
@@ -326,6 +429,7 @@ function textOf(
     return {
         ...base,
         kind: "text",
+        rotation: num(f.get("rotation")) ?? 0,
         text: f.get("text") ?? "",
         at,
         anchor,
@@ -340,9 +444,11 @@ function textOf(
 
 /**
  * An arrow annotation. Cytoscape keeps its start as the annotation it leaves (`sourceAnnotation`) and its end as a
- * point, a node's center at save time (`targetNode`) or another annotation, and saves the arrow's top-left corner
- * as `x`, `y`: the start wherever the end lies right of and below it, which is taken for the start, else the center
- * of the annotation it leaves.
+ * point (`targetPoint`), a node's center at save time (`targetNode`) or another annotation (`targetAnnotation`). It
+ * draws the line from the middle of the side of the source annotation's box that faces the end, to the end point or
+ * the middle of the facing side of the target annotation's box, at half the saved `lineThickness` and never under
+ * 1 (measured on Cytoscape 3.10.5's SVG of `specimen-images-charts-p6` and of the tutorial session). A source with
+ * no saved size (a text annotation) leaves from the arrow's saved `x`, `y` corner.
  * @param f - its fields
  * @param base - its id, layer and order
  * @param zoom - the zoom its line width was saved at
@@ -355,17 +461,26 @@ function arrowOf(
     zoom: number,
     byId: ReadonlyMap<string, ReadonlyMap<string, string>>,
 ): ArrowAnnotation[] | null {
-    const target = f.get("targetAnnotation");
-    const to = point(f.get("targetPoint")) ?? point(f.get("targetNode")) ?? centerOf(byId.get(target ?? ""), zoom);
-    if (to === null) {
+    const sourceBox = boxOf(byId.get(f.get("sourceAnnotation") ?? ""), zoom);
+    const targetBox = boxOf(byId.get(f.get("targetAnnotation") ?? ""), zoom);
+    const toPoint = point(f.get("targetPoint")) ?? point(f.get("targetNode"));
+    const corner = { x: num(f.get("x")) ?? 0, y: num(f.get("y")) ?? 0 };
+    const sourceCenter = sourceBox === null ? corner : centerOfBox(sourceBox);
+    const aim = toPoint ?? (targetBox === null ? null : centerOfBox(targetBox));
+    if (aim === null) {
         return null;
     }
-    const corner = { x: num(f.get("x")) ?? 0, y: num(f.get("y")) ?? 0 };
-    const source = centerOf(byId.get(f.get("sourceAnnotation") ?? ""), zoom) ?? corner;
-    // ponytail: the start is exact only when the end lies right of and below it; elsewhere the center of the
-    // annotation it leaves, as Cytoscape stores no other start. Clip to that annotation's box if it matters.
-    const from = { x: to.x > corner.x ? corner.x : source.x, y: to.y > corner.y ? corner.y : source.y };
+    // a source with no saved size (a text) leaves from the arrow's saved top-left corner where the end lies right of
+    // and below it, else from the source's corner: the file keeps no other trace of where the text was drawn
+    const from =
+        sourceBox !== null && sourceBox.width > 0 && sourceBox.height > 0
+            ? facing(sourceBox, aim)
+            : { x: aim.x > corner.x ? corner.x : sourceCenter.x, y: aim.y > corner.y ? corner.y : sourceCenter.y };
+    // ponytail: a node end stops at its center; Cytoscape stops at the node's box, which needs the node's size
+    const to = toPoint ?? facing(targetBox ?? { x: aim.x, y: aim.y, width: 0, height: 0 }, sourceCenter);
     const color = javaColor(f.get("lineColor")) ?? { color: "#000000", alpha: 1 };
+    const sourceColor = javaColor(f.get("sourceColor"))?.color ?? color.color;
+    const targetColor = javaColor(f.get("targetColor"))?.color ?? color.color;
     return [
         {
             ...base,
@@ -374,22 +489,55 @@ function arrowOf(
             to: { x: to.x, y: -to.y },
             color: color.color,
             opacity: color.alpha * percent(f.get("lineOpacity")),
-            width: (positive(f.get("lineThickness")) ?? 1) / zoom,
+            width: Math.max(1, (positive(f.get("lineThickness")) ?? 1) / zoom / 2),
             sourceArrow: arrowShape(f.get("sourceType")),
             targetArrow: arrowShape(f.get("targetType")),
             sourceSize: positive(f.get("sourceSize")) ?? 1,
             targetSize: positive(f.get("targetSize")) ?? 1,
+            sourceColor,
+            targetColor,
+            ...heads("source", f.get("sourceType"), positive(f.get("sourceSize")) ?? 1),
+            ...heads("target", f.get("targetType"), positive(f.get("targetSize")) ?? 1),
         },
     ];
 }
 
 /**
- * An annotation's center, y down as the file writes it: a shape's box center, a text's corner.
+ * The length and width Cytoscape draws one end's arrowhead at: its type's length and 10 across, times its size.
+ * @param end - which end
+ * @param type - the end's saved `ArrowType`, a position or a name
+ * @param size - the end's saved size
+ * @returns the end's head length and width, none for an end without a head
+ */
+function heads(
+    end: "source" | "target",
+    type: string | undefined,
+    size: number,
+): Partial<Pick<ArrowAnnotation, "sourceHeadLength" | "sourceHeadWidth" | "targetHeadLength" | "targetHeadWidth">> {
+    const shape = arrowShape(type);
+    if (shape === "none") {
+        return {};
+    }
+    const k = num(type) ?? ARROW_ORDER.indexOf(shape);
+    const length = ARROW_LENGTHS[k] ?? ARROW_LENGTHS[1];
+    return { [`${end}HeadLength`]: length * size, [`${end}HeadWidth`]: ARROW_WIDTH * size };
+}
+
+/** An annotation's box as the file writes it: top-left corner, y down. */
+interface FileBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+/**
+ * An annotation's box, y down as the file writes it.
  * @param f - its fields, or undefined
  * @param zoom - the zoom the arrow was saved at
- * @returns the point, or null
+ * @returns the box, or null
  */
-function centerOf(f: ReadonlyMap<string, string> | undefined, zoom: number): AnnotationPoint | null {
+function boxOf(f: ReadonlyMap<string, string> | undefined, zoom: number): FileBox | null {
     if (f === undefined) {
         return null;
     }
@@ -398,7 +546,33 @@ function centerOf(f: ReadonlyMap<string, string> | undefined, zoom: number): Ann
     if (x === null || y === null) {
         return null;
     }
-    return { x: x + (positive(f.get("width")) ?? 0) / zoom / 2, y: y + (positive(f.get("height")) ?? 0) / zoom / 2 };
+    return { x, y, width: (positive(f.get("width")) ?? 0) / zoom, height: (positive(f.get("height")) ?? 0) / zoom };
+}
+
+/**
+ * A box's center.
+ * @param b - the box
+ * @returns the center
+ */
+function centerOfBox(b: FileBox): AnnotationPoint {
+    return { x: b.x + b.width / 2, y: b.y + b.height / 2 };
+}
+
+/**
+ * The middle of the side of a box that faces a point: a left or right side when the point lies more across than
+ * along, against the box's own proportions, else the top or bottom.
+ * @param b - the box
+ * @param p - the point
+ * @returns the side's middle
+ */
+function facing(b: FileBox, p: AnnotationPoint): AnnotationPoint {
+    const c = centerOfBox(b);
+    const dx = p.x - c.x;
+    const dy = p.y - c.y;
+    if (Math.abs(dx) * b.height >= Math.abs(dy) * b.width) {
+        return { x: c.x + Math.sign(dx) * (b.width / 2), y: c.y };
+    }
+    return { x: c.x, y: c.y + Math.sign(dy) * (b.height / 2) };
 }
 
 /**