@aaqu/fromcubes-react 0.2.0 → 0.2.2

package/nodes/editor/file-tree.js

@@ -7,7 +7,7 @@
  * module is a pair of pure functions so it can be unit-tested under vitest and
  * still be loaded as a plain browser script by the Node-RED editor.
  *
- * Loaded in the browser via `<script src="fromcubes-react/editor/file-tree.js">`
+ * Loaded in the browser by the asset loader in portal-react.html (`<base>/editor/file-tree.js`)
  * (exposes `window.__fcFileTree`) and in tests via `require()`.
  */
 (function (root, factory) {

package/nodes/editor/format.js

@@ -13,7 +13,7 @@
   "use strict";
 
   const PREFIX = "[FC-Format]";
-  const BASE = "fromcubes-react/prettier/";
+  const BASE = (window.__fcAssetBase || "fromcubes-react/") + "prettier/";
   // UMD builds: each sets window.prettier / window.prettierPlugins.
   const SCRIPTS = [
     "standalone.js",

package/nodes/editor/provider-settings.js

@@ -1,10 +1,10 @@
 /**
- * Settings → Fromcubes: choose the identity provider and the CSS engine.
+ * Settings → Fromcubes: choose the CSS engine and the identity provider.
  *
  * Exactly one provider per kind, shown as a radio list, so two can never be
  * active at once. Reads and writes `/fromcubes-react/providers`; the server
  * validates, persists to <userDir>/fromcubes/providers.json, and applies the
- * change (identity: every portal session reloads; css: every portal rebuilds).
+ * change (css: every portal rebuilds; identity: every portal session reloads).
  * A kind set in settings.js is shown locked.
  *
  * Node-RED shows a pane by the element id `red-ui-settings-tab-<pane id>`,
@@ -18,18 +18,18 @@
   var URL = "fromcubes-react/providers";
 
   var KINDS = [
-    {
-      kind: "identity",
-      title: "Identity provider",
-      hint: "Who is behind a portal session — used by Portal Auth, auth-cast and per-user delivery.",
-      setting: "identityProvider",
-    },
     {
       kind: "css",
       title: "CSS engine",
       hint: "Generates each portal's stylesheet at deploy. Changing it rebuilds every portal.",
       setting: "cssEngine",
     },
+    {
+      kind: "identity",
+      title: "Identity provider",
+      hint: "Who is behind a portal session — used by Portal Auth, auth-cast and per-user delivery.",
+      setting: "identityProvider",
+    },
   ];
 
   function errorText(xhr) {

package/nodes/editor/workspace.js

@@ -19,6 +19,8 @@
   const EDITOR_NAME = "React Editor";
   const FLUSH_DEBOUNCE_MS = 400;
   const MIN_TREE_WIDTH = 150;
+  // Versioned asset path set by portal-react.html (see ASSET_BASE in lib/admin-api.js).
+  const ASSET_BASE = window.__fcAssetBase || "fromcubes-react/";
 
   // ── Module state ────────────────────────────────────────────
 
@@ -636,7 +638,7 @@
    * @returns {void}
    */
   function injectIconSprite() {
-    $.ajax({ url: "fromcubes-react/editor/icons.svg", dataType: "text" })
+    $.ajax({ url: ASSET_BASE + "editor/icons.svg", dataType: "text" })
       .done(function (markup) {
         $("<div>")
           .attr("id", "fc-ws-icon-sprite")
@@ -1107,7 +1109,7 @@
     const brand = $("<div>").addClass("fc-ws-brand").appendTo(header);
     $("<img>")
       .addClass("fc-ws-mark-logo")
-      .attr("src", "fromcubes-react/editor/mark.svg")
+      .attr("src", ASSET_BASE + "editor/mark.svg")
       .attr("alt", "fromcubes")
       .appendTo(brand);
     // One word split by colour — wrapped so the lockup's gap sits between the
@@ -1471,7 +1473,7 @@
       });
     $("<img>")
       .addClass("fc-ws-statusbar-icon")
-      .attr("src", "fromcubes-react/icons/fromcubes-react.svg")
+      .attr("src", ASSET_BASE + "icons/fromcubes-react.svg")
       .attr("alt", "")
       .appendTo(el);
     $("<span>").text(EDITOR_NAME).appendTo(el);

package/nodes/lib/admin-api.js

@@ -1,5 +1,21 @@
 const path = require("path");
 
+/**
+ * Editor assets are also served under a path carrying the core's version
+ * (`fromcubes-react/0.2.0/editor/…`), and the editor template loads them from
+ * there. Every cache in between — the browser, a CDN, a reverse proxy — keys
+ * on the path, so a new release can never be handed an old file, nor a 404
+ * remembered from a moment the route did not exist yet. Query strings are not
+ * enough: some caches ignore them. The unversioned paths stay for anything
+ * that still points at them.
+ */
+const ASSET_VERSION = String(require("../../package.json").version).replace(
+  /[^0-9A-Za-z.+-]/g,
+  "",
+);
+/** Relative to the admin root, as the editor needs it (no leading slash). */
+const ASSET_BASE = "fromcubes-react/" + ASSET_VERSION + "/";
+
 /**
  * Register editor/admin/public support routes for portal-react.
  *
@@ -37,41 +53,36 @@ function registerAdminApi(RED, deps) {
     onProviderChange,
   } = deps;
 
+  /**
+   * Mount one static directory at both its plain and its versioned path.
+   * @param {string} name
+   * @param {string} dir
+   * @returns {void}
+   */
+  function serveStatic(name, dir) {
+    const files = express.static(dir);
+    RED.httpAdmin.use("/fromcubes-react/" + name, permRead, files);
+    RED.httpAdmin.use("/" + ASSET_BASE + name, permRead, files);
+  }
+
   // Since 0.56 monaco-editor has an `exports` map that hides package.json;
   // its CommonJS entry is min/vs/index.js, so the AMD build (loader.js and
   // editor/editor.main.js) sits in the same directory.
-  const monacoVsPath = path.dirname(require.resolve("monaco-editor"));
-  RED.httpAdmin.use(
-    "/fromcubes-react/vs",
-    permRead,
-    express.static(monacoVsPath),
-  );
+  serveStatic("vs", path.dirname(require.resolve("monaco-editor")));
 
   // Editor-side workspace plugin (tree + full-screen Monaco overlay). Served
   // as static files instead of being inlined into portal-react.html so the
   // node's editor template stays readable.
-  RED.httpAdmin.use(
-    "/fromcubes-react/editor",
-    permRead,
-    express.static(path.join(__dirname, "..", "editor")),
-  );
+  serveStatic("editor", path.join(__dirname, "..", "editor"));
 
   // The node icon doubles as the editor's status-bar mark. Serving the icons
   // directory here keeps one copy on disk and spares the client from having to
   // know the package name that Node-RED's own /icons route is keyed by.
-  RED.httpAdmin.use(
-    "/fromcubes-react/icons",
-    permRead,
-    express.static(path.join(__dirname, "..", "icons")),
-  );
+  serveStatic("icons", path.join(__dirname, "..", "icons"));
 
   // Prettier's browser builds, straight from node_modules — same arrangement
   // as Monaco at /fromcubes-react/vs. Nothing is fetched until someone formats.
-  RED.httpAdmin.use(
-    "/fromcubes-react/prettier",
-    permRead,
-    express.static(path.dirname(require.resolve("prettier/package.json"))),
-  );
+  serveStatic("prettier", path.dirname(require.resolve("prettier/package.json")));
 
   const CSS_HASH_RE = /^[a-f0-9]{1,64}$/;
   function findCssByHash(reqHash) {
@@ -193,7 +204,7 @@ function registerProviderRoutes(RED, deps) {
     res.json(providers.describe());
   });
 
-  // Completion list for className="…", from whichever CSS engine is in force.
+  // Completion data for className="…", from whichever CSS engine is in force.
   // `engine` lets the editor tell a stale list from a fresh one.
   RED.httpAdmin.get("/fromcubes-react/css-classes", permRead, async (_req, res) => {
     try {
@@ -204,6 +215,36 @@ function registerProviderRoutes(RED, deps) {
     }
   });
 
+  // What the editor shows for classes it has in hand: a completion's CSS,
+  // a hover, a modifier's swatch, whether a variant exists. `c` carries the
+  // candidates newline-separated — a class never holds whitespace, and one
+  // string sidesteps query-string array parsing.
+  // Canonical spellings (`w-[16px]` → `w-4`) for the diagnostic — apart
+  // from css-describe because an engine may be slow here, and a hover must
+  // not wait for it. Same `c` format.
+  for (const [route, method, what] of [
+    ["css-describe", "describeClasses", "describe"],
+    ["css-canonical", "canonicalClasses", "canonicalise"],
+  ]) {
+    RED.httpAdmin.get("/fromcubes-react/" + route, permRead, async (req, res) => {
+      const c = req.query.c;
+      if (typeof c !== "string") {
+        res.status(400).json({ error: "expected class candidates in c" });
+        return;
+      }
+      try {
+        res.json(await providers[method](c.split("\n")));
+      } catch (e) {
+        if (e instanceof TypeError) {
+          res.status(400).json({ error: e.message });
+          return;
+        }
+        RED.log.error(`[portal-react] ${route}: ${e.message}`);
+        res.status(500).json({ error: `could not ${what} classes` });
+      }
+    });
+  }
+
   RED.httpAdmin.put(
     "/fromcubes-react/providers",
     permWrite,
@@ -235,4 +276,4 @@ function registerProviderRoutes(RED, deps) {
   );
 }
 
-module.exports = { registerAdminApi };
+module.exports = { registerAdminApi, ASSET_BASE };

package/nodes/lib/providers.js

@@ -15,9 +15,19 @@
  *     type: "fromcubes-css",
  *     apiVersion: 1,
  *     generate(source) { return { css } },
- *     editor: { classes() { return ["p-4", …] } },   // optional: completion
+ *     editor: {                                      // optional, all three
+ *       classes() { return ["p-4", …] },             // names only
+ *       completions() { return { classes: [{ name, modifiers, color }], variants } },
+ *       describe(candidates) { return [{ hover, documentation, detail, color, rules } | null, …] },
+ *       canonical(candidates) { return ["w-4" | null, …] },
+ *     },
  *   })
  *
+ * `completions`, `describe` and `canonical` are what Tailwind CSS
+ * IntelliSense works from (modifiers, swatches, variants, CSS previews, colour squares in the
+ * code, conflict and canonical-class diagnostics); an engine with only
+ * `classes` still gets plain completion.
+ *
  * The core builds in only `none` for each kind. Everything that does real
  * work — `headers` (@aaqu/fromcubes-auth-headers) and
  * `tailwind` (@aaqu/fromcubes-tailwind) — is a Node-RED plugin like any third-party one,
@@ -69,6 +79,21 @@ const IDENTITY_TIMEOUT_MS = 5000;
 // every editor that opens a dialog.
 const MAX_EDITOR_CLASSES = 50000;
 const MAX_EDITOR_CLASS_LEN = 200;
+const MAX_EDITOR_MODIFIERS = 1000;
+const MAX_EDITOR_VARIANTS = 1000;
+const MAX_EDITOR_DETAIL_LEN = 2000;
+// One describe request: what a completion's detail pane, a hover or a
+// modifier list needs at once, for candidates that may carry an arbitrary
+// value — `w-[calc(100%-2rem)]` is longer than any listed class.
+const MAX_DESCRIBE = 64;
+const MAX_DESCRIBE_LEN = 1000;
+const MAX_DESCRIBE_TEXT = 100000;
+// Conflict-check entries per class: Tailwind's largest (shadows, with their
+// @property registrations) hold about twenty.
+const MAX_DESCRIBE_RULES = 200;
+// Swatch colours: the forms Monaco draws (hex, rgb()/rgba() with commas)
+// and the two keywords IntelliSense marks as colours without one.
+const EDITOR_COLOR_RE = /^(?:#[0-9a-fA-F]{3,8}|rgba?\([\d\s.,%]{1,60}\)|transparent|currentColor)$/;
 
 const USER_STRING_FIELDS = ["login", "displayName", "email", "role"];
 
@@ -138,6 +163,137 @@ function sanitizeUser(raw) {
   return user;
 }
 
+/**
+ * @param {*} c
+ * @param {number} max
+ * @returns {boolean}  a non-empty string without whitespace, at most `max` long
+ */
+function isToken(c, max) {
+  return typeof c === "string" && c.length > 0 && c.length <= max && !/\s/.test(c);
+}
+
+/**
+ * @param {*} v
+ * @param {number} max
+ * @returns {string|null}
+ */
+function boundedOrNull(v, max) {
+  return typeof v === "string" && v.length <= max ? v : null;
+}
+
+/**
+ * @param {*} c
+ * @returns {string|null}
+ */
+function editorColor(c) {
+  return typeof c === "string" && EDITOR_COLOR_RE.test(c) ? c : null;
+}
+
+/**
+ * Validate a CSS engine's `editor.completions()` (or plain `classes()`)
+ * answer into what the editor is sent. Modifier lists are shared — Tailwind
+ * gives ~15 000 classes the same 21 opacity steps — so each distinct list
+ * travels once and classes point at it by index, as colours do by position.
+ *
+ * @param {*} rawClasses  Array of names, or of `{name, modifiers?, color?}`.
+ * @param {*} [rawVariants]
+ * @returns {{classes: Array<string>, colors: Array<string>, modifiers: Array<Array<string>>, classModifiers: Array<number>, variants: Array<Object>}}
+ */
+function normalizeCompletions(rawClasses, rawVariants) {
+  const classes = [];
+  const colors = [];
+  const modifiers = [];
+  const classModifiers = [];
+  const modifierIndex = new Map();
+  const seen = new Set();
+  for (const entry of Array.isArray(rawClasses) ? rawClasses : []) {
+    if (classes.length >= MAX_EDITOR_CLASSES) break;
+    const isObject = entry !== null && typeof entry === "object";
+    const name = isObject ? entry.name : entry;
+    if (!isToken(name, MAX_EDITOR_CLASS_LEN) || seen.has(name)) continue;
+    seen.add(name);
+    classes.push(name);
+    colors.push((isObject && editorColor(entry.color)) || "");
+    let mods = isObject && Array.isArray(entry.modifiers) ? entry.modifiers : [];
+    mods = mods.length <= MAX_EDITOR_MODIFIERS ? mods.filter((m) => isToken(m, MAX_EDITOR_CLASS_LEN)) : [];
+    if (mods.length === 0) {
+      classModifiers.push(-1);
+      continue;
+    }
+    const key = mods.join("\n");
+    let idx = modifierIndex.get(key);
+    if (idx === undefined) {
+      idx = modifiers.length;
+      modifiers.push(mods);
+      modifierIndex.set(key, idx);
+    }
+    classModifiers.push(idx);
+  }
+
+  const variants = [];
+  for (const v of Array.isArray(rawVariants) ? rawVariants : []) {
+    if (variants.length >= MAX_EDITOR_VARIANTS) break;
+    if (!v || typeof v !== "object" || !isToken(v.name, MAX_EDITOR_CLASS_LEN)) continue;
+    const values = Array.isArray(v.values) && v.values.length <= MAX_EDITOR_MODIFIERS ? v.values : [];
+    const valueDetails = Array.isArray(v.valueDetails) ? v.valueDetails : [];
+    const kept = [];
+    const details = [];
+    values.forEach((value, i) => {
+      if (!isToken(value, MAX_EDITOR_CLASS_LEN)) return;
+      kept.push(value);
+      details.push(boundedOrNull(valueDetails[i], MAX_EDITOR_DETAIL_LEN));
+    });
+    variants.push({
+      name: v.name,
+      values: kept,
+      hasDash: v.hasDash !== false,
+      isArbitrary: v.isArbitrary === true,
+      detail: boundedOrNull(v.detail, MAX_EDITOR_DETAIL_LEN),
+      valueDetails: details,
+      failed: v.failed === true,
+    });
+  }
+
+  return { classes, colors, modifiers, classModifiers, variants };
+}
+
+/**
+ * @param {*} list
+ * @param {number} maxItems
+ * @param {number} maxLen
+ * @returns {Array<string>|null}  the list when it is short strings only
+ */
+function boundedStrings(list, maxItems, maxLen) {
+  if (!Array.isArray(list) || list.length > maxItems) return null;
+  return list.every((v) => typeof v === "string" && v.length <= maxLen) ? list.slice() : null;
+}
+
+/**
+ * Validate one entry of a CSS engine's `editor.describe()` answer. `rules`
+ * (what the CSS-conflict diagnostic compares) is optional for an engine.
+ *
+ * @param {*} d
+ * @returns {{hover: string|null, documentation: string|null, detail: string|null, color: string|null, rules: Array<{properties: Array<string>, context: Array<string>}>}|null}
+ */
+function sanitizeDescription(d) {
+  if (!d || typeof d !== "object") return null;
+  const rules = [];
+  if (Array.isArray(d.rules) && d.rules.length <= MAX_DESCRIBE_RULES) {
+    for (const r of d.rules) {
+      const properties = r && boundedStrings(r.properties, MAX_DESCRIBE_RULES, MAX_EDITOR_CLASS_LEN);
+      const context = r && boundedStrings(r.context, MAX_DESCRIBE_RULES, MAX_EDITOR_DETAIL_LEN);
+      if (properties && context) rules.push({ properties, context });
+    }
+  }
+  return {
+    hover: boundedOrNull(d.hover, MAX_DESCRIBE_TEXT),
+    documentation: boundedOrNull(d.documentation, MAX_DESCRIBE_TEXT),
+    detail: boundedOrNull(d.detail, MAX_DESCRIBE_TEXT),
+    color: editorColor(d.color),
+    rules,
+  };
+}
+
 /**
  * The only providers built into the core: one per kind that does nothing, so
  * "no identity" and "no stylesheet" are always choosable. Their ids are
@@ -182,7 +338,9 @@ function builtinProviders() {
  *   cssEngineId: function(): string,
  *   describe: function(): Object,
  *   select: function(string, string): boolean,
- *   editorClasses: function(): Promise<{engine: string, classes: Array<string>}>,
+ *   editorClasses: function(): Promise<Object>,
+ *   describeClasses: function(Array<string>): Promise<{engine: string, results: Array<Object|null>}>,
+ *   canonicalClasses: function(Array<string>): Promise<{engine: string, results: Array<string|null>}>,
  * }}
  */
 function createProviders(RED, opts = {}) {
@@ -195,8 +353,8 @@ function createProviders(RED, opts = {}) {
   const logged = new Set();
   /** @type {{identity?: string, css?: string}} */
   const chosen = loadChoice();
-  // provider object → its validated class list. Keyed by the object, not the
-  // id, so a plugin reinstalled at runtime (a new definition) is asked again.
+  // provider object → its validated completion data. Keyed by the object, not
+  // the id, so a plugin reinstalled at runtime (a new definition) is asked again.
   const classCache = new WeakMap();
 
   /**
@@ -525,44 +683,126 @@ function createProviders(RED, opts = {}) {
   }
 
   /**
-   * Class names the editor offers inside `className="…"` for the engine in
-   * force. Optional for plugins (`editor.classes()`); an engine without it,
-   * an unusable engine, or one that fails yields an empty list — completion
-   * just stays quiet, nothing else depends on it.
+   * What the editor completes inside `className="…"` for the engine in
+   * force: class names in the engine's order, with per class a swatch
+   * colour (`colors[i]`, "" for none) and modifier list (`modifiers[
+   * classModifiers[i]]`, -1 for none), plus the variants. Taken from the
+   * plugin's `editor.completions()`, or `editor.classes()` for names alone.
+   * Both are optional; an engine without them, an unusable engine, or one
+   * that fails yields an empty list — completion just stays quiet, nothing
+   * else depends on it. `describe` / `canonical` say whether
+   * `describeClasses` / `canonicalClasses` have anything to ask the engine.
    *
-   * @returns {Promise<{engine: string, classes: Array<string>}>}
+   * @returns {Promise<{engine: string, classes: Array<string>, colors: Array<string>, modifiers: Array<Array<string>>, classModifiers: Array<number>, variants: Array<Object>, describe: boolean, canonical: boolean}>}
    */
   async function editorClasses() {
     const engine = cssEngineId();
     const { provider } = lookup(CSS_TYPE, builtins.css, engine);
-    const fn = provider && provider.editor && provider.editor.classes;
-    if (typeof fn !== "function") return { engine, classes: [] };
-    if (classCache.has(provider)) return { engine, classes: classCache.get(provider) };
+    const editor = (provider && provider.editor) || {};
+    const describe = typeof editor.describe === "function";
+    const canonical = typeof editor.canonical === "function";
+    const empty = () => ({ engine, ...normalizeCompletions([]), describe, canonical });
+    const fn = typeof editor.completions === "function" ? "completions" : "classes";
+    if (typeof editor[fn] !== "function") return empty();
+    if (classCache.has(provider)) return { engine, ...classCache.get(provider), describe, canonical };
     let raw;
     try {
-      raw = await fn.call(provider.editor);
+      raw = await editor[fn]();
     } catch (e) {
-      RED.log.warn(`[portal-react] css engine "${engine}" editor.classes() failed: ${e.message}`);
-      return { engine, classes: [] };
+      RED.log.warn(`[portal-react] css engine "${engine}" editor.${fn}() failed: ${e.message}`);
+      return empty();
     }
-    const classes = [];
-    if (Array.isArray(raw)) {
-      const seen = new Set();
-      for (const c of raw) {
-        if (classes.length >= MAX_EDITOR_CLASSES) break;
-        if (typeof c !== "string" || !c || c.length > MAX_EDITOR_CLASS_LEN || /\s/.test(c)) continue;
-        if (seen.has(c)) continue;
-        seen.add(c);
-        classes.push(c);
-      }
-    } else {
-      RED.log.warn(`[portal-react] css engine "${engine}" editor.classes() did not return an array`);
+    const rawClasses = fn === "completions" ? raw && raw.classes : raw;
+    if (!Array.isArray(rawClasses)) {
+      RED.log.warn(`[portal-react] css engine "${engine}" editor.${fn}() did not return ${fn === "completions" ? "a classes array" : "an array"}`);
+    }
+    const data = normalizeCompletions(rawClasses, fn === "completions" && raw ? raw.variants : []);
+    classCache.set(provider, data);
+    return { engine, ...data, describe, canonical };
+  }
+
+  /**
+   * What the editor shows for classes it has in hand — a completion's
+   * detail pane, a hover, a modifier's swatch, a colour square, a
+   * diagnostic — from the engine's `editor.describe()`: per candidate
+   * `{hover, documentation, detail, color, rules}`, or `null`
+   * when the engine generates nothing for it (which is
+   * also how the editor asks whether `group-hover/x` is a variant). Never
+   * rejects for an engine problem: no describe, or a failing one, answers
+   * `null` throughout.
+   *
+   * @param {*} candidates  At most 64 class candidates.
+   * @returns {Promise<{engine: string, results: Array<Object|null>}>}
+   * @throws {TypeError} for a malformed list — a caller's error, not the engine's.
+   */
+  async function describeClasses(candidates) {
+    checkCandidates(candidates);
+    const engine = cssEngineId();
+    const { provider } = lookup(CSS_TYPE, builtins.css, engine);
+    const fn = provider && provider.editor && provider.editor.describe;
+    const nothing = { engine, results: candidates.map(() => null) };
+    if (typeof fn !== "function") return nothing;
+    let raw;
+    try {
+      raw = await fn.call(provider.editor, candidates.slice());
+    } catch (e) {
+      RED.log.warn(`[portal-react] css engine "${engine}" editor.describe() failed: ${e.message}`);
+      return nothing;
+    }
+    if (!Array.isArray(raw)) return nothing;
+    return { engine, results: candidates.map((_, i) => sanitizeDescription(raw[i])) };
+  }
+
+  /**
+   * The canonical spelling the engine suggests per class (`w-[16px]` →
+   * `w-4`), or `null` — for the canonical-class diagnostic only. Kept apart
+   * from `describeClasses` because an engine may take its time here (the
+   * Tailwind add-on asks a worker thread whose first answer waits for an
+   * index) and a hover must never wait for that. Never rejects for an
+   * engine problem.
+   *
+   * @param {*} candidates  At most 64 class candidates.
+   * @returns {Promise<{engine: string, results: Array<string|null>}>}
+   * @throws {TypeError} for a malformed list.
+   */
+  async function canonicalClasses(candidates) {
+    checkCandidates(candidates);
+    const engine = cssEngineId();
+    const { provider } = lookup(CSS_TYPE, builtins.css, engine);
+    const fn = provider && provider.editor && provider.editor.canonical;
+    const nothing = { engine, results: candidates.map(() => null) };
+    if (typeof fn !== "function") return nothing;
+    let raw;
+    try {
+      raw = await fn.call(provider.editor, candidates.slice());
+    } catch (e) {
+      RED.log.warn(`[portal-react] css engine "${engine}" editor.canonical() failed: ${e.message}`);
+      return nothing;
+    }
+    if (!Array.isArray(raw)) return nothing;
+    return {
+      engine,
+      results: candidates.map((c, i) => (isToken(raw[i], MAX_DESCRIBE_LEN) && raw[i] !== c ? raw[i] : null)),
+    };
+  }
+
+  /**
+   * @param {*} candidates
+   * @returns {void}
+   * @throws {TypeError} unless 1–64 class candidates
+   */
+  function checkCandidates(candidates) {
+    if (
+      !Array.isArray(candidates) ||
+      candidates.length === 0 ||
+      candidates.length > MAX_DESCRIBE ||
+      !candidates.every((c) => isToken(c, MAX_DESCRIBE_LEN))
+    ) {
+      throw new TypeError(`expected 1-${MAX_DESCRIBE} class candidates`);
     }
-    classCache.set(provider, classes);
-    return { engine, classes };
   }
 
-  return { resolveUser, generateCss, identityId, cssEngineId, describe, select, editorClasses };
+  return { resolveUser, generateCss, identityId, cssEngineId, describe, select, editorClasses, describeClasses, canonicalClasses };
 }
 
 module.exports = {
@@ -578,4 +818,6 @@ module.exports = {
   MAX_USER_STRING,
   MAX_GROUPS,
   MAX_EDITOR_CLASSES,
+  MAX_DESCRIBE,
+  normalizeCompletions,
 };