@ethlete/cli 3.0.0-next.25 → 3.0.0-next.26

package/src/lib/design/system/complete.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.completenessOf = exports.inventoryIdsOf = exports.seePart = exports.completenessGapLineOf = exports.completenessGapsOf = exports.findingKeyOf = exports.isFindingOf = exports.declaredControlsOf = void 0;
+exports.partsCompletenessOf = exports.completenessOf = exports.inventoryIdsOf = exports.seePart = exports.PLAIN_CONTROL_SELECTOR = exports.SDK_CONTROLS = exports.isMissingStateGap = exports.completenessGapLineOf = exports.completenessGapsOf = exports.findingKeyOf = exports.isFindingOf = exports.smallChangeHintsOf = exports.controlStateGapsOf = exports.isControlPart = exports.isInteractionState = exports.declaredControlsOf = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const browser_1 = require("../browser");
@@ -18,16 +18,18 @@ const serve_1 = require("../serve");
 const shot_1 = require("../shot");
 const thumb_1 = require("../thumb");
 const resolve_product_1 = require("./resolve-product");
+const contact_sheet_1 = require("../contact-sheet");
 const baseline_1 = require("./sketch/baseline");
 const merged_parts_1 = require("./sketch/merged-parts");
 const system_modules_1 = require("./system-modules");
 const exceptions_1 = require("./exceptions");
 const inventory_approval_1 = require("./inventory-approval");
+const option_values_1 = require("./rules/option-values");
 const KINDS = {
     disclosure: { surface: 'body', closed: 'collapsed' },
     button: { adds: ['active'] },
-    select: { surface: 'open', options: true },
-    menu: { surface: 'open', options: true },
+    select: { surface: 'open', options: { interactions: ['hover', 'focus-visible'], selected: true } },
+    menu: { surface: 'open', options: { interactions: ['hover', 'focus-visible', 'active'], selected: false } },
     row: { selects: true, virtualFocus: true },
     field: { noActive: true },
     tooltip: { surface: 'tooltip' },
@@ -88,6 +90,74 @@ const declaredControlsOf = (value) => isRecord(value)
     }))
     : null;
 exports.declaredControlsOf = declaredControlsOf;
+const INTERACTION_WORDS = new Set(['hover', 'hovered', 'focus', 'focused', 'pressed', 'active', 'selected']);
+const NAME_WORDS = new Set([...INTERACTION_WORDS, 'visible', 'within', 'invalid', 'disabled', 'checked', 'open']);
+const wordsOf = (state) => state
+    .replace(/([a-z0-9])([A-Z])/gu, '$1-$2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/u)
+    .filter((word) => word !== '');
+/**
+ * Whether a state name shows an interaction: its last word, split at `-`, `_`, spaces and camelCase, or the whole name
+ * is hover, hovered, focus, focused, pressed, active or selected. `row-hover`, `collapseFocus` and `focus-visible`
+ * are; `active-only` and `inactive` are not.
+ */
+const isInteractionState = (state) => {
+    var _a, _b;
+    const words = wordsOf(state);
+    while (words.length > 1 && ['visible', 'within'].includes((_a = words[words.length - 1]) !== null && _a !== void 0 ? _a : ''))
+        words.pop();
+    return INTERACTION_WORDS.has((_b = words[words.length - 1]) !== null && _b !== void 0 ? _b : '');
+};
+exports.isInteractionState = isInteractionState;
+/** Whether a part may draw interaction states: it is no page, and its `controls` declare a control of a checked kind. */
+const isControlPart = (options) => {
+    var _a;
+    return !options.part.startsWith('pages/') &&
+        Object.values((_a = (0, exports.declaredControlsOf)(options.controls)) !== null && _a !== void 0 ? _a : {}).some((control) => CHECKED_KINDS.includes(control.kind));
+};
+exports.isControlPart = isControlPart;
+/**
+ * One `CONTROL-STATE` gap per element whose interaction states a part draws that is no control part. The element is
+ * the state name without its interaction words (`row-hover` names the row), or `control` when nothing is left.
+ */
+const controlStateGapsOf = (options) => {
+    var _a, _b;
+    const { part, states } = options;
+    if ((0, exports.isControlPart)(options))
+        return [];
+    const elements = new Map();
+    for (const state of states.filter(exports.isInteractionState)) {
+        const element = wordsOf(state)
+            .filter((word) => !NAME_WORDS.has(word))
+            .join('-') || 'control';
+        elements.set(element, [...((_a = elements.get(element)) !== null && _a !== void 0 ? _a : []), state]);
+    }
+    const why = part.startsWith('pages/')
+        ? 'a page is no control part'
+        : `${part} declares no control of a kind ${CHECKED_KINDS.join(', ')}`;
+    const declaresNone = Object.keys((_b = (0, exports.declaredControlsOf)(options.controls)) !== null && _b !== void 0 ? _b : {}).length === 0;
+    const fixOf = (element) => part.startsWith('components/') && declaresNone
+        ? `declare its controls (Q164), or extract the ${element} as its own control part`
+        : `extract the ${element} as its own control part`;
+    return [...elements].map(([element, shown]) => ({
+        code: 'CONTROL-STATE',
+        target: part,
+        detail: `${shown.length === 1 ? 'state' : 'states'} ${statesShownOf(shown)} draw${shown.length === 1 ? 's' : ''} an interaction (hover, focus, pressed, active or selected), which only a control part draws, and ${why} - ${fixOf(element)} and draw ${shown.length === 1 ? 'this state' : 'these states'} there`,
+    }));
+};
+exports.controlStateGapsOf = controlStateGapsOf;
+const SMALL_CHANGE = 0.1;
+/**
+ * One hint per state of an element or component that is no control part whose pixels differ from its first state in
+ * under a tenth of the frame. Pages compose parts, so they get none; interaction states are left to `CONTROL-STATE`.
+ */
+const smallChangeHintsOf = (options) => options.part.startsWith('pages/') || (0, exports.isControlPart)(options)
+    ? []
+    : options.changes
+        .filter(({ state, share }) => share > 0 && share < SMALL_CHANGE && !(0, exports.isInteractionState)(state))
+        .map(({ state, base, share }) => `HINT ${options.part} ${state} - changes ${(share * 100).toFixed(1)} % of the frame against ${base} - extract the changed element as its own part`);
+exports.smallChangeHintsOf = smallChangeHintsOf;
 /** Whether a discovered element is an undeclared or unclassified finding of the part, not owned or declared. */
 const isFindingOf = (declared) => (found) => {
     var _a;
@@ -98,6 +168,7 @@ const isFindingOf = (declared) => (found) => {
 exports.isFindingOf = isFindingOf;
 const findingKeyOf = (found) => `${found.kind} ${found.what} ${found.path}`;
 exports.findingKeyOf = findingKeyOf;
+const NATIVE_CONTROLS = ['button', 'a[href]', 'input:not([type="hidden"])', 'select', 'textarea', 'summary'];
 const discoveryGapsOf = (options) => {
     var _a, _b, _c, _d;
     const { part, declared, frames } = options;
@@ -125,7 +196,9 @@ const discoveryGapsOf = (options) => {
             ? {
                 code: 'CONTROL-UNDECLARED',
                 target: part,
-                detail: `${where} - mark it with data-et-control and declare it in controls`,
+                detail: `${where} - ${NATIVE_CONTROLS.includes(found.what)
+                    ? 'mark it with control(markup, name) from @ethlete/components/design/control and declare the name in controls'
+                    : 'mark it with data-et-control and declare it in controls'}`,
             }
             : {
                 code: 'CONTROL-UNCLASSIFIED',
@@ -134,6 +207,7 @@ const discoveryGapsOf = (options) => {
             };
     });
 };
+const isUndeclaredControlGap = (gap) => gap.code === 'CONTROL-UNDECLARED';
 const statesShownOf = (states) => states.length > 4 ? `${states.slice(0, 3).join(', ')} and ${states.length - 3} more` : states.join(', ');
 const overrideGapsOf = (options) => {
     var _a, _b;
@@ -190,17 +264,26 @@ const ownersOf = (frames) => [
         .flatMap((seen) => { var _a; return ((_a = seen.found) !== null && _a !== void 0 ? _a : []).map((found) => { var _a; return (_a = found.owner) !== null && _a !== void 0 ? _a : null; }); })
         .filter((owner) => owner !== null)),
 ];
-const interactionGapOf = (options) => {
+const undefinedClassesGapOf = (options) => {
     var _a;
+    const { forced, what, interaction } = options;
+    const seen = forced.find((force) => { var _a; return (_a = force.undefinedClasses) === null || _a === void 0 ? void 0 : _a.length; });
+    if (!seen)
+        return null;
+    const classes = (_a = seen.undefinedClasses) !== null && _a !== void 0 ? _a : [];
+    return `state ${seen.state} forces ${interaction} on ${what}, but no stylesheet defines its ${classes.length === 1 ? 'class' : 'classes'} ${classes.join(', ')} - Tailwind generates no utility of that name; use a colour or value the product's theme defines`;
+};
+const interactionGapOf = (options) => {
+    var _a, _b;
     const { frames, id, interaction } = options;
     const forced = frames.flatMap((frame) => frame.controls
         .filter((control) => control.id === id)
         .flatMap((control) => control.forced.filter((force) => force.interaction === interaction))
-        .map((force) => ({ state: frame.state, differs: force.differs })));
+        .map((force) => ({ state: frame.state, differs: force.differs, undefinedClasses: force.undefinedClasses })));
     if (forced.some((force) => force.differs))
         return null;
     if (forced.length > 0)
-        return `state ${(_a = forced[0]) === null || _a === void 0 ? void 0 : _a.state} forces ${interaction} on it, but its box draws no different pixel than at rest - if a descendant draws ${interaction}, mark it with data-et-control-part`;
+        return ((_a = undefinedClassesGapOf({ forced, what: 'it', interaction })) !== null && _a !== void 0 ? _a : `state ${(_b = forced[0]) === null || _b === void 0 ? void 0 : _b.state} forces ${interaction} on it, but its box draws no different pixel than at rest - if a descendant draws ${interaction}, mark it with data-et-control-part`);
     return `no state draws it ${interaction} - draw a state that forces ${interaction} on the data-et-control element, e.g. with forceInteraction - a data-et-control-part in it takes the force too`;
 };
 const keyboardActiveRowGapOf = (options) => {
@@ -237,12 +320,12 @@ const lookGapOf = (options) => {
     return null;
 };
 const forcedGapOf = (options) => {
-    var _a;
+    var _a, _b;
     const { forced, what, interaction } = options;
     if (forced.some((force) => force.differs))
         return null;
     if (forced.length > 0)
-        return `state ${(_a = forced[0]) === null || _a === void 0 ? void 0 : _a.state} forces ${interaction} on ${what}, but its box draws no different pixel than at rest`;
+        return ((_a = undefinedClassesGapOf(options)) !== null && _a !== void 0 ? _a : `state ${(_b = forced[0]) === null || _b === void 0 ? void 0 : _b.state} forces ${interaction} on ${what}, but its box draws no different pixel than at rest`);
     return `no state draws ${what} ${interaction} - force ${interaction} on it, e.g. with forceInteraction`;
 };
 const surfaceGapsOf = (options) => {
@@ -285,19 +368,21 @@ const keyboardActiveGapOf = (options) => {
     return `state ${(_b = compared[0]) === null || _b === void 0 ? void 0 : _b.state} marks an option active by ${KEYBOARD_ACTIVE}, but it looks the same as a plain option - give the active option its own look`;
 };
 const optionGapsOf = (options) => {
-    const { frames, surfaceId } = options;
+    const { frames, surfaceId, interactions } = options;
     const shownIn = (frame) => frame.surfaces.filter((seen) => seen.id === surfaceId && seen.shown).flatMap((seen) => { var _a; return (_a = seen.options) !== null && _a !== void 0 ? _a : []; });
     const what = `an option in ${surfaceId}`;
     const gaps = [];
-    for (const interaction of ['hover', 'focus-visible']) {
+    for (const interaction of interactions) {
         const forced = frames.flatMap((frame) => shownIn(frame).flatMap((option) => option.forced
             .filter((force) => force.interaction === interaction)
-            .map((force) => ({ state: frame.state, differs: force.differs }))));
+            .map((force) => ({ state: frame.state, differs: force.differs, undefinedClasses: force.undefinedClasses }))));
         const gap = forcedGapOf({ forced, what, interaction });
         const missing = gap && interaction === 'focus-visible' ? keyboardActiveGapOf({ frames, shownIn, forcedGap: gap }) : gap;
         if (missing)
             gaps.push([`option-${interaction}`, missing]);
     }
+    if (!options.selected)
+        return gaps;
     const seen = frames
         .filter((frame) => frame.interaction === null)
         .flatMap((frame) => shownIn(frame)
@@ -334,7 +419,7 @@ const requirementGapsOf = (options) => {
         const forced = frames.flatMap((frame) => frame.controls
             .filter((seen) => seen.id === id && seen.selected)
             .flatMap((seen) => seen.forced.filter((force) => force.interaction === 'hover'))
-            .map((force) => ({ state: frame.state, differs: force.differs })));
+            .map((force) => ({ state: frame.state, differs: force.differs, undefinedClasses: force.undefinedClasses })));
         const hovered = forcedGapOf({ forced, what: 'it selected', interaction: 'hover' });
         if (selected)
             gaps.push(['selected', selected]);
@@ -354,7 +439,7 @@ const requirementGapsOf = (options) => {
     if (kind.surface)
         gaps.push(...surfaceGapsOf(Object.assign(Object.assign({}, options), { surface: kind.surface, closed: kind.closed })));
     if (own && kind.options && kind.surface)
-        gaps.push(...optionGapsOf({ frames, surfaceId: `${id}.${kind.surface}` }));
+        gaps.push(...optionGapsOf(Object.assign({ frames, surfaceId: `${id}.${kind.surface}` }, kind.options)));
     return gaps;
 };
 /**
@@ -431,7 +516,7 @@ const completenessGapsOf = (options) => {
     }
     return [
         ...gaps,
-        ...discoveryGapsOf({ part, declared, frames }),
+        ...discoveryGapsOf({ part, declared, frames }).filter((gap) => !isUndeclaredControlGap(gap)),
         ...ownerGapsOf({ part, declared, frames, referenced }),
         ...overrideGapsOf({ part, frames }),
         ...inventoryGapsOf({ part, inventory }),
@@ -446,6 +531,10 @@ const inventoryGapsOf = ({ part, inventory }) => {
 };
 const completenessGapLineOf = (gap) => `${gap.code} ${gap.target} - ${gap.detail}`;
 exports.completenessGapLineOf = completenessGapLineOf;
+const MISSING_STATE_CODES = ['CONTROL-UNDRAWN', 'CONTROL-GRID-MISSING', 'REQUIREMENT-MISSING'];
+/** Whether a gap is a declared control that no state draws, or that lacks a drawn interaction, look or surface. */
+const isMissingStateGap = (gap) => MISSING_STATE_CODES.includes(gap.code);
+exports.isMissingStateGap = isMissingStateGap;
 const NO_MOTION = '*, *::before, *::after { transition: none !important; animation: none !important; }';
 const PAD = 8;
 const COLOUR_PROPERTIES = [
@@ -489,6 +578,28 @@ const coversOf = (property) => {
         return ['all', 'border', 'border-color', property.replace(/-color$/, ''), property];
     return ['all', property];
 };
+const undefinedVariantClasses = (at) => `((at) => {
+  const control = document.querySelector('[data-et-complete="' + at + '"]');
+  const selectors = [];
+  const collect = (rules) => {
+    for (const rule of rules) {
+      if (rule.selectorText) selectors.push(rule.selectorText);
+      if (rule.cssRules) collect(rule.cssRules);
+    }
+  };
+  for (const sheet of document.styleSheets) {
+    try {
+      collect(sheet.cssRules);
+    } catch {}
+  }
+  const tokens = new Set([control, ...control.querySelectorAll('*')].flatMap((element) => [...element.classList]));
+  return [...tokens].filter((token) => token.includes(':') && !selectors.some((selector) => selector.includes('.' + CSS.escape(token))));
+})(${JSON.stringify(at)})`;
+const VARIANT_WORDS = { hover: 'hover', active: 'active', 'focus-visible': 'focus' };
+const isVariantOf = (token, interaction) => token
+    .split(':')
+    .slice(0, -1)
+    .some((variant) => { var _a; return variant.includes((_a = VARIANT_WORDS[interaction]) !== null && _a !== void 0 ? _a : interaction); });
 const stillChangesOf = (rest, forced) => forced.names.flatMap((name, element) => {
     var _a;
     const { properties, durations } = (_a = forced.transitions[element]) !== null && _a !== void 0 ? _a : { properties: [], durations: [] };
@@ -526,7 +637,7 @@ const INTERACTIVE_ROLES = [
     'textbox',
     'treeitem',
 ];
-const SDK_CONTROLS = [
+exports.SDK_CONTROLS = [
     '[et-button]',
     '[et-icon-button]',
     '[et-text-button]',
@@ -566,23 +677,22 @@ const SDK_CONTROLS = [
     'et-time-input',
     'et-toggletip',
 ];
-const LIKELY_CONTROLS = [
-    ...SDK_CONTROLS,
-    'button',
-    'a[href]',
-    'input:not([type="hidden"])',
-    'select',
-    'textarea',
-    'summary',
-    '[tabindex]',
-    ...INTERACTIVE_ROLES.map((role) => `[role="${role}"]`),
-];
+const PLAIN_CONTROLS = [...NATIVE_CONTROLS, '[tabindex]', ...INTERACTIVE_ROLES.map((role) => `[role="${role}"]`)];
+const LIKELY_CONTROLS = [...exports.SDK_CONTROLS, ...PLAIN_CONTROLS];
 const LOOK_PROPERTIES = [...COLOUR_PROPERTIES, 'opacity', 'box-shadow', 'font-weight', 'text-decoration-line'];
 const OPTION_SELECTOR = '[role="option"], [role^="menuitem"], [data-et-option]';
+const COMPOSITE_ROLES = ['grid', 'listbox', 'menu', 'menubar', 'radiogroup', 'tablist', 'tree', 'treegrid'];
+const FOCUS_CONTAINER = COMPOSITE_ROLES.flatMap((role) => [
+    `[role="${role}"][tabindex="-1"]`,
+    `[role="${role}"][aria-activedescendant]`,
+]).join(', ');
+exports.PLAIN_CONTROL_SELECTOR = `:is(${PLAIN_CONTROLS.join(', ')}):not(${FOCUS_CONTAINER})`;
 const discoverControls = `((root) => {
   const LIKELY = ${JSON.stringify(LIKELY_CONTROLS)};
   const likely = LIKELY.join(', ');
-  const sdk = ${JSON.stringify(SDK_CONTROLS.join(', '))};
+  const container = ${JSON.stringify(FOCUS_CONTAINER)};
+  const isLikely = (element) => element.matches(likely) && !element.matches(container);
+  const sdk = ${JSON.stringify(exports.SDK_CONTROLS.join(', '))};
   const rendered = (element) => element.getClientRects().length > 0;
   const HOVER = /(?<!\\\\):hover(?![\\w-])/g;
   const FORCED_HOVER = /:is\\(:hover,\\s*\\[data-et-force~="?hover"?\\]\\)/g;
@@ -640,7 +750,7 @@ const discoverControls = `((root) => {
   const markedOf = (element) => {
     if (element.hasAttribute('data-et-control')) return element.getAttribute('data-et-control');
     for (let at = element.parentElement; at && at !== root; at = at.parentElement) {
-      if (at.matches(likely)) return null;
+      if (isLikely(at)) return null;
       const id = markerOf(at, element);
       if (id !== null) return id;
     }
@@ -649,7 +759,7 @@ const discoverControls = `((root) => {
   const found = [];
   for (const element of root.querySelectorAll('*')) {
     if (!rendered(element)) continue;
-    const what = LIKELY.find((selector) => element.matches(selector));
+    const what = !element.matches(container) && LIKELY.find((selector) => element.matches(selector));
     if (what) {
       const inSdk = element.parentElement.closest(sdk);
       if (inSdk !== null && root.contains(inSdk)) continue;
@@ -659,7 +769,9 @@ const discoverControls = `((root) => {
     const cursor = getComputedStyle(element).cursor;
     const pointer = cursor === 'pointer' && getComputedStyle(element.parentElement).cursor !== 'pointer';
     if (!pointer && !hovered.has(element)) continue;
-    if (element.closest('[data-et-control], ' + likely) !== null) continue;
+    let inControl = false;
+    for (let at = element; at && !inControl; at = at.parentElement) inControl = at.hasAttribute('data-et-control') || isLikely(at);
+    if (inControl) continue;
     const reason = [pointer ? 'cursor: pointer' : '', hovered.has(element) ? ':hover rule' : ''].filter(Boolean).join(' and ');
     found.push({ kind: 'unclassified', what: nameOf(element) + ' with ' + reason, path: pathOf(element), marked: null, within: [], owner: ownerOf(element)?.key ?? null, box: frameBoxOf(element) });
   }
@@ -819,7 +931,7 @@ const seeFrame = (options) => `(() => {
   const isKeyboard = (element) => element.getAttribute('data-active-source') === 'keyboard';
   let next = 0;
   const tagged = (element) => {
-    const at = next++;
+    const at = element.hasAttribute('data-et-complete') ? Number(element.getAttribute('data-et-complete')) : next++;
     element.setAttribute('data-et-complete', String(at));
     const box = element.getBoundingClientRect();
     const x = Math.max(0, box.x + scrollX - ${PAD});
@@ -873,6 +985,7 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
     const context = yield browser.newContext();
     const seen = [];
     const refused = [];
+    const shots = [];
     try {
         const page = yield context.newPage();
         for (const frame of frames) {
@@ -885,6 +998,13 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
                 refused.push(`${frame.state}: ${found.refused}`);
                 continue;
             }
+            if (frame.interaction === null) {
+                const box = frame.clip ? yield page.locator('#root').boundingBox() : null;
+                shots.push({
+                    state: frame.state,
+                    png: yield page.screenshot({ type: 'png', fullPage: true, animations: 'disabled', clip: box !== null && box !== void 0 ? box : undefined }),
+                });
+            }
             const forcedOf = (element) => __awaiter(void 0, void 0, void 0, function* () {
                 const forced = [];
                 for (const interaction of element.forced.filter((name) => FORCEABLE.has(name))) {
@@ -900,11 +1020,12 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
                     const rest = yield shot();
                     const restColours = (yield page.evaluate(colourSnapshot(element.at)));
                     yield page.evaluate(forceOn({ at: element.at, interaction, on: true }));
-                    forced.push({
-                        interaction,
-                        differs: !drawn.equals(rest),
-                        still: stillChangesOf(restColours, drawnColours),
-                    });
+                    const differs = !drawn.equals(rest);
+                    const undefinedClasses = differs
+                        ? []
+                        : (yield page.evaluate(undefinedVariantClasses(element.at))).filter((token) => isVariantOf(token, interaction));
+                    forced.push(Object.assign({ interaction,
+                        differs, still: stillChangesOf(restColours, drawnColours) }, (undefinedClasses.length > 0 ? { undefinedClasses } : {})));
                 }
                 return forced;
             });
@@ -931,7 +1052,20 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
     finally {
         yield context.close();
     }
-    return { seen, refused };
+    const [first, ...others] = shots;
+    const shares = first ? yield (0, contact_sheet_1.changedSharesOf)({ browser, base: first.png, others: others.map(({ png }) => png) }) : [];
+    return {
+        seen,
+        refused,
+        changes: others.map(({ state }, index) => {
+            var _a, _b;
+            return ({
+                state,
+                base: (_a = first === null || first === void 0 ? void 0 : first.state) !== null && _a !== void 0 ? _a : '',
+                share: (_b = shares[index]) !== null && _b !== void 0 ? _b : 0,
+            });
+        }),
+    };
 });
 /**
  * Draws every state of one part of the product, at rest and, unless `restOnly`, in each interaction it declares,
@@ -984,13 +1118,14 @@ const seePart = (options) => __awaiter(void 0, void 0, void 0, function* () {
         .filter((file) => file.endsWith('.css'))
         .sort()
         .map((file) => (0, fs_1.readFileSync)((0, path_1.join)(dir, file), 'utf8'));
-    const { seen, refused } = yield draw((browser) => seeFrames({ browser, base, frames, part: key, ownCss }));
+    const { seen, refused, changes } = yield draw((browser) => seeFrames({ browser, base, frames, part: key, ownCss }));
     const owner = (0, inventory_approval_1.partOwnerOf)({ product, part });
     return {
         definition,
         states,
         seen,
         refused,
+        changes,
         addresses: states.map((state) => ({ state, preset, width })),
         owner,
         hash: (0, baseline_1.partHashOf)({ product: owner, dir }),
@@ -1005,23 +1140,45 @@ exports.inventoryIdsOf = inventoryIdsOf;
 /**
  * Draws every state of one part, at rest and in each interaction it declares, once at its first preset or width,
  * and answers the gaps of its `controls` declaration, or why it could not draw. A part a control names in `part`,
- * and an embedded part whose `data-et-part` root draws a control, is checked the same way, and its gaps fail it.
+ * and an embedded part whose `data-et-part` root draws a control, is checked the same way, and its gaps fail it -
+ * unless it is a part of the product's base, whose gaps stay its own.
  * A page fails until the user approves its control inventory in Studio. An exception the user approved in Studio
  * drops the gap it names until the part changes; a pending one still fails. With `sketch`, every part is drawn as
  * that variant draws it, and a part the variant changes is not merged yet, so it never fails as unreviewed.
+ * A drawn control that no `controls` entry declares is a hint; the sketch check fails on one a sketch adds.
  */
 const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d;
     const { target, config, product, part, sketch = null } = options;
-    const resolveChromium = (_a = options.chromiumOf) !== null && _a !== void 0 ? _a : browser_1.chromiumOf;
     const system = (0, system_modules_1.createSystemModules)({ target, config });
-    const parts = (_c = (_b = (sketch ? system.drawnOf(product.name, sketch) : product)) === null || _b === void 0 ? void 0 : _b.parts) !== null && _c !== void 0 ? _c : [];
+    const parts = (_b = (_a = (sketch ? system.drawnOf(product.name, sketch) : product)) === null || _a === void 0 ? void 0 : _a.parts) !== null && _b !== void 0 ? _b : [];
     if (!parts.some((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === part))
         return {
             problem: sketch
                 ? `variant "${sketch.variant}" of the sketch on ${sketch.target} in product "${product.name}" has no part "${part}"`
                 : `product "${product.name}" has no part "${part}"`,
         };
+    const checked = yield (0, exports.partsCompletenessOf)(Object.assign(Object.assign({}, options), { parts: [part] }));
+    if ('unavailable' in checked)
+        return checked;
+    const gaps = (_c = checked.gaps.get(part)) !== null && _c !== void 0 ? _c : [];
+    if (typeof gaps === 'string')
+        return { problem: gaps };
+    const hints = (_d = checked.hints.get(part)) !== null && _d !== void 0 ? _d : [];
+    return Object.assign(Object.assign({ gaps }, (checked.exceptions.length > 0 ? { exceptions: checked.exceptions } : {})), (hints.length > 0 ? { hints } : {}));
+});
+exports.completenessOf = completenessOf;
+/**
+ * Checks each named part as `completenessOf` does, sharing one server, browser and cache, and answers the gaps of
+ * each part, or why it could not be checked as a string.
+ */
+const partsCompletenessOf = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    const { target, config, product, sketch = null } = options;
+    const resolveChromium = (_a = options.chromiumOf) !== null && _a !== void 0 ? _a : browser_1.chromiumOf;
+    const system = (0, system_modules_1.createSystemModules)({ target, config });
+    const parts = (_c = (_b = (sketch ? system.drawnOf(product.name, sketch) : product)) === null || _b === void 0 ? void 0 : _b.parts) !== null && _c !== void 0 ? _c : [];
+    const optionValuesOf = (0, option_values_1.optionValuesChecker)({ target, config, parts });
     if (!(yield resolveChromium(target)))
         return { unavailable: 'neither the checkout nor this package resolves playwright or playwright-core' };
     const queue = (0, thumb_1.createDrawQueue)({ target, chromiumOf: resolveChromium });
@@ -1031,6 +1188,7 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
         const { port } = (_d = server.httpServer) === null || _d === void 0 ? void 0 : _d.address();
         const checked = new Map();
         const exceptions = [];
+        const hints = new Map();
         const gapsOfPart = (key, chain) => __awaiter(void 0, void 0, void 0, function* () {
             const known = checked.get(key);
             if (known !== undefined && !chain.includes(key))
@@ -1040,7 +1198,7 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
             return gaps;
         });
         const freshGapsOfPart = (key, chain) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             const resolved = parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === key);
             if (!resolved)
                 return `product "${product.name}" has no part "${key}"`;
@@ -1057,17 +1215,29 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
             });
             if (typeof sight === 'string')
                 return [{ code: 'RENDER', target: key, detail: (_a = sight.split('\n')[0]) !== null && _a !== void 0 ? _a : '' }];
-            const { definition, states, seen, refused, owner, hash } = sight;
-            const sketched = ((_b = product.parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === key)) === null || _b === void 0 ? void 0 : _b.file) !== resolved.file;
+            const { definition, states, seen, refused, changes, owner, hash } = sight;
+            const optionProblems = optionValuesOf(resolved, definition !== null && definition !== void 0 ? definition : {});
+            hints.set(key, [
+                ...(0, exports.smallChangeHintsOf)({ part: key, controls: definition === null || definition === void 0 ? void 0 : definition.controls, changes }),
+                ...(0, exports.controlStateGapsOf)({ part: key, controls: definition === null || definition === void 0 ? void 0 : definition.controls, states }).map(exports.completenessGapLineOf),
+                ...discoveryGapsOf({ part: key, declared: (_b = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _b !== void 0 ? _b : {}, frames: seen })
+                    .filter(isUndeclaredControlGap)
+                    .map(exports.completenessGapLineOf),
+                ...optionProblems
+                    .filter((gap) => gap.code === 'OPTION-VALUE-MISSING')
+                    .map((gap) => (0, exports.completenessGapLineOf)(Object.assign(Object.assign({}, gap), { target: key }))),
+            ]);
+            const sketched = ((_c = product.parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === key)) === null || _c === void 0 ? void 0 : _c.file) !== resolved.file;
             const reviewed = sketched || (0, merged_parts_1.readMerged)(owner.dir)[key] === hash;
             const referenced = {};
             const used = [
-                ...Object.values((_c = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _c !== void 0 ? _c : {}).map((control) => control.part),
+                ...Object.values((_d = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _d !== void 0 ? _d : {}).map((control) => control.part),
                 ...ownersOf(seen),
             ];
+            const isKitPart = (other) => { var _a; return resolved.origin !== 'base' && ((_a = parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === other)) === null || _a === void 0 ? void 0 : _a.origin) === 'base'; };
             for (const other of used)
                 if (other !== null && !(other in referenced))
-                    referenced[other] = yield gapsOfPart(other, [...chain, key]);
+                    referenced[other] = isKitPart(other) ? [] : yield gapsOfPart(other, [...chain, key]);
             const excepted = (0, exceptions_1.withExceptions)({
                 part: key,
                 exceptions: (0, exceptions_1.readExceptions)(owner.dir),
@@ -1086,12 +1256,16 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
                 }),
             });
             exceptions.push(...excepted.listed);
-            return [...refused.map((detail) => ({ code: 'RENDER', target: key, detail })), ...excepted.gaps];
+            return [
+                ...refused.map((detail) => ({ code: 'RENDER', target: key, detail })),
+                ...optionProblems.filter((gap) => gap.code !== 'OPTION-VALUE-MISSING').map((gap) => (Object.assign(Object.assign({}, gap), { target: key }))),
+                ...excepted.gaps,
+            ];
         });
-        const gaps = yield gapsOfPart(part, []);
-        if (typeof gaps === 'string')
-            return { problem: gaps };
-        return exceptions.length > 0 ? { gaps, exceptions } : { gaps };
+        const gaps = new Map();
+        for (const part of options.parts)
+            gaps.set(part, yield gapsOfPart(part, []));
+        return { gaps, exceptions, hints };
     }
     catch (error) {
         if (error instanceof thumb_1.ThumbUnavailableError)
@@ -1102,5 +1276,5 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
         yield Promise.all([queue.close(), server.close()]);
     }
 });
-exports.completenessOf = completenessOf;
+exports.partsCompletenessOf = partsCompletenessOf;
 //# sourceMappingURL=complete.js.map