cursedbelt 5.81.2 → 5.82.0

package/dist/react/canvas-hud/AlignmentGuides.d.ts

@@ -0,0 +1,26 @@
+import { type RefObject } from 'react';
+import { type AlignmentGuide } from './alignment.js';
+export interface AlignmentGuidesProps {
+    /** What `snapToAlignment` returned for the drag in progress; empty draws nothing. */
+    guides: readonly AlignmentGuide[];
+    /** The view's scale, so each line stays one screen pixel wide at every zoom. */
+    scale: number;
+}
+/**
+ * CNV-12's lines — Mural's thin accent hairlines, drawn while an item is dragged and gone the moment
+ * it is let go. Place it INSIDE the canvas's transformed stage (React Flow's `ViewportPortal`, or the
+ * element a canvas puts `translate(x, y) scale(k)` on): it draws in world units from the stage's
+ * origin, so it pans and zooms with the content and never needs the view's offset.
+ *
+ * `aria-hidden` and `pointer-events: none`: the lines are a hint about where the item will land,
+ * which the item itself already shows; they must never take a pointer from the item underneath.
+ */
+export declare function AlignmentGuides({ guides, scale }: AlignmentGuidesProps): import("react").JSX.Element | null;
+/**
+ * Whether ⌘ or Ctrl is held right now — CNV-12's way to drag an item off the lines. A ref, not
+ * state: React Flow reports a drag as a stream of changes with no pointer event on them, so the
+ * canvas reads this inside its change handler, between renders. Kept current from the pointer's
+ * own moves and from the keys, so pressing ⌘ mid-drag takes effect on the next move.
+ */
+export declare function useSnapSuspended(): RefObject<boolean>;
+//# sourceMappingURL=AlignmentGuides.d.ts.map

package/dist/react/canvas-hud/AlignmentGuides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlignmentGuides.d.ts","sourceRoot":"","sources":["../../../src/react/canvas-hud/AlignmentGuides.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,OAAO,CAAC;AAC1D,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,qFAAqF;IACrF,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,oBAAoB,sCA2CtE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,SAAS,CAAC,OAAO,CAAC,CAuBrD"}

package/dist/react/canvas-hud/AlignmentGuides.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { snapSuspended } from './alignment.js';
+/**
+ * CNV-12's lines — Mural's thin accent hairlines, drawn while an item is dragged and gone the moment
+ * it is let go. Place it INSIDE the canvas's transformed stage (React Flow's `ViewportPortal`, or the
+ * element a canvas puts `translate(x, y) scale(k)` on): it draws in world units from the stage's
+ * origin, so it pans and zooms with the content and never needs the view's offset.
+ *
+ * `aria-hidden` and `pointer-events: none`: the lines are a hint about where the item will land,
+ * which the item itself already shows; they must never take a pointer from the item underneath.
+ */
+export function AlignmentGuides({ guides, scale }) {
+    if (guides.length === 0 || !(scale > 0))
+        return null;
+    const width = 1 / scale;
+    return (_jsx("svg", { "data-testid": 'canvas-alignment-guides', "aria-hidden": 'true', width: 1, height: 1, 
+        // At the stage's origin, above the items it is drawn among (React Flow's nodes reach z ~2000).
+        className: 'pointer-events-none absolute top-0 left-0 z-[5000] overflow-visible', children: guides.map((guide) => guide.axis === 'x' ? (_jsx("line", { "data-guide": 'x', x1: guide.at, x2: guide.at, y1: guide.from, y2: guide.to, stroke: 'var(--accent)', strokeOpacity: 0.85, strokeWidth: width, shapeRendering: 'crispEdges' }, `x${guide.at}`)) : (_jsx("line", { "data-guide": 'y', x1: guide.from, x2: guide.to, y1: guide.at, y2: guide.at, stroke: 'var(--accent)', strokeOpacity: 0.85, strokeWidth: width, shapeRendering: 'crispEdges' }, `y${guide.at}`))) }));
+}
+/**
+ * Whether ⌘ or Ctrl is held right now — CNV-12's way to drag an item off the lines. A ref, not
+ * state: React Flow reports a drag as a stream of changes with no pointer event on them, so the
+ * canvas reads this inside its change handler, between renders. Kept current from the pointer's
+ * own moves and from the keys, so pressing ⌘ mid-drag takes effect on the next move.
+ */
+export function useSnapSuspended() {
+    const held = useRef(false);
+    useEffect(() => {
+        const read = (event) => {
+            held.current = snapSuspended(event);
+        };
+        const clear = () => {
+            held.current = false;
+        };
+        window.addEventListener('keydown', read, true);
+        window.addEventListener('keyup', read, true);
+        window.addEventListener('pointermove', read, true);
+        window.addEventListener('pointerdown', read, true);
+        window.addEventListener('blur', clear);
+        return () => {
+            window.removeEventListener('keydown', read, true);
+            window.removeEventListener('keyup', read, true);
+            window.removeEventListener('pointermove', read, true);
+            window.removeEventListener('pointerdown', read, true);
+            window.removeEventListener('blur', clear);
+        };
+    }, []);
+    return held;
+}
+//# sourceMappingURL=AlignmentGuides.js.map

package/dist/react/canvas-hud/AlignmentGuides.js.map

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

package/dist/react/canvas-hud/alignment.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CNV-12 — alignment guides while dragging (forge task 3437). The owner asked for Mural's lines: as
+ * an item is dragged, a hairline shows when one of its edges or its middle lines up with another
+ * item's, and the item settles onto that line. Figma, Miro and Mural all draw the same thing.
+ *
+ * Pure — no React, no DOM — so a canvas built on React Flow (desk, arch) and one built on its own
+ * stage use the same rule, pinned by `alignment.spec.tsx`. Everything is in WORLD units; the caller
+ * turns its screen tolerance into world units by dividing by the view's scale, so the pull feels the
+ * same at every zoom.
+ */
+import type { CanvasBounds } from './viewport.js';
+/** How close, in SCREEN pixels, an edge or a middle must come to another's before it snaps. */
+export declare const ALIGNMENT_TOLERANCE = 6;
+/**
+ * One line to draw. `axis: 'x'` is a VERTICAL line at `x = at`, running from `y = from` to
+ * `y = to`; `axis: 'y'` is a horizontal one at `y = at`, running along x.
+ */
+export interface AlignmentGuide {
+    axis: 'x' | 'y';
+    at: number;
+    from: number;
+    to: number;
+}
+export interface AlignmentSnap {
+    /** What to add to the dragged item's position so it sits on the nearest line — 0 when none is near. */
+    dx: number;
+    dy: number;
+    /** Every line the item rests on AFTER the snap, merged per position, spanning every item it meets. */
+    guides: AlignmentGuide[];
+}
+/**
+ * Where `moving` should settle, and the guides to draw there. `others` is every item it may line up
+ * with — never the item itself, nor anything travelling with it (a multi-selection, a group's
+ * contents). `tolerance` is in world units: `ALIGNMENT_TOLERANCE / view.scale`.
+ *
+ * Each axis snaps on its own, to the closest line within tolerance, so an item can settle on a
+ * vertical and a horizontal guide at once. A guide is drawn for every line that matches after the
+ * snap — two neighbours sharing a left edge make one line through all three — and runs from the
+ * farthest item it touches to the farthest on the other side, the way Mural draws it.
+ *
+ * `axis` limits it to one direction for an item that only moves one way — family's lineages slide
+ * sideways and never change row, so `'x'` (vertical lines only): a row of cards would otherwise draw
+ * a horizontal line along every generation.
+ */
+export declare function snapToAlignment(moving: CanvasBounds, others: readonly CanvasBounds[], tolerance: number, axis?: 'x' | 'y' | 'both'): AlignmentSnap;
+/** The box around several — what a multi-selection drags as one. `null` for none. */
+export declare function unionBounds(boxes: readonly CanvasBounds[]): CanvasBounds | null;
+/**
+ * Snapping is suspended while ⌘ (or Ctrl) is held — Figma's convention, so an item can still be
+ * put a few pixels off a line on purpose. Read from the drag's own pointer event.
+ */
+export declare function snapSuspended(event: {
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+} | null | undefined): boolean;
+//# sourceMappingURL=alignment.d.ts.map

package/dist/react/canvas-hud/alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../../src/react/canvas-hud/alignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B,uGAAuG;IACvG,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,sGAAsG;IACtG,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,GAAG,GAAG,GAAG,GAAG,MAAe,GAChC,aAAa,CA4Cf;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,GAAG,IAAI,CAa/E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEzG"}

package/dist/react/canvas-hud/alignment.js

@@ -0,0 +1,100 @@
+/** How close, in SCREEN pixels, an edge or a middle must come to another's before it snaps. */
+export const ALIGNMENT_TOLERANCE = 6;
+const NONE = { dx: 0, dy: 0, guides: [] };
+/** Start, middle, end — the three lines of a box along one axis. */
+function lines(start, size) {
+    return [start, start + size / 2, start + size];
+}
+/** The smallest move along one axis that puts any of `moving`'s lines on any of `targets`' lines. */
+function nearest(moving, targets, tolerance) {
+    let best = Number.POSITIVE_INFINITY;
+    for (const target of targets) {
+        for (const want of target) {
+            for (const have of moving) {
+                const delta = want - have;
+                if (Math.abs(delta) <= tolerance && Math.abs(delta) < Math.abs(best))
+                    best = delta;
+            }
+        }
+    }
+    return Number.isFinite(best) ? best : 0;
+}
+/**
+ * Where `moving` should settle, and the guides to draw there. `others` is every item it may line up
+ * with — never the item itself, nor anything travelling with it (a multi-selection, a group's
+ * contents). `tolerance` is in world units: `ALIGNMENT_TOLERANCE / view.scale`.
+ *
+ * Each axis snaps on its own, to the closest line within tolerance, so an item can settle on a
+ * vertical and a horizontal guide at once. A guide is drawn for every line that matches after the
+ * snap — two neighbours sharing a left edge make one line through all three — and runs from the
+ * farthest item it touches to the farthest on the other side, the way Mural draws it.
+ *
+ * `axis` limits it to one direction for an item that only moves one way — family's lineages slide
+ * sideways and never change row, so `'x'` (vertical lines only): a row of cards would otherwise draw
+ * a horizontal line along every generation.
+ */
+export function snapToAlignment(moving, others, tolerance, axis = 'both') {
+    if (others.length === 0 || !(tolerance > 0))
+        return NONE;
+    const near = others.filter((other) => other.width >= 0 && other.height >= 0 && Number.isFinite(other.x) && Number.isFinite(other.y));
+    const dx = axis === 'y' ? 0 : nearest(lines(moving.x, moving.width), near.map((other) => lines(other.x, other.width)), tolerance);
+    const dy = axis === 'x' ? 0 : nearest(lines(moving.y, moving.height), near.map((other) => lines(other.y, other.height)), tolerance);
+    const placed = { x: moving.x + dx, y: moving.y + dy, width: moving.width, height: moving.height };
+    // Lines that already coincide count; a hair of float error must not hide one.
+    const epsilon = Math.min(tolerance, 0.5);
+    const guides = [];
+    const add = (axis, at, from, to) => {
+        const same = guides.find((guide) => guide.axis === axis && Math.abs(guide.at - at) <= epsilon);
+        if (same) {
+            same.from = Math.min(same.from, from);
+            same.to = Math.max(same.to, to);
+        }
+        else
+            guides.push({ axis, at, from, to });
+    };
+    const ownX = lines(placed.x, placed.width);
+    const ownY = lines(placed.y, placed.height);
+    /** The lines of `theirs` that `own` sits on — without the middle when both edges match too,
+     *  since a box the same size as its neighbour would otherwise draw three parallel lines. */
+    const matched = (own, theirs) => {
+        const hits = theirs.map((at) => own.some((have) => Math.abs(have - at) <= epsilon));
+        return theirs.filter((_, index) => hits[index] && !(index === 1 && hits[0] && hits[2]));
+    };
+    for (const other of near) {
+        if (axis !== 'y')
+            for (const at of matched(ownX, lines(other.x, other.width))) {
+                add('x', at, Math.min(placed.y, other.y), Math.max(placed.y + placed.height, other.y + other.height));
+            }
+        if (axis !== 'x')
+            for (const at of matched(ownY, lines(other.y, other.height))) {
+                add('y', at, Math.min(placed.x, other.x), Math.max(placed.x + placed.width, other.x + other.width));
+            }
+    }
+    if (guides.length === 0 && dx === 0 && dy === 0)
+        return NONE;
+    return { dx, dy, guides };
+}
+/** The box around several — what a multi-selection drags as one. `null` for none. */
+export function unionBounds(boxes) {
+    if (boxes.length === 0)
+        return null;
+    let left = Number.POSITIVE_INFINITY;
+    let top = Number.POSITIVE_INFINITY;
+    let right = Number.NEGATIVE_INFINITY;
+    let bottom = Number.NEGATIVE_INFINITY;
+    for (const box of boxes) {
+        left = Math.min(left, box.x);
+        top = Math.min(top, box.y);
+        right = Math.max(right, box.x + box.width);
+        bottom = Math.max(bottom, box.y + box.height);
+    }
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/**
+ * Snapping is suspended while ⌘ (or Ctrl) is held — Figma's convention, so an item can still be
+ * put a few pixels off a line on purpose. Read from the drag's own pointer event.
+ */
+export function snapSuspended(event) {
+    return !!(event?.metaKey || event?.ctrlKey);
+}
+//# sourceMappingURL=alignment.js.map

package/dist/react/canvas-hud/alignment.js.map

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

package/dist/react/canvas-hud/index.d.ts

@@ -1,3 +1,7 @@
+export type { AlignmentGuide, AlignmentSnap } from './alignment.js';
+export { ALIGNMENT_TOLERANCE, snapSuspended, snapToAlignment, unionBounds } from './alignment.js';
+export type { AlignmentGuidesProps } from './AlignmentGuides.js';
+export { AlignmentGuides, useSnapSuspended } from './AlignmentGuides.js';
 export type { CanvasMinimapProps } from './CanvasMinimap.js';
 export { CanvasMinimap } from './CanvasMinimap.js';
 export type { CanvasNodeMenuItem, CanvasNodeMenuProps, CanvasNodeMenuSection } from './CanvasNodeMenu.js';

package/dist/react/canvas-hud/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/canvas-hud/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC1G,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAClF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,aAAa,EACb,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,eAAe,EACf,aAAa,EACb,aAAa,EACb,eAAe,EACf,MAAM,GACP,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/canvas-hud/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClG,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACzE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC1G,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAClF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,aAAa,EACb,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,eAAe,EACf,aAAa,EACb,aAAa,EACb,eAAe,EACf,MAAM,GACP,MAAM,eAAe,CAAC"}

package/dist/react/canvas-hud/index.js

@@ -1,3 +1,5 @@
+export { ALIGNMENT_TOLERANCE, snapSuspended, snapToAlignment, unionBounds } from './alignment.js';
+export { AlignmentGuides, useSnapSuspended } from './AlignmentGuides.js';
 export { CanvasMinimap } from './CanvasMinimap.js';
 export { CanvasNodeMenu } from './CanvasNodeMenu.js';
 export { CanvasSearchField } from './CanvasSearchField.js';

package/dist/react/canvas-hud/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/canvas-hud/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAUlF,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,eAAe,EACf,aAAa,EACb,aAAa,EACb,eAAe,EACf,MAAM,GACP,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/canvas-hud/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAUlF,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,eAAe,EACf,aAAa,EACb,aAAa,EACb,eAAe,EACf,MAAM,GACP,MAAM,eAAe,CAAC"}

package/dist/styles-areas/canvas-hud.css

@@ -18,7 +18,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 40 candidate(s).
+ * 42 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -29,4 +29,5 @@
 @source inline("[scrollbar-width:none] aria-pressed:bg-muted aria-pressed:text-foreground basis-0 basis-full");
 @source inline("bg-background/40 bg-background/70 bottom-3 bottom-4 focus-visible:border-transparent");
 @source inline("focus-visible:ring-0 left-3 max-w-48 min-w-10 min-w-26 min-w-40 ml-2 opacity-100 order-1 order-2");
-@source inline("order-3 pb-1.5 pl-0 pl-1 place-items-center pr-1 pt-1 px-0.5 right-3 right-4 w-40 w-64");
+@source inline("order-3 overflow-visible pb-1.5 pl-0 pl-1 place-items-center pr-1 pt-1 px-0.5 right-3 right-4");
+@source inline("w-40 w-64 z-[5000]");

package/dist/styles-utilities.css

@@ -360,6 +360,9 @@
   .z-\[9\] {
     z-index: 9;
   }
+  .z-\[5000\] {
+    z-index: 5000;
+  }
   .z-\[var\(--z-popover\)\] {
     z-index: var(--z-popover);
   }
@@ -1579,6 +1582,9 @@
   .overflow-hidden {
     overflow: hidden;
   }
+  .overflow-visible {
+    overflow: visible;
+  }
   .overflow-x-auto {
     overflow-x: auto;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.81.2",
+	"version": "5.82.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",

package/src/react/canvas-hud/AlignmentGuides.tsx

@@ -0,0 +1,94 @@
+import { type RefObject, useEffect, useRef } from 'react';
+import { type AlignmentGuide, snapSuspended } from './alignment.js';
+
+export interface AlignmentGuidesProps {
+  /** What `snapToAlignment` returned for the drag in progress; empty draws nothing. */
+  guides: readonly AlignmentGuide[];
+  /** The view's scale, so each line stays one screen pixel wide at every zoom. */
+  scale: number;
+}
+
+/**
+ * CNV-12's lines — Mural's thin accent hairlines, drawn while an item is dragged and gone the moment
+ * it is let go. Place it INSIDE the canvas's transformed stage (React Flow's `ViewportPortal`, or the
+ * element a canvas puts `translate(x, y) scale(k)` on): it draws in world units from the stage's
+ * origin, so it pans and zooms with the content and never needs the view's offset.
+ *
+ * `aria-hidden` and `pointer-events: none`: the lines are a hint about where the item will land,
+ * which the item itself already shows; they must never take a pointer from the item underneath.
+ */
+export function AlignmentGuides({ guides, scale }: AlignmentGuidesProps) {
+  if (guides.length === 0 || !(scale > 0)) return null;
+  const width = 1 / scale;
+  return (
+    <svg
+      data-testid='canvas-alignment-guides'
+      aria-hidden='true'
+      width={1}
+      height={1}
+      // At the stage's origin, above the items it is drawn among (React Flow's nodes reach z ~2000).
+      className='pointer-events-none absolute top-0 left-0 z-[5000] overflow-visible'
+    >
+      {guides.map((guide) =>
+        guide.axis === 'x' ? (
+          <line
+            key={`x${guide.at}`}
+            data-guide='x'
+            x1={guide.at}
+            x2={guide.at}
+            y1={guide.from}
+            y2={guide.to}
+            stroke='var(--accent)'
+            strokeOpacity={0.85}
+            strokeWidth={width}
+            shapeRendering='crispEdges'
+          />
+        ) : (
+          <line
+            key={`y${guide.at}`}
+            data-guide='y'
+            x1={guide.from}
+            x2={guide.to}
+            y1={guide.at}
+            y2={guide.at}
+            stroke='var(--accent)'
+            strokeOpacity={0.85}
+            strokeWidth={width}
+            shapeRendering='crispEdges'
+          />
+        ),
+      )}
+    </svg>
+  );
+}
+
+/**
+ * Whether ⌘ or Ctrl is held right now — CNV-12's way to drag an item off the lines. A ref, not
+ * state: React Flow reports a drag as a stream of changes with no pointer event on them, so the
+ * canvas reads this inside its change handler, between renders. Kept current from the pointer's
+ * own moves and from the keys, so pressing ⌘ mid-drag takes effect on the next move.
+ */
+export function useSnapSuspended(): RefObject<boolean> {
+  const held = useRef(false);
+  useEffect(() => {
+    const read = (event: KeyboardEvent | PointerEvent) => {
+      held.current = snapSuspended(event);
+    };
+    const clear = () => {
+      held.current = false;
+    };
+    window.addEventListener('keydown', read, true);
+    window.addEventListener('keyup', read, true);
+    window.addEventListener('pointermove', read, true);
+    window.addEventListener('pointerdown', read, true);
+    window.addEventListener('blur', clear);
+    return () => {
+      window.removeEventListener('keydown', read, true);
+      window.removeEventListener('keyup', read, true);
+      window.removeEventListener('pointermove', read, true);
+      window.removeEventListener('pointerdown', read, true);
+      window.removeEventListener('blur', clear);
+    };
+  }, []);
+  return held;
+}

package/src/react/canvas-hud/alignment.spec.tsx

@@ -0,0 +1,149 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render } from '@testing-library/react';
+import { snapSuspended, snapToAlignment, unionBounds } from './alignment.js';
+import { AlignmentGuides, useSnapSuspended } from './AlignmentGuides.js';
+
+afterEach(cleanup);
+
+const box = (x: number, y: number, width = 100, height = 50) => ({ x, y, width, height });
+
+describe('snapToAlignment (CNV-12: alignment guides while dragging)', () => {
+  test('a left edge within tolerance settles onto its neighbour’s, and one vertical guide spans both', () => {
+    const snap = snapToAlignment(box(203, 200, 60, 30), [box(200, 0)], 6);
+    expect(snap.dx).toBe(-3);
+    expect(snap.dy).toBe(0);
+    expect(snap.guides).toEqual([{ axis: 'x', at: 200, from: 0, to: 230 }]);
+  });
+
+  test('a box the same size as its neighbour draws its two edges, not a third line down the middle', () => {
+    const snap = snapToAlignment(box(203, 200), [box(200, 0)], 6);
+    expect(snap.guides).toEqual([
+      { axis: 'x', at: 200, from: 0, to: 250 },
+      { axis: 'x', at: 300, from: 0, to: 250 },
+    ]);
+  });
+
+  test('outside the tolerance nothing moves and nothing is drawn', () => {
+    expect(snapToAlignment(box(207, 400), [box(200, 0)], 6)).toEqual({ dx: 0, dy: 0, guides: [] });
+  });
+
+  test('middles line up with middles, and an edge with a middle of another size', () => {
+    // The moving box's middle (54 + 46 = 100) already sits on the other's (50 + 50): no move beats
+    // the left edges' 4, and the middle guide is drawn.
+    const centred = snapToAlignment(box(54, 300, 92, 20), [box(50, 0, 100, 50)], 6);
+    expect(centred.dx).toBe(0);
+    expect(centred.guides.some((g) => g.axis === 'x' && g.at === 100)).toBe(true);
+    const edgeToMiddle = snapToAlignment(box(97, 300, 40, 20), [box(0, 0, 200, 50)], 6);
+    expect(edgeToMiddle.dx).toBe(3);
+    expect(edgeToMiddle.guides).toContainEqual({ axis: 'x', at: 100, from: 0, to: 320 });
+  });
+
+  test('each axis snaps on its own, so a corner can settle on two lines at once', () => {
+    const snap = snapToAlignment(box(502, 104, 40, 30), [box(500, 0), box(0, 100)], 6);
+    expect(snap.dx).toBe(-2);
+    expect(snap.dy).toBe(-4);
+    expect(snap.guides.map((g) => `${g.axis}${g.at}`).sort()).toEqual(['x500', 'y100']);
+  });
+
+  test('the nearest line wins, not the first one found', () => {
+    const snap = snapToAlignment(box(105, 400), [box(100, 0), box(104, 200)], 6);
+    expect(snap.dx).toBe(-1);
+  });
+
+  test('three items on one line draw ONE guide through all of them', () => {
+    const snap = snapToAlignment(box(301, 500, 40, 20), [box(300, 0), box(300, 200)], 6);
+    const vertical = snap.guides.filter((g) => g.axis === 'x' && g.at === 300);
+    expect(vertical).toEqual([{ axis: 'x', at: 300, from: 0, to: 520 }]);
+  });
+
+  test('a right edge snaps to a right edge, and the guide sits on that edge', () => {
+    const snap = snapToAlignment(box(0, 200, 98, 30), [box(0, 0, 100, 50)], 6);
+    // left edges already coincide (0 = 0), so no move — and both the left guide and the right are honest
+    expect(snap.dx).toBe(0);
+    const shifted = snapToAlignment(box(20, 200, 78, 30), [box(0, 0, 100, 50)], 6);
+    expect(shifted.dx).toBe(2);
+    expect(shifted.guides).toContainEqual({ axis: 'x', at: 100, from: 0, to: 230 });
+  });
+
+  test("axis 'x' snaps and draws only vertical lines — a row of cards does not draw a line along the row", () => {
+    // Same row (y 0) as the neighbour, left edge 2 off: settles sideways, and no horizontal line is drawn.
+    const sideways = snapToAlignment(box(202, 0, 60, 50), [box(200, 0)], 6, 'x');
+    expect(sideways.dx).toBe(-2);
+    expect(sideways.dy).toBe(0);
+    expect(sideways.guides.every((g) => g.axis === 'x')).toBe(true);
+    expect(snapToAlignment(box(500, 3, 60, 50), [box(0, 0)], 6, 'x')).toEqual({ dx: 0, dy: 0, guides: [] });
+    expect(snapToAlignment(box(500, 3, 60, 50), [box(0, 0)], 6, 'y').dy).toBe(-3);
+  });
+
+  test('no neighbours, or a zero tolerance (⌘ held), is a plain drag', () => {
+    expect(snapToAlignment(box(3, 3), [], 6)).toEqual({ dx: 0, dy: 0, guides: [] });
+    expect(snapToAlignment(box(203, 3), [box(200, 0)], 0)).toEqual({ dx: 0, dy: 0, guides: [] });
+  });
+});
+
+describe('unionBounds', () => {
+  test('the box around a multi-selection', () => {
+    expect(unionBounds([box(10, 20, 30, 40), box(-5, 50, 10, 10)])).toEqual({ x: -5, y: 20, width: 45, height: 40 });
+    expect(unionBounds([])).toBeNull();
+  });
+});
+
+describe('snapSuspended', () => {
+  test('⌘ or Ctrl suspends snapping; nothing held does not', () => {
+    expect(snapSuspended({ metaKey: true })).toBe(true);
+    expect(snapSuspended({ ctrlKey: true })).toBe(true);
+    expect(snapSuspended({ metaKey: false, ctrlKey: false })).toBe(false);
+    expect(snapSuspended(null)).toBe(false);
+  });
+});
+
+describe('AlignmentGuides', () => {
+  test('draws one hairline per guide, one screen pixel wide at the view’s scale, and takes no pointer', () => {
+    const { getByTestId } = render(
+      <AlignmentGuides
+        scale={2}
+        guides={[
+          { axis: 'x', at: 10, from: 0, to: 90 },
+          { axis: 'y', at: 40, from: -5, to: 60 },
+        ]}
+      />,
+    );
+    const svg = getByTestId('canvas-alignment-guides');
+    expect(svg.getAttribute('aria-hidden')).toBe('true');
+    expect(svg.getAttribute('class')).toContain('pointer-events-none');
+    const [vertical, horizontal] = Array.from(svg.querySelectorAll('line'));
+    expect([vertical.getAttribute('x1'), vertical.getAttribute('x2'), vertical.getAttribute('y1'), vertical.getAttribute('y2')]).toEqual(['10', '10', '0', '90']);
+    expect([horizontal.getAttribute('y1'), horizontal.getAttribute('x1'), horizontal.getAttribute('x2')]).toEqual(['40', '-5', '60']);
+    expect(vertical.getAttribute('stroke-width')).toBe('0.5');
+  });
+
+  test('nothing to draw renders nothing', () => {
+    const { queryByTestId } = render(<AlignmentGuides scale={1} guides={[]} />);
+    expect(queryByTestId('canvas-alignment-guides')).toBeNull();
+  });
+});
+
+describe('useSnapSuspended', () => {
+  test('follows ⌘ down and up, and lets go when the window loses focus', () => {
+    let held: { current: boolean | null } = { current: null };
+    function Probe() {
+      held = useSnapSuspended();
+      return null;
+    }
+    render(<Probe />);
+    expect(held.current).toBe(false);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Meta', metaKey: true }));
+    });
+    expect(held.current).toBe(true);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keyup', { key: 'Meta', metaKey: false }));
+    });
+    expect(held.current).toBe(false);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Control', ctrlKey: true }));
+      window.dispatchEvent(new Event('blur'));
+    });
+    expect(held.current).toBe(false);
+  });
+});

package/src/react/canvas-hud/alignment.ts

@@ -0,0 +1,143 @@
+/**
+ * CNV-12 — alignment guides while dragging (forge task 3437). The owner asked for Mural's lines: as
+ * an item is dragged, a hairline shows when one of its edges or its middle lines up with another
+ * item's, and the item settles onto that line. Figma, Miro and Mural all draw the same thing.
+ *
+ * Pure — no React, no DOM — so a canvas built on React Flow (desk, arch) and one built on its own
+ * stage use the same rule, pinned by `alignment.spec.tsx`. Everything is in WORLD units; the caller
+ * turns its screen tolerance into world units by dividing by the view's scale, so the pull feels the
+ * same at every zoom.
+ */
+import type { CanvasBounds } from './viewport.js';
+
+/** How close, in SCREEN pixels, an edge or a middle must come to another's before it snaps. */
+export const ALIGNMENT_TOLERANCE = 6;
+
+/**
+ * One line to draw. `axis: 'x'` is a VERTICAL line at `x = at`, running from `y = from` to
+ * `y = to`; `axis: 'y'` is a horizontal one at `y = at`, running along x.
+ */
+export interface AlignmentGuide {
+  axis: 'x' | 'y';
+  at: number;
+  from: number;
+  to: number;
+}
+
+export interface AlignmentSnap {
+  /** What to add to the dragged item's position so it sits on the nearest line — 0 when none is near. */
+  dx: number;
+  dy: number;
+  /** Every line the item rests on AFTER the snap, merged per position, spanning every item it meets. */
+  guides: AlignmentGuide[];
+}
+
+const NONE: AlignmentSnap = { dx: 0, dy: 0, guides: [] };
+
+/** Start, middle, end — the three lines of a box along one axis. */
+function lines(start: number, size: number): [number, number, number] {
+  return [start, start + size / 2, start + size];
+}
+
+/** The smallest move along one axis that puts any of `moving`'s lines on any of `targets`' lines. */
+function nearest(moving: readonly number[], targets: readonly (readonly number[])[], tolerance: number): number {
+  let best = Number.POSITIVE_INFINITY;
+  for (const target of targets) {
+    for (const want of target) {
+      for (const have of moving) {
+        const delta = want - have;
+        if (Math.abs(delta) <= tolerance && Math.abs(delta) < Math.abs(best)) best = delta;
+      }
+    }
+  }
+  return Number.isFinite(best) ? best : 0;
+}
+
+/**
+ * Where `moving` should settle, and the guides to draw there. `others` is every item it may line up
+ * with — never the item itself, nor anything travelling with it (a multi-selection, a group's
+ * contents). `tolerance` is in world units: `ALIGNMENT_TOLERANCE / view.scale`.
+ *
+ * Each axis snaps on its own, to the closest line within tolerance, so an item can settle on a
+ * vertical and a horizontal guide at once. A guide is drawn for every line that matches after the
+ * snap — two neighbours sharing a left edge make one line through all three — and runs from the
+ * farthest item it touches to the farthest on the other side, the way Mural draws it.
+ *
+ * `axis` limits it to one direction for an item that only moves one way — family's lineages slide
+ * sideways and never change row, so `'x'` (vertical lines only): a row of cards would otherwise draw
+ * a horizontal line along every generation.
+ */
+export function snapToAlignment(
+  moving: CanvasBounds,
+  others: readonly CanvasBounds[],
+  tolerance: number,
+  axis: 'x' | 'y' | 'both' = 'both',
+): AlignmentSnap {
+  if (others.length === 0 || !(tolerance > 0)) return NONE;
+  const near = others.filter(
+    (other) => other.width >= 0 && other.height >= 0 && Number.isFinite(other.x) && Number.isFinite(other.y),
+  );
+  const dx = axis === 'y' ? 0 : nearest(
+    lines(moving.x, moving.width),
+    near.map((other) => lines(other.x, other.width)),
+    tolerance,
+  );
+  const dy = axis === 'x' ? 0 : nearest(
+    lines(moving.y, moving.height),
+    near.map((other) => lines(other.y, other.height)),
+    tolerance,
+  );
+  const placed = { x: moving.x + dx, y: moving.y + dy, width: moving.width, height: moving.height };
+  // Lines that already coincide count; a hair of float error must not hide one.
+  const epsilon = Math.min(tolerance, 0.5);
+  const guides: AlignmentGuide[] = [];
+  const add = (axis: 'x' | 'y', at: number, from: number, to: number) => {
+    const same = guides.find((guide) => guide.axis === axis && Math.abs(guide.at - at) <= epsilon);
+    if (same) {
+      same.from = Math.min(same.from, from);
+      same.to = Math.max(same.to, to);
+    } else guides.push({ axis, at, from, to });
+  };
+  const ownX = lines(placed.x, placed.width);
+  const ownY = lines(placed.y, placed.height);
+  /** The lines of `theirs` that `own` sits on — without the middle when both edges match too,
+   *  since a box the same size as its neighbour would otherwise draw three parallel lines. */
+  const matched = (own: readonly number[], theirs: readonly number[]) => {
+    const hits = theirs.map((at) => own.some((have) => Math.abs(have - at) <= epsilon));
+    return theirs.filter((_, index) => hits[index] && !(index === 1 && hits[0] && hits[2]));
+  };
+  for (const other of near) {
+    if (axis !== 'y') for (const at of matched(ownX, lines(other.x, other.width))) {
+      add('x', at, Math.min(placed.y, other.y), Math.max(placed.y + placed.height, other.y + other.height));
+    }
+    if (axis !== 'x') for (const at of matched(ownY, lines(other.y, other.height))) {
+      add('y', at, Math.min(placed.x, other.x), Math.max(placed.x + placed.width, other.x + other.width));
+    }
+  }
+  if (guides.length === 0 && dx === 0 && dy === 0) return NONE;
+  return { dx, dy, guides };
+}
+
+/** The box around several — what a multi-selection drags as one. `null` for none. */
+export function unionBounds(boxes: readonly CanvasBounds[]): CanvasBounds | null {
+  if (boxes.length === 0) return null;
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const box of boxes) {
+    left = Math.min(left, box.x);
+    top = Math.min(top, box.y);
+    right = Math.max(right, box.x + box.width);
+    bottom = Math.max(bottom, box.y + box.height);
+  }
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/**
+ * Snapping is suspended while ⌘ (or Ctrl) is held — Figma's convention, so an item can still be
+ * put a few pixels off a line on purpose. Read from the drag's own pointer event.
+ */
+export function snapSuspended(event: { metaKey?: boolean; ctrlKey?: boolean } | null | undefined): boolean {
+  return !!(event?.metaKey || event?.ctrlKey);
+}

package/src/react/canvas-hud/index.ts

@@ -1,6 +1,11 @@
 // cursedbelt/react/canvas-hud — the viewport arithmetic and the floating chrome every pan-and-zoom
-// canvas carries (docs/design/canvas.md, CNV-1…CNV-5; forge task 2401). Its own subpath, so a
+// canvas carries (docs/design/canvas.md, CNV-1…CNV-5; forge task 2401), and CNV-12's alignment
+// guides while an item is dragged (forge task 3437). Its own subpath, so a
 // page with no canvas never pulls it in.
+export type { AlignmentGuide, AlignmentSnap } from './alignment.js';
+export { ALIGNMENT_TOLERANCE, snapSuspended, snapToAlignment, unionBounds } from './alignment.js';
+export type { AlignmentGuidesProps } from './AlignmentGuides.js';
+export { AlignmentGuides, useSnapSuspended } from './AlignmentGuides.js';
 export type { CanvasMinimapProps } from './CanvasMinimap.js';
 export { CanvasMinimap } from './CanvasMinimap.js';
 export type { CanvasNodeMenuItem, CanvasNodeMenuProps, CanvasNodeMenuSection } from './CanvasNodeMenu.js';

package/src/styles-areas/canvas-hud.css

@@ -18,7 +18,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 40 candidate(s).
+ * 42 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -29,4 +29,5 @@
 @source inline("[scrollbar-width:none] aria-pressed:bg-muted aria-pressed:text-foreground basis-0 basis-full");
 @source inline("bg-background/40 bg-background/70 bottom-3 bottom-4 focus-visible:border-transparent");
 @source inline("focus-visible:ring-0 left-3 max-w-48 min-w-10 min-w-26 min-w-40 ml-2 opacity-100 order-1 order-2");
-@source inline("order-3 pb-1.5 pl-0 pl-1 place-items-center pr-1 pt-1 px-0.5 right-3 right-4 w-40 w-64");
+@source inline("order-3 overflow-visible pb-1.5 pl-0 pl-1 place-items-center pr-1 pt-1 px-0.5 right-3 right-4");
+@source inline("w-40 w-64 z-[5000]");

package/src/styles-utilities.css

@@ -360,6 +360,9 @@
   .z-\[9\] {
     z-index: 9;
   }
+  .z-\[5000\] {
+    z-index: 5000;
+  }
   .z-\[var\(--z-popover\)\] {
     z-index: var(--z-popover);
   }
@@ -1579,6 +1582,9 @@
   .overflow-hidden {
     overflow: hidden;
   }
+  .overflow-visible {
+    overflow: visible;
+  }
   .overflow-x-auto {
     overflow-x: auto;
   }