@kritzel/engine 0.4.31

package/dist/types/classes/objects/image.class.d.ts

@@ -0,0 +1,246 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelAssetLoadState } from '../../interfaces/asset.interface';
+import { KritzelBaseObject } from './base-object.class';
+import { KritzelObjectExportContext, KritzelObjectExportFormat } from '../../interfaces/object-export.interface';
+/**
+ * Configuration options for creating a KritzelImage instance.
+ */
+export interface KritzelImageConfig {
+    assetId?: string;
+    mimeType?: string;
+    src?: string;
+    x?: number;
+    y?: number;
+    translateX?: number;
+    translateY?: number;
+    rotation?: number;
+    scale?: number;
+    width?: number;
+    height?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    maxLoadAttempts?: number;
+}
+/**
+ * Represents an image object on the canvas.
+ *
+ * Image bytes are NOT stored on this object or inside the Yjs document.
+ * Instead, the image is identified by a stable `assetId`; the actual
+ * bytes live in the asset storage layer (see `KritzelAssetResolver`).
+ * This keeps the CRDT small and lets images be served from pluggable
+ * storage (IndexedDB, HTTP, pre-signed S3, ...).
+ *
+ * Legacy images persisted before the asset layer existed may still carry
+ * a `src` data URL; the renderer and migration path treat `src` as a
+ * read-only fallback that is upgraded to an `assetId` on first load.
+ */
+export declare class KritzelImage extends KritzelBaseObject<HTMLImageElement> {
+    __class__: string;
+    /**
+     * Stable asset identifier (uuid) persisted in the Yjs document.
+     * Used by the asset resolver to locate the image bytes across
+     * devices and storage backends.
+     */
+    assetId: string;
+    /**
+     * MIME type of the referenced asset (e.g. `image/png`). Persisted in
+     * the Yjs document alongside `assetId` so the renderer can hint
+     * browsers and the exporter can produce correct data URLs.
+     */
+    mimeType: string;
+    /**
+     * Legacy inline source (typically a `data:` URL). Preserved only for
+     * backward compatibility with documents that were created before the
+     * asset storage layer existed. New images should use `assetId`.
+     *
+     * @deprecated Use `assetId` with an asset storage provider instead.
+     */
+    src: string;
+    maxWidth: number;
+    maxHeight: number;
+    maxCompressionSize: number;
+    /**
+     * URL resolved from the asset storage layer (e.g. a `blob:` or https URL).
+     * Not serialized into the Yjs document.
+     */
+    resolvedSrc?: string;
+    /**
+     * Current load state for the referenced asset.
+     * Not serialized into the Yjs document.
+     */
+    loadState: KritzelAssetLoadState;
+    /**
+     * Maximum number of resolution attempts per page load before the
+     * image is considered permanently failed. Defaults to 3.
+     *
+     * Only attempts that fail with a definitive "asset not found"
+     * (i.e. {@link AssetNotFoundError}) consume this budget. Transient
+     * failures (network blips, remote temporarily unreachable) do not
+     * count against the budget; they are bounded by
+     * {@link maxTransientRetryDurationMs} instead.
+     *
+     * The counter is transient (not persisted to Yjs) and resets every
+     * time a fresh `KritzelImage` instance is constructed, so a full page
+     * reload always grants a fresh budget.
+     */
+    maxLoadAttempts: number;
+    /**
+     * Number of resolution attempts that have failed with a definitive
+     * "asset not found" so far for the current page load. Only updates
+     * for {@link AssetNotFoundError} rejections; transient failures do
+     * not increment this counter. Not serialized into the Yjs document.
+     */
+    loadAttempts: number;
+    /**
+     * Maximum wall-clock duration (in milliseconds) the image will keep
+     * retrying transient resolution failures before giving up and
+     * surfacing the error placeholder. Defaults to 30 seconds.
+     *
+     * This bound exists so that a permanently-broken backend eventually
+     * surfaces UX feedback even when failures look "transient" (and
+     * therefore do not consume {@link maxLoadAttempts}).
+     */
+    maxTransientRetryDurationMs: number;
+    /**
+     * Wall-clock timestamp (ms since epoch) of the first transient
+     * failure in the current retry chain. `null` when no transient
+     * retries are in flight. Reset on success and on definitive miss.
+     * Not serialized into the Yjs document.
+     */
+    transientRetryStartedAt: number | null;
+    /**
+     * Creates a new KritzelImage instance.
+     * @param config - Optional configuration object to initialize image properties
+     *                 including assetId, src, position (x, y), translation, and scale.
+     */
+    constructor(config?: KritzelImageConfig);
+    /**
+     * Factory method to create a new KritzelImage instance with core integration.
+     * Initializes the image with default values and links it to the core store.
+     * @param core - The KritzelCore instance providing access to store and state management.
+     * @returns A new KritzelImage instance configured with the core context.
+     */
+    static create(core: KritzelCore, config?: Partial<KritzelImage>): KritzelImage;
+    /**
+     * Resizes the image while maintaining aspect ratio based on the new height.
+     * Updates the image's position and dimensions, then syncs changes to y.js
+     * for collaborative editing support.
+     * @param x - The new x translation coordinate.
+     * @param y - The new y translation coordinate.
+     * @param width - The new width (used for validation, not directly applied).
+     * @param height - The new height used to calculate the scale factor.
+     */
+    resize(x: number, y: number, width: number, height: number): void;
+    /**
+     * Serializes the image, excluding transient rendering state so the
+     * Yjs document never persists blob URLs or load lifecycle flags.
+     */
+    serialize(): any;
+    /**
+     * Carries transient asset-loading state (resolved URL, load lifecycle,
+     * retry counters) over from the previous local instance when a remote
+     * Yjs update produces a freshly-revived replacement. Without this,
+     * frequent remote updates (e.g. another user dragging the image)
+     * would reset `loadState` to `'idle'` on every tick and cause the
+     * skeleton to flicker between renders.
+     */
+    adoptTransientStateFrom(previous: KritzelBaseObject<any>): void;
+    /**
+     * Triggers (idempotent) resolution of the referenced asset. Updates
+     * `resolvedSrc` and `loadState` as the resolution progresses and
+     * schedules a re-render when the URL is available.
+     *
+     * Failure handling distinguishes two cases:
+     *  - Definitive miss ({@link AssetNotFoundError}): consumes one slot
+     *    of the {@link maxLoadAttempts} budget. Once exhausted, the
+     *    image is marked permanently `'error'` for the remainder of the
+     *    page load to avoid hammering an unavailable backend; a full
+     *    reload (which constructs a fresh instance) grants a new budget.
+     *  - Transient failure (network blip, resolver init in flight, ...):
+     *    does NOT consume the attempt budget. Retries continue with the
+     *    same exponential backoff up to
+     *    {@link maxTransientRetryDurationMs} of wall-clock time, after
+     *    which the image is marked `'error'`.
+     */
+    ensureResolved(): void;
+    /**
+     * Schedules a retry of {@link ensureResolved} with a small exponential
+     * backoff. The backoff base is the current attempt index so successive
+     * definitive misses ramp up gradually.
+     */
+    private scheduleRetry;
+    /**
+     * One-shot migration for legacy images that were persisted with an
+     * inline `src` data URL. Uploads the bytes to the asset resolver and
+     * swaps the image to use the resulting `assetId`, clearing `src` so
+     * the Yjs document no longer carries the raw payload.
+     */
+    private migrateLegacyDataUrlIfNeeded;
+    /**
+     * Kicks off asset resolution (or legacy data-URL migration) without
+     * requiring the `<img>` element to be mounted. Safe to call multiple
+     * times; both underlying paths are idempotent.
+     *
+     * Useful for the renderer's loading-skeleton path, where the actual
+     * `<img>` is not in the DOM yet but the asset bytes still need to
+     * start loading.
+     */
+    ensureLoaded(): void;
+    /**
+     * Prepares image objects for insertion into the canvas while preserving
+     * the standard object-first flow (`new KritzelImage(...); addObject(image)`).
+     *
+     * Behavior:
+     * - If `assetId` is already set, no-op.
+     * - If `src` is set (URL or data URL), uploads bytes through the asset
+     *   resolver, fills `assetId`/`mimeType`, computes dimensions when needed,
+     *   and seeds `resolvedSrc` for immediate rendering.
+     */
+    prepareForInsert(): Promise<void>;
+    /**
+     * Measures intrinsic image dimensions from a Blob.
+     */
+    private measureImageBlob;
+    /**
+     * Overrides base mount to kick off asset resolution the first time
+     * the image is attached to the DOM. Legacy images persisted with an
+     * inline `src` data URL are opportunistically migrated to the asset
+     * storage layer on first mount.
+     */
+    mount(element: HTMLImageElement): void;
+    /**
+     * Creates a KritzelImage from a URL, handling image loading and dimension calculation.
+     * Loads the image, calculates scaled dimensions respecting maxWidth/maxHeight constraints,
+     * and returns a fully configured KritzelImage instance.
+     *
+     * Intended for legacy / data-URL code paths only. New callers should
+     * upload through the asset resolver and construct the image from the
+     * resulting asset descriptor.
+     * @param src - The image URL or data URI to load.
+     * @param config - Optional partial configuration to pass to the KritzelImage constructor.
+     * @returns A promise resolving to a fully configured KritzelImage with correct dimensions.
+     */
+    static fromUrl(src: string, config?: Partial<KritzelImage>): Promise<KritzelImage>;
+    /**
+     * Creates a fully initialized KritzelImage from a Blob.
+     * Uploads the blob via the asset resolver and sets up dimensions/asset references.
+     *
+     * @param core - The KritzelCore instance providing the asset resolver and state.
+     * @param blob - The image Blob (e.g. from clipboard or file picker).
+     * @param config - Optional configuration to merge into the new image.
+     * @returns A promise resolving to a fully loaded KritzelImage object.
+     */
+    static fromBlob(core: KritzelCore, blob: Blob, config?: Partial<KritzelImage>): Promise<KritzelImage>;
+    /**
+     * Calculates scaled dimensions for an image while respecting maxWidth and maxHeight constraints.
+     * Maintains the original aspect ratio by using the smaller of the two scale ratios.
+     * @param img - The HTMLImageElement to calculate dimensions for.
+     * @returns An object containing the scaled width and height values.
+     */
+    calculateScaledDimensions(img: HTMLImageElement): {
+        scaledWidth: number;
+        scaledHeight: number;
+    };
+    getSupportedExportFormats(): KritzelObjectExportFormat[];
+    exportAs(format: KritzelObjectExportFormat, context: KritzelObjectExportContext): Promise<string | null>;
+}

package/dist/types/classes/objects/line.class.d.ts

@@ -0,0 +1,285 @@
+import { KritzelBaseObject } from './base-object.class';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+import { KritzelCore } from '../core/core.class';
+import { LineAnchor } from '../../interfaces/anchor.interface';
+import { ArrowHeadStyle, LineArrowConfig } from '../../interfaces/arrow-head.interface';
+import { ThemeAwareColor } from '../../constants/color-palette.constants';
+/**
+ * Configuration options for creating a KritzelLine instance.
+ */
+export interface KritzelLineConfig {
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    controlX?: number;
+    controlY?: number;
+    translateX?: number;
+    translateY?: number;
+    /** Rotation in degrees at initialization time. */
+    rotation?: number;
+    scale?: number;
+    stroke?: ThemeAwareColor;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Anchor connection for the start point */
+    startAnchor?: LineAnchor;
+    /** Anchor connection for the end point */
+    endAnchor?: LineAnchor;
+    /** Arrow head configuration for start and end of line */
+    arrows?: LineArrowConfig;
+}
+export declare class KritzelLine extends KritzelBaseObject<SVGElement> {
+    __class__: string;
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    controlX?: number;
+    controlY?: number;
+    stroke: ThemeAwareColor;
+    strokeWidth: number;
+    scale: number;
+    options: KritzelLineConfig | undefined;
+    /** Anchor connection for the start point of the line */
+    startAnchor?: LineAnchor;
+    /** Anchor connection for the end point of the line */
+    endAnchor?: LineAnchor;
+    /** Arrow head configuration for start and end of line */
+    arrows?: LineArrowConfig;
+    isVisible: boolean;
+    isDebugInfoVisible: boolean;
+    isCompleted: boolean;
+    /** Cached adjusted points for hit testing, accounting for rotation and translation */
+    private _adjustedPoints?;
+    /** Cached clip information for anchored line endpoints */
+    private _clipInfo;
+    /**
+     * Generates the SVG path data string for the line.
+     * Returns a quadratic Bezier curve path if control point exists, otherwise a straight line.
+     * @returns SVG path data string in the format "M x y Q cx cy ex ey" or "M x y L ex ey"
+     */
+    get d(): string;
+    /**
+     * Generates the SVG viewBox attribute string for rendering the line.
+     * @returns ViewBox string in the format "x y width height"
+     */
+    get viewBox(): string;
+    /**
+     * Creates a new KritzelLine instance.
+     * @param config - Optional configuration options for the line including start/end points,
+     *                 control point for curves, stroke settings, anchors, and arrow configuration
+     */
+    constructor(config?: KritzelLineConfig);
+    /**
+     * Factory method to create a new KritzelLine with a core reference and unique ID.
+     * This is the preferred way to create lines that will be managed by the core.
+     * @param core - The KritzelCore instance that will manage this line
+     * @param options - Optional configuration options for the line
+     * @returns A fully initialized KritzelLine instance with generated ID and workspace assignment
+     */
+    static create(core: KritzelCore, options?: KritzelLineConfig): KritzelLine;
+    /**
+     * Resizes the line to fit within the specified dimensions.
+     * Scales both endpoints and control point proportionally, then repositions the line.
+     * @param x - New X position for the line (or null to keep current)
+     * @param y - New Y position for the line (or null to keep current)
+     * @param width - New width to scale the line to (must be > 1)
+     * @param height - New height to scale the line to (must be > 1)
+     */
+    resize(x: number | null, y: number | null, width: number, height: number): void;
+    /**
+     * Sets the rotation angle of the line around its center.
+     * Invalidates cached adjusted points and clip info.
+     * @param value - Rotation angle in radians
+     */
+    rotate(value: number): void;
+    /**
+     * Moves the line by calculating the delta between start and end positions.
+     * Updates anchored objects if the line has anchor connections.
+     * @param startX - Starting X position of the drag in screen coordinates
+     * @param startY - Starting Y position of the drag in screen coordinates
+     * @param endX - Ending X position of the drag in screen coordinates
+     * @param endY - Ending Y position of the drag in screen coordinates
+     */
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    /**
+     * Tests if a point intersects with the line within the stroke tolerance.
+     * Uses distance to line segment for straight lines, or distance to Bezier curve for curved lines.
+     * @param x - X coordinate of the point to test in world coordinates
+     * @param y - Y coordinate of the point to test in world coordinates
+     * @returns True if the point is within the stroke width tolerance of the line
+     */
+    hitTest(x: number, y: number): boolean;
+    /**
+     * Tests if the line intersects with or is contained within a polygon.
+     * Checks endpoint containment, polygon vertex proximity, curve sampling for Bezier curves,
+     * and line-edge intersections for straight lines.
+     * @param polygon - The polygon to test intersection with, defined by four corner points
+     * @returns True if any part of the line intersects with the polygon
+     */
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    /**
+     * Updates the translation position of the line without recalculating dimensions.
+     * Invalidates cached adjusted points and clip info.
+     * @param x - New X translation in world coordinates
+     * @param y - New Y translation in world coordinates
+     */
+    updatePosition(x: number, y: number): void;
+    /**
+     * Updates a specific endpoint of the line (start or end).
+     * Recalculates the bounding box dimensions and adjusts translation to maintain
+     * the visual position after the origin shift, accounting for rotation.
+     * @param handleType - Which endpoint to update: 'start' or 'end'
+     * @param newX - New X coordinate in viewBox-local space (relative to x, y origin)
+     * @param newY - New Y coordinate in viewBox-local space (relative to x, y origin)
+     */
+    updateEndpoint(handleType: 'start' | 'end', newX: number, newY: number): void;
+    /**
+     * Updates the control point for a quadratic Bezier curve.
+     * Recalculates bounding box and adjusts translation to maintain visual position.
+     * Pass undefined for both parameters to convert the line back to a straight line.
+     * @param newX - New X coordinate for the control point, or undefined to remove
+     * @param newY - New Y coordinate for the control point, or undefined to remove
+     */
+    updateControlPoint(newX: number | undefined, newY: number | undefined): void;
+    /**
+     * Computes the line endpoints in world coordinates, accounting for rotation,
+     * scale, and translation transformations.
+     * @returns Array of two points [[startX, startY], [endX, endY]] in world coordinates
+     */
+    private computeAdjustedPoints;
+    /**
+     * Calculates the minimum distance from a point to a line segment.
+     * Uses parametric projection to find the closest point on the segment.
+     * @param x - X coordinate of the test point
+     * @param y - Y coordinate of the test point
+     * @param x1 - X coordinate of the segment start
+     * @param y1 - Y coordinate of the segment start
+     * @param x2 - X coordinate of the segment end
+     * @param y2 - Y coordinate of the segment end
+     * @returns The minimum distance from the point to the line segment
+     */
+    private pointToLineSegmentDistance;
+    /**
+     * Calculates the minimum distance from a point to a quadratic Bezier curve.
+     * Uses sampling along the curve (20 samples) to approximate the closest point.
+     * @param x - X coordinate of the test point in world coordinates
+     * @param y - Y coordinate of the test point in world coordinates
+     * @param startT - Start parameter for curve sampling (0-1), used for clipped curves
+     * @param endT - End parameter for curve sampling (0-1), used for clipped curves
+     * @returns The minimum distance from the point to the sampled curve
+     */
+    private pointToBezierDistance;
+    /**
+     * Retrieves or computes the clip information for anchored line endpoints.
+     * Caches the result to avoid recalculation on subsequent calls.
+     * @returns Object containing optional start and end clip points with world coordinates
+     *          and parametric t values for curve clipping
+     */
+    private getClipInfo;
+    /**
+     * Computes the adjusted control point in world coordinates.
+     * Applies rotation around the bounding box center, then scale and translation transforms.
+     * @returns Array [x, y] representing the control point in world coordinates,
+     *          or the midpoint of the line if no control point is defined
+     */
+    private computeAdjustedControlPoint;
+    /**
+     * Gets the bounding polygon of the line in world coordinates, accounting for rotation.
+     * Used for selection bounds and intersection testing.
+     * @returns A polygon with four corner points (topLeft, topRight, bottomRight, bottomLeft)
+     *          transformed to world coordinates with rotation applied
+     */
+    get rotatedPolygon(): KritzelPolygon;
+    /**
+     * Calculates the tight bounding box for a quadratic Bezier curve or straight line.
+     * For curves, finds extrema points where the derivative equals zero to ensure
+     * the bounding box encompasses the entire curve arc.
+     * @param startX - X coordinate of the line start point
+     * @param startY - Y coordinate of the line start point
+     * @param endX - X coordinate of the line end point
+     * @param endY - Y coordinate of the line end point
+     * @param controlX - X coordinate of the control point (undefined for straight lines)
+     * @param controlY - Y coordinate of the control point (undefined for straight lines)
+     * @param strokeWidth - Width of the line stroke for padding calculation
+     * @returns Object with minX, minY, maxX, maxY including stroke width padding
+     */
+    static calculateBoundingBox(startX: number, startY: number, endX: number, endY: number, controlX: number | undefined, controlY: number | undefined, strokeWidth: number): {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    /**
+     * Calculates the bounding box for this line instance using the current endpoint,
+     * control point, and stroke width values.
+     * @returns Object with minX, minY, maxX, maxY bounds including stroke width padding
+     */
+    calculateBoundingBox(): {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    /**
+     * Serializes the line while excluding transient cache fields.
+     * @returns A serializable line object without runtime caches
+     */
+    serialize(): any;
+    /**
+     * Deserializes and resets transient caches so geometry is recomputed lazily.
+     * @param object - The serialized line object
+     * @returns This instance cast to type T
+     */
+    deserialize<T>(object: any): T;
+    /**
+     * Recalculates and updates the width, height, x, y, and translation properties
+     * based on the current endpoint positions and stroke width.
+     * Called during construction and after endpoint changes.
+     */
+    private updateDimensions;
+    /**
+     * Gets the unique SVG marker ID for the arrow head at the start of the line.
+     * Used in SVG defs for marker-start attribute.
+     * @returns A unique marker ID string in the format "arrow-start-{lineId}"
+     */
+    get startMarkerId(): string;
+    /**
+     * Gets the unique SVG marker ID for the arrow head at the end of the line.
+     * Used in SVG defs for marker-end attribute.
+     * @returns A unique marker ID string in the format "arrow-end-{lineId}"
+     */
+    get endMarkerId(): string;
+    /**
+     * Gets the arrow head size for the specified end of the line.
+     * @param end - Which end to get the arrow size for: 'start' or 'end'
+     * @returns The configured arrow size, or strokeWidth * 3 as default
+     */
+    getArrowSize(end: 'start' | 'end'): number;
+    /**
+     * Gets the resolved fill color for the arrow head at the specified end.
+     * Resolves theme-aware colors to the appropriate value for the current theme.
+     * @param end - Which end to get the arrow fill for: 'start' or 'end'
+     * @returns The resolved CSS color string for the arrow fill
+     */
+    getArrowFill(end: 'start' | 'end'): string;
+    /**
+     * Generates SVG path data for an arrow head based on the given style.
+     * All paths are designed to fit in a 10x10 viewBox with the tip at (10, 5).
+     * @param style - The arrow head style: 'triangle' (filled), 'open' (outline),
+     *                'diamond' (rhombus), or 'circle'. Defaults to 'triangle'.
+     * @returns SVG path data string for use in a marker element
+     */
+    getArrowPath(style?: ArrowHeadStyle): string;
+    /**
+     * Checks if an arrow head is enabled at the start of the line.
+     * @returns True if the start arrow configuration exists and is enabled
+     */
+    get hasStartArrow(): boolean;
+    /**
+     * Checks if an arrow head is enabled at the end of the line.
+     * @returns True if the end arrow configuration exists and is enabled
+     */
+    get hasEndArrow(): boolean;
+}