@dumiflex/wp-kit 0.0.0-stage → 0.4.0

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/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

@@ -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;

package/src/matrix-axis.ts

@@ -0,0 +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)";
+}

package/src/pagination.ts

@@ -0,0 +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];
+}

package/src/platform-keys.ts

@@ -0,0 +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+↵";
+}

package/src/rich-tokenize.ts

@@ -0,0 +1,357 @@
+/**
+ * Wildcard Pipeline rich-text tokenizer: the pure tokenizing surface of the
+ * extension's `src/widgets/richTokenize.ts` lexer (same grammar). It has no
+ * resolution helpers and no HTML emitters: TokenizedValue walks these tokens
+ * in a template, so nothing here needs `v-html`.
+ *
+ * Recognises the following syntactic surface (locked grammar, Tasks 3-7):
+ *
+ *   $varname                     subject placeholder (var)
+ *   @{8hex}                      nested wildcard reference by UUID (ref)
+ *   $$ / @@                      literal-escape sequences (escape)
+ *   {a|b|c}                      inline-choice block (dp-brace, single token)
+ *   {N$$sep$$a|b|c}              multi-select with optional separator (dp-multi)
+ *
+ * Single-token emission for brace blocks: `{a|b|c}` produces ONE `dp-brace`
+ * token whose `meta.branches` lists the raw branch strings. This mirrors the
+ * Python tokenizer exactly and is the contract the corpus (tests/fixtures/
+ * syntax-corpus.json) locks in.
+ *
+ * Lossless invariant: joining all `.raw` fields reproduces the input exactly.
+ *
+ * REMOVED (legacy syntax no longer supported):
+ *   @name short-form ref         - use @{8hex} UUID form instead
+ *   N#$var / N#@ref / N#{...}    quantifier prefix
+ *   # comment to end of line     greyed-out comment line
+ *   dp-pipe / dp-weight          sub-tokens inside brace blocks
+ *
+ * Note: `dp-pipe` and `dp-weight` remain in the TokenKind union for backwards
+ * compatibility with any consumers that reference the type, but the tokenizer
+ * no longer emits them.
+ */
+
+export type TokenKind =
+  | "text"
+  | "var"
+  | "ref"
+  | "dp-brace"
+  | "dp-pipe"    // retained in type only; not emitted by tokenizeRich
+  | "dp-multi"
+  | "dp-weight"  // retained in type only; not emitted by tokenizeRich
+  | "escape";
+// REMOVED: "comment", "quantifier" - dropped in locked grammar (Tasks 3-5)
+
+export interface TokenMeta {
+  // var tokens
+  name?: string;
+  /** SP2a list accessor: `$name.K` -> 0-based index K (omitted when absent). */
+  index?: number;
+  /** Schema v8: `$name.neg` / `$name.K.neg` reads the variable's negatives. */
+  neg?: boolean;
+  // ref tokens
+  uuid?: string;
+  sub_categories?: string[];
+  // escape tokens
+  literal?: string;
+  // dp-brace / dp-multi tokens
+  branches?: string[];
+  // dp-multi tokens
+  count?: number;
+  sep?: string;
+  /** SP2b: count range — `min`==`max` for a fixed `{N$$}`, `min<max` for a
+   *  `{N-M$$}` range. `independent` is the `~` flag (repeats allowed). */
+  min?: number;
+  max?: number;
+  independent?: boolean;
+  // dp-weight tokens (type kept for compat; not emitted)
+  weight?: number;
+  range?: string;
+}
+
+/** SP2a: reduce a var reference to its BASE name — drop an optional leading
+ *  `$` and an optional trailing `.K` list accessor. `$mood.0` -> `mood`;
+ *  `mood` -> `mood`; `weird.name` (non-digit suffix) -> unchanged. Used by
+ *  validation + conflict scanning so a `.K` accessor resolves against the
+ *  bound base var, not a phantom `mood.0`. */
+export function varBaseName(raw: string): string {
+  return raw.replace(/^\$/, "").replace(/\.neg$/, "").replace(/\.\d+$/, "").trim();
+}
+
+export interface RichToken {
+  kind: TokenKind;
+  start: number;
+  end: number;
+  raw: string;
+  meta?: TokenMeta;
+}
+
+/** Peeled view of a nested ref's `:`-filter body. */
+export interface RefFilterParts {
+  /** Boolean sub-category expression, with the `!null` marker removed. */
+  expr: string;
+  /** True when the body carried the trailing `!null` exclude-null marker. */
+  excludeNull: boolean;
+}
+
+/**
+ * Peel a trailing `!null` exclude marker off a ref's raw `:`-body, returning
+ * the pure boolean expression + the exclude-null flag:
+ *   `"warm or intense!null"` → `{ expr: "warm or intense", excludeNull: true }`
+ *   `"warm or cool"`         → `{ expr: "warm or cool",   excludeNull: false }`
+ *
+ * Sub-category names and the boolean expression never contain `!` (see the
+ * grammar in `subcatFilter.ts`), so the only `!` in a serialized body is the
+ * null marker. Single source for the peel that RefChip, the canvas OptionRow,
+ * and RichTextInput's editor model all need — keeps them from re-deriving it
+ * (and drifting) independently.
+ */
+export function splitRefFilter(body: string): RefFilterParts {
+  const bang = body.lastIndexOf("!");
+  if (bang >= 0) {
+    return { expr: body.slice(0, bang).trim(), excludeNull: body.slice(bang + 1) === "null" };
+  }
+  return { expr: body.trim(), excludeNull: false };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (mirrors Python engine/syntax/tokenize.py)
+// ---------------------------------------------------------------------------
+
+/**
+ * Split `s` on `|` at brace-depth zero only. Nested `{a|b}` stays intact.
+ * Mirrors Python `_split_top_level_pipes`.
+ */
+function splitTopLevelPipes(s: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let last = 0;
+  for (let idx = 0; idx < s.length; idx++) {
+    const c = s[idx];
+    if (c === "{") depth++;
+    else if (c === "}") depth--;
+    else if (c === "|" && depth === 0) {
+      parts.push(s.slice(last, idx));
+      last = idx + 1;
+    }
+  }
+  parts.push(s.slice(last));
+  return parts;
+}
+
+// Multi-pick prefix: {N$$sep$$ or {N-M~$$sep$$ — group 1 is the count (fixed
+// `N` or a `N-M` range), group 2 is the optional `~` independent flag (absent
+// = unique), group 3 is the separator. Applied against the whole raw block
+// including the leading `{`. SP2b.
+const MULTI_PREFIX_RE = /^\{(\d+(?:-\d+)?)(~?)\$\$([\s\S]*?)\$\$/;
+
+/**
+ * Try to scan a `{...}` block starting at `text[start]` (must be `{`).
+ *
+ * Returns `[endIndex, branches, count | null, sep | null]` on success, or
+ * `null` if the block is malformed (unclosed, or no top-level pipes for a
+ * plain pick). Mirrors Python `_scan_brace_block`.
+ */
+function scanBraceBlock(
+  text: string,
+  start: number,
+): [number, string[], [number, number, boolean] | null, string | null] | null {
+  const n = text.length;
+  if (start >= n || text[start] !== "{") return null;
+
+  // Walk to the matching `}` tracking depth.
+  let i = start + 1;
+  let depth = 1;
+  while (i < n && depth > 0) {
+    const c = text[i];
+    if (c === "{") depth++;
+    else if (c === "}") depth--;
+    if (depth > 0) i++;
+  }
+  if (depth !== 0) return null; // unclosed
+
+  const bodyStart = start + 1;
+  const bodyEnd = i; // index of closing `}`
+  const endIndex = i + 1;
+  const body = text.slice(bodyStart, bodyEnd);
+
+  // Detect multi-pick prefix: {N$$sep$$...
+  const raw = text.slice(start, endIndex);
+  const multiMatch = raw.match(MULTI_PREFIX_RE);
+  if (multiMatch) {
+    const countRaw = multiMatch[1];                 // "N" or "N-M"
+    const independent = multiMatch[2] === "~";      // SP2b: repeats allowed
+    const sep = multiMatch[3];
+    // Prefix length excluding the leading `{`
+    const prefixLen = multiMatch[0].length - 1;
+    const rest = body.slice(prefixLen);
+    const branches = splitTopLevelPipes(rest);
+    const [lo, hi] = countRaw.includes("-")
+      ? countRaw.split("-")
+      : [countRaw, countRaw];
+    let cmin = parseInt(lo, 10);
+    let cmax = parseInt(hi, 10);
+    if (cmin > cmax) { const t = cmin; cmin = cmax; cmax = t; }
+    return [endIndex, branches, [cmin, cmax, independent], sep];
+  }
+
+  // Plain pick: must contain at least one top-level `|`
+  const branches = splitTopLevelPipes(body);
+  if (branches.length < 2) return null; // fall back to literal text
+
+  return [endIndex, branches, null, null];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk `text` once and emit a flat list of {@link RichToken}s.
+ *
+ * Token shapes mirror the Python tokenizer (`engine/syntax/tokenize.py`) so
+ * the corpus contract holds across both languages.
+ */
+export function tokenizeRich(text: string): RichToken[] {
+  const out: RichToken[] = [];
+  if (!text) return out;
+
+  const N = text.length;
+  let i = 0;
+  // Accumulated start of current literal-text run (null = no run in progress)
+  let textStart: number | null = null;
+
+  function flushText(endAt: number): void {
+    if (textStart === null) return;
+    if (endAt > textStart) {
+      out.push({
+        kind: "text",
+        raw: text.slice(textStart, endAt),
+        start: textStart,
+        end: endAt,
+        meta: {},
+      });
+    }
+    textStart = null;
+  }
+
+  while (i < N) {
+    const ch = text[i];
+
+    // -- Escape sequences: $$ -> literal $, @@ -> literal @ ----------------
+    if (ch === "$" && i + 1 < N && text[i + 1] === "$") {
+      flushText(i);
+      out.push({ kind: "escape", raw: "$$", start: i, end: i + 2, meta: { literal: "$" } });
+      i += 2;
+      continue;
+    }
+    if (ch === "@" && i + 1 < N && text[i + 1] === "@") {
+      flushText(i);
+      out.push({ kind: "escape", raw: "@@", start: i, end: i + 2, meta: { literal: "@" } });
+      i += 2;
+      continue;
+    }
+
+    // -- Variable: $name or $name.K (SP2a list accessor) --------------------
+    if (ch === "$") {
+      // `.match` (not `.exec`) keeps the matcher off the security-hook's radar
+      // while giving the same match-array shape. Group 2 = optional `.K` index.
+      // Group 3 = optional `.neg` (schema v8 negatives read).
+      const m = text
+        .slice(i + 1)
+        .match(/^([A-Za-z_][A-Za-z0-9_]*)(?:\.(\d+))?(\.neg(?![A-Za-z0-9_]))?/);
+      if (m) {
+        flushText(i);
+        const raw =
+          "$" + m[1] + (m[2] !== undefined ? "." + m[2] : "") + (m[3] ?? "");
+        const meta: { name: string; index?: number; neg?: boolean } = { name: m[1] };
+        if (m[2] !== undefined) meta.index = parseInt(m[2], 10);
+        if (m[3] !== undefined) meta.neg = true;
+        out.push({
+          kind: "var",
+          raw,
+          start: i,
+          end: i + raw.length,
+          meta,
+        });
+        i += raw.length;
+        continue;
+      }
+      // Lone $ or $ not followed by ident -- fall through to text accumulation
+    }
+
+    // -- Ref: @{8hex} or @{8hex#name:expr!null} -----------------------------
+    // Optional `:expr` is an SP1 boolean sub-category filter (`warm or
+    // intense`, `not cool`, parens; comma = or) with an optional trailing
+    // `!null` exclude-null marker. The lexer does NOT parse the grammar — it
+    // just captures the raw `:`-body, comma-split into `sub_categories` for
+    // legacy callers. Downstream (RichTextInput, validateModule) rejoins on
+    // `,`, peels `!null`, and hands the rest to the shared subcat-filter
+    // parser. Keeps one library wildcard reusable while each call site
+    // narrows surgically (e.g. `@{color:warm}` vs `@{color:cool or warm}`).
+    // Empty filter → no filter.
+    if (ch === "@") {
+      // Groups: 1=uuid, 2=optional `#name` cache, 3=optional subcat filter.
+      const refMatch = text.slice(i).match(/^@\{([0-9a-f]{8})(?:#([^#:}@{]*))?(?::([^}]*))?\}/);
+      if (refMatch) {
+        flushText(i);
+        const filterRaw = refMatch[3];
+        const subCategories =
+          typeof filterRaw === "string"
+            ? filterRaw.split(",").map((s) => s.trim()).filter(Boolean)
+            : [];
+        const meta: { uuid: string; name?: string; sub_categories?: string[] } = { uuid: refMatch[1] };
+        if (refMatch[2]) meta.name = refMatch[2];
+        if (subCategories.length > 0) meta.sub_categories = subCategories;
+        out.push({
+          kind: "ref",
+          raw: refMatch[0],
+          start: i,
+          end: i + refMatch[0].length,
+          meta,
+        });
+        i += refMatch[0].length;
+        continue;
+      }
+      // Not a ref -- fall through to text accumulation
+    }
+
+    // -- Brace block: {a|b|c} or {N$$sep$$a|b|c} ---------------------------
+    if (ch === "{") {
+      const scanned = scanBraceBlock(text, i);
+      if (scanned !== null) {
+        const [endIndex, branches, count, sep] = scanned;
+        flushText(i);
+        if (count === null) {
+          out.push({
+            kind: "dp-brace",
+            raw: text.slice(i, endIndex),
+            start: i,
+            end: endIndex,
+            meta: { branches },
+          });
+        } else {
+          const [cmin, cmax, independent] = count;
+          out.push({
+            kind: "dp-multi",
+            raw: text.slice(i, endIndex),
+            start: i,
+            end: endIndex,
+            // `count` kept == max for back-compat; min/max carry the range,
+            // independent carries the `~` flag (SP2b). Mirrors the Python meta.
+            meta: { min: cmin, max: cmax, independent, count: cmax, sep: sep ?? "", branches },
+          });
+        }
+        i = endIndex;
+        continue;
+      }
+      // Malformed brace -- fall through to literal text
+    }
+
+    // -- Default: accumulate literal text ------------------------------------
+    if (textStart === null) textStart = i;
+    i++;
+  }
+
+  flushText(N);
+  return out;
+}