@graph-knowledge/api 0.1.7 → 0.1.22

package/README.md

@@ -91,6 +91,7 @@ new GraphKnowledgeAPI(config: ApiConfig)
 | `signIn(email, password)` | Signs in with email and password |
 | `signOut()` | Signs out the current user |
 | `waitForAuthInit()` | Waits for Firebase Auth to initialize |
+| `measureText(text, options?)` | Measures text dimensions (static method, no auth required) |
 
 #### Properties
 
@@ -243,6 +244,44 @@ await api.elements.create(documentId, nodeId, {
     methods: "+ getName(): string\n+ setName(name: string): void"
 });
 
+// Create a line
+await api.elements.create(documentId, nodeId, {
+    type: "line",
+    x: 100,
+    y: 100,
+    width: 200,
+    height: 100,
+    strokeColor: "#000000",
+    strokeWidth: 2,
+    lineStyle: "solid"  // "solid" | "dashed" | "dotted"
+});
+
+// Create a block arrow
+await api.elements.create(documentId, nodeId, {
+    type: "block-arrow",
+    x: 100,
+    y: 100,
+    width: 150,
+    height: 80,
+    fillColor: "#4a9eff",
+    strokeColor: "#000000",
+    strokeWidth: 2,
+    direction: "right"  // "right" | "left" | "up" | "down"
+});
+
+// Create basic shapes (triangle, diamond, hexagon, ellipse)
+// All basic shapes share the same properties
+await api.elements.create(documentId, nodeId, {
+    type: "triangle",  // or "diamond", "hexagon", "ellipse"
+    x: 100,
+    y: 100,
+    width: 150,
+    height: 130,
+    fillColor: "#4CAF50",
+    strokeColor: "#2E7D32",
+    strokeWidth: 2
+});
+
 // Update an element
 await api.elements.update(documentId, nodeId, elementId, {
     x: 200,
@@ -316,7 +355,13 @@ await api.batch.deleteElements(documentId, nodeId, [
 | Type | Description |
 |------|-------------|
 | `rectangle` | Rectangle shape with fill, stroke, corner radius |
+| `triangle` | Triangle shape with fill and stroke |
+| `diamond` | Diamond/rhombus shape with fill and stroke |
+| `hexagon` | Hexagon shape with fill and stroke |
+| `ellipse` | Ellipse/oval shape with fill and stroke |
 | `text` | Text element with font customization (supports multi-line with `\n`) |
+| `line` | Freeform line with stroke styling |
+| `block-arrow` | Block arrow shape with directional pointer |
 | `connector` | Line connecting two elements |
 | `uml-class` | UML class diagram element |
 | `uml-interface` | UML interface element |
@@ -341,6 +386,70 @@ await api.elements.create(documentId, nodeId, {
 });
 ```
 
+## Text Measurement
+
+Measure text dimensions before creating elements. Useful for calculating layouts and positioning:
+
+```typescript
+import { GraphKnowledgeAPI } from "@graph-knowledge/api";
+
+// Static method - no API instance or authentication needed
+const metrics = GraphKnowledgeAPI.measureText("Hello World", {
+    fontSize: 24,
+    fontFamily: "Arial",
+    fontWeight: 400
+});
+console.log(metrics);
+// { width: 132.5, height: 24, lines: 1, anchorDx: 0, anchorDy: 0 }
+
+// Measure multi-line text
+const multiLine = GraphKnowledgeAPI.measureText("Line 1\nLine 2", {
+    fontSize: 16,
+    lineHeight: 1.4
+});
+console.log(multiLine.lines);  // 2
+
+// Measure with word wrapping
+const wrapped = GraphKnowledgeAPI.measureText(
+    "This is a long sentence that will be wrapped",
+    { fontSize: 16, maxWidth: 150 }
+);
+console.log(wrapped.lines);  // > 1
+console.log(wrapped.width);  // <= 150
+```
+
+### MeasureTextOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fontSize` | `number` | `16` | Font size in pixels |
+| `fontFamily` | `string` | `"Arial"` | Font family |
+| `fontWeight` | `number` | `400` | Font weight (100-900) |
+| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Affects anchorDx |
+| `lineHeight` | `number` | `1.2` | Line height multiplier |
+| `maxWidth` | `number` | - | Max width for word wrapping |
+
+### TextMetrics Result
+
+| Property | Description |
+|----------|-------------|
+| `width` | Maximum line width in pixels |
+| `height` | Total text height in pixels |
+| `lines` | Number of lines |
+| `anchorDx` | X offset for text alignment positioning |
+| `anchorDy` | Y offset (0 for top baseline) |
+
+### Node.js Support
+
+For accurate text measurement in Node.js, install the optional `canvas` package:
+
+```bash
+npm install canvas
+```
+
+Without it, the API uses character-based estimation (less accurate).
+The `canvas` package requires native compilation - see [node-canvas requirements](https://github.com/Automattic/node-canvas#compiling).
+
 ## Error Handling
 
 The API throws typed errors for different failure cases:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graph-knowledge/api",
-  "version": "0.1.7",
+  "version": "0.1.22",
   "description": "Headless Document API for Graph Knowledge - programmatic access to documents, nodes, and elements",
   "license": "MIT",
   "author": "Graph Knowledge Team",
@@ -35,7 +35,13 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "firebase": ">=10.0.0 <13.0.0"
+    "firebase": ">=10.0.0 <13.0.0",
+    "canvas": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "canvas": {
+      "optional": true
+    }
   },
   "sideEffects": false,
   "type": "commonjs"

package/src/index.d.ts

@@ -8,12 +8,14 @@ export type { IElementOperations } from "./lib/interfaces/element-operations.int
 export type { IBatchOperations, BatchUpdateElementInput } from "./lib/interfaces/batch-operations.interface";
 export type { ITemplateOperations } from "./lib/interfaces/template-operations.interface";
 export type { IElementTypeValidator, IElementValidatorRegistry } from "./lib/interfaces/element-validator.interface";
-export type { CreateDocumentInput, UpdateDocumentInput, DocumentResult, CreateNodeInput, UpdateNodeInput, NodeResult } from "./lib/types/api-types";
+export type { CreateDocumentInput, UpdateDocumentInput, DocumentResult, CreateNodeInput, UpdateNodeInput, NodeResult, CreateTemplateInput } from "./lib/types/api-types";
 export type { BaseElementInput, RectangleInput, TextInput, ConnectorInput, ConnectorAnchor, LineStyle, MarkerType, UmlClassInput, UmlInterfaceInput, UmlComponentInput, UmlPackageInput, UmlArtifactInput, UmlNoteInput, TriangleInput, DiamondInput, HexagonInput, EllipseInput, LineInput, BlockArrowInput, BlockArrowDirection, CustomShapeInput, AnyElementInput, UpdateElementInput } from "./lib/types/element-input-types";
 export { GraphKnowledgeAPIError, AuthenticationError, NotFoundError, ValidationError, PermissionError } from "./lib/errors/api-errors";
 export type { Document, GraphNode, GraphElement } from "./lib/models";
 export { CURRENT_DOCUMENT_SCHEMA_VERSION } from "./lib/models";
 export { LinkLevelManager } from "./lib/utils/link-level-manager";
 export type { LevelChange, LinkState } from "./lib/utils/link-level-manager";
+export type { MeasureTextOptions, TextMetrics } from "./lib/types/text-measurement-types";
+export { TextMeasurementService } from "./lib/utils/text-measurement/text-measurement-service";
 export { MockAuthClient } from "./lib/testing/mock-auth-client";
 export { MockFirestoreClient } from "./lib/testing/mock-firestore-client";

package/src/index.js

@@ -3,7 +3,7 @@
 // Graph Knowledge Headless Document API
 // =============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MockFirestoreClient = exports.MockAuthClient = exports.LinkLevelManager = exports.CURRENT_DOCUMENT_SCHEMA_VERSION = exports.PermissionError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.GraphKnowledgeAPIError = exports.GraphKnowledgeAPI = void 0;
+exports.MockFirestoreClient = exports.MockAuthClient = exports.TextMeasurementService = exports.LinkLevelManager = exports.CURRENT_DOCUMENT_SCHEMA_VERSION = exports.PermissionError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.GraphKnowledgeAPIError = exports.GraphKnowledgeAPI = void 0;
 // Main API Class
 var graph_knowledge_api_1 = require("./lib/graph-knowledge-api");
 Object.defineProperty(exports, "GraphKnowledgeAPI", { enumerable: true, get: function () { return graph_knowledge_api_1.GraphKnowledgeAPI; } });
@@ -23,6 +23,8 @@ Object.defineProperty(exports, "CURRENT_DOCUMENT_SCHEMA_VERSION", { enumerable:
 // =============================================================================
 var link_level_manager_1 = require("./lib/utils/link-level-manager");
 Object.defineProperty(exports, "LinkLevelManager", { enumerable: true, get: function () { return link_level_manager_1.LinkLevelManager; } });
+var text_measurement_service_1 = require("./lib/utils/text-measurement/text-measurement-service");
+Object.defineProperty(exports, "TextMeasurementService", { enumerable: true, get: function () { return text_measurement_service_1.TextMeasurementService; } });
 // =============================================================================
 // Testing Utilities
 // =============================================================================

package/src/lib/graph-knowledge-api.d.ts

@@ -5,6 +5,7 @@ import { INodeOperations } from "./interfaces/node-operations.interface";
 import { IElementOperations } from "./interfaces/element-operations.interface";
 import { IBatchOperations } from "./interfaces/batch-operations.interface";
 import { ITemplateOperations } from "./interfaces/template-operations.interface";
+import { MeasureTextOptions, TextMetrics } from "./types/text-measurement-types";
 /**
  * Main entry point for the Graph Knowledge Headless API.
  *
@@ -50,6 +51,10 @@ export declare class GraphKnowledgeAPI {
     private readonly _elements;
     private readonly _batch;
     private readonly _templates;
+    /**
+     * Shared text measurement service for static and instance methods.
+     */
+    private static _textMeasurementService;
     /**
      * Creates a new GraphKnowledgeAPI instance.
      * @param config Configuration including Firebase credentials
@@ -111,4 +116,34 @@ export declare class GraphKnowledgeAPI {
      * @throws PermissionError if not premium
      */
     requirePremium(): Promise<void>;
+    /**
+     * Measures text dimensions. No authentication required.
+     * Useful for calculating layouts and positioning before creating elements.
+     *
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     *
+     * @example
+     * ```typescript
+     * const metrics = GraphKnowledgeAPI.measureText("Hello World", { fontSize: 24 });
+     * console.log(metrics.width, metrics.height);
+     * ```
+     */
+    static measureText(text: string, options?: MeasureTextOptions): TextMetrics;
+    /**
+     * Measures text dimensions. No authentication required.
+     * Instance method that delegates to the static method.
+     *
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     *
+     * @example
+     * ```typescript
+     * const api = new GraphKnowledgeAPI({ firebaseConfig: {...} });
+     * const metrics = api.measureText("Hello", { fontSize: 16 });
+     * ```
+     */
+    measureText(text: string, options?: MeasureTextOptions): TextMetrics;
 }

package/src/lib/graph-knowledge-api.js

@@ -14,6 +14,8 @@ const template_operations_1 = require("./operations/template-operations");
 const document_validator_1 = require("./validators/document-validator");
 const node_validator_1 = require("./validators/node-validator");
 const element_validator_registry_1 = require("./validators/element-validator-registry");
+const template_validator_1 = require("./validators/template-validator");
+const text_measurement_service_1 = require("./utils/text-measurement/text-measurement-service");
 /**
  * Main entry point for the Graph Knowledge Headless API.
  *
@@ -59,6 +61,10 @@ class GraphKnowledgeAPI {
     _elements;
     _batch;
     _templates;
+    /**
+     * Shared text measurement service for static and instance methods.
+     */
+    static _textMeasurementService = null;
     /**
      * Creates a new GraphKnowledgeAPI instance.
      * @param config Configuration including Firebase credentials
@@ -80,7 +86,7 @@ class GraphKnowledgeAPI {
         this._nodes = new node_operations_1.NodeOperations(firestoreClient, this._authClient, nodeValidator);
         this._elements = new element_operations_1.ElementOperations(firestoreClient, this._authClient, elementValidatorRegistry);
         this._batch = new batch_operations_1.BatchOperations(firestoreClient, this._authClient, elementValidatorRegistry);
-        this._templates = new template_operations_1.TemplateOperations(firestoreClient, this._authClient);
+        this._templates = new template_operations_1.TemplateOperations(firestoreClient, this._authClient, new template_validator_1.TemplateValidator());
     }
     /**
      * Authentication client for sign-in/sign-out operations.
@@ -165,5 +171,45 @@ class GraphKnowledgeAPI {
     async requirePremium() {
         return this._authClient.requirePremium();
     }
+    // =========================================================================
+    // Text Measurement (static and instance methods)
+    // =========================================================================
+    /**
+     * Measures text dimensions. No authentication required.
+     * Useful for calculating layouts and positioning before creating elements.
+     *
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     *
+     * @example
+     * ```typescript
+     * const metrics = GraphKnowledgeAPI.measureText("Hello World", { fontSize: 24 });
+     * console.log(metrics.width, metrics.height);
+     * ```
+     */
+    static measureText(text, options = {}) {
+        if (!GraphKnowledgeAPI._textMeasurementService) {
+            GraphKnowledgeAPI._textMeasurementService = new text_measurement_service_1.TextMeasurementService();
+        }
+        return GraphKnowledgeAPI._textMeasurementService.measureText(text, options);
+    }
+    /**
+     * Measures text dimensions. No authentication required.
+     * Instance method that delegates to the static method.
+     *
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     *
+     * @example
+     * ```typescript
+     * const api = new GraphKnowledgeAPI({ firebaseConfig: {...} });
+     * const metrics = api.measureText("Hello", { fontSize: 16 });
+     * ```
+     */
+    measureText(text, options = {}) {
+        return GraphKnowledgeAPI.measureText(text, options);
+    }
 }
 exports.GraphKnowledgeAPI = GraphKnowledgeAPI;

package/src/lib/interfaces/template-operations.interface.d.ts

@@ -1,4 +1,4 @@
-import { DocumentResult } from "../types/api-types";
+import { CreateTemplateInput, DocumentResult } from "../types/api-types";
 /**
  * Interface for template operations.
  *
@@ -6,6 +6,16 @@ import { DocumentResult } from "../types/api-types";
  * by premium users to create new documents.
  */
 export interface ITemplateOperations {
+    /**
+     * Creates a new template document with a root node.
+     * Requires admin access.
+     *
+     * @param input Template creation parameters
+     * @returns The newly created template with its root node
+     * @throws AuthenticationError if not authenticated
+     * @throws PermissionError if not admin
+     */
+    create(input: CreateTemplateInput): Promise<DocumentResult>;
     /**
      * Lists all published templates available to users.
      * @returns Array of published template documents (shallow, without nodes)

package/src/lib/interfaces/text-measurement.interface.d.ts

@@ -0,0 +1,24 @@
+import { MeasureTextOptions, TextMetrics } from "../types/text-measurement-types";
+/**
+ * Interface for text measurement providers.
+ * Implements the Strategy pattern for cross-environment support.
+ *
+ * Providers:
+ * - BrowserTextMeasurementProvider: Uses native canvas API (browsers)
+ * - NodeTextMeasurementProvider: Uses canvas npm package (Node.js)
+ * - FallbackTextMeasurementProvider: Character-based estimation (always available)
+ */
+export interface ITextMeasurementProvider {
+    /**
+     * Measures text dimensions.
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     */
+    measureText(text: string, options: MeasureTextOptions): TextMetrics;
+    /**
+     * Checks if this provider is available in the current environment.
+     * @returns true if the provider can be used
+     */
+    isAvailable(): boolean;
+}

package/src/lib/interfaces/text-measurement.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/operations/template-operations.d.ts

@@ -1,7 +1,8 @@
 import { ITemplateOperations } from "../interfaces/template-operations.interface";
 import { IFirestoreClient } from "../interfaces/firestore-client.interface";
 import { IAuthClient } from "../interfaces/auth-client.interface";
-import { DocumentResult } from "../types/api-types";
+import { CreateTemplateInput, DocumentResult } from "../types/api-types";
+import { TemplateValidator } from "../validators/template-validator";
 /**
  * Implementation of template operations.
  *
@@ -11,7 +12,9 @@ import { DocumentResult } from "../types/api-types";
 export declare class TemplateOperations implements ITemplateOperations {
     private readonly firestore;
     private readonly auth;
-    constructor(firestore: IFirestoreClient, auth: IAuthClient);
+    private readonly validator;
+    constructor(firestore: IFirestoreClient, auth: IAuthClient, validator: TemplateValidator);
+    create(input: CreateTemplateInput): Promise<DocumentResult>;
     list(): Promise<DocumentResult[]>;
     get(templateId: string): Promise<DocumentResult>;
     clone(templateId: string, title?: string): Promise<DocumentResult>;

package/src/lib/operations/template-operations.js

@@ -16,9 +16,55 @@ const DEFAULT_CANVAS_HEIGHT = 1080;
 class TemplateOperations {
     firestore;
     auth;
-    constructor(firestore, auth) {
+    validator;
+    constructor(firestore, auth, validator) {
         this.firestore = firestore;
         this.auth = auth;
+        this.validator = validator;
+    }
+    async create(input) {
+        const userId = this.auth.requireAuth();
+        await this.auth.requireAdmin();
+        this.validator.validateCreate(input);
+        const docId = (0, uuid_1.generateUuid)();
+        const rootNodeId = (0, uuid_1.generateUuid)();
+        const canvasWidth = input.canvasWidth ?? DEFAULT_CANVAS_WIDTH;
+        const canvasHeight = input.canvasHeight ?? DEFAULT_CANVAS_HEIGHT;
+        // Create the template document
+        const templateDocument = {
+            schemaVersion: models_1.CURRENT_DOCUMENT_SCHEMA_VERSION,
+            title: input.title,
+            content: input.content ?? "",
+            owner: userId,
+            sharedWith: [],
+            createdAt: new Date(),
+            rootNodeId,
+            isPremiumContent: false,
+            isTemplate: true,
+            isPublished: input.isPublished ?? false,
+            nodes: [] // Nodes stored in sub-collection
+        };
+        // Create the root node
+        const rootNode = {
+            id: rootNodeId,
+            title: input.title,
+            content: "",
+            elements: [],
+            canvasWidth,
+            canvasHeight,
+            level: 0,
+            owner: userId
+        };
+        // Write everything in a batch
+        const batch = this.firestore.batch();
+        batch.set(`documents/${docId}`, templateDocument);
+        batch.set(`documents/${docId}/nodes/${rootNodeId}`, rootNode);
+        await batch.commit();
+        return {
+            id: docId,
+            ...templateDocument,
+            nodes: [rootNode]
+        };
     }
     async list() {
         this.auth.requireAuth();

package/src/lib/types/api-types.d.ts

@@ -59,3 +59,18 @@ export interface UpdateNodeInput {
 export type NodeResult = GraphNode & {
     id: string;
 };
+/**
+ * Input for creating a new template (admin only).
+ */
+export interface CreateTemplateInput {
+    /** Template title (required) */
+    title: string;
+    /** Template description/content */
+    content?: string;
+    /** Root node canvas width (defaults to 1920) */
+    canvasWidth?: number;
+    /** Root node canvas height (defaults to 1080) */
+    canvasHeight?: number;
+    /** Whether to publish immediately (defaults to false - draft) */
+    isPublished?: boolean;
+}

package/src/lib/types/text-measurement-types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Options for measuring text dimensions.
+ * All properties are optional and have sensible defaults.
+ */
+export interface MeasureTextOptions {
+    /**
+     * Font size in pixels.
+     * @default 16
+     */
+    fontSize?: number;
+    /**
+     * Font family name.
+     * @default "Arial"
+     */
+    fontFamily?: string;
+    /**
+     * Font weight (100-900).
+     * @default 400
+     */
+    fontWeight?: number;
+    /**
+     * Text alignment. Affects anchorDx calculation.
+     * @default "left"
+     */
+    textAlign?: "left" | "center" | "right";
+    /**
+     * Line height multiplier for multi-line text.
+     * @default 1.2
+     */
+    lineHeight?: number;
+    /**
+     * Maximum width for word wrapping.
+     * When specified, text will be wrapped to fit within this width.
+     */
+    maxWidth?: number;
+}
+/**
+ * Result of text measurement containing dimensions and positioning offsets.
+ */
+export interface TextMetrics {
+    /**
+     * Maximum line width in pixels.
+     */
+    width: number;
+    /**
+     * Total text height in pixels.
+     */
+    height: number;
+    /**
+     * Number of lines in the text.
+     */
+    lines: number;
+    /**
+     * X offset for text alignment positioning.
+     * - left: 0
+     * - center: -width/2
+     * - right: -width
+     */
+    anchorDx: number;
+    /**
+     * Y offset (0 for top/hanging baseline).
+     */
+    anchorDy: number;
+}

package/src/lib/types/text-measurement-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/utils/text-measurement/browser-text-measurement-provider.d.ts

@@ -0,0 +1,28 @@
+import { ITextMeasurementProvider } from "../../interfaces/text-measurement.interface";
+import { MeasureTextOptions, TextMetrics } from "../../types/text-measurement-types";
+/**
+ * Browser text measurement provider using native Canvas API.
+ * Provides accurate measurements when running in a browser environment.
+ */
+export declare class BrowserTextMeasurementProvider implements ITextMeasurementProvider {
+    private _canvas;
+    private _context;
+    measureText(text: string, options: MeasureTextOptions): TextMetrics;
+    isAvailable(): boolean;
+    /**
+     * Gets or creates the canvas context for measurement.
+     */
+    private _getContext;
+    /**
+     * Wraps a single line of text to fit within maxWidth.
+     */
+    private _wrapLine;
+    /**
+     * Calculates the maximum width among all lines.
+     */
+    private _calculateMaxLineWidth;
+    /**
+     * Calculates the X anchor offset based on text alignment.
+     */
+    private _calculateAnchorDx;
+}

package/src/lib/utils/text-measurement/browser-text-measurement-provider.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserTextMeasurementProvider = void 0;
+const text_measurement_defaults_1 = require("./text-measurement-defaults");
+/**
+ * Browser text measurement provider using native Canvas API.
+ * Provides accurate measurements when running in a browser environment.
+ */
+class BrowserTextMeasurementProvider {
+    _canvas = null;
+    _context = null;
+    measureText(text, options) {
+        const fontSize = options.fontSize ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontSize;
+        const fontFamily = options.fontFamily ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontFamily;
+        const fontWeight = options.fontWeight ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontWeight;
+        const lineHeight = options.lineHeight ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.lineHeight;
+        const textAlign = options.textAlign ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.textAlign;
+        const maxWidth = options.maxWidth;
+        if (!text || text.length === 0) {
+            return {
+                width: 0,
+                height: 0,
+                lines: 0,
+                anchorDx: 0,
+                anchorDy: 0
+            };
+        }
+        const ctx = this._getContext();
+        if (!ctx) {
+            // Should not happen if isAvailable() is checked, but fallback gracefully
+            throw new Error("Canvas context not available");
+        }
+        // Set font for measurement
+        ctx.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
+        // Split by explicit newlines
+        const explicitLines = text.split("\n");
+        // Calculate wrapped lines if maxWidth is specified
+        const wrappedLines = [];
+        if (maxWidth !== undefined && maxWidth > 0) {
+            for (const line of explicitLines) {
+                const wrapped = this._wrapLine(ctx, line, maxWidth);
+                wrappedLines.push(...wrapped);
+            }
+        }
+        else {
+            wrappedLines.push(...explicitLines);
+        }
+        // Calculate dimensions
+        const lineCount = wrappedLines.length;
+        const maxLineWidth = this._calculateMaxLineWidth(ctx, wrappedLines);
+        const width = maxWidth !== undefined ? Math.min(maxLineWidth, maxWidth) : maxLineWidth;
+        // Height calculation: first line is fontSize, subsequent lines add lineHeight * fontSize
+        const height = lineCount > 0
+            ? fontSize + (lineCount - 1) * lineHeight * fontSize
+            : 0;
+        // Calculate anchor offset based on alignment
+        const anchorDx = this._calculateAnchorDx(width, textAlign);
+        return {
+            width,
+            height,
+            lines: lineCount,
+            anchorDx,
+            anchorDy: 0 // Top/hanging baseline
+        };
+    }
+    isAvailable() {
+        return typeof document !== "undefined" && !!document.createElement;
+    }
+    /**
+     * Gets or creates the canvas context for measurement.
+     */
+    _getContext() {
+        if (this._context) {
+            return this._context;
+        }
+        if (!this.isAvailable()) {
+            return null;
+        }
+        this._canvas = document.createElement("canvas");
+        this._context = this._canvas.getContext("2d");
+        return this._context;
+    }
+    /**
+     * Wraps a single line of text to fit within maxWidth.
+     */
+    _wrapLine(ctx, line, maxWidth) {
+        if (line.length === 0) {
+            return [""];
+        }
+        const words = line.split(/\s+/);
+        const lines = [];
+        let currentLine = "";
+        for (const word of words) {
+            const testLine = currentLine.length > 0 ? `${currentLine} ${word}` : word;
+            const metrics = ctx.measureText(testLine);
+            if (metrics.width <= maxWidth || currentLine.length === 0) {
+                currentLine = testLine;
+            }
+            else {
+                lines.push(currentLine);
+                currentLine = word;
+            }
+        }
+        if (currentLine.length > 0) {
+            lines.push(currentLine);
+        }
+        return lines.length > 0 ? lines : [""];
+    }
+    /**
+     * Calculates the maximum width among all lines.
+     */
+    _calculateMaxLineWidth(ctx, lines) {
+        let maxWidth = 0;
+        for (const line of lines) {
+            const metrics = ctx.measureText(line);
+            if (metrics.width > maxWidth) {
+                maxWidth = metrics.width;
+            }
+        }
+        return maxWidth;
+    }
+    /**
+     * Calculates the X anchor offset based on text alignment.
+     */
+    _calculateAnchorDx(width, textAlign) {
+        switch (textAlign) {
+            case "center":
+                return -width / 2;
+            case "right":
+                return -width;
+            case "left":
+            default:
+                return 0;
+        }
+    }
+}
+exports.BrowserTextMeasurementProvider = BrowserTextMeasurementProvider;

package/src/lib/utils/text-measurement/fallback-text-measurement-provider.d.ts

@@ -0,0 +1,29 @@
+import { ITextMeasurementProvider } from "../../interfaces/text-measurement.interface";
+import { MeasureTextOptions, TextMetrics } from "../../types/text-measurement-types";
+/**
+ * Fallback text measurement provider using character-based estimation.
+ * Always available, but less accurate than canvas-based providers.
+ *
+ * Uses average character width ratios derived from common fonts.
+ */
+export declare class FallbackTextMeasurementProvider implements ITextMeasurementProvider {
+    /**
+     * Average character width as a ratio of font size.
+     * Based on typical proportional fonts like Arial.
+     */
+    private static readonly AVG_CHAR_WIDTH_RATIO;
+    measureText(text: string, options: MeasureTextOptions): TextMetrics;
+    isAvailable(): boolean;
+    /**
+     * Wraps a single line of text to fit within maxWidth.
+     */
+    private _wrapLine;
+    /**
+     * Calculates the maximum width among all lines.
+     */
+    private _calculateMaxLineWidth;
+    /**
+     * Calculates the X anchor offset based on text alignment.
+     */
+    private _calculateAnchorDx;
+}

package/src/lib/utils/text-measurement/fallback-text-measurement-provider.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackTextMeasurementProvider = void 0;
+const text_measurement_defaults_1 = require("./text-measurement-defaults");
+/**
+ * Fallback text measurement provider using character-based estimation.
+ * Always available, but less accurate than canvas-based providers.
+ *
+ * Uses average character width ratios derived from common fonts.
+ */
+class FallbackTextMeasurementProvider {
+    /**
+     * Average character width as a ratio of font size.
+     * Based on typical proportional fonts like Arial.
+     */
+    static AVG_CHAR_WIDTH_RATIO = 0.55;
+    measureText(text, options) {
+        const fontSize = options.fontSize ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontSize;
+        const lineHeight = options.lineHeight ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.lineHeight;
+        const textAlign = options.textAlign ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.textAlign;
+        const maxWidth = options.maxWidth;
+        if (!text || text.length === 0) {
+            return {
+                width: 0,
+                height: 0,
+                lines: 0,
+                anchorDx: 0,
+                anchorDy: 0
+            };
+        }
+        // Split by explicit newlines
+        const explicitLines = text.split("\n");
+        // Calculate estimated char width
+        const charWidth = fontSize * FallbackTextMeasurementProvider.AVG_CHAR_WIDTH_RATIO;
+        // Calculate wrapped lines if maxWidth is specified
+        const wrappedLines = [];
+        if (maxWidth !== undefined && maxWidth > 0) {
+            for (const line of explicitLines) {
+                const wrapped = this._wrapLine(line, charWidth, maxWidth);
+                wrappedLines.push(...wrapped);
+            }
+        }
+        else {
+            wrappedLines.push(...explicitLines);
+        }
+        // Calculate dimensions
+        const lineCount = wrappedLines.length;
+        const maxLineWidth = this._calculateMaxLineWidth(wrappedLines, charWidth);
+        const width = maxWidth !== undefined ? Math.min(maxLineWidth, maxWidth) : maxLineWidth;
+        // Height calculation: first line is fontSize, subsequent lines add lineHeight * fontSize
+        const height = lineCount > 0
+            ? fontSize + (lineCount - 1) * lineHeight * fontSize
+            : 0;
+        // Calculate anchor offset based on alignment
+        const anchorDx = this._calculateAnchorDx(width, textAlign);
+        return {
+            width,
+            height,
+            lines: lineCount,
+            anchorDx,
+            anchorDy: 0 // Top/hanging baseline
+        };
+    }
+    isAvailable() {
+        return true;
+    }
+    /**
+     * Wraps a single line of text to fit within maxWidth.
+     */
+    _wrapLine(line, charWidth, maxWidth) {
+        if (line.length === 0) {
+            return [""];
+        }
+        const words = line.split(/\s+/);
+        const lines = [];
+        let currentLine = "";
+        for (const word of words) {
+            const wordWidth = word.length * charWidth;
+            const currentWidth = currentLine.length * charWidth;
+            const spaceWidth = currentLine.length > 0 ? charWidth : 0;
+            if (currentWidth + spaceWidth + wordWidth <= maxWidth || currentLine.length === 0) {
+                currentLine = currentLine.length > 0 ? `${currentLine} ${word}` : word;
+            }
+            else {
+                lines.push(currentLine);
+                currentLine = word;
+            }
+        }
+        if (currentLine.length > 0) {
+            lines.push(currentLine);
+        }
+        return lines.length > 0 ? lines : [""];
+    }
+    /**
+     * Calculates the maximum width among all lines.
+     */
+    _calculateMaxLineWidth(lines, charWidth) {
+        let maxWidth = 0;
+        for (const line of lines) {
+            const lineWidth = line.length * charWidth;
+            if (lineWidth > maxWidth) {
+                maxWidth = lineWidth;
+            }
+        }
+        return maxWidth;
+    }
+    /**
+     * Calculates the X anchor offset based on text alignment.
+     */
+    _calculateAnchorDx(width, textAlign) {
+        switch (textAlign) {
+            case "center":
+                return -width / 2;
+            case "right":
+                return -width;
+            case "left":
+            default:
+                return 0;
+        }
+    }
+}
+exports.FallbackTextMeasurementProvider = FallbackTextMeasurementProvider;

package/src/lib/utils/text-measurement/node-text-measurement-provider.d.ts

@@ -0,0 +1,35 @@
+import { ITextMeasurementProvider } from "../../interfaces/text-measurement.interface";
+import { MeasureTextOptions, TextMetrics } from "../../types/text-measurement-types";
+/**
+ * Node.js text measurement provider using the canvas npm package.
+ * Provides accurate measurements in Node.js when the canvas package is installed.
+ *
+ * @requires canvas - Optional peer dependency (npm install canvas)
+ */
+export declare class NodeTextMeasurementProvider implements ITextMeasurementProvider {
+    private _canvas;
+    private _context;
+    private _canvasModule;
+    measureText(text: string, options: MeasureTextOptions): TextMetrics;
+    isAvailable(): boolean;
+    /**
+     * Attempts to load the canvas npm package.
+     */
+    private _tryLoadCanvas;
+    /**
+     * Gets or creates the canvas context for measurement.
+     */
+    private _getContext;
+    /**
+     * Wraps a single line of text to fit within maxWidth.
+     */
+    private _wrapLine;
+    /**
+     * Calculates the maximum width among all lines.
+     */
+    private _calculateMaxLineWidth;
+    /**
+     * Calculates the X anchor offset based on text alignment.
+     */
+    private _calculateAnchorDx;
+}

package/src/lib/utils/text-measurement/node-text-measurement-provider.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeTextMeasurementProvider = void 0;
+const text_measurement_defaults_1 = require("./text-measurement-defaults");
+/**
+ * Node.js text measurement provider using the canvas npm package.
+ * Provides accurate measurements in Node.js when the canvas package is installed.
+ *
+ * @requires canvas - Optional peer dependency (npm install canvas)
+ */
+class NodeTextMeasurementProvider {
+    _canvas = null;
+    _context = null;
+    _canvasModule = null;
+    measureText(text, options) {
+        const fontSize = options.fontSize ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontSize;
+        const fontFamily = options.fontFamily ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontFamily;
+        const fontWeight = options.fontWeight ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.fontWeight;
+        const lineHeight = options.lineHeight ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.lineHeight;
+        const textAlign = options.textAlign ?? text_measurement_defaults_1.TEXT_MEASUREMENT_DEFAULTS.textAlign;
+        const maxWidth = options.maxWidth;
+        if (!text || text.length === 0) {
+            return {
+                width: 0,
+                height: 0,
+                lines: 0,
+                anchorDx: 0,
+                anchorDy: 0
+            };
+        }
+        const ctx = this._getContext();
+        if (!ctx) {
+            throw new Error("Node canvas context not available");
+        }
+        // Set font for measurement
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ctx.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
+        // Split by explicit newlines
+        const explicitLines = text.split("\n");
+        // Calculate wrapped lines if maxWidth is specified
+        const wrappedLines = [];
+        if (maxWidth !== undefined && maxWidth > 0) {
+            for (const line of explicitLines) {
+                const wrapped = this._wrapLine(ctx, line, maxWidth);
+                wrappedLines.push(...wrapped);
+            }
+        }
+        else {
+            wrappedLines.push(...explicitLines);
+        }
+        // Calculate dimensions
+        const lineCount = wrappedLines.length;
+        const maxLineWidth = this._calculateMaxLineWidth(ctx, wrappedLines);
+        const width = maxWidth !== undefined ? Math.min(maxLineWidth, maxWidth) : maxLineWidth;
+        // Height calculation: first line is fontSize, subsequent lines add lineHeight * fontSize
+        const height = lineCount > 0
+            ? fontSize + (lineCount - 1) * lineHeight * fontSize
+            : 0;
+        // Calculate anchor offset based on alignment
+        const anchorDx = this._calculateAnchorDx(width, textAlign);
+        return {
+            width,
+            height,
+            lines: lineCount,
+            anchorDx,
+            anchorDy: 0 // Top/hanging baseline
+        };
+    }
+    isAvailable() {
+        return this._tryLoadCanvas();
+    }
+    /**
+     * Attempts to load the canvas npm package.
+     */
+    _tryLoadCanvas() {
+        if (this._canvasModule !== null) {
+            return this._canvasModule !== undefined;
+        }
+        try {
+            // Using Function constructor so bundlers don't statically include the optional 'canvas' package
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const dynamicRequire = new Function("moduleName", "return require(moduleName)");
+            this._canvasModule = dynamicRequire("canvas");
+            return true;
+        }
+        catch {
+            // canvas package not installed
+            this._canvasModule = undefined;
+            return false;
+        }
+    }
+    /**
+     * Gets or creates the canvas context for measurement.
+     */
+    _getContext() {
+        if (this._context) {
+            return this._context;
+        }
+        if (!this._tryLoadCanvas() || !this._canvasModule) {
+            return null;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { createCanvas } = this._canvasModule;
+        this._canvas = createCanvas(1, 1);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this._context = this._canvas.getContext("2d");
+        return this._context;
+    }
+    /**
+     * Wraps a single line of text to fit within maxWidth.
+     */
+    _wrapLine(ctx, line, maxWidth) {
+        if (line.length === 0) {
+            return [""];
+        }
+        const words = line.split(/\s+/);
+        const lines = [];
+        let currentLine = "";
+        for (const word of words) {
+            const testLine = currentLine.length > 0 ? `${currentLine} ${word}` : word;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const metrics = ctx.measureText(testLine);
+            if (metrics.width <= maxWidth || currentLine.length === 0) {
+                currentLine = testLine;
+            }
+            else {
+                lines.push(currentLine);
+                currentLine = word;
+            }
+        }
+        if (currentLine.length > 0) {
+            lines.push(currentLine);
+        }
+        return lines.length > 0 ? lines : [""];
+    }
+    /**
+     * Calculates the maximum width among all lines.
+     */
+    _calculateMaxLineWidth(ctx, lines) {
+        let maxWidth = 0;
+        for (const line of lines) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const metrics = ctx.measureText(line);
+            if (metrics.width > maxWidth) {
+                maxWidth = metrics.width;
+            }
+        }
+        return maxWidth;
+    }
+    /**
+     * Calculates the X anchor offset based on text alignment.
+     */
+    _calculateAnchorDx(width, textAlign) {
+        switch (textAlign) {
+            case "center":
+                return -width / 2;
+            case "right":
+                return -width;
+            case "left":
+            default:
+                return 0;
+        }
+    }
+}
+exports.NodeTextMeasurementProvider = NodeTextMeasurementProvider;

package/src/lib/utils/text-measurement/text-measurement-defaults.d.ts

@@ -0,0 +1,5 @@
+import { MeasureTextOptions } from "../../types/text-measurement-types";
+/**
+ * Default values for text measurement options.
+ */
+export declare const TEXT_MEASUREMENT_DEFAULTS: Required<Omit<MeasureTextOptions, "maxWidth">>;

package/src/lib/utils/text-measurement/text-measurement-defaults.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_MEASUREMENT_DEFAULTS = void 0;
+/**
+ * Default values for text measurement options.
+ */
+exports.TEXT_MEASUREMENT_DEFAULTS = {
+    fontSize: 16,
+    fontFamily: "Arial",
+    fontWeight: 400,
+    textAlign: "left",
+    lineHeight: 1.2
+};

package/src/lib/utils/text-measurement/text-measurement-service.d.ts

@@ -0,0 +1,39 @@
+import { ITextMeasurementProvider } from "../../interfaces/text-measurement.interface";
+import { MeasureTextOptions, TextMetrics } from "../../types/text-measurement-types";
+/**
+ * Service for measuring text dimensions.
+ * Automatically detects the best available provider for the current environment.
+ *
+ * Provider selection order:
+ * 1. BrowserTextMeasurementProvider - Uses native canvas API (browsers)
+ * 2. NodeTextMeasurementProvider - Uses canvas npm package (Node.js)
+ * 3. FallbackTextMeasurementProvider - Character-based estimation (always available)
+ */
+export declare class TextMeasurementService {
+    private readonly _provider;
+    /**
+     * Creates a new TextMeasurementService.
+     * @param provider Optional custom provider. If not specified, auto-detects the best available.
+     */
+    constructor(provider?: ITextMeasurementProvider);
+    /**
+     * Measures text dimensions.
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     */
+    measureText(text: string, options: MeasureTextOptions): TextMetrics;
+    /**
+     * Gets the current provider.
+     */
+    get provider(): ITextMeasurementProvider;
+    /**
+     * Detects and returns the best available provider for the current environment.
+     *
+     * Detection order:
+     * 1. Browser canvas API
+     * 2. Node.js canvas package
+     * 3. Fallback estimation
+     */
+    static detectProvider(): ITextMeasurementProvider;
+}

package/src/lib/utils/text-measurement/text-measurement-service.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextMeasurementService = void 0;
+const browser_text_measurement_provider_1 = require("./browser-text-measurement-provider");
+const node_text_measurement_provider_1 = require("./node-text-measurement-provider");
+const fallback_text_measurement_provider_1 = require("./fallback-text-measurement-provider");
+/**
+ * Service for measuring text dimensions.
+ * Automatically detects the best available provider for the current environment.
+ *
+ * Provider selection order:
+ * 1. BrowserTextMeasurementProvider - Uses native canvas API (browsers)
+ * 2. NodeTextMeasurementProvider - Uses canvas npm package (Node.js)
+ * 3. FallbackTextMeasurementProvider - Character-based estimation (always available)
+ */
+class TextMeasurementService {
+    _provider;
+    /**
+     * Creates a new TextMeasurementService.
+     * @param provider Optional custom provider. If not specified, auto-detects the best available.
+     */
+    constructor(provider) {
+        this._provider = provider ?? TextMeasurementService.detectProvider();
+    }
+    /**
+     * Measures text dimensions.
+     * @param text The text to measure
+     * @param options Measurement options (fontSize, fontFamily, etc.)
+     * @returns TextMetrics with width, height, lines, anchorDx, anchorDy
+     */
+    measureText(text, options) {
+        return this._provider.measureText(text, options);
+    }
+    /**
+     * Gets the current provider.
+     */
+    get provider() {
+        return this._provider;
+    }
+    /**
+     * Detects and returns the best available provider for the current environment.
+     *
+     * Detection order:
+     * 1. Browser canvas API
+     * 2. Node.js canvas package
+     * 3. Fallback estimation
+     */
+    static detectProvider() {
+        // Try browser provider first
+        const browserProvider = new browser_text_measurement_provider_1.BrowserTextMeasurementProvider();
+        if (browserProvider.isAvailable()) {
+            return browserProvider;
+        }
+        // Try Node.js canvas provider
+        const nodeProvider = new node_text_measurement_provider_1.NodeTextMeasurementProvider();
+        if (nodeProvider.isAvailable()) {
+            return nodeProvider;
+        }
+        // Fall back to estimation
+        return new fallback_text_measurement_provider_1.FallbackTextMeasurementProvider();
+    }
+}
+exports.TextMeasurementService = TextMeasurementService;

package/src/lib/validators/template-validator.d.ts

@@ -0,0 +1,16 @@
+import { CreateTemplateInput } from "../types/api-types";
+/**
+ * Validator for template operations.
+ */
+export declare class TemplateValidator {
+    /**
+     * Validates input for template creation.
+     * @param input The creation input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateCreate(input: CreateTemplateInput): void;
+    /**
+     * Validates canvas dimensions.
+     */
+    private validateCanvasDimensions;
+}

package/src/lib/validators/template-validator.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateValidator = void 0;
+const api_errors_1 = require("../errors/api-errors");
+/**
+ * Validator for template operations.
+ */
+class TemplateValidator {
+    /**
+     * Validates input for template creation.
+     * @param input The creation input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateCreate(input) {
+        if (!input.title || typeof input.title !== "string") {
+            throw new api_errors_1.ValidationError("title is required", "title");
+        }
+        if (input.title.trim().length === 0) {
+            throw new api_errors_1.ValidationError("title cannot be empty", "title");
+        }
+        if (input.title.length > 200) {
+            throw new api_errors_1.ValidationError("title must be 200 characters or less", "title");
+        }
+        if (input.content !== undefined && typeof input.content !== "string") {
+            throw new api_errors_1.ValidationError("content must be a string", "content");
+        }
+        this.validateCanvasDimensions(input.canvasWidth, input.canvasHeight);
+    }
+    /**
+     * Validates canvas dimensions.
+     */
+    validateCanvasDimensions(width, height) {
+        if (width !== undefined) {
+            if (typeof width !== "number" || isNaN(width)) {
+                throw new api_errors_1.ValidationError("canvasWidth must be a valid number", "canvasWidth");
+            }
+            if (width < 100 || width > 10000) {
+                throw new api_errors_1.ValidationError("canvasWidth must be between 100 and 10000", "canvasWidth");
+            }
+        }
+        if (height !== undefined) {
+            if (typeof height !== "number" || isNaN(height)) {
+                throw new api_errors_1.ValidationError("canvasHeight must be a valid number", "canvasHeight");
+            }
+            if (height < 100 || height > 10000) {
+                throw new api_errors_1.ValidationError("canvasHeight must be between 100 and 10000", "canvasHeight");
+            }
+        }
+    }
+}
+exports.TemplateValidator = TemplateValidator;