@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/craft/TransformBox.svelte

@@ -0,0 +1,254 @@
+<!--
+  widgets/craft/TransformBox.svelte
+  The selection box of a craft editor: a bounding box with 8 resize handles
+  over one selected object. Render it in CanvasViewport's `overlay` snippet:
+  `rect` is in DOCUMENT units and `zoom` / `panX` / `panY` are the viewport
+  transform the snippet hands over, so the box and its 8 px handles are drawn
+  in screen px and stay the same size at any zoom.
+
+  - Drag the box to move, a handle to resize (maths in transform-math.ts).
+    `aspect` locks the ratio; Shift flips the lock for that drag. `bounds`
+    keeps a move inside the page. `resize="none"` keeps only the move,
+    `movable={false}` only the handles, `locked` neither (dashed, no handles).
+  - Keys on the focused box: arrows move by `step` (Shift: `bigStep`),
+    Alt + arrows resize from the far corner, Delete / Backspace call
+    `ondelete`, Esc cancels a drag in progress. Handled keys never bubble, so
+    an editor's arrow shortcuts (page turns) do not fire under a selection.
+  - `onpreview` follows every step of a drag or nudge; `oncommit(rect, kind)`
+    fires once: on pointer up (if it moved) or 400 ms after a burst of keys.
+    The committed rect stays on screen until the host's `rect` catches up.
+  - Pointer listeners are native and stop propagation: CanvasViewport listens
+    natively on its stage, so a delegated handler here would run after it.
+  The box is a tab stop (role="group", aria-roledescription "selection");
+  the handles are pointer-only, Alt + arrows is their keyboard path.
+  Tokens only, no colour literals.
+-->
+<script lang="ts">
+  import { cn } from '../../utils.js';
+  import type { CanvasRect, TransformHandle, TransformKind } from './types.js';
+  import { keyRect, moveRect, resizeRect } from './transform-math.js';
+
+  interface Props {
+    rect: CanvasRect;
+    zoom: number;
+    panX: number;
+    panY: number;
+    /** Lock the width:height ratio while resizing (Shift flips it). */
+    aspect?: boolean;
+    resize?: 'all' | 'none';
+    movable?: boolean;
+    locked?: boolean;
+    /** Smallest width / height in document units. */
+    minSize?: number;
+    /** Keep a move inside this rect (document units), e.g. the page. */
+    bounds?: CanvasRect | null;
+    step?: number;
+    bigStep?: number;
+    /** What is selected, for its accessible name ("Signature"). */
+    label?: string;
+    /** Take focus when shown, so the arrow keys reach it. */
+    autofocus?: boolean;
+    onpreview?: (rect: CanvasRect) => void;
+    oncommit?: (rect: CanvasRect, kind: TransformKind) => void;
+    ondelete?: () => void;
+    class?: string;
+  }
+
+  let {
+    rect,
+    zoom,
+    panX,
+    panY,
+    aspect = false,
+    resize = 'all',
+    movable = true,
+    locked = false,
+    minSize = 4,
+    bounds = null,
+    step = 1,
+    bigStep = 10,
+    label = 'Selection',
+    autofocus = false,
+    onpreview,
+    oncommit,
+    ondelete,
+    class: className,
+  }: Props = $props();
+
+  const HANDLES: TransformHandle[] = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'];
+  const CURSOR: Record<TransformHandle, string> = { nw: 'nwse', se: 'nwse', ne: 'nesw', sw: 'nesw', n: 'ns', s: 'ns', e: 'ew', w: 'ew' };
+  const NUDGE_MS = 400;
+  const HOLD_MS = 1500;
+
+  /** The rect being dragged or nudged (null when idle). */
+  let draft = $state<CanvasRect | null>(null);
+  /** A committed rect shown until the host's `rect` moves off `from` (or HOLD_MS passes). */
+  let held = $state<{ from: CanvasRect; r: CanvasRect } | null>(null);
+  let drag: { kind: 'move' | 'resize'; h?: TransformHandle; sx: number; sy: number; start: CanvasRect } | null = null;
+  let nudgeTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Where a burst of arrow keys started (the commit compares against it). */
+  let nudgeOrigin: CanvasRect | null = null;
+  let holdTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const same = (a: CanvasRect, b: CanvasRect) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+  const shown = $derived(draft ?? (held && same(held.from, rect) ? held.r : rect));
+  const box = $derived({ left: panX + shown.x * zoom, top: panY + shown.y * zoom, width: shown.width * zoom, height: shown.height * zoom });
+  const handles = $derived(locked || resize === 'none' ? [] : HANDLES);
+
+  function commit(r: CanvasRect, kind: TransformKind, from: CanvasRect) {
+    if (same(r, from)) return;
+    held = { from: rect, r };
+    clearTimeout(holdTimer);
+    holdTimer = setTimeout(() => (held = null), HOLD_MS);
+    oncommit?.(r, kind);
+  }
+
+  /** Start a pointer drag on `node` (the box or a handle); moves and the release come back to it (pointer capture). */
+  function begin(e: PointerEvent, node: HTMLElement, kind: 'move' | 'resize', h?: TransformHandle) {
+    if (e.button !== 0) return;
+    e.stopPropagation();
+    e.preventDefault();
+    root?.focus({ preventScroll: true });
+    if (locked || (kind === 'move' && !movable)) return;
+    node.setPointerCapture?.(e.pointerId);
+    const start = shown;
+    drag = { kind, h, sx: e.clientX, sy: e.clientY, start };
+    const move = (ev: PointerEvent) => {
+      ev.stopPropagation();
+      if (!drag) return;
+      const dx = (ev.clientX - drag.sx) / zoom;
+      const dy = (ev.clientY - drag.sy) / zoom;
+      draft = drag.kind === 'move' ? moveRect(drag.start, dx, dy, bounds) : resizeRect(drag.start, drag.h!, dx, dy, { aspect: aspect !== ev.shiftKey, min: minSize });
+      onpreview?.(draft);
+    };
+    const end = (ev: PointerEvent) => {
+      ev.stopPropagation();
+      node.releasePointerCapture?.(ev.pointerId);
+      node.removeEventListener('pointermove', move);
+      node.removeEventListener('pointerup', end);
+      node.removeEventListener('pointercancel', end);
+      const d = draft;
+      const k = drag?.kind;
+      drag = null;
+      draft = null;
+      if (d && k && ev.type === 'pointerup') commit(d, k, start);
+    };
+    node.addEventListener('pointermove', move);
+    node.addEventListener('pointerup', end);
+    node.addEventListener('pointercancel', end);
+  }
+
+  function onkey(e: KeyboardEvent) {
+    if (e.key === 'Escape' && drag) {
+      drag = null;
+      draft = null;
+    } else if ((e.key === 'Delete' || e.key === 'Backspace') && ondelete && !locked) {
+      ondelete();
+    } else {
+      if (drag || locked || (e.altKey ? resize === 'none' : !movable)) return;
+      const base = draft ?? shown;
+      const next = keyRect(base, e.key, { shift: e.shiftKey, alt: e.altKey, aspect, step, bigStep, min: minSize, bounds });
+      if (!next) return;
+      nudgeOrigin ??= base;
+      draft = next;
+      onpreview?.(next);
+      clearTimeout(nudgeTimer);
+      nudgeTimer = setTimeout(() => {
+        const [d, from] = [draft, nudgeOrigin];
+        draft = null;
+        nudgeOrigin = null;
+        if (d && from) commit(d, 'nudge', from);
+      }, NUDGE_MS);
+    }
+    e.preventDefault();
+    e.stopPropagation();
+  }
+
+  let root = $state<HTMLDivElement | null>(null);
+
+  /** Native listeners on the box (not delegated: see the header), and focus on mount when asked. */
+  function boxInput(node: HTMLDivElement) {
+    const down = (e: PointerEvent) => begin(e, node, 'move');
+    node.addEventListener('pointerdown', down);
+    node.addEventListener('keydown', onkey);
+    if (autofocus) node.focus({ preventScroll: true });
+    return () => {
+      node.removeEventListener('pointerdown', down);
+      node.removeEventListener('keydown', onkey);
+      clearTimeout(nudgeTimer);
+      clearTimeout(holdTimer);
+    };
+  }
+  const handleInput = (h: TransformHandle) => (node: HTMLDivElement) => {
+    const down = (e: PointerEvent) => begin(e, node, 'resize', h);
+    node.addEventListener('pointerdown', down);
+    return () => node.removeEventListener('pointerdown', down);
+  };
+
+  // Spread, not attributes: svelte's a11y lint flags tabindex on role="group", yet a focusable box is the keyboard path.
+  const TAB_STOP = { tabindex: 0 };
+  const size = $derived(`${Math.round(shown.width)} by ${Math.round(shown.height)}`);
+</script>
+
+<div
+  bind:this={root}
+  {@attach boxInput}
+  data-slot="transform-box"
+  data-locked={locked ? 'true' : undefined}
+  role="group"
+  aria-roledescription="selection"
+  aria-label="{label}, {size}{locked ? ', locked' : ''}"
+  title={locked ? `${label} (locked)` : 'Drag to move. Arrow keys nudge (Shift: 10), Alt + arrows resize, Delete removes.'}
+  {...TAB_STOP}
+  class={cn('craft-transform', locked && 'locked', !locked && movable && 'movable', className)}
+  style:left="{box.left}px"
+  style:top="{box.top}px"
+  style:width="{box.width}px"
+  style:height="{box.height}px"
+>
+  {#each handles as h (h)}
+    <div
+      {@attach handleInput(h)}
+      data-slot="transform-handle"
+      data-handle={h}
+      aria-hidden="true"
+      class="craft-handle"
+      style:left="{h.includes('w') ? 0 : h.includes('e') ? 100 : 50}%"
+      style:top="{h.includes('n') ? 0 : h.includes('s') ? 100 : 50}%"
+      style:cursor="{CURSOR[h]}-resize"
+    ></div>
+  {/each}
+</div>
+
+<style>
+  .craft-transform {
+    position: absolute;
+    pointer-events: auto;
+    box-shadow: 0 0 0 1px var(--ripple-accent);
+    outline: none;
+    touch-action: none;
+  }
+  .craft-transform.movable {
+    cursor: move;
+  }
+  .craft-transform:focus-visible {
+    box-shadow:
+      0 0 0 1px var(--ripple-accent),
+      0 0 0 3px color-mix(in oklab, var(--ripple-accent) 35%, transparent);
+  }
+  .craft-transform.locked {
+    box-shadow: none;
+    outline: 1px dashed var(--ripple-muted-foreground);
+    cursor: default;
+  }
+  .craft-handle {
+    position: absolute;
+    width: 8px;
+    height: 8px;
+    margin: -4px 0 0 -4px;
+    border-radius: 2px;
+    background: var(--ripple-surface);
+    box-shadow: 0 0 0 1px var(--ripple-accent);
+    touch-action: none;
+  }
+</style>

package/dist/widgets/craft/TransformBox.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { CanvasRect, TransformKind } from './types.js';
+interface Props {
+    rect: CanvasRect;
+    zoom: number;
+    panX: number;
+    panY: number;
+    /** Lock the width:height ratio while resizing (Shift flips it). */
+    aspect?: boolean;
+    resize?: 'all' | 'none';
+    movable?: boolean;
+    locked?: boolean;
+    /** Smallest width / height in document units. */
+    minSize?: number;
+    /** Keep a move inside this rect (document units), e.g. the page. */
+    bounds?: CanvasRect | null;
+    step?: number;
+    bigStep?: number;
+    /** What is selected, for its accessible name ("Signature"). */
+    label?: string;
+    /** Take focus when shown, so the arrow keys reach it. */
+    autofocus?: boolean;
+    onpreview?: (rect: CanvasRect) => void;
+    oncommit?: (rect: CanvasRect, kind: TransformKind) => void;
+    ondelete?: () => void;
+    class?: string;
+}
+declare const TransformBox: import("svelte").Component<Props, {}, "">;
+type TransformBox = ReturnType<typeof TransformBox>;
+export default TransformBox;

package/dist/widgets/craft/asset-panel.d.ts

@@ -0,0 +1,53 @@
+export declare const ASSET_MIME = "application/x-ripple-asset+json";
+export interface AssetFilter {
+    id: string;
+    label: string;
+}
+export interface AssetTab {
+    id: string;
+    label: string;
+    /** Lucide icon slug for the rail; the `icon` snippet overrides it. */
+    icon?: string;
+    /** Search box placeholder, e.g. "Search templates". */
+    placeholder?: string;
+    /** Filter chips; an item matches a chip when its `tags` include the chip id. */
+    filters?: AssetFilter[];
+    emptyText?: string;
+    /** Show the label under each tile. Default true. */
+    captions?: boolean;
+}
+export interface AssetItem {
+    id: string;
+    label: string;
+    /** Thumbnail URL, lazy-loaded. */
+    thumb?: string;
+    /** Natural size, for the tile's aspect ratio. Square when absent. */
+    width?: number;
+    height?: number;
+    tags?: string[];
+    /** The host's own type ("template", "element", "text-preset", "upload"…). */
+    kind?: string;
+    /** Text drawn in the tile when there is no thumbnail (text presets). */
+    preview?: string;
+    /** Anything the host needs on insert or drop (template id, command args). */
+    data?: unknown;
+}
+/** What a canvas receives from a dropped tile. */
+export interface AssetDrop {
+    tab: string;
+    id: string;
+    label: string;
+    kind?: string;
+    data?: unknown;
+}
+export declare function assetDrop(item: AssetItem, tab: string): AssetDrop;
+/** Write a tile's payload onto a drag. */
+export declare function writeAssetDrag(dt: DataTransfer, item: AssetItem, tab: string): void;
+/** Read a dropped tile, or null when the drop is not an asset (a file, plain text). */
+export declare function readAssetDrop(dt: DataTransfer | null | undefined): AssetDrop | null;
+/** True while a drag carries an asset (dragover can't read the data, only the types). */
+export declare function isAssetDrag(dt: DataTransfer | null | undefined): boolean;
+export declare function filterAssets(items: AssetItem[], query: string, chip: string | null): AssetItem[];
+/** Columns in the tile grid: the browser's resolved tracks, or (when it reports the
+ *  unresolved `repeat(...)`, as jsdom does) what auto-fill fits at this width. */
+export declare function gridColumns(templateColumns: string, width: number, minTile: number, gap?: number): number;

package/dist/widgets/craft/asset-panel.js

@@ -0,0 +1,53 @@
+// widgets/craft/asset-panel.ts
+// The data model of AssetPanel and the drag contract between the panel and a
+// canvas. A dragged tile carries an `AssetDrop` as JSON under ASSET_MIME (plus
+// its label as text/plain); the canvas reads it back with `readAssetDrop`.
+// `filterAssets` is the panel's local search: every query token must appear in
+// the label or a tag, and an active filter chip must be one of the item's tags.
+// `gridColumns` is the column count the grid's Up/Down keys step by.
+export const ASSET_MIME = 'application/x-ripple-asset+json';
+export function assetDrop(item, tab) {
+    return { tab, id: item.id, label: item.label, kind: item.kind, data: item.data };
+}
+/** Write a tile's payload onto a drag. */
+export function writeAssetDrag(dt, item, tab) {
+    dt.setData(ASSET_MIME, JSON.stringify(assetDrop(item, tab)));
+    dt.setData('text/plain', item.label);
+    dt.effectAllowed = 'copy';
+}
+/** Read a dropped tile, or null when the drop is not an asset (a file, plain text). */
+export function readAssetDrop(dt) {
+    const raw = dt?.getData(ASSET_MIME);
+    if (!raw)
+        return null;
+    try {
+        const v = JSON.parse(raw);
+        return v && typeof v.id === 'string' && typeof v.tab === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True while a drag carries an asset (dragover can't read the data, only the types). */
+export function isAssetDrag(dt) {
+    return !!dt && Array.from(dt.types ?? []).includes(ASSET_MIME);
+}
+export function filterAssets(items, query, chip) {
+    const tokens = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    return items.filter((it) => {
+        if (chip && !it.tags?.includes(chip))
+            return false;
+        if (!tokens.length)
+            return true;
+        const hay = [it.label, ...(it.tags ?? [])].join(' ').toLowerCase();
+        return tokens.every((t) => hay.includes(t));
+    });
+}
+/** Columns in the tile grid: the browser's resolved tracks, or (when it reports the
+ *  unresolved `repeat(...)`, as jsdom does) what auto-fill fits at this width. */
+export function gridColumns(templateColumns, width, minTile, gap = 8) {
+    const tracks = templateColumns.trim();
+    if (tracks && !tracks.startsWith('repeat('))
+        return tracks.split(/\s+/).length;
+    return Math.max(1, Math.floor((width + gap) / (minTile + gap)));
+}

package/dist/widgets/craft/page-strip.d.ts

@@ -0,0 +1,12 @@
+export interface PageItem {
+    id: string;
+    /** Accessible name; defaults to "Page N". */
+    label?: string;
+    /** Thumbnail URL (the engine's region render). */
+    thumb?: string;
+    /** Page size, for the thumbnail's aspect ratio. Square when absent. */
+    width?: number;
+    height?: number;
+}
+export declare const PAGE_MIME = "application/x-ripple-page";
+export declare function reorderIndex(from: number, target: number, after: boolean): number | null;

package/dist/widgets/craft/page-strip.js

@@ -0,0 +1,12 @@
+// widgets/craft/page-strip.ts
+// PageStrip's item type and its one piece of arithmetic: where a dragged page
+// lands. Dropping page `from` before or after page `target` gives the index it
+// should hold in the reordered list (the host splices it there), or null for a
+// drop that changes nothing.
+export const PAGE_MIME = 'application/x-ripple-page';
+export function reorderIndex(from, target, after) {
+    let to = target + (after ? 1 : 0);
+    if (from < to)
+        to -= 1;
+    return to === from ? null : to;
+}

package/dist/widgets/craft/ruler-math.d.ts

@@ -0,0 +1,12 @@
+export interface RulerTicks {
+    /** Units between labelled ticks. */
+    step: number;
+    major: {
+        px: number;
+        label: string;
+    }[];
+    minor: number[];
+}
+export declare function niceStep(minUnits: number): number;
+export declare function formatTick(v: number, step: number): string;
+export declare function rulerTicks(length: number, pan: number, pxPerUnit: number, minMajorPx?: number): RulerTicks;

package/dist/widgets/craft/ruler-math.js

@@ -0,0 +1,43 @@
+// widgets/craft/ruler-math.ts
+// Tick layout for CanvasViewport's rulers. A ruler maps screen pixel s to the
+// ruler value (s - pan) / pxPerUnit, where pxPerUnit = zoom * unitSize (screen
+// px per ruler unit; unitSize = document units per ruler unit, e.g. 72 for
+// inches on a points document). The labelled step is the smallest 1/2/5 x 10^k
+// whose spacing is at least `minMajorPx`; minor ticks subdivide it while they
+// stay at least 5 px apart.
+export function niceStep(minUnits) {
+    const p = 10 ** Math.floor(Math.log10(Math.max(minUnits, 1e-9)));
+    for (const m of [1, 2, 5, 10])
+        if (m * p >= minUnits - 1e-12)
+            return m * p;
+    return 10 * p;
+}
+export function formatTick(v, step) {
+    const decimals = Math.max(0, -Math.floor(Math.log10(step) + 1e-9));
+    const n = +v.toFixed(decimals);
+    return String(n === 0 ? 0 : n);
+}
+export function rulerTicks(length, pan, pxPerUnit, minMajorPx = 64) {
+    const ppu = Math.max(pxPerUnit, 1e-9);
+    const step = niceStep(minMajorPx / ppu);
+    const lead = Math.round(step / 10 ** Math.floor(Math.log10(step) + 1e-9));
+    const divs = (lead === 2 ? [4, 2] : lead === 5 ? [5] : [10, 5, 2]).find((d) => (step * ppu) / d >= 5) ?? 1;
+    const start = (0 - pan) / ppu;
+    const end = (length - pan) / ppu;
+    const major = [];
+    const minor = [];
+    const first = Math.floor(start / step);
+    const last = Math.ceil(end / step);
+    for (let i = first; i <= last && major.length < 500; i++) {
+        const v = i * step;
+        const px = pan + v * ppu;
+        if (px >= -1 && px <= length + 1)
+            major.push({ px, label: formatTick(v, step) });
+        for (let j = 1; j < divs; j++) {
+            const mpx = pan + (v + (step * j) / divs) * ppu;
+            if (mpx >= 0 && mpx <= length)
+                minor.push(mpx);
+        }
+    }
+    return { step, major, minor };
+}

package/dist/widgets/craft/toolbar-math.d.ts

@@ -0,0 +1,19 @@
+import type { ScreenRect } from './types.js';
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface ToolbarPlacement {
+    x: number;
+    y: number;
+    side: 'top' | 'bottom';
+    hidden: boolean;
+}
+export interface PlaceOptions {
+    prefer?: 'top' | 'bottom';
+    /** Space between the anchor and the bar. */
+    gap?: number;
+    /** Minimum space between the bar and the bounds' edge. */
+    margin?: number;
+}
+export declare function placeToolbar(anchor: ScreenRect, size: Size, bounds: Size, { prefer, gap, margin }?: PlaceOptions): ToolbarPlacement;

package/dist/widgets/craft/toolbar-math.js

@@ -0,0 +1,17 @@
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(v, hi));
+export function placeToolbar(anchor, size, bounds, { prefer = 'top', gap = 8, margin = 8 } = {}) {
+    const hidden = anchor.x + anchor.width < 0 || anchor.y + anchor.height < 0 || anchor.x > bounds.width || anchor.y > bounds.height;
+    const above = anchor.y - gap - size.height;
+    const below = anchor.y + anchor.height + gap;
+    const fitsAbove = above >= margin;
+    const fitsBelow = below + size.height <= bounds.height - margin;
+    let side = prefer;
+    if (prefer === 'top' && !fitsAbove && fitsBelow)
+        side = 'bottom';
+    if (prefer === 'bottom' && !fitsBelow && fitsAbove)
+        side = 'top';
+    // Neither side fits (a selection taller than the view): the clamp lays the bar over it.
+    const y = clamp(side === 'top' ? above : below, margin, bounds.height - margin - size.height);
+    const x = clamp(anchor.x + anchor.width / 2 - size.width / 2, margin, bounds.width - margin - size.width);
+    return { x: Math.round(x), y: Math.round(y), side, hidden };
+}

package/dist/widgets/craft/transform-math.d.ts

@@ -0,0 +1,16 @@
+import type { CanvasRect, TransformHandle } from './types.js';
+export interface ResizeOptions {
+    aspect?: boolean;
+    min?: number;
+}
+export declare function moveRect(r: CanvasRect, dx: number, dy: number, bounds?: CanvasRect | null): CanvasRect;
+export declare function resizeRect(r: CanvasRect, h: TransformHandle, dx: number, dy: number, { aspect, min }?: ResizeOptions): CanvasRect;
+export declare function keyRect(r: CanvasRect, key: string, { shift, alt, aspect, step, bigStep, min, bounds }: {
+    shift?: boolean;
+    alt?: boolean;
+    aspect?: boolean;
+    step?: number;
+    bigStep?: number;
+    min?: number;
+    bounds?: CanvasRect | null;
+}): CanvasRect | null;

package/dist/widgets/craft/transform-math.js

@@ -0,0 +1,37 @@
+export function moveRect(r, dx, dy, bounds) {
+    let x = r.x + dx;
+    let y = r.y + dy;
+    if (bounds) {
+        x = Math.max(bounds.x, Math.min(x, bounds.x + bounds.width - r.width));
+        y = Math.max(bounds.y, Math.min(y, bounds.y + bounds.height - r.height));
+    }
+    return { x, y, width: r.width, height: r.height };
+}
+export function resizeRect(r, h, dx, dy, { aspect = false, min = 1 } = {}) {
+    const west = h.includes('w');
+    const east = h.includes('e');
+    const north = h.includes('n');
+    const south = h.includes('s');
+    // The side being dragged moves; its opposite stays put. Clamp so it cannot cross.
+    let w = east ? r.width + dx : west ? r.width - dx : r.width;
+    let ht = south ? r.height + dy : north ? r.height - dy : r.height;
+    w = Math.max(min, w);
+    ht = Math.max(min, ht);
+    if (aspect && r.width > 0 && r.height > 0) {
+        const corner = (west || east) && (north || south);
+        const k = corner ? (Math.abs(w / r.width - 1) >= Math.abs(ht / r.height - 1) ? w / r.width : ht / r.height) : west || east ? w / r.width : ht / r.height;
+        const s = Math.max(k, min / Math.min(r.width, r.height));
+        w = r.width * s;
+        ht = r.height * s;
+    }
+    const x = west ? r.x + r.width - w : east ? r.x : r.x + (r.width - w) / 2;
+    const y = north ? r.y + r.height - ht : south ? r.y : r.y + (r.height - ht) / 2;
+    return { x, y, width: w, height: ht };
+}
+export function keyRect(r, key, { shift = false, alt = false, aspect = false, step = 1, bigStep = 10, min = 1, bounds }) {
+    const d = shift ? bigStep : step;
+    const v = { ArrowLeft: [-d, 0], ArrowRight: [d, 0], ArrowUp: [0, -d], ArrowDown: [0, d] }[key];
+    if (!v)
+        return null;
+    return alt ? resizeRect(r, 'se', v[0], v[1], { aspect, min }) : moveRect(r, v[0], v[1], bounds);
+}

package/dist/widgets/craft/types.d.ts

@@ -0,0 +1,84 @@
+/** One tool button on a ToolRail. */
+export interface CraftTool {
+    id: string;
+    label: string;
+    /** Icon name; the host maps it to a glyph through ToolRail's `icon` snippet. */
+    icon?: string;
+    /** Single key, shown in the tooltip; selects the tool when `hotkeys` is on. */
+    hotkey?: string;
+    /** Consecutive tools sharing a group render together, split by a separator. */
+    group?: string;
+    disabled?: boolean;
+}
+/** Modifier keys held during a canvas pointer event. */
+export interface CanvasMods {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+}
+/** A pointer event from CanvasViewport, in DOCUMENT coordinates. */
+export interface CanvasPointer {
+    kind: 'down' | 'drag' | 'up' | 'move' | 'doubleclick';
+    x: number;
+    y: number;
+    mods: CanvasMods;
+    button: number;
+    pointerType: string;
+    pressure: number;
+}
+/** The viewport transform: document point d sits at screen point pan + d * zoom. */
+export interface ViewTransform {
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+/** A right-panel tab on EditorShell. */
+export interface EditorPanelTab {
+    id: string;
+    label: string;
+}
+/** True when a key event is aimed at something that takes text input. */
+export declare function isEditableTarget(t: EventTarget | null): boolean;
+/** True when editor hotkeys must stay quiet: a modal layer (dialog, menu, listbox,
+ *  popover) is open anywhere in the document, or `host` sits in an inert subtree. */
+export declare function hotkeysBlocked(host?: Element | null): boolean;
+/** A layer reorder from Tree's drag-and-drop or Alt+Arrow keys. The host
+ *  applies it (and rejects a move into the dragged node's own subtree). */
+export interface LayerMove {
+    id: string | number;
+    targetId: string | number;
+    position: 'before' | 'after' | 'inside';
+}
+export type { TreeNode as LayerNode } from '../data/Tree.svelte';
+/** A ruler guide in DOCUMENT coordinates: a horizontal guide sits at y = position, a vertical one at x. */
+export interface CanvasGuide {
+    orientation: 'horizontal' | 'vertical';
+    position: number;
+}
+/** A guide edit raised by CanvasViewport: add (dragged out of a ruler), move, or remove (dropped back on its ruler). */
+export interface CanvasGuideChange extends CanvasGuide {
+    action: 'add' | 'move' | 'remove';
+    /** Index into the `guides` prop, for move and remove. */
+    index?: number;
+}
+/** A rectangle in DOCUMENT coordinates (the selection extent shown on the rulers). */
+export interface CanvasRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A TransformBox handle: a corner (nw, ne, se, sw) or an edge midpoint (n, e, s, w). */
+export type TransformHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+/** What a TransformBox commit was: a pointer move, a handle resize, or a keyboard nudge / resize burst. */
+export type TransformKind = 'move' | 'resize' | 'nudge';
+/** A rectangle in SCREEN space: the coordinate frame of the canvas stage, the same one
+ *  CanvasViewport's `overlay` snippet and EditorShell's `floating` layer use
+ *  (a document point d sits at pan + d * zoom). ContextToolbar anchors to one. */
+export interface ScreenRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}