@dumiflex/wp-kit 0.0.0-stage → 0.3.0

package/src/drop-zone.ts

@@ -0,0 +1,41 @@
+/**
+ * File checks for DropZone: does a file (or a dragged item, whose name is
+ * not known until the drop) match an `accept` list like the file input's
+ * ("image/*,.txt,application/json")?
+ */
+export function acceptList(accept: string | undefined): string[] {
+  return (accept ?? "").split(",").map((a) => a.trim().toLowerCase()).filter(Boolean);
+}
+
+function typeMatches(type: string, rule: string): boolean {
+  if (!type) return false;
+  const t = type.toLowerCase();
+  return rule.endsWith("/*") ? t.startsWith(rule.slice(0, -1)) : t === rule;
+}
+
+/** A dropped file: by its extension or its type. An empty list takes all. */
+export function fileAccepted(file: { name: string; type: string }, accept: string | undefined): boolean {
+  const rules = acceptList(accept);
+  if (!rules.length) return true;
+  const name = file.name.toLowerCase();
+  return rules.some((r) => (r.startsWith(".") ? name.endsWith(r) : typeMatches(file.type, r)));
+}
+
+/**
+ * A dragged item, before the drop: only its type is known. Returns false
+ * only when it surely won't be taken; an item with no type, or a list that
+ * names extensions (which we can't see yet), gets the benefit of the doubt.
+ */
+export function dragItemMaybeAccepted(type: string, accept: string | undefined): boolean {
+  const rules = acceptList(accept);
+  if (!rules.length || !type) return true;
+  if (rules.some((r) => r.startsWith("."))) return true;
+  return rules.some((r) => typeMatches(type, r));
+}
+
+/** "2.4 MB", "820 KB". */
+export function formatBytes(n: number): string {
+  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(n >= 10 * 1024 * 1024 ? 0 : 1)} MB`;
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`;
+  return `${n} B`;
+}

package/src/flip.ts

@@ -0,0 +1,237 @@
+/**
+ * Manual FLIP-move helper + reduce-motion gate. Shared across every
+ * row-list surface in the extension — moved from
+ * `src/components/context/bundles/flip.ts` (which was bundle-coupled
+ * by directory but not by code) so InjectorRow + future row UIs can
+ * reuse the same animation primitives instead of reinventing them.
+ *
+ * Used by ContextWidget's drop / picker-add / trash-remove paths to
+ * animate row reordering, plus cross-container fade-slide and bundle
+ * collapse/expand. Pure functions — no Vue imports, unit-testable.
+ *
+ * Reduce-motion contract: every helper checks `shouldAnimate()` which
+ * returns false when `.wp-a11y-no-motion` is on `document.body`. CSS
+ * transitions/animations are handled by a separate blanket rule in
+ * src/components/shared/a11y.css; this module handles the JS side.
+ *
+ * Motion constants mirror the CSS tokens in
+ * src/components/shared/theme.css (--wp-motion-*). Keep these in sync.
+ *
+ * Class-name customization: every animation helper accepts an
+ * `opts.classes` field so different consumers can use their own
+ * BEM-style modifier names (e.g. ModuleRow uses `wp-module--*`,
+ * InjectorRow uses `wp-inj-row--*`). Defaults preserve the original
+ * Context/Bundle behavior so ContextWidget keeps working without
+ * any callsite change.
+ */
+
+export const MOTION_COLLAPSE_MS = 450;
+export const MOTION_FLIP_MS = 280;
+export const MOTION_FADE_MS = 180;
+export const MOTION_PULSE_MS = 420;
+export const MOTION_STAGGER_MS = 60;
+export const MOTION_CURVE_FLIP = "cubic-bezier(0.22, 1, 0.36, 1)";
+
+type FlipOptions = { duration?: number; ease?: string };
+
+/** Per-consumer class name vocabulary. Each animation helper applies
+ *  these classes to mark rows mid-transition; the consumer's CSS
+ *  defines what the classes look like. Defaults to the original
+ *  ContextWidget/ModuleRow names for back-compat. */
+export interface AnimationClasses {
+  arriving: string;
+  arrived: string;
+  leaving: string;
+  flash: string;
+}
+
+const DEFAULT_CLASSES: AnimationClasses = {
+  arriving: "wp-module--arriving",
+  arrived: "wp-module--arrived",
+  leaving: "wp-module--leaving",
+  flash: "wp-module--flash",
+};
+
+/** Resolve user-supplied classes against the defaults so callers can
+ *  override only the names that differ. Internal helper. */
+function resolveClasses(partial?: Partial<AnimationClasses>): AnimationClasses {
+  if (!partial) return DEFAULT_CLASSES;
+  return { ...DEFAULT_CLASSES, ...partial };
+}
+
+/** Whether motion should animate. False when user has reduce-motion ON. */
+export function shouldAnimate(): boolean {
+  return !document.body.classList.contains("wp-a11y-no-motion");
+}
+
+/** Capture each child's bounding rect, keyed by the caller's key function. */
+export function captureRects(
+  container: HTMLElement,
+  key: (el: HTMLElement) => string | null,
+): Map<string, DOMRect> {
+  const out = new Map<string, DOMRect>();
+  for (const child of Array.from(container.children)) {
+    const el = child as HTMLElement;
+    const k = key(el);
+    if (k != null) out.set(k, el.getBoundingClientRect());
+  }
+  return out;
+}
+
+/**
+ * After a DOM mutation, apply inverse-transform to children whose
+ * position changed, then transition back to identity. Skip silently
+ * when reduce-motion is on.
+ */
+export function applyFlip(
+  container: HTMLElement,
+  before: Map<string, DOMRect>,
+  key: (el: HTMLElement) => string | null,
+  opt: FlipOptions = {},
+): void {
+  if (!shouldAnimate()) return;
+  const dur = opt.duration ?? MOTION_FLIP_MS;
+  const ease = opt.ease ?? MOTION_CURVE_FLIP;
+  for (const child of Array.from(container.children)) {
+    const el = child as HTMLElement;
+    const k = key(el);
+    if (k == null) continue;
+    const beforeRect = before.get(k);
+    if (!beforeRect) continue;
+    const afterRect = el.getBoundingClientRect();
+    const dx = beforeRect.left - afterRect.left;
+    const dy = beforeRect.top - afterRect.top;
+    if (dx === 0 && dy === 0) continue;
+    el.style.transition = "none";
+    el.style.transform = `translate(${dx}px, ${dy}px)`;
+    requestAnimationFrame(() => {
+      el.style.transition = `transform ${dur}ms ${ease}`;
+      el.style.transform = "translate(0, 0)";
+    });
+  }
+}
+
+/**
+ * Mutate state then animate the newly-inserted element (matched by uid)
+ * with --arriving → --arrived class transition. The arriving class is
+ * applied after the mutation + a microtask so the browser registers
+ * the "from" state; arrived flips the next frame so the transition fires.
+ * No-op (mutate-only) when reduce-motion is on.
+ */
+export async function withEnterAnimation(
+  uid: string,
+  container: HTMLElement,
+  mutate: () => void,
+  opts?: { classes?: Partial<AnimationClasses> },
+): Promise<void> {
+  mutate();
+  if (!shouldAnimate()) return;
+  const cls = resolveClasses(opts?.classes);
+  // Wait one rAF so Vue commits the mutation to DOM before we query.
+  // A bare `await Promise.resolve()` schedules a microtask that can
+  // race Vue's own microtask-based reactivity scheduler — rAF runs
+  // after the microtask queue drains and before paint.
+  await new Promise<void>(r => requestAnimationFrame(() => r()));
+  const el = container.querySelector<HTMLElement>(`[data-uid="${uid}"]`);
+  if (!el) return;
+  el.classList.add(cls.arriving);
+  await new Promise<void>(r => requestAnimationFrame(() => r()));
+  el.classList.add(cls.arrived);
+  const cleanup = (): void => {
+    el.classList.remove(cls.arriving, cls.arrived);
+    el.removeEventListener("transitionend", cleanup);
+  };
+  el.addEventListener("transitionend", cleanup, { once: true });
+}
+
+/**
+ * Animate a batch of newly-inserted elements (matched by uid array)
+ * with --arriving → --arrived class lifecycle. Caller has already
+ * mutated state and is responsible for waiting nextTick if needed —
+ * this helper waits one rAF before applying classes so Vue's commit
+ * has landed.
+ *
+ * Two-pass design: apply all --arriving classes first (so every row
+ * is at the from-state simultaneously), then apply all --arrived
+ * classes on the next frame (so they all transition together). Avoids
+ * a staircase effect where rows animate sequentially.
+ *
+ * No-op when reduce-motion is on.
+ */
+export async function animateEnterBatch(
+  uids: readonly (string | null | undefined)[],
+  container: HTMLElement,
+  opts?: { classes?: Partial<AnimationClasses> },
+): Promise<void> {
+  if (!shouldAnimate()) return;
+  const cls = resolveClasses(opts?.classes);
+  await new Promise<void>(r => requestAnimationFrame(() => r()));
+  const elements: HTMLElement[] = [];
+  for (const uid of uids) {
+    if (!uid) continue;
+    const el = container.querySelector<HTMLElement>(`[data-uid="${uid}"]`);
+    if (el) elements.push(el);
+  }
+  if (elements.length === 0) return;
+  for (const el of elements) el.classList.add(cls.arriving);
+  await new Promise<void>(r => requestAnimationFrame(() => r()));
+  for (const el of elements) {
+    el.classList.add(cls.arrived);
+    const cleanup = (): void => {
+      el.classList.remove(cls.arriving, cls.arrived);
+      el.removeEventListener("transitionend", cleanup);
+    };
+    el.addEventListener("transitionend", cleanup, { once: true });
+  }
+}
+
+/**
+ * Flash a batch of rows with the existing wp-module--flash green ring
+ * keyframe (1500ms) — used to indicate library-side mutations (refresh,
+ * reset, fork). Staggered so bulk refresh cascades. No-op when reduce-
+ * motion is on.
+ */
+const FLASH_DURATION_MS = MOTION_PULSE_MS;  // 420ms — matches drop pulse timing
+export async function flashRows(
+  uids: readonly (string | null | undefined)[],
+  container: HTMLElement,
+  staggerMs: number = MOTION_STAGGER_MS,
+  opts?: { classes?: Partial<AnimationClasses> },
+): Promise<void> {
+  if (!shouldAnimate()) return;
+  const cls = resolveClasses(opts?.classes);
+  await new Promise<void>(r => requestAnimationFrame(() => r()));
+  for (let i = 0; i < uids.length; i++) {
+    const uid = uids[i];
+    if (!uid) continue;
+    const el = container.querySelector<HTMLElement>(`[data-uid="${uid}"]`);
+    if (!el) continue;
+    const delay = i * staggerMs;
+    setTimeout(() => {
+      el.classList.add(cls.flash);
+      setTimeout(() => el.classList.remove(cls.flash), FLASH_DURATION_MS);
+    }, delay);
+  }
+}
+
+/**
+ * Animate an element (matched by uid) with --leaving class, wait for the
+ * fade to complete, then run mutate to remove from state. Mutate is
+ * called immediately when reduce-motion is on (no class added).
+ */
+export async function withLeaveAnimation(
+  uid: string,
+  container: HTMLElement,
+  mutate: () => void,
+  opts?: { classes?: Partial<AnimationClasses> },
+): Promise<void> {
+  if (!shouldAnimate()) {
+    mutate();
+    return;
+  }
+  const cls = resolveClasses(opts?.classes);
+  const el = container.querySelector<HTMLElement>(`[data-uid="${uid}"]`);
+  if (el) el.classList.add(cls.leaving);
+  await new Promise<void>(r => setTimeout(r, MOTION_FADE_MS));
+  mutate();
+}

package/src/floating.ts

@@ -0,0 +1,99 @@
+/**
+ * Where a floating panel (popover, menu, tooltip) goes next to its anchor:
+ * on the preferred side when it fits, on the other side when it doesn't,
+ * and always kept inside the viewport. Pure maths, no DOM, so it is the
+ * same on the canvas and in the manager. `Popover`, `ContextMenu` and the
+ * tooltip directive all place themselves through it.
+ */
+
+export type Side = "top" | "bottom" | "left" | "right";
+export type Align = "start" | "center" | "end";
+export type Placement = Side | `${Side}-${Exclude<Align, "center">}`;
+
+export interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface PlaceOptions {
+  placement?: Placement;
+  /** Space between the anchor and the panel. */
+  gap?: number;
+  /** Space the panel keeps from the viewport edge. */
+  margin?: number;
+}
+
+export interface Placed {
+  x: number;
+  y: number;
+  /** The side it ended up on, after any flip. */
+  side: Side;
+}
+
+const OPPOSITE: Record<Side, Side> = { top: "bottom", bottom: "top", left: "right", right: "left" };
+
+export function splitPlacement(p: Placement): { side: Side; align: Align } {
+  const [side, align] = p.split("-") as [Side, Exclude<Align, "center"> | undefined];
+  return { side, align: align ?? "center" };
+}
+
+function room(side: Side, a: Rect, view: Size, gap: number, margin: number): number {
+  switch (side) {
+    case "top": return a.top - gap - margin;
+    case "bottom": return view.height - (a.top + a.height) - gap - margin;
+    case "left": return a.left - gap - margin;
+    case "right": return view.width - (a.left + a.width) - gap - margin;
+  }
+}
+
+function clamp(v: number, min: number, max: number): number {
+  return max < min ? min : Math.min(Math.max(v, min), max);
+}
+
+export function placeFloating(anchor: Rect, panel: Size, view: Size, opts: PlaceOptions = {}): Placed {
+  const gap = opts.gap ?? 6;
+  const margin = opts.margin ?? 8;
+  const { side: want, align } = splitPlacement(opts.placement ?? "bottom-start");
+  const vertical = want === "top" || want === "bottom";
+  const need = vertical ? panel.height : panel.width;
+
+  // Flip only when the other side has more room; a panel too big for both
+  // stays on the side with more space and gets clamped.
+  let side = want;
+  if (room(want, anchor, view, gap, margin) < need) {
+    const other = OPPOSITE[want];
+    if (room(other, anchor, view, gap, margin) > room(want, anchor, view, gap, margin)) side = other;
+  }
+
+  let x: number;
+  let y: number;
+  if (vertical) {
+    y = side === "bottom" ? anchor.top + anchor.height + gap : anchor.top - gap - panel.height;
+    x = align === "start" ? anchor.left
+      : align === "end" ? anchor.left + anchor.width - panel.width
+      : anchor.left + (anchor.width - panel.width) / 2;
+  } else {
+    x = side === "right" ? anchor.left + anchor.width + gap : anchor.left - gap - panel.width;
+    y = align === "start" ? anchor.top
+      : align === "end" ? anchor.top + anchor.height - panel.height
+      : anchor.top + (anchor.height - panel.height) / 2;
+  }
+
+  return {
+    x: Math.round(clamp(x, margin, view.width - margin - panel.width)),
+    y: Math.round(clamp(y, margin, view.height - margin - panel.height)),
+    side,
+  };
+}
+
+/** The viewport, for callers that have a window. */
+export function viewportSize(): Size {
+  return { width: window.innerWidth, height: window.innerHeight };
+}

package/src/hsv.ts

@@ -0,0 +1,100 @@
+/**
+ * HSV / RGB / hex color conversion utilities.
+ *
+ * `h` in `[0, 360)`, `s` and `v` in `[0, 1]`. Hex strings are `#rrggbb`
+ * lowercase. Functions are tolerant of out-of-range input — they clamp
+ * rather than throw, which keeps the picker UI robust under fast drags.
+ *
+ * Lives in shared/ so both the manager-side ColorPicker / TweaksPanel
+ * AND the canvas-side bundle modal can drive the same HsvPicker
+ * without a cross-package import.
+ */
+
+export interface Hsv {
+  h: number;
+  s: number;
+  v: number;
+}
+
+export interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+const HEX_PATTERN = /^#?([0-9a-fA-F]{6})$/;
+
+function clamp(n: number, lo: number, hi: number): number {
+  if (Number.isNaN(n)) return lo;
+  return Math.min(hi, Math.max(lo, n));
+}
+
+export function hsvToRgb(hsv: Hsv): Rgb {
+  const H = (((hsv.h % 360) + 360) % 360);
+  const S = clamp(hsv.s, 0, 1);
+  const V = clamp(hsv.v, 0, 1);
+
+  const C = V * S;
+  const X = C * (1 - Math.abs(((H / 60) % 2) - 1));
+  const M = V - C;
+  let r1 = 0;
+  let g1 = 0;
+  let b1 = 0;
+  if (H < 60)        { r1 = C; g1 = X; b1 = 0; }
+  else if (H < 120)  { r1 = X; g1 = C; b1 = 0; }
+  else if (H < 180)  { r1 = 0; g1 = C; b1 = X; }
+  else if (H < 240)  { r1 = 0; g1 = X; b1 = C; }
+  else if (H < 300)  { r1 = X; g1 = 0; b1 = C; }
+  else               { r1 = C; g1 = 0; b1 = X; }
+  return {
+    r: Math.round((r1 + M) * 255),
+    g: Math.round((g1 + M) * 255),
+    b: Math.round((b1 + M) * 255),
+  };
+}
+
+export function rgbToHsv(rgb: Rgb): Hsv {
+  const R = clamp(rgb.r, 0, 255) / 255;
+  const G = clamp(rgb.g, 0, 255) / 255;
+  const B = clamp(rgb.b, 0, 255) / 255;
+  const max = Math.max(R, G, B);
+  const min = Math.min(R, G, B);
+  const delta = max - min;
+
+  let h = 0;
+  if (delta > 0) {
+    if (max === R)      h = ((G - B) / delta) % 6;
+    else if (max === G) h = (B - R) / delta + 2;
+    else                h = (R - G) / delta + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  const s = max === 0 ? 0 : delta / max;
+  const v = max;
+  return { h, s, v };
+}
+
+export function rgbToHex(rgb: Rgb): string {
+  const part = (n: number): string => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+  return `#${part(rgb.r)}${part(rgb.g)}${part(rgb.b)}`;
+}
+
+export function hexToRgb(hex: string): Rgb | null {
+  const matches = hex.trim().match(HEX_PATTERN);
+  if (!matches) return null;
+  const v = matches[1];
+  return {
+    r: parseInt(v.slice(0, 2), 16),
+    g: parseInt(v.slice(2, 4), 16),
+    b: parseInt(v.slice(4, 6), 16),
+  };
+}
+
+export function hexToHsv(hex: string): Hsv | null {
+  const rgb = hexToRgb(hex);
+  return rgb ? rgbToHsv(rgb) : null;
+}
+
+export function hsvToHex(hsv: Hsv): string {
+  return rgbToHex(hsvToRgb(hsv));
+}

package/src/icon-catalog.ts

@@ -0,0 +1,52 @@
+/**
+ * Curated PrimeIcons glyphs offered by `IconPicker.vue`.
+ *
+ * PrimeIcons ships ~314 glyphs; this is a subset. The full set would need its
+ * own search UI, and most of it (chevrons, spinners, media transport, brand
+ * logos) means nothing as a library label. The groups below follow the kinds
+ * of things people actually categorise prompt modules by.
+ *
+ * Names are PrimeIcons ids MINUS the `pi-` prefix (`"user"`, not `"pi-user"`)
+ * — that is what the engine's `icon` column holds and what `Icon.vue` expects.
+ *
+ * In a plain module rather than inside the SFC so `icon-catalog.test.ts` can
+ * check every name against the installed `primeicons.css` without mounting a
+ * component. That test is the point: a name with no matching glyph renders as
+ * an EMPTY CELL, which looks like a layout bug rather than a typo, and `brush`
+ * shipped that way because nothing verified the list.
+ */
+export interface IconGroup {
+  label: string;
+  icons: string[];
+}
+
+export const ICON_GROUPS: IconGroup[] = [
+  {
+    label: "Subject",
+    icons: ["user", "users", "heart", "star", "eye", "face-smile", "crown", "id-card"],
+  },
+  {
+    // `sliders-h` stands in for the art-supply glyph PrimeIcons doesn't have —
+    // there is no brush/paint icon in the set, and `palette` already carries
+    // "art style". Sliders read as "tune the look".
+    label: "Style & look",
+    icons: ["palette", "pencil", "sliders-h", "camera", "image", "sparkles", "sun", "moon"],
+  },
+  {
+    label: "Scene",
+    icons: ["home", "building", "map", "map-marker", "globe", "compass", "car", "cloud"],
+  },
+  {
+    label: "Structure",
+    icons: ["box", "folder", "book", "tag", "tags", "list", "sitemap", "objects-column"],
+  },
+  {
+    label: "Signals",
+    icons: ["bolt", "flag", "bell", "shield", "lock", "wrench", "filter", "info-circle"],
+  },
+];
+
+/** Every offered glyph, flattened — for tests and any future search box. */
+export function allCuratedIcons(): string[] {
+  return ICON_GROUPS.flatMap((g) => g.icons);
+}

package/src/image-zoom.ts

@@ -0,0 +1,93 @@
+/**
+ * The maths behind `WpImageZoom`: one transform, `translate(x, y) scale(s)`
+ * with its origin at the image's top-left corner. Pure, so it is tested on
+ * its own.
+ */
+
+export interface Size { width: number; height: number }
+export interface View { scale: number; x: number; y: number }
+
+/** Zoom never goes below this share of Fit (or of 100% for a tiny image), nor above MAX_SCALE. */
+export const MAX_SCALE = 8;
+/** The steps the − / + buttons jump through, as real-size factors. */
+export const ZOOM_STEPS = [0.1, 0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4, 6, 8] as const;
+/** How long `WpImageZoom`'s bar stays after the last pointer move or key, with `autohide`. */
+export const IDLE_MS = 2000;
+/** One wheel notch. */
+export const WHEEL_FACTOR = 1.2;
+
+/** The scale that shows the whole image in the stage (it may be above 1 for a small image). */
+export function fitScale(image: Size, stage: Size): number {
+  if (image.width <= 0 || image.height <= 0 || stage.width <= 0 || stage.height <= 0) return 1;
+  return Math.min(stage.width / image.width, stage.height / image.height);
+}
+
+export function minScale(image: Size, stage: Size): number {
+  return Math.min(fitScale(image, stage), 1) / 2;
+}
+
+export function clampScale(scale: number, image: Size, stage: Size): number {
+  return Math.min(MAX_SCALE, Math.max(minScale(image, stage), scale));
+}
+
+/** Keep the image in view: centred on an axis where it is smaller than the
+ *  stage, otherwise never showing an empty edge. */
+export function clampView(view: View, image: Size, stage: Size): View {
+  const axis = (pos: number, img: number, room: number): number => {
+    const size = img * view.scale;
+    if (size <= room) return (room - size) / 2;
+    return Math.min(0, Math.max(room - size, pos));
+  };
+  return { scale: view.scale, x: axis(view.x, image.width, stage.width), y: axis(view.y, image.height, stage.height) };
+}
+
+/** Set the scale, keeping the image point under `at` (stage px) where it is. */
+export function zoomAt(view: View, scale: number, at: { x: number; y: number }, image: Size, stage: Size): View {
+  const s = clampScale(scale, image, stage);
+  const k = s / view.scale;
+  return clampView({ scale: s, x: at.x - (at.x - view.x) * k, y: at.y - (at.y - view.y) * k }, image, stage);
+}
+
+/** The view at `scale` centred on the image point `centre` (fractions 0..1). */
+export function viewAround(scale: number, centre: { x: number; y: number }, image: Size, stage: Size): View {
+  const s = clampScale(scale, image, stage);
+  return clampView({
+    scale: s,
+    x: stage.width / 2 - centre.x * image.width * s,
+    y: stage.height / 2 - centre.y * image.height * s,
+  }, image, stage);
+}
+
+/** The image point (fractions 0..1) at the middle of the stage. */
+export function centreOf(view: View, image: Size, stage: Size): { x: number; y: number } {
+  if (image.width <= 0 || image.height <= 0) return { x: 0.5, y: 0.5 };
+  const f = (mid: number, pos: number, img: number): number => Math.min(1, Math.max(0, (mid - pos) / (img * view.scale)));
+  return { x: f(stage.width / 2, view.x, image.width), y: f(stage.height / 2, view.y, image.height) };
+}
+
+/** The next step up (dir 1) or down (dir -1) from `scale`, with Fit slotted in among the steps. */
+export function stepScale(scale: number, dir: 1 | -1, fit: number): number {
+  const steps = [...ZOOM_STEPS, fit].sort((a, b) => a - b);
+  const eps = 1e-3;
+  if (dir > 0) return steps.find((s) => s > scale + eps) ?? MAX_SCALE;
+  return [...steps].reverse().find((s) => s < scale - eps) ?? steps[0];
+}
+
+/** "100%", "35%", "250%". */
+export function percent(scale: number): string {
+  return `${Math.round(scale * 100)}%`;
+}
+
+/** The part of the image the stage shows, as fractions 0..1 of the image (for a mini-map). */
+export function visibleRect(view: View, image: Size, stage: Size): { x: number; y: number; w: number; h: number } {
+  if (image.width <= 0 || image.height <= 0) return { x: 0, y: 0, w: 1, h: 1 };
+  const axis = (pos: number, img: number, room: number): [number, number] => {
+    const size = img * view.scale;
+    const a = Math.min(1, Math.max(0, -pos / size));
+    const b = Math.min(1, Math.max(0, (room - pos) / size));
+    return [a, b - a];
+  };
+  const [x, w] = axis(view.x, image.width, stage.width);
+  const [y, h] = axis(view.y, image.height, stage.height);
+  return { x, y, w, h };
+}

package/src/logo-paths.ts

@@ -0,0 +1,21 @@
+/** The Wildcard Pipeline logo, split into its parts so a drawing can move them
+ *  on their own (viewBox 0 0 1024 1024). Same shapes as `wp-logo.svg`. */
+export const RING_A =
+  "m512,2c-53.6,0-98.47,38.16-108.84,88.73-75.07,19.29-143.32,58.26-198.74,113.68-55.42,55.42-94.39,123.68-113.68,198.74-50.58,10.38-88.73,55.24-88.73,108.84s38.16,98.47,88.73,108.84c13.62,53.14,37.03,102.64,69.77,147.47,37.14,50.86,85.83,93.86,140.81,124.33,5.54,3.08,11.56,4.54,17.48,4.54,12.7,0,25.02-6.72,31.61-18.61,9.68-17.44,3.38-39.42-14.07-49.09-85.32-47.32-147.22-125.71-173.38-218.21,36.3-18.29,61.27-55.92,61.27-99.28s-24.94-80.97-61.23-99.27c34.22-119.96,129.79-215.52,249.74-249.74,18.3,36.29,55.92,61.23,99.27,61.23,61.27,0,111.11-49.84,111.11-111.11S573.27,2,512,2ZM113.11,473.11c21.44,0,38.89,17.44,38.89,38.89,0,20.1-15.32,36.69-34.91,38.69h-.01c-.18.02-.36.03-.53.04-1.13.1-2.28.16-3.43.16-21.44,0-38.89-17.44-38.89-38.89s17.44-38.89,38.89-38.89Zm398.89-321.11c-21.44,0-38.89-17.44-38.89-38.89s17.44-38.89,38.89-38.89,38.89,17.44,38.89,38.89-17.44,38.89-38.89,38.89Z";
+export const RING_B =
+  "m933.27,403.16c-13.62-53.14-37.03-102.64-69.77-147.47-37.14-50.86-85.83-93.86-140.81-124.33-17.44-9.68-39.42-3.38-49.09,14.07-9.68,17.44-3.38,39.42,14.07,49.09,85.32,47.32,147.22,125.71,173.38,218.21-36.3,18.29-61.27,55.92-61.27,99.28s24.94,80.97,61.23,99.27c-34.22,119.96-129.79,215.52-249.74,249.74-18.3-36.29-55.92-61.23-99.27-61.23-61.27,0-111.11,49.84-111.11,111.11s49.84,111.11,111.11,111.11c53.6,0,98.47-38.16,108.84-88.73,75.07-19.29,143.32-58.26,198.74-113.68,55.42-55.42,94.39-123.68,113.68-198.74,50.58-10.38,88.73-55.24,88.73-108.84s-38.16-98.47-88.73-108.84Zm-421.27,546.62c-21.44,0-38.89-17.44-38.89-38.89s17.44-38.89,38.89-38.89,38.89,17.44,38.89,38.89-17.44,38.89-38.89,38.89Zm398.89-398.89c-21.44,0-38.89-17.44-38.89-38.89,0-20.03,15.22-36.58,34.72-38.67.38-.04.77-.08,1.16-.11h.02c.99-.08,1.99-.11,2.99-.11,21.44,0,38.89,17.44,38.89,38.89s-17.44,38.89-38.89,38.89Z";
+export const STAR_BIG =
+  "m735.02,517.56c-153.82,30.87-186.59,63.64-217.46,217.46-1.22,6.08-9.9,6.08-11.12,0-30.87-153.82-63.64-186.59-217.46-217.46-6.08-1.22-6.08-9.9,0-11.12,153.82-30.87,186.59-63.64,217.46-217.46,1.22-6.08,9.9-6.08,11.12,0,30.87,153.82,63.64,186.59,217.46,217.46,6.08,1.22,6.08,9.9,0,11.12Z";
+export const STAR_A =
+  "m434.06,665.85c-51.08,10.25-61.96,21.13-72.22,72.22-.41,2.02-3.29,2.02-3.69,0-10.25-51.08-21.13-61.96-72.22-72.22-2.02-.41-2.02-3.29,0-3.69,51.08-10.25,61.96-21.13,72.22-72.22.41-2.02,3.29-2.02,3.69,0,10.25,51.08,21.13,61.96,72.22,72.22,2.02.41,2.02,3.29,0,3.69Z";
+export const STAR_B =
+  "m738.07,361.84c-51.08,10.25-61.96,21.13-72.22,72.22-.41,2.02-3.29,2.02-3.69,0-10.25-51.08-21.13-61.96-72.22-72.22-2.02-.41-2.02-3.29,0-3.69,51.08-10.25,61.96-21.13,72.22-72.22.41-2.02,3.29-2.02,3.69,0,10.25,51.08,21.13,61.96,72.22,72.22,2.02.41,2.02,3.29,0,3.69Z";
+
+/** The logo's colours: [big star and first ring start, middle, small star and
+ *  second ring end]. Brand colours, not theme tokens: the mark looks the same
+ *  in light and dark. `community` is the community site's rust counterpart. */
+export const BRAND_COLOURS = {
+  extension: ["#a970ff", "#6366f1", "#33d6c6"],
+  community: ["#da7550", "#f1636c", "#ad33d6"],
+} as const;
+export type LogoBrand = keyof typeof BRAND_COLOURS;