@dumiflex/wp-kit 0.6.0 → 0.7.0

package/src/WorkingLine.vue

@@ -20,14 +20,16 @@
  * never narrower than the word: it widens at once and narrows smoothly once
  * the old word has mostly faded.
  *
- * Every mark animates registered custom properties, never `transform` or
- * `opacity` themselves, so the paths repaint sharp each frame instead of
- * going to a compositor layer that blurs them and snaps them to whole pixels.
+ * The marks move on a canvas over the still SVG, so they stay sharp and
+ * glide in every browser (`canvas-motion.ts` says why); the SVG is the first
+ * paint and stays under reduced motion, where it only breathes.
  */
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
 import { BRAND_COLOURS, STAR_A, STAR_B, STAR_BIG, type LogoBrand } from "./logo-paths";
+import { canvasBox, useCanvasMotion } from "./canvas-motion";
+import { TEMPO_MS, TYPING_X, drawWorking, orbitNodes, type WorkingVariant } from "./working-line-motion";
 
-export type WorkingVariant = "typing" | "shuffle" | "orbit" | "burst";
+export type { WorkingVariant } from "./working-line-motion";
 
 const props = withDefaults(defineProps<{
   /** What is shown, without the "…" (the line adds it). */
@@ -55,14 +57,14 @@ const BIG = computed(() => colours.value[0]);
 const A = computed(() => colours.value[1]);
 const B = computed(() => colours.value[2]);
 /** The logo's four nodes for the orbit, with steps between the colours. */
-const nodes = computed(() => [
-  [911, 512, B.value],
-  [512, 911, `color-mix(in srgb, ${B.value} 70%, ${A.value})`],
-  [113, 512, `color-mix(in srgb, ${BIG.value} 60%, ${A.value})`],
-  [512, 113, A.value],
-] as const);
+const nodes = computed(() => orbitNodes(colours.value));
 /** Typing stars: the big sparkle drawn small three times in a row. */
-const typing = computed(() => [[250, A.value], [512, BIG.value], [774, B.value]] as const);
+const typing = computed(() => TYPING_X.map((x, i) => [x, [A.value, BIG.value, B.value][i] ?? BIG.value] as const));
+
+const canvas = ref<HTMLCanvasElement | null>(null);
+const canvasStyle = computed(() => canvasBox(props.size));
+const { live, drawn } = useCanvasMotion(canvas, (ctx, width, ms) =>
+  drawWorking(ctx, width, ms, props.variant, TEMPO_MS[props.tempo], colours.value));
 
 const measure = ref<HTMLElement | null>(null);
 const boxWidth = ref<number | null>(null);
@@ -98,41 +100,39 @@ onBeforeUnmount(() => resized?.disconnect());
     :data-tempo="tempo"
     :data-variant="variant"
     :data-inline="inline ? 'true' : undefined"
+    :data-drawn="drawn ? 'true' : undefined"
     role="status"
     :aria-label="name"
     :title="name"
     :style="{ '--wp-wl-big': BIG, '--wp-wl-a': A, '--wp-wl-b': B }"
   >
+    <span class="wp-wl__art" :style="{ width: `${size}px`, height: `${size}px` }">
     <svg class="wp-wl__logo" viewBox="0 0 1024 1024" :width="size" :height="size" aria-hidden="true">
       <template v-if="variant === 'typing'">
-        <g v-for="([x, c], i) in typing" :key="i" class="wp-wl__hop" :style="{ '--wp-wl-k': i }">
-          <path class="wp-wl__star" :style="{ fill: c }" :transform="`translate(${x - 256} 256) scale(.5)`" :d="STAR_BIG" />
-        </g>
+        <path
+          v-for="([x, c], i) in typing" :key="i" :style="{ fill: c }"
+          :transform="`translate(${x - 256} 256) scale(.5)`" :d="STAR_BIG"
+        />
       </template>
       <g v-else-if="variant === 'shuffle'" transform="translate(512 512) scale(1.45) translate(-512 -512)">
-        <path class="wp-wl__star wp-wl__star--big wp-wl__dip" :style="{ fill: BIG }" :d="STAR_BIG" />
-        <g class="wp-wl__vb wp-wl__swap">
-          <path class="wp-wl__star" :style="{ fill: A }" :d="STAR_A" />
-          <path class="wp-wl__star" :style="{ fill: B }" :d="STAR_B" />
-        </g>
+        <path :style="{ fill: BIG }" :d="STAR_BIG" />
+        <path :style="{ fill: A }" :d="STAR_A" />
+        <path :style="{ fill: B }" :d="STAR_B" />
       </g>
       <template v-else-if="variant === 'orbit'">
-        <g class="wp-wl__vb wp-wl__spin">
-          <circle
-            v-for="([x, y, c], i) in nodes" :key="i" class="wp-wl__dot"
-            :style="{ '--wp-wl-k': i, fill: c }" :cx="x" :cy="y" r="70"
-          />
-        </g>
-        <path class="wp-wl__star wp-wl__star--big wp-wl__breathe" :style="{ fill: BIG }" :d="STAR_BIG" />
-        <path class="wp-wl__star" :style="{ fill: A }" :d="STAR_A" />
-        <path class="wp-wl__star" :style="{ fill: B }" :d="STAR_B" />
+        <circle v-for="([x, y, c], i) in nodes" :key="i" :style="{ fill: c }" :cx="x" :cy="y" r="70" />
+        <path :style="{ fill: BIG }" :d="STAR_BIG" />
+        <path :style="{ fill: A }" :d="STAR_A" />
+        <path :style="{ fill: B }" :d="STAR_B" />
       </template>
       <g v-else transform="translate(512 512) scale(1.3) translate(-512 -512)">
-        <path class="wp-wl__star wp-wl__star--big wp-wl__pop" :style="{ fill: BIG }" :d="STAR_BIG" />
-        <path class="wp-wl__star wp-wl__burst" :style="{ fill: A, '--wp-wl-dx': '152px', '--wp-wl-dy': '-152px' }" :d="STAR_A" />
-        <path class="wp-wl__star wp-wl__burst" :style="{ fill: B, '--wp-wl-dx': '-152px', '--wp-wl-dy': '152px' }" :d="STAR_B" />
+        <path :style="{ fill: BIG }" :d="STAR_BIG" />
+        <path :style="{ fill: A }" :d="STAR_A" />
+        <path :style="{ fill: B }" :d="STAR_B" />
       </g>
     </svg>
+    <canvas v-if="live" ref="canvas" class="wp-wl__canvas" :style="canvasStyle" aria-hidden="true" />
+    </span>
     <span
       class="wp-wl__words"
       :data-grow="growing ? 'true' : undefined"
@@ -149,7 +149,6 @@ onBeforeUnmount(() => resized?.disconnect());
 
 <style scoped>
 .wp-wl {
-  --wp-wl-t: 2.8s;
   display: flex;
   align-items: center;
   gap: 8px;
@@ -158,9 +157,7 @@ onBeforeUnmount(() => resized?.disconnect());
   font-size: 13px;
   white-space: nowrap;
 }
-.wp-wl[data-tempo="mid"] { --wp-wl-t: 2.2s; }
-.wp-wl[data-tempo="fast"] { --wp-wl-t: 1.5s; }
-.wp-wl__logo { flex-shrink: 0; overflow: visible; }
+.wp-wl__logo { overflow: visible; }
 .wp-wl__words {
   position: relative;
   display: inline-flex;
@@ -220,100 +217,17 @@ onBeforeUnmount(() => resized?.disconnect());
   .wp-wl-word-enter-from, .wp-wl-word-leave-to { --wp-wl-wb: 0px; }
 }
 
-/* Every mark animates registered custom properties, never `transform` or
- * `opacity` themselves. A `transform` / `opacity` animation goes to the
- * compositor, which lifts each path onto its own layer as it starts:
- * rasterised once at a fixed scale and snapped to whole pixels, so the sharp
- * mark went soft and jumped half a pixel the moment it began to move. A
- * custom property animates on the main thread and each frame repaints the
- * vector paths in place, as sharp as at rest. */
-@property --wp-wl-x { syntax: "<length>"; inherits: false; initial-value: 0px; }
-@property --wp-wl-f { syntax: "<number>"; inherits: false; initial-value: 0; }
-@property --wp-wl-r { syntax: "<angle>"; inherits: false; initial-value: 0deg; }
-@property --wp-wl-s { syntax: "<number>"; inherits: false; initial-value: 1; }
+/* The marks move on the canvas; the SVG is the still mark under it. */
+.wp-wl__art { position: relative; display: inline-block; flex-shrink: 0; line-height: 0; }
+.wp-wl__logo { display: block; }
+.wp-wl__canvas { position: absolute; pointer-events: none; }
+.wp-wl[data-drawn="true"] .wp-wl__logo { visibility: hidden; }
+
 @property --wp-wl-o { syntax: "<number>"; inherits: false; initial-value: 1; }
 @property --wp-wl-wo { syntax: "<number>"; inherits: false; initial-value: 1; }
 @property --wp-wl-wb { syntax: "<length>"; inherits: false; initial-value: 0px; }
 
-.wp-wl__star, .wp-wl__dot, .wp-wl__hop { transform-box: fill-box; transform-origin: center; }
-.wp-wl__vb { transform-box: view-box; transform-origin: 512px 512px; }
-
-/* Typing stars: each hops in turn. */
-.wp-wl__hop {
-  transform: translateY(var(--wp-wl-x)) scale(var(--wp-wl-s));
-  animation: wp-wl-hop var(--wp-wl-t) ease-in-out infinite;
-  animation-delay: calc(var(--wp-wl-t) * var(--wp-wl-k) * 0.15);
-}
-@keyframes wp-wl-hop {
-  0%, 40%, 100% { --wp-wl-x: 0px; --wp-wl-s: 1; }
-  20% { --wp-wl-x: -110px; --wp-wl-s: 1.12; }
-}
-
-/* Shuffle: the small stars swap places, the big one dips and turns. */
-.wp-wl__swap {
-  transform: rotate(var(--wp-wl-r));
-  animation: wp-wl-swap calc(var(--wp-wl-t) * 2) cubic-bezier(0.65, 0, 0.35, 1) infinite;
-}
-.wp-wl__dip {
-  transform: rotate(var(--wp-wl-r)) scale(var(--wp-wl-s));
-  animation: wp-wl-dip var(--wp-wl-t) cubic-bezier(0.65, 0, 0.35, 1) infinite;
-}
-@keyframes wp-wl-swap {
-  0%, 15% { --wp-wl-r: 0deg; }
-  50%, 65% { --wp-wl-r: 180deg; }
-  100% { --wp-wl-r: 360deg; }
-}
-@keyframes wp-wl-dip {
-  0%, 15% { --wp-wl-s: 1; --wp-wl-r: 0deg; }
-  32% { --wp-wl-s: 0.7; --wp-wl-r: 45deg; }
-  50%, 100% { --wp-wl-s: 1; --wp-wl-r: 90deg; }
-}
-
-/* Orbit: the four nodes circle the stars and twinkle in turn. */
-.wp-wl__spin {
-  transform: rotate(var(--wp-wl-r));
-  animation: wp-wl-spin calc(var(--wp-wl-t) * 2) cubic-bezier(0.5, 0.1, 0.5, 0.9) infinite;
-}
-.wp-wl__dot {
-  opacity: var(--wp-wl-o);
-  transform: scale(var(--wp-wl-s));
-  animation: wp-wl-twinkle var(--wp-wl-t) ease-in-out infinite;
-  animation-delay: calc(var(--wp-wl-t) * var(--wp-wl-k) * -0.25);
-}
-.wp-wl__breathe {
-  transform: scale(var(--wp-wl-s));
-  animation: wp-wl-breathe var(--wp-wl-t) ease-in-out infinite;
-}
-@keyframes wp-wl-spin { from { --wp-wl-r: 0deg; } to { --wp-wl-r: 360deg; } }
-@keyframes wp-wl-twinkle {
-  0%, 100% { --wp-wl-o: 1; --wp-wl-s: 1; }
-  50% { --wp-wl-o: 0.35; --wp-wl-s: 0.6; }
-}
-@keyframes wp-wl-breathe { 0%, 100% { --wp-wl-s: 1; } 50% { --wp-wl-s: 0.86; } }
-
-/* Burst: the small stars fly out of the big one and back. `--wp-wl-f` is
- * how far out they are (1 = at --wp-wl-dx/dy, 0 = home). */
-.wp-wl__burst {
-  opacity: var(--wp-wl-o);
-  transform:
-    translate(calc(var(--wp-wl-dx) * var(--wp-wl-f)), calc(var(--wp-wl-dy) * var(--wp-wl-f)))
-    scale(var(--wp-wl-s));
-  animation: wp-wl-burst var(--wp-wl-t) cubic-bezier(0.3, 0, 0.2, 1) infinite;
-}
-.wp-wl__pop {
-  transform: scale(var(--wp-wl-s));
-  animation: wp-wl-pop var(--wp-wl-t) ease-in-out infinite;
-}
-@keyframes wp-wl-burst {
-  0% { --wp-wl-f: 1; --wp-wl-s: 0; --wp-wl-o: 0; }
-  15% { --wp-wl-o: 1; }
-  45%, 75% { --wp-wl-f: 0; --wp-wl-s: 1.15; --wp-wl-o: 1; }
-  100% { --wp-wl-f: 1; --wp-wl-s: 0; --wp-wl-o: 0; }
-}
-@keyframes wp-wl-pop { 0%, 100% { --wp-wl-s: 1.1; } 40% { --wp-wl-s: 0.8; } }
-
 @media (prefers-reduced-motion: reduce) {
-  .wp-wl__logo * { animation: none !important; }
   .wp-wl__logo { opacity: var(--wp-wl-o); animation: wp-wl-fade 2.4s ease-in-out infinite; }
   @keyframes wp-wl-fade { 0%, 100% { --wp-wl-o: 1; } 50% { --wp-wl-o: 0.55; } }
 }

package/src/canvas-motion.ts

@@ -0,0 +1,251 @@
+/**
+ * Looping marks drawn on a canvas (LoadingMark, WorkingLine).
+ *
+ * A keyframed `transform` / `opacity` on an SVG path goes to the compositor,
+ * which blurs the path and snaps it to whole pixels as it starts. Animating
+ * registered custom properties fixed that in Chromium, but Firefox still lays
+ * each frame of an SVG transform on the pixel grid, so small marks stepped
+ * and twitched as they moved. A canvas puts every shape at its exact
+ * fractional position each frame, sharp and smooth in both.
+ *
+ * One `requestAnimationFrame` loop draws every mark on the page. Each mark
+ * keeps its own clock, so a host can slow or pause the marks inside it with
+ * `data-wp-motion-speed` (a number) and `data-wp-motion-paused` on an
+ * ancestor, as the kit site's Animations section does.
+ *
+ * A mark keeps its still SVG for the first paint, under reduced motion and
+ * in a test DOM; `useCanvasMotion` puts the canvas over it once it can draw.
+ */
+import { nextTick, onBeforeUnmount, onMounted, ref, type Ref } from "vue";
+
+/** Room around the 1024 box for parts that move past its edge, and for
+ *  anti-aliasing there. */
+export const PAD = 82;
+export const BOX = 1024 + 2 * PAD;
+
+/** CSS `cubic-bezier(x1, y1, x2, y2)` as a function of progress. */
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number): (x: number) => number {
+  return (x) => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    let lo = 0;
+    let hi = 1;
+    let t = x;
+    for (let k = 0; k < 30; k++) {
+      t = (lo + hi) / 2;
+      const cx = 3 * x1 * t * (1 - t) ** 2 + 3 * x2 * t * t * (1 - t) + t ** 3;
+      if (cx < x) lo = t;
+      else hi = t;
+    }
+    return 3 * y1 * t * (1 - t) ** 2 + 3 * y2 * t * t * (1 - t) + t ** 3;
+  };
+}
+
+export const EASE = cubicBezier(0.25, 0.1, 0.25, 1);
+export const EASE_IN_OUT = cubicBezier(0.42, 0, 0.58, 1);
+export const SMOOTH = cubicBezier(0.65, 0, 0.35, 1);
+
+export type Stop = readonly [at: number, values: readonly number[]];
+
+/** Value of a keyframe track at progress `p` (0..1), eased per segment the
+ *  way CSS eases between two keyframes. */
+export function track(stops: readonly Stop[], p: number, ease: (x: number) => number): number[] {
+  for (let k = 0; k < stops.length - 1; k++) {
+    const a = stops[k];
+    const b = stops[k + 1];
+    if (!a || !b) break;
+    if (p >= a[0] && p <= b[0]) {
+      if (b[0] === a[0]) return [...b[1]];
+      const e = ease((p - a[0]) / (b[0] - a[0]));
+      return a[1].map((v, j) => v + ((b[1][j] ?? v) - v) * e);
+    }
+  }
+  return [...(stops[stops.length - 1]?.[1] ?? [])];
+}
+
+/** Progress (0..1) through a loop of `period` ms, `ms` into the animation.
+ *  A positive `delay` holds the start pose until it has passed, like CSS. */
+export function loop(ms: number, period: number, delay = 0): number {
+  const t = ms - delay;
+  if (t < 0) return 0;
+  return (t % period) / period;
+}
+
+/** Mixes two `#rrggbb` colours in sRGB, like `color-mix(in srgb, a w%, b)`. */
+export function mix(a: string, b: string, weightA: number): string {
+  const ch = (hex: string, i: number): number => parseInt(hex.slice(1 + 2 * i, 3 + 2 * i), 16);
+  const out = [0, 1, 2].map((i) => Math.round(ch(a, i) * weightA + ch(b, i) * (1 - weightA)));
+  return `#${out.map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** Fills `path` scaled and turned around `[x, y]`. */
+export function fillAround(
+  ctx: CanvasRenderingContext2D,
+  [x, y]: readonly [number, number],
+  scale: number,
+  turn: number,
+  path: Path2D,
+  fill: string | CanvasGradient,
+  alpha = 1,
+): void {
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((turn * Math.PI) / 180);
+  ctx.scale(scale, scale);
+  ctx.translate(-x, -y);
+  ctx.globalAlpha = alpha;
+  ctx.fillStyle = fill;
+  ctx.fill(path);
+  ctx.restore();
+}
+
+/** Clears the canvas and sets it up to draw in the 1024 box. */
+export function begin(ctx: CanvasRenderingContext2D, width: number): void {
+  const k = width / BOX;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, width, width);
+  ctx.setTransform(k, 0, 0, k, PAD * k, PAD * k);
+}
+
+/** Draws one frame `ms` into the animation on a square canvas `width` px wide. */
+export type Draw = (ctx: CanvasRenderingContext2D, width: number, ms: number) => void;
+
+/** A mark the loop draws. */
+export interface Animated {
+  canvas: HTMLCanvasElement;
+  draw: Draw;
+  /** ms of animation shown so far, advanced by the loop. */
+  clock: number;
+  /** False while off screen: the clock still runs, nothing is drawn. */
+  visible: boolean;
+}
+
+const marks = new Set<Animated>();
+let frame = 0;
+let last = 0;
+
+/** Speed and pause from the nearest host that sets them. */
+export function motionOf(el: Element): { speed: number; paused: boolean } {
+  const paused = el.closest("[data-wp-motion-paused]") !== null;
+  const speedHost = el.closest("[data-wp-motion-speed]");
+  const speed = Number(speedHost?.getAttribute("data-wp-motion-speed") ?? "1");
+  return { speed: Number.isFinite(speed) && speed >= 0 ? speed : 1, paused };
+}
+
+function fit(c: HTMLCanvasElement): void {
+  const want = Math.max(1, Math.round(c.clientWidth * (window.devicePixelRatio || 1)));
+  if (c.width !== want) {
+    c.width = want;
+    c.height = want;
+  }
+}
+
+function paint(m: Animated): boolean {
+  const ctx = m.canvas.getContext("2d");
+  if (!ctx) return false;
+  fit(m.canvas);
+  m.draw(ctx, m.canvas.width, m.clock);
+  return true;
+}
+
+function tick(now: number): void {
+  const dt = last ? Math.min(now - last, 100) : 0;
+  last = now;
+  for (const m of marks) {
+    const { speed, paused } = motionOf(m.canvas);
+    if (!paused) m.clock += dt * speed;
+    if (m.visible) paint(m);
+  }
+  frame = marks.size ? requestAnimationFrame(tick) : 0;
+}
+
+/** Starts drawing a mark; returns the function that stops it. */
+export function animate(mark: Animated): () => void {
+  marks.add(mark);
+  if (!frame) {
+    last = 0;
+    frame = requestAnimationFrame(tick);
+  }
+  return () => {
+    marks.delete(mark);
+    if (!marks.size && frame) {
+      cancelAnimationFrame(frame);
+      frame = 0;
+    }
+  };
+}
+
+/** Draws one frame right away (before the loop runs, so the mark never
+ *  shows blank). False when there is no 2D canvas. */
+export function drawNow(mark: Animated): boolean {
+  return paint(mark);
+}
+
+/** Inline style for a canvas over a `px`-wide mark, reaching PAD past it. */
+export function canvasBox(px: number): Record<string, string> {
+  const side = (px * BOX) / 1024;
+  const off = (px * PAD) / 1024;
+  return { width: `${side}px`, height: `${side}px`, top: `${-off}px`, left: `${-off}px` };
+}
+
+/**
+ * Runs a mark's canvas while motion is allowed. Render
+ * `<canvas v-if="live" ref="canvas">` over the still SVG, and hide the SVG
+ * while `drawn`.
+ */
+export function useCanvasMotion(canvas: Ref<HTMLCanvasElement | null>, draw: Draw): { live: Ref<boolean>; drawn: Ref<boolean> } {
+  const live = ref(false);
+  const drawn = ref(false);
+  let stop: (() => void) | null = null;
+  let observer: IntersectionObserver | null = null;
+  let motion: MediaQueryList | null = null;
+
+  async function start(): Promise<void> {
+    if (stop) return;
+    live.value = true;
+    await nextTick();
+    const el = canvas.value;
+    if (!el || !live.value) return;
+    const mark: Animated = { canvas: el, draw, clock: 0, visible: true };
+    if (!drawNow(mark)) {
+      live.value = false;
+      return;
+    }
+    drawn.value = true;
+    stop = animate(mark);
+    if (typeof IntersectionObserver === "function") {
+      observer = new IntersectionObserver((entries) => {
+        for (const e of entries) mark.visible = e.isIntersecting;
+      });
+      observer.observe(el);
+    }
+  }
+  function halt(): void {
+    stop?.();
+    stop = null;
+    observer?.disconnect();
+    observer = null;
+    live.value = false;
+    drawn.value = false;
+  }
+  function onMotionChange(): void {
+    if (motion?.matches) halt();
+    else void start();
+  }
+
+  onMounted(() => {
+    // No matchMedia means no way to honour reduced motion, and a test DOM
+    // (jsdom) has no canvas and logs an error for every attempt: keep the
+    // still SVG in both.
+    if (typeof window.matchMedia !== "function" || typeof requestAnimationFrame !== "function") return;
+    if (navigator.userAgent.includes("jsdom")) return;
+    motion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    motion.addEventListener?.("change", onMotionChange);
+    if (!motion.matches) void start();
+  });
+  onBeforeUnmount(() => {
+    motion?.removeEventListener?.("change", onMotionChange);
+    halt();
+  });
+  return { live, drawn };
+}

package/src/kind-colour.ts

@@ -1,7 +1,8 @@
 /**
  * The colour of each module type, for a Chip (or anything else) that names
  * one: the `--wp-kind-*` colour the extension uses for that type, bundles
- * slate. There is no kind chip: a kind is a Chip with this colour.
+ * slate, and its icon (`kindIcon`). There is no kind chip: a kind is a Chip
+ * with this colour.
  *
  *   <Chip :color="kindColour(itemType(post.kind, post.subtype))">{{ itemType(post.kind, post.subtype) }}</Chip>
  */
@@ -26,3 +27,25 @@ export function itemType(kind: "module" | "bundle", subtype?: ItemType | null):
 export function kindColour(type: ItemType): string {
   return COLOURS[type];
 }
+
+/** The PrimeIcons name (for Icon / ListRow `icon`) of each item type: the
+ *  same icons the extension's kind-icons map uses. */
+const ICONS: Record<ItemType, string> = {
+  wildcard: "sparkles",
+  fixed_values: "tag",
+  combine: "link",
+  derivation: "arrow-right-arrow-left",
+  constraint: "filter",
+  bundle: "box",
+};
+
+/** The icon of a type read from a payload (any string): `circle` for a type
+ *  the kit doesn't know. */
+export function kindIcon(type: string): string {
+  return (ICONS as Record<string, string>)[type] ?? "circle";
+}
+
+/** A payload's type string as a module subtype, or null when it isn't one. */
+export function moduleSubtype(type: string): ModuleSubtype | null {
+  return type === "fixed_values" || type === "combine" || type === "wildcard" || type === "constraint" || type === "derivation" ? type : null;
+}

package/src/linkify.ts

@@ -0,0 +1,142 @@
+/**
+ * Dependency-free, pure rich-text segmenter for prose (post descriptions).
+ *
+ * Splits a plain-text string into an ordered list of {@link RichSeg}s so the
+ * renderer (`RichText.vue`) can paint each piece as a Vue node, never via
+ * `v-html`. Because every segment is interpolated as a text node
+ * or a plain `<a>`/`<code>` with attribute-bound values, the output is
+ * XSS-safe by construction: a `<script>` in the input is just text.
+ *
+ * A single left-to-right scan recognises, in priority order:
+ *   1. `@{...}`        wildcard-ref code token (e.g. `@{color:cool and dark}`)
+ *   2. `$name(.field)` var/accessor code token (e.g. `$color`, `$color.2`)
+ *   3. `https?://…`    explicit URL
+ *   4. bare URL        a `domain.tld/path` or `www.…` (must carry a `/path`)
+ * Everything else accumulates as literal text. Adjacent text runs collapse
+ * into one `text` segment.
+ *
+ * URL handling:
+ *   - Trailing punctuation `.,;:!?)` is peeled off the match and pushed back
+ *     as text, so `(see https://x.com).` doesn't swallow the `).`.
+ *   - http(s) matches keep their scheme as the href; bare/`www.` matches are
+ *     prefixed with `https://`.
+ *   - A `link` segment is emitted ONLY when the resulting href starts with
+ *     `http://` or `https://`; anything else degrades to text.
+ *
+ * Lossless invariant: concatenating every `.text` reproduces the input.
+ *
+ * Why not rich-tokenize.ts: that is the wildcard GRAMMAR lexer (picks,
+ * escapes, `@{8hex}` refs only), and a description is prose: `{a|b}` must
+ * stay text, `$$` is just two dollars, and a mention like `@{color:cool}`
+ * names a wildcard in words. This scanner only marks mentions and links.
+ */
+
+export type RichSeg = {
+  kind: "text" | "link" | "code";
+  text: string;
+  /** Present only on `link` segments — always an `http(s)://` absolute URL. */
+  href?: string;
+};
+
+// Code token: `@{...}` (ref). Non-greedy body, no nested `}`.
+const RE_REF = /^@\{[^}]*\}/;
+// Code token: `$name` with an optional single `.field` accessor.
+const RE_VAR = /^\$[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)?/;
+// Explicit URL with scheme — runs to the next whitespace.
+const RE_URL = /^https?:\/\/[^\s]+/;
+// Bare URL: either a `www.` host, OR a `domain.tld/` (a dotted host directly
+// followed by a `/path`). Requires the `/` so prose like `e.g.` or `node.com`
+// without a path is NOT linkified (kept conservative on purpose).
+const RE_BARE = /^(?:www\.|[a-z0-9-]+(?:\.[a-z0-9-]+)+\/)[^\s]+/i;
+
+/** Trailing punctuation peeled off a matched URL and returned as text. */
+const TRAILING = new Set([".", ",", ";", ":", "!", "?", ")"]);
+
+/**
+ * Segment `input` into ordered text / link / code runs. Returns an empty
+ * array for empty input; the caller decides what to render for `[]`.
+ */
+export function parseRichText(input: string): RichSeg[] {
+  if (!input) return [];
+
+  const segs: RichSeg[] = [];
+  let buf = "";
+
+  /** Flush the pending literal-text run (if any) as one `text` segment. */
+  const flush = (): void => {
+    if (buf) {
+      segs.push({ kind: "text", text: buf });
+      buf = "";
+    }
+  };
+
+  let i = 0;
+  const n = input.length;
+  while (i < n) {
+    const rest = input.slice(i);
+    const ch = input[i];
+
+    // 1. @{...} ref code token.
+    if (ch === "@") {
+      const m = rest.match(RE_REF);
+      if (m) {
+        flush();
+        segs.push({ kind: "code", text: m[0] });
+        i += m[0].length;
+        continue;
+      }
+    }
+
+    // 2. $var code token.
+    if (ch === "$") {
+      const m = rest.match(RE_VAR);
+      if (m) {
+        flush();
+        segs.push({ kind: "code", text: m[0] });
+        i += m[0].length;
+        continue;
+      }
+    }
+
+    // 3 + 4. URLs — explicit scheme first, then bare/`www.`.
+    //
+    // A bare match is only attempted at a word boundary (start of input or
+    // after whitespace) so we don't linkify the tail of a longer token.
+    const atBoundary = i === 0 || /\s/.test(input[i - 1] ?? "");
+    const urlMatch =
+      rest.match(RE_URL) ?? (atBoundary ? rest.match(RE_BARE) : null);
+    if (urlMatch) {
+      let raw = urlMatch[0];
+      // Peel trailing punctuation back into the text stream.
+      let trailer = "";
+      let last = raw.slice(-1);
+      while (last && TRAILING.has(last)) {
+        trailer = last + trailer;
+        raw = raw.slice(0, -1);
+        last = raw.slice(-1);
+      }
+      if (raw.length > 0) {
+        const href = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+        // Only emit a link when the href is genuinely http(s); otherwise the
+        // whole match degrades to text (defensive — the prefix above always
+        // satisfies this, but keeps the contract explicit).
+        if (/^https?:\/\//i.test(href)) {
+          flush();
+          segs.push({ kind: "link", text: raw, href });
+        } else {
+          buf += raw;
+        }
+        if (trailer) buf += trailer;
+        i += raw.length + trailer.length;
+        continue;
+      }
+    }
+
+    // Default: accumulate one literal character.
+    buf += ch;
+    i += 1;
+  }
+
+  flush();
+  return segs;
+}