@canvus/core 0.1.0

package/dist/matrix.js

@@ -0,0 +1,264 @@
+// ─────────────────────────────────────────────────────────────
+// canvus/src/matrix.ts
+// Pure mathematical viewport transform utilities.
+// Every function is stateless, side-effect free, and operates
+// exclusively on the primitive types defined in types.ts.
+// ─────────────────────────────────────────────────────────────
+import { ZOOM_MAX, ZOOM_MIN } from "./types.js";
+// ── Coordinate Space Conversions ────────────────────────────
+/**
+ * Projects a raw screen-space pointer coordinate (e.g. `MouseEvent.clientX/Y`)
+ * into the infinite canvas coordinate space, accounting for:
+ *   1. The canvas element's own position within the page (`canvasRect`).
+ *   2. The current pan offset (`viewport.offsetX/Y`).
+ *   3. The current zoom scale (`viewport.scale`).
+ *
+ * Derivation:
+ *   screenX = canvasX * scale + offsetX + canvasRect.x
+ *   ⟹ canvasX = (clientX - canvasRect.x - offsetX) / scale
+ *
+ * @param clientX - `MouseEvent.clientX` (viewport-relative screen pixel).
+ * @param clientY - `MouseEvent.clientY` (viewport-relative screen pixel).
+ * @param viewport - Current affine viewport transform state.
+ * @param canvasRect - Bounding rect of the `<canvas>` element on screen.
+ * @returns The corresponding point in canvas (world) space.
+ */
+export function screenToCanvas(clientX, clientY, viewport, canvasRect) {
+    return {
+        x: (clientX - canvasRect.x - viewport.offsetX) / viewport.scale,
+        y: (clientY - canvasRect.y - viewport.offsetY) / viewport.scale,
+    };
+}
+/**
+ * Projects a canvas-space coordinate back to absolute screen pixels,
+ * the algebraic inverse of `screenToCanvas`.
+ *
+ * Derivation:
+ *   screenX = canvasX * scale + offsetX + canvasRect.x
+ *
+ * @param canvasX - X position in canvas (world) space.
+ * @param canvasY - Y position in canvas (world) space.
+ * @param viewport - Current affine viewport transform state.
+ * @param canvasRect - Bounding rect of the `<canvas>` element on screen.
+ * @returns The corresponding point in screen (client) space.
+ */
+export function canvasToScreen(canvasX, canvasY, viewport, canvasRect) {
+    return {
+        x: canvasX * viewport.scale + viewport.offsetX + canvasRect.x,
+        y: canvasY * viewport.scale + viewport.offsetY + canvasRect.y,
+    };
+}
+// ── Zoom Anchoring ──────────────────────────────────────────
+/**
+ * Computes a new `ViewportMatrix` after applying a zoom delta
+ * anchored precisely at the cursor's current screen position.
+ *
+ * The key invariant: the canvas-space point directly beneath the
+ * cursor must map to the *exact same screen pixel* before and
+ * after the zoom. This prevents the jarring "zoom drift" that
+ * occurs with naïve center-point scaling.
+ *
+ * ### Mathematical derivation
+ *
+ * Let `(cx, cy)` be the cursor in screen-space relative to the
+ * canvas element origin:
+ *   cx = clientX - canvasRect.x
+ *   cy = clientY - canvasRect.y
+ *
+ * Before zoom, the canvas-space point under the cursor is:
+ *   worldX = (cx - offsetX) / oldScale
+ *   worldY = (cy - offsetY) / oldScale
+ *
+ * After zoom with `newScale`, we require the same world point to
+ * project back to `(cx, cy)`:
+ *   cx = worldX * newScale + newOffsetX
+ *   cy = worldY * newScale + newOffsetY
+ *
+ * Solving for the new offsets:
+ *   newOffsetX = cx - worldX * newScale
+ *              = cx - ((cx - offsetX) / oldScale) * newScale
+ *              = cx * (1 - newScale / oldScale) + offsetX * (newScale / oldScale)
+ *
+ * Equivalently (and more numerically stable):
+ *   newOffsetX = cx - (cx - offsetX) * (newScale / oldScale)
+ *
+ * @param clientX     - `MouseEvent.clientX` at the zoom gesture origin.
+ * @param clientY     - `MouseEvent.clientY` at the zoom gesture origin.
+ * @param scaleDelta  - Multiplicative scale factor to apply (e.g. 1.1 for zoom-in).
+ * @param viewport    - The current viewport transform state before zooming.
+ * @param canvasRect  - Bounding rect of the `<canvas>` element on screen.
+ * @returns A new `ViewportMatrix` with the anchored zoom applied.
+ */
+export function calculateZoomAnchor(clientX, clientY, scaleDelta, viewport, canvasRect) {
+    const newScale = clampScale(viewport.scale * scaleDelta);
+    // Actual ratio may differ from `scaleDelta` due to clamping.
+    const effectiveRatio = newScale / viewport.scale;
+    // Cursor position relative to the canvas element's top-left corner.
+    const cx = clientX - canvasRect.x;
+    const cy = clientY - canvasRect.y;
+    // Re-derive offsets so the world-point under (cx, cy) is invariant.
+    const newOffsetX = cx - (cx - viewport.offsetX) * effectiveRatio;
+    const newOffsetY = cy - (cy - viewport.offsetY) * effectiveRatio;
+    return {
+        scale: newScale,
+        offsetX: newOffsetX,
+        offsetY: newOffsetY,
+    };
+}
+/**
+ * Convenience wrapper that converts a `WheelEvent.deltaY` value
+ * into a multiplicative scale factor and delegates to
+ * `calculateZoomAnchor`.
+ *
+ * Scroll-up (negative deltaY) zooms in, scroll-down zooms out.
+ * The sensitivity constant (0.001) yields a smooth, non-jarring
+ * zoom curve across trackpad and discrete-notch scroll wheels.
+ *
+ * @param clientX    - `MouseEvent.clientX` at the wheel event.
+ * @param clientY    - `MouseEvent.clientY` at the wheel event.
+ * @param deltaY     - `WheelEvent.deltaY` (positive = scroll down = zoom out).
+ * @param viewport   - Current viewport state.
+ * @param canvasRect - Canvas element bounding rect.
+ * @returns A new `ViewportMatrix` with the wheel-zoom applied.
+ */
+export function applyWheelZoom(clientX, clientY, deltaY, viewport, canvasRect, isPinch = false) {
+    // Trackpad pinch events have small deltas. We use a higher sensitivity (0.01)
+    // for pinch to make it feel fluid, and a standard sensitivity (0.001) for regular scroll.
+    const sensitivity = isPinch ? 0.01 : 0.001;
+    let scaleDelta = Math.exp(-deltaY * sensitivity);
+    // Clamp the scaleDelta to a safe range per event [0.85, 1.15] (15% max change)
+    // to prevent standard mouse wheel zooms (e.g. Ctrl + Mouse Wheel) from zooming too fast.
+    scaleDelta = Math.min(1.15, Math.max(0.85, scaleDelta));
+    return calculateZoomAnchor(clientX, clientY, scaleDelta, viewport, canvasRect);
+}
+// ── Pan (Translate) ─────────────────────────────────────────
+/**
+ * Applies a screen-space pan delta to the viewport offset.
+ * Typically driven by pointer-move events while spacebar is held
+ * or middle-mouse is pressed.
+ *
+ * @param dx - Horizontal screen-pixel delta (`e.movementX`).
+ * @param dy - Vertical screen-pixel delta (`e.movementY`).
+ * @param viewport - Current viewport state.
+ * @returns A new `ViewportMatrix` with the pan offset applied.
+ */
+export function applyPan(dx, dy, viewport) {
+    return {
+        scale: viewport.scale,
+        offsetX: viewport.offsetX + dx,
+        offsetY: viewport.offsetY + dy,
+    };
+}
+// ── Hit Testing ─────────────────────────────────────────────
+/**
+ * Axis-Aligned Bounding Box (AABB) point-inclusion test.
+ *
+ * Returns `true` if the point `(x, y)` lies within (or exactly on
+ * the boundary of) the rectangle described by `bounds`.
+ *
+ * Both coordinates and bounds should be in the same space
+ * (typically canvas-space after `screenToCanvas` conversion).
+ *
+ * @param x - Point X coordinate.
+ * @param y - Point Y coordinate.
+ * @param bounds - The axis-aligned bounding rectangle to test against.
+ * @returns Whether the point is inside or on the edge of `bounds`.
+ */
+export function isPointInElement(x, y, bounds) {
+    return (x >= bounds.x &&
+        x <= bounds.x + bounds.width &&
+        y >= bounds.y &&
+        y <= bounds.y + bounds.height);
+}
+/**
+ * Determines which `WebHTMLNode` (if any) is hit by a canvas-space
+ * point, respecting z-order (last in the array = topmost).
+ *
+ * @param x - Canvas-space X coordinate.
+ * @param y - Canvas-space Y coordinate.
+ * @param elements - Array of elements with `id` and bounding `Rect`.
+ * @returns The `id` of the topmost hit element, or `null` if none.
+ */
+export function hitTestElements(x, y, elements) {
+    // Walk backwards for top-most-first z-order.
+    for (let i = elements.length - 1; i >= 0; i--) {
+        const el = elements[i];
+        if (el.currentRect && isPointInElement(x, y, el.currentRect)) {
+            return el.id;
+        }
+    }
+    return null;
+}
+// ── Resize Anchor Positions ─────────────────────────────────
+/**
+ * Computes the screen-space positions of all 8 resize anchor
+ * handles for a given element bounding box.
+ *
+ * Returns an object keyed by anchor direction with the
+ * corresponding screen-space `Vec2` position of each handle center.
+ *
+ * @param bounds    - The element's bounding rect in canvas-space.
+ * @param viewport  - Current viewport transform.
+ * @param canvasRect - Canvas element bounding rect on screen.
+ * @returns Record mapping each anchor to its screen-space center point.
+ */
+export function getAnchorPositions(bounds, viewport, canvasRect) {
+    const { x, y, width, height } = bounds;
+    // Canvas-space anchor centers (mid-edge and corners).
+    const midX = x + width / 2;
+    const midY = y + height / 2;
+    const right = x + width;
+    const bottom = y + height;
+    const toScreen = (cx, cy) => canvasToScreen(cx, cy, viewport, canvasRect);
+    return {
+        nw: toScreen(x, y),
+        n: toScreen(midX, y),
+        ne: toScreen(right, y),
+        e: toScreen(right, midY),
+        se: toScreen(right, bottom),
+        s: toScreen(midX, bottom),
+        sw: toScreen(x, bottom),
+        w: toScreen(x, midY),
+    };
+}
+// ── Utilities ───────────────────────────────────────────────
+/** Clamps a scale value to the allowed zoom range. */
+export function clampScale(s) {
+    return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, s));
+}
+/**
+ * Linearly interpolates between two values.
+ * Useful for animated viewport transitions.
+ *
+ * @param a - Start value.
+ * @param b - End value.
+ * @param t - Interpolation factor in [0, 1].
+ */
+export function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/**
+ * Linearly interpolates between two `ViewportMatrix` states.
+ * Useful for smooth animated zoom/pan transitions.
+ *
+ * @param from - Starting viewport.
+ * @param to   - Target viewport.
+ * @param t    - Interpolation factor in [0, 1].
+ */
+export function lerpViewport(from, to, t) {
+    return {
+        scale: lerp(from.scale, to.scale, t),
+        offsetX: lerp(from.offsetX, to.offsetX, t),
+        offsetY: lerp(from.offsetY, to.offsetY, t),
+    };
+}
+/**
+ * Checks if two axis-aligned bounding rectangles intersect.
+ */
+export function rectsIntersect(r1, r2) {
+    return !(r2.x > r1.x + r1.width ||
+        r2.x + r2.width < r1.x ||
+        r2.y > r1.y + r1.height ||
+        r2.y + r2.height < r1.y);
+}
+//# sourceMappingURL=matrix.js.map

package/dist/matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.js","sourceRoot":"","sources":["../src/matrix.ts"],"names":[],"mappings":"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"}

package/dist/renderer.d.ts

@@ -0,0 +1,286 @@
+import type { Rect, ResizeAnchor, Vec2, ViewportMatrix, ResolvedNode } from "./types.js";
+import type { GridTrack } from "./layout.js";
+import type { DropTarget } from "./drop-zone.js";
+/** Visual styling tokens for the overlay renderer. */
+export interface OverlayStyle {
+    /** Stroke color for selected element outlines. */
+    selectionStroke: string;
+    /** Stroke width (screen pixels) for selection outlines. */
+    selectionWidth: number;
+    /** Shadow color for the selection glow effect. */
+    selectionGlow: string;
+    /** Blur radius (px) for the selection glow. */
+    selectionGlowRadius: number;
+    /** Stroke color for hovered (non-selected) element outlines. */
+    hoverStroke: string;
+    /** Stroke width for hover outlines. */
+    hoverWidth: number;
+    /** Dash pattern for hover outlines (`[]` = solid). */
+    hoverDash: number[];
+    /** Side length of each square resize handle (screen px). */
+    handleSize: number;
+    /** Fill color for resize handles. */
+    handleFill: string;
+    /** Stroke color for resize handles. */
+    handleStroke: string;
+    /** Stroke width for resize handles. */
+    handleStrokeWidth: number;
+    /** Corner radius of resize handles (`0` = square). */
+    handleRadius: number;
+    /**
+     * Hit-test radius around each handle center (screen px).
+     * Should be ≥ handleSize/2 for comfortable targeting (Fitts's law).
+     */
+    handleHitRadius: number;
+    /** Fill color when a handle is actively being dragged. */
+    handleActiveFill: string;
+    /** Stroke color for alignment guide lines. */
+    guideStroke: string;
+    /** Stroke width for guides. */
+    guideWidth: number;
+    /** Dash pattern for guides. */
+    guideDash: number[];
+    /** Stroke color for the origin crosshair. */
+    originStroke: string;
+    /** Dash pattern for the origin crosshair. */
+    originDash: number[];
+    /** Stroke color for the aggregate bounding box. */
+    multiSelectStroke: string;
+    /** Dash pattern for the aggregate bounding box. */
+    multiSelectDash: number[];
+    /** Background color for layout mode badge pills. */
+    layoutBadgeBg: string;
+    /** Text color for layout badge labels. */
+    layoutBadgeText: string;
+    /** Font for layout badge labels. */
+    layoutBadgeFont: string;
+    /** Stroke color for grid track overlay lines. */
+    gridTrackStroke: string;
+    /** Dash pattern for grid track lines. */
+    gridTrackDash: number[];
+    /** Stroke color for parent highlight outline when child is selected. */
+    parentHighlightStroke: string;
+    /** Stroke color for available children outlines when container is selected. */
+    childOutlineStroke: string;
+    /** Stroke color for the active drop container border. */
+    dropZoneStroke: string;
+    /** Stroke width for drop zones. */
+    dropZoneWidth: number;
+    /** Stroke color for the insertion line. */
+    insertionLineStroke: string;
+    /** Stroke width for the insertion line. */
+    insertionLineWidth: number;
+}
+/** Alignment guide line in canvas-space. */
+export interface Guide {
+    /** Which axis the guide runs along. `"x"` = vertical line, `"y"` = horizontal line. */
+    axis: "x" | "y";
+    /** Canvas-space coordinate on the perpendicular axis. */
+    position: number;
+}
+/**
+ * Complete description of a single overlay frame.
+ * Passed to `OverlayRenderer.render()` each time the
+ * workspace state changes.
+ */
+export interface OverlayFrame {
+    /** Current viewport transform. */
+    viewport: ViewportMatrix;
+    /** All mounted nodes with their canvas-space rects and hierarchy data. */
+    nodes: ReadonlyArray<ResolvedNode>;
+    /** Set of currently selected node IDs. */
+    selectedIds: ReadonlySet<string>;
+    /** ID of the node under the cursor (hover), or `null`. */
+    hoveredId: string | null;
+    /** The resize anchor currently being dragged, or `null`. */
+    activeAnchor: ResizeAnchor | null;
+    /** Alignment guides to render (typically computed by `computeAlignmentGuides`). */
+    guides: ReadonlyArray<Guide>;
+    /** ID of the node currently being dragged, or `null`. */
+    draggedNodeId?: string | null;
+    /** ID of the node currently being resized, or `null`. */
+    resizedNodeId?: string | null;
+    /** Layout mode badges to render on selected containers. */
+    layoutBadges?: ReadonlyArray<LayoutBadgeInfo>;
+    /** Grid track overlays to render on selected grid containers. */
+    gridOverlays?: ReadonlyArray<GridOverlayInfo>;
+    /** Active drop zone target container and index. */
+    activeDropTarget?: DropTarget | null;
+    /** Active marquee selection rect in canvas-space. */
+    marqueeRect?: Rect | null;
+    /** Active spacing adjusters to render on screen. */
+    spacingAdjusters?: ReadonlyArray<SpacingAdjusterInfo>;
+    /** Active drawing element bounds in canvas-space. */
+    drawingRect?: Rect | null;
+    /** Active drawing element HTML tag name. */
+    drawingTag?: string | null;
+    /** Active or hovered corner radius handle name (tl, tr, bl, br). */
+    activeRadiusCorner?: string | null;
+}
+export type SpacingAdjusterType = "padding-top" | "padding-right" | "padding-bottom" | "padding-left" | "margin-top" | "margin-right" | "margin-bottom" | "margin-left";
+export interface SpacingAdjusterInfo {
+    type: SpacingAdjusterType;
+    /** Bounding box of the handle bar in canvas-space. */
+    rect: Rect;
+    /** Visual bounding box representing the actual spacing dimensions exactly. */
+    visualRect: Rect;
+    /** Spacing value in pixels. */
+    value: number;
+    /** Hover state. */
+    isHovered: boolean;
+    /** Active dragging state. */
+    isActive: boolean;
+}
+/** Data for rendering a layout mode badge on a container. */
+export interface LayoutBadgeInfo {
+    /** Canvas-space rect of the container. */
+    rect: Rect;
+    /** Short label like "FLEX →", "GRID", "BLOCK". */
+    label: string;
+    /** True if this is a script/JS badge. */
+    isJS?: boolean;
+}
+/** Data for rendering grid track lines on a container. */
+export interface GridOverlayInfo {
+    /** Canvas-space rect of the container. */
+    rect: Rect;
+    /** Column tracks (offsets relative to container padding edge). */
+    columns: ReadonlyArray<GridTrack>;
+    /** Row tracks. */
+    rows: ReadonlyArray<GridTrack>;
+}
+/**
+ * Returns the appropriate CSS cursor string for a given
+ * resize anchor direction.
+ *
+ * @param anchor - The anchor being hovered, or `null`.
+ * @returns CSS cursor value (e.g. `"nwse-resize"`), or
+ *          `"default"` if no anchor is active.
+ */
+export declare function anchorCursor(anchor: ResizeAnchor | null): string;
+/**
+ * Hardware-accelerated canvas overlay renderer.
+ *
+ * Handles all visual affordances drawn on top of the Shadow DOM
+ * projection layer: selection outlines with glow, 8-point resize
+ * handles, hover highlights, alignment guides, and origin markers.
+ *
+ * ### Usage
+ * ```ts
+ * const renderer = new OverlayRenderer(canvas);
+ * renderer.resize(width, height);
+ * renderer.render(frame);
+ * ```
+ *
+ * ### Performance Notes
+ * - Single `render()` call per frame — no internal rAF loop.
+ * - DPR-aware: physical pixels are scaled so lines stay crisp
+ *   on retina displays.
+ * - Canvas state changes are minimized by batching similar
+ *   operations (hover pass → selection pass → handle pass).
+ */
+export declare function isContainerNode(node: ResolvedNode): boolean;
+export declare class OverlayRenderer {
+    private readonly canvas;
+    private readonly ctx;
+    private readonly style;
+    private dpr;
+    private width;
+    private height;
+    /**
+     * @param canvas - The `<canvas>` element to draw on.
+     * @param style  - Optional partial style overrides.
+     */
+    constructor(canvas: HTMLCanvasElement, style?: Partial<OverlayStyle>);
+    /**
+     * Resizes the canvas buffer to match the given CSS dimensions,
+     * scaling by the device pixel ratio for crisp rendering.
+     *
+     * Call this on window resize and initial setup.
+     *
+     * @param cssWidth  - Desired CSS width in pixels.
+     * @param cssHeight - Desired CSS height in pixels.
+     */
+    resize(cssWidth: number, cssHeight: number): void;
+    /**
+     * Draws a complete overlay frame.
+     *
+     * Rendering order (painter's algorithm, back to front):
+     *   1. Clear
+     *   2. Origin crosshair
+     *   3. Alignment guides
+     *   4. Hover outlines (non-selected, hovered node)
+     *   5. Selection outlines + glow
+     *   6. Multi-select bounding box (if > 1 selected)
+     *   7. Resize handles (selected nodes only)
+     */
+    render(frame: OverlayFrame): void;
+    /**
+     * Tests if a screen-space point is within the hit radius of
+     * any of the 8 resize handles for a given element.
+     *
+     * The `canvasRect` parameter is not needed here because
+     * `bounds` is in canvas-space and we project it using the
+     * viewport ourselves.
+     *
+     * @param screenX   - Pointer X in screen-space (relative to
+     *                    the canvas element, NOT clientX).
+     * @param screenY   - Pointer Y relative to canvas element.
+     * @param bounds    - The element's bounding rect in canvas-space.
+     * @param viewport  - Current viewport transform.
+     * @returns The anchor being hovered, or `null`.
+     */
+    hitTestHandle(screenX: number, screenY: number, bounds: Readonly<Rect>, viewport: Readonly<ViewportMatrix>): ResizeAnchor | null;
+    /** Draws the 8 resize handles around a projected rect. */
+    private drawHandles;
+    /** Draws the origin crosshair spanning the full viewport. */
+    private drawOrigin;
+    /** Draws a single alignment guide line. */
+    private drawGuide;
+    /** Draws the aggregate bounding box around all selected nodes. */
+    private drawMultiSelectBounds;
+    /**
+     * Draws a layout mode badge pill (e.g. "FLEX →", "GRID")
+     * anchored to the top-left corner of a container's projected rect.
+     */
+    private drawLayoutBadge;
+    /**
+     * Draws dotted grid track lines overlaying a grid container.
+     */
+    private drawGridOverlay;
+}
+/**
+ * Computes alignment guide lines between a moving element and
+ * all other elements. Detects edge-to-edge and center-to-center
+ * alignment on both axes.
+ *
+ * ### Checked alignments (per axis)
+ * - **Left/Top edge** of the moving element ↔ left/top, center,
+ *   right/bottom of each other element.
+ * - **Center** of the moving element ↔ left/top, center,
+ *   right/bottom of each other element.
+ * - **Right/Bottom edge** of the moving element ↔ left/top,
+ *   center, right/bottom of each other element.
+ *
+ * @param movingRect  - The bounding rect of the element being
+ *                       dragged or resized (canvas-space).
+ * @param otherRects  - Array of bounding rects of all other
+ *                       elements to snap against (canvas-space).
+ * @param threshold   - Snap distance in canvas-space pixels.
+ * @returns Array of `Guide` objects to render.
+ */
+export declare function computeAlignmentGuides(movingRect: Readonly<Rect>, otherRects: ReadonlyArray<Readonly<Rect>>, threshold?: number): Guide[];
+/**
+ * Computes snap-corrected position for a moving rect.
+ *
+ * If any edge or center of the moving rect is within `threshold`
+ * of an alignment target, the returned position is adjusted to
+ * snap exactly onto that target.
+ *
+ * @param movingRect - The element's current canvas-space rect.
+ * @param otherRects - All other element rects to snap against.
+ * @param threshold  - Snap distance in canvas-space pixels.
+ * @returns A new `{ x, y }` position with snapping applied.
+ */
+export declare function computeSnappedPosition(movingRect: Readonly<Rect>, otherRects: ReadonlyArray<Readonly<Rect>>, threshold?: number): Vec2;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAIjD,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAE3B,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,mBAAmB,EAAE,MAAM,CAAC;IAG5B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IAGpB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IAGzB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAC;IAGpB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;IAGrB,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,eAAe,EAAE,MAAM,EAAE,CAAC;IAG1B,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IAGxB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,aAAa,EAAE,MAAM,EAAE,CAAC;IAGxB,wEAAwE;IACxE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM,CAAC;IAG3B,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAiDD,4CAA4C;AAC5C,MAAM,WAAW,KAAK;IACpB,uFAAuF;IACvF,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,QAAQ,EAAE,cAAc,CAAC;IACzB,0EAA0E;IAC1E,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACnC,0CAA0C;IAC1C,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4DAA4D;IAC5D,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,mFAAmF;IACnF,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAG9B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC9C,iEAAiE;IACjE,YAAY,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAG9C,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAGrC,qDAAqD;IACrD,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACtD,qDAAqD;IACrD,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oEAAoE;IACpE,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,cAAc,GACd,eAAe,GACf,aAAa,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,sDAAsD;IACtD,IAAI,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,UAAU,EAAE,IAAI,CAAC;IACjB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,IAAI,EAAE,IAAI,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,IAAI,EAAE,IAAI,CAAC;IACX,kEAAkE;IAClE,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAClC,kBAAkB;IAClB,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CAChC;AA0BD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,CAEhE;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAsB3D;AAED,qBAAa,eAAe;IAYxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAXzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2B;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IAEnB;;;OAGG;gBAEgB,MAAM,EAAE,iBAAiB,EAC1C,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAU/B;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAgBjD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAoZjC;;;;;;;;;;;;;;OAcG;IACH,aAAa,CACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EACtB,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,GACjC,YAAY,GAAG,IAAI;IAkBtB,0DAA0D;IAC1D,OAAO,CAAC,WAAW;IAgDnB,6DAA6D;IAC7D,OAAO,CAAC,UAAU;IAwBlB,2CAA2C;IAC3C,OAAO,CAAC,SAAS;IAyBjB,kEAAkE;IAClE,OAAO,CAAC,qBAAqB;IAmC7B;;;OAGG;IACH,OAAO,CAAC,eAAe;IA+CvB;;OAEG;IACH,OAAO,CAAC,eAAe;CA2CxB;AAWD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,EAC1B,UAAU,EAAE,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EACzC,SAAS,GAAE,MAA+B,GACzC,KAAK,EAAE,CAsDT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,EAC1B,UAAU,EAAE,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EACzC,SAAS,GAAE,MAA+B,GACzC,IAAI,CAuDN"}