ts-visio 1.7.0 → 1.10.0

package/README.md

@@ -27,6 +27,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **Document Metadata**: Read and write document properties (title, author, description, keywords, company, dates) via `doc.getMetadata()` / `doc.setMetadata()`.
 - **Named Connection Points**: Define specific ports on shapes (`Top`, `Right`, etc.) and connect to them precisely using `fromPort`/`toPort` on any connector API.
 - **StyleSheets**: Create document-level named styles with fill, line, and text properties via `doc.createStyle()` and apply them to shapes at creation time (`styleId`) or post-creation (`shape.applyStyle()`).
+- **Color Palette**: Register named colors in the document's color table via `doc.addColor()` and look them up by index or hex value with `doc.getColors()` / `doc.getColorIndex()`.
 
 Feature gaps are being tracked in [FEATURES.md](./FEATURES.md).
 
@@ -153,7 +154,7 @@ await shape1.setStyle({ fillColor: '#00FF00' })
 Use specific arrowheads (Crow's Foot, etc.)
 
 ```typescript
-import { ArrowHeads } from 'ts-visio/utils/StyleHelpers';
+import { ArrowHeads } from 'ts-visio';
 
 await page.connectShapes(shape1, shape2, ArrowHeads.One, ArrowHeads.CrowsFoot);
 // OR
@@ -449,7 +450,7 @@ Supported values: `'rectangle'` (default), `'ellipse'`, `'diamond'`, `'rounded-r
 Control line appearance and routing algorithm on any connector.
 
 ```typescript
-import { ArrowHeads } from 'ts-visio/utils/StyleHelpers';
+import { ArrowHeads } from 'ts-visio';
 
 // Styled connector with crow's foot arrow and custom line
 await shape1.connectTo(shape2, ArrowHeads.One, ArrowHeads.CrowsFoot, {
@@ -664,6 +665,67 @@ const styles = doc.getStyles();
 `StyleProps` supports: `fillColor`, `lineColor`, `lineWeight` (pt), `linePattern`, `fontColor`, `fontSize` (pt), `bold`, `italic`, `underline`, `strikethrough`, `fontFamily`, `horzAlign`, `verticalAlign`, `spaceBefore`, `spaceAfter`, `lineSpacing`, `textMarginTop/Bottom/Left/Right` (in).
 Local shape properties always override inherited stylesheet values.
 
+#### 30. Reading Connectors Back
+Enumerate connectors on a page — including those loaded from an existing `.vsdx` file — and inspect or delete them.
+
+```typescript
+import { VisioDocument } from 'ts-visio';
+
+const doc  = await VisioDocument.load(buffer);   // or VisioDocument.create()
+const page = doc.pages[0];
+
+// Read all connector shapes
+const connectors = page.getConnectors();
+
+for (const conn of connectors) {
+    console.log(`Connector ${conn.id}: ${conn.fromShapeId} → ${conn.toShapeId}`);
+    console.log('  fromPort:', conn.fromPort);     // 'center' | { name } | { index }
+    console.log('  toPort:',   conn.toPort);
+    console.log('  style:',    conn.style);        // lineColor, lineWeight, linePattern, routing
+    console.log('  arrows:',   conn.beginArrow, conn.endArrow);
+}
+
+// Delete a specific connector
+await connectors[0].delete();
+
+// After delete the connector is gone but the shapes remain
+console.log(page.getConnectors().length);  // 0
+console.log(page.getShapes().length);      // shapes still exist
+```
+
+#### 31. Color Palette
+Register colors in the document's indexed color table (`<Colors>` in `document.xml`). Colors are identified by an integer IX that you can reference anywhere a hex color is accepted.
+
+```typescript
+// Register colors — returns the integer index (IX)
+const blueIx  = doc.addColor('#4472C4');  // → 2 (first user color)
+const redIx   = doc.addColor('#FF0000');  // → 3
+const greenIx = doc.addColor('#00B050');  // → 4
+
+// De-duplication: adding the same color returns the existing index
+doc.addColor('#4472C4');  // → 2 (no duplicate created)
+
+// Shorthand, missing #, and case variations are all normalised
+doc.addColor('#FFF');        // same as #FFFFFF → returns 1 (built-in white)
+doc.addColor('4472c4');      // same as #4472C4 → returns 2
+
+// Read the full palette (sorted by index)
+const palette = doc.getColors();
+// [
+//   { index: 0, rgb: '#000000' },  // built-in black
+//   { index: 1, rgb: '#FFFFFF' },  // built-in white
+//   { index: 2, rgb: '#4472C4' },
+//   { index: 3, rgb: '#FF0000' },
+//   { index: 4, rgb: '#00B050' },
+// ]
+
+// Look up an index by hex value
+doc.getColorIndex('#4472C4');  // → 2
+doc.getColorIndex('#123456');  // → undefined (not registered)
+```
+
+Built-in colors: IX 0 = `#000000` (black), IX 1 = `#FFFFFF` (white). User colors start at IX 2 and increment sequentially.
+
 ---
 
 ## Examples

package/dist/Connector.d.ts

@@ -0,0 +1,53 @@
+import { ConnectorStyle, ConnectionTarget } from './types/VisioTypes';
+import { ShapeModifier } from './ShapeModifier';
+/**
+ * Raw data extracted from the page XML for a single connector shape.
+ * Returned by `ShapeReader.readConnectors()` and wrapped by the `Connector` class.
+ */
+export interface ConnectorData {
+    /** Visio shape ID of the connector (1D shape). */
+    id: string;
+    /** ID of the shape at the connector's begin-point (BeginX). */
+    fromShapeId: string;
+    /** ID of the shape at the connector's end-point (EndX). */
+    toShapeId: string;
+    /** Connection point used on the from-shape. */
+    fromPort: ConnectionTarget;
+    /** Connection point used on the to-shape. */
+    toPort: ConnectionTarget;
+    /** Line style extracted from the connector's Line section. */
+    style: ConnectorStyle;
+    /** Begin-arrow head value (Visio ArrowHeads integer string). */
+    beginArrow: string;
+    /** End-arrow head value (Visio ArrowHeads integer string). */
+    endArrow: string;
+}
+/**
+ * A read/delete wrapper around a connector shape found on a page.
+ * Obtain instances via `page.getConnectors()`.
+ */
+export declare class Connector {
+    private readonly pageId;
+    private readonly modifier;
+    /** Visio shape ID of this connector. */
+    readonly id: string;
+    /** ID of the shape this connector starts from. */
+    readonly fromShapeId: string;
+    /** ID of the shape this connector ends at. */
+    readonly toShapeId: string;
+    /** Connection point used on the from-shape ('center', `{ name }`, or `{ index }`). */
+    readonly fromPort: ConnectionTarget;
+    /** Connection point used on the to-shape ('center', `{ name }`, or `{ index }`). */
+    readonly toPort: ConnectionTarget;
+    /** Line style (color, weight, pattern, routing) for this connector. */
+    readonly style: ConnectorStyle;
+    /** Begin-arrow head value string (e.g. `'0'` = none, `'1'` = standard). */
+    readonly beginArrow: string;
+    /** End-arrow head value string (e.g. `'0'` = none, `'1'` = standard). */
+    readonly endArrow: string;
+    constructor(data: ConnectorData, pageId: string, modifier: ShapeModifier);
+    /**
+     * Delete this connector from the page (removes the shape and its Connect entries).
+     */
+    delete(): Promise<void>;
+}

package/dist/Connector.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Connector = void 0;
+/**
+ * A read/delete wrapper around a connector shape found on a page.
+ * Obtain instances via `page.getConnectors()`.
+ */
+class Connector {
+    constructor(data, pageId, modifier) {
+        this.pageId = pageId;
+        this.modifier = modifier;
+        this.id = data.id;
+        this.fromShapeId = data.fromShapeId;
+        this.toShapeId = data.toShapeId;
+        this.fromPort = data.fromPort;
+        this.toPort = data.toPort;
+        this.style = data.style;
+        this.beginArrow = data.beginArrow;
+        this.endArrow = data.endArrow;
+    }
+    /**
+     * Delete this connector from the page (removes the shape and its Connect entries).
+     */
+    async delete() {
+        await this.modifier.deleteShape(this.pageId, this.id);
+    }
+}
+exports.Connector = Connector;

package/dist/Page.d.ts

@@ -1,4 +1,5 @@
 import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName, ConnectionTarget } from './types/VisioTypes';
+import { Connector } from './Connector';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier } from './ShapeModifier';
 import { NewShapeProps } from './types/VisioTypes';
@@ -50,6 +51,12 @@ export declare class Page {
      */
     findShapes(predicate: (shape: Shape) => boolean): Shape[];
     addShape(props: NewShapeProps, parentId?: string): Promise<Shape>;
+    /**
+     * Return all connector shapes on the page.
+     * Each `Connector` exposes the from/to shape IDs, port targets, line style, arrows,
+     * and a `delete()` method to remove the connector.
+     */
+    getConnectors(): Connector[];
     connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): Promise<void>;
     addImage(data: Buffer, name: string, x: number, y: number, width: number, height: number): Promise<Shape>;
     addContainer(props: NewShapeProps): Promise<Shape>;

package/dist/Page.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Page = void 0;
 const VisioTypes_1 = require("./types/VisioTypes");
+const Connector_1 = require("./Connector");
 const ShapeReader_1 = require("./ShapeReader");
 const ShapeModifier_1 = require("./ShapeModifier");
 const Shape_1 = require("./Shape");
@@ -124,6 +125,22 @@ class Page {
         });
         return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
+    /**
+     * Return all connector shapes on the page.
+     * Each `Connector` exposes the from/to shape IDs, port targets, line style, arrows,
+     * and a `delete()` method to remove the connector.
+     */
+    getConnectors() {
+        const reader = new ShapeReader_1.ShapeReader(this.pkg);
+        try {
+            const data = reader.readConnectors(this.pagePath);
+            return data.map(d => new Connector_1.Connector(d, this.id, this.modifier));
+        }
+        catch (e) {
+            console.warn(`Could not read connectors for page ${this.id}:`, e);
+            return [];
+        }
+    }
     async connectShapes(fromShape, toShape, beginArrow, endArrow, style, fromPort, toPort) {
         await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow, style, fromPort, toPort);
     }

package/dist/ShapeModifier.d.ts

@@ -131,6 +131,12 @@ export declare class ShapeModifier {
 }
 export interface ShapeStyle {
     fillColor?: string;
+    /** Border/stroke colour as a CSS hex string (e.g. `'#cc0000'`). */
+    lineColor?: string;
+    /** Stroke weight in **points**. Stored internally as inches (pt / 72). */
+    lineWeight?: number;
+    /** Line pattern. 0 = none, 1 = solid (default), 2 = dash, 3 = dot, 4 = dash-dot. */
+    linePattern?: number;
     fontColor?: string;
     bold?: boolean;
     /** Italic text. */

package/dist/ShapeModifier.js

@@ -400,6 +400,18 @@ class ShapeModifier {
             shape.Section = shape.Section.filter((s) => s['@_N'] !== 'Fill');
             shape.Section.push((0, StyleHelpers_1.createFillSection)(style.fillColor));
         }
+        // Update/Add Line
+        const hasLineProps = style.lineColor !== undefined
+            || style.lineWeight !== undefined
+            || style.linePattern !== undefined;
+        if (hasLineProps) {
+            shape.Section = shape.Section.filter((s) => s['@_N'] !== 'Line');
+            shape.Section.push((0, StyleHelpers_1.createLineSection)({
+                color: style.lineColor,
+                weight: style.lineWeight !== undefined ? (style.lineWeight / 72).toString() : undefined,
+                pattern: style.linePattern !== undefined ? style.linePattern.toString() : undefined,
+            }));
+        }
         // Update/Add Character (Font/Text Style)
         const hasCharProps = style.fontColor !== undefined
             || style.bold !== undefined

package/dist/ShapeReader.d.ts

@@ -1,5 +1,6 @@
 import { VisioPackage } from './VisioPackage';
 import { VisioShape } from './types/VisioTypes';
+import { ConnectorData } from './Connector';
 export declare class ShapeReader {
     private pkg;
     private parser;
@@ -15,6 +16,14 @@ export declare class ShapeReader {
      * Returns undefined if not found.
      */
     readShapeById(path: string, shapeId: string): VisioShape | undefined;
+    /**
+     * Read all connector shapes from a page XML file.
+     * A shape is considered a connector if it has `ObjType=2` or a `BeginX` cell,
+     * and is referenced in the page's `<Connects>` section.
+     */
+    readConnectors(path: string): ConnectorData[];
+    /** Decode a Visio ToPart integer string to a ConnectionTarget. */
+    private decodeToPart;
     private gatherShapes;
     private findShapeById;
     private parseShape;

package/dist/ShapeReader.js

@@ -63,6 +63,125 @@ class ShapeReader {
             return undefined;
         return this.findShapeById((0, VisioParsers_1.asArray)(shapesData), shapeId);
     }
+    /**
+     * Read all connector shapes from a page XML file.
+     * A shape is considered a connector if it has `ObjType=2` or a `BeginX` cell,
+     * and is referenced in the page's `<Connects>` section.
+     */
+    readConnectors(path) {
+        let content;
+        try {
+            content = this.pkg.getFileText(path);
+        }
+        catch {
+            return [];
+        }
+        const parsed = this.parser.parse(content);
+        const shapesData = parsed.PageContents?.Shapes?.Shape;
+        if (!shapesData)
+            return [];
+        // Build a flat map of all shapes by ID (including nested)
+        const shapeMap = new Map();
+        const collectShapes = (list) => {
+            for (const s of list) {
+                shapeMap.set(s['@_ID'], s);
+                if (s.Shapes?.Shape)
+                    collectShapes((0, VisioParsers_1.asArray)(s.Shapes.Shape));
+            }
+        };
+        collectShapes((0, VisioParsers_1.asArray)(shapesData));
+        // Identify connector shapes by ObjType=2 or presence of BeginX cell
+        const connectorShapes = [];
+        for (const [, shape] of shapeMap) {
+            const cells = (0, VisioParsers_1.parseCells)(shape);
+            if (cells['ObjType']?.V === '2' || cells['BeginX'] !== undefined) {
+                connectorShapes.push(shape);
+            }
+        }
+        if (connectorShapes.length === 0)
+            return [];
+        // Group <Connect> elements by connector ID (FromSheet)
+        const connectsRaw = parsed.PageContents?.Connects?.Connect;
+        const connects = (0, VisioParsers_1.asArray)(connectsRaw);
+        const connectsByConnector = new Map();
+        for (const c of connects) {
+            const fromSheet = c['@_FromSheet'];
+            const fromCell = c['@_FromCell'];
+            if (!connectsByConnector.has(fromSheet)) {
+                connectsByConnector.set(fromSheet, {});
+            }
+            const entry = connectsByConnector.get(fromSheet);
+            if (fromCell === 'BeginX')
+                entry.beginConnect = c;
+            else if (fromCell === 'EndX')
+                entry.endConnect = c;
+        }
+        const ROUTING_BY_VALUE = {
+            '1': 'orthogonal',
+            '2': 'straight',
+            '16': 'curved',
+        };
+        const result = [];
+        for (const connShape of connectorShapes) {
+            const connId = connShape['@_ID'];
+            const entry = connectsByConnector.get(connId);
+            if (!entry?.beginConnect || !entry?.endConnect)
+                continue;
+            const { beginConnect, endConnect } = entry;
+            const fromShapeId = beginConnect['@_ToSheet'];
+            const toShapeId = endConnect['@_ToSheet'];
+            const fromPort = this.decodeToPart(beginConnect['@_ToPart']);
+            const toPort = this.decodeToPart(endConnect['@_ToPart']);
+            // Extract line style from the connector's Line section
+            const sections = (0, VisioParsers_1.asArray)(connShape.Section);
+            let lineColor;
+            let lineWeight;
+            let linePattern;
+            for (const sec of sections) {
+                if (sec['@_N'] === 'Line') {
+                    const lineCells = (0, VisioParsers_1.parseCells)(sec);
+                    if (lineCells['LineColor']?.V)
+                        lineColor = lineCells['LineColor'].V;
+                    if (lineCells['LineWeight']?.V)
+                        lineWeight = parseFloat(lineCells['LineWeight'].V) * 72; // in→pt
+                    if (lineCells['LinePattern']?.V)
+                        linePattern = parseInt(lineCells['LinePattern'].V, 10);
+                }
+            }
+            const cells = (0, VisioParsers_1.parseCells)(connShape);
+            const routeStyleVal = cells['ShapeRouteStyle']?.V;
+            const routing = routeStyleVal ? ROUTING_BY_VALUE[routeStyleVal] : undefined;
+            const style = {};
+            if (lineColor !== undefined)
+                style.lineColor = lineColor;
+            if (lineWeight !== undefined)
+                style.lineWeight = lineWeight;
+            if (linePattern !== undefined)
+                style.linePattern = linePattern;
+            if (routing !== undefined)
+                style.routing = routing;
+            result.push({
+                id: connId,
+                fromShapeId,
+                toShapeId,
+                fromPort,
+                toPort,
+                style,
+                beginArrow: cells['BeginArrow']?.V ?? '0',
+                endArrow: cells['EndArrow']?.V ?? '0',
+            });
+        }
+        return result;
+    }
+    /** Decode a Visio ToPart integer string to a ConnectionTarget. */
+    decodeToPart(toPart) {
+        const part = toPart !== undefined ? parseInt(toPart, 10) : 3;
+        if (isNaN(part) || part === 3)
+            return 'center';
+        if (part >= 100)
+            return { index: part - 100 };
+        return 'center';
+    }
     gatherShapes(rawShapes, result) {
         for (const s of rawShapes) {
             result.push(this.parseShape(s));

package/dist/VisioDocument.d.ts

@@ -1,5 +1,5 @@
 import { Page } from './Page';
-import { DocumentMetadata, StyleProps, StyleRecord } from './types/VisioTypes';
+import { DocumentMetadata, StyleProps, StyleRecord, ColorEntry } from './types/VisioTypes';
 export declare class VisioDocument {
     private pkg;
     private pageManager;
@@ -7,6 +7,7 @@ export declare class VisioDocument {
     private mediaManager;
     private metadataManager;
     private styleSheetManager;
+    private colorManager;
     private constructor();
     static create(): Promise<VisioDocument>;
     static load(pathOrBuffer: string | Buffer | ArrayBuffer | Uint8Array): Promise<VisioDocument>;
@@ -56,5 +57,43 @@ export declare class VisioDocument {
      * Return all stylesheets defined in the document (including built-in styles).
      */
     getStyles(): StyleRecord[];
+    /**
+     * Add a color to the document-level color palette and return its integer index (IX).
+     *
+     * If the color is already registered the existing index is returned without
+     * creating a duplicate. The two built-in colors are always present:
+     *   - index 0  →  `#000000`  (black)
+     *   - index 1  →  `#FFFFFF`  (white)
+     *
+     * User colors receive indices starting at 2.
+     *
+     * @param hex  CSS hex string — `'#4472C4'`, `'#ABC'`, or `'4472c4'` are all accepted.
+     * @returns    Integer IX that uniquely identifies this color in the palette.
+     *
+     * @example
+     * const blueIx = doc.addColor('#4472C4');  // → 2
+     * const redIx  = doc.addColor('#FF0000');  // → 3
+     * doc.addColor('#4472C4');                 // → 2 (de-duplicated)
+     */
+    addColor(hex: string): number;
+    /**
+     * Return all color entries in the document palette, ordered by index.
+     *
+     * @example
+     * doc.addColor('#4472C4');
+     * doc.getColors();
+     * // → [{ index: 0, rgb: '#000000' }, { index: 1, rgb: '#FFFFFF' }, { index: 2, rgb: '#4472C4' }]
+     */
+    getColors(): ColorEntry[];
+    /**
+     * Look up the palette index of a color by its hex value.
+     * Returns `undefined` if the color has not been added to the palette.
+     *
+     * @example
+     * doc.addColor('#4472C4');
+     * doc.getColorIndex('#4472C4');  // → 2
+     * doc.getColorIndex('#FF0000');  // → undefined
+     */
+    getColorIndex(hex: string): number | undefined;
     save(filename?: string): Promise<Buffer>;
 }

package/dist/VisioDocument.js

@@ -40,6 +40,7 @@ const Page_1 = require("./Page");
 const MediaManager_1 = require("./core/MediaManager");
 const MetadataManager_1 = require("./core/MetadataManager");
 const StyleSheetManager_1 = require("./core/StyleSheetManager");
+const ColorManager_1 = require("./core/ColorManager");
 class VisioDocument {
     constructor(pkg) {
         this.pkg = pkg;
@@ -48,6 +49,7 @@ class VisioDocument {
         this.mediaManager = new MediaManager_1.MediaManager(pkg);
         this.metadataManager = new MetadataManager_1.MetadataManager(pkg);
         this.styleSheetManager = new StyleSheetManager_1.StyleSheetManager(pkg);
+        this.colorManager = new ColorManager_1.ColorManager(pkg);
     }
     static async create() {
         const pkg = await VisioPackage_1.VisioPackage.create();
@@ -169,6 +171,50 @@ class VisioDocument {
     getStyles() {
         return this.styleSheetManager.getStyles();
     }
+    /**
+     * Add a color to the document-level color palette and return its integer index (IX).
+     *
+     * If the color is already registered the existing index is returned without
+     * creating a duplicate. The two built-in colors are always present:
+     *   - index 0  →  `#000000`  (black)
+     *   - index 1  →  `#FFFFFF`  (white)
+     *
+     * User colors receive indices starting at 2.
+     *
+     * @param hex  CSS hex string — `'#4472C4'`, `'#ABC'`, or `'4472c4'` are all accepted.
+     * @returns    Integer IX that uniquely identifies this color in the palette.
+     *
+     * @example
+     * const blueIx = doc.addColor('#4472C4');  // → 2
+     * const redIx  = doc.addColor('#FF0000');  // → 3
+     * doc.addColor('#4472C4');                 // → 2 (de-duplicated)
+     */
+    addColor(hex) {
+        return this.colorManager.addColor(hex);
+    }
+    /**
+     * Return all color entries in the document palette, ordered by index.
+     *
+     * @example
+     * doc.addColor('#4472C4');
+     * doc.getColors();
+     * // → [{ index: 0, rgb: '#000000' }, { index: 1, rgb: '#FFFFFF' }, { index: 2, rgb: '#4472C4' }]
+     */
+    getColors() {
+        return this.colorManager.getColors();
+    }
+    /**
+     * Look up the palette index of a color by its hex value.
+     * Returns `undefined` if the color has not been added to the palette.
+     *
+     * @example
+     * doc.addColor('#4472C4');
+     * doc.getColorIndex('#4472C4');  // → 2
+     * doc.getColorIndex('#FF0000');  // → undefined
+     */
+    getColorIndex(hex) {
+        return this.colorManager.getColorIndex(hex);
+    }
     async save(filename) {
         return this.pkg.save(filename);
     }

package/dist/core/ColorManager.d.ts

@@ -0,0 +1,57 @@
+import { VisioPackage } from '../VisioPackage';
+import { ColorEntry } from '../types/VisioTypes';
+/**
+ * Manages the document-level color palette stored in `<Colors>` inside
+ * `visio/document.xml`.
+ *
+ * The palette is a simple indexed table — Visio identifies colors by their
+ * zero-based integer index (IX) as well as by their hex RGB value.
+ *
+ * Built-in entries (always present):
+ *   - IX 0  →  #000000  (black)
+ *   - IX 1  →  #FFFFFF  (white)
+ *
+ * User-added colors receive sequential indices starting at 2.
+ */
+export declare class ColorManager {
+    private pkg;
+    private parser;
+    private builder;
+    constructor(pkg: VisioPackage);
+    /**
+     * Add a color to the document palette and return its integer index (IX).
+     *
+     * If the color is already in the palette the existing index is returned
+     * without creating a duplicate. Built-in colors (black = 0, white = 1)
+     * are returned directly.
+     *
+     * @param hex  CSS hex string — `'#4472C4'`, `'#abc'`, `'4472c4'` all accepted.
+     * @returns    Integer IX that can be used as a color reference.
+     *
+     * @example
+     * const ix = doc.addColor('#4472C4');  // → 2 (first user color)
+     * await page.addShape({ text: 'Hi', fillColor: '#4472C4', ... });
+     */
+    addColor(hex: string): number;
+    /**
+     * Return all color entries currently in the document palette,
+     * ordered by index ascending.
+     */
+    getColors(): ColorEntry[];
+    /**
+     * Look up the index of a color in the palette by its hex value.
+     * Returns `undefined` if the color has not been registered.
+     *
+     * @example
+     * const ix = doc.getColorIndex('#4472C4');  // 2, or undefined if not added
+     */
+    getColorIndex(hex: string): number | undefined;
+    private getParsedDoc;
+    private saveParsedDoc;
+    /** Ensure `<Colors>` exists and contains the two built-in entries. */
+    private ensureColors;
+    /** Next IX = max existing index + 1, always at least 2. */
+    private nextIndex;
+    /** Minimal built-in palette returned when <Colors> is absent. */
+    private builtIns;
+}

package/dist/core/ColorManager.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColorManager = void 0;
+const XmlHelper_1 = require("../utils/XmlHelper");
+/**
+ * Manages the document-level color palette stored in `<Colors>` inside
+ * `visio/document.xml`.
+ *
+ * The palette is a simple indexed table — Visio identifies colors by their
+ * zero-based integer index (IX) as well as by their hex RGB value.
+ *
+ * Built-in entries (always present):
+ *   - IX 0  →  #000000  (black)
+ *   - IX 1  →  #FFFFFF  (white)
+ *
+ * User-added colors receive sequential indices starting at 2.
+ */
+class ColorManager {
+    constructor(pkg) {
+        this.pkg = pkg;
+        this.parser = (0, XmlHelper_1.createXmlParser)();
+        this.builder = (0, XmlHelper_1.createXmlBuilder)();
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Add a color to the document palette and return its integer index (IX).
+     *
+     * If the color is already in the palette the existing index is returned
+     * without creating a duplicate. Built-in colors (black = 0, white = 1)
+     * are returned directly.
+     *
+     * @param hex  CSS hex string — `'#4472C4'`, `'#abc'`, `'4472c4'` all accepted.
+     * @returns    Integer IX that can be used as a color reference.
+     *
+     * @example
+     * const ix = doc.addColor('#4472C4');  // → 2 (first user color)
+     * await page.addShape({ text: 'Hi', fillColor: '#4472C4', ... });
+     */
+    addColor(hex) {
+        const normalized = normalizeHex(hex);
+        const parsed = this.getParsedDoc();
+        const doc = parsed['VisioDocument'];
+        this.ensureColors(doc);
+        const colors = doc['Colors'];
+        const entries = toArray(colors['ColorEntry']);
+        // De-duplicate: return existing index if the color is already registered
+        const existing = entries.find((e) => normalizeHex(e['@_RGB']) === normalized);
+        if (existing)
+            return parseInt(existing['@_IX'], 10);
+        // Append at the next sequential index
+        const nextIX = this.nextIndex(entries);
+        entries.push({ '@_IX': nextIX.toString(), '@_RGB': normalized });
+        colors['ColorEntry'] = entries;
+        this.saveParsedDoc(parsed);
+        return nextIX;
+    }
+    /**
+     * Return all color entries currently in the document palette,
+     * ordered by index ascending.
+     */
+    getColors() {
+        const parsed = this.getParsedDoc();
+        const doc = parsed['VisioDocument'];
+        const colors = doc?.['Colors'];
+        if (!colors)
+            return this.builtIns();
+        return toArray(colors['ColorEntry'])
+            .map((e) => ({
+            index: parseInt(e['@_IX'], 10),
+            rgb: normalizeHex(e['@_RGB']),
+        }))
+            .sort((a, b) => a.index - b.index);
+    }
+    /**
+     * Look up the index of a color in the palette by its hex value.
+     * Returns `undefined` if the color has not been registered.
+     *
+     * @example
+     * const ix = doc.getColorIndex('#4472C4');  // 2, or undefined if not added
+     */
+    getColorIndex(hex) {
+        const normalized = normalizeHex(hex);
+        return this.getColors().find(e => e.rgb === normalized)?.index;
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    getParsedDoc() {
+        const xml = this.pkg.getFileText('visio/document.xml');
+        return this.parser.parse(xml);
+    }
+    saveParsedDoc(parsed) {
+        this.pkg.updateFile('visio/document.xml', (0, XmlHelper_1.buildXml)(this.builder, parsed));
+    }
+    /** Ensure `<Colors>` exists and contains the two built-in entries. */
+    ensureColors(doc) {
+        if (!doc['Colors'])
+            doc['Colors'] = {};
+        const colors = doc['Colors'];
+        const entries = toArray(colors['ColorEntry']);
+        if (!entries.some((e) => e['@_IX'] === '0')) {
+            entries.unshift({ '@_IX': '0', '@_RGB': '#000000' });
+        }
+        if (!entries.some((e) => e['@_IX'] === '1')) {
+            const blackPos = entries.findIndex((e) => e['@_IX'] === '0');
+            entries.splice(blackPos + 1, 0, { '@_IX': '1', '@_RGB': '#FFFFFF' });
+        }
+        colors['ColorEntry'] = entries;
+    }
+    /** Next IX = max existing index + 1, always at least 2. */
+    nextIndex(entries) {
+        const max = entries.reduce((m, e) => {
+            const ix = parseInt(e['@_IX'], 10);
+            return isNaN(ix) ? m : Math.max(m, ix);
+        }, 1);
+        return max + 1;
+    }
+    /** Minimal built-in palette returned when <Colors> is absent. */
+    builtIns() {
+        return [
+            { index: 0, rgb: '#000000' },
+            { index: 1, rgb: '#FFFFFF' },
+        ];
+    }
+}
+exports.ColorManager = ColorManager;
+// ── Module-level helpers ──────────────────────────────────────────────────────
+/** Normalise any hex string to uppercase `#RRGGBB`. */
+function normalizeHex(hex) {
+    let h = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (h.length === 3)
+        h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    return '#' + h.toUpperCase();
+}
+function toArray(val) {
+    if (!val)
+        return [];
+    return Array.isArray(val) ? val : [val];
+}

package/dist/index.d.ts

@@ -6,8 +6,12 @@ export { ShapeModifier } from './ShapeModifier';
 export { VisioDocument } from './VisioDocument';
 export { Page } from './Page';
 export { Shape } from './Shape';
+export { Connector } from './Connector';
+export type { ConnectorData } from './Connector';
 export type { ShapeData, ShapeHyperlink } from './Shape';
 export { Layer } from './Layer';
 export { SchemaDiagram } from './SchemaDiagram';
 export { VisioValidator } from './core/VisioValidator';
 export * from './types/VisioTypes';
+export { ArrowHeads, hexToRgb } from './utils/StyleHelpers';
+export type { ShapeStyle } from './ShapeModifier';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VisioValidator = exports.SchemaDiagram = exports.Layer = exports.Shape = exports.Page = exports.VisioDocument = exports.ShapeModifier = exports.ShapeReader = exports.PageManager = exports.VisioPackage = void 0;
+exports.hexToRgb = exports.ArrowHeads = exports.VisioValidator = exports.SchemaDiagram = exports.Layer = exports.Connector = exports.Shape = exports.Page = exports.VisioDocument = exports.ShapeModifier = exports.ShapeReader = exports.PageManager = exports.VisioPackage = void 0;
 var VisioPackage_1 = require("./VisioPackage");
 Object.defineProperty(exports, "VisioPackage", { enumerable: true, get: function () { return VisioPackage_1.VisioPackage; } });
 var PageManager_1 = require("./core/PageManager");
@@ -29,6 +29,8 @@ var Page_1 = require("./Page");
 Object.defineProperty(exports, "Page", { enumerable: true, get: function () { return Page_1.Page; } });
 var Shape_1 = require("./Shape");
 Object.defineProperty(exports, "Shape", { enumerable: true, get: function () { return Shape_1.Shape; } });
+var Connector_1 = require("./Connector");
+Object.defineProperty(exports, "Connector", { enumerable: true, get: function () { return Connector_1.Connector; } });
 var Layer_1 = require("./Layer");
 Object.defineProperty(exports, "Layer", { enumerable: true, get: function () { return Layer_1.Layer; } });
 var SchemaDiagram_1 = require("./SchemaDiagram");
@@ -36,3 +38,6 @@ Object.defineProperty(exports, "SchemaDiagram", { enumerable: true, get: functio
 var VisioValidator_1 = require("./core/VisioValidator");
 Object.defineProperty(exports, "VisioValidator", { enumerable: true, get: function () { return VisioValidator_1.VisioValidator; } });
 __exportStar(require("./types/VisioTypes"), exports);
+var StyleHelpers_1 = require("./utils/StyleHelpers");
+Object.defineProperty(exports, "ArrowHeads", { enumerable: true, get: function () { return StyleHelpers_1.ArrowHeads; } });
+Object.defineProperty(exports, "hexToRgb", { enumerable: true, get: function () { return StyleHelpers_1.hexToRgb; } });

package/dist/types/VisioTypes.d.ts

@@ -146,6 +146,19 @@ export interface ConnectorStyle {
 }
 /** Non-rectangular geometry variants supported by ShapeBuilder. */
 export type ShapeGeometry = 'rectangle' | 'ellipse' | 'diamond' | 'rounded-rectangle' | 'triangle' | 'parallelogram';
+/**
+ * A single entry in the document-level color palette (`<Colors>` in `document.xml`).
+ * Returned by `doc.getColors()` and created via `doc.addColor()`.
+ */
+export interface ColorEntry {
+    /**
+     * Zero-based integer index (IX). Can be passed as a color reference
+     * anywhere a hex string is accepted (e.g. `fillColor`, `lineColor`).
+     */
+    index: number;
+    /** Normalized CSS hex string, always uppercase `#RRGGBB`. */
+    rgb: string;
+}
 /** A reference to a document-level stylesheet, returned by `doc.createStyle()`. */
 export interface StyleRecord {
     /** Zero-based integer ID used as `LineStyle` / `FillStyle` / `TextStyle` on shapes. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-visio",
-  "version": "1.7.0",
+  "version": "1.10.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -25,6 +25,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.9",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   }