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

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

@@ -9,7 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.completenessOf = exports.completenessGapLineOf = exports.completenessGapsOf = 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");
 const force_interactions_1 = require("../force-interactions");
@@ -17,13 +18,41 @@ 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 CHECKED_KINDS = ['disclosure'];
+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: { 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' },
+};
+const CHECKED_KINDS = Object.keys(KINDS);
 const INPUT_INTERACTIONS = { pointer: ['hover', 'active'], keyboard: ['focus-visible'] };
+const MARKS = {
+    selected: 'aria-selected="true", aria-checked="true", aria-pressed="true" or aria-current',
+    disabled: 'disabled or aria-disabled="true"',
+};
+const CONTROL_MARKS = Object.assign(Object.assign({}, MARKS), { disabled: `${MARKS.disabled} on it or a data-et-control-part in it` });
 const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
-const requiredInteractionsOf = (control) => control.input.flatMap((input) => { var _a; return (_a = INPUT_INTERACTIONS[input]) !== null && _a !== void 0 ? _a : []; });
+const requiredInteractionsOf = (control) => {
+    var _a, _b;
+    return [
+        ...new Set([
+            ...control.input
+                .flatMap((input) => { var _a; return (_a = INPUT_INTERACTIONS[input]) !== null && _a !== void 0 ? _a : []; })
+                .filter((interaction) => { var _a; return !(((_a = KINDS[control.kind]) === null || _a === void 0 ? void 0 : _a.noActive) && interaction === 'active'); }),
+            ...((_b = (_a = KINDS[control.kind]) === null || _a === void 0 ? void 0 : _a.adds) !== null && _b !== void 0 ? _b : []),
+        ]),
+    ];
+};
 const gridGapOf = (options) => {
     const { grid, states, interactions } = options;
     const fix = `draw its states with interactionRows, which gives the grid a column per interaction (${interactions.join(', ')})`;
@@ -55,21 +84,102 @@ const declaredControlsOf = (value) => isRecord(value)
                 surfaces: isRecord(declared['surfaces'])
                     ? Object.fromEntries(Object.entries(declared['surfaces']).filter((entry) => typeof entry[1] === 'string'))
                     : {},
+                disabled: declared['disabled'] === true,
             },
         ];
     }))
     : 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;
+    return ((_a = found.owner) !== null && _a !== void 0 ? _a : null) === null &&
+        !found.within.some((id) => { var _a, _b; return ((_b = (_a = declared[id]) === null || _a === void 0 ? void 0 : _a.part) !== null && _b !== void 0 ? _b : null) !== null; }) &&
+        !(found.kind === 'control' && found.marked !== null);
+};
+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;
-    const ownedByPart = (found) => found.within.some((id) => { var _a, _b; return ((_b = (_a = declared[id]) === null || _a === void 0 ? void 0 : _a.part) !== null && _b !== void 0 ? _b : null) !== null; });
+    const isFinding = (0, exports.isFindingOf)(declared);
     const groups = new Map();
     for (const frame of frames.filter((seen) => seen.interaction === null)) {
         const counts = new Map();
         for (const found of (_a = frame.found) !== null && _a !== void 0 ? _a : []) {
-            if (ownedByPart(found) || (found.kind === 'control' && found.marked !== null))
+            if (!isFinding(found))
                 continue;
-            const key = `${found.kind} ${found.what} ${found.path}`;
+            const key = (0, exports.findingKeyOf)(found);
             const group = (_b = groups.get(key)) !== null && _b !== void 0 ? _b : { found, states: [], count: 0 };
             counts.set(key, ((_c = counts.get(key)) !== null && _c !== void 0 ? _c : 0) + 1);
             if (!group.states.includes(frame.state))
@@ -81,13 +191,14 @@ const discoveryGapsOf = (options) => {
     return [...groups.values()]
         .sort((a, b) => a.found.path.localeCompare(b.found.path) || a.found.what.localeCompare(b.found.what))
         .map(({ found, states, count }) => {
-        const shown = states.length > 4 ? `${states.slice(0, 3).join(', ')} and ${states.length - 3} more` : states.join(', ');
-        const where = `${found.what} at ${found.path} in ${shown}${count > 1 ? ` (${count} of them)` : ''}`;
+        const where = `${found.what} at ${found.path} in ${statesShownOf(states)}${count > 1 ? ` (${count} of them)` : ''}`;
         return found.kind === 'control'
             ? {
                 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',
@@ -96,18 +207,96 @@ const discoveryGapsOf = (options) => {
             };
     });
 };
-const interactionGapOf = (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;
+    const groups = new Map();
+    for (const frame of options.frames.filter((seen) => seen.interaction === null))
+        for (const override of (_a = frame.overrides) !== null && _a !== void 0 ? _a : []) {
+            const key = `${override.owner} ${override.selector} ${override.path}`;
+            const group = (_b = groups.get(key)) !== null && _b !== void 0 ? _b : { override, states: [] };
+            if (!group.states.includes(frame.state))
+                group.states.push(frame.state);
+            groups.set(key, group);
+        }
+    return [...groups.values()]
+        .sort((a, b) => a.override.owner.localeCompare(b.override.owner) || a.override.path.localeCompare(b.override.path))
+        .map(({ override, states }) => ({
+        code: 'CONTROL-OVERRIDDEN',
+        target: options.part,
+        detail: `"${override.selector}" sets ${override.properties.join(', ')} on ${override.path}, drawn by ${override.owner}, in ${statesShownOf(states)} - change ${override.owner} instead, or mark the control with data-et-control and declare it in controls`,
+    }));
+};
+const ownerGapsOf = (options) => {
+    var _a, _b, _c;
+    const { part, declared, frames, referenced } = options;
+    const named = new Set(Object.values(declared).map((control) => control.part));
+    const owned = new Map();
+    for (const frame of frames.filter((seen) => seen.interaction === null))
+        for (const found of (_a = frame.found) !== null && _a !== void 0 ? _a : []) {
+            const owner = (_b = found.owner) !== null && _b !== void 0 ? _b : null;
+            if (owner === null || named.has(owner))
+                continue;
+            owned.set(owner, ((_c = owned.get(owner)) !== null && _c !== void 0 ? _c : new Set()).add(`${found.what} ${found.path}`));
+        }
+    return [...owned.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .flatMap(([owner, controls]) => {
+        const used = referenced[owner];
+        const drawn = `${owner} draws ${controls.size} control(s) here`;
+        if (typeof used === 'string')
+            return [{ code: 'CONTROL-PART-INCOMPLETE', target: part, detail: `${drawn}: ${used}` }];
+        if (!used || used.length === 0)
+            return [];
+        return [
+            {
+                code: 'CONTROL-PART-INCOMPLETE',
+                target: part,
+                detail: `${drawn} and is not design complete: ${used.length} gap(s) - run design complete ${owner}`,
+            },
+        ];
+    });
+};
+const ownersOf = (frames) => [
+    ...new Set(frames
+        .filter((seen) => seen.interaction === null)
+        .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 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`;
-    return `no state draws it ${interaction} - draw a state that forces ${interaction} on the data-et-control element, e.g. with forceInteraction`;
+        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) => {
+    const { instances, forcedGap } = options;
+    const active = instances.filter((seen) => seen.keyboard);
+    const plain = instances.filter((seen) => !seen.keyboard && !seen.selected && !seen.disabled);
+    if (active.length === 0)
+        return `${forcedGap}; no state marks it data-active-source="keyboard" either`;
+    if (plain.length === 0)
+        return `a state marks it data-active-source="keyboard", but no state draws it plain (not selected, active or disabled) to compare it with`;
+    if (active.some((seen) => plain.some((other) => other.look !== seen.look)))
+        return null;
+    return `it looks the same with data-active-source="keyboard" as plain - give the active look its own colours`;
 };
 const stillGapOf = (options) => {
     var _a;
@@ -118,30 +307,139 @@ const stillGapOf = (options) => {
                 return `state ${frame.state} changes ${(_a = force.still) === null || _a === void 0 ? void 0 : _a.join(', ')} in one frame - give them a transition with the product's motion tokens`;
     return null;
 };
-const disclosureGapsOf = (options) => {
-    const { frames, id, control, states } = options;
+const lookGapOf = (options) => {
+    const { seen, flag, what, marks = MARKS } = options;
+    const on = seen.filter((one) => one.flag);
+    const off = seen.filter((one) => !one.flag);
+    if (on.length === 0)
+        return `no state draws ${what} ${flag} - mark it with ${marks[flag]} in a state`;
+    if (off.length === 0)
+        return `every state draws ${what} ${flag} - draw it without ${flag} too, to compare`;
+    if (!on.some((one) => off.some((other) => one.look !== other.look)))
+        return `${what} looks the same ${flag} as without - give the ${flag} look its own colours`;
+    return null;
+};
+const forcedGapOf = (options) => {
+    var _a, _b;
+    const { forced, what, interaction } = options;
+    if (forced.some((force) => force.differs))
+        return null;
+    if (forced.length > 0)
+        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) => {
+    const { frames, id, control, states, surface, closed } = options;
     const rest = frames.filter((frame) => frame.interaction === null);
-    const body = control.surfaces['body'];
-    const bodyId = `${id}.body`;
-    const showsBody = (frame) => frame.surfaces.some((surface) => surface.id === bodyId && surface.shown);
+    const state = control.surfaces[surface];
+    const surfaceId = `${id}.${surface}`;
+    const shows = (frame) => frame.surfaces.some((seen) => seen.id === surfaceId && seen.shown);
     const drawsControl = (frame) => frame.controls.some((seen) => seen.id === id);
     const gaps = [];
-    for (const interaction of control.part === null ? requiredInteractionsOf(control) : []) {
-        const gap = interactionGapOf({ frames, id, interaction });
+    if (closed && !rest.some((frame) => drawsControl(frame) && !shows(frame)))
+        gaps.push([closed, `every state that draws it also shows its ${surface} - draw a state with ${surfaceId} closed`]);
+    if (state === undefined)
+        gaps.push([surface, `declares no surfaces.${surface} - name the state that draws it open`]);
+    else if (!states.includes(state))
+        gaps.push([surface, `surfaces.${surface} names state ${state}, which the part does not declare`]);
+    else if (!rest.some((frame) => frame.state === state && drawsControl(frame) && shows(frame)))
+        gaps.push([
+            surface,
+            `state ${state} draws no visible, non-empty data-et-surface="${surfaceId}" next to data-et-control="${id}"`,
+        ]);
+    return gaps;
+};
+const KEYBOARD_ACTIVE = 'aria-activedescendant or data-active-source="keyboard"';
+const isKeyboardActive = (option) => !!option.named || !!option.keyboard;
+const isPlain = (option) => !option.selected && !isKeyboardActive(option) && option.forced.length === 0;
+const keyboardActiveGapOf = (options) => {
+    var _a, _b;
+    const { frames, shownIn, forcedGap } = options;
+    const active = frames
+        .map((frame) => ({ state: frame.state, options: shownIn(frame) }))
+        .filter((frame) => frame.options.some(isKeyboardActive));
+    const compared = active.filter((frame) => frame.options.some(isPlain));
+    if (active.length === 0)
+        return `${forcedGap}; no option is marked active by ${KEYBOARD_ACTIVE} either`;
+    if (compared.length === 0)
+        return `state ${(_a = active[0]) === null || _a === void 0 ? void 0 : _a.state} marks an option active by ${KEYBOARD_ACTIVE}, but draws no plain option (not selected, active or forced) to compare it with`;
+    if (compared.some((frame) => frame.options.some((option) => isKeyboardActive(option) && frame.options.some((plain) => isPlain(plain) && plain.look !== option.look))))
+        return null;
+    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, 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 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, 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)
+        .filter((option) => option.forced.length === 0 && !isKeyboardActive(option))
+        .map((option) => ({ look: option.look, flag: option.selected })));
+    const selected = lookGapOf({ seen, flag: 'selected', what });
+    if (selected)
+        gaps.push(['option-selected', selected]);
+    return gaps;
+};
+const requirementGapsOf = (options) => {
+    var _a;
+    const { frames, id, control } = options;
+    const kind = (_a = KINDS[control.kind]) !== null && _a !== void 0 ? _a : {};
+    const own = control.part === null;
+    const instances = frames
+        .filter((frame) => frame.interaction === null)
+        .flatMap((frame) => frame.controls.filter((seen) => seen.id === id && seen.forced.length === 0));
+    const gaps = [];
+    for (const interaction of own ? requiredInteractionsOf(control) : []) {
+        const forcedGap = interactionGapOf({ frames, id, interaction });
+        const gap = forcedGap && interaction === 'focus-visible' && kind.virtualFocus
+            ? keyboardActiveRowGapOf({ instances, forcedGap })
+            : forcedGap;
         if (gap)
             gaps.push([interaction, gap]);
     }
-    if (!rest.some((frame) => drawsControl(frame) && !showsBody(frame)))
-        gaps.push(['collapsed', `every state that draws it also shows its body - draw a state with ${bodyId} closed`]);
-    if (body === undefined)
-        gaps.push(['body', 'declares no surfaces.body - name the state that draws it open']);
-    else if (!states.includes(body))
-        gaps.push(['body', `surfaces.body names state ${body}, which the part does not declare`]);
-    else if (!rest.some((frame) => frame.state === body && drawsControl(frame) && showsBody(frame)))
-        gaps.push([
-            'body',
-            `state ${body} draws no visible, non-empty data-et-surface="${bodyId}" next to data-et-control="${id}"`,
-        ]);
+    if (own && kind.selects) {
+        const selected = lookGapOf({
+            seen: instances.map((seen) => { var _a; return ({ look: seen.look, flag: (_a = seen.selected) !== null && _a !== void 0 ? _a : false }); }),
+            flag: 'selected',
+            what: 'it',
+        });
+        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, undefinedClasses: force.undefinedClasses })));
+        const hovered = forcedGapOf({ forced, what: 'it selected', interaction: 'hover' });
+        if (selected)
+            gaps.push(['selected', selected]);
+        if (hovered)
+            gaps.push(['selected-hover', hovered]);
+    }
+    if (own && control.disabled) {
+        const disabled = lookGapOf({
+            seen: instances.map((seen) => { var _a; return ({ look: seen.look, flag: (_a = seen.disabled) !== null && _a !== void 0 ? _a : false }); }),
+            flag: 'disabled',
+            what: 'it',
+            marks: CONTROL_MARKS,
+        });
+        if (disabled)
+            gaps.push(['disabled', disabled]);
+    }
+    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(Object.assign({ frames, surfaceId: `${id}.${kind.surface}` }, kind.options)));
     return gaps;
 };
 /**
@@ -150,8 +448,8 @@ const disclosureGapsOf = (options) => {
  */
 const completenessGapsOf = (options) => {
     var _a;
-    const { part, states, frames, reviewed, grid, referenced = {} } = options;
-    const declared = (_a = declaredControlsOf(options.controls)) !== null && _a !== void 0 ? _a : {};
+    const { part, states, frames, reviewed, grid, referenced = {}, inventory } = options;
+    const declared = (_a = (0, exports.declaredControlsOf)(options.controls)) !== null && _a !== void 0 ? _a : {};
     const gaps = [];
     if (!reviewed)
         gaps.push({
@@ -208,7 +506,7 @@ const completenessGapsOf = (options) => {
             gaps.push({ code: 'CONTROL-UNDRAWN', target: `${part}.${id}`, detail: `no state draws data-et-control="${id}"` });
             continue;
         }
-        for (const [requirement, detail] of disclosureGapsOf({ frames, id, control, states }))
+        for (const [requirement, detail] of requirementGapsOf({ frames, id, control, states }))
             gaps.push({ code: 'REQUIREMENT-MISSING', target: `${part}.${id}.${requirement}`, detail });
         for (const interaction of interactions) {
             const gap = stillGapOf({ frames, id, interaction });
@@ -216,11 +514,27 @@ const completenessGapsOf = (options) => {
                 gaps.push({ code: 'CONTROL-TRANSITION-MISSING', target: `${part}.${id}.${interaction}`, detail: gap });
         }
     }
-    return [...gaps, ...discoveryGapsOf({ part, declared, frames })];
+    return [
+        ...gaps,
+        ...discoveryGapsOf({ part, declared, frames }).filter((gap) => !isUndeclaredControlGap(gap)),
+        ...ownerGapsOf({ part, declared, frames, referenced }),
+        ...overrideGapsOf({ part, frames }),
+        ...inventoryGapsOf({ part, inventory }),
+    ];
 };
 exports.completenessGapsOf = completenessGapsOf;
+const inventoryGapsOf = ({ part, inventory }) => {
+    const reason = inventory ? (0, inventory_approval_1.inventoryReasonOf)(inventory) : null;
+    return reason === null
+        ? []
+        : [{ code: 'INVENTORY-UNAPPROVED', target: part, detail: `${reason} - check and approve it in Studio` }];
+};
 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 = [
@@ -264,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: [] };
@@ -301,7 +637,7 @@ const INTERACTIVE_ROLES = [
     'textbox',
     'treeitem',
 ];
-const SDK_CONTROLS = [
+exports.SDK_CONTROLS = [
     '[et-button]',
     '[et-icon-button]',
     '[et-text-button]',
@@ -341,48 +677,23 @@ 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 nameOf = (element) => {
-    const cls = [...element.classList].find((name) => /^[a-z][\\w-]*$/i.test(name));
-    return element.tagName.toLowerCase() + (cls ? '.' + cls : '');
-  };
-  const pathOf = (element) => {
-    const names = [];
-    for (let at = element; at && at !== root; at = at.parentElement) names.unshift(nameOf(at));
-    return (names.length > 4 ? '... > ' : '') + names.slice(-4).join(' > ');
-  };
-  const splitTop = (selector) => {
-    const parts = [];
-    let depth = 0;
-    let from = 0;
-    for (let at = 0; at < selector.length; at++) {
-      const char = selector[at];
-      if (char === '\\\\') at++;
-      else if (char === '(' || char === '[') depth++;
-      else if (char === ')' || char === ']') depth--;
-      else if (char === ',' && depth === 0) {
-        parts.push(selector.slice(from, at).trim());
-        from = at + 1;
-      }
-    }
-    parts.push(selector.slice(from).trim());
-    return parts.filter(Boolean);
-  };
   const HOVER = /(?<!\\\\):hover(?![\\w-])/g;
   const FORCED_HOVER = /:is\\(:hover,\\s*\\[data-et-force~="?hover"?\\]\\)/g;
   const hoveredOf = (written) => {
@@ -408,7 +719,7 @@ const discoverControls = `((root) => {
     for (const rule of rules) {
       if (rule instanceof CSSStyleRule) {
         const own = splitTop(rule.selectorText).map((selector) =>
-          parent === null ? selector : selector.includes('&') ? selector.replaceAll('&', ':is(' + parent + ')') : ':is(' + parent + ') ' + selector,
+          nested(selector, parent),
         );
         for (const selector of own) {
           const target = hoveredOf(selector);
@@ -426,43 +737,166 @@ const discoverControls = `((root) => {
       walk(sheet.cssRules, null);
     } catch {}
   }
+  const markerOf = (at, element) =>
+    at.getAttribute('data-et-control') ?? (element.matches(${JSON.stringify(OPTION_SELECTOR)}) ? at.getAttribute('data-et-surface')?.split('.')[0] : null) ?? null;
   const withinOf = (element) => {
     const ids = [];
-    for (let at = element; at && at !== root; at = at.parentElement)
-      if (at.hasAttribute('data-et-control')) ids.push(at.getAttribute('data-et-control'));
+    for (let at = element; at && at !== root; at = at.parentElement) {
+      const id = markerOf(at, element);
+      if (id !== null) ids.push(id);
+    }
     return ids;
   };
   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 (at.hasAttribute('data-et-control')) return at.getAttribute('data-et-control');
+      if (isLikely(at)) return null;
+      const id = markerOf(at, element);
+      if (id !== null) return id;
     }
     return null;
   };
   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;
-      found.push({ kind: 'control', what: what.startsWith('[') ? element.tagName.toLowerCase() + what : what, path: pathOf(element), marked: markedOf(element), within: withinOf(element) });
+      found.push({ kind: 'control', what: what.startsWith('[') ? element.tagName.toLowerCase() + what : what, path: pathOf(element), marked: markedOf(element), within: withinOf(element), owner: ownerOf(element)?.key ?? null, box: frameBoxOf(element) });
       continue;
     }
     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: [] });
+    found.push({ kind: 'unclassified', what: nameOf(element) + ' with ' + reason, path: pathOf(element), marked: null, within: [], owner: ownerOf(element)?.key ?? null, box: frameBoxOf(element) });
   }
   return found;
 })`;
-const seeFrame = (discover) => `(() => {
+const ROOT_LAYOUT = [
+    '^margin',
+    '^inset',
+    '^(top|right|bottom|left)$',
+    '^(min-|max-)?(width|height|inline-size|block-size)$',
+    '^position$',
+    '^z-index$',
+    '^flex(-grow|-shrink|-basis)?$',
+    '^grid-(area|row|column)',
+    '^(align|justify|place)-self$',
+    '^order$',
+    '^(transform|translate|rotate|scale)$',
+];
+const findOverrides = `((ownCss) => {
+  const LAYOUT = new RegExp(${JSON.stringify(ROOT_LAYOUT.join('|'))});
+  const USER_ACTION = /(?<!\\\\):(hover|focus-visible|focus-within|focus|active)(?![\\w-])/g;
+  const PSEUDO_ELEMENT = /::?(before|after|marker|placeholder|selection|backdrop|file-selector-button|first-line|first-letter)(?![\\w-])/g;
+  const declaredByHost = (element) => {
+    for (let at = element; at && at !== root.parentElement; at = at.parentElement)
+      if (at.hasAttribute('data-et-control') && ownerOf(at) === null) return true;
+    return false;
+  };
+  const overrides = [];
+  const seen = new Set();
+  const check = (selector, style) => {
+    const properties = [...new Set(style.cssText.split(';').map((declaration) => declaration.split(':')[0].trim()).filter(Boolean))];
+    if (properties.length === 0) return;
+    let matched = [];
+    try {
+      matched = [...root.querySelectorAll(selector.replace(PSEUDO_ELEMENT, '').replace(USER_ACTION, ':where(*)'))];
+    } catch {
+      return;
+    }
+    for (const element of matched) {
+      const owner = ownerOf(element);
+      if (owner === null || declaredByHost(element)) continue;
+      const look = owner.at === element ? properties.filter((property) => !LAYOUT.test(property)) : properties;
+      const key = selector + ' ' + pathOf(element);
+      if (look.length === 0 || seen.has(key)) continue;
+      seen.add(key);
+      overrides.push({ owner: owner.key, selector, path: pathOf(element), properties: look });
+    }
+  };
+  const walk = (rules, parent) => {
+    for (const rule of rules) {
+      if (rule instanceof CSSStyleRule) {
+        const own = splitTop(rule.selectorText).map((selector) => nested(selector, parent));
+        for (const selector of own) check(selector, rule.style);
+        if (rule.cssRules && rule.cssRules.length > 0) walk(rule.cssRules, own.join(', '));
+      } else if (parent !== null && rule.constructor.name === 'CSSNestedDeclarations') check(parent, rule.style);
+      else if (rule.cssRules) walk(rule.cssRules, parent);
+    }
+  };
+  for (const text of ownCss) {
+    const sheet = new CSSStyleSheet();
+    try {
+      sheet.replaceSync(text);
+    } catch {
+      continue;
+    }
+    walk(sheet.cssRules, null);
+  }
+  return overrides;
+})`;
+/** A control root and every `data-et-control-part` whose nearest `data-et-control` is that root, in the page. */
+const controlPartsOf = `((control) => [
+  control,
+  ...[...control.querySelectorAll('[data-et-control-part]')].filter((part) => part.parentElement.closest('[data-et-control]') === control),
+])`;
+const seeFrame = (options) => `(() => {
   const root = document.getElementById('root');
   const refused = root.innerText.trim();
   if (refused.startsWith('design-explore:')) return { refused: refused.split('\\n')[0] };
+  const ORIGIN = ${options.clip} ? root.getBoundingClientRect() : { left: -scrollX, top: -scrollY };
+  const frameBoxOf = (element) => {
+    const box = element.getBoundingClientRect();
+    return box.width > 0 && box.height > 0
+      ? { x: Math.round(box.left - ORIGIN.left), y: Math.round(box.top - ORIGIN.top), width: Math.round(box.width), height: Math.round(box.height) }
+      : null;
+  };
+  const OWN = ${JSON.stringify(options.part)};
+  const tokensOf = (element, name) => (element.getAttribute(name) ?? '').split(' ').filter(Boolean);
+  const ownerOf = (element) => {
+    const slotted = tokensOf(element, 'data-et-slot');
+    for (let at = element; at; at = at.parentElement)
+      for (const key of tokensOf(at, 'data-et-part')) {
+        const index = slotted.indexOf(key);
+        if (index >= 0) slotted.splice(index, 1);
+        else return key === OWN ? null : { key, at };
+      }
+    return null;
+  };
+  const nameOf = (element) => {
+    const cls = [...element.classList].find((name) => /^[a-z][\\w-]*$/i.test(name));
+    return element.tagName.toLowerCase() + (cls ? '.' + cls : '');
+  };
+  const pathOf = (element) => {
+    const names = [];
+    for (let at = element; at && at !== root; at = at.parentElement) names.unshift(nameOf(at));
+    return (names.length > 4 ? '... > ' : '') + names.slice(-4).join(' > ');
+  };
+  const splitTop = (selector) => {
+    const parts = [];
+    let depth = 0;
+    let from = 0;
+    for (let at = 0; at < selector.length; at++) {
+      const char = selector[at];
+      if (char === '\\\\') at++;
+      else if (char === '(' || char === '[') depth++;
+      else if (char === ')' || char === ']') depth--;
+      else if (char === ',' && depth === 0) {
+        parts.push(selector.slice(from, at).trim());
+        from = at + 1;
+      }
+    }
+    parts.push(selector.slice(from).trim());
+    return parts.filter(Boolean);
+  };
+  const nested = (selector, parent) =>
+    parent === null ? selector : selector.includes('&') ? selector.replaceAll('&', ':is(' + parent + ')') : ':is(' + parent + ') ' + selector;
   const shown = (element) => {
     const box = element.getBoundingClientRect();
     let { left, top, right, bottom } = box;
@@ -479,38 +913,79 @@ const seeFrame = (discover) => `(() => {
     }
     return element.innerText.trim() !== '' || !!element.querySelector('img, svg, canvas, video, iframe, input, select, textarea');
   };
-  const controls = [...root.querySelectorAll('[data-et-control]')].map((element, at) => {
+  const LOOK = ${JSON.stringify(LOOK_PROPERTIES)};
+  const lookOf = (element) => {
+    const own = LOOK.map((name) => getComputedStyle(element).getPropertyValue(name));
+    const inside = [...element.querySelectorAll('*')].map((child) => {
+      const style = getComputedStyle(child);
+      return LOOK.map((name) => style.getPropertyValue(name)).join(' ');
+    });
+    return JSON.stringify([own, [...new Set(inside)].sort()]);
+  };
+  const named = new Set([...root.querySelectorAll('[aria-activedescendant]')].filter((element) => ownerOf(element) === null).map((element) => element.getAttribute('aria-activedescendant')));
+  const isSelected = (element) =>
+    ['aria-selected', 'aria-checked', 'aria-pressed'].some((name) => element.getAttribute(name) === 'true') ||
+    (element.hasAttribute('aria-current') && element.getAttribute('aria-current') !== 'false');
+  const isDisabled = (element) =>
+    element.matches(':disabled') || element.getAttribute('aria-disabled') === 'true' || tokensOf(element, 'data-et-force').includes('disabled');
+  const isKeyboard = (element) => element.getAttribute('data-active-source') === 'keyboard';
+  let next = 0;
+  const tagged = (element) => {
+    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});
     const y = Math.max(0, box.y + scrollY - ${PAD});
     return {
-      id: element.getAttribute('data-et-control'),
       at,
-      forced: (element.getAttribute('data-et-force') ?? '').split(' ').filter(Boolean),
+      forced: tokensOf(element, 'data-et-force'),
       box: box.width > 0 && box.height > 0 ? { x, y, width: box.width + ${PAD * 2}, height: box.height + ${PAD * 2} } : null,
+      selected: isSelected(element),
+      look: lookOf(element),
+    };
+  };
+  const controls = [...root.querySelectorAll('[data-et-control]')].filter((element) => ownerOf(element) === null).map((element) => {
+    const parts = ${controlPartsOf}(element);
+    const forced = new Set(parts.flatMap((part) => tokensOf(part, 'data-et-force')));
+    for (const part of parts) if (forced.size > 0) part.setAttribute('data-et-force', [...forced].join(' '));
+    return {
+      id: element.getAttribute('data-et-control'),
+      disabled: parts.some(isDisabled),
+      keyboard: parts.some(isKeyboard),
+      frameBox: frameBoxOf(element),
+      ...tagged(element),
     };
   });
-  const surfaces = [...root.querySelectorAll('[data-et-surface]')].map((element) => ({
+  const surfaces = [...root.querySelectorAll('[data-et-surface]')].filter((element) => ownerOf(element) === null).map((element) => ({
     id: element.getAttribute('data-et-surface'),
     shown: shown(element),
+    options: [...element.querySelectorAll(${JSON.stringify(OPTION_SELECTOR)})].filter((option) => ownerOf(option) === null && shown(option)).map((option) => ({ ...tagged(option), named: option.id !== '' && named.has(option.id), keyboard: isKeyboard(option) })),
   }));
-  return { controls, surfaces, found: ${discover} ? ${discoverControls}(root) : [] };
+  const discover = ${options.discover};
+  return {
+    controls,
+    surfaces,
+    found: discover ? ${discoverControls}(root) : [],
+    overrides: discover ? ${findOverrides}(${JSON.stringify(options.ownCss)}) : [],
+  };
 })()`;
 const forceOn = ({ at, interaction, on, }) => `((at, interaction, on) => {
-  const element = document.querySelector('[data-et-complete="' + at + '"]');
-  const tokens = new Set((element.getAttribute('data-et-force') ?? '').split(' ').filter(Boolean));
-  if (on) tokens.add(interaction);
-  else tokens.delete(interaction);
-  if (tokens.size > 0) element.setAttribute('data-et-force', [...tokens].join(' '));
-  else element.removeAttribute('data-et-force');
+  const found = document.querySelector('[data-et-complete="' + at + '"]');
+  for (const element of found.hasAttribute('data-et-control') ? ${controlPartsOf}(found) : [found]) {
+    const tokens = new Set((element.getAttribute('data-et-force') ?? '').split(' ').filter(Boolean));
+    if (on) tokens.add(interaction);
+    else tokens.delete(interaction);
+    if (tokens.size > 0) element.setAttribute('data-et-force', [...tokens].join(' '));
+    else element.removeAttribute('data-et-force');
+  }
 })(${JSON.stringify(at)}, ${JSON.stringify(interaction)}, ${JSON.stringify(on)})`;
 const FORCEABLE = new Set(['hover', 'focus-visible', 'active']);
 const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
-    const { browser, base, frames } = options;
+    const { browser, base, frames, part, ownCss } = options;
     const context = yield browser.newContext();
     const seen = [];
     const refused = [];
+    const shots = [];
     try {
         const page = yield context.newPage();
         for (const frame of frames) {
@@ -518,117 +993,256 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
             yield (0, thumb_1.openFrame)(page, `${base}/frame.html?${frame.search}`);
             yield page.addStyleTag({ content: NO_MOTION });
             yield page.evaluate(thumb_1.settled);
-            const found = (yield page.evaluate(seeFrame(frame.interaction === null)));
+            const found = (yield page.evaluate(seeFrame({ discover: frame.interaction === null, part, ownCss, clip: frame.clip })));
             if ('refused' in found) {
                 refused.push(`${frame.state}: ${found.refused}`);
                 continue;
             }
-            const controls = [];
-            for (const control of found.controls) {
+            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 control.forced.filter((name) => FORCEABLE.has(name))) {
-                    if (!control.box) {
+                for (const interaction of element.forced.filter((name) => FORCEABLE.has(name))) {
+                    if (!element.box) {
                         forced.push({ interaction, differs: false });
                         continue;
                     }
-                    const shot = () => { var _a; return page.screenshot({ type: 'png', fullPage: true, clip: (_a = control.box) !== null && _a !== void 0 ? _a : undefined, animations: 'disabled' }); };
+                    const shot = () => { var _a; return page.screenshot({ type: 'png', fullPage: true, clip: (_a = element.box) !== null && _a !== void 0 ? _a : undefined, animations: 'disabled' }); };
                     const drawn = yield shot();
-                    const drawnColours = (yield page.evaluate(colourSnapshot(control.at)));
-                    yield page.evaluate(forceOn({ at: control.at, interaction, on: false }));
+                    const drawnColours = (yield page.evaluate(colourSnapshot(element.at)));
+                    yield page.evaluate(forceOn({ at: element.at, interaction, on: false }));
                     yield page.evaluate(thumb_1.settled);
                     const rest = yield shot();
-                    const restColours = (yield page.evaluate(colourSnapshot(control.at)));
-                    yield page.evaluate(forceOn({ at: control.at, interaction, on: true }));
-                    forced.push({
-                        interaction,
-                        differs: !drawn.equals(rest),
-                        still: stillChangesOf(restColours, drawnColours),
-                    });
+                    const restColours = (yield page.evaluate(colourSnapshot(element.at)));
+                    yield page.evaluate(forceOn({ at: element.at, interaction, on: true }));
+                    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 } : {})));
                 }
-                controls.push({ id: control.id, forced });
+                return forced;
+            });
+            const controls = [];
+            const surfaces = [];
+            for (const control of found.controls)
+                controls.push(Object.assign(Object.assign({ id: control.id, forced: yield forcedOf(control), selected: control.selected, disabled: control.disabled, look: control.look }, (control.keyboard ? { keyboard: true } : {})), { box: control.frameBox }));
+            for (const surface of found.surfaces) {
+                const options = [];
+                for (const option of surface.options)
+                    options.push(Object.assign(Object.assign({ selected: option.selected, look: option.look, forced: yield forcedOf(option) }, (option.named ? { named: true } : {})), (option.keyboard ? { keyboard: true } : {})));
+                surfaces.push({ id: surface.id, shown: surface.shown, options });
             }
             seen.push({
                 state: frame.state,
                 interaction: frame.interaction,
                 controls,
-                surfaces: found.surfaces,
+                surfaces,
                 found: found.found,
+                overrides: found.overrides,
             });
         }
     }
     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,
+ * once at its first preset or width, and answers what each frame showed, or why its module did not load as a string.
+ */
+const seePart = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d, _e;
+    const { product, part, system, base, load, draw, restOnly = false, sketch = null } = options;
+    const key = (0, resolve_product_1.partKeyOf)(part);
+    const loaded = yield load((0, system_modules_1.productModuleIdOf)({ file: part.file, product: product.name, sketch }))
+        .then((module) => ({ module: module }))
+        .catch((error) => ({ error: error instanceof Error ? error.message : String(error) }));
+    if ('error' in loaded)
+        return loaded.error;
+    const definition = loaded.module.default;
+    const states = isRecord(definition === null || definition === void 0 ? void 0 : definition.states) ? Object.keys(definition.states) : [];
+    const interactions = Array.isArray(definition === null || definition === void 0 ? void 0 : definition.interactions)
+        ? definition.interactions.filter((name) => force_interactions_1.INTERACTIONS.some((known) => known === name))
+        : [];
+    const widths = Array.isArray(definition === null || definition === void 0 ? void 0 : definition.widths)
+        ? definition.widths.filter((width) => typeof width === 'number')
+        : [];
+    const presets = Object.keys((_b = (_a = system.drawnOf(product.name, null)) === null || _a === void 0 ? void 0 : _a.presets) !== null && _b !== void 0 ? _b : {});
+    const preset = part.layer === 'pages' ? ((_c = presets[0]) !== null && _c !== void 0 ? _c : null) : null;
+    const width = preset === null ? ((_d = widths[0]) !== null && _d !== void 0 ? _d : null) : null;
+    const frames = [];
+    for (const state of states)
+        for (const interaction of [null, ...(restOnly ? [] : interactions)]) {
+            const frame = (0, shot_1.partFrameOf)({
+                system,
+                product: product.name,
+                part: key,
+                state,
+                preset,
+                width,
+                sketch,
+                interaction,
+            });
+            if (!(frame instanceof Error))
+                frames.push({
+                    state,
+                    interaction,
+                    search: frame.search.toString(),
+                    size: (_e = frame.size) !== null && _e !== void 0 ? _e : null,
+                    clip: preset === null,
+                });
+        }
+    const dir = (0, path_1.dirname)(part.file);
+    const ownCss = (0, fs_1.readdirSync)(dir)
+        .filter((file) => file.endsWith('.css'))
+        .sort()
+        .map((file) => (0, fs_1.readFileSync)((0, path_1.join)(dir, file), 'utf8'));
+    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 }),
+    };
 });
+exports.seePart = seePart;
+/** The control ids a page draws at rest, the set its inventory approval holds. */
+const inventoryIdsOf = (frames) => [
+    ...new Set(frames.filter((frame) => frame.interaction === null).flatMap((frame) => frame.controls.map(({ id }) => id))),
+].sort();
+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`
- * is checked the same way, and its gaps fail the control.
+ * 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 -
+ * 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 } = options;
+    const { target, config, product, part, sketch = null } = options;
+    const system = (0, system_modules_1.createSystemModules)({ target, config });
+    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;
-    if (!product.parts.some((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === part))
-        return { problem: `product "${product.name}" has no part "${part}"` };
+    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 });
     const server = yield (0, serve_1.createDesignServer)({ target, config, listen: true, port: 0 });
     try {
         yield server.listen();
-        const { port } = (_b = server.httpServer) === null || _b === void 0 ? void 0 : _b.address();
-        const system = (0, system_modules_1.createSystemModules)({ target, config });
-        const presets = Object.keys((_d = (_c = system.drawnOf(product.name, null)) === null || _c === void 0 ? void 0 : _c.presets) !== null && _d !== void 0 ? _d : {});
+        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* () {
-            var _a, _b, _c, _d, _e;
-            const resolved = product.parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === key);
+            const known = checked.get(key);
+            if (known !== undefined && !chain.includes(key))
+                return known;
+            const gaps = yield freshGapsOfPart(key, chain);
+            checked.set(key, gaps);
+            return gaps;
+        });
+        const freshGapsOfPart = (key, chain) => __awaiter(void 0, void 0, void 0, function* () {
+            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}"`;
             if (chain.includes(key))
                 return `its controls name each other in a cycle: ${[...chain, key].join(' > ')}`;
-            const loaded = yield server
-                .ssrLoadModule((0, system_modules_1.productModuleIdOf)({ file: resolved.file, product: product.name, sketch: null }))
-                .then((module) => ({ module: module }))
-                .catch((error) => ({ error: error instanceof Error ? error.message : String(error) }));
-            if ('error' in loaded)
-                return [{ code: 'RENDER', target: key, detail: (_a = loaded.error.split('\n')[0]) !== null && _a !== void 0 ? _a : '' }];
-            const definition = loaded.module.default;
-            const states = isRecord(definition === null || definition === void 0 ? void 0 : definition.states) ? Object.keys(definition.states) : [];
-            const interactions = Array.isArray(definition === null || definition === void 0 ? void 0 : definition.interactions)
-                ? definition.interactions.filter((name) => force_interactions_1.INTERACTIONS.some((known) => known === name))
-                : [];
-            const widths = Array.isArray(definition === null || definition === void 0 ? void 0 : definition.widths)
-                ? definition.widths.filter((width) => typeof width === 'number')
-                : [];
-            const preset = resolved.layer === 'pages' ? ((_b = presets[0]) !== null && _b !== void 0 ? _b : null) : null;
-            const width = preset === null ? ((_c = widths[0]) !== null && _c !== void 0 ? _c : null) : null;
-            const frames = [];
-            for (const state of states)
-                for (const interaction of [null, ...interactions]) {
-                    const frame = (0, shot_1.partFrameOf)({
-                        system,
-                        product: product.name,
-                        part: key,
-                        state,
-                        preset,
-                        width,
-                        sketch: null,
-                        interaction,
-                    });
-                    if (!(frame instanceof Error))
-                        frames.push({ state, interaction, search: frame.search.toString(), size: (_d = frame.size) !== null && _d !== void 0 ? _d : null });
-                }
-            const { seen, refused } = yield queue.run((browser) => seeFrames({ browser, base: `http://localhost:${port}`, frames }));
-            const reviewed = (0, merged_parts_1.readMerged)(product.dir)[key] === (0, baseline_1.partHashOf)({ product, dir: (0, path_1.dirname)(resolved.file) });
+            const sight = yield (0, exports.seePart)({
+                product,
+                part: resolved,
+                system,
+                base: `http://localhost:${port}`,
+                load: (id) => server.ssrLoadModule(id),
+                draw: (job) => queue.run(job),
+                sketch,
+            });
+            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, 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 = {};
-            for (const control of Object.values((_e = declaredControlsOf(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _e !== void 0 ? _e : {}))
-                if (control.part !== null && !(control.part in referenced))
-                    referenced[control.part] = yield gapsOfPart(control.part, [...chain, key]);
-            return [
-                ...refused.map((detail) => ({ code: 'RENDER', target: key, detail })),
-                ...(0, exports.completenessGapsOf)({
+            const used = [
+                ...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] = isKitPart(other) ? [] : yield gapsOfPart(other, [...chain, key]);
+            const excepted = (0, exceptions_1.withExceptions)({
+                part: key,
+                exceptions: (0, exceptions_1.readExceptions)(owner.dir),
+                hash,
+                gaps: (0, exports.completenessGapsOf)({
                     part: key,
                     controls: definition === null || definition === void 0 ? void 0 : definition.controls,
                     states,
@@ -636,11 +1250,22 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
                     reviewed,
                     grid: definition === null || definition === void 0 ? void 0 : definition.grid,
                     referenced,
+                    inventory: resolved.layer === 'pages'
+                        ? (0, inventory_approval_1.inventoryStateOf)({ approval: (0, inventory_approval_1.readInventory)(owner.dir)[key], ids: (0, exports.inventoryIdsOf)(seen), hash })
+                        : undefined,
                 }),
+            });
+            exceptions.push(...excepted.listed);
+            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, []);
-        return typeof gaps === 'string' ? { problem: gaps } : { 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)
@@ -651,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