@dumiflex/wp-kit 0.3.0 → 0.4.0

package/src/image-zoom.ts

@@ -1,93 +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 };
-}
+/**
+ * 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/kind-colour.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ *   <Chip :color="kindColour(itemType(post.kind, post.subtype))">{{ itemType(post.kind, post.subtype) }}</Chip>
+ */
+export type ModuleSubtype = "fixed_values" | "combine" | "wildcard" | "constraint" | "derivation";
+export type ItemType = ModuleSubtype | "bundle";
+
+const COLOURS: Record<ItemType, string> = {
+  fixed_values: "var(--wp-kind-fixed)",
+  combine: "var(--wp-kind-combine)",
+  wildcard: "var(--wp-kind-wildcard)",
+  constraint: "var(--wp-kind-constraint)",
+  derivation: "var(--wp-kind-derivation)",
+  bundle: "var(--wp-bundle-default)",
+};
+
+/** A post or library item's type. A module with no subtype reads as
+ *  `fixed_values` (the oldest type); a `"bundle"` subtype reads as a bundle. */
+export function itemType(kind: "module" | "bundle", subtype?: ItemType | null): ItemType {
+  return kind === "bundle" ? "bundle" : (subtype ?? "fixed_values");
+}
+
+export function kindColour(type: ItemType): string {
+  return COLOURS[type];
+}

package/src/logo-paths.ts

@@ -1,21 +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;
+/** 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;

package/src/matrix-axis.ts

@@ -1,91 +1,91 @@
-/**
- * Constraint-matrix axis grouping — the pure logic shared by both matrix
- * surfaces (the SPA `ConstraintMatrix.vue` library editor and the canvas
- * `MatrixSection.vue` instance modal). Keeping it here means the two grids
- * order, group, label and colour their axes identically; only their template
- * + CSS differ.
- *
- * A wildcard's `tag_groups` (axis name → member sub-categories) drives the
- * layout: tags are ordered by axis, each axis becomes a coloured band
- * (columns) or pinned header chip (rows), and the leftover run of tags with
- * no axis becomes the labelled "uncategorized" bucket instead of a blank.
- */
-import { axisHueAt } from "./axis-color";
-
-/** One tag stamped with its axis + whether it opens a new group. Cell lookups
- *  stay keyed by tag name, so reordering for display is safe. */
-export interface TagMeta {
-  tag: string;
-  axisIndex: number; // -1 = ungrouped
-  axisName: string;
-  groupStart: boolean; // first tag of its axis
-}
-
-/** A contiguous run of tags belonging to one axis (or the trailing ungrouped
- *  run). Columns render one band per group; row groups with >1 tag get a
- *  header chip, solo named groups fold the name into the tag. */
-export interface AxisGroup {
-  axisIndex: number; // -1 = ungrouped
-  axisName: string;
-  tags: string[];
-  grouped: boolean;
-}
-
-/** Order `tags` by axis (grouped first, in axis order; ungrouped last) and
- *  stamp each with its axis index + whether it opens a new group. */
-export function orderByGroups(tags: string[], groups: Record<string, string[]>): TagMeta[] {
-  const out: TagMeta[] = [];
-  const seen = new Set<string>();
-  Object.keys(groups).forEach((axis, ai) => {
-    let first = true;
-    for (const t of groups[axis] ?? []) {
-      if (seen.has(t) || !tags.includes(t)) continue;
-      seen.add(t);
-      out.push({ tag: t, axisIndex: ai, axisName: axis, groupStart: first });
-      first = false;
-    }
-  });
-  let firstUngrouped = true;
-  for (const t of tags) {
-    if (seen.has(t)) continue;
-    out.push({ tag: t, axisIndex: -1, axisName: "", groupStart: firstUngrouped });
-    firstUngrouped = false;
-  }
-  return out;
-}
-
-/** Collapse an ordered `TagMeta[]` into contiguous axis groups. */
-export function toGroups(ordered: TagMeta[]): AxisGroup[] {
-  const groups: AxisGroup[] = [];
-  for (const m of ordered) {
-    if (m.groupStart || groups.length === 0) {
-      groups.push({ axisIndex: m.axisIndex, axisName: m.axisName, tags: [], grouped: m.axisIndex >= 0 });
-    }
-    groups[groups.length - 1].tags.push(m.tag);
-  }
-  return groups;
-}
-
-/** A "bucket" is the catch-all uncategorized run: no axis, or a blank axis
- *  name. Buckets are labelled "uncategorized" + tinted neutral rather than
- *  rendered blank. */
-export function isBucket(grp: AxisGroup): boolean {
-  return !grp.grouped || grp.axisName.trim().length === 0;
-}
-
-/** Display label for a group's band / chip. */
-export function groupLabel(grp: AxisGroup): string {
-  return isBucket(grp) ? "uncategorized" : grp.axisName;
-}
-
-/** Neutral grey for the uncategorized bucket — distinct from the per-axis
- *  palette so it doesn't read as a real named axis. */
-export const UNGROUPED_HUE = "var(--wp-text-muted, #8a8a9a)";
-
-/** Hue for a group's chips / band / tags. Named axes take the shared palette;
- *  the uncategorized bucket goes neutral grey when it's labelled (mixed
- *  layout), else keeps the legacy source/target tint (fully-flat matrix). */
-export function groupHue(grp: AxisGroup, role: "source" | "target", labeled: boolean): string {
-  if (!isBucket(grp)) return axisHueAt(grp.axisIndex);
-  return labeled ? UNGROUPED_HUE : role === "source" ? "var(--wp-constraint-source)" : "var(--wp-constraint-target)";
-}
+/**
+ * Constraint-matrix axis grouping — the pure logic shared by both matrix
+ * surfaces (the SPA `ConstraintMatrix.vue` library editor and the canvas
+ * `MatrixSection.vue` instance modal). Keeping it here means the two grids
+ * order, group, label and colour their axes identically; only their template
+ * + CSS differ.
+ *
+ * A wildcard's `tag_groups` (axis name → member sub-categories) drives the
+ * layout: tags are ordered by axis, each axis becomes a coloured band
+ * (columns) or pinned header chip (rows), and the leftover run of tags with
+ * no axis becomes the labelled "uncategorized" bucket instead of a blank.
+ */
+import { axisHueAt } from "./axis-color";
+
+/** One tag stamped with its axis + whether it opens a new group. Cell lookups
+ *  stay keyed by tag name, so reordering for display is safe. */
+export interface TagMeta {
+  tag: string;
+  axisIndex: number; // -1 = ungrouped
+  axisName: string;
+  groupStart: boolean; // first tag of its axis
+}
+
+/** A contiguous run of tags belonging to one axis (or the trailing ungrouped
+ *  run). Columns render one band per group; row groups with >1 tag get a
+ *  header chip, solo named groups fold the name into the tag. */
+export interface AxisGroup {
+  axisIndex: number; // -1 = ungrouped
+  axisName: string;
+  tags: string[];
+  grouped: boolean;
+}
+
+/** Order `tags` by axis (grouped first, in axis order; ungrouped last) and
+ *  stamp each with its axis index + whether it opens a new group. */
+export function orderByGroups(tags: string[], groups: Record<string, string[]>): TagMeta[] {
+  const out: TagMeta[] = [];
+  const seen = new Set<string>();
+  Object.keys(groups).forEach((axis, ai) => {
+    let first = true;
+    for (const t of groups[axis] ?? []) {
+      if (seen.has(t) || !tags.includes(t)) continue;
+      seen.add(t);
+      out.push({ tag: t, axisIndex: ai, axisName: axis, groupStart: first });
+      first = false;
+    }
+  });
+  let firstUngrouped = true;
+  for (const t of tags) {
+    if (seen.has(t)) continue;
+    out.push({ tag: t, axisIndex: -1, axisName: "", groupStart: firstUngrouped });
+    firstUngrouped = false;
+  }
+  return out;
+}
+
+/** Collapse an ordered `TagMeta[]` into contiguous axis groups. */
+export function toGroups(ordered: TagMeta[]): AxisGroup[] {
+  const groups: AxisGroup[] = [];
+  for (const m of ordered) {
+    if (m.groupStart || groups.length === 0) {
+      groups.push({ axisIndex: m.axisIndex, axisName: m.axisName, tags: [], grouped: m.axisIndex >= 0 });
+    }
+    groups[groups.length - 1].tags.push(m.tag);
+  }
+  return groups;
+}
+
+/** A "bucket" is the catch-all uncategorized run: no axis, or a blank axis
+ *  name. Buckets are labelled "uncategorized" + tinted neutral rather than
+ *  rendered blank. */
+export function isBucket(grp: AxisGroup): boolean {
+  return !grp.grouped || grp.axisName.trim().length === 0;
+}
+
+/** Display label for a group's band / chip. */
+export function groupLabel(grp: AxisGroup): string {
+  return isBucket(grp) ? "uncategorized" : grp.axisName;
+}
+
+/** Neutral grey for the uncategorized bucket — distinct from the per-axis
+ *  palette so it doesn't read as a real named axis. */
+export const UNGROUPED_HUE = "var(--wp-text-muted, #8a8a9a)";
+
+/** Hue for a group's chips / band / tags. Named axes take the shared palette;
+ *  the uncategorized bucket goes neutral grey when it's labelled (mixed
+ *  layout), else keeps the legacy source/target tint (fully-flat matrix). */
+export function groupHue(grp: AxisGroup, role: "source" | "target", labeled: boolean): string {
+  if (!isBucket(grp)) return axisHueAt(grp.axisIndex);
+  return labeled ? UNGROUPED_HUE : role === "source" ? "var(--wp-constraint-source)" : "var(--wp-constraint-target)";
+}

package/src/pagination.ts

@@ -1,27 +1,27 @@
-/**
- * The page numbers a Pagination shows: always the first and last page, the
- * current page with `siblings` on each side, and "…" where pages are left
- * out. A gap of exactly one page shows that page instead of "…", so the row
- * keeps the same length as you move through it.
- */
-export type PageItem = number | "gap-start" | "gap-end";
-
-export function pageItems(page: number, pages: number, siblings = 1): PageItem[] {
-  if (pages <= 0) return [];
-  const slots = siblings * 2 + 5;
-  if (pages <= slots) return Array.from({ length: pages }, (_, i) => i + 1);
-  const cur = Math.min(Math.max(1, page), pages);
-  const left = Math.max(cur - siblings, 1);
-  const right = Math.min(cur + siblings, pages);
-  const showStart = left > 3;
-  const showEnd = right < pages - 2;
-  if (!showStart) {
-    const n = siblings * 2 + 3;
-    return [...Array.from({ length: n }, (_, i) => i + 1), "gap-end", pages];
-  }
-  if (!showEnd) {
-    const n = siblings * 2 + 3;
-    return [1, "gap-start", ...Array.from({ length: n }, (_, i) => pages - n + 1 + i)];
-  }
-  return [1, "gap-start", ...Array.from({ length: right - left + 1 }, (_, i) => left + i), "gap-end", pages];
-}
+/**
+ * The page numbers a Pagination shows: always the first and last page, the
+ * current page with `siblings` on each side, and "…" where pages are left
+ * out. A gap of exactly one page shows that page instead of "…", so the row
+ * keeps the same length as you move through it.
+ */
+export type PageItem = number | "gap-start" | "gap-end";
+
+export function pageItems(page: number, pages: number, siblings = 1): PageItem[] {
+  if (pages <= 0) return [];
+  const slots = siblings * 2 + 5;
+  if (pages <= slots) return Array.from({ length: pages }, (_, i) => i + 1);
+  const cur = Math.min(Math.max(1, page), pages);
+  const left = Math.max(cur - siblings, 1);
+  const right = Math.min(cur + siblings, pages);
+  const showStart = left > 3;
+  const showEnd = right < pages - 2;
+  if (!showStart) {
+    const n = siblings * 2 + 3;
+    return [...Array.from({ length: n }, (_, i) => i + 1), "gap-end", pages];
+  }
+  if (!showEnd) {
+    const n = siblings * 2 + 3;
+    return [1, "gap-start", ...Array.from({ length: n }, (_, i) => pages - n + 1 + i)];
+  }
+  return [1, "gap-start", ...Array.from({ length: right - left + 1 }, (_, i) => left + i), "gap-end", pages];
+}

package/src/platform-keys.ts

@@ -1,29 +1,29 @@
-/**
- * Platform-correct labels for the modifier we actually listen for.
- *
- * The save shortcut in our modals is `(ev.ctrlKey || ev.metaKey) && Enter`, so
- * it has always worked on both platforms — but the hint rendered a hardcoded
- * `⌘`, which reads as a Mac-only binding to the ~90% of ComfyUI users on
- * Windows and Linux.
- */
-
-/** True on macOS/iPadOS, where the command key is the accelerator. */
-export function isApplePlatform(): boolean {
-  if (typeof navigator === "undefined") return false;
-  const nav = navigator as Navigator & { userAgentData?: { platform?: string } };
-  // `navigator.platform` is deprecated; prefer the UA-CH hint and fall back to
-  // the user-agent string, which still carries "Macintosh" / "iPhone".
-  const hint = nav.userAgentData?.platform ?? "";
-  if (hint) return /mac/i.test(hint);
-  return /mac|iphone|ipad|ipod/i.test(nav.userAgent ?? "");
-}
-
-/** The accelerator key's symbol: `⌘` on Apple platforms, `Ctrl` elsewhere. */
-export function accelLabel(): string {
-  return isApplePlatform() ? "⌘" : "Ctrl";
-}
-
-/** The full "save" chord as shown in modal footers — `⌘↵` or `Ctrl+↵`. */
-export function saveChordLabel(): string {
-  return isApplePlatform() ? "⌘↵" : "Ctrl+↵";
-}
+/**
+ * Platform-correct labels for the modifier we actually listen for.
+ *
+ * The save shortcut in our modals is `(ev.ctrlKey || ev.metaKey) && Enter`, so
+ * it has always worked on both platforms — but the hint rendered a hardcoded
+ * `⌘`, which reads as a Mac-only binding to the ~90% of ComfyUI users on
+ * Windows and Linux.
+ */
+
+/** True on macOS/iPadOS, where the command key is the accelerator. */
+export function isApplePlatform(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const nav = navigator as Navigator & { userAgentData?: { platform?: string } };
+  // `navigator.platform` is deprecated; prefer the UA-CH hint and fall back to
+  // the user-agent string, which still carries "Macintosh" / "iPhone".
+  const hint = nav.userAgentData?.platform ?? "";
+  if (hint) return /mac/i.test(hint);
+  return /mac|iphone|ipad|ipod/i.test(nav.userAgent ?? "");
+}
+
+/** The accelerator key's symbol: `⌘` on Apple platforms, `Ctrl` elsewhere. */
+export function accelLabel(): string {
+  return isApplePlatform() ? "⌘" : "Ctrl";
+}
+
+/** The full "save" chord as shown in modal footers — `⌘↵` or `Ctrl+↵`. */
+export function saveChordLabel(): string {
+  return isApplePlatform() ? "⌘↵" : "Ctrl+↵";
+}